| name | ase |
| description | Use when the user is working with atomistic structures, calculators, geometry
optimization, trajectories, CIF/POSCAR/XYZ/EXTXYZ files, periodic cells,
molecular dynamics setup, NEB paths, surface/slab builders, or workflows that
need a common Python interface across DFT codes, ML interatomic potentials,
and classical force fields. Prefer ASE over ad hoc NumPy coordinate handling
when Atoms objects, units, file I/O, calculators, constraints, optimizers, or
trajectory provenance matter.
|
| version | 0.1.0 |
| compatible_versions | >=3.22,<4 |
| related_skills | ["pymatgen","mace","openmm"] |
| canonical_docs | https://ase-lib.org/ |
| canonical_tutorials | https://ase.gitlab.io/ase/gettingstarted/tut01_molecule/molecule.html |
ASE
What this library is for
ASE, the Atomic Simulation Environment, is the common Python interface for
building, reading, writing, transforming, simulating, and optimizing atomistic
systems. It centers on the Atoms object and plugs that object into calculators
for energies, forces, stresses, dynamics, and electronic-structure workflows.
When to use this vs. alternatives
- Use ASE when the task needs atomistic file I/O, periodic cells, constraints,
optimizers, molecular dynamics, trajectories, or a calculator abstraction.
- Use pymatgen for composition/phase-diagram/Materials Project workflows and
crystallographic analysis; convert to ASE only when a calculator or ASE I/O
workflow is needed.
- Use RDKit for molecule graphs, conformer generation, reactions, and cheminfo
descriptors; convert to ASE only after atoms and 3D coordinates are needed for
simulation.
- Use MACE, GPAW, VASP, CP2K, LAMMPS, OpenMM, or another calculator through ASE
when the model/code is the scientific method. ASE is the orchestration layer,
not the potential itself.
- Do not roll your own atom coordinate arrays for routine simulation scripts.
You will lose calculator provenance, unit conventions, PBC/cell handling,
constraints, and standard trajectory I/O.
Canonical workflow
Use the official getting-started and examples gallery for full workflows. The
dominant pattern is: build or read an Atoms, attach a calculator, run an ASE
operation that asks the calculator for energies/forces, then write a trajectory
or structure.
from ase.build import bulk
from ase.calculators.emt import EMT
from ase.io import read, write
from ase.optimize import BFGS
atoms = bulk("Cu", "fcc", a=3.6, cubic=True)
atoms.rattle(stdev=0.03, seed=7)
atoms.calc = EMT()
opt = BFGS(atoms, trajectory="relax.traj", logfile="relax.log")
opt.run(fmax=0.03)
print("energy_eV", atoms.get_potential_energy())
print("max_force_eV_per_A", abs(atoms.get_forces()).max())
write("relaxed.cif", atoms)
relaxed = read("relax.traj", index=-1)
For deeper examples, read:
Key conventions and gotchas
- Energies are in eV, distances in Angstrom, times in ASE time units, forces in
eV/Angstrom, and stresses in eV/Angstrom^3 unless a calculator documents an
exception.
- Modern ASE examples use
atoms.calc = calc. Older code may use
atoms.set_calculator(calc); prefer direct assignment in new code.
Atoms can exist without a calculator. Calls such as get_potential_energy()
or get_forces() will fail unless atoms.calc is set or values were loaded
from a trajectory/single-point calculator.- Periodic boundary conditions and cell vectors are separate state:
atoms.pbc controls periodicity, while atoms.cell stores lattice vectors.
For periodic calculations, verify both before computing energies or neighbor
lists.
- CIF/POSCAR/XYZ/EXTXYZ round trips do not preserve the same metadata. Use
.traj or database formats when calculator results, constraints, or workflow
provenance must survive.
- Calculator support for stress, charges, magnetic moments, and periodicity is
calculator-specific. Check
implemented_properties or catch
PropertyNotImplementedError.
- Some calculators reorder or transform atom lists for external codes. Keep a
clear mapping when mixing constraints, adsorbates, selective dynamics, or
post-processing.
Anti-patterns
- Do not parse CIF/POSCAR/XYZ manually for normal workflows. Use
ase.io.read
and inspect atoms, atoms.cell, atoms.pbc, and atoms.get_chemical_formula().
- Do not call
get_forces() inside an optimizer loop you wrote yourself unless
you have a specific reason. Use ASE optimizers (BFGS, FIRE, LBFGS) so
trajectories, restarts, constraints, and convergence are handled consistently.
- Do not assume an EMT example is scientifically valid for the user's system.
EMT is convenient for demos and tests; choose a domain-appropriate calculator
for real conclusions.
- Do not compare total energies between structures with different composition,
cell constraints, calculators, pseudopotentials, charge states, or spin
settings without normalization and provenance checks.
- Do not convert between ASE and pymatgen/RDKit/OpenMM without validating atom
order, units, charge/spin, periodic cell, and bonding assumptions afterward.
Diagnostic checks
Before trusting outputs, the agent should:
- Print or log the formula, atom count, cell, PBC flags, calculator class, and
calculator parameters.
- Check
atoms.get_forces() and report max force after relaxation.
- Confirm the intended cell degrees of freedom: fixed-cell relaxation, atom-only
relaxation, or cell/shape relaxation with the correct filter.
- Visualize or write intermediate structures for slabs, adsorbates, NEB images,
and generated supercells.
- Re-read the written output file and compare atom count, formula, cell, and PBC
against the in-memory
Atoms.
- Save
trajectory, logfile, and enough calculator settings to reproduce the
calculation.
Pointers to deeper material
