Welcome to CSSlib 👋

CSSlib is an open-source code for building configuration search space (CSS) of disordered crystals, loading of the CSS dataset obtained, local/remote MPI or SLURM calculations and data visualization.

Table of content

• Installation
• Agent plugin
• Contributors
• Tutorial
• References & Citing

Installation

CSSlib can be installed through

1. the pip package manager (in the virtual environment):

pip install csslib

2. the git clone command:

git clone https://github.com/AIRI-Institute/CSSlib.git CSSlib
cd CSSlib
pip install .

3. the uv package manager:

uv venv .venv
source .venv/bin/activate
uv pip install csslib

CSSlib requires Python 3.11–3.14. To work through the tutorial notebook, install the separate tutorial dependencies:

pip install "csslib[tutorial]"

For a local editable checkout, use pip install -e ".[tutorial]". The tutorial pipeline diagram also requires the Graphviz executable to be installed and available on PATH.

CSSlib depends on the lightweight pymatgen-core distribution. It provides the same pymatgen.* import paths used by CSSlib without installing the unrelated high-level analysis packages.

Candidate interstitial sites remain explicit placeholder species in the input CIF and must be listed in fictive_atoms. CSSlib can now construct such a candidate sublattice directly, without pymatgen-analysis-defects:

from csslib import generate_interstitial_structure

structure = generate_interstitial_structure(
    "host.cif",
    fictive_atom="Np",
    output_filename="host_interstitial.cif",
)

for site in structure:
    if site.label.startswith("Np"):
        print(site.label, site.frac_coords)

Symmetry-equivalent positions receive the same label (Np0, Np1, and so on), so the generated CIF can be passed to the existing CSS pipeline with "fictive_atoms": ["Np"]. Existing output files are protected unless overwrite=True is passed.

The search uses vertices of a periodic Voronoi tessellation and reports geometric candidates only. It can miss relevant positions on Voronoi faces or edges and does not establish that an interstitial defect is energetically stable. The defaults min_distance=0.9 Å and clustering_tolerance=0.5 Å are numerical filters, not universal physical radii; adjust them for the host structure and intended impurity.

CSSlib by default requires Supercell program. Details on Supercell installation can be found at the corresponding website.

As a calculator for quantum mechanical calculations, CSSlib assumes the use of the VASP (Vienna Ab initio Simulation Package) software package. Also there is an optional dependency for the QuantumEspresso simulation package which can be installed after the normal installation as:

pip install --group espresso .

or

uv sync --group espresso

Agent plugin

The project-local csslib-agent Codex plugin exposes eleven MCP tools covering provenance-aware MP/AFLOW acquisition, CIF inspection, constrained CSS estimation/generation, dataset selection/do-selection, calculation planning/preflight, and calculation launch/status/cancel/resume.

Install CSSlib with the stable MCP v1 extra before loading the plugin directory in Codex:

pip install -e ".[agent]"

Materials Project acquisition is a deliberately separate optional dependency because mp-api brings the full MP client stack:

pip install -e ".[agent,sources]"

CSS generation follows an inspect_cif → estimate_css_space → generate_css gate. The request must explicitly enable or disable charge/composition constraints; oxidation states are never inferred. Estimates include pre-symmetry configuration count, conservative storage/planning-memory bounds, free disk, and Supercell availability.

Calculations follow a plan_calculation → preflight_calculation → run_calculation gate. Preflight checks disk reserve, best-effort remote quota, the exact launcher and VASP/QE executable, parser support, and live scheduler capacity. Running work can be monitored, cancelled, and resumed safely within the same MCP server process; status is atomically checkpointed to calculation_state.pkl.gz.

Remote passwords, private-key passphrases, and Materials Project API keys are not accepted as tool arguments. Use SSH agent or the documented CSSLIB_SSH_PASSWORD, CSSLIB_SSH_KEY_PASSPHRASE, and MP_API_KEY environment variables outside chat.

See csslib-agent/TESTING.md for automated tests and safe manual smoke scenarios.

Contributors

• Aleksey Krautsou
• Aleksandr Solovykh

Tutorial

The best way to learn how to use CSSlib is through the tutorial notebook located at the tests directory or at the google collab. Install it from a local checkout with pip install -e ".[tutorial]" before starting JupyterLab.

References & Citing

If you use this code, please consider citing works that actively used the CSS approach, which resulted in the creation of this library:

1. A.V. Krautsou, I.S. Humonen, V.D. Lazarev, R.A. Eremin, S.A. Budennyy
   "Impact of crystal structure symmetry in training datasets on GNN-based energy assessments for chemically disordered CsPbI₃"
   https://doi.org/10.1038/s41598-025-92669-3
2. N.A. Matsokin, R.A. Eremin, A.A. Kuznetsova, I.S. Humonen, A.V. Krautsou, V.D. Lazarev, Y.Z. Vassilyeva, A.Y. Pak, S.A. Budennyy, A.G. Kvashnin, A.A. Osiptsov
   "Discovery of chemically modified higher tungsten boride by means of hybrid GNN/DFT approach"
   https://doi.org/10.1038/s41524-025-01628-z
3. R.A. Zaripov, R.A. Eremin, I.S. Humonen, A.V. Krautsou, V.V. Kuznetsov, K.E. GermanS, S.A. Budennyy, S.V. Levchenko
   "First-principles data-driven approach for assessment of stability of Tc-C systems"
   https://doi.org/10.1016/j.actamat.2025.121704