pyuncertainnumber.propagation.p =============================== .. py:module:: pyuncertainnumber.propagation.p Classes ------- .. autoapisummary:: pyuncertainnumber.propagation.p.P pyuncertainnumber.propagation.p.AleatoryPropagation pyuncertainnumber.propagation.p.EpistemicPropagation pyuncertainnumber.propagation.p.MixedPropagation pyuncertainnumber.propagation.p.Propagation Module Contents --------------- .. py:class:: P(vars, func, method, dependency=None) Bases: :py:obj:`abc.ABC` Base class blueprint. Not for direct use .. py:attribute:: _vars .. py:attribute:: func .. py:attribute:: method .. py:attribute:: dependency :value: None .. py:method:: post_init_check() some checks .. py:method:: type_check() :abstractmethod: if the nature of the UN suitable for the method .. py:method:: method_check() :abstractmethod: if the method is suitable for the nature of the UN .. py:class:: AleatoryPropagation(vars, func, method, dependency=None) Bases: :py:obj:`P` Aleatoric uncertainty propagation class for Distribution constructs only :param vars: a list of uncertain numbers objects :type vars: Distribution :param func: the response or performance function applied to the uncertain numbers :type func: callable :param method: a string indicating the method to be used for propagation. :type method: str :param dependency: a Dependency object(i.e. a copula function) to model the dependency structure among input variables. Strings such as "independence" accepted for independence. :type dependency: string or Dependency .. note:: Supported methods include "monte_carlo". Note that "taylor_expansion" is not supported herein but implemented as a standalone function in the module `taylor_expansion.py`. .. caution:: This function supports with low-level constructs NOT the high-level `UN` (uncertain number) objects. For `UN` objects, use `Propagation` class as an high-level API. .. seealso:: :func:`Propagation` : the high-level API for uncertain number propagation. .. rubric:: Example >>> from pyuncertainnumber import pba >>> from pyuncertainnumber.propagation.p import AleatoryPropagation >>> def foo(x): return x[0] ** 3 + x[1] + x[2] >>> a_d = pba.Distribution('gaussian', (3,1)) >>> b_d = pba.Distribution('gaussian', (10, 1)) >>> c_d = pba.Distribution('uniform', (5, 10)) >>> aleatory = AleatoryPropagation(vars=[a_d, b_d, c_d], func=foo, method='monte_carlo') >>> result = aleatory(n_sam=1000) .. py:method:: type_check() only distributions .. py:method:: method_check() if the method is suitable for the nature of the UN .. py:method:: run(n_sam: int = 1000) doing the propagation .. py:class:: EpistemicPropagation(vars, func, method) Bases: :py:obj:`P` Epistemic uncertainty propagation class for construct :param vars: a list of interval objects :type vars: Interval :param func: the response or performance function applied to the uncertain numbers :type func: callable :param method: a string indicating the method to be used for propagation :type method: str :param interval_strategy: a strategy for interval propagation, including {'endpoints', 'subinterval'} :type interval_strategy: str .. caution:: This function supports with low-level constructs NOT the high-level `UN` (uncertain number) objects. For `UN` objects, use `Propagation` class as an high-level API. .. seealso:: :func:`Propagation` : the high-level API for uncertain number propagation. .. rubric:: Example >>> from pyuncertainnumber import pba >>> from pyuncertainnumber.propagation.p import EpistemicPropagation >>> def foo(x): return x[0] ** 3 + x[1] + x[2] >>> a = pba.I(1, 5) >>> b = pba.I(7, 13) >>> c = pba.I(5, 10) >>> ep = EpistemicPropagation(vars=[a,b,c], func=foo, method='subinterval') >>> result = ep(n_sub=20, style='endpoints') .. py:method:: type_check() only intervals .. py:method:: method_check() if the method is suitable for the nature of the UN .. py:method:: run(**kwargs) doing the propagation .. py:class:: MixedPropagation(vars, func, method, dependency=None, interval_strategy=None) Bases: :py:obj:`P` Mixed uncertainty propagation class for construct :param vars: a list of uncertain numbers objects :type vars: Pbox or DempsterShafer :param func: the response or performance function applied to the uncertain numbers :type func: callable :param method: a string indicating the method to be used for pbox propagation, including {'interval_monte_carlo', 'slicing', 'double_monte_carlo'}. :type method: str :param dependency: a Dependency object(i.e. a copula function) to model the dependency structure among input variables. Strings such as "independence" accepted for independence. :type dependency: string or Dependency :param interval_strategy: a sub-level strategy selector for interval propagation, including {'direct', 'subinterval', 'endpoints'}. :type interval_strategy: str .. caution:: This function supports with low-level constructs NOT the high-level `UN` (uncertain number) objects. For `UN` objects, use `Propagation` class as an high-level API. .. seealso:: :func:`Propagation` : the high-level API for uncertain number propagation. .. warning:: The computation cost increases exponentially with the number of input variables and the number of slices. Be cautious with the choice of number of slices ``n_slices`` given the number of input variables ``vars`` of the response function. .. note:: Discussion of the methods and strategies. When choosing ``interval_strategy``, "direct" requires function signature to take a list of inputs, whereas "subinterval" and "endpoints" require the function to take a vectorised signature. Currently, only "interval_monte_carlo" supports with dependency structures (e.g. copulas). When calling the `run` function to do propagation, extra keyword arguments are needed to be passed down to the selected `method`. For example, `n_sam` for "interval_monte_carlo"; `n_slices` for "slicing"; `n_outer`, `n_inner` for "double_monte_carlo". .. rubric:: Example >>> from pyuncertainnumber import pba >>> from pyuncertainnumber.propagation.p import MixedPropagation >>> def foo(x): return x[0] ** 3 + x[1] + x[2] >>> a = pba.normal([2, 3], [1]) >>> b = pba.normal([10, 14], [1]) >>> c = pba.normal([4, 5], [1]) >>> mix = MixedPropagation(vars=[a,b,c], func=foo, method='slicing', interval_strategy='subinterval') >>> result = mix.run(n_slices=20, n_sub=2, style='endpoints') .. py:attribute:: interval_strategy :value: None .. py:method:: type_check() Inspection if inputs are mixed uncertainy model .. py:method:: method_check() Check if the method is suitable for mixed uncertainty propagation .. py:method:: run(**kwargs) doing the propagation. Extra keyword are needed to be passed down to the selected `method` .. py:class:: Propagation(vars: list[pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber], func: callable, method: str, dependency: str | pyuncertainnumber.pba.dependency.Dependency = None, interval_strategy: str = None) High-level integrated class for the propagation of uncertain numbers :param vars: a list of uncertain numbers objects :type vars: UncertainNumber :param func: the response or performance function applied to the uncertain numbers :type func: Callable :param method: a string indicating the method to be used for propagation (e.g. "monte_carlo", "endpoint", etc.) which may depend on the constructs of the uncertain numbers. See notes about function signature. :type method: str :param dependency: a Dependency object(i.e. a copula function) to model the dependency structure among input variables. Strings such as "independence" accepted for independence. :type dependency: string or Dependency :param interval_strategy: a strategy for interval propagation, including {'direct', 'subinterval', 'endpoints'} which will affect the function signature of the response function. See notes about function signature. :type interval_strategy: str .. caution:: This class supports with high-level computation with `UncertainNumber` objects. .. note:: Discussion of the methods and strategies. When choosing ``interval_strategy``, "direct" requires function signature to take a list of inputs, whereas "subinterval" and "endpoints" require the function to take a vectorised signature. .. warning:: The computation cost increases exponentially with the number of input variables and the number of slices. Be cautious with the choice of number of slices ``n_slices`` given the number of input variables ``vars`` of the response function. .. rubric:: Example >>> import pyuncertainnumber as pun >>> # construction of uncertain number objects >>> a = pun.I(2, 3) >>> b = pun.normal(4, 1) >>> c = pun.uniform([4,5], [9,10]) >>> # vectorised function signature with matrix input (2D np.ndarray) >>> def foo_vec(x): return x[:, 0] ** 3 + x[:, 1] + x[:, 2] >>> # high-level propagation API >>> p = Propagation(vars=[a,b,c], >>> func=foo, >>> method='slicing', >>> interval_strategy='subinterval' >>> ) >>> # heavy-lifting of propagation >>> t = p.run(n_sam=20, n_sub=2, style='endpoints') .. py:attribute:: _vars .. py:attribute:: _func .. py:attribute:: method .. py:attribute:: dependency :value: None .. py:attribute:: interval_strategy :value: None .. py:method:: _post_init_check() Some checks after initialisation .. py:method:: assign_method() Assign the propagation method based on the essence of constructs .. py:property:: constructs return the underlying constructs .. py:method:: run(**kwargs) Doing the propagation and return UN :returns: the result of the propagation as an uncertain number object :rtype: UncertainNumber