ase/structure format#
Aliases#
ase/structure
Implementation: ASEStructureFormat
Overview#
In-memory Atomic Simulation Environment (ASE) Atoms objects.
This adapter converts between dpdata systems and ASE objects without writing a file. It can also use ASE’s I/O support to load multi-frame files; pass ase_fmt when ASE cannot infer the underlying file format. Labeled conversion reads or attaches an ASE calculator’s energy, forces, and stress. The optional ase dependency is required.
Quick examples#
The examples use the preferred alias ase/structure; any alias listed above is equivalent.
import dpdata
from ase import Atoms
atoms = Atoms("H")
# Geometry-only data
system = dpdata.System(atoms, fmt="ase/structure")
# Data with energies and forces
labeled_system = dpdata.LabeledSystem(atoms, fmt="ase/structure")
# Multiple compositions or calculation directories
systems = dpdata.MultiSystems.from_file("trajectory.xyz", fmt="ase/structure")
# Write geometry-only data
converted = system.to("ase/structure")
# Write labeled data
converted = labeled_system.to("ase/structure")
Conversions#
Convert from this format to System#
- dpdata.System(atoms: 'ase.Atoms', fmt: Literal['ase/structure'] = None, **kwargs) dpdata.system.System
- dpdata.System.from_ase_structure(atoms: 'ase.Atoms', **kwargs) dpdata.system.System
Convert ase.Atoms to a System.
- Parameters:
- atomsase.Atoms
an ASE Atoms, containing a structure
- **kwargsdict
other parameters
- Returns:
- System
converted system
Convert from System to this format#
- dpdata.System.to(fmt: Literal['ase/structure'], **kwargs) 'list[ase.Atoms]'
- dpdata.System.to_ase_structure(**kwargs) 'list[ase.Atoms]'
Convert every System frame to an ASE Atoms object.
- Parameters:
- **kwargsdict
Additional format arguments accepted for API compatibility.
- Returns:
- list[ase.Atoms]
One ASE object per frame.
Convert from LabeledSystem to this format#
- dpdata.LabeledSystem.to(fmt: Literal['ase/structure'], *args, **kwargs) 'list[ase.Atoms]'
- dpdata.LabeledSystem.to_ase_structure(*args, **kwargs) 'list[ase.Atoms]'
Convert labeled frames to ASE objects with single-point calculators.
- Parameters:
- **kwargsdict
Additional keyword arguments accepted for API compatibility.
- Returns:
- list[ase.Atoms]
One ASE object per frame with labels stored in a
SinglePointCalculator.
Convert from this format to LabeledSystem#
- dpdata.LabeledSystem(atoms: 'ase.Atoms', fmt: Literal['ase/structure'] = None, **kwargs) dpdata.system.LabeledSystem
- dpdata.LabeledSystem.from_ase_structure(atoms: 'ase.Atoms', **kwargs) dpdata.system.LabeledSystem
Convert ASE Atoms to a LabeledSystem.
Energies and forces are calculated by the attached calculator.
Note that this method will try to load virials from either virial field or converted from stress tensor.
- Parameters:
- atomsase.Atoms
an ASE Atoms, containing a structure
- **kwargsdict
other parameters
- Returns:
- LabeledSystem
converted system
- Raises:
- RuntimeError
ASE will raise RuntimeError if the atoms does not have a calculator
Convert from this format to MultiSystems#
- dpdata.MultiSystems.from_ase_structure(file_name: 'str', begin: 'int | None' = None, end: 'int | None' = None, step: 'int | None' = None, ase_fmt: 'str | None' = None, **kwargs) dpdata.system.MultiSystems
Convert a ASE supported file to ASE Atoms.
It will finally be converted to MultiSystems.
- Parameters:
- file_namestr
path to file
- beginint, optional
begin frame index
- endint, optional
end frame index
- stepint, optional
frame index step
- ase_fmtstr, optional
ASE format. See the ASE documentation about supported formats
- **kwargsdict
other parameters
- Returns:
- MultiSystems
converted system