ValPAS

For API reference visit https://pnnl-predictive-phenomics.github.io/valpas/.

Prerequisites

• Python 3.12 or higher
• pip (Python package installer)

Installation

1. Clone the Repository

git clone <repository-url>
cd <repository-name>

2. Create Virtual Environment

Steps 2. & 3. are only necessary if an encapuslated virtual python environment is desired. An alternative to venv is to use conda. For more information on anaconda / conda refer to https://anaconda.org/. If no virtual environment is desired or already exists skip to Step 4.

python -m venv valpas-env

3. Activate Virtual Environment

Windows:

valpas-env\Scripts\activate

macOS/Linux:

source valpas-env/bin/activate

4. Install valpas

pip install .

5. Install Additional Dependencies for Demonstration Notebook

These dependencies are only necessary if the included demonstration notebook is being run locally.

pip install -r requirements.txt

Quick Setup (One Command)

macOS/Linux:

python -m venv valpas-env && source valpas-env/bin/activate && pip install . && pip install -r requirements.txt

Windows:

python -m venv valpas-env && valpas-env\Scripts\activate && pip install . && pip install -r requirements.txt

Usage

Starting the Environment

Always activate the virtual environment before working on the project:

Windows:

valpas-env\Scripts\activate

macOS/Linux:

source valpas-env/bin/activate

Running Jupyter

Once the environment is activated, start Jupyter:

jupyter notebook

or

jupyter lab

Deactivating the Environment

When you're done working:

deactivate

Dependencies

The project uses the following main libraries:

• Jupyter: Interactive notebook environment
• PyTorch: Deep learning framework
• Scikit-learn: Machine learning library
• Matplotlib: Plotting library
• Seaborn: Statistical data visualization

Troubleshooting

Python Version Issues

If you need a specific Python version, create the environment with:

python3.13 -m venv valpas-env  # Replace 3.13 with your desired version

PyTorch GPU Support

For CUDA-enabled PyTorch installation, visit pytorch.org update torch with the appropriate command for your system.

pip install --force-reinstall torch torchvision --index-url <specified url>

Permission Issues

If you encounter permission errors, try:

pip install --user .
pip install --user -r requirements.txt

Development

Remember to activate your virtual environment (source valpas-env/bin/activate) every time you work on this project.

Running the notebook

Within a browser

To start the jupyter server and initialize the notebook the virtual environment has to be activated first. This can be done by invoking from within the root of the git-repository via:

source valpas-env/bin/activate

Next the jupyter server has to be booted up. This is done via the command:

jupyter notebook

The command will also automatically open a browser window and redirect to http://localhost:8888/ from where the actual jupyter notebook can be opened.

Within VSCode

Running the notebook from within VSCode requires the installation of the Jupyter extension. For more on VSCodes notebook functionality also see here. After opening the git repository as folder in VSCode and opening the jupyter notebook, the previously installed virtual environment should be a selectable kernel option. If it is not available a restart of VSCode might help.