diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000000000000000000000000000000000000..1dfc30850c515b40e237d110e014bdc82106b0ed --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,11 @@ +API & Theory +============ + +.. toctree:: + :maxdepth: 2 + + /emulator/index + /inference/index + /sampler/index + /sensitivity/index + /simulator/index \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index b34f888ca52f9b379ff2b5456893e859b6afa939..504a816306212d8e2cb293e8e81c1aa804d6115b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,6 +10,7 @@ # 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. # +from datetime import date import os import sys sys.path.insert(0, os.path.abspath('../../src/psimpy/')) @@ -18,9 +19,11 @@ sys.path.insert(0, os.path.abspath('../../src/psimpy/')) # -- Project information ----------------------------------------------------- project = 'psimpy' -copyright = '2022, Hu Zhao' +copyright = f'{date.today().year}, Hu Zhao' author = 'Hu Zhao' -#release = "v0.2.0" + +# import psimpy +# version = psimpy.__version__ # -- General configuration --------------------------------------------------- @@ -97,6 +100,8 @@ html_sidebars = { ] } +html_title = "PSimPy's documentation" + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000000000000000000000000000000000000..2616ef02539e27094053f2f29b4947a164ecda9e --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,6 @@ +Example Gallery +=============== + +.. toctree:: + + Emulator - RobustGaSP <../auto_examples/emulator/robustgasp/index> \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index c9303db3bd0a54474b6bb740ba24ff4d5b0a9bba..b9cf7b25a251da6b1431bd13107876cad7bc3d12 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,104 +1,18 @@ :gitlab_url: https://git-ce.rwth-aachen.de/mbd/psimpy -Welcome -======= +Welcome to PSimPy's documentation! +================================== -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`. +Contents +-------- .. toctree:: :maxdepth: 2 - :hidden: Home <self> - /emulator/index - /inference/index - /sampler/index - /sensitivity/index - /simulator/index - changelog.rst - refs.rst + quickstart + changelog + api + examples + refs diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000000000000000000000000000000000000..717d65bc1ac4725ba15fd57ba00f80556e876242 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,91 @@ + +Getting Started +=============== + +Overview +-------- + +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`. \ No newline at end of file