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:
poscarVASP 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.
extxyzExtended XYZ as written by ASE and libAtoms/QUIP:
Lattice,Propertiesandpbcon the comment line. A. H. Larsen et al., J. Phys.: Condens. Matter 29, 273002 (2017).genThe 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
Latticeandpbc, 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
The implemented formats; nothing else is discoverable. |
|
What each format can carry beyond lattice, species and positions. |
Functions
|
A copy of |
|
The implemented formats with what they carry, for listings. |
|
What |
|
A periodic structure read from |
|
A periodic structure from one extended-XYZ frame with Lattice and pbc. |
|
A 3-D periodic structure from DFTB+ GEN text (types S or F). |
|
A 3-D periodic structure from VASP 5 POSCAR/CONTCAR text. |
|
What no export flag can admit: losing these would change the chemistry. |
|
|
Classes
|
Text in |
- 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:
objectText in
formatand what it could not carry (empty when lossless).
- vibesketcher.document.periodic_formats.describe()[source]¶
The implemented formats with what they carry, for listings.
- vibesketcher.document.periodic_formats.read_poscar(text, *, identifier)[source]¶
A 3-D periodic structure from VASP 5 POSCAR/CONTCAR text.
- Parameters:
- Return type:
- vibesketcher.document.periodic_formats.read_extxyz(text, *, identifier)[source]¶
A periodic structure from one extended-XYZ frame with Lattice and pbc.
- Parameters:
- Return type:
- 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:
- vibesketcher.document.periodic_formats.read(text, fmt, *, identifier)[source]¶
A periodic structure read from
textin an implemented format.- Parameters:
- Return type:
- vibesketcher.document.periodic_formats.refusals(structure, fmt)[source]¶
What no export flag can admit: losing these would change the chemistry.
- Parameters:
structure (PeriodicStructure)
fmt (str)
- Return type:
- vibesketcher.document.periodic_formats.losses(structure, fmt)[source]¶
What
fmtcannot carry fromstructure(empty when lossless).- Parameters:
structure (PeriodicStructure)
fmt (str)
- Return type:
- vibesketcher.document.periodic_formats.write(structure, fmt, *, reduced=False)[source]¶
structureasfmttext; refuses losses unlessreducedis 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:
structure (PeriodicStructure)
fmt (str)
reduced (bool)
- Return type:
- vibesketcher.document.periodic_formats.add_to_document(document, structure)[source]¶
A copy of
documentwithstructureadded; its ID must be new.- Parameters:
document (Any)
structure (PeriodicStructure)
- Return type: