vibe-sketcherDocumentation

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, poscar

yes

yes

Kresse and Furthmüller, Phys. Rev. B 54, 11169 (1996); VASP wiki, POSCAR

Extended XYZ

implemented, extxyz

one frame

yes

Larsen et al., J. Phys.: Condens. Matter 29, 273002 (2017)

DFTB+ GEN

implemented, gen

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= and pbc=, and the format is chosen by the caller, never by the .xyz extension.

  • A GEN type name must be an element symbol. A label such as Si1 is 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, --reduced or ?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/.qvf name.

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) or Cartesian (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_pv or Fe/1a2b keep the element before _ or /, and the full labels are recorded. Species runs are written in site order, so Si O Si repeats 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 dynamics with F F F becomes a fixed site (provenance["builder"]["fixed_sites"]), and fixed sites are written that way. Mixed flags such as T F T are 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 optional Origin="x y z".

  • PBC: pbc="T T F" is required and kept exactly, so 1-D and 2-D models round trip. F F F is a molecule and is refused here.

  • Elements: the species:S:1 column, which must hold element symbols.

  • Site IDs: a site_id:S:1 column is written and read. Without it, sites are numbered by element.

  • Charge/spin: charge= and multiplicity= 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:1 with F (ASE’s convention for fixed atoms) or move_mask:L:3 with F F F is a fixed site; fixed sites are written as move_mask:L:1. A partial three-column mask is refused.

  • Other data: other columns and keys, such as forces or energy, are results, not structure. They are not kept. Their names are listed under provenance["builder"]["ignored"] and reported as a warning. Zero velocities or momenta are 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. S gives Cartesian angstrom and F fractional 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) and H (helical) are refused.

  • Origin: read and recorded. S positions are taken relative to it. The writer uses F with 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/formats lists the implemented formats and what they carry.

  • POST /api/documents/{id}/periodic/import-format takes revision, format, text and identifier. A stale revision returns 409 and a refusal 422.

  • GET /api/documents/{id}/periodic/{structure}/format/{format}?reduced=false returns text, losses and reduced. It never changes the document.

  • The MCP tools are import_periodic_format and export_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.