extxyz format

Aliases

extxyz, gpumd/xyz, mace/xyz, nequip/xyz, quip/gap/xyz, quip/gap/xyz_file

Implementation: QuipGapXYZFormat

Overview

Extended XYZ used by QUIP/GAP and atomistic ML tools.

QUIP/GAP provides a Gaussian Approximation Potential framework, while MACE, NequIP, and GPUMD are modern machine-learning interatomic potential packages.

The comment-line Lattice and Properties metadata can store cells, energies, forces, virials, and per-atom fields. A single file may contain multiple frames and formulas, so the format supports dpdata.MultiSystems. The aliases extxyz, mace/xyz, nequip/xyz, and gpumd/xyz share this implementation.

Quick examples

The examples use the preferred alias extxyz; any alias listed above is equivalent.

import dpdata

# Data with energies and forces
labeled_system = dpdata.LabeledSystem("data.xyz", fmt="extxyz")

# Multiple compositions or calculation directories
systems = dpdata.MultiSystems.from_file("data.xyz", fmt="extxyz")

# Write labeled data
labeled_system.to("extxyz", "output_path")

# Write multiple systems
systems.to("extxyz", "output_path")

Conversions

Convert from this format to LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['extxyz'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['gpumd/xyz'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['mace/xyz'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['nequip/xyz'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['quip/gap/xyz'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem(data, fmt: Literal['quip/gap/xyz_file'] = None, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_extxyz(data, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_gpumd_xyz(data, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_mace_xyz(data, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_nequip_xyz(data, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_quip_gap_xyz(data, **kwargs) → dpdata.system.LabeledSystem

dpdata.LabeledSystem.from_quip_gap_xyz_file(data, **kwargs) → dpdata.system.LabeledSystem

Load the first labeled frame from an extended XYZ source.

Parameters:

datastr, os.PathLike, or dict

Input extended XYZ file, or an already parsed frame supplied by from_multi_systems().

**kwargsdict

Extended-XYZ parsing options described below.

Returns:

LabeledSystem

converted system

Other Parameters:

stress_signint, default=-1

Sign in virial = stress_sign * volume * stress. The default follows ASE’s virial = -V * stress convention.

Convert from LabeledSystem to this format

dpdata.LabeledSystem.to(fmt: Literal['extxyz'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to(fmt: Literal['gpumd/xyz'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to(fmt: Literal['mace/xyz'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to(fmt: Literal['nequip/xyz'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to(fmt: Literal['quip/gap/xyz'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to(fmt: Literal['quip/gap/xyz_file'], file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_extxyz(file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_gpumd_xyz(file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_mace_xyz(file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_nequip_xyz(file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_quip_gap_xyz(file_name: 'FileType', **kwargs)

dpdata.LabeledSystem.to_quip_gap_xyz_file(file_name: 'FileType', **kwargs)

Write LabeledSystem data to QUIP/GAP XYZ format file.

Parameters:

file_nameFileType

output file name or file handler

**kwargsdict

additional arguments

Convert from this format to MultiSystems

dpdata.MultiSystems.from_extxyz(file_name, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.from_gpumd_xyz(file_name, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.from_mace_xyz(file_name, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.from_nequip_xyz(file_name, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.from_quip_gap_xyz(file_name, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.from_quip_gap_xyz_file(file_name, **kwargs) → dpdata.system.MultiSystems

Iterate over all frames and formulas in an extended XYZ file.

Parameters:

file_namestr or os.PathLike

Input extended XYZ file.

**kwargsdict

Extended-XYZ parsing options described below.

Returns:

MultiSystems

converted system

Other Parameters:

stress_signint, default=-1

Sign in virial = stress_sign * volume * stress. The default follows ASE’s virial = -V * stress convention.

Convert from MultiSystems to this format

dpdata.MultiSystems.to(fmt: Literal['extxyz'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to(fmt: Literal['gpumd/xyz'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to(fmt: Literal['mace/xyz'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to(fmt: Literal['nequip/xyz'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to(fmt: Literal['quip/gap/xyz'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to(fmt: Literal['quip/gap/xyz_file'], directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_extxyz(directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_gpumd_xyz(directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_mace_xyz(directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_nequip_xyz(directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_quip_gap_xyz(directory, **kwargs) → dpdata.system.MultiSystems

dpdata.MultiSystems.to_quip_gap_xyz_file(directory, **kwargs) → dpdata.system.MultiSystems

Return single filename for all systems in QUIP/GAP XYZ format.

For QUIP/GAP XYZ format, all systems are written to a single file.

Parameters:

directorystr

output filename

**kwargsdict

additional arguments

Returns:

MultiSystems

this system