Skip to content

Installation

This guide will help you install CarrierCapture.py on your system.

System Requirements

  • Python 3.9 or later (Python 3.11-3.12 recommended)
  • pip package manager
  • Git (for development installation)

Platform Support

CarrierCapture.py works on:

  • Linux (tested on Ubuntu 20.04+)
  • macOS (tested on macOS 12+)
  • Windows (via WSL or native Python)

Quick Installation (PyPI)

Coming Soon

CarrierCapture.py will be available on PyPI. For now, install from source.

# Future release
pip install carriercapture

Installation from Source

1. Clone the Repository

git clone https://github.com/WMD-group/CarrierCapture.py.git
cd CarrierCapture.py

Using venv:

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

Using conda:

conda create -n carriercapture python=3.11
conda activate carriercapture

3. Install Package

For users:

pip install -e .

For developers:

pip install -e ".[dev]"

Optional Dependencies

Interactive Visualization

For the Dash dashboard and advanced plotting:

pip install carriercapture[viz]

This includes:

  • Plotly
  • Dash
  • Additional visualization tools

doped Integration

For defect calculation workflows with doped:

pip install carriercapture[doped]

This includes:

  • doped package
  • monty for serialization
  • pymatgen (already included in base install)

Documentation Building

For building documentation locally:

pip install carriercapture[docs]

Jupyter Notebooks

For running tutorial notebooks:

pip install carriercapture[notebook]

All Optional Dependencies

Install everything:

pip install -e ".[dev,docs,notebook,doped,viz]"

Verify Installation

After installation, verify that CarrierCapture works:

Check CLI

carriercapture --help

You should see the help message with available commands.

Check Python API

python -c "import carriercapture; print(carriercapture.__version__)"

Run Tests

pytest tests/ -v

Troubleshooting

Import Errors

If you get import errors, ensure your virtual environment is activated:

which python  # Should point to your venv
pip list | grep carriercapture  # Should show installed version

SciPy/NumPy Installation Issues

On some systems, you may need to install system dependencies first:

Ubuntu/Debian:

sudo apt-get install python3-dev gfortran libopenblas-dev liblapack-dev

macOS:

brew install gcc openblas lapack

Permission Denied

If you get permission errors, use pip install --user or create a virtual environment.

Windows-Specific Issues

On Windows, we recommend using Windows Subsystem for Linux (WSL) for the best experience. Alternatively, ensure you have:

  • Visual C++ Build Tools installed
  • Latest version of pip: python -m pip install --upgrade pip

Updating CarrierCapture

From Source

cd CarrierCapture.py
git pull
pip install -e . --upgrade

From PyPI (Future)

pip install --upgrade carriercapture

Uninstallation

To remove CarrierCapture:

pip uninstall carriercapture

Development Installation

For contributing to CarrierCapture, install in editable mode with all development tools:

git clone https://github.com/WMD-group/CarrierCapture.py.git
cd CarrierCapture.py
pip install -e ".[dev]"
pre-commit install  # Optional: set up git hooks

This installs:

  • pytest for testing
  • black, ruff for code formatting
  • mypy for type checking
  • All other development dependencies

Next Steps

Now that you have CarrierCapture installed, proceed to:

Getting Help

If you encounter issues during installation:

  1. Check the GitHub Issues
  2. Search for your error message
  3. Open a new issue with:
  4. Your operating system
  5. Python version (python --version)
  6. Error message
  7. Steps to reproduce