Skip to main content

Xtalate

CI Version Python 3.11+ Ruff License: Apache-2.0

A loss-aware converter for computational-chemistry file formats — it tells you exactly what each conversion kept, dropped, or had to fabricate, and proves it.

Every conversion produces a Conversion Report (what was preserved, dropped, or supplied — with a reason for each) and a Validation Report (the output re-parsed and diffed against the source). The rule behind the whole tool: never silently lose scientific information. If you diffed the input and output by hand, nothing should surprise you that Xtalate didn't already flag.

Install

pip install xtalate

Python ≥ 3.11. ASE is the only scientific dependency.

Quickstart

See what's inside a file before touching it:

xtalate inspect water_traj.xyz

Convert it. This XYZ trajectory has no lattice, and POSCAR needs one structure and a cell — so you supply those two choices explicitly, and each is recorded as an Assumption:

xtalate convert water_traj.xyz --to poscar -o POSCAR \
    --recover frame_selection=last \
    --recover missing_lattice=bounding_box,padding_ang=5.0
Conversion Report  [completed]
  xyz → poscar
  preserved: atoms.symbols, atoms.positions
  supplied:  cell.lattice_vectors, cell.pbc
  assumptions:
    ~ A1 frame_selection=last          frame 1 of 2 retained
    ~ A2 missing_lattice=bounding_box   axis-aligned box + 5.0 Å padding

Validation Report  [passed]  (tolerance: default)
  ✓ atom_count · ✓ species_preservation · ✓ positions_rmsd · ✓ lattice_consistency …

Leave out the --recover flags and the command refuses, printing the exact decisions it needs — a refusal is a reported outcome, never a silent default. Exit codes make it CI-native (0 ok · 2 refused · 3 validation failed · 4 parse error · 5 strict-mode warnings · 1 usage), and --json on any command emits the report schema verbatim.

Full CLI reference · library example.

Supported formats

Format Read Write Notes
XYZ ✓ ✓ Plain coordinates
extended XYZ ✓ ✓ ASE-backed; MLIP labels (energy, forces, stress)
POSCAR / CONTCAR ✓ ✓ VASP structure; CONTCAR keeps the velocity block
XDATCAR ✓ ✓ VASP trajectory
ASE .traj ✓ ✓
CIF ✓ ✓ Symmetry from declared operations; site occupancy is first-class
LAMMPS dump ✓ ✓ MD trajectory; unit system resolved explicitly
LAMMPS data ✓ ✓ Input / restart; atom style resolved explicitly
Quantum ESPRESSO pw.x input ✓ ✓ Namelists + cards
ASE .db ✓ ✓ Multi-structure dataset
DeePMD-kit npy ✓ ✓ Directory system; MLIP training layout
vasprun.xml ✓ — VASP output (source only)
OUTCAR ✓ — VASP output; per-atom magnetic moments
Quantum ESPRESSO pw.x output ✓ — QE output (source only)

Read-only formats are conversion sources, never targets — a code's output is never something Xtalate writes back. In-memory adapters also translate pymatgen Structure/Molecule objects (pip install "xtalate[pymatgen]"), and CP2K is available through the community-plugin seam. Any pair of read+write formats converts; the nightly suite runs the full n×n matrix.

These formats close the MLIP data loop end to end — relabel production frames with DFT (OUTCAR/vasprun.xml/QE output → extended XYZ), assemble them into a dataset (ase_db, deepmd_npy), and deploy back to an engine (LAMMPS) — every arrow a reported, validated conversion.

What every conversion gives you

  • Inspect first. A ✓/✗ inventory of which canonical fields a file actually holds, each annotated with the format's capability — no conversion needed.
  • Loss predicted before writing. A per-format Capability Matrix tells the exporter what the target can hold before it writes (P5).
  • Recovery is explicit, never guessed. When a target needs a field the source lacks, you choose a preset and it becomes an Assumption; with no choice, the conversion refuses rather than invent data (P4).
  • Validation is not optional. Every conversion is re-parsed and diffed against the source under a tolerance profile (default / strict / loose, or a custom table). There is no switch to skip it.
  • Absence is information (P3). The model distinguishes "the source never had this" (None) from "the source had it, and the value is zero." Parsers never default an absent field.
  • Scales to large trajectories. A frame-chunked streaming core keeps memory sub-linear in frame count; a 10⁴-frame XDATCAR streams at roughly constant memory and yields a byte-identical report.
  • Extensible by plugins. A parser, exporter, or analysis plugin in a separate package is discovered through Python entry points (xtalate.parsers / xtalate.exporters / xtalate.analysis) with no fork or edit. First-party formats and plugins hold no privileged API.

Beyond the CLI

The same engine drives four surfaces; the scientific logic lives in the engine and nowhere else.

Library:

from xtalate.registry import default_registry
from xtalate.conversion import ConversionEngine

registry = default_registry()
with open("in.extxyz", "rb") as fh:
    source = registry.get_parser("extxyz").parse(fh, filename="in.extxyz").canonical

result = ConversionEngine(registry).convert(
    source, source_format_id="extxyz", target_format_id="poscar",
)
print(result.report.model_dump_json(indent=2))   # the Conversion Report
print(result.validation.status)                   # "passed"

HTTP service — a FastAPI app exposing the engine as async jobs under /v1:

pip install "xtalate[service]"
python -m backend                       # http://localhost:8000
# or the full stack (API, worker, Postgres, MinIO, Redis):
docker compose up --build --wait

A refusal comes back as a completed HTTP-200 job, not an error; reports outlive the bytes they describe. The curl walkthrough is in docs/API.md, and the machine-readable contract is docs/openapi.json.

Web UI — a Next.js front end over /v1 that walks upload → inspect → convert → recover → download, rendering the engine's reports verbatim (no scientific logic of its own). Self-hosting is the primary deployment; see the self-hosting guide.

Seeing what the report says (v1.6). The Web UI also shows the structures the reports describe, from the same canonical data — a Structure tab renders the file or a conversion's output in 3D (species legend, the unit-cell wireframe only when a cell is present, a fabricated lattice drawn in the ◆ assumption violet with its Assumption one click away), a frame scrubber plays multi-frame trajectories frame by frame with no invented time axis, and the Compare tab on a conversion record puts the source and the re-parsed output side by side: the Validation Report's own RMSD, the dropped fields' reasons verbatim, and the supplied-violet marker on the output the source lacks — see what the report says was fabricated. Bonds are a display heuristic, off by default, in no report ever. The viewer is a viewer, not an editor: measurement, selection, and rendering export are deliberate omissions, and accessibility is honest — the reports are the accessible record, the viewer is an additional presentation.

Repairing on request (v1.7). v1.7 is File Repair — explicit, chosen, recorded modification, never silent fixing. Four operations — wrap-into-cell, center, deduplicate, and species reorder — modify a Canonical Object between parse and pre-flight, each applied in the order you ask, each recorded as an Assumption with its complete parameters, so every repaired conversion is reproducible from its report alone. Repair is never automatic, and no report ever says "fixed": the report says what changed, to which atoms, by whose request — a repaired conversion's rows carry the ⟳ "Modified on request" mark, a blue mark deliberately distinct from the ◆ violet of fabricated data, because a transformed coordinate is not a fabricated one. The flagship: an unwrapped MD trajectory wrapped into its cell on request carries the R5 warning that wrapping discards unwrapped diffusion paths — see what the report says was changed, then reproduce it byte-for-byte from the report's own recorded parameters. The operation set is closed at four, and the boundary is honest: byte-level repair stays with parse-time recovery — a file that cannot become a Canonical Object cannot be repaired, only recovered. Xtalate remains not a molecular editor: modification is a bounded, recorded, user-initiated act, never a tool the pipeline applies on its own.

Analyzing on request (v1.8). v1.8 is the Analysis Plugin Surface — a stable, third-party way to read a Canonical Object and annotate its own namespace, without touching the core and without ever changing what Xtalate converts, reports, or validates. A plugin is a name, a version, and one analyze() method (see docs/DEVELOPER_GUIDE.md §8); pip install it and default_registry() discovers it through the xtalate.analysis entry point, exactly like a parser. Results are contained to the plugin's own "<name>:" namespace structurally, not on trust — the runner hands the plugin a deep copy and merges only its own keys into user_metadata.custom_global, recording the run in Provenance — and every consumer renders them generically: xtalate analyze FILE --plugin <name>, POST /v1/analyze, and the Web UI's Analysis tab all walk the results by JSON value type with no branching on any plugin or key, so a third-party plugin renders through the same path as the first-party one. The reference plugin, xtalate-analysis-composition, is deliberately the only first-party analysis — element counts, a formula, and a mass density reported only when the source actually carries a cell and masses (and null with a stated reason otherwise, never fabricated). What is not first-party — radial distribution functions, coordination numbers, trajectory statistics, and anything ML (descriptors, uncertainty quantification, learned frame selection) — is yours to build as a plugin: the surface is the answer, and the core neither bundles nor blesses any of it. Xtalate stays a converter, not an analysis package; analysis is a consumer of the Canonical Model that attaches at a defined seam.

Batch — xtalate convert --batch manifest.yaml -o out/ (and POST /v1/batch/convert) converts a whole directory into one record: each file's reports embedded verbatim, tallies on top, one file's failure never aborting the rest. Selection, splitting, and deduplication are deliberately out of scope — curation is a scientific judgment, conversion is a translation.

How it works

Native File → Format Sniffer → Parser → Canonical Object → Exporter → Target Format
                                             ↑        ↓
                         Information Discovery   Capability Matrix
                         Recovery Engine (explicit only) → Validation Engine

The Canonical Object is the only thing that crosses the parser/exporter boundary — no parser calls another parser, and no conversion takes a format-to-format shortcut (P2). That single spine makes adding a format O(1) in the number already present: each new format is one parser, one exporter, and a Capability Matrix row, joining sniffing, discovery, conversion, and validation without touching any other format.

Design and principles: docs/ARCHITECTURE.md · library/CLI surface: docs/API.md · building and extending: docs/DEVELOPER_GUIDE.md.

Versioning

Xtalate follows Semantic Versioning. Within a major series a named public surface — the canonical schema, the report schemas, the plugin SDK, the /v1 REST surface, and the documented CLI — evolves additively only: new formats, scenarios, and optional fields arrive with safe defaults, and nothing already documented is removed or given a new meaning. The _-prefixed internal surface is not part of the contract.

The product version and the on-the-wire schema_version move on separate axes: the schema version bumps only when the model changes, and always behind a real migration that carries older stored objects forward with a recorded migrate step — never silently.

Development

pip install -e ".[dev]"
ruff check . && ruff format --check .    # lint + format
mypy                                     # types (strict)
lint-imports                             # acyclic package layering (P2)
pytest                                   # tests

CI runs on Python 3.11 and 3.13, plus corpus governance over both corpus roots and a coverage ratchet.

Contributing

Contributions are welcome — see CONTRIBUTING.md. The invited path is corpus contributions: real, licensed sample files that harden the converter. A golden case (tests/golden/) asserts what a file should produce; a wild case (tests/wild/) is a real third-party file asserting what it does produce. Both need a manifest and a license — no manifest, no license, no merge. Parser plugins are welcome too; the plugin SDK is a stable contract.

License

Apache-2.0 — see LICENSE and NOTICE.

Metadata

Release files for xtalate 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xtalate 1.8.0
File Size Uploaded Provenance Actions
xtalate-1.8.0.tar.gz 2.6 MB Without provenance Details for xtalate-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtalate 1.8.0
File Interpreter ABI Platform Actions
xtalate-1.8.0-py3-none-any.whl Python 3 none any Details for xtalate-1.8.0-py3-none-any.whl

Total release size: 3.1 MB

Release files / xtalate-1.8.0.tar.gz

Download URL xtalate-1.8.0.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
c1095e31a375449b7b57c733081a2c2bc849d7f04a7f6c9c85802b412ca85102
BLAKE2b-256 checksum
How to use checksums
77c34ea89d4c726d231a502e591003325c151bea8b4693a5cd37e9e3fc59e74f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / xtalate-1.8.0-py3-none-any.whl

Download URL xtalate-1.8.0-py3-none-any.whl
Size 538.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ecbad2a8d05b946351576149821eb381578dfe579a85bae896deeb648f433073
BLAKE2b-256 checksum
How to use checksums
6e4b72cac1bc76ad026267ea2b037d901d8410947a2b2847f21fe107a727427f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for xtalate 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page