ExtXYZ
Read ExtXYZ data into the ELFES data format.
convert_extxyz_to_hdf5(
input_path: StrPath,
output_path: StrPath,
quantity_types: Mapping[str, AtomisticDataType],
*,
precision: Precision = 64,
compression: Compression = "none",
compression_level: int = 4,
metadata: dict[str, str] | None = None,
overwrite: bool = False,
) -> int
Convert every frame of one ExtXYZ file to one ELFES HDF5 file.
quantity_types maps each source field name to its physical ELFES data type.
Fields are resolved across the ASE Atoms.info, Atoms.arrays, and calculator
result namespaces, and their source names are retained as HDF5 physical-data
names. ExtXYZ numerical values must already use ELFES units: Å, eV, and the
corresponding derived units.
ExtXYZ atom-level arrays place the atom axis first; the conversion moves it to
the axis expected by ELFES physical objects. Rank-2 Cartesian tensors may use
shape (..., 3, 3), flattened shape (..., 9), or symmetric ASE Voigt order
(..., 6) as (xx, yy, zz, yz, xz, xy).
Frames missing any selected field are omitted. One summary warning reports the skipped-frame count and per-field missing counts after successful conversion. Existing fields with invalid values or shapes remain errors. Original zero-based frame indices are retained as string sample IDs. The returned integer is the number of converted frames.
ExtXYZ records whether a value belongs to a structure or its atoms and records its numerical shape, but it does not identify whether three components form a Cartesian vector or merely three unrelated scalars. Conversion therefore requires an explicit mapping from each source field name to an ELFES atomistic data type. The source name is retained as the physical-data name in HDF5:
from elfes.io.extxyz import convert_extxyz_to_hdf5
convert_extxyz_to_hdf5(
"training.xyz",
"training.h5",
{
"dft_energy": "scalar",
"dft_force": "atom_cartesian_vector",
"dft_virial": "cartesian_tensor_2",
},
compression="gzip",
)
The converter resolves fields from all three namespaces produced by ASE's ExtXYZ reader: structure-level Atoms.info, atom-level Atoms.arrays, and recognized calculator results such as energy, forces, and stress. Atom-level source arrays use a leading atom axis and are transposed into the axis order of the corresponding ELFES physical object. Cartesian rank-2 tensors accept full 3 × 3 values, flattened 9-component values, and symmetric 6-component values in ASE Voigt order (xx, yy, zz, yz, xz, xy).
ExtXYZ does not carry dependable units or distinguish stress from virial by shape. Input values must already use the applicable ELFES units, and conversion does not divide a virial by cell volume or change its sign. In particular, a stress target must be in eV/ų, while a virial target is an energy-like tensor in eV. Keeping the source name prevents this distinction from being hidden.
The caller selects only the quantities required by the resulting logical dataset. A frame missing any selected quantity is omitted, and one summary warning reports the number of skipped frames and the missing count for each field. A field that is present but has an invalid numerical type or shape remains an error rather than being treated as missing. Retained samples keep their original zero-based ExtXYZ frame indices as string IDs and must share the same physical types and fixed extra shapes.