ARES

drama.ares.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.ares.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)

Runs (parametric) ARES analysis and returns a dictionary with config and iterable results.

Parameters:

• config (dict or list) –

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

  {
      'runid': str (max. 6 characters) or list,
      'comment1': str or list,
      'comment2': str or list,
      'functionality': int [1,2,3,4] or list,
      'minimumParticleSize': float or list [m],
      'maximumParticleSize': float or list [m],
      'populationCloudIds': list of 5 str *see known issues,
      'populationCloudSwitches': list of 5 int [0, 1] *see known issues,
      'radarWavelength': float or list [m],
      'radarEquationParameters': list of 3 lists of 2 float *see known issues,
      'energyToMassRatioSwitch': int or list [0, 1],
      'minimumEnergyToMassRatio': float or list [J/g],
      'spacecraftMass': float or list [kg],
      'spacecraftRadius': float or list [m],
      'semiMajorAxis': float or list [km],
      'eccentricity': float or list,
      'inclination': float or list [deg],
      'rightAscensionOfTheAscendingNode': float or list [deg],
      'argumentOfPerigee': float or list [deg],
      'analysisReferenceDate': datetime or list,
      'spacecraftUncertaintyType': int or list [1, 2],
      'spacecraftAlongTrackUncertainty': float or list [km],
      'spacecraftCrossTrackUncertainty': float or list [km],
      'spacecraftRadialUncertainty': float or list [km],
      'predictionToEventTime': float or list [0 < days < 7],
      'catalogUncertaintyType': int or list [1, 2],
      'userEnteredCovariances': list of 36 lists of 18 float [km] *see known issues,
      'globalUncertaintyScalingFactor': float or list,
      'uncertaintyScalingFactors': list of 36 lists of 6 float *see known issues,
      'numberOfACPLValues': int *see known issues,
      'ACPLValues': list of float *see known issues,
      'collisionProbabilityAlgorithm': int or list [0, 1],
      'avoidanceManoeuvreCriteria': int or list [0, 1, 3],
      'targetCollisionProbabilityLevel': float or list,
      'allowedMinimumMissDistance': float or list [km],
      'numberOfRevolutions': int *see known issues,
      'revolutionVectors': list of int *see known issues,
      'engineName': str or list,
      'engineSpecificImpulse': float or list [s],
  }
  

  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 ares_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 ares configuration file.

• **kwargs – If config is None, the ARES 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 ares
results_lazy = ares.run_lazy(semiMajorAxis=7162.0, eccentricity=0, inclination=98, analysisReferenceDate=datetime(2024, 3, 27))

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

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

#store the annual collision probability of each single run:
annual_collision_probabilities=[]
for res in results_lazy['results']:
    for single_run_res in res:
        annual_collision_probabilities.append(single_run_res['annual_collision_p'])

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

from drama import ares
config = {
    'semiMajorAxis': [7162.0 + 480, 7162.0 + 500],
    'eccentricity': [0.001, 0.005],
}
dependent_variables = [['semiMajorAxis', 'eccentricity']]
results_lazy = ares.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.ares.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, keep_output_files='summary', tmpfile_path=None, framework='DRAMA', spell_check=True, **kwargs)

Runs (parametric) ARES analysis and return the results.

Parameters:

• config (dict or list) –

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

  {
      'runid': str (max. 6 characters) or list,
      'comment1': str or list,
      'comment2': str or list,
      'functionality': int [1,2,3,4] or list,
      'minimumParticleSize': float or list [m],
      'maximumParticleSize': float or list [m],
      'populationCloudIds': list of 5 str *see known issues,
      'populationCloudSwitches': list of 5 int [0, 1] *see known issues,
      'radarWavelength': float or list [m],
      'radarEquationParameters': list of 3 lists of 2 float *see known issues,
      'energyToMassRatioSwitch': int or list [0, 1],
      'minimumEnergyToMassRatio': float or list [J/g],
      'spacecraftMass': float or list [kg],
      'spacecraftRadius': float or list [m],
      'semiMajorAxis': float or list [km],
      'eccentricity': float or list,
      'inclination': float or list [deg],
      'rightAscensionOfTheAscendingNode': float or list [deg],
      'argumentOfPerigee': float or list [deg],
      'analysisReferenceDate': datetime or list,
      'spacecraftUncertaintyType': int or list [1, 2],
      'spacecraftAlongTrackUncertainty': float or list [km],
      'spacecraftCrossTrackUncertainty': float or list [km],
      'spacecraftRadialUncertainty': float or list [km],
      'predictionToEventTime': float or list [0 < days < 7],
      'catalogUncertaintyType': int or list [1, 2],
      'userEnteredCovariances': list of 36 lists of 18 float [km] *see known issues,
      'globalUncertaintyScalingFactor': float or list,
      'uncertaintyScalingFactors': list of 36 lists of 6 float *see known issues,
      'numberOfACPLValues': int *see known issues,
      'ACPLValues': list of float *see known issues,
      'collisionProbabilityAlgorithm': int or list [0, 1],
      'avoidanceManoeuvreCriteria': int or list [0, 1, 3],
      'targetCollisionProbabilityLevel': float or list,
      'allowedMinimumMissDistance': float or list [km],
      'numberOfRevolutions': int *see known issues,
      'revolutionVectors': list of int *see known issues,
      'engineName': str or list,
      'engineSpecificImpulse': float or list [s]
  }
  

  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 ares_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.

• 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

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

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

• **kwargs – If config is None, the ARES 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 ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
            'annual_collision_p': annual collision probability,
        },
        ...
    ],
}

Examples

Direct call with one run:

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

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

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

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

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

drama.ares.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)

ARES 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 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) – Define whether DRAMA or DMF is using the wrapper

• **kwargs – If config is None, the ARES 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 ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
            'annual_collision_p': annual collision probability,
        },
        ...
    ],
    'stopping reason',
}

The stopping reason should be always n_max reached.

Example

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

drama.ares.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 ARES 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) – Define whether DRAMA or DMF is using the wrapper

• **kwargs – If config is None, the ARES 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 ares
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=7162.0, sigma=2.5)}
results_lazy = ares.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.ares.run_monte_carlo_with_wilson_confidence(config=None, n_max=10000, target_variable='annual_collision_p', 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)

ARES 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.

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

• 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) – Define whether DRAMA or DMF is using the wrapper

• **kwargs – If config is None, the ARES 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 ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of ares process,
            'logfile': ares.log file content,
            'errfile': ares.err file content,
            'annual_collision_p': annual collision probability,
        },
        ...
    ],
    '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 ares
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=7162.0, sigma=2.5)}
results = ares.run_monte_carlo_with_wilson_confidence(config=config,
    confidence_level=95.)

drama.ares.get_progress(tmpfile_path)

Retrieves the current progress of ARES, when the tmpfile_path exists

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

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

Parameters:

• results (list) – List of dict of ARES 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_ares.plot_cdf(results, target='annual_collision_p', plotfile_name='cdf', x_label=None, framework='DRAMA')

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

Parameters:

• results (list) – List of dict of ARES 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_ares.plot_heatmap(results, variables, target='annual_collision_p', plotfile_name='heatmap', x_label=None, y_label=None, framework='DRAMA')

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

Parameters:

• results (list) – List of dict of ARES 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.