xtalforge-core 1.5.1

Core crystal-structure types for xtalforge: elements, lattices, sites and structures.
Documentation

xtalforge

A pure Rust library for building, manipulating, analysing and exporting crystal structures, with a CLI, Python bindings and WebAssembly bindings developed at parity with the Rust API.

Status: 1.5.1 published on 2026-11-13. Phases 0-11 are complete and the Phase 12 binding work shipped in 1.5.0; Tasks 12.1.4 (progress and cancellation), 12.3.5 (optional threads) and 12.4.1 (tutorial, playground and benchmark) remain open. The public API is frozen; later changes follow the SemVer policy in docs/api/stability.md. 1.5.0 added the object-oriented Python and WASM APIs, NumPy/typed arrays, typed result classes, batch helpers and the typed TypeScript interface; 1.5.1 is the icon and package-metadata patch. The known reference gaps are listed in docs/roadmap/index.md. The plan is in docs/roadmap; the project rules are in AGENTS.md.

What works today

  • Crystal structures: elements, lattices, sites, P1 expansion, supercells, slabs, transforms, periodic neighbours, bond graphs, rings and measures.
  • Symmetry: space-group detection, Wyckoff positions, standard and primitive cells, lattice reduction, subgroups, layer and magnetic groups, molecular point groups, Brillouin zones and band paths.
  • Formats and editing: CIF, POSCAR, XYZ, pymatgen JSON, CSSR, GEN, LAMMPS, SHELX and PDB; atomic writes, project archives, undo/redo documents, selections, workspace runs and scene data.
  • Force fields and thermodynamics: native UFF/UFF4MOF, QEq/EQeq/EEQ charges, Ewald, FIRE/L-BFGS, scans, Gamma-point vibrations, IR, thermochemistry and quasi-harmonic free energies.
  • MOF platform: checker and solvent removal, deconstruction into nodes and linkers, RCSR topology, MOFid/MOFkey, open metal sites, native pore descriptors, UFF/EQeq-TraPPE adsorption, Widom/GCMC, PSM, defects, interpenetration, CoRE MOF/QMOF readers and screening.
  • Core crystal features: structure matching and RMSD, strain and rattle, site editing and interpolation, Voronoi and coordination environments, bond-valence sums and oxidation states, RDF and fingerprints, unique Miller indices, slab terminations, Wulff shapes, adsorption sites, point defects, orderings and SQS, interfaces, elastic tensors, EOS fits and convex hulls.
  • Analysis and builders: PXRD, porosity, isosurfaces, nets, RCSR matching, graphene, nanotubes, fullerenes, SMILES embedding, polymers, MOF assembly and powder refinement.
  • Agent layer: session verbs, diagnostics, change bursts, SVG/PNG pictures, MCP over stdio and skill documents; open extension registries.
  • Machine learning: the Python ASE bridge for MACE, ORB-v3 and MatterSim, with a checksum-verified model cache.
  • Four surfaces at parity, with documented exceptions for the filesystem, subprocesses and threads in WASM. See docs/api/parity.md.

Install

Install the current release:

cargo add xtalforge@1.5.1
pip install xtalforge==1.5.1
npm install xtalforge-wasm@1.5.1

Goals

  • Everything the headless core of Crystal-Builder does: symmetry-aware structure editing, file formats, force fields and optimizers, PXRD, porosity, topology, builders (molecules, carbons, polymers, MOFs) and powder refinement.
  • Symmetry through moyo.
  • Proven code reused from sci-form.
  • Four surfaces at parity: Rust (xtalforge crate), CLI (xtalforge binary), Python (xtalforge on PyPI), WebAssembly (xtalforge-wasm on npm).
  • Documentation site built with VitePress (docs/).

Working on the project

scripts/check-rules.sh                 # 500-line limit and warning-suppression checks
cargo clippy --workspace --all-targets -- -D warnings
cd docs && npm install && npm run docs:dev

See docs/guide/contributing.md for the full checklist and the roadmap workflow.

License

Licensed under either of

at your option. Third-party code and data: THIRD_PARTY.md.