Skip to content
Snippets Groups Projects
Commit de2f7cf3 authored by Hu Zhao's avatar Hu Zhao
Browse files

docs: set up doc structure

parent fa62d3cd
No related branches found
No related tags found
No related merge requests found
Showing
with 165 additions and 26 deletions
...@@ -4,9 +4,9 @@ ...@@ -4,9 +4,9 @@
# You can set these variables from the command line, and also # You can set these variables from the command line, and also
# from the environment for the first two. # from the environment for the first two.
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = python -msphinx SPHINXBUILD = sphinx-build
SOURCEDIR = . SOURCEDIR = source
BUILDDIR = _build BUILDDIR = source/_build
# Put it first so that "make" without argument is like "make help". # Put it first so that "make" without argument is like "make help".
help: help:
......
```{include} ../CONDUCT.md
```
\ No newline at end of file
emulator Examples
^^^^^^^^^^^^^^^^^
\ No newline at end of file
inference Examples
^^^^^^^^^^^^^^^^^^
\ No newline at end of file
sampler Examples
^^^^^^^^^^^^^^^^
\ No newline at end of file
sensitivity Examples
^^^^^^^^^^^^^^^^^^^^
\ No newline at end of file
simulator Examples
^^^^^^^^^^^^^^^^^^
\ No newline at end of file
```{include} ../README.md
```
```{toctree}
:maxdepth: 1
:hidden:
changelog.md
conduct.md
autoapi/index
```
myst-nb sphinx_rtd_theme
sphinx-autoapi sphinx_autodoc_typehints
sphinx-rtd-theme sphinxcontrib_bibtex
\ No newline at end of file sphinx_gallery
\ No newline at end of file
File moved
...@@ -10,9 +10,9 @@ ...@@ -10,9 +10,9 @@
# add these directories to sys.path here. If the directory is relative to the # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
# #
# import os import os
# import sys import sys
# sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../../src/psimpy/'))
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
...@@ -20,20 +20,37 @@ ...@@ -20,20 +20,37 @@
project = 'psimpy' project = 'psimpy'
copyright = '2022, Hu Zhao' copyright = '2022, Hu Zhao'
author = 'Hu Zhao' author = 'Hu Zhao'
#release = "v0.2.0"
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
extensions = [ extensions = [
'myst_nb', # 'myst_nb',
'autoapi.extension', # 'autoapi.extension',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon', 'sphinx.ext.napoleon',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'sphinx_autodoc_typehints',
'sphinx_gallery.gen_gallery',
'sphinxcontrib.bibtex',
] ]
autoapi_dirs = ['../src']
# autoapi_dirs = ['../src']
autoclass_content = 'init'
autodoc_member_order = 'bysource'
add_module_names = False
bibtex_bibfiles = ['refs.bib']
bibtex_default_style = 'unsrt'
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -44,6 +61,25 @@ templates_path = ['_templates'] ...@@ -44,6 +61,25 @@ templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# configure Sphinx-Gallery
sphinx_gallery_conf = {
"examples_dirs": [
"../examples/emulator",
"../examples/inference",
"../examples/sampler",
"../examples/sensitivity",
"../examples/simulator",
], # path to your example scripts,
"gallery_dirs": [
"../auto_examples/emulator",
"../auto_examples/inference",
"../auto_examples/sampler",
"../auto_examples/sensitivity",
"../auto_examples/simulator",
], # path to where to save gallery generated output
}
# -- Options for HTML output ------------------------------------------------- # -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
......
:gitlab_url: https://git-ce.rwth-aachen.de/mbd/psimpy
=======
Welcome
=======
PSimPy (Predictive and probabilistic simulation with Python) implements
a Gaussian process emulation-based framework that enables systematically and
efficiently performing uncertainty-related analyses of physics-based
models, which are often computationlly expensive. Examples are variance-based
global sensitvity analysis, uncertainty quantification, and parameter
calibration.
Installation
============
:py:mod:`PSimPy` is a pure Python package. All Python-related dependencies are
automatically taken care of. It should be noted that some modules rely on or use
non-Python package and software. More specifically, the emulator module
:py:mod:`robustgasp.py` relies on the R package
`RobustGaSP <https://cran.r-project.org/web/packages/RobustGaSP/>`_;
the simulator module :py:mod:`ravaflow24.py` relies on the open source software
`r.avaflow 2.4 <https://www.landslidemodels.org/r.avaflow/>`_.
If the simulator module :py:mod:`ravaflow24.py` is desired, you may follow the
official `r.avaflow User manual <https://www.landslidemodels.org/r.avaflow/manual.php>`_
to install it. The installation of the R package `RobustGaSP` is covered in
following steps.
We recommond you to install :py:mod:`PSimPy` in a virtual environment such as a
`conda` environment. You may want to first install `Anaconda` or `Miniconda` if you
haven't. The steps afterwards are as follows.
1. Create a conda environment with Python 3.9::
conda create --name your_env_name python=3.9
2. Install `R` if you don't have it on your machine (if you have `R`, you can
skip this step; alternatively, you can still follow this step to install `R` in
the conda environment)::
conda activate your_env_name
conda install -c conda-forge r-base=3.6
3. Install the R package `RobustGaSP` in the R terminal::
R
install.packages("RobustGaSP",repos="https://cran.r-project.org",version="0.6.4")
Try if it is successfully installed by::
library("RobustGaSP")
4. Configure the environment variable `R_HOME` so that `rpy2` knows where to find
`R` packages. You can find your `R_HOME` by typing the following command in the
R terminal::
R.home()
q()
It is a path like ".../lib/R". Set the environment variable `R_HOME` in your
conda environment by::
conda env config vars set R_HOME=your_R_HOME
Afterwards reactivate your conda environment to make the change take effect by::
conda deactivate
conda activate your_env_name
5. Install :py:mod:`PSimPy` using `pip` in your conda environment by::
conda install -c conda-forge pip
pip install psimpy
Now you should have :py:mod:`PSimPy` and its dependencies successfully installed
in your conda environment. You can use it in the Python terminal or in your
Python IDE.
If you would like to use it with Jupyter Notebook (iPython Notebook), there is
one extra step needed to set your conda environment on your Notebook:
6. Install `ipykernel` and install a kernel that points to your conda environment
by::
conda install -c conda-forge ipykernel
python -m ipykernel install --user --name=your_env_name
Now you can start your Notebook, change the kernel to your conda environment, and
use :py:mod:`PSimPy`.
.. toctree::
:hidden:
Home <self>
/emulator/index
/inference/index
/sampler/index
/sampling/index
/sensitivity/index
/simulator/index
refs.rst
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment