vibe-sketcherDocumentation

vibesketcher.document.periodic_formats

Periodic interchange adapters with explicit loss contracts (#209).

Three plain-text formats used by solid-state workflows, read and written in pure Python:

poscar

VASP POSCAR/CONTCAR, VASP 5 layout (species names line required). G. Kresse, J. Furthmueller, Phys. Rev. B 54, 11169 (1996); the layout is the one documented on the VASP wiki “POSCAR” page.

extxyz

Extended XYZ as written by ASE and libAtoms/QUIP: Lattice, Properties and pbc on the comment line. A. H. Larsen et al., J. Phys.: Condens. Matter 29, 273002 (2017).

gen

The DFTB+ “Gen” geometry format (S supercell and F fractional types). B. Hourahine et al., J. Chem. Phys. 152, 124101 (2020); layout from the DFTB+ manual, appendix “Gen format”.

The contract, the same for every format:

  • Reading never guesses. A POSCAR without a species names line, an XYZ without Lattice and pbc, or a GEN type name that is not an element is refused. Per-axis constraints, magnetic moments, per-site charges, isotopic masses, partial occupancy and nonzero velocities, which the model cannot hold, are refused with the line number.

  • Writing returns text only; it never changes or replaces the source document. Partial occupancy is always refused. Anything else the format cannot carry (image bonds, parent mapping, a nonperiodic axis, site IDs, fixed sites, charge/spin, the space-group description, anisotropic displacement tensors) is a loss: the writer refuses unless reduced=True, and then returns the list of losses with the text. Every written text is read back and compared before it is returned.

Unlisted formats (SHELX RES, periodic PDB, CSSR, LAMMPS data) are assessed in the manual but not implemented, and nothing here offers them.

Module Attributes

FORMATS

The implemented formats; nothing else is discoverable.

CAPABILITIES

What each format can carry beyond lattice, species and positions.

Functions

add_to_document(document, structure)

A copy of document with structure added; its ID must be new.

describe()

The implemented formats with what they carry, for listings.

losses(structure, fmt)

What fmt cannot carry from structure (empty when lossless).

read(text, fmt, *, identifier)

A periodic structure read from text in an implemented format.

read_extxyz(text, *, identifier)

A periodic structure from one extended-XYZ frame with Lattice and pbc.

read_gen(text, *, identifier)

A 3-D periodic structure from DFTB+ GEN text (types S or F).

read_poscar(text, *, identifier)

A 3-D periodic structure from VASP 5 POSCAR/CONTCAR text.

refusals(structure, fmt)

What no export flag can admit: losing these would change the chemistry.

write(structure, fmt, *[, reduced])

structure as fmt text; refuses losses unless reduced is set.

Classes

Export(format, text[, losses])

Text in format and what it could not carry (empty when lossless).

vibesketcher.document.periodic_formats.FORMATS: tuple[Literal['poscar', 'extxyz', 'gen'], ...] = ('poscar', 'extxyz', 'gen')

The implemented formats; nothing else is discoverable.

vibesketcher.document.periodic_formats.CAPABILITIES: dict[Literal['poscar', 'extxyz', 'gen'], dict[str, bool]] = {'extxyz': {'charge': True, 'fixed_sites': True, 'multiplicity': True, 'partial_pbc': True, 'site_ids': True}, 'gen': {'charge': False, 'fixed_sites': False, 'multiplicity': False, 'partial_pbc': False, 'site_ids': False}, 'poscar': {'charge': False, 'fixed_sites': True, 'multiplicity': False, 'partial_pbc': False, 'site_ids': False}}

What each format can carry beyond lattice, species and positions.

class vibesketcher.document.periodic_formats.Export(format, text, losses=<factory>)[source]

Bases: object

Text in format and what it could not carry (empty when lossless).

Parameters:
format: Literal['poscar', 'extxyz', 'gen']
text: str
losses: list[str]
vibesketcher.document.periodic_formats.describe()[source]

The implemented formats with what they carry, for listings.

Return type:

list[dict[str, Any]]

vibesketcher.document.periodic_formats.read_poscar(text, *, identifier)[source]

A 3-D periodic structure from VASP 5 POSCAR/CONTCAR text.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.periodic_formats.read_extxyz(text, *, identifier)[source]

A periodic structure from one extended-XYZ frame with Lattice and pbc.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.periodic_formats.read_gen(text, *, identifier)[source]

A 3-D periodic structure from DFTB+ GEN text (types S or F).

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.periodic_formats.read(text, fmt, *, identifier)[source]

A periodic structure read from text in an implemented format.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.periodic_formats.refusals(structure, fmt)[source]

What no export flag can admit: losing these would change the chemistry.

Parameters:
Return type:

list[str]

vibesketcher.document.periodic_formats.losses(structure, fmt)[source]

What fmt cannot carry from structure (empty when lossless).

Parameters:
Return type:

list[str]

vibesketcher.document.periodic_formats.write(structure, fmt, *, reduced=False)[source]

structure as fmt text; refuses losses unless reduced is set.

The text is read back and compared with structure (lattice, species, positions and every field the format claims to carry) before it is returned. The source structure and its document are not changed.

Parameters:
Return type:

Export

vibesketcher.document.periodic_formats.add_to_document(document, structure)[source]

A copy of document with structure added; its ID must be new.

Parameters:
Return type:

Any