pyuncertainnumber.propagation.uncertaintyPropagation¶

Functions¶

`aleatory_propagation`([vars, results, func, n_sam, ...])	This function propagates aleatory uncertainty through a given function (func) using either Monte Carlo or Latin Hypercube sampling, considering the aleatory uncertainty represented by a list of UncertainNumber objects (vars).
`mixed_propagation`(vars[, func, results, method, ...])	Performs mixed uncertainty propagation through a given function. This function handles uncertainty propagation when there's a mix of
`epistemic_propagation`(vars, func[, method, ...])	Performs epistemic uncertainty propagation through a given function. This function implements various methods for propagating epistemic uncertainty,
`Propagation`(vars, func[, results, n_sub, n_sam, x0, ...])	Performs uncertainty propagation through a given function with uncertain inputs. This function automatically selects and executes an appropriate uncertainty propagation method based on the types of uncertainty in the input variables. It supports interval analysis, probabilistic methods, and mixed uncertainty propagation.
`plotPbox`(xL, xR[, p])	Plots a p-box (probability box) using matplotlib.
`main`()	implementation of any method for epistemic uncertainty on the cantilever beam example

Module Contents¶

pyuncertainnumber.propagation.uncertaintyPropagation.aleatory_propagation(vars: list = None, results: pyuncertainnumber.propagation.utils.Propagation_results = None, func: Callable = None, n_sam: int = 500, method: str = 'monte_carlo', save_raw_data=False, *, base_path=np.nan, **kwargs)¶

This function propagates aleatory uncertainty through a given function (func) using either Monte Carlo or Latin Hypercube sampling, considering the aleatory uncertainty represented by a list of UncertainNumber objects (vars). :param - vars: A list of UncertainNumber objects, each representing an input

variable with its associated uncertainty.

Parameters:

func (-) – The function to propagate uncertainty through.
n_sam (-) – The number of samples to generate. Default is 500.
method (-) – The sampling method (‘monte_carlo’ or ‘latin_hypercube’). Defaults to ‘monte_carlo’.
save_raw_data (-) – Whether to save raw data (‘yes’ or ‘no’). Defaults to ‘no’.
base_path (-) – Path for saving results (if save_raw_data is ‘yes’). Defaults to np.nan.
**kwargs (-) –
Additional keyword arguments to be passed to the UncertainNumber constructor.

signature:: aleatory_propagation(x:np.ndarray, f:Callable, n:int, …) -> Propagation_results

Note

If the f function returns multiple outputs, the all_output array will be 2-dimensional y and x for all x samples.

Returns:

A Propagation_results object containing:

’un’: A list of UncertainNumber objects, each representing
the output(s) of the function.
’raw_data’: A dictionary containing raw data (if
save_raw_data is ‘yes’):
’x’: All generated input samples.

’f’: Corresponding output values for each
input sample.

Return type:

Propagation_results

Raises:

ValueError – For invalid method, save_raw_data, or missing arguments.

pyuncertainnumber.propagation.uncertaintyPropagation.mixed_propagation(vars: list, func: Callable = None, results: pyuncertainnumber.propagation.utils.Propagation_results = None, method='second_order_extremepoints', n_disc: int | numpy.ndarray = 10, condensation: int = None, tOp: float | numpy.ndarray = 0.999, bOt: float | numpy.ndarray = 0.001, save_raw_data='no', *, base_path=np.nan, **kwargs)¶

Performs mixed uncertainty propagation through a given function. This function handles uncertainty propagation when there’s a mix of: aleatory and epistemic uncertainty in the input variables.

Parameters:

vars (-) – A list of uncertain variables, which can be a mix of different uncertainty types (e.g., intervals, distributions).
func (-) – The function to propagate uncertainty through.
results (-) – An object to store propagation results. Defaults to None, in which case a new Propagation_results object is created.
method (-) – The mixed uncertainty propagation method. Can be one of: ‘second_order_endpoints’, ‘second_order_vertex’, ‘second_order_extremepoints’, ‘first_order_extremepoints’. Defaults to ‘second_order_extremepoints’.
n_disc (-) – Number of discretization points for interval variables. Defaults to 10.
condensation (-) – Parameter for reducing the complexity of the output uncertainty representation. Defaults to None.
tOp (-) – Upper threshold or bound used in some methods. Defaults to 0.999.
bOt (-) – Lower threshold or bound used in some methods. Defaults to 0.001.
save_raw_data (-) – Whether to save raw data (‘yes’ or ‘no’). Defaults to ‘no’.
base_path (-) – Path for saving results (if save_raw_data is ‘yes’). Defaults to np.nan.
**kwargs (-) –
Additional keyword arguments passed to the underlying propagation methods.

signature:: mixed_propagation(vars: list, func: Callable, results: Propagation_results = None, …) -> Propagation_results

Notes

It can be used if each uncertain number is exrpessed in terms of precise distributions.

Returns:

A Propagation_results object containing the results of: the mixed uncertainty propagation. The format of the results depends on the chosen method.

Return type:

Propagation_results

Raises:

ValueError – For invalid method or save_raw_data.

Examples

>>> a = mixed_propagation(vars= [y, L, I, F, E],
                    func= cantilever_beam_func,
                    method= 'second_order_extremepoints',
                    n_disc=8,
                    #save_raw_data= "no"#,
                    save_raw_data= "yes",
                    base_path= base_path
                )

pyuncertainnumber.propagation.uncertaintyPropagation.epistemic_propagation(vars, func, method: str = None, save_raw_data=False, *, results: pyuncertainnumber.propagation.utils.Propagation_results = None, n_sub: numpy.integer = None, n_sam: numpy.integer = None, x0: numpy.ndarray = None, base_path=np.nan, tol_loc: numpy.ndarray = None, options_loc: dict = None, method_loc='Nelder-Mead', pop_size=1000, n_gen=100, tol=0.001, n_gen_last=10, algorithm_type='NSGA2', **kwargs)¶

Performs epistemic uncertainty propagation through a given function. This function implements various methods for propagating epistemic uncertainty,: typically represented as intervals.

Parameters:

vars (-) – A list of UncertainNumber objects representing the input variables with their associated interval uncertainty.
func (-) – The function to propagate uncertainty through.
results (-) – An object to store propagation results. Defaults to None, in which case a new Propagation_results object is created.
n_sub (-) – Number of subintervals for subinterval methods. Defaults to None.
n_sam (-) – Number of samples for sampling-based methods. Defaults to None.
x0 (-) – Initial guess for local optimization methods. Defaults to None.
method (-) – The uncertainty propagation method to use. Defaults to “endpoint”.
save_raw_data (-) – Whether to save raw data (‘yes’ or ‘no’). Defaults to “no”.
base_path (-) – Path for saving results (if save_raw_data is ‘yes’). Defaults to np.nan.
tol_loc (-) – Tolerance for local optimization. Defaults to None.
options_loc (-) – Options for local optimization. Defaults to None.
method_loc (-) – Method for local optimization. Defaults to ‘Nelder-Mead’.
pop_size (-) – Population size for genetic algorithms. Defaults to 1000.
n_gen (-) – Number of generations for genetic algorithms. Defaults to 100.
tol (-) – Tolerance for genetic algorithms. Defaults to 1e-3.
n_gen_last (-) – Number of last generations for genetic algorithms. Defaults to 10.
algorithm_type (-) – Type of genetic algorithm. Defaults to ‘NSGA2’.
**kwargs (-) –
Additional keyword arguments passed to the UncertainNumber constructor.

signature:: epistemic_propagation(vars: list, func: Callable, results: Propagation_results = None, …) -> Propagation_results

Notes

It supports a wide range of techniques, including:
1. Interval-based methods:
  
  endpoints or vertex: Calculates the function output at the endpoints
  or vertices of the input intervals.
  
  extremepoints: Considers all possible combinations of interval endpoints
  to find the extreme values of the output.
  
  subinterval or subinterval_reconstitution: Divides the input intervals
  into subintervals and performs propagation on each subinterval.
2. Sampling-based methods:
  
  monte_carlo, latin_hypercube: Uses Monte Carlo or Latin Hypercube
  sampling within the input intervals.
  
  monte_carlo_endpoints, latin_hypercube_endpoints: Combines sampling with
  evaluation at interval endpoints.
  
  cauchy, endpoint_cauchy, endpoints_cauchy: Uses Cauchy deviates for
  sampling.
3. Optimization-based methods:
  
  local_optimization or local_optimisation: Uses local optimization
  algorithms to find the minimum or maximum output values.
  
  genetic_optimisation or genetic_optimization: Uses genetic algorithms for
  global optimization.

Returns:

A Propagation_results object containing the results of: the epistemic uncertainty propagation. The format of the results depends on the chosen method.

Return type:

Propagation_results

Raises:

- ValueError – For invalid method, save_raw_data, or missing arguments.
- TypeError – If func is not callable for optimization methods.

Example

>>> a = epistemic_propagation(vars= [ y, L, I, F, E],
                        func= cantilever_beam_func,
                        method= 'extremepoints',
                        n_disc=8,
                        save_raw_data= "no"
                    )

pyuncertainnumber.propagation.uncertaintyPropagation.Propagation(vars: list, func: Callable, results: pyuncertainnumber.propagation.utils.Propagation_results = None, n_sub: numpy.integer = 3, n_sam: numpy.integer = 500, x0: numpy.ndarray = None, method=None, n_disc: int | numpy.ndarray = 10, condensation: int = None, tOp: float | numpy.ndarray = 0.999, bOt: float | numpy.ndarray = 0.001, save_raw_data='no', *, base_path=np.nan, tol_loc: numpy.ndarray = None, options_loc: dict = None, method_loc='Nelder-Mead', pop_size=1000, n_gen=100, tol=0.001, n_gen_last=10, algorithm_type='NSGA2', **kwargs)¶

Performs uncertainty propagation through a given function with uncertain inputs. This function automatically selects and executes an appropriate uncertainty propagation method based on the types of uncertainty in the input variables. It supports interval analysis, probabilistic methods, and mixed uncertainty propagation.

Parameters:

vars (-) – A list of uncertain variables.
func (-) – The function through which to propagate uncertainty.
results (-) – An object to store propagation results. Defaults to None, in which case a new Propagation_results object is created.
n_sub (-) – Number of subintervals for interval-based methods. Defaults to 3.
n_sam (-) – Number of samples for Monte Carlo simulation. Defaults to 500.
x0 (-) – Initial guess for optimization-based methods. Defaults to None.
method (-) – Specifies the uncertainty propagation method. Defaults to None, which triggers automatic selection.
n_disc (-) – Number of discretization points. Defaults to 10.
condensation (-) – Parameter for reducing output complexity. Defaults to None.
tOp (-) – Upper threshold or bound. Defaults to 0.999.
bOt (-) – Lower threshold or bound. Defaults to 0.001.
save_raw_data (-) – Whether to save intermediate results (‘yes’ or ‘no’). Defaults to ‘no’.
base_path (-) – Path for saving data. Defaults to np.nan.
tol_loc (-) – Tolerance for local optimization. Defaults to None.
options_loc (-) – Options for local optimization. Defaults to None.
method_loc (-) – Method for local optimization. Defaults to ‘Nelder-Mead’.
pop_size (-) – Population size for genetic algorithms. Defaults to 1000.
n_gen (-) – Number of generations for genetic algorithms. Defaults to 100.
tol (-) – Tolerance for genetic algorithms. Defaults to 1e-3.
n_gen_last (-) – Number of last generations for genetic algorithms. Defaults to 10.
algorithm_type (-) – Type of genetic algorithm. Defaults to ‘NSGA2’.
**kwargs – Additional keyword arguments passed to the underlying propagation methods.

signature:

Propagation(vars: list, func: Callable, results: Propagation_results = None, …) -> Propagation_results

Returns:

A Propagation_results object including:

’un’: A list of UncertainNumber objects, each representing
the output(s) of the function.
’raw_data’: depending on the method selected.

Return type:

Propagation_results

Example

>>> a = Propagation(vars= [ y, L, I, F, E],
                    func= cantilever_beam_func,
                    method= 'extremepoints',
                    n_disc=8,
                    save_raw_data= "no"
                )

pyuncertainnumber.propagation.uncertaintyPropagation.plotPbox(xL, xR, p=None)¶

Plots a p-box (probability box) using matplotlib.

Parameters:

xL (np.ndarray) – A 1D NumPy array of lower bounds.
xR (np.ndarray) – A 1D NumPy array of upper bounds.
p (np.ndarray, optional) – A 1D NumPy array of probabilities corresponding to the intervals. Defaults to None, which generates equally spaced probabilities.
color (str, optional) – The color of the plot. Defaults to ‘k’ (black).

pyuncertainnumber.propagation.uncertaintyPropagation.main()¶: implementation of any method for epistemic uncertainty on the cantilever beam example