-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* sphinx documentation quickstart * updated autodocs * updated documentation * updated readme * updated readme * updated readme again * more documentation updates * updated documentation * added docs * updated docs * updated opt docs * updated read me and markdown imports * Added installation instructions and new theme * changes to the readme and instructions * updates to docs and added docs for utils
- Loading branch information
Showing
32 changed files
with
1,423 additions
and
527 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
# Installation | ||
|
||
## Dependencies | ||
`SOUPy` depends on [FEniCS](http://fenicsproject.org/) version 2019.1. and [hIPPYlib](https://hippylib.github.io/) version 3.0.0 or above. | ||
|
||
`FEniCS` needs to be built with the following dependencies enabled: | ||
|
||
- `numpy`, `scipy`, `matplotlib`, `mpi4py` | ||
- `PETSc` and `petsc4py` (version 3.10.0 or above) | ||
- `SLEPc` and `slepc4py` (version 3.10.0 or above) | ||
- PETSc dependencies: `parmetis`, `scotch`, `suitesparse`, `superlu_dist`, `ml`, `hypre` | ||
- (optional): `gmsh`, `mshr`, `jupyter` | ||
|
||
## Recommended installation procedures using conda | ||
1. Install `FEniCS` with appropriate dependencies | ||
``` | ||
conda create -n soupy -c conda-forge fenics==2019.1.0 matplotlib scipy jupyter | ||
``` | ||
|
||
2. Clone the `hIPPYlib` [repository](https://github.com/hippylib/hippylib). | ||
``` | ||
git clone https://github.com/hippylib/hippylib.git | ||
``` | ||
|
||
3. Clone the `SOUPy` [repository](https://github.com/hippylib/soupy/tree/main) | ||
``` | ||
git clone https://github.com/hippylib/soupy.git | ||
``` | ||
|
||
4. Set the path to the `hIPPYlib` and `SOUPy` as environment variables, e.g. | ||
``` | ||
conda activate soupy | ||
conda env config vars set HIPPYLIB_PATH=path/to/hippylib | ||
conda env config vars set SOUPY_PATH=path/to/soupy | ||
``` | ||
|
||
Examples in the `applications` directory can now be run. We refer to the full `FEniCS` [installation instructions](https://hippylib.readthedocs.io/en/3.0.0/installation.html) from `hIPPYlib` for more detail. | ||
|
||
## Build the SOUPy documentation using Sphinx | ||
|
||
Documentation for `SOUPy` can be built using `sphinx`, along with extensions | ||
`myst_parser` and `sphinx_rtd_theme`. These can be installed via `pip`. | ||
|
||
To build simply run `make html` from `doc` folder. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,19 @@ | ||
# soupy | ||
Stochastic Optimization under Uncertainty in Python. | ||
# Stochastic Optimization under high-dimensional Uncertainty in Python | ||
|
||
**S**tochastic **O**ptimization under high-dimensional **U**ncertainty in **Py**thon—**SOUPy**, | ||
implements scalable algorithms to solve problems of PDE-constrained optimization under uncertainty, with the computational complexity measured in terms of PDE solves independent of the uncertain parameter dimension and optimization variable dimension. | ||
|
||
`SOUPy` is built on the open-source `hIPPYlib` library, which provides state-of-the-art scalable adjoint-based methods for deterministic and Bayesian inverse problems governed by PDEs, which in turn makes use of the `FEniCS` library for high-level formulation, discretization, and scalable solution of PDEs. | ||
|
||
`SOUPy` implements algorithms for the optimization of probability/risk measures such as mean, variance, and superquantile/condition-value-at-risk, subject to PDE constraints. | ||
Sample based approximations of risk measures are supported in `SOUPy`, which leverages MPI for rapid parallel sampling. | ||
Numerical optimization algorithms can be called from `SciPy` or using the built-in optimization algorithms. | ||
|
||
`SOUPy` has been developed and in active development to incorporate advanced approximation algorithms and capabilities, including: | ||
- PDE-constrained operator/tensor/matrix products, | ||
- symbolic differentiation (of appropriate Lagrangians) for the derivation of high order mixed derivatives (via the `FEniCS` interface), | ||
- randomized algorithms for matrix and high order tensor decomposition, | ||
- decomposition of uncertain parameter spaces by mixture models, | ||
- Taylor expansion-based high-dimensional control variates, and | ||
- product convolution approximations, | ||
- common interfaces for random fields, PDE models, probability/risk measures, and control/design/inversion constraints. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = . | ||
BUILDDIR = _build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# Configuration file for the Sphinx documentation builder. | ||
# | ||
# For the full list of built-in configuration values, see the documentation: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
# -- Path setup -------------------------------------------------------------- | ||
# If extensions (or modules to document with autodoc) are in another directory, | ||
# add these directories to sys.path here. If the directory is relative to the | ||
# documentation root, use os.path.abspath to make it absolute, like shown here. | ||
# | ||
import os | ||
import sys | ||
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) | ||
sys.path.insert(0, basedir) | ||
|
||
autodoc_mock_imports = ["dolfin", "matplotlib", "ffc", "ufl", | ||
"petsc4py", "mpi4py", "scipy", "numpy", "hippylib"] | ||
autodoc_default_flags = ['members', 'private-members', 'undoc-members'] | ||
autoclass_content = 'both' | ||
|
||
# -- Project information ----------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
||
project = 'SOUPy' | ||
copyright = "2023, Peng Chen, Dingcheng Luo, Thomas O'Leary-Roseberry, Umberto Villa" | ||
author = "Peng Chen, Dingcheng Luo, Thomas O'Leary-Roseberry, Umberto Villa" | ||
release = '0.1.0' | ||
|
||
# -- General configuration --------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration | ||
|
||
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', | ||
'sphinx.ext.napoleon', 'myst_parser', 'sphinx.ext.autosummary'] | ||
|
||
templates_path = ['_templates'] | ||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] | ||
source_suffix = ['.rst', '.md'] | ||
master_doc = 'index' | ||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output | ||
|
||
html_theme = 'sphinx_rtd_theme' | ||
html_static_path = [] | ||
# html_theme_options = { | ||
# "nosidebar": True | ||
# } | ||
# html_theme_options = { | ||
# "nosidebar": False, "sidebarwidth": "40em" | ||
# } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
.. SOUPy documentation master file, created by | ||
sphinx-quickstart on Thu Jul 6 18:03:26 2023. | ||
You can adapt this file completely to your liking, but it should at least | ||
contain the root `toctree` directive. | ||
Welcome to SOUPy's documentation! | ||
================================= | ||
.. include:: ../README.md | ||
:parser: myst_parser.sphinx_ | ||
|
||
Documentation | ||
--------------------- | ||
|
||
.. toctree:: | ||
:titlesonly: | ||
:maxdepth: 1 | ||
|
||
install | ||
Complete API reference <soupy> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
.. include:: ../INSTALL.md | ||
:parser: myst_parser.sphinx_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=. | ||
set BUILDDIR=_build | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.https://www.sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
soupy.collectives | ||
========================== | ||
|
||
soupy.collectives.collective | ||
----------------------------------- | ||
|
||
.. automodule:: soupy.collectives.collective | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,87 @@ | ||
soupy.modeling | ||
========================= | ||
|
||
soupy.modeling.PDEControlProblem | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.PDEControlProblem | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
soupy.modeling.controlModel | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.controlModel | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
soupy.modeling.controlQoI | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.controlQoI | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
|
||
soupy.modeling.controlCostFunctional | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.controlCostFunctional | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.modeling.meanVarRiskMeasure | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.meanVarRiskMeasure | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.modeling.meanVarRiskMeasureSAA | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.meanVarRiskMeasureSAA | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.modeling.variables | ||
------------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.variables | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.modeling.augmentedVector | ||
------------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.augmentedVector | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.modeling.superquantileRiskMeasureSAA | ||
------------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.superquantileRiskMeasureSAA | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
soupy.modeling.penalization | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.modeling.penalization | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
soupy.optimization | ||
========================== | ||
|
||
soupy.optimization.bfgs | ||
----------------------------------- | ||
|
||
.. automodule:: soupy.optimization.bfgs | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.optimization.projectableConstraint | ||
----------------------------------------- | ||
|
||
.. automodule:: soupy.optimization.projectableConstraint | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.optimization.steepestDescent | ||
----------------------------------- | ||
|
||
.. automodule:: soupy.optimization.steepestDescent | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.optimization.sgd | ||
----------------------------------- | ||
|
||
.. automodule:: soupy.optimization.sgd | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
soupy package | ||
================ | ||
|
||
Submodules | ||
----------- | ||
|
||
.. toctree:: | ||
|
||
soupy.modeling | ||
soupy.optimization | ||
soupy.collectives | ||
soupy.utils | ||
|
||
Module contents | ||
--------------- | ||
|
||
.. automodule:: soupy | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
soupy.utils module | ||
========================= | ||
|
||
soupy.utils.penalizationFiniteDifference | ||
----------------------------------------------- | ||
|
||
.. automodule:: soupy.utils.penalizationFiniteDifference | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
soupy.utils.qoiFiniteDifference | ||
----------------------------------------------- | ||
|
||
.. automodule:: soupy.utils.qoiFiniteDifference | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
|
||
soupy.utils.stochasticCostFiniteDifference | ||
----------------------------------------------- | ||
|
||
.. automodule:: soupy.utils.stochasticCostFiniteDifference | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
soupy.utils.scipyCostWrapper module | ||
--------------------------------------- | ||
|
||
.. automodule:: soupy.utils.scipyCostWrapper | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
Oops, something went wrong.