Installation#

PVDeg releases may be installed using pip. Compatible with Python 3.10 and above.

For a quick start, see the Installation section in our README.md.

Base Install#

To install PVDeg with core functionality:

pip install pvdeg

This installs PVDeg with all required dependencies for basic degradation modeling, including:

PVDeg offers optional dependency groups for specific use cases. You can install these using the bracket syntax:

pip install pvdeg[group_name]

sam - System Advisor Model Integration

Adds NREL-PySAM for detailed system performance modeling and integration with SAM. Required for agrivoltaics and advanced system modeling workflows.

pip install pvdeg[sam]

docs - Documentation Building

Installs tools for building Sphinx documentation including:

pip install pvdeg[docs]

test - Testing and Validation

Includes pytest, pytest-cov, nbval for notebook validation, and scikit-learn for testing. Essential for contributors running the test suite.

pip install pvdeg[test]

books - Jupyter Book Publishing

Adds jupyter-book for building and publishing tutorial documentation.

pip install pvdeg[books]

all - Everything

Installs all optional dependencies above. Recommended for developers.

pip install pvdeg[all]

While PVDeg is installed via pip, you can use conda to manage your Python environment:

Create a new conda environment:

conda create -n pvdeg python=3.11
conda activate pvdeg

Install PVDeg with pip:
```
pip install pvdeg[all]
```
Register the environment as a Jupyter kernel (important for HPC systems):
```
python -m ipykernel install --user --name=pvdeg
```
This allows you to select the pvdeg kernel when running Jupyter notebooks, especially important on HPC systems like NREL’s Kestrel.

If you want to contribute to PVDeg or modify the source code, install in editable mode:

Fork the repository on GitHub and clone your fork:

git clone https://github.com/YOUR-USERNAME/PVDegradationTools.git
cd PVDegradationTools

Create and activate a virtual environment:

Using venv (Python standard library):

python -m venv pvdeg-dev
source pvdeg-dev/bin/activate  # On Windows: pvdeg-dev\Scripts\activate

Or using conda:

conda create -n pvdeg-dev python=3.11
conda activate pvdeg-dev

Install in editable mode with all dependencies:
```
pip install -e .[all]
```
The -e flag installs the package in “editable” mode, meaning changes you make to the source code are immediately reflected without reinstalling.
Install pre-commit hooks for code quality checks:
```
pre-commit install
```
This will automatically run code formatting (black) and linting (flake8) before each commit.
(Optional but recommended for HPC) Register the kernel for Jupyter:
```
python -m ipykernel install --user --name=pvdeg-dev
```
Verify your installation by running the test suite:
```
pytest pvdeg
```

For complete developer guidelines including contribution workflow, code style, and testing requirements, see Contributing.

Import errors after installation: Make sure you’re in the correct environment and that the installation completed successfully. Try pip list | grep pvdeg to verify the package is installed.
HPC/Kestrel Jupyter kernel issues: If your environment doesn’t appear in Jupyter on HPC systems, ensure you’ve run: python -m ipykernel install --user --name=your-env-name
Dependency conflicts: Use a fresh virtual environment if you encounter version conflicts with existing packages.
Cartopy installation issues: Cartopy requires GEOS and PROJ libraries. On some systems, you may need to install these via conda: conda install -c conda-forge cartopy

Python: 3.10, 3.11, 3.12, 3.13
Operating Systems: Linux, macOS, Windows
Key Dependencies:
- pvlib >= 0.12.0
- numpy >= 1.19.3
- pandas (compatible versions)
- h5py <= 3.14.0 (pinned due to compatibility issues)

For the most up-to-date compatibility information, see the pyproject.toml file in the repository.