MIDAS

drama.midas.get_basic_config(framework='DRAMA', project=None)

Returns the base config read from the provided project or the default if no project is specified.

Parameters:

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

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

Returns:

The config dict as specified in parameter config in run().

drama.midas.run_lazy(config=None, dependent_variables=[], json=None, project=None, save_output_dirs=None, parallel=True, ncpus=None, timeout=None, logging_queue=None, log_level='DEBUG', log_group_id=None, framework='DRAMA', keep_output_files='summary', spell_check=True, **kwargs)

Run (parametric) MIDAS analysis and returns a dictionary with config and iterable results.

Parameters:

• config (dict or list) –

  The (parametric) MIDAS run configuration. If a dictionary is provided it must be of the following format (lists are used for parametric analyses):

  {
      'beginDate': datetime or list,
      'endDate': datetime or list,
      'runId': str < 15 chars or list,
      'semiMajorAxis': float or list [km],
      'eccentricity': float or list,
      'inclination': float or list [deg],
      'rightAscensionOfTheAscendingNode': float or list [deg],
      'argumentOfPerigee': float or list [deg],
      'comment1': str < 80 chars or list,
      'comment2': str < 80 chars or list,
      'mass': float or list [kg],
      'area': float or list [m^2],
      'dragCoefficient': float or list,
      'solarRadiationPressureCoefficient': float or list,
      'lowerSizeThreshold': float or list,
      'lowerSizeThresholdUnit': str or list ['m'/'kg']
      'upperSizeThreshold': float or list,
      'upperSizeThresholdUnit': str or list ['m'/'kg']
      'sourceSwitches': list of 10 int [0, 1] *see known issues,
      'backgroundMeteoroidModel': int or list [1, 2 ,3],
      'backgroundMeteoroidPopulation': list of 5 int [0, 1] *see known issues,
      'velocityDistribution': int or list [0, 1],
      'annualMeteoroidStream': int or list [0, 1, 2],
      'cloudSwitches': list of 5 int [0, 1] *see known issues,
      'cloudFileIds': list of 5 str [0, 1] *see known issues,
      'radarWavelength': float or list [m],
      'radarEquationParameters': list of 3 lists of 2 float *see known issues
  }
  

  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. See the example below for details.

• json (dict) – Python object holding the resemblance of the JSON file containing all required fields needed for a run. It should conform with the midas_input.schema.json.

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

• save_output_dirs – Save 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) – Define 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.

• logging_queue (manager.Queue) – thread safe queue, which aggregates log messages for the caller.

• log_level (str) – the log level for the logger, can be DEBUG, INFO, WARNING, ERROR and CRITICAL.

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

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

• 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).

• spell_check (bool) – Specify if the case to run should contain only keywords that are present in the configuration file.

• **kwargs – If config is None, the MIDAS run configuration values can be passed on as kwargs.

Returns:

{
    'config': provided config of all runs,
    'results': <generator object generic_run_lazy>,
}

Examples

Direct call with one run:

from drama import midas
results_lazy = midas.run_lazy(semiMajorAxis=6878, eccentricity=0, inclination=98, beginDate=datetime(2024, 3, 27))

Multiple parametric runs passing a configuration dictionary (four runs with all possible combinations):

from drama import midas
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
    'inclination': 98,
    'beginDate': datetime(2024, 3, 27),
}
results_lazy = midas.run_lazy(config)

#store the total number of impacts of each single run:
total_numbers_of_impacts=[]
for res in results_lazy['results']:
    for single_run_res in res:
        total_numbers_of_impacts.append(single_run_res['total_number_of_impacts'])

Two runs with dependent variables (semiMajorAxis = 6858, eccentricity = 0.001 and semiMajorAxis = 6878, eccentricity = 0.005):

from drama import midas
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
}
dependent_variables = [['semiMajorAxis', 'eccentricity']]
results_lazy = midas.run_lazy(config, dependent_variables)

#print the status of each single run:
for res in results_lazy['results']:
    for single_run_res in res:
        print(single_run_res['status'])

drama.midas.run(config=None, dependent_variables=[], json=None, project=None, save_output_dirs=None, parallel=True, ncpus=None, timeout=None, logging_queue=None, log_level='DEBUG', log_group_id=None, framework='DRAMA', keep_output_files='all', tmpfile_path=None, spell_check=True, **kwargs)

Run (parametric) MIDAS analysis and return the results.

Parameters:

• config (dict or list) –

  The (parametric) MIDAS run configuration. If a dictionary is provided it must be of the following format (lists are used for parametric analyses):

  {
      'beginDate': datetime or list,
      'endDate': datetime or list,
      'runId': str < 15 chars or list,
      'semiMajorAxis': float or list [km],
      'eccentricity': float or list,
      'inclination': float or list [deg],
      'rightAscensionOfTheAscendingNode': float or list [deg],
      'argumentOfPerigee': float or list [deg],
      'comment1': str < 80 chars or list,
      'comment2': str < 80 chars or list,
      'mass': float or list [kg],
      'area': float or list [m^2],
      'dragCoefficient': float or list,
      'solarRadiationPressureCoefficient': float or list,
      'lowerSizeThreshold': float or list,
      'lowerSizeThresholdUnit': str or list ['m'/'kg']
      'upperSizeThreshold': float or list,
      'upperSizeThresholdUnit': str or list ['m'/'kg']
      'sourceSwitches': list of 10 int [0, 1] *see known issues,
      'backgroundMeteoroidModel': int or list [1, 2 ,3],
      'backgroundMeteoroidPopulation': list of 5 int [0, 1] *see known issues,
      'velocityDistribution': int or list [0, 1],
      'annualMeteoroidStream': int or list [0, 1, 2],
      'cloudSwitches': list of 5 int [0, 1] *see known issues,
      'cloudFileIds': list of 5 str [0, 1] *see known issues,
      'radarWavelength': float or list [m],
      'radarEquationParameters': list of 3 lists of 2 float *see known issues
  }
  

  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. See the example below for details.

• json (dict) – Python object holding the resemblance of the JSON file containing all required fields needed for a run. It should conform with the midas_input.schema.json.

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

• save_output_dirs – Save 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) – Define 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.

• logging_queue (manager.Queue) – thread safe queue, which aggregates log messages for the caller.

• log_level (str) – the log level for the logger, can be DEBUG, INFO, WARNING, ERROR and CRITICAL.

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

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

• 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).

• tmpfile_path (ValueProxy) – hands back the tmp file path used by the analysis module so that it can be checked continuously in a separate thread.

• spell_check (bool) – Specify if the case to run should contain only keywords that are present in the configuration file.

• **kwargs – If config is None, the MIDAS run configuration values can be passed on as kwargs.

Returns:

{
    'config': {}, # provided config of all runs,
    'errors': [ # info on erroneous runs
        {
            'config': config of single erroneous run,
            'status': 'error <details>',
            'output': stdout and stderr of midas process,
            'logfile': midas logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config of single successful run,
            'status': 'success',
            'output': stdout and stderr of midas process,
            'logfile': midas logfile content,
            'total_number_of_impacts': total number of impacts,
        },
        ...
    ],
}

Examples

Direct call with one run:

from drama import midas
results = midas.run(semiMajorAxis=6878, eccentricity=0, inclination=98, beginDate=datetime(2024, 3, 27))

Multiple parametric runs passing a configuration dictionary (four runs with all possible combinations):

from drama import midas
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
    'inclination': 98,
    'beginDate': datetime(2024, 3, 27),
}
results = midas.run(config)

Two runs with dependent variables (semiMajorAxis = 6858, eccentricity = 0.001 and semiMajorAxis = 6878, eccentricity = 0.005):

from drama import midas
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
}
dependent_variables = [['semiMajorAxis', 'eccentricity']]
results = midas.run(config, dependent_variables)

drama.midas.run_monte_carlo(config=None, n=10000, project=None, parallel=True, ncpus=None, timeout=None, keep_output_files='summary', spell_check=True, framework='DRAMA', **kwargs)

MIDAS Monte Carlo runner.

Parameters:

• config (dict) – The config as specified in parameter config in run(), containing at least one monte_carlo.Distribution.

• n (int) – The number of runs.

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

• parallel (bool) – Define 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).

• spell_check (bool) – Specify if the case to run should contain only keywords that are present in the configuration file

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

• **kwargs – If config is None, the MIDAS run configuration values can be passed on as kwargs.

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 midas process,
            'logfile': midas logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of midas process,
            'logfile': midas logfile content,
            'total_number_of_impacts': total number of impacts,
        },
        ...
    ],
    'stopping reason',
}

The stopping reason should be always n_max reached.

Example

from drama import midas
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=6700, sigma=2.5)}
results = midas.run_monte_carlo(config)

drama.midas.run_monte_carlo_lazy(config=None, n=10000, project=None, parallel=True, ncpus=None, timeout=None, keep_output_files='summary', spell_check=True, framework='DRAMA', **kwargs)

Lazy version of the MIDAS Monte Carlo runner.

Parameters:

• config (dict) – The config as specified in parameter config in run(), containing at least one monte_carlo.Distribution.

• n (int) – The number of runs.

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

• parallel (bool) – Define 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).

• spell_check (bool) – Specify if the case to run should contain only keywords that are present in the configuration file

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

• **kwargs – If config is None, the MIDAS run configuration values can be passed on as kwargs.

Returns:

 {
    'config': provided config of all runs,
    'results': <iterable>,
    'stopping reason',
}

The stopping reason should be always n_max reached.

Example

from drama import midas
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=6700, sigma=2.5)}
results = midas.run_monte_carlo_lazy(config)

#print the status of each single run:
for res in results_lazy['results']:
    for single_run_res in res:
        print(single_run_res['status'])

drama.midas.run_monte_carlo_with_wilson_confidence(config=None, n_max=10000, target_variable='total_number_of_impacts', binary_criteria=0.0001, confidence_level=99.0, project=None, quantile=0.9, parallel=True, ncpus=None, timeout=None, keep_output_files='summary', spell_check=True, framework='DRAMA', **kwargs)

MIDAS Monte Carlo runner checking for Wilson confidence interval with correction for continuity.

Parameters:

• config (dict) – The config as specified in parameter config in run(), containing at least one monte_carlo.Distribution.

• n_max (int) – The maximum number of runs.

• target_variable (str) – The key in the result dictionaries to be checked.

• binary_criteria (float) – The threshold value for the binary check.

• confidence_level (float) – The confidence level to be reached. Supported confidence levels: 95.0, 99.0, 99.8.

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

• quantile – Probability that the target variable is compliance with the binary criteria. Default value is 0.9 (90% probability).

• parallel (bool) – Define 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).

• spell_check (bool) – Specify if the case to run should contain only keywords that are present in the configuration file

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

• **kwargs – If config is None, the MIDAS run configuration values can be passed on as kwargs.

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 midas process,
            'logfile': midas logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of midas process,
            'logfile': midas logfile content,
            'total_number_of_impacts': total number of impacts,
        },
        ...
    ],
    'stopping reason',
}

The stopping reason can be:

• n_max reached if the confidence level was not reached.

• confidence reached with status OK if the confidence was reached and the hypothesis was fulfilled.

• confidence reached with status NOK if the confidence level was reached and the hypothesis was not fulfilled.

Example

from drama import midas
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=6700, sigma=2.5)}
results = midas.run_monte_carlo_with_wilson_confidence(config=config,
    confidence_level=95.)

drama.midas.get_progress(tmpfile_path)

Retrieves the current progress of MIDAS, when the tmpfile_path already exists

drama.plot_midas.plot_histogram(results, target='total_flux', plotfile_name='histogram', x_label=None, framework='DRAMA')

Generates the histogram of the ‘target’ variable from the provided ‘results’ from MIDAS.

Parameters:

• results (list) – List of dict of MIDAS results. Each dictionary must contain the ‘target’ key.

• target (str) – The target variable

• plotfile_name (str) – file name (without extension) for the output file.

• x_label (str) – label for the x axis

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

Note

Creates a {plotfile_name}.png file containing the histogram plot for the ‘target’ variable.

drama.plot_midas.plot_cdf(results, target='total_flux', plotfile_name='cdf', x_label=None, framework='DRAMA')

Generates the cumulative distribution function of the ‘target’ variable from the provided ‘results’ from MIDAS.

Parameters:

• results (list) – List of dict of MIDAS results. Each dictionary must contain the ‘target’ key.

• target (str) – The target variable

• plotfile_name (str) – file name (without extension) for the output file.

• x_label (str) – label for the x axis

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

Note

Creates a {plotfile_name}.png file containing the cumulative distribution function plot for the ‘target’ variable.

drama.plot_midas.plot_heatmap(results, variables, target='total_flux', plotfile_name='heatmap', x_label=None, y_label=None, framework='DRAMA')

Generates the Heatmap of the ‘target’ variable from the provided ‘results’ from MIDAS.

Parameters:

• results (list) – List of dict of MIDAS results. Each dictionary must contain the ‘target’ key.

• target (str) – The target variable

• plotfile_name (str) – file name (without extension) for the output file.

• x_label (str) – label for the x axis

• y_label (str) – label for the y axis

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

Note

Creates a {plotfile_name}.png file containing the heatmap plot for the ‘target’ variable.