parsac.sensitivity package

Module contents

class parsac.sensitivity.CV(n: int | None = None, **kwargs)

Bases: SensitivityAnalysis

Ratio of coefficients of variation of each target metric and input parameter, based on Monte Carlo sampling.

This analysis is only meaningful when performed for one parameter at a time.

Parameters:

kwargs – Additional keyword arguments to passed to Experiment.

class parsac.sensitivity.MVR(n: int | None = None, **kwargs)

Bases: SensitivityAnalysis

Sensitivity analysis based on Monte Carlo sampling and linear regression, as described by Saltelli et al. (section 1.2.5)

The sensitivity metric that is returned by default by run() and run_async() is the value of the standardized regression coefficients. These can take negative values, indicating that the parameter has an inverse relationship with the target metric. When ranking parameters by their sensitivity, the absolute value of the coefficients is used.

Parameters:

kwargs – Additional keyword arguments to passed to Experiment.

class parsac.sensitivity.Morris(*sampler_args, db_file: str | Path | None = None, distributed: bool | None = None, max_workers: int | None = None, **sampler_kwargs)

Bases: _SALibAnalysis

Method of Morris, using SALib.sample.morris.sample() and SALib.analyze.morris.analyze().

The sensitivity metric that is returned by default by run() and run_async() is the mean of the distribution of the absolute values of the elementary effects (mu_star).

References: Morris (1991); Campolongo et al. (2007)

Parameters:

  • sampler_args – Positional arguments to pass to the SALib sampler.

  • db_file – The file to store the results in. If None, a file with the same name as the script will be created with the suffix “.results.db”.

  • distributed – Whether to run the experiment in distributed mode using MPI. If None, distributed mode is activated if variable MPI4PY_FUTURES_MAX_WORKERS is present in the environment.

  • max_workers – The maximum number of workers to use. If None, it will be set to the number of available CPUs.

  • sampler_kwargs – Keyword arguments to pass to the SALib sampler.

class parsac.sensitivity.SensitivityAnalysis(**kwargs)

Bases: Experiment

A sensitivity analysis.

To configure the analysis, add parameters to include by calling add_parameter(), and add jobs that calculate target metrics by calling add_job(). These target metrics should be scalar outputs of the job. Some jobs may require you to specify explicitly which outputs to record by calling methods such as parsac.job.gotm.Simulation.record_output().

Parameters:

kwargs – Additional keyword arguments to passed to Experiment.

add_job(runner: Runner) → None

Add a job that takes parameter as input and produces scalar outputs, suitable as target for sensitivity analysis.

run(**kwargs) → ndarray | dict[str, Any]

Run the sensitivity analysis.

Parameters:

**kwargs – Additional keyword arguments to pass to run_async().

async run_async(work_dirs: Iterable[PathLike[Any] | str] | str | None = None, return_details: bool = False, **kwargs) → ndarray | dict[str, Any]

Run the sensitivity analysis asynchronously.

Parameters:

  • work_dirs – A list of directories to use to store setups and results per parameter set, or a format string with a single placeholder that incorporates the parameter set index i, for instance, work_dirs="{i:03}" to place results in directories 000, 001, … If this argument is not provided, temporary directories will be used to store results while evaluating the parameter sets.

  • return_details – If True, return a dictionary with all results from the analysis.

  • **kwargs – Additional keyword arguments to pass to the analysis method.

Returns:

If return_details is False, an array that specifies the sensitivity of each target (second dimension) to each parameter (first dimension). If return_details is True, a dictionary with raw results of the analysis (values) for each target (keys).

class parsac.sensitivity.Sobol(*sampler_args, db_file: str | Path | None = None, distributed: bool | None = None, max_workers: int | None = None, **sampler_kwargs)

Bases: _SALibAnalysis

Sobol’ Sensitivity Analysis, using SALib.sample.sobol.sample() and SALib.analyze.sobol.analyze().

The sensitivity metric that is returned by default by run() and run_async() is the total sensitivity (ST).

References: Sobol’ (2001); Saltelli (2002); Saltelli et al. (2010)

Parameters:

  • sampler_args – Positional arguments to pass to the SALib sampler.

  • db_file – The file to store the results in. If None, a file with the same name as the script will be created with the suffix “.results.db”.

  • distributed – Whether to run the experiment in distributed mode using MPI. If None, distributed mode is activated if variable MPI4PY_FUTURES_MAX_WORKERS is present in the environment.

  • max_workers – The maximum number of workers to use. If None, it will be set to the number of available CPUs.

  • sampler_kwargs – Keyword arguments to pass to the SALib sampler.