Periodic interchange formats¶
Solid-state workflows pass structures between programs in small text formats. Each one carries less than a vibe-sketcher periodic structure, so each adapter states what it reads, what it writes and what it refuses (#209). VSK and QVF stay the native, complete saves. An export in one of these formats is a separate, deliberately reduced copy: it never replaces or changes the document it came from.
Three formats are implemented, in pure Python with no extra dependency: POSCAR/CONTCAR, extended XYZ and DFTB+ GEN. SHELX RES, periodic PDB, CSSR and LAMMPS data were assessed below and are not implemented. No command, endpoint or tool offers them.
Status¶
Format |
Status |
Read |
Write |
Reference |
|---|---|---|---|---|
POSCAR / CONTCAR (VASP 5) |
implemented, |
yes |
yes |
Kresse and Furthmüller, Phys. Rev. B 54, 11169 (1996); VASP wiki, POSCAR |
Extended XYZ |
implemented, |
one frame |
yes |
Larsen et al., J. Phys.: Condens. Matter 29, 273002 (2017) |
DFTB+ GEN |
implemented, |
S and F types |
F type |
Hourahine et al., J. Chem. Phys. 152, 124101 (2020); DFTB+ manual, Gen format |
SHELX RES/INS |
assessed, not implemented |
no |
no |
Sheldrick, Acta Cryst. C71, 3 (2015) |
Periodic PDB (CRYST1) |
assessed, not implemented |
no |
no |
wwPDB format guide 3.3 |
CSSR |
assessed, not implemented |
no |
no |
CCDC CSSR description |
LAMMPS data |
assessed, not implemented |
no |
no |
LAMMPS manual, read_data |
The three adapters were qualified against ASE 3.29.0 in both directions. ASE read the sketcher’s triclinic and slab exports, and the sketcher read ASE’s files of a fixed-bottom Al(111) slab. The cells, positions, species, PBC and fixed atoms agreed. ASE is not a dependency of vibe-sketcher.
The contract¶
Reading never guesses.
POSCAR without a species names line (VASP 4) is refused. The species are not taken from the comment line or a POTCAR.
A plain XYZ is never treated as periodic. Its comment is never read for a cell. Extended XYZ needs an explicit
Lattice=andpbc=, and the format is chosen by the caller, never by the.xyzextension.A GEN type name must be an element symbol. A label such as
Si1is refused rather than mapped.Partial occupancy, per-axis constraints, magnetic moments, per-site charges, isotopic masses and nonzero velocities cannot be held by the model. They are refused, with the line number, not dropped.
Left-handed or singular cells are refused; reflecting one would invert the structure.
Writing fails closed.
Partially occupied sites are always refused. Resolve the disorder first.
Anything else a format cannot carry is a loss. Losses include image bonds, parent mappings, a nonperiodic axis, site IDs, fixed sites, charge, spin, the space-group description, the cell-setting label and measured anisotropic displacement tensors (none of the three formats has a field for them; CIF export keeps them). The writer refuses them unless you ask for a reduced export (
reduced=True,--reducedor?reduced=true). It then returns the list of losses with the text.Every written text is read back and compared with the structure before it is returned. The comparison covers the lattice, species, positions and every field the format claims to carry.
The CLI refuses to write an export over the source document or to a
.vsk/.qvfname.
What each format carries¶
POSCAR / CONTCAR¶
Units and convention: lattice vectors are rows in angstrom, multiplied by the scaling line. One positive factor scales the whole cell. One negative value is the target cell volume in ų. Three factors scale the x, y and z components. Positions are
Direct(fractional) orCartesian(angstrom, scaled too).PBC: always periodic in three directions. A 2-D slab is written only as a reduced export that loses its nonperiodic flag. A vacuum-padded 3-D slab is lossless.
Origin: none; fractional coordinates are relative to the cell.
Elements: from the species names line. VASP 6 POTCAR labels such as
Zn_pvorFe/1a2bkeep the element before_or/, and the full labels are recorded. Species runs are written in site order, soSi O Sirepeats a species; each run then needs its own POTCAR entry.Site IDs: none. Reading numbers sites by element (
Si1,O1,Si2). Other IDs are a loss.Charge/spin: none; they belong to INCAR (
NELECT,MAGMOM).Occupancy/ADPs: none.
Image bonds: none.
Constraints:
Selective dynamicswithF F Fbecomes a fixed site (provenance["builder"]["fixed_sites"]), and fixed sites are written that way. Mixed flags such asT F Tare refused.Cannot carry: velocities, the MD predictor-corrector block and lattice velocities. A CONTCAR whose velocities are all zero is read. Nonzero velocities are refused.
Extended XYZ¶
Units and convention:
Lattice="ax ay az bx by bz cx cy cz"gives rows a, b, c in angstrom. Positions are Cartesian angstrom, measured from an optionalOrigin="x y z".PBC:
pbc="T T F"is required and kept exactly, so 1-D and 2-D models round trip.F F Fis a molecule and is refused here.Elements: the
species:S:1column, which must hold element symbols.Site IDs: a
site_id:S:1column is written and read. Without it, sites are numbered by element.Charge/spin:
charge=andmultiplicity=on the comment line.Occupancy/ADPs: none. Occupancy, charge, magnetic-moment, mass and spin columns or keys are refused.
Image bonds: none.
Constraints:
move_mask:L:1withF(ASE’s convention for fixed atoms) ormove_mask:L:3withF F Fis a fixed site; fixed sites are written asmove_mask:L:1. A partial three-column mask is refused.Other data: other columns and keys, such as
forcesorenergy, are results, not structure. They are not kept. Their names are listed underprovenance["builder"]["ignored"]and reported as a warning. Zerovelocitiesormomentaare read; nonzero ones are refused. Only one frame is read.
DFTB+ GEN¶
Units and convention: the first line is the atom count and the type.
Sgives Cartesian angstrom andFfractional positions. The origin and three lattice rows in angstrom follow the atoms.#starts a comment.PBC: periodic in three directions. Type
C(cluster, no cell) andH(helical) are refused.Origin: read and recorded.
Spositions are taken relative to it. The writer usesFwith origin 0 0 0.Elements: the type-name line, which must hold element symbols.
Site IDs, charge/spin, occupancy, image bonds, constraints: none; each is a loss on export.
SHELX RES/INS (not implemented)¶
CELL gives the wavelength, a, b, c (Å), α, β and γ (°). LATT, SYMM and
SFAC give the centring, the operators and the element list. Atom lines hold
fractional coordinates, a site occupation factor and U values (Ų). The site
occupation factor can be tied to free variables (FVAR), and PART
groups disorder. Hydrogen positions and restraints come from AFIX, DFIX
and similar instructions, which are refinement directives, not structure. A
reader needs the space-group expansion of the CIF importer and a decoder for
free variables, with every disorder decision refused or recorded. ADPs
cannot be stored in the model. Writing would lose bonds, PBC masks and IDs
beyond four characters.
Periodic PDB (CRYST1; not implemented)¶
CRYST1 holds a, b, c (Å), α, β, γ (°), a Hermann-Mauguin space-group
symbol and Z. Coordinates are orthogonal Cartesian angstrom, with the frame
set by SCALEn/ORIGXn. Elements sit in columns 77 to 78; without them,
the atom name would have to be guessed, and that would be refused. Occupancy
and B are per-atom columns, with ANISOU for ADPs. CONECT bonds carry no
lattice image. The fixed columns limit atom serials to 99,999. The
placeholder CRYST1 1.000 1.000 1.000 90.00 90.00 90.00 P 1 means “not
crystallographic” and must be refused as nonperiodic.
CSSR (not implemented)¶
CSSR is the Cambridge Structure Search and Retrieval format, used by porous-materials tools. Its lines give a, b, c (Å); α, β, γ (°) with a space-group number; the atom count with a coordinate flag (fractional or orthogonal); and a title. Atom lines give a serial number, a label, x, y and z, up to eight neighbour serials and a charge. Elements would have to be read from labels, and ambiguous labels would be refused. The neighbour list carries no lattice image. Partial charges are per site and cannot be stored.
LAMMPS data (not implemented)¶
The header gives counts and the box (xlo xhi, ylo yhi, zlo zhi, plus
xy xz yz tilt factors). That box is LAMMPS’s restricted triclinic frame: a
along x and b in the xy plane. Writing other cells would need a recorded
rotation. The length unit comes from the input script’s units, not the
file, so it would have to be stated. Atom types are integers; mapping them to
elements needs an explicit table, because Masses are ambiguous. Per-atom
charges (charge and full styles) and image flags are present. Bonds name
atom IDs without lattice images, and PBC (boundary) lives in the input
script.
SDK, CLI, REST and MCP¶
from vibesketcher.document import periodic_formats as pf
slab = pf.read(open("CONTCAR").read(), "poscar", identifier="slab")
copy = pf.write(slab, "extxyz") # lossless: copy.losses == []
gen = pf.write(slab, "gen", reduced=True) # gen.losses lists what GEN drops
vibe-sketcher solid import-format slab.vsk CONTCAR --format poscar --id slab
vibe-sketcher solid export-format slab.vsk --structure slab --format extxyz -o slab.extxyz
vibe-sketcher solid export-format slab.vsk --structure slab --format gen --reduced -o slab.gen
GET /api/periodic/formatslists the implemented formats and what they carry.POST /api/documents/{id}/periodic/import-formattakesrevision,format,textandidentifier. A stale revision returns 409 and a refusal 422.GET /api/documents/{id}/periodic/{structure}/format/{format}?reduced=falsereturnstext,lossesandreduced. It never changes the document.The MCP tools are
import_periodic_formatandexport_periodic_format.
read refuses a structure with more than 25,000 sites before reading any
coordinates, and the text is bounded like every other import.