From 935d45ddb3cb849aa387e9774561d063832cb85a Mon Sep 17 00:00:00 2001 From: connor-krill Date: Tue, 15 Aug 2023 14:16:14 -0400 Subject: [PATCH] improved docstrings and markdown for cleaniness and consistency in readthedocs --- docs/code/reliability/inverse_form/README.rst | 4 +--- .../inverse_form/inverse_form_cantilever.py | 22 +++++++++---------- .../{performance_function.py => local_pfn.py} | 6 +++++ docs/source/reliability/inverse_form.rst | 12 +++++----- .../reliability/taylor_series/InverseFORM.py | 7 +++--- 5 files changed, 28 insertions(+), 23 deletions(-) rename docs/code/reliability/inverse_form/{performance_function.py => local_pfn.py} (87%) diff --git a/docs/code/reliability/inverse_form/README.rst b/docs/code/reliability/inverse_form/README.rst index b3c07358..44cdc4d1 100644 --- a/docs/code/reliability/inverse_form/README.rst +++ b/docs/code/reliability/inverse_form/README.rst @@ -1,4 +1,2 @@ Inverse FORM Examples -^^^^^ - -The following example is Example 7.2 from Chapter 7 of :cite:`FORM_XDu`. \ No newline at end of file +^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/code/reliability/inverse_form/inverse_form_cantilever.py b/docs/code/reliability/inverse_form/inverse_form_cantilever.py index ed7b2216..b5bfcb79 100644 --- a/docs/code/reliability/inverse_form/inverse_form_cantilever.py +++ b/docs/code/reliability/inverse_form/inverse_form_cantilever.py @@ -1,25 +1,25 @@ """ Inverse FORM - Cantilever Beam ------ +----------------------------------- +The following example is Example 7.2 from Chapter 7 of :cite:`FORM_XDu`. -A cantilever beam (example 7.2 in :cite:`FORM_XDu`) is considered to fail if the displacement at the tip exceeds the -threshold :math:`D_0`. The performance function :math:`G(\textbf{U})` of this problem is given by +A cantilever beam is considered to fail if the displacement at the tip exceeds the threshold :math:`D_0`. +The performance function :math:`G(\\textbf{U})` of this problem is given by -.. math:: G = D_0 - \frac{4L^3}{Ewt} \sqrt{ \left(\frac{P_x}{w^2}\right)^2 + \left(\frac{P_y}{t^2}\right)^2} +.. math:: G = D_0 - \\frac{4L^3}{Ewt} \\sqrt{ \\left(\\frac{P_x}{w^2}\\right)^2 + \\left(\\frac{P_y}{t^2}\\right)^2} Where the external forces are modeled as random variables :math:`P_x \sim N(500, 100)` and :math:`P_y \sim N(1000,100)`. -The constants in the problem are length (:math:`L=100`), elastic modulus (:math:E=30\times 10^6), cross section width -(:math:`w=2`) and cross section height (:math:`t=4`). +The constants in the problem are length (:math:`L=100`), elastic modulus (:math:`E=30\\times 10^6`), cross section width +(:math:`w=2`), cross section height (:math:`t=4`), and :math:`D_0=3`. """ # %% md # -# Import the necessary modules. +# First, we import the necessary modules. # %% + import numpy as np -import matplotlib.pyplot as plt -plt.style.use('ggplot') from scipy import stats from UQpy.distributions import Normal from UQpy.reliability.taylor_series import InverseFORM @@ -34,7 +34,7 @@ # %% -model = PythonModel(model_script='performance_function.py', model_object_name="cantilever_beam") +model = PythonModel(model_script='local_pfn.py', model_object_name="cantilever_beam") runmodel_object = RunModel(model=model) # %% md @@ -70,4 +70,4 @@ print('Design point in original space:', inverse_form.design_point_x[0]) print('Hasofer-Lind reliability index:', beta) print('Probability of failure at design point:', stats.norm.cdf(-beta)) -print('Number of iterations:', inverse_form.iteration_record[0]) \ No newline at end of file +print('Number of iterations:', inverse_form.iteration_record[0]) diff --git a/docs/code/reliability/inverse_form/performance_function.py b/docs/code/reliability/inverse_form/local_pfn.py similarity index 87% rename from docs/code/reliability/inverse_form/performance_function.py rename to docs/code/reliability/inverse_form/local_pfn.py index 4bfbcecf..4f40a8a7 100644 --- a/docs/code/reliability/inverse_form/performance_function.py +++ b/docs/code/reliability/inverse_form/local_pfn.py @@ -1,3 +1,9 @@ +""" + +Auxiliary file +============================================== + +""" import numpy as np diff --git a/docs/source/reliability/inverse_form.rst b/docs/source/reliability/inverse_form.rst index 79bf8af8..6dde4b65 100644 --- a/docs/source/reliability/inverse_form.rst +++ b/docs/source/reliability/inverse_form.rst @@ -9,7 +9,7 @@ where :math:`\textbf{U}^\star` is the expansion point, :math:`G(\textbf{U})` is the standard normal space and :math:`\nabla G(\textbf{U}^\star)` is the gradient of :math:`G(\textbf{U})` evaluated at :math:`\textbf{U}^\star`. The probability failure is approximated as -.. math:: P_{fail} = \Phi(-\beta_{HL}) +.. math:: p_{fail} = \Phi(-\beta_{HL}) where :math:`\Phi(\cdot)` is the standard normal cumulative distribution function and :math:`\beta_{HL}=||\textbf{U}^*||` is the norm of the design point known as the Hasofer-Lind reliability index. @@ -24,14 +24,14 @@ are: Problem Statement ------ +----------------- Compute :math:`u^* = \text{argmin}\ G(\textbf{U})` such that :math:`||\textbf{U}||=\beta`. The feasibility criteria :math:`||\textbf{U}||=\beta` may be equivalently defined as :math:`\beta = -\Phi^{-1}(p_{fail})`, where :math:`\Phi^{-1}(\cdot)` is the inverse standard normal CDF. Algorithm ------ +----------------- This method implements a gradient descent algorithm to solve the optimization problem within the tolerances specified by :math:`\text{tolerance}_{\textbf{U}}` (:code:`tolerance_u`) and :math:`\text{tolerance}_{\nabla G(\textbf{U})}` (:code:`tolerance_gradient`). @@ -50,12 +50,12 @@ The :class:`.InverseFORM` class is imported using the following command: >>> from UQpy.reliability.taylor_series import InverseFORM Methods -""""""" +----------------- .. autoclass:: UQpy.reliability.taylor_series.InverseFORM :members: run Attributes -"""""""""" +----------------- .. autoattribute:: UQpy.reliability.taylor_series.InverseFORM.alpha .. autoattribute:: UQpy.reliability.taylor_series.InverseFORM.alpha_record .. autoattribute:: UQpy.reliability.taylor_series.InverseFORM.beta @@ -71,4 +71,4 @@ Examples """""""""" .. toctree:: - FORM Examples <../auto_examples/reliability/inverse_form/index> \ No newline at end of file + InverseFORM Examples <../auto_examples/reliability/inverse_form/index> \ No newline at end of file diff --git a/src/UQpy/reliability/taylor_series/InverseFORM.py b/src/UQpy/reliability/taylor_series/InverseFORM.py index 0e282607..6ec2adff 100644 --- a/src/UQpy/reliability/taylor_series/InverseFORM.py +++ b/src/UQpy/reliability/taylor_series/InverseFORM.py @@ -111,16 +111,17 @@ def __init__( self.alpha_record: list = [] """Record of alpha :math:`\\alpha=\\frac{\\nabla G(u)}{||\\nabla G(u)||}`""" self.beta: float = self.beta - """Feasibility criteria for the optimization :math:`||\\textbf{U}|| = \\beta`""" + """Feasibility criteria for the optimization :math:`||\\textbf{U}|| = \\beta_{HL}`""" self.beta_record: list = [] - """Record of Hasofer-Lind reliability index that defines the feasibility criteria :math:`||u||=\\beta_{HL}`""" + """Record of Hasofer-Lind reliability index that defines the feasibility criteria + :math:`||\\textbf{U}||=\\beta_{HL}`""" self.design_point_u: list = [] """Design point in the standard normal space :math:`\\textbf{U}`""" self.design_point_x: list = [] """Design point in the parameter space :math:`\\textbf{X}`""" self.error_record: list = [] """Record of the final error defined by - :math:`error_u = ||u_new - u||` and :math:`error_{gradient} = || \\nabla G(u_new) - \\nabla G(u)||`""" + :math:`error_u = ||u_{new} - u||` and :math:`error_{\\nabla G(u)} = || \\nabla G(u_{new}) - \\nabla G(u)||`""" self.iteration_record: list = [] """Record of the number of iterations before algorithm termination""" self.failure_probability_record: list = []