Installation#

This guide covers how to install airsspy and its dependencies.

Requirements#

  • Python 3.8 or later

  • pip or uv package manager

  • AIRSS buildcell executable (for structure generation)

Installing airsspy#

Using uv (faster, modern alternative)#

uv pip install airsspy

Development Installation#

For development or to get the latest version from source:

git clone https://github.com/zhubonan/airsspy.git
cd airsspy
pip install -e .[full,test,docs]

Or with uv:

git clone https://github.com/zhubonan/airsspy.git
cd airsspy
uv pip install -e .[full,test,docs]

Optional Dependencies#

airsspy has several optional dependency groups:

  • analysis: Pandas for data analysis

  • full: All optional dependencies (pandas, spglib)

  • test: Testing tools (pytest, pytest-cov)

  • docs: Documentation building tools (Sphinx, themes, extensions)

Install with optional dependencies:

pip install airsspy[full]

Installing AIRSS#

To generate random structures, you need the AIRSS buildcell executable.

Download and Build AIRSS#

  1. Download AIRSS from the official website

  2. Extract and build:

tar -xzf airss-*.tgz
cd airss-*
make
make install

  1. Add AIRSS binaries to your PATH:

export PATH=<airss root folder>/bin:$PATH

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

Verify Installation#

Check that buildcell is accessible:

which buildcell

Dependencies#

airsspy depends on:

  • ase - Atomic Simulation Environment

  • castepinput (≥0.1) - CASTEP input file handling

  • numpy (≥1.20) - Numerical computing

  • pymatgen (≥2022.0.0) - Interface for reading SHELX files

These are automatically installed when you install airsspy.

Verifying Installation#

Test your installation:

import airsspy
print(airsspy.__version__)

# Test creating a seed
from airsspy import SeedAtoms
seed = SeedAtoms('C4', cell=[5, 5, 5], pbc=True)
print("airsspy is working!")

Troubleshooting#

buildcell not found#

If you get an error about buildcell not being found:

  1. Check that AIRSS is installed: which buildcell

  2. Ensure AIRSS bin directory is in your PATH

  3. Try specifying the full path to buildcell if needed

Import errors#

If you encounter import errors:

  1. Verify you’re using Python 3.8 or later: python --version

  2. Try installing in a fresh virtual environment

  3. Ensure all dependencies are installed: pip install airsspy[full]

Next Steps#

Now that airsspy is installed, continue to the Quickstart Tutorial to perform your first structure search.