reemission.salib.runners

class reemission.salib.runners.SALibProblem(names: ~typing.List[str], bounds: ~typing.List[~typing.Tuple[float, float]] = <factory>, groups: ~typing.Dict[str, ~typing.List[int]] | None = None, use_groups_in_sobol: bool = False)[source]

Bases: object

A dataclass to represent a SALib problem definition and construct SALib problem dictionary.

num_vars

Number of variables in the problem.

Type:: int

names

List of variable names.

Type:: List[str]

bounds

List of bounds for each variable.

Type:: List[Tuple[float, float]]

groups

Optional dictionary mapping group names to lists of variable indices.

Type:: Dict[str, List[int]] | None

use_groups_in_sobol

If True, use groups in Sobol analysis.

Type:: bool

using_unit_bounds

If True, all bounds are (0.0, 1.0).

Type:: bool

__post_init__()[source]: Post-initialization to set the number of variables.

bounds: List[Tuple[float, float]]

classmethod from_variables(variables: List[Variable], use_groups_in_sobol: bool = False) → SALibProblem[source]

Create a SALibProblem instance from a list of Variable objects. :param variables: A list of Variable objects defining the model parameters. :param use_groups_in_sobol: If True, use groups in Sobol analysis.

Returns:: A SALibProblem instance.
Raises:: ValueError – If there are duplicate variable names or if the bounds are not defined.

groups: Dict[str, List[int]] | None = None

names: List[str]

num_vars: int

to_dict() → Dict[str, Any][source]: Convert the SALibProblem instance to a dictionary. :returns: A dictionary representation of the SALib problem.

use_groups_in_sobol: bool = False

using_unit_bounds: bool

class reemission.salib.runners.SobolAnalyser(problem: SALibProblem, variables: List[Variable], model: SALibModelWrapperProtocol, num_samples: int, calc_second_order: bool = True, group_indices: bool = True)[source]

Bases: object

A class to perform Sobol sensitivity analysis using SALib.

problem

A SALibProblem instance defining the problem.

Type:: reemission.salib.runners.SALibProblem

variables

A list of Variable objects defining the model parameters.

Type:: List[reemission.salib.distributions.Variable]

model

A callable model function that takes a list of variables.

Type:: reemission.salib.wrappers.SALibModelWrapperProtocol

num_sampes: Number of samples to generate with Sobol sampling.

calc_second_order

If True, calculates second-order Sobol indices.

Type:: bool

group_indices

If True, groups Sobol indices by variable groups.

Type:: bool

Raises:: ValueError – If the number of variables in the problem does not match the number of variables provided, or if the variable names do not match the names in the problem definition.

Usage:

>>> from utils.salib import SobolAnalyser, SALibProblem
>>> from utils.distributions import Variable, NormalDistribution
>>> problem = SALibProblem.from_variables(
...     variables=[
...         Variable(name='a', distribution=NormalDistribution(mean=0.0, std_dev=1.0)),
...         Variable(name='b', distribution=NormalDistribution(mean=0.0, std_dev=1.0)),
...         Variable(name='c', distribution=DiscreteNormalDistribution(mean=0.0, std_dev=1.0))
...     ]
... )
>>> model = TestModelSALibWrapper.from_variables(problem.variables)
>>> analyser = SobolAnalyser(
...     problem=problem,
...     variables=problem.variables,
...     model=model,
...     num_samples=1000,
...     calc_second_order=True,
...     group_indices=True
... )
>>> sobol_results = analyser.run_sobol_sensitivity()
>>> print(sobol_results)

__post_init__() → None[source]

calc_second_order: bool = True

calculate_grouped_indices(sobol_indices: ResultDict) → Dict[Literal['S1', 'S2', 'ST'], Dict[str, Numerical]][source]

Aggregate Sobol indices by variable groups. If no groups are defined, return the Sobol indices as is. :param sobol_indices: A dictionary containing Sobol indices.

Returns:: A dictionary with aggregated Sobol indices by groups.
Raises:: ValueError – If the sobol_indices do not contain the expected keys.

get_variable(var_name: str) → Variable | None[source]: Get a variable by its name, with memoization.

group_indices: bool = True

model: SALibModelWrapperProtocol

num_samples: int

problem: SALibProblem

run_sobol(fix_variables: bool = False, sobol_index: Literal['S1', 'S2', 'ST'] = 'ST', **kwargs) → SobolResults[source]: Run Sobol sensitivity analysis. :param fix_variables: If True, fix the variables to their nominal values. :param sobol_index: The Sobol index type to use for estimating variance contributions. :param **kwargs: Additional keyword arguments to pass to the Sobol sampling function.

run_sobol_sampling(**kwargs) → ndarray[tuple[Any, ...], dtype[NumpyValue]][source]: Run Sobol sampling to generate input samples.

run_sobol_scenarios(scenarios: Dict[str, Dict[str, Numerical]], pi_bounds: Tuple[float, float] = (0.25, 0.975), sobol_index: Literal['S1', 'S2', 'ST'] = 'ST', **kwargs) → SobolScenarioResults[source]

Run Sobol analysis for multiple scenarios, where each scenario fixes some variables. Returns a dictionary mapping scenario names to SobolResults. :param scenarios: A dictionary where keys are scenario names and values are dictionaries

mapping variable names to fixed values for that scenario.

Parameters:

pi_bounds – A tuple of two floats representing the lower and upper bounds for the percentile interval to calculate the nominal output.
sobol_index – The Sobol index type to use for estimating variance contributions.
**kwargs – Additional keyword arguments to pass to the Sobol sampling function.

variables: List[Variable]

class reemission.salib.runners.SobolBatchAnalyser(problem: SALibProblem, batch_variables: Dict[str, List[Variable]], models: Dict[str, SALibModelWrapperProtocol], num_samples: int, calc_second_order: bool = True, group_indices: bool = True)[source]

Bases: object

A class to perform Sobol sensitivity analysis for a batch of inputs. .. attribute:: problem

A SALibProblem instance defining the problem.

type:

reemission.salib.runners.SALibProblem

batch_variables

A dictionary mapping scenario names to lists of Variable objects defining the model parameters.

Type:: Dict[str, List[reemission.salib.distributions.Variable]]

models

A dictionary mapping scenario names to SALibModelWrapperProtocol instances.

Type:: Dict[str, reemission.salib.wrappers.SALibModelWrapperProtocol]

num_samples

Number of samples to generate with Sobol sampling.

Type:: int

calc_second_order

If True, calculates second-order Sobol indices.

Type:: bool

group_indices

If True, groups Sobol indices by variable groups.

Type:: bool

Raises:: ValueError – If the number of batch variables does not match the number of models, or if the variable names do not match the model names.

__post_init__() → None[source]: Post-initialization to validate the problem and batch variables.

batch_variables: Dict[str, List[Variable]]

calc_second_order: bool = True

group_indices: bool = True

models: Dict[str, SALibModelWrapperProtocol]

num_samples: int

problem: SALibProblem

run_sobol_batch(fix_variables: bool = False, **kwargs) → SobolScenarioResults[source]: Run Sobol sensitivity analysis for a batch of inputs.

class reemission.salib.runners.SobolResults(outputs: NDArray, nominal_output: np.float | np.int, indices: ResultDict, var_names: List[str], fixed_var_names: Optional[List[str]] = None, grouped_indices: Dict[str, ResultDict] = <factory>, variance_contributions: Optional[VarianceContributions] = None)[source]

Bases: object

A class to hold the results of Sobol sensitivity analysis. .. attribute:: outputs

The model outputs for the Sobol samples.

type:

NDArray

nominal_output

The model output for the nominal input.

Type:: np.float | np.int

indices

A dictionary containing Sobol indices (first-order, second-order, total effect).

Type:: ResultDict

var_names

A list of variable names corresponding to the Sobol indices.

Type:: List[str]

grouped_indices

A dictionary containing grouped Sobol indices by variable groups.

Type:: Dict[str, ResultDict]

variance_contributions

Optional VarianceContributions for the total variance and contributions.

Type:: Optional[VarianceContributions]

Raises:: ValueError – If the indices do not contain the expected keys.

Usage:

>>> from utils.salib import SobolResults
>>> from utils.distributions import Variable, NormalDistribution
>>> outputs = np.array([1.0, 2.0, 3.0])
>>> nominal_output = 2.0
>>> indices = {
...     'S1': [0.1, 0.2, 0.3],
...     'S2': [0.05, 0.1, 0.15],
...     'ST': [0.2, 0.3, 0.4]
... }
>>> var_names = ['a', 'b', 'c']
>>> sobol_results = SobolResults(
...     outputs=outputs,
...     nominal_output=nominal_output,
...     indices=indices,
...     var_names=var_names
... )
>>> print(sobol_results.first_order)  # Output: [0.1, 0.2, 0.3]

property first_order: List[Numerical]: Returns the first-order Sobol indices.

fixed_var_names: List[str] | None = None

property fixed_variables: List[str]: Returns the names of fixed variables if any are defined.

grouped_indices: Dict[str, ResultDict]

property groups: List[str]: Return the group names from the first entry in grouped_indices, or an empty list if grouped_indices is empty.

indices: ResultDict

nominal_output: np.float | np.int

outputs: NDArray

property second_order: List[Numerical]: Returns the second-order Sobol indices.

property total_effect: List[Numerical]: Returns the total effect Sobol indices.

var_names: List[str]

variance_contributions: VarianceContributions | None = None

class reemission.salib.runners.SobolScenarioResults(results: List[SobolResults], sc_names: List[str])[source]

Bases: object

A class to hold the results of Sobol sensitivity analysis for multiple scenarios. .. attribute:: results

A list of SobolResults for each scenario.

type:

List[reemission.salib.runners.SobolResults]

sc_names

A list of scenario names.

Type:: List[str]

ix_to_name

A mapping from scenario index to scenario name.

Type:: Dict[int, str]

NOTE: This class is used to hold the results of Sobol sensitivity analysis for multiple scenarios, where each scenario can fix some variables to specific values. It contains a list of SobolResults for each scenario and a list of VarianceContributions for each scenario, which holds the total variance and contributions of each group to the total variance.

__post_init__() → None[source]

property group_names: List[str]: Returns the group names for the Sobol results.

ix_to_name: Dict[int, str]

property nominal_outputs: List[Numerical]: Returns the nominal outputs for each scenario.

results: List[SobolResults]

sc_names: List[str]

property scenario_names: List[str]: Returns the scenario names for the Sobol results.

property var_names: List[str]: Returns the variable names for the scenarios.

property variances: List[VarianceContributions]: Contributions of variable groups to total variance

class reemission.salib.runners.VarianceContributions(sobol_index: Literal['S1', 'S2', 'ST'], total_variance: Numerical, contributions_by_group: Dict[str, Numerical])[source]

Bases: object

A dataclass to hold variances for each scenario storing contributions of variable groups to total variance.

sobol_index

The Sobol index type (e.g., ‘S1’, ‘S2’, ‘ST’) used for estimating variance contributions to total variance from each variable group.

Type:: Literal[‘S1’, ‘S2’, ‘ST’]

total_variance

The total variance of the output for this scenario.

Type:: reemission.salib.runners.Numerical

contributions_by_group

A dictionary mapping group names to their contributions to the total variance.

Type:: Dict[str, reemission.salib.runners.Numerical]

__post_init__() → None[source]: Post-initialization to validate the Sobol index. :raises ValueError: If the Sobol index is not one of the supported indices (‘S1’, ‘S2’, ‘ST’).

contributions_by_group: Dict[str, Numerical]

sobol_index: Literal['S1', 'S2', 'ST']

to_dict() → Dict[str, Any][source]: Convert the VarianceContributions instance to a dictionary.

total_variance: Numerical

reemission.salib.runners.transform_uniform(uniform_samples: ndarray[tuple[Any, ...], dtype[NumpyValue]], variables: List[Variable], eps: float = 1e-06) → ndarray[tuple[Any, ...], dtype[NumpyValue]][source]

Transforms uniform samples U to the distributions defined by the variables. :param uniform_samples: NDArray of uniform samples, shape (num_samples, num_variables) :param variables: List of Variable objects defining the distributions. :param eps: Small value to prevent numerical issues when transforming uniform samples.

Returns:: NDArray of transformed samples, shape (num_samples, num_variables).

Note

Variables in the variables list must be in the same order as the columns in uniform_samples.

Raises:

TypeError – If uniform_samples is not a numpy ndarray.
ValueError – If uniform_samples is not a 2D array or if the number of variables does not match the shape of uniform_samples.
ValueError – If variables list is empty or contains non-Variable objects.
ValueError – If a variable’s distribution type is not supported.

Functions

transform_uniform(uniform_samples, variables)

Transforms uniform samples U to the distributions defined by the variables.

Classes

`SALibProblem`(names, bounds, float]] =, ...)	A dataclass to represent a SALib problem definition and construct SALib problem dictionary.
`SobolAnalyser`(problem, variables, model, ...)	A class to perform Sobol sensitivity analysis using SALib.
`SobolBatchAnalyser`(problem, batch_variables, ...)	A class to perform Sobol sensitivity analysis for a batch of inputs.
`SobolResults`(outputs, nominal_output, ...)	A class to hold the results of Sobol sensitivity analysis.
`SobolScenarioResults`(results, sc_names)	A class to hold the results of Sobol sensitivity analysis for multiple scenarios.
`VarianceContributions`(sobol_index, ...)	A dataclass to hold variances for each scenario storing contributions of variable groups to total variance.

reemission.salib.montecarlo

reemission.salib.visualize