airsspy Documentation#

Modern Python interface for AIRSS (Ab initio Random Structure Searching).

Getting Started

New to airsspy? Start here to learn installation and basic usage.

Getting Started
How-To Guides

Step-by-step guides for common tasks and workflows.

How-To Guides
Explanations

Understand AIRSS concepts, seed files, and buildcell parameters.

Explanations
API Reference

Complete API documentation for all modules and classes.

API Reference
Command Line

Reference for the installed ap command and local AIRSS workflows.

Command Line Interface

Quick Example#

from airsspy import SeedAtoms

# Create a seed for silicon structure search
seed = SeedAtoms('Si8', cell=[5, 5, 5], pbc=True)
seed.gentags.minsep = 2.0
seed.gentags.varvol = 20

# Generate a random structure
random_atoms = seed.build_random_atoms()

What is airsspy?#

airsspy provides a modern, Pythonic interface to AIRSS by:

  • Extending ASE’s Atoms class with AIRSS-specific features

  • Managing buildcell subprocess communication

  • Handling AIRSS/CASTEP .res file I/O and lossless RES/extxyz conversion

  • Running local searches, relaxations, single-points, and packed-file ranking

  • Deploying jobflow searches and querying stored results

Learn more →

Features#

  • ASE Integration: Seamless integration with the Atomic Simulation Environment

  • Modern Python: Type hints, clean API, Python 3.9+ support

  • Structure Generation: Generate random structures with flexible constraints

  • RES File Support: Read and write CASTEP .res files

  • Buildcell Interface: Full access to AIRSS buildcell parameters

  • CLI Workflows: ap run, ap rank, ap convert, ap pack, and jobflow database tools

Installation#

Install airsspy using pip:

pip install airsspy

For development installation with all dependencies:

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

See the Installation Guide for more details.