OSCAR

drama.oscar.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.oscar.run_lazy(config=None, dependent_variables=[], json=None, project=None, fap_day_content=None, fap_mon_content=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', trajectory=False, spell_check=True, geo_cross=False, **kwargs)

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

Parameters:

• config (dict or list) –

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

  {
      'beginDate': datetime or list,
      'runId': str or list,
      'comment1': str or list,
      'comment2': str 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],
      'meanAnomaly': float or list [deg],
      'spacecraftCrossSectionArea': float or list [m^2],
      'spacecraftMass': float or list [kg],
      'dryMassSwitch': int or list,
      'dragCoefficient': float or list,
      'reflectivityCoefficient': float or list,
      'disposalOption': int or list,
      'disposalSystem': int or list
      'hohmannTransferManoeuvres': int or list,
      'directDeOrbitPerigeeAltitude': float or list [km],
      'reOrbitPerigeeAltitude': float or list [km],
      'lifetimeLimit': float or list [years],
      'lifetimeMargin': float or list [%],
      'chemicalPropulsionSystem': str or list,
      'chemicalSpecificImpulse': float or list [s],
      'electricPropulsionSystem': str or list,
      'electricSpecificImpulse': float or list [s],
      'electricTotalThrust': float or list [mN],
      'electricThrusterLifetime': float or list [hours],
      'tetherLength': float or list [km],
      'tetherResistance': float or list [Ohm],
      'tetherRelativeAngle': float or list [deg],
      'dragAugmentationCrossSectionArea': float or list [m^2],
      'dragAugmentationDragCoefficient': float or list,
      'dragAugmentationSolarReflectivityCoefficient': float or list,
      'propagationTime': float or list [years],
      'solarAndGeomagneticActivityScenario': int or list,
      'latestPredictionScenario': int or list,
      'confidenceInterval': float or list [%]
      'solarActivityModeSwitch': int or list,
      'userDefinedSolarFlux': float or list [W/m^2/Hz],
      'userDefinedAp': float or list,
      'monteCarloSamplingCycles': int or list,
      'generatePlots': list of 7 int, *see known issues
      'dataLinestyle': int or list,
      'plotCriticalAltitude': int or list,
      'criticalAltitudeLinestyle': int or list,
  }
  

  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 oscar_input.schema.json.

• fap_day_content (list) – Holds an array of fap_day lines

• fap_mon_content (list) – Holds an array of fap_mon lines

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

• trajectory (bool) – Specify if the computed trajectory should be returned in the output

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

• geo_cross (bool) – Flag to search for GEO crossing in oscar.oad file.

• **kwargs – If config is None, the OSCAR 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 oscar
results_lazy = oscar.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 oscar
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
    'inclination': 98,
    'beginDate': datetime(2024, 3, 27),
}
results_lazy = oscar.run_lazy(config)

#store the lifetime of each single run:
lifetimes=[]
for res in results_lazy['results']:
    for single_run_res in res:
        lifetimes.append(single_run_res['lifetime'])

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

from drama import oscar
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
}
dependent_variables = [['semiMajorAxis', 'eccentricity']]
results_lazy = oscar.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.oscar.run(config=None, dependent_variables=[], json=None, project=None, fap_day_content=None, fap_mon_content=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', tmpfile_path=None, trajectory=False, spell_check=True, geo_cross=False, **kwargs)

Runs (parametric) OSCAR analysis and return the results.

Parameters:

• config (dict or list) –

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

  {
      'beginDate': datetime or list,
      'runId': str or list,
      'comment1': str or list,
      'comment2': str 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],
      'meanAnomaly': float or list [deg],
      'spacecraftCrossSectionArea': float or list [m^2],
      'spacecraftMass': float or list [kg],
      'dryMassSwitch': int or list,
      'dragCoefficient': float or list,
      'reflectivityCoefficient': float or list,
      'disposalOption': int or list,
      'disposalSystem': int or list
      'hohmannTransferManoeuvres': int or list,
      'directDeOrbitPerigeeAltitude': float or list [km],
      'reOrbitPerigeeAltitude': float or list [km],
      'lifetimeLimit': float or list [years],
      'lifetimeMargin': float or list [%],
      'chemicalPropulsionSystem': str or list,
      'chemicalSpecificImpulse': float or list [s],
      'electricPropulsionSystem': str or list,
      'electricSpecificImpulse': float or list [s],
      'electricTotalThrust': float or list [mN],
      'electricThrusterLifetime': float or list [hours],
      'tetherLength': float or list [km],
      'tetherResistance': float or list [Ohm],
      'tetherRelativeAngle': float or list [deg],
      'dragAugmentationCrossSectionArea': float or list [m^2],
      'dragAugmentationDragCoefficient': float or list,
      'dragAugmentationSolarReflectivityCoefficient': float or list,
      'propagationTime': float or list [years],
      'solarAndGeomagneticActivityScenario': int or list,
      'latestPredictionScenario': int or list,
      'confidenceInterval': float or list [%]
      'solarActivityModeSwitch': int or list,
      'userDefinedSolarFlux': float or list [W/m^2/Hz],
      'userDefinedAp': float or list,
      'monteCarloSamplingCycles': int or list,
      'generatePlots': list of int, *see known issues
      'dataLinestyle': int or list,
      'plotCriticalAltitude': int or list,
      'criticalAltitudeLinestyle': int or list,
  }
  

  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 oscar_input.schema.json.

• fap_day_content (list) – Holds an array of fap_day lines

• fap_mon_content (list) – Holds an array of fap_mon lines

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

• trajectory (bool) – Specify if the computed trajectory should be returned in the output

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

• geo_cross (bool) – Flag to search for GEO crossing in oscar.oad file.

• **kwargs – If config is None, the OSCAR 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 oscar process,
            'logfile': oscar logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of oscar process,
            'logfile': oscar logfile content,
            'lifetime': lifetime in years,
            'reentry': True if object reentered in the propagation
                span,
            'final_state': final state of the object at the end of
                the propagation span,
            'trajectory': computed trajectory, [optional]
            'oad_data': altitude vs. declination given epoch
                with GEO crossing flag from PyOscar.oad,
            'geo_crossing': True if GEO crossing are detected,False otherwise.
        },
        ...
    ],
}

Examples

Direct call with one run:

from drama import oscar
results = oscar.run(sma=6878, ecc=0, inc=98, epoch=datetime(2019, 5, 10))

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

from drama import oscar
config = {
    'semiMajorAxis': [6378 + 480, 6378 + 500],
    'eccentricity': [0.001, 0.005],
    'inclination': 98,
    'epoch': datetime(2019, 5, 10),
}
results = oscar.run(config)

Two runs with dependent variables (sma = 6858, ecc = 0.001 and sma = 6878, ecc = 0.005):

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

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

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

• trajectory (bool) – Specify if the computed trajectory should be returned in the output

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

• geo_cross (bool/str) – Flag to search for GEO crossing in oscar.oad file. If ‘ignores_first_year’, the True flags within the firt year of propagation are ignored.

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

• **kwargs – If config is None, the OSCAR 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 oscar process,
            'logfile': oscar logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of oscar process,
            'logfile': oscar logfile content,
            'lifetime': lifetime in years,
            'reentry': True if object reentered in the propagation
                span,
            'final_state': final state of the object at the end of
                the propagation span,
            'trajectory': computed trajectory, [optional]
            'oad_data': altitude vs. declination given epoch
                with GEO crossing flag from PyOscar.oad,
            'geo_crossing': True if GEO crossing are detected,False otherwise.
        },
        ...
    ],
    'stopping reason',
    'distributions': dict of the input parameters and target variables
        with the list of values in each single simulation
    'n_tot_runs': total number of runs,
    'n_succ_runs': number of successful runs,
}

The stopping reason should be always n_max reached.

Example

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

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

Lazy version of the OSCAR 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).

• trajectory (bool) – Specify if the computed trajectory should be returned in the output

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

• geo_cross (bool/str) – Flag to search for GEO crossing in oscar.oad file. If ‘ignores_first_year’, the True flags within the firt year of propagation are ignored.

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

• **kwargs – If config is None, the OSCAR 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 oscar
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=6700, sigma=2.5)}
results_lazy = oscar.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.oscar.run_monte_carlo_with_wilson_confidence(config=None, n_max=10000, target_variable='lifetime', binary_criteria=25.0, confidence_level=99.0, project=None, quantile=0.9, parallel=True, ncpus=None, timeout=None, keep_output_files='summary', trajectory=False, spell_check=True, geo_cross=False, framework='DRAMA', **kwargs)

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

• trajectory (bool) – Specify if the computed trajectory should be returned in the output

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

• geo_cross (bool) – Flag to search for GEO crossing in oscar.oad file. If ‘ignores_first_year’, the True flags within the firt year of propagation are ignored.

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

• **kwargs – If config is None, the OSCAR 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 oscar process,
            'logfile': oscar logfile content,
        },
        ...
    ],
    'results': [
        {
            'config': config dict of single successful run,
            'status': 'success',
            'output': stdout and stderr of oscar process,
            'logfile': oscar logfile content,
            'lifetime': lifetime in years,
            'reentry': True if object reentered in the propagation
                span,
            'final_state': final state of the object at the end of
                the propagation span,
            'trajectory': computed trajectory, [optional]
            'oad_data': altitude vs. declination given epoch
                with GEO crossing flag from PyOscar.oad,
            'geo_crossing': True if GEO crossing are detected,False otherwise.
        },
        ...
    ],
    'stopping reason',
    'distributions': dict of the input parameters and target variables
        with the list of values in each single simulation
    'n_tot_runs': total number of runs,
    'n_succ_runs': number of successful runs,
}

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 oscar
from drama.monte_carlo import Gaussian
config = {'semiMajorAxis': Gaussian(mu=6700, sigma=2.5)}
results = oscar.run_monte_carlo_with_wilson_confidence(config=config,
    confidence_level=95.)

drama.oscar.get_progress(tmpfile_path)

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

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

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

Parameters:

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

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

Parameters:

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

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

Parameters:

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