psimpy 0.2.0

Predictive and probabilistic simulation tools.

Description

PSimPy (Predictive and probabilistic simulation with Python) implements a Gaussian process emulation-based framework that enables systematic and efficient investigation of uncertainties associated with physics-based models (i.e. simulators).

Prerequisites

Before installing and using PSimPy, please ensure that you have the following prerequisites:
(Please note that we will cover number 1 to 3 in our recommended installation method: Installation in a Conda Environment.)

1. Python 3.9 or later:
   Make sure you have Python installed on your system. You can download the latest version of Python from the official website: Python Downloads
2. R Installed and Added to the PATH Environment Variable:
   • Install R from the official R Project website.
   • Add R to your system's PATH environment variable. This step is crucial for enabling communication between Python and R.
3. (Optional) RobustGaSP - R package:
   The emulator module, robustgasp.py, relies on the R package RobustGaSP. This has also been initegrated with other PSimPy modules, such as active_learning.py. In order to utilize these modules, make sure to install the R package RobustGaSP first.
4. (Optional) r.avaflow - Mass Flow Simulation Tool:
   PSimPy includes a simulator module, ravaflow3G.py, that interfaces with the open source software r.avaflow 3G. If you intend to use this module, please refer to the official documentation of r.avaflow 3G to for installation guide.

Installation

PSimPy can be easily installed using pip.

$ pip install psimpy

This command will install the package along with its dependencies.

Installation in a Conda Environment (Recommended)

We recommond you to install PSimPy in a virtual environment such as a conda environment. In this section, we will ceate a conda environment, install prerequisites (number 1 to 3), install python, and lastly, add the conda environment to Jupyter Notebook. 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 and R, and activate the environment:

   $ conda create --name your_env_name python R
   $ conda activate your_env_name
   

2. Install the R package RobustGaSP in the R terminal:

   $ R
   ...
   > install.packages("RobustGaSP",repos="https://cran.r-project.org",version="0.6.4")
   

   Make sure it is successfully installed:

   > library("RobustGaSP")
   

3. Next, you need to configure the environment variable R_HOME so that rpy2 knows where to find R packages. Find your R_HOME using the following command and then quit the R terminal:

   > R.home()
   > q()
   

   Set the environment variable R_HOME in your conda environment with

   $ conda env config vars set R_HOME=your_R_HOME
   

   Reactivate your conda environment to make the change take effect by

   $ conda deactivate
   $ conda activate your_env_name
   

4. Install PSimPy using pip in your conda environment:

   $ pip install psimpy
   

Now you should have 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:

5. Install ipykernel and install a kernel that points to your conda environment:

   $ 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 PSimPy.

Documentation

Detailed documentation of PSimPy is hosted at https://mbd.pages.rwth-aachen.de/psimpy/, including the API and theory (or reference) of each module.

Usage

Usage examples are provided by the Example Gallery.

License

PSimPy was created by Hu Zhao at the Chair of Methods for Model-based Development in Computational Engineering (RWTH Aachen University, Germany). It is licensed under the terms of the MIT license.