Merge pull request #224 from SURGroup/feature/documentation_improvements

Feature/documentation improvements

README.rst

@@ -6,8 +6,6 @@
 .. |AzureDevops| image:: https://img.shields.io/azure-devops/build/UQpy/5ce1851f-e51f-4e18-9eca-91c3ad9f9900/1?style=plastic   :alt: Azure DevOps builds
 .. |PyPIdownloads| image:: https://img.shields.io/pypi/dm/UQpy?style=plastic   :alt: PyPI - Downloads
 .. |PyPI| image:: https://img.shields.io/pypi/v/UQpy?style=plastic   :alt: PyPI
-.. |Binder| image:: https://mybinder.org/badge_logo.svg
- :target: https://mybinder.org/v2/gh/SURGroup/UQpy/master
 
 .. |bear-ified| image:: https://raw.githubusercontent.com/beartype/beartype-assets/main/badge/bear-ified.svg
    :align: top
@@ -32,7 +30,7 @@ Uncertainty Quantification with python (UQpy)
 +                       +                                                                  +
 |                       | Ketson RM dos Santos, Katiana Kontolati, Dimitris Loukrezis,     |
 +                       +                                                                  +
-|                       | Promit Chakroborty, Lukáš Novák, Andrew Solanto                  |
+|                       | Promit Chakroborty, Lukáš Novák, Andrew Solanto, Connor Krill    |
 +-----------------------+------------------------------------------------------------------+
 | **Contributors:**     | Michael Gardner, Prateek Bhustali, Julius Schultz, Ulrich Römer  |
 +-----------------------+------------------------------------------------------------------+

docs/code/reliability/form/FORM_linear_function_3d.py

@@ -35,13 +35,13 @@
 dist3 = Normal(loc=4., scale=0.4)
 
 model = PythonModel(model_script='local_pfn.py', model_object_name="example3",)
-RunModelObject3 = RunModel(model=model)
+run_model = RunModel(model=model)
 
-Z0 = FORM(distributions=[dist1, dist2, dist3], runmodel_object=RunModelObject3)
-Z0.run()
+form = FORM(distributions=[dist1, dist2, dist3], runmodel_object=run_model)
+form.run()
 
-print('Design point in standard normal space: %s' % Z0.design_point_u)
-print('Design point in original space: %s' % Z0.design_point_x)
-print('Hasofer-Lind reliability index: %s' % Z0.beta)
-print('FORM probability of failure: %s' % Z0.failure_probability)
+print('Design point in standard normal space: %s' % form.design_point_u)
+print('Design point in original space: %s' % form.design_point_x)
+print('Hasofer-Lind reliability index: %s' % form.beta)
+print('FORM probability of failure: %s' % form.failure_probability)
 

docs/code/reliability/sorm/SORM_nonlinear_function.py

@@ -34,13 +34,13 @@
 
 dist1 = Normal(loc=20., scale=2)
 dist2 = Lognormal(s=s, loc=0.0, scale=scale)
-model = PythonModel(model_script='local_pfn.py', model_object_name="example4",)
+model = PythonModel(model_script='local_model4.py', model_object_name="example4")
 RunModelObject4 = RunModel(model=model)
 form = FORM(distributions=[dist1, dist2], runmodel_object=RunModelObject4)
 form.run()
-Q0 = SORM(form_object=form)
+sorm = SORM(form_object=form)
 
 
 # print results
-print('SORM probability of failure: %s' % Q0.failure_probability)
+print('SORM probability of failure: %s' % sorm.failure_probability)
 

docs/code/reliability/sorm/local_model4.py

@@ -0,0 +1,8 @@
+import numpy as np
+
+
+def example4(samples=None):
+    g = np.zeros(samples.shape[0])
+    for i in range(samples.shape[0]):
+        g[i] = samples[i, 0] * samples[i, 1] - 80
+    return g

docs/code/reliability/sorm/local_pfn.py

@@ -6,33 +6,31 @@
 """
 import numpy as np
 
+
 def example1(samples=None):
     g = np.zeros(samples.shape[0])
-    for i in range(samples.shape[0]):         
+    for i in range(samples.shape[0]):
         R = samples[i, 0]
         S = samples[i, 1]
         g[i] = R - S
     return g
-    
+
 
 def example2(samples=None):
     import numpy as np
     d = 2
     beta = 3.0902
     g = np.zeros(samples.shape[0])
     for i in range(samples.shape[0]):
-        g[i] = -1/np.sqrt(d) * (samples[i, 0] + samples[i, 1]) + beta
+        g[i] = -1 / np.sqrt(d) * (samples[i, 0] + samples[i, 1]) + beta
     return g
 
 
 def example3(samples=None):
     g = np.zeros(samples.shape[0])
     for i in range(samples.shape[0]):
-        g[i] = 6.2*samples[i, 0] - samples[i, 1]*samples[i, 2]**2
+        g[i] = 6.2 * samples[i, 0] - samples[i, 1] * samples[i, 2] ** 2
     return g
-
-def example4(samples=None):
-    g = np.zeros(samples.shape[0])
-    for i in range(samples.shape[0]):
-        g[i] = samples[i, 0]*samples[i, 1] - 80
-    return g
+
+
+

docs/code/surrogates/pce/plot_pce_sparsity_lars.py

@@ -15,16 +15,16 @@
 # %%
 
 import numpy as np
-import math
-import numpy as np
+
 from UQpy.distributions import Uniform, JointIndependent
 from UQpy.surrogates import *
 
 
 # %% md
 #
 # We then define the Ishigami function, which reads:
-# :math:` f(x_1, x_2, x_3) = \sin(x_1) + a \sin^2(x_2) + b x_3^4 \sin(x_1)`
+#
+# .. math:: f(x_1, x_2, x_3) = \sin(x_1) + a \sin^2(x_2) + b x_3^4 \sin(x_1)
 
 # %%
 
@@ -41,7 +41,7 @@ def ishigami(xx):
 
 # %% md
 #
-# The Ishigami function has three indepdent random inputs, which are uniformly distributed in
+# The Ishigami function has three independent random inputs, which are uniformly distributed in
 # interval :math:`[-\pi, \pi]`.
 
 # %%
@@ -70,7 +70,7 @@ def ishigami(xx):
 #
 # where :math:`N` is the number of random inputs (here, :math:`N=3`).
 #
-# Note that the size of the basis is highly dependent both on :math:`N` and :math:`P:math:`. It is generally advisable
+# Note that the size of the basis is highly dependent both on :math:`N` and :math:`P`. It is generally advisable
 # that the experimental design has :math:`2-10` times more data points than the number of PCE polynomials. This might
 # lead to curse of dimensionality and thus we will utilize the best model selection algorithm based on
 # Least Angle Regression.
@@ -102,8 +102,8 @@ def ishigami(xx):
 
 # %% md
 #
-# We now fit the PCE coefficients by solving a regression problem. Here we opt for the _np.linalg.lstsq_ method,
-# which is based on the _dgelsd_ solver of LAPACK. This original PCE class will be used for further selection of
+# We now fit the PCE coefficients by solving a regression problem. Here we opt for the :code:`_np.linalg.lstsq_` method,
+# which is based on the :code:`_dgelsd_` solver of LAPACK. This original PCE class will be used for further selection of
 # the best basis functions.
 
 # %%
@@ -238,7 +238,7 @@ def ishigami(xx):
 # %% md
 #
 # In case of high-dimensional input and/or high :math:P` it is also beneficial to reduce the TD basis set by hyperbolic
-# trunction. The hyperbolic truncation reduces higher-order interaction terms in dependence to parameter :math:`q` in
+# truncation. The hyperbolic truncation reduces higher-order interaction terms in dependence to parameter :math:`q` in
 # interval :math:`(0,1)`. The set of multi indices :math:`\alpha` is reduced as follows:
 #
 # :math:`\alpha\in \mathbb{N}^{N}: || \boldsymbol{\alpha}||_q \equiv \Big( \sum_{i=1}^{N} \alpha_i^q \Big)^{1/q} \leq P`

docs/source/index.rst

@@ -18,7 +18,7 @@ as a set of modules centered around core capabilities in Uncertainty Quantificat
 +                       +                                                                  +
 |                       | Ketson RM dos Santos, Katiana Kontolati, Dimitris Loukrezis,     |
 +                       +                                                                  +
-|                       | Promit Chakroborty, Lukáš Novák, Andrew Solanto                  |
+|                       | Promit Chakroborty, Lukáš Novák, Andrew Solanto, Connor Krill    |
 +-----------------------+------------------------------------------------------------------+
 | **Contributors:**     | Michael Gardner, Prateek Bhustali, Julius Schultz, Ulrich Römer  |
 +-----------------------+------------------------------------------------------------------+

docs/source/reliability/index.rst

@@ -2,19 +2,20 @@ Reliability
 ===========
 
 Reliability of a system refers to the assessment of its probability of failure (i.e the system no longer satisfies some
-performance measures), given the model uncertainty in the structural, environmental and load parameters. Given a vector
-of random variables :math:`\textbf{X}=\{X_1, X_2, \ldots, X_n\} \in \mathcal{D}_\textbf{X}\subset \mathbb{R}^n`, where
-:math:`\mathcal{D}` is the domain of interest and :math:`f_{\textbf{X}}(\textbf{x})` is its joint probability density
-function then, the probability that the system will fail is defined as
+performance measure), given the model uncertainty in the structural, environmental and load parameters. Given a vector
+of random variables :math:`\textbf{X}=[X_1, X_2, \ldots, X_n]^T \in \mathcal{D}_\textbf{X}\subset \mathbb{R}^n`, where
+:math:`\mathcal{D}_\textbf{X}` is the domain of interest and :math:`f_{\textbf{X}}(\textbf{x})` is its joint probability density
+function, then the probability that the system will fail is defined as
 
 
-.. math:: P_f =\mathbb{P}(g(\textbf{X}) \leq 0) = \int_{D_f} f_{\textbf{X}}(\textbf{x})d\textbf{x} = \int_{\{\textbf{X}:g(\textbf{X})\leq 0 \}} f_{\textbf{X}}(\textbf{x})d\textbf{x}
+.. math:: P_f =\mathbb{P}(g(\textbf{X}) \leq 0) = \int_{\mathcal{D}_f} f_{\textbf{X}}(\textbf{x})d\textbf{x} = \int_{\{\textbf{X}:g(\textbf{X})\leq 0 \}} f_{\textbf{X}}(\textbf{x})d\textbf{x}
 
 
-where :math:`g(\textbf{X})` is the so-called performance function. The reliability problem is often formulated in the
+where :math:`g(\textbf{X})` is the so-called performance function and :math:`\mathcal{D}_f=\{\textbf{X}:g(\textbf{X})\leq 0 \}` is the failure domain.
+The reliability problem is often formulated in the
 standard normal space :math:`\textbf{U}\sim \mathcal{N}(\textbf{0}, \textbf{I}_n)`, which means that a nonlinear
 isoprobabilistic  transformation from the generally non-normal parameter space
-:math:`\textbf{X}\sim f_{\textbf{X}}(\cdot)` to the standard normal is required (see the :py:mod:`.transformations` module).
+:math:`\textbf{X}\sim f_{\textbf{X}}(\cdot)` to the standard normal space is required (see the :py:mod:`.transformations` module).
 The performance function in the standard normal space is denoted :math:`G(\textbf{U})`. :py:mod:`.UQpy` does not require this
 transformation and can support reliability analysis for problems with arbitrarily distributed parameters.
 

docs/source/reliability/subset.rst

@@ -2,48 +2,46 @@ Subset Simulation
 -------------------
 
 In the subset simulation method :cite:`SubsetSimulation` the probability of failure :math:`P_f`  is approximated by a product of probabilities
-of more frequent events. That is, the failure event :math:`G = \{\textbf{x} \in \mathbb{R}^n:G(\textbf{x}) \leq 0\}`,
+of more frequent events. That is, the failure event :math:`G = \{\textbf{X} \in \mathbb{R}^n:g(\textbf{X}) \leq 0\}`,
 is expressed as the of union of `M` nested intermediate events :math:`G_1,G_2,\cdots,G_M` such that
 :math:`G_1 \supset G_2 \supset \cdots \supset G_M`, and :math:`G = \cap_{i=1}^{M} G_i`. The intermediate failure events
-are defined as :math:`G_i=\{G(\textbf{x})\le b_i\}`, where :math:`b_1>b_2>\cdots>b_i=0` are positive thresholds selected
-such that each conditional probability :math:`P(G_i | G_{i-1}), ~i=2,3,\cdots,M-1` equals a target probability value
+are defined as :math:`G_i=\{g(\textbf{X})\le b_i\}`, where :math:`b_1>b_2>\cdots>b_M=0` are non-negative thresholds selected
+such that each conditional probability :math:`P(G_{i+1} | G_{i}),\ i=1,2,\cdots,M-1` equals a target probability value
 :math:`p_0`. The probability of failure :math:`P_f` is estimated as:
 
-.. math:: P_f = P\left(\cap_{i=1}^M G_i\right) = P(G_1)\prod_{i=2}^M P(G_i | G_{i-1})
+.. math:: P_f = P\left(\bigcap_{i=1}^M G_i\right) = P(G_1)\prod_{i=1}^{M-1} P(G_{i+1} | G_{i})
 
 where the probability :math:`P(G_1)` is computed through Monte Carlo simulations. In order to estimate the conditional
-probabilities :math:`P(G_i|G_{i-1}),~j=2,3,\cdots,M` generation of Markov Chain Monte Carlo (MCMC) samples from the
-conditional pdf :math:`p_{\textbf{U}}(\textbf{u}|G_{i-1})` is required. In the context of subset simulation, the Markov
+probabilities :math:`P(G_{i+1}|G_i),~i=1,2,\cdots,M-1` generation of Markov Chain Monte Carlo (MCMC) samples from the
+conditional pdf :math:`p_{\textbf{X}}(\textbf{x}|G_i)` is required. In the context of subset simulation, the Markov
 chains are constructed through a two-step acceptance/rejection criterion. Starting from a Markov chain state
-:math:`\textbf{x}` and a proposal distribution :math:`q(\cdot|\textbf{x})`, a candidate sample :math:`\textbf{w}` is
-generated. In the first stage, the sample :math:`\textbf{w}` is accepted/rejected with probability
+:math:`\textbf{X}` and a proposal distribution :math:`q(\cdot|\textbf{X})`, a candidate sample :math:`\textbf{W}` is
+generated. In the first stage, the sample :math:`\textbf{W}` is accepted/rejected with probability
 
-.. math:: \alpha=\min\bigg\{1, \frac{p(\textbf{w})q(\textbf{x}|\textbf{w})}{p(\textbf{x})q(\textbf{w}|\textbf{x})}\bigg\}
+.. math:: \alpha=\min\bigg\{1, \frac{p_\textbf{X}(\textbf{w})q(\textbf{x}|\textbf{W})}{p_\textbf{X}(\textbf{x})q(\textbf{w}|\textbf{X})}\bigg\}
 
-and in the second stage is accepted/rejected based on whether the sample belongs to the failure region :math:`G_j`.
-:class:`.SubSetSimulation` can be used with any of the available (or custom) :class:`.MCMC` classes in the
-:py:mod:`sampling` module.
-
-SubsetSimulation Class
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+and in the second stage is accepted/rejected based on whether the sample belongs to the failure region :math:`G_i`.
+:class:`.SubsetSimulation` can be used with any of the available (or custom) :class:`.MCMC` classes in the
+:py:mod:`Sampling` module.
 
 The :class:`.SubsetSimulation` class is imported using the following command:
 
 >>> from UQpy.reliability.SubsetSimulation import SubsetSimulation
 
 Methods
 """""""
+
 .. autoclass:: UQpy.reliability.SubsetSimulation
 
 Attributes
 """"""""""
-.. autoattribute:: UQpy.reliability.SubsetSimulation.samples
-.. autoattribute:: UQpy.reliability.SubsetSimulation.performance_function_per_level
-.. autoattribute:: UQpy.reliability.SubsetSimulation.performance_threshold_per_level
+
+.. autoattribute:: UQpy.reliability.SubsetSimulation.dependent_chains_CoV
 .. autoattribute:: UQpy.reliability.SubsetSimulation.failure_probability
 .. autoattribute:: UQpy.reliability.SubsetSimulation.independent_chains_CoV
-.. autoattribute:: UQpy.reliability.SubsetSimulation.dependent_chains_CoV
-
+.. autoattribute:: UQpy.reliability.SubsetSimulation.performance_function_per_level
+.. autoattribute:: UQpy.reliability.SubsetSimulation.performance_threshold_per_level
+.. autoattribute:: UQpy.reliability.SubsetSimulation.samples
 
 Examples
 """"""""""