# 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 pip (recommended for users)

```bash
pip install airsspy
```

### Using uv (faster, modern alternative)

```bash
uv pip install airsspy
```

### Development Installation

For development or to get the latest version from source:

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

Or with uv:

```bash
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:

```bash
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](http://www.mtg.msm.cam.ac.uk/Codes/AIRSS)

2. Extract and build:

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

3. Add AIRSS binaries to your PATH:

```bash
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:

```bash
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:

```python
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](quickstart.md) to perform your first structure search.