Utils

class drama.utils.json_decoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

Used for decoding JSONs and ensuring the variables are initialised correctly

decode(s, **kwargs)

Return the Python representation of s (a str instance containing a JSON document).

class drama.utils.InputXml(default_xml, user_choice)

Class to define the new xml default input for the project.

Parameters:

• default_xml (dict) –

  Specifications regarding the variables location into the xml file and the functions which should be used to format them into strings. This input is specified as follows:

  }
      'input file 1': {
          'path/to/variable1/in/xml': (
              'name of variable1 in user configuration',
              format function,
          ),
          'path/to/variable2/in/xml': (
              'name of variable2 in user configuration',
              format function,
          ),
      },
      'input file 2': {
          'path/to/variable1/in/xml': (
              'name of variable1 in user configuration',
              format function,
          ),
          'path/to/variable2/in/xml': (
              'name of variable2 in user configuration',
              format function,
          ),
      },
  }
  

  The format function takes the user provided value as input and produces a string as output.

  This is provided by the package developer.

• user_choice (dict) – The variables to be replaced (provided by the user).

createxml(xmlfilename, xml_string)

Reads the base input file, replaces the values and returns the input XML file object.

Parameters:

• xmlfilename (str) – Name of the base input file.

• xml_string (str) – Content of the base input file.

Returns:

The XML file object with replaced values.

Return type:

xml.etree.ElementTree.ElementTree

class drama.utils.Input(default_lines, user_choice)

Class to define the new default input for the project.

Parameters:

• default_lines (dict) –

  Specifications of the lines and the columns of the variables location into the input file and the functions which should be used to format them into strings. The line number is without taking comment lines into account. I.e. 0 refers to the first line that is not a comment. This input is specified as follows:

  {
      'input file 1': {
          'variable1_name': (line number, column, format function),
          'variable2_name': (line number, column, format function),
      },
      'input file 2': {
          'variable1_name': (line number, column, format function),
          'variable2_name': (line number, column, format function),
      },
  }
  

  The format function takes the user provided value as input and produces a string as output.

  This is provided by the package developer.

• user_choice (dict) – The variables to be replaced (provided by the user).

create(filename, input_lines)

Reads the base input file, replaces the values and returns the modified input file lines.

Parameters:

• filename (str) – Name of the base input file.

• input_lines (str) – Content of the base input file.

Returns:

The lines of the input file with replaced values.

Return type:

list of str

add_dict(d)

Adds a further dictionary to the user choices, in case more than one dictionary is needed to create the input file.

Parameters:

d (dict) – The dictionary with updates.

Returns:

Updated dictionary.

drama.utils.get_basic_config_dictionary(input_lines, default_input_lines)

Return the dictionary for the get_basic_config(), defined using _default_input_lines().

Returns:

dictionary with the basic configuration

Return type:

(dict)

drama.utils.get_basic_config_xml_dictionary(input_root, default_input_lines)

Return the dictionary for the get_basic_config(), defined using xmlinput_lines().

Returns:

dictionary with the basic configuration

Return type:

(dict)

drama.utils.spellcheck_input_var(config, default_lines_var)

Check for mispelling in user-input definition

Returns:

Raise error in case the variable is not one of those available.

Return type:

(Raise error)

drama.utils.spellcheck_xml_input_var(config, default_lines_var)

Check for misspelling in user-input definition (for xml input files)

Returns:

Raise error in case the variable is not one of those available.

Return type:

(Raise error)

drama.utils.get_drama_installation_path(framework='DRAMA')

Returns the DRAMA installation path.

Parameters:

framework (str) – defines whether DRAMA or DMF is using the wrapper

Returns:

DRAMA installation path.

Return type:

(str)

drama.utils.get_drama_config(framework='DRAMA')

Returns the paths to TOOLS and to other relevant folders/files of the installed version of DRAMA.

Parameters:

framework (str) – defines whether DRAMA or DMF is using the wrapper

Returns:

dictionary with the path to TOOLS and to other relevant

folders/files.

Return type:

(dict)

drama.utils.get_gnuplot_path(framework='DRAMA')

Returns the paths to the gnuplot executive file

Parameters:

framework (str) – defines whether DRAMA or DMF is using the wrapper.

Returns:

path to the gnuplot executive file

Return type:

(str)

drama.utils.generic_run_lazy(config, dependent_variables, project, save_output_dirs, parallel, ncpus, single_run_function, timeout, keep_output_files, framework='DRAMA', **kwargs)

Runs the single_run_function for the provided config and specified options, returns the iterable of the results.

Parameters:

• config (dict or list) –

  The (parametric) configuration. If dictionary, it can contain lists that would be expanded for the parametric analyses.

  Alternatively, config can also be a list of config dictionaries, or any iterable. Each config dictionary in this case describes one run and thus can not contain any list to expand.

• dependent_variables (list of lists of strs) – Describe which parameters depend on each other in a parametric analysis. Each list of parameters defines one dependency.

• project (str) – Path to DRAMA project to use as baseline (directory or exported project). If None the default project is used.

• save_output_dirs – Saves the output directories of all runs to this directory. Each run will have its own numbered directory. The path to it is stored in output_dir in each run’s config. If None the output directories will be deleted.

• parallel (bool) – Defines if simulations shall be run in parallel.

• ncpus (int) – Number of CPUs to use if parallel is True. If not specified, the maximum available will be used.

• timeout (int) – Timeout in seconds for each run.

• keep_output_files (str or list) – If list, it contains the filenames of the output files that will be saved into the output_dir (shared list for reentry and risk analysis). If ‘all’ the whole output folder will be saved into the output_dir, if ‘summary’ (Default), only a default list of output files will be saved into the output_dir (valid only if output_dir is provided as input parameter).

• framework (str) – defines whether DRAMA or DMF is using the wrapper

Returns:

<generator object generic_run_lazy>

drama.utils.generic_run(config, dependent_variables, project, save_output_dirs, parallel, ncpus, single_run_function, timeout, keep_output_files, framework='DRAMA', **kwargs)

Runs the single_run_function for the provided config and specified options, returns the list of results.

Parameters:

• config (dict or list) –

  The (parametric) configuration. If dictionary, it can contain lists that would be expanded for the parametric analyses.

  Alternatively, config can also be a list of config dictionaries, or any iterable. Each config dictionary in this case describes one run and thus can not contain any list to expand.

• dependent_variables (list of lists of strs) – Describe which parameters depend on each other in a parametric analysis. Each list of parameters defines one dependency.

• project (str) – Path to DRAMA project to use as baseline (directory or exported project). If None the default project is used.

• save_output_dirs – Saves the output directories of all runs to this directory. Each run will have its own numbered directory. The path to it is stored in output_dir in each run’s config. If None the output directories will be deleted.

• parallel (bool) – Defines if simulations shall be run in parallel.

• ncpus (int) – Number of CPUs to use if parallel is True. If not specified, the maximum available will be used.

• timeout (int) – Timeout in seconds for each run.

• keep_output_files (str or list) – If list, it contains the filenames of the output files that will be saved into the output_dir (shared list for reentry and risk analysis). If ‘all’ the whole output folder will be saved into the output_dir, if ‘summary’ (Default), only a default list of output files will be saved into the output_dir (valid only if output_dir is provided as input parameter).

• framework (str) – defines whether DRAMA or DMF is using the wrapper

Returns:

{
    'config': provided config of all runs,
    'errors': [ # info on erroneous runs
        {
            'config' : config dict of single erroneous run,
            'status' : 'error <details>',
            'output' : stdout and stderr of tool-specific process,
            'logfile': tool-specific logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of tool-specific process,
            'logfile': tool-specific logfile content,
            tool-specific-result: result(s) of the tool-specific
                                  output function(s),
        },
        ...
    ],
}

drama.utils.format_label(label, target)

Returns label in a suitable format for the plots

Returns:

label

Return type:

(str)

drama.utils.uniq_fname()

Creates unique filenames using NamedTemporaryFile

drama.utils.init_logging(process_logger, log_level='DEBUG', logging_queue=None, log_group_id=None)

Initializes the logging for this wrapper.

Parameters:

• process_logger – (logging.logger) the logger as used in this module and the current instance of the process

• log_level – (dict) defines what log records to report

• logging_queue – (Manager.Queue) the logging queue gathering all log records

• log_group_id – (str) additional argument that is added to a log record.