xtalforge-core 1.5.1

Core crystal-structure types for xtalforge: elements, lattices, sites and structures.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

<p align="center">
  <img src="https://raw.githubusercontent.com/jigonzalez930209/xtalforge/main/assets/xtalforge.png" alt="xtalforge" width="128" height="128">
</p>

# 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`](docs/roadmap/index.md). The plan is in
> [`docs/roadmap`](docs/roadmap/index.md); the project rules are in
> [`AGENTS.md`](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:

```bash
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](https://github.com/JulesOpp/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](https://github.com/spglib/moyo).
- Proven code reused from [sci-form](https://github.com/jigonzalez930209/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

```bash
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`](docs/guide/contributing.md) for the full
checklist and the roadmap workflow.

## License

Licensed under either of

- Apache License, Version 2.0 ([`LICENSE-APACHE`](LICENSE-APACHE))
- MIT license ([`LICENSE-MIT`](LICENSE-MIT))

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