Skip to content

Commit 6f8ae38

Browse files
jnschmidjnschmid
authored
Merge pull request #3 from jnschmid/doc_updates
Lognormal variable added, document workflow added, and documentation updated
2 parents 058f0bd + e1f08b0 commit 6f8ae38

35 files changed

+1601
-716
lines changed

‎.github/workflows/docs_workflow.yml‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Build docs
2+
3+
name: UQPCE Docs
4+
5+
on:
6+
# Trigger on push, pull request
7+
push:
8+
branches: [ main ]
9+
pull_request:
10+
branches: [ main ]
11+
12+
# Trigger via workflow_dispatch event
13+
workflow_dispatch:
14+
15+
jobs:
16+
17+
docs_ubuntu:
18+
runs-on: ubuntu-22.04
19+
20+
timeout-minutes: 90
21+
22+
strategy:
23+
fail-fast: false
24+
matrix:
25+
include:
26+
# baseline versions except with pyoptsparse but no SNOPT
27+
# build docs to verify those that use pyoptsparse do not use SNOPT
28+
- NAME: baseline_no_snopt
29+
PY: '3.11'
30+
NUMPY: '1.26'
31+
SCIPY: '1.13'
32+
PYYAML: '6.0.2'
33+
JAX: '0.6.1'
34+
OPENMDAO: 'latest'
35+
DYMOS: 'latest'
36+
MPI4PY: '3.1.4'
37+
OPTIONAL: '[docs]'
38+
PUBLISH_DOCS: 1
39+
40+
# # make sure the latest versions of things don't break the docs
41+
# # sticking with Python 3.12 for now, 3.13 requires NumPy 2.1 which does not work yet with PETSc/pyoptsparse
42+
# # Pin PETSc back to 3.22.2
43+
# - NAME: latest
44+
# PY: '3.12'
45+
# NUMPY: 1
46+
# SCIPY: 1
47+
# PETSc: 3.21.0
48+
# PYOPTSPARSE: 'latest'
49+
# SNOPT: 7.7
50+
# OPENMDAO: 'dev'
51+
# OPTIONAL: '[docs]'
52+
# JAX: 'latest'
53+
# PUBLISH_DOCS: 0
54+
55+
steps:
56+
- name: Display run details
57+
run: |
58+
echo "============================================================="
59+
echo "Run #${GITHUB_RUN_NUMBER}"
60+
echo "Run ID: ${GITHUB_RUN_ID}"
61+
echo "Testing: ${GITHUB_REPOSITORY}"
62+
echo "Triggered by: ${GITHUB_EVENT_NAME}"
63+
echo "Initiated by: ${GITHUB_ACTOR}"
64+
echo "============================================================="
65+
66+
- name: Checkout code
67+
uses: actions/checkout@v4
68+
69+
- name: Setup conda
70+
uses: conda-incubator/setup-miniconda@v3
71+
with:
72+
python-version: ${{ matrix.PY }}
73+
channels: conda-forge
74+
conda-remove-defaults: true
75+
76+
- name: Install Numpy/Scipy
77+
shell: bash -l {0}
78+
run: |
79+
echo "============================================================="
80+
echo "Install Numpy/Scipy"
81+
echo "============================================================="
82+
conda install numpy=${{ matrix.NUMPY }} scipy=${{ matrix.SCIPY }} -q -y
83+
84+
- name: Install OpenMDAO
85+
if: matrix.OPENMDAO
86+
shell: bash -l {0}
87+
run: |
88+
echo "============================================================="
89+
echo "Install OpenMDAO"
90+
echo "============================================================="
91+
if [[ "${{ matrix.OPENMDAO }}" == "dev" ]]; then
92+
pip install git+https://github.com/OpenMDAO/OpenMDAO
93+
elif [[ "${{ matrix.OPENMDAO }}" == "latest" ]]; then
94+
pip install openmdao
95+
else
96+
pip install openmdao==${{ matrix.OPENMDAO }}
97+
fi
98+
99+
- name: Install Dymos
100+
if: matrix.DYMOS
101+
shell: bash -l {0}
102+
run: |
103+
echo "============================================================="
104+
echo "Install Dymos"
105+
echo "============================================================="
106+
if [[ "${{ matrix.DYMOS }}" == "dev" ]]; then
107+
pip install git+https://github.com/OpenMDAO/dymos
108+
elif [[ "${{ matrix.DYMOS }}" == "latest" ]]; then
109+
pip install dymos
110+
else
111+
pip install dymos==${{ matrix.DYMOS }}
112+
fi
113+
114+
- name: Install PyYAML
115+
if: matrix.PYYAML
116+
shell: bash -l {0}
117+
run: |
118+
echo "============================================================="
119+
echo "Install PyYAML"
120+
echo "============================================================="
121+
pip install PyYAML==${{ matrix.PYYAML }}
122+
123+
- name: Install JAX
124+
if: matrix.JAX
125+
shell: bash -l {0}
126+
run: |
127+
echo "============================================================="
128+
echo "Install JAX"
129+
echo "============================================================="
130+
pip install jax==${{ matrix.JAX }}
131+
132+
- name: Install mpi4py
133+
if: matrix.MPI4PY
134+
shell: bash -l {0}
135+
run: |
136+
echo "============================================================="
137+
echo "Install mpi4py"
138+
echo "============================================================="
139+
conda install mpi4py==${{ matrix.MPI4PY }} -q -y
140+
141+
- name: Install UQPCE
142+
shell: bash -l {0}
143+
run: |
144+
echo "============================================================="
145+
echo "Install UQPCE"
146+
echo "============================================================="
147+
pip install .${{ matrix.OPTIONAL }}
148+
149+
- name: Display environment info
150+
id: env_info
151+
shell: bash -l {0}
152+
run: |
153+
conda info
154+
conda list
155+
156+
echo "============================================================="
157+
echo "Check installed versions of Python, Numpy and Scipy"
158+
echo "============================================================="
159+
python -c "import sys; assert str(sys.version).startswith(str(${{ matrix.PY }})), \
160+
f'Python version {sys.version} is not the requested version (${{ matrix.PY }})'"
161+
162+
python -c "import numpy; assert str(numpy.__version__).startswith(str(${{ matrix.NUMPY }})), \
163+
f'Numpy version {numpy.__version__} is not the requested version (${{ matrix.NUMPY }})'"
164+
165+
python -c "import scipy; assert str(scipy.__version__).startswith(str(${{ matrix.SCIPY }})), \
166+
f'Scipy version {scipy.__version__} is not the requested version (${{ matrix.SCIPY }})'"
167+
168+
- name: Display dependency tree
169+
if: failure() && steps.env_info.outcome == 'failure'
170+
run: |
171+
pip install pipdeptree
172+
pipdeptree
173+
174+
- name: Build docs
175+
id: build_docs
176+
shell: bash -l {0}
177+
run: |
178+
echo "============================================================="
179+
echo "Building Docs"
180+
echo "============================================================="
181+
export PYDEVD_DISABLE_FILE_VALIDATION=1
182+
jupyter-book build -W --keep-going docs
183+
184+
- name: Display doc build reports
185+
continue-on-error: True
186+
if: failure() && steps.build_docs.outcome == 'failure'
187+
run: |
188+
echo $PWD
189+
find docs/_build/html/reports/ -type f -name '*.log' \
190+
-exec echo "#################################################################" \; \
191+
-exec echo {} \; \
192+
-exec echo "#################################################################" \; \
193+
-exec cat {} \;
194+
195+
- name: Publish docs to github.io
196+
if: |
197+
github.event_name == 'push' && matrix.PUBLISH_DOCS == '1'
198+
shell: bash -l {0}
199+
run: |
200+
echo "============================================================="
201+
echo "Publishing Docs to github.io"
202+
echo "============================================================="
203+
pip install ghp-import
204+
cd $HOME/work/UQPCE
205+
ghp-import -n -p -f docs/_build/html

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22

33
Uncertainty Quantification with Polynomial Chaos Expansion ([UQPCE](https://github.com/nasa/UQPCE)) is an open-source, python-based research code for use in parametric, non-deterministic computational studies. UQPCE utilizes a non-intrusive polynomial chaos for computational analyses. The software allows the user to perform an automated uncertainty analysis for any given computational code without requiring modification to the source. UQPCE estimates sensitivities, confidence intervals, and other model statistics, which can be useful in the conceptual design and analysis of flight vehicles. This software was developed for the [Aeronautics Systems Analysis Branch](https://sacd.larc.nasa.gov/asab/) within the [Systems Analysis and Concepts Directorate](https://sacd.larc.nasa.gov/) at [NASA Langley Research Center](https://www.nasa.gov/langley).
44

5+
## Documentation
6+
7+
Documentation for the most recent verison of UQPCE can be found [here](https://nasa.github.io/UQPCE/intro.html).
8+
59
## Installation
610

711
Install library with `pip install -e .` in the location of your choice.
812

9-
Run the test case in `python examples/paraboloid/paraboloid_example.py`
10-
13+
Run the unittests using `python -m unittest discover uqpce`
1114

1215
## Notices
1316
Copyright © 2020-2024 United States Government as represented by the
@@ -76,4 +79,4 @@ INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S
7679
USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE
7780
UNITED STATES GOVERNMENT, ITS CONTRACTORS, AND SUBCONTRACTORS, AS WELL AS ANY
7881
PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR
79-
ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.
82+
ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.

‎docs/_config.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ logo: images/UQPCE_logo.png
99
# Force re-execution of notebooks on each build.
1010
# See https://jupyterbook.org/content/execute.html
1111
execute:
12-
execute_notebooks: force
12+
execute_notebooks: cache
13+
timeout: 800
1314

1415
# Define the name of the latex output file for PDF builds
1516
latex:
@@ -47,6 +48,7 @@ sphinx:
4748
extra_extensions:
4849
- 'sphinx.ext.autodoc'
4950
- 'sphinx.ext.autosummary'
51+
- 'sphinx.ext.napoleon'
5052
config:
5153
html_favicon: favicon.ico
5254
autosummary_generate: True

‎docs/_toc.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,12 @@ root: intro
77

88
parts:
99
- caption: User Guide
10+
maxdepth: 1
1011
chapters:
1112
- file: user-guide/getting-started
13+
sections:
14+
- file: user-guide/running-uqpce
15+
- file: user-guide/multiphase_projectile_example
1216
- file: user-guide/variables
1317
- file: user-guide/inputs
1418
- file: user-guide/settings
@@ -44,6 +48,7 @@ parts:
4448
- file: reference/continuous/beta
4549
- file: reference/continuous/gamma
4650
- file: reference/continuous/exponential
51+
- file: reference/continuous/lognormal
4752
- file: reference/continuous/user-input
4853
- file: reference/continuous/epistemic
4954
- file: reference/discrete-variables

‎docs/reference/continuous-variables.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Continuous Variables
66
- [Beta](continuous/beta)
77
- [Gamma](continuous/gamma)
88
- [Exponential](continuous/exponential)
9+
- [Lognormal](continuous/lognormal)
910
- [Continuous User-Input](continuous/user-input)
1011
- [Continuous Epistemic](continuous/epistemic)

‎docs/reference/continuous/lognormal.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Lognormal Variable
2+
-------------------
3+
4+
.. autoclass:: uqpce.pce.variables.continuous.LognormalVariable
5+
:members:

‎docs/theory/variables.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,17 @@ f(x) = \frac{1}{\Gamma(\alpha)\theta^{\alpha}} (x\ -\ a)^{\alpha - 1} e^{-\frac{
5252
$$
5353

5454

55+
### Lognormal Variable
56+
The equation UQPCE uses for a lognormal variable is shown below where $\mu \ \epsilon \ \mathbb{R}$ and $\sigma > 0$. Parameter $\mu$ is the mean of the variable's natural logarithm, and $\sigma$ is the standard deviation of the variable's natural logarithm. The support range of this variable is [a, $\infty$].
57+
58+
$$
59+
f(x) = \frac{1}{(x - a) \sigma \sqrt{2 \pi}} \cdot e^{-\frac{\bigg(ln \big(x-a \big) - \mu \bigg)^{2}}{2 \sigma}}
60+
$$
61+
62+
5563
(variable)=
5664

65+
5766
### User-Input Variable
5867
This is an option for the user to input a variable that has an arbitrary continuous distribution. While this gives the user flexibility, there are some requirements the distribution must adhere to:
5968

‎docs/user-guide/getting-started.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Getting Started with UQPCE
2+
3+
The following section contains information for running UQPCE as a script and running UQPCE with [OpenMDAO](https://openmdao.org/newdocs/versions/latest/main.html) for design under uncertainty.
4+
5+
```{tableofcontents}
6+
```

‎docs/user-guide/inputs.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ The basic input files are required when executing UQPCE as a module. Files can b
2929

3030
* When adding comments to the YAML file, comments need to begin with a new line a new line and start with ``"#"``. Comments that are in-line with an input should begin with ``" #"`` (space before the ``#``).
3131

32-
```
3332

3433
### Example
3534

0 commit comments

Comments
 (0)