Format Specific Options



Import ABINIT input file.

Reads cell, atom positions, etc. from abinit input file, atoms, param=None, species=None, pseudos=None)[source]



Reads a ACE-Molecule input file :param filename: :type filename: ACE-Molecule input file name

Return type:

ASE atoms object containing geometry only.


Interface to ACEMoleculeReader, return values for corresponding quantity

  • filename (ACE-Molecule log file.) –

  • quantity (One of atoms, energy, forces, excitation-energy.) –


  • - quantity = ‘excitation-energy’ – returns None. This is placeholder function to run TDDFT calculations without IndexError.

  • - quantity = ‘energy’ – returns energy as float value.

  • - quantity = ‘forces’ – returns force of each atoms as numpy array of shape (natoms, 3).

  • - quantity = ‘atoms’ – returns ASE atoms object.

aims, apply_constraints=True)[source]

Import FHI-aims geometry type files.

Reads unitcell, atom positions and constraints from a file.

If geometric constraint (symmetry parameters) are in the file include that information in[“symmetry_block”], atoms, scaled=False, geo_constrain=False, write_velocities=False, velocities=False, ghosts=None, info_str=None, wrap=False)[source]

Method to write FHI-aims geometry files.

Writes the atoms positions and constraints (only FixAtoms is supported at the moment).

  • fd – file object File to output structure to

  • atoms – ase.atoms.Atoms structure to output to the file

  • scaled – bool If True use fractional coordinates instead of Cartesian coordinates

  • symmetry_block – list of str List of geometric constraints as defined in: arXiv: 1908.01610

  • write_velocities – bool If True add the atomic velocity vectors to the file

  • velocities – bool NOT AN ARRAY OF VELOCITIES, but the legacy version of \(write_velocities\)

  • ghosts – list of Atoms A list of ghost atoms for the system

  • info_str – str A string to be added to the header of the file

  • wrap – bool Wrap atom positions to cell before writing

Deprecated since version 3.23.0: Use of velocities is deprecated, please use write_velocities.

aims-output, index=-1, non_convergence_ok=False)[source]

Import FHI-aims output files with all data available, i.e. relaxations, MD information, force information etc etc etc.

bundletrajectory, index=-1)[source]

Reads one or more atoms objects from a BundleTrajectory.


filename: str

The name of the bundle (really a directory!)

index: int

An integer specifying which frame to read, or an index object for reading multiple frames. Default: -1 (reads the last frame)., images, append=False)[source]

Write image(s) to a BundleTrajectory.

Write also energy, forces, and stress if they are already calculated.

castep-castep, index=None)[source]

Reads a .castep file and returns an atoms object. The calculator information will be stored in the calc attribute.

There is no use of the “index” argument as of now, it is just inserted for convenience to comply with the generic “read()” in

Please note that this routine will return an atom ordering as found within the castep file. This means that the species will be ordered by ascending atomic numbers. The atoms witin a species are ordered as given in the original cell file.

Note: This routine returns a single atoms_object only, the last configuration in the file. Yet, if you want to parse an MD run, use the novel function \(read_md()\)

castep-cell, index=None, calculator_args={}, find_spg=False, units={'Eh': 27.2113845, 'Pascal': 160217653000.0, 'a0': 0.5291772108, 'c': 299792458, 'e': 1.60217653e-19, 'hbar': 6.58211915e-16, 'kB': 8.617343e-05, 'me': 0.00054857990945, 't0': 2.4188843276239763e-17})[source]

Read a .cell file and return an atoms object. Any value found that does not fit the atoms API will be stored in the atoms.calc attribute.

By default, the Castep calculator will be tolerant and in the absence of a castep_keywords.json file it will just accept all keywords that aren’t automatically parsed., atoms, positions_frac=False, force_write=False, precision=6, magnetic_moments=None, castep_cell=None)[source]

This CASTEP export function write minimal information to a .cell file. If the atoms object is a trajectory, it will take the last image.

Note that function has been altered in order to require a filedescriptor rather than a filename. This allows to use the more generic write() function from

Note that the “force_write” keywords has no effect currently.

  • positions_frac – boolean. If true, positions are printed as fractional rather than absolute. Default is false.

  • castep_cell – if provided, overrides the existing CastepCell object in the Atoms calculator

  • precision – number of digits to which lattice and positions are printed

  • magnetic_moments – if None, no SPIN values are initialised. If ‘initial’, the values from get_initial_magnetic_moments() are used. If ‘calculated’, the values from get_magnetic_moments() are used. If an array of the same length as the atoms object, its contents will be used as magnetic moments.

castep-geom, index=None, units={'Eh': 27.2113845, 'Pascal': 160217653000.0, 'a0': 0.5291772108, 'c': 299792458, 'e': 1.60217653e-19, 'hbar': 6.58211915e-16, 'kB': 8.617343e-05, 'me': 0.00054857990945, 't0': 2.4188843276239763e-17})[source]

Reads a .geom file produced by the CASTEP GeometryOptimization task and returns an atoms object. The information about total free energy and forces of each atom for every relaxation step will be stored for further analysis especially in a single-point calculator. Note that everything in the .geom file is in atomic units, which has been conversed to commonly used unit angstrom(length) and eV (energy).

Note that the index argument has no effect as of now.

Contribution by Wei-Bing Zhang. Thanks!

Routine now accepts a filedescriptor in order to out-source the gz and bz2 handling to Note that there is a fallback routine read_geom() that behaves like previous versions did.

castep-md, index=None, return_scalars=False, units={'Eh': 27.2113845, 'Pascal': 160217653000.0, 'a0': 0.5291772108, 'c': 299792458, 'e': 1.60217653e-19, 'hbar': 6.58211915e-16, 'kB': 8.617343e-05, 'me': 0.00054857990945, 't0': 2.4188843276239763e-17})[source]

Reads a .md file written by a CASTEP MolecularDynamics task and returns the trajectory stored therein as a list of atoms object.

Note that the index argument has no effect as of now.

castep-phonon, index=None, read_vib_data=False, gamma_only=True, frequency_factor=None, units={'Eh': 27.2113845, 'Pascal': 160217653000.0, 'a0': 0.5291772108, 'c': 299792458, 'e': 1.60217653e-19, 'hbar': 6.58211915e-16, 'kB': 8.617343e-05, 'me': 0.00054857990945, 't0': 2.4188843276239763e-17})[source]

Reads a .phonon file written by a CASTEP Phonon task and returns an atoms object, as well as the calculated vibrational data if requested.

Note that the index argument has no effect as of now.


Read atomic configuration from a CFG-file (native AtomEye format). See:, atoms)[source]

Write atomic configuration to a CFG-file (native AtomEye format). See:

cif, index=-1, *, store_tags: bool = False, primitive_cell: bool = False, subtrans_included: bool = True, fractional_occupancies: bool = True, reader: str = 'ase') Union[Atoms, List[Atoms]][source]

Read Atoms object from CIF file.

  • store_tags (bool) – If true, the info attribute of the returned Atoms object will be populated with all tags in the corresponding cif data block.

  • primitive_cell (bool) – If true, the primitive cell is built instead of the conventional cell.

  • subtrans_included (bool) – If true, sublattice translations are assumed to be included among the symmetry operations listed in the CIF file (seems to be the common behaviour of CIF files). Otherwise the sublattice translations are determined from setting 1 of the extracted space group. A result of setting this flag to true, is that it will not be possible to determine the primitive cell.

  • fractional_occupancies (bool) – If true, the resulting atoms object will be tagged equipped with a dictionary \(occupancy\). The keys of this dictionary will be integers converted to strings. The conversion to string is done in order to avoid troubles with JSON encoding/decoding of the dictionaries with non-string keys. Also, in case of mixed occupancies, the atom’s chemical symbol will be that of the most dominant species.

  • reader (str) –

    Select CIF reader.

    • ase : built-in CIF reader (default)

    • pycodcif : CIF reader based on pycodcif package


Only blocks with valid crystal data will be included., images, cif_format=None, wrap=True, labels=None, loop_keys=None) None[source]

Write images to CIF file.

wrap: bool

Wrap atoms into unit cell.

labels: list

Use this list (shaped list[i_frame][i_atom] = string) for the ‘_atom_site_label’ section instead of automatically generating it from the element symbol.

loop_keys: dict

Add the information from this dictionary to the \(loop_\) section. Keys are printed to the \(loop_\) section preceeded by ‘ _’. dict[key] should contain the data printed for each atom, so it needs to have the setup \(dict[key][i_frame][i_atom] = string\). The strings are printed as they are, so take care of formating. Information can be re-read using the \(store_tags\) option of the cif reader.


Read a Chemical Json file as written by avogadro2 (>=1.93.0)



cp2k-dcd, index=-1, ref_atoms=None, aligned=False)[source]

Read a DCD file created by CP2K.

To yield one Atoms object at a time use iread_cp2k_dcd.

Note: Other programs use other formats, they are probably not compatible.

If ref_atoms is not given, all atoms will have symbol ‘X’.

To make sure that this is a dcd file generated with the DCD_ALIGNED_CELL key in the CP2K input, you need to set aligned to True to get cell information. Make sure you do not set it otherwise, the cell will not match the atomic coordinates! See the following url for details:!searchin/cp2k/Outputting$20cell$20information$20and$20fractional$20coordinates%7Csort:relevance/cp2k/72MhYykrSrQ/5c9Jaw7S9yQJ.


Read Atoms and Cell from Restart File.

Reads the elements, coordinates and cell information from the ‘&SUBSYS’ section of a CP2K restart file.

Tries to convert atom names to elements, if this fails element is set to X.

Returns an Atoms object.


Method to read coordinates form ‘fort.34’ files additionally read information about periodic boundary condition, atoms)[source]

Method to write atom structure in crystal format (fort.34 format)

cube, read_data=True, program=None, verbose=False)[source]

Read atoms and data from CUBE file.

file_objstr or file

Location to the cube file.


If set true, the actual cube file content, i.e. an array containing the electronic density (or something else )on a grid and the dimensions of the corresponding voxels are read.

program: str

Use program=’castep’ to follow the PBC convention that first and last voxel along a direction are mirror images, thus the last voxel is to be removed. If program=None, the routine will try to catch castep files from the comment lines.


Print some more information to stdout.

Returns a dict with the following keys:

  • ‘atoms’: Atoms object

  • ‘data’ : (Nx, Ny, Nz) ndarray

  • ‘origin’: (3,) ndarray, specifying the cube_data origin.

  • ‘spacing’: (3, 3) ndarray, representing voxel size, atoms, data=None, origin=None, comment=None)[source]

Function to write a cube file.

file_obj: str or file object

File to which output is written.

atoms: Atoms

The Atoms object specifying the atomic configuration.

data3-dim numpy array, optional (default = None)

Array containing volumetric data as e.g. electronic density


Origin of the volumetric data (units: Angstrom)

commentstr, optional (default = None)

Comment for the first line of the cube file.


db, index, **kwargs)[source], images, append=False, **kwargs)[source]


Method to read coordinates from the Geometry section of a DFTB+ input file (typically called “dftb_in.hsd”).

As described in the DFTB+ manual, this section can be in a number of different formats. This reader supports the GEN format and the so-called “explicit” format.

The “explicit” format is unique to DFTB+ input files. The GEN format can also be used in a stand-alone fashion, as coordinate files with a \(.gen\) extension. Reading and writing such files is implemented in \(\)., images: Union[Atoms, Sequence[Atoms]], fractional: bool = False)[source]

Write structure in GEN format (refer to DFTB+ manual). Multiple snapshots are not allowed.

dlp-history IO, index: Optional[Union[int, slice]] = None, symbols: Optional[List[str]] = None) List[Atoms][source]

Read a HISTORY file.

Compatible with DLP4 and DLP_CLASSIC.

Index can be integer or a slice.

Provide a list of element strings to symbols to ignore naming from the HISTORY file.

dlp4 IO, symbols: Optional[List[str]] = None) Atoms[source]

Read a DL_POLY_4 config/revcon file.

Typically used indirectly through read(“filename”, atoms, format=”dlp4”).

Can be unforgiving with custom chemical element names. Please complain to for bugs. IO, atoms: Atoms, levcfg: int = 0, title: str = 'CONFIG generated by ASE')[source]

Write a DL_POLY_4 config file.

Typically used indirectly through write(“filename”, atoms, format=”dlp4”).

Can be unforgiven with custom chemical element names. Please complain to in case of bugs

dmol-arc, index=-1)[source]

Read a dmol arc-file and return a series of Atoms objects (images)., images)[source]

Writes all images to file filename in arc format.

Similar to the .car format only pbc 111 or 000 is supported.


Read a dmol car-file and return an Atoms object.


Cell is constructed from cellpar so orientation of cell might be off., atoms)[source]

Write a dmol car-file from an Atoms object


The positions written to file are rotated as to align with the cell when reading (due to cellpar information) Can not handle multiple images. Only allows for pbc 111 or 000.

dmol-incoor, bohr=True)[source]

Reads an incoor file and returns an atoms object.


If bohr is True then incoor is assumed to be in bohr and the data is rescaled to Angstrom., atoms, bohr=True)[source]

Write a dmol incoor-file from an Atoms object


Only used for pbc 111. Can not handle multiple images. DMol3 expect data in .incoor files to be in bohr, if bohr is false however the data is written in Angstroms.


Import ELK atoms definition.

Reads unitcell, atom positions, magmoms from file.

elk-in, atoms, parameters=None)[source]

eon, index=-1)[source]

Reads an EON file or directory and returns one or more Atoms objects.

This function handles single EON files, in both single image and multi-image variants. It returns either a single Atoms object, a list of Atoms objects, or a specific Atoms object indexed from the file or directory.

  • fileobj (str or Path or file-like object) – The path to the EON file or directory, or an open file-like object.

  • index (int, optional) – The index of the Atoms object to return. If -1 (default), returns all objects or a single object if only one is present.


Depending on the \(index\) parameter and the content of the fileobj, returns either a single Atoms object or a list of Atoms objects.

Return type:

Atoms or List[Atoms], images, comment='Generated by ASE')[source]

Writes structures to an EON trajectory file, allowing for multiple snapshots.

This function iterates over all provided images, converting each one into a text format compatible with EON trajectory files. It handles the conversion of the cell parameters, chemical symbols, atomic masses, and atomic constraints. Only FixAtoms constraints are supported; any other constraints will generate a warning and be skipped. Arbitrary masses will raise an error, since EON will not accept them, i.e. no Duterium and Hydrogen.

  • fileobj (file object) – An opened, writable file or file-like object to which the EON trajectory information will be written.

  • images (list of Atoms) – A list of ASE Atoms objects representing the images (atomic structures) to be written into the EON trajectory file. Each Atoms object should have a cell attribute and may have a constraints attribute. If the constraints attribute is not a FixAtoms object, a warning will be issued.

  • comment (str) – An additional comment statement which will be written out as the first header

  • Warning – If any constraint in an Atoms object is not an instance of FixAtoms.

  • RuntimeError – If the masses for the species are not the default ones, i.e. if isotopes are present


The function writes directly to the provided file object.

Return type:


See also

for segmenting the list of images.


>>> from import Trajectory
>>> from import segment_list
>>> traj = Trajectory("neb.traj")
>>> n_images = 10  # Segment size, i.e. number of images in the NEB
>>> for idx, pth in enumerate(segment_list(traj, n_images)):
...     with open(f"outputs/neb_path_{idx:03d}.con", "w") as fobj:
...         write_eon_traj(fobj, pth)

eps, atoms, **parameters)[source]


Parse a Quantum ESPRESSO input files, ‘.in’, ‘.pwi’.

ESPRESSO inputs are generally a fortran-namelist format with custom blocks of data. The namelist is parsed as a dict and an atoms object is constructed from the included information.


fileobj (file | str) – A file-like object that supports line iteration with the contents of the input file, or a filename.


atoms – Structure defined in the input file.

Return type:



KeyError – Raised for missing keys that are required to process the file, atoms, input_data=None, pseudopotentials=None, kspacing=None, kpts=None, koffset=(0, 0, 0), crystal_coordinates=False, additional_cards=None, **kwargs)[source]

Create an input file for pw.x.

Use set_initial_magnetic_moments to turn on spin, if ispin is set to 2 with no magnetic moments, they will all be set to 0.0. Magnetic moments will be converted to the QE units (fraction of valence electrons) using any pseudopotential files found, or a best guess for the number of valence electrons.

Units are not converted for any other input data, so use Quantum ESPRESSO units (Usually Ry or atomic units).

Keys with a dimension (e.g. Hubbard_U(1)) will be incorporated as-is so the \(i\) should be made to match the output.

Implemented features:

  • Conversion of ase.constraints.FixAtoms and


  • \(starting_magnetization\) derived from the \(mgmoms\) and pseudopotentials (searches default paths for pseudo files.)

  • Automatic assignment of options to their correct sections.

Not implemented:

  • Non-zero values of ibrav

  • Lists of k-points

  • Other constraints

  • Hubbard parameters

  • Validation of the argument types for input

  • Validation of required options

  • fd (file | str) – A file to which the input is written.

  • atoms (Atoms) – A single atomistic configuration to write to \(fd\).

  • input_data (dict) – A flat or nested dictionary with input parameters for pw.x

  • pseudopotentials (dict) – A filename for each atomic species, e.g. {‘O’: ‘O.pbe-rrkjus.UPF’, ‘H’: ‘H.pbe-rrkjus.UPF’}. A dummy name will be used if none are given.

  • kspacing (float) – Generate a grid of k-points with this as the minimum distance, in A^-1 between them in reciprocal space. If set to None, kpts will be used instead.

  • kpts ((int, int, int) or dict) – If kpts is a tuple (or list) of 3 integers, it is interpreted as the dimensions of a Monkhorst-Pack grid. If kpts is set to None, only the Γ-point will be included and QE will use routines optimized for Γ-point-only calculations. Compared to Γ-point-only calculations without this optimization (i.e. with kpts=(1, 1, 1)), the memory and CPU requirements are typically reduced by half. If kpts is a dict, it will either be interpreted as a path in the Brillouin zone (*) if it contains the ‘path’ keyword, otherwise it is converted to a Monkhorst-Pack grid (**). (*) see ase.dft.kpoints.bandpath (**) see ase.calculators.calculator.kpts2sizeandoffsets

  • koffset ((int, int, int)) – Offset of kpoints in each direction. Must be 0 (no offset) or 1 (half grid offset). Setting to True is equivalent to (1, 1, 1).

  • crystal_coordinates (bool) – Whether the atomic positions should be written to the QE input file in absolute (False, default) or relative (crystal) coordinates (True).

espresso-out, index=slice(None, None, None), results_required=True)[source]

Reads Quantum ESPRESSO output files.

The atomistic configurations as well as results (energy, force, stress, magnetic moments) of the calculation are read for all configurations within the output file.

Will probably raise errors for broken or incomplete files.

  • fileobj (file|str) – A file like object or filename

  • index (slice) – The index of configurations to extract.

  • results_required (bool) – If True, atomistic configurations that do not have any associated results will not be included. This prevents double printed configurations and incomplete calculations from being returned as the final configuration with no results data.


structure (Atoms) – The next structure from the index slice. The Atoms has a SinglePointCalculator attached with any results parsed from the file.


No automatic documentation of this module found.

Visit to see if you find the information needed in the source code.

extxyz, index=-1, properties_parser=<function key_val_str_to_dict>)

Read from a file in Extended XYZ format

index is the frame to read, default is last frame (index=-1). properties_parser is the parse to use when converting the properties line to a dictionary, extxyz.key_val_str_to_dict is the default and can deal with most use cases, extxyz.key_val_str_to_dict_regex is slightly faster but has fewer features.

Extended XYZ format is an enhanced version of the basic XYZ format that allows extra columns to be present in the file for additonal per-atom properties as well as standardising the format of the comment line to include the cell lattice and other per-frame parameters.

It’s easiest to describe the format with an example. Here is a standard XYZ file containing a bulk cubic 8 atom silicon cell

Cubic bulk silicon cell
Si          0.00000000      0.00000000      0.00000000
Si        1.36000000      1.36000000      1.36000000
Si        2.72000000      2.72000000      0.00000000
Si        4.08000000      4.08000000      1.36000000
Si        2.72000000      0.00000000      2.72000000
Si        4.08000000      1.36000000      4.08000000
Si        0.00000000      2.72000000      2.72000000
Si        1.36000000      4.08000000      4.08000000

The first line is the number of atoms, followed by a comment and then one line per atom, giving the element symbol and cartesian x y, and z coordinates in Angstroms.

Here’s the same configuration in extended XYZ format

Lattice="5.44 0.0 0.0 0.0 5.44 0.0 0.0 0.0 5.44" Properties=species:S:1:pos:R:3 Time=0.0
Si        0.00000000      0.00000000      0.00000000
Si        1.36000000      1.36000000      1.36000000
Si        2.72000000      2.72000000      0.00000000
Si        4.08000000      4.08000000      1.36000000
Si        2.72000000      0.00000000      2.72000000
Si        4.08000000      1.36000000      4.08000000
Si        0.00000000      2.72000000      2.72000000
Si        1.36000000      4.08000000      4.08000000

In extended XYZ format, the comment line is replaced by a series of key/value pairs. The keys should be strings and values can be integers, reals, logicals (denoted by \(T\) and \(F\) for true and false) or strings. Quotes are required if a value contains any spaces (like \(Lattice\) above). There are two mandatory parameters that any extended XYZ: \(Lattice\) and \(Properties\). Other parameters – e.g. \(Time\) in the example above — can be added to the parameter line as needed.

\(Lattice\) is a Cartesian 3x3 matrix representation of the cell vectors, with each vector stored as a column and the 9 values listed in Fortran column-major order, i.e. in the form

Lattice="R1x R1y R1z R2x R2y R2z R3x R3y R3z"

where \(R1x R1y R1z\) are the Cartesian x-, y- and z-components of the first lattice vector (\(\mathbf{a}\)), \(R2x R2y R2z\) those of the second lattice vector (\(\mathbf{b}\)) and \(R3x R3y R3z\) those of the third lattice vector (\(\mathbf{c}\)).

The list of properties in the file is described by the \(Properties\) parameter, which should take the form of a series of colon separated triplets giving the name, format (\(R\) for real, \(I\) for integer) and number of columns of each property. For example:


indicates the first column represents atomic species, the next three columns represent atomic positions, the next three velcoities, and the last is an single integer called \(select\). With this property definition, the line

Si        4.08000000      4.08000000      1.36000000   0.00000000      0.00000000      0.00000000       1

would describe a silicon atom at position (4.08,4.08,1.36) with zero velocity and the \(select\) property set to 1.

The property names \(pos\), \(Z\), \(mass\), and \(charge\) map to ASE ase.atoms.Atoms.arrays entries named \(positions\), \(numbers\), \(masses\) and \(charges\) respectively.

Additional key-value pairs in the comment line are parsed into the dictionary, with the following conventions

  • Values can be quoted with \(""\), \(''\), \([]\) or \({}\) (the latter are included to ease command-line usage as the \({}\) are not treated specially by the shell)

  • Quotes within keys or values can be escaped with \(\"\).

  • Keys with special names \(stress\) or \(virial\) are treated as 3x3 matrices in Fortran order, as for \(Lattice\) above.

  • Otherwise, values with multiple elements are treated as 1D arrays, first assuming integer format and falling back to float if conversion is unsuccessful.

  • A missing value defaults to \(True\), e.g. the comment line \("cutoff=3.4 have_energy"\) leads to \({'cutoff': 3.4, 'have_energy': True}\) in \(\).

  • Value strings starting with \("_JSON"\) are interpreted as JSON content; similarly, when writing, anything which does not match the criteria above is serialised as JSON.

The extended XYZ format is also supported by the the Ovito visualisation tool., images, comment='', columns=None, write_info=True, write_results=True, plain=False, vec_cell=False)

Write output in extended XYZ format

Optionally, specify which columns (arrays) to include in output, whether to write the contents of the \(\) dict to the XYZ comment line (default is True), the results of any calculator attached to this Atoms. The \(plain\) argument can be used to write a simple XYZ file with no additional information. \(vec_cell\) can be used to write the cell vectors as additional pseudo-atoms.

See documentation for read_xyz() for further details of the extended XYZ file format.

findsym, images)[source]

gamess-us-in, atoms, properties=None, **params)[source]



gaussian-in, attach_calculator=False)[source]

Reads a gaussian input file and returns an Atoms object.

  • fd (file-like) – Contains the contents of a gaussian input file

  • attach_calculator (bool) – When set to True, a Gaussian calculator will be attached to the Atoms object which is returned. This will mean that additional information is read from the input file (see below for details).


An Atoms object containing the following information that has been read from the input file: symbols, positions, cell.

Return type:



Gaussian input files can be read where the atoms’ locations are set with cartesian coordinates or as a z-matrix. Variables may be used in the z-matrix definition, but currently setting constants for constraining a geometry optimisation is not supported. Note that the \(alternative\) z-matrix definition where two bond angles are set instead of a bond angle and a dihedral angle is not currently supported.

If the parameter attach_calculator is set to True, then the Atoms object is returned with a Gaussian calculator attached.

This Gaussian calculator will contain a parameters dictionary which will contain the Link 0 commands and the options and keywords set in the route section of the Gaussian input file, as well as:

  • The charge and multiplicity

  • The selected level of output

  • The method, basis set and (optional) fitting basis set.

  • Basis file name/definition if set

  • Nuclear properties

  • Masses set in the nuclear properties section or in the ReadIsotopes section (if freq=ReadIso is set). These will be saved in an array with keyword isolist, in the parameters dictionary. For these to actually be used in calculations and/or written out to input files, the Atoms object’s masses must be manually updated to these values (this is not done automatically)

If the Gaussian input file has been generated by ASE’s write_gaussian_in method, then the basis set, method and fitting basis will be saved under the basis, method and fitting_basis keywords in the parameters dictionary. Otherwise they are saved as keywords in the parameters dict.

Currently this does not support reading of any other sections which would be found below the molecule specification that have not been mentioned here (such as the ModRedundant section)., atoms, properties=['energy'], method=None, basis=None, fitting_basis=None, output_type='P', basisfile=None, basis_set=None, xc=None, charge=None, mult=None, extra=None, ioplist=None, addsec=None, spinlist=None, zefflist=None, qmomlist=None, nmagmlist=None, znuclist=None, radnuclearlist=None, **params)[source]

Generates a Gaussian input file

  • fd (file-like) – where the Gaussian input file will be written

  • atoms (Atoms) – Structure to write to the input file

  • properties (list) – Properties to calculate

  • method (str) – Level of theory to use, e.g. hf, ccsd, mp2, or b3lyp. Overrides xc (see below).

  • xc (str) – Level of theory to use. Translates several XC functionals from their common name (e.g. PBE) to their internal Gaussian name (e.g. PBEPBE).

  • basis (str) – The basis set to use. If not provided, no basis set will be requested, which usually results in STO-3G. Maybe omitted if basisfile is set (see below).

  • fitting_basis (str) – The name of the fitting basis set to use.

  • output_type (str) – Level of output to record in the Gaussian output file - this may be N- normal or P - additional.

  • basisfile (str) – The name of the basis file to use. If a value is provided, basis may be omitted (it will be automatically set to ‘gen’)

  • basis_set (str) – The basis set definition to use. This is an alternative to basisfile, and would be the same as the contents of such a file.

  • charge (int) – The system charge. If not provided, it will be automatically determined from the Atoms object’s initial_charges.

  • mult (int) – The system multiplicity (spin + 1). If not provided, it will be automatically determined from the Atoms object’s initial_magnetic_moments.

  • extra (str) – Extra lines to be included in the route section verbatim. It should not be necessary to use this, but it is included for backwards compatibility.

  • ioplist (list) – A collection of IOPs definitions to be included in the route line.

  • addsec (str) – Text to be added after the molecular geometry specification, e.g. for defining masses with freq=ReadIso.

  • spinlist (list) – A list of nuclear spins to be added into the nuclear propeties section of the molecule specification.

  • zefflist (list) – A list of effective charges to be added into the nuclear propeties section of the molecule specification.

  • qmomlist (list) – A list of nuclear quadropole moments to be added into the nuclear propeties section of the molecule specification.

  • nmagmlist (list) – A list of nuclear magnetic moments to be added into the nuclear propeties section of the molecule specification.

  • znuclist (list) – A list of nuclear charges to be added into the nuclear propeties section of the molecule specification.

  • radnuclearlist (list) – A list of nuclear radii to be added into the nuclear propeties section of the molecule specification.

  • params (dict) – Contains any extra keywords and values that will be included in either the link0 section or route section of the gaussian input file. To be included in the link0 section, the keyword must be one of the following: mem, chk, oldchk, schk, rwf, oldmatrix, oldrawmatrix, int, d2e, save, nosave, errorsave, cpu, nprocshared, gpucpu, lindaworkers, usessh, ssh, debuglinda. Any other keywords will be placed (along with their values) in the route section.

gaussian-out, index=-1)[source]

Reads a gaussian output file and returns an Atoms object.


Read structure in GEN format (refer to DFTB+ manual). Multiple snapshot are not allowed., images: Union[Atoms, Sequence[Atoms]], fractional: bool = False)[source]

Write structure in GEN format (refer to DFTB+ manual). Multiple snapshots are not allowed.

gif, images, writer=None, interval=200, save_count=None, save_parameters=None, ax=None, **kwargs)

gpaw-out, index)[source]

Read text output from GPAW calculation.

gpumd, species=None, isotope_masses=None)[source]

Read Atoms object from a GPUMD structure input file

  • fd (file | str) – File object or name of file from which to read the Atoms object

  • species (List[str]) – List with the chemical symbols that correspond to each type, will take precedence over isotope_masses

  • isotope_masses (Dict[str, List[float]]) – Dictionary with chemical symbols and lists of the associated atomic masses, which is used to identify the chemical symbols that correspond to the types not found in species_types. The default is to find the closest match


atoms – Atoms object

Return type:



ValueError – Raised if the list of species is incompatible with the input file, atoms, maximum_neighbors=None, cutoff=None, groupings=None, use_triclinic=False, species=None)[source]

Writes atoms into GPUMD input format.

  • fd (file) – File like object to which the atoms object should be written

  • atoms (Atoms) – Input structure

  • maximum_neighbors (int) – Maximum number of neighbors any atom can ever have (not relevant when using force constant potentials)

  • cutoff (float) – Initial cutoff distance used for building the neighbor list (not relevant when using force constant potentials)

  • groupings (list[list[list[int]]]) – Groups into which the individual atoms should be divided in the form of a list of list of lists. Specifically, the outer list corresponds to the grouping methods, of which there can be three at the most, which contains a list of groups in the form of lists of site indices. The sum of the lengths of the latter must be the same as the total number of atoms.

  • use_triclinic (bool) – Use format for triclinic cells

  • species (List[str]) – GPUMD uses integers to define atom types. This list allows customized such definitions (e.g, [‘Pd’, ‘H’] means Pd is type 0 and H type 1). If None, this list is built by assigning each distinct species to an integer in the order of appearance in \(atoms\).


ValueError – Raised if parameters are incompatible



From: C format “%5d%-5s%5s%5d%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f” python: starting from 0, including first excluding last 0:4 5:10 10:15 15:20 20:28 28:36 36:44 44:52 52:60 60:68

Import gromacs geometry type files (.gro). Reads atom positions, velocities(if present) and simulation cell (if present), atoms)[source]

Write gromacs geometry files (.gro).


  • atom positions,

  • velocities (if present, otherwise 0)

  • simulation cell (if present)


Read gromos geometry files (.g96). Reads: atom positions, and simulation cell (if present) tries to set atom types, atoms)[source]

Write gromos geometry files (.g96). Writes: atom positions, and simulation cell (if present)

html, atoms)[source]

Writes to html using X3DOM.

  • object (filename or output file) –

  • object

  • rendered (atoms - Atoms object to be) –

json, index, **kwargs), images, append=False, **kwargs)


Reads a JSV file., atoms)[source]

Writes JSV file.

lammps-data, Z_of_type: dict = None, sort_by_id: bool = True, read_image_flags: bool = True, units: str = 'metal', atom_style: str = None, style: str = None)[source]

Method which reads a LAMMPS data file.

  • fileobj (file | str) – File from which data should be read.

  • Z_of_type (dict[int, int], optional) – Mapping from LAMMPS atom types (typically starting from 1) to atomic numbers. If None, if there is the “Masses” section, atomic numbers are guessed from the atomic masses. Otherwise, atomic numbers of 1 (H), 2 (He), etc. are assigned to atom types of 1, 2, etc. Default is None.

  • sort_by_id (bool, optional) – Order the particles according to their id. Might be faster to set it False. Default is True.

  • read_image_flags (bool, default True) – If True, the lattice translation vectors derived from image flags are added to atomic positions.

  • units (str, optional) – LAMMPS units. Default is ‘metal’.

  • atom_style ({'atomic', 'charge', 'full'} etc., optional) – LAMMPS atom style. If None, \(atom_style\) is guessed in the following priority (1) comment after \(Atoms\) (2) length of fields (valid only \(atomic\) and \(full\)). Default is None., atoms: Atoms, *, specorder: list = None, reduce_cell: bool = False, force_skew: bool = False, prismobj: Prism = None, write_image_flags: bool = False, masses: bool = False, velocities: bool = False, units: str = 'metal', atom_style: str = 'atomic')[source]

Write atomic structure data to a LAMMPS data file.

  • fd (file|str) – File to which the output will be written.

  • atoms (Atoms) – Atoms to be written.

  • specorder (list[str], optional) – Chemical symbols in the order of LAMMPS atom types, by default None

  • force_skew (bool, optional) – Force to write the cell as a triclinic box, by default False

  • reduce_cell (bool, optional) – Whether the cell shape is reduced or not, by default False

  • prismobj (Prism|None, optional) – Prism, by default None

  • write_image_flags (bool, default False) – If True, the image flags, i.e., in which images of the periodic simulation box the atoms are, are written.

  • masses (bool, optional) – Whether the atomic masses are written or not, by default False

  • velocities (bool, optional) – Whether the atomic velocities are written or not, by default False

  • units (str, optional) – LAMMPS units, by default ‘metal’

  • atom_style ({'atomic', 'charge', 'full'}, optional) – LAMMPS atom style, by default ‘atomic’

lammps-dump-binary, index=-1, colnames=None, intformat='SMALLBIG', **kwargs)[source]

Read binary dump-files (after binary2txt.cpp from lammps/tools)

  • fileobj – file-stream containing the binary lammps data

  • index – integer or slice object (default: get the last timestep)

  • colnames – data is columns and identified by a header

  • intformat – lammps support different integer size. Parameter set at compile-time and can unfortunately not derived from data file


list of Atoms-objects

Return type:


lammps-dump-text, index=-1, **kwargs)[source]

Process cleartext lammps dumpfiles

  • fileobj – filestream providing the trajectory data

  • index – integer or slice object (default: get the last timestep)


list of Atoms objects

Return type:


magres, include_unrecognised=False)[source]

Reader function for magres files., image)[source]

A writing function for magres files. Two steps: first data are arranged into structures, then dumped to the actual file

mol TextIO) Atoms

Read the sdf data and compose the corresponding Atoms object.

mp4, images, writer=None, interval=200, save_count=None, save_parameters=None, ax=None, **kwargs)


Import muSTEM input file.

Reads cell, atom positions, etc. from muSTEM xtl file. The mustem xtl save the root mean square (RMS) displacement, which is convert to Debye-Waller (in Ų) factor by:

\[B = RMS * 8\pi^2\], *args, **kwargs)[source]

Write muSTEM input file.


atoms: Atoms object

keV: float

Energy of the electron beam in keV required for the image simulation.

debye_waller_factors: float or dictionary of float with atom type as key

Debye-Waller factor of each atoms. Since the prismatic/computem software use root means square RMS) displacements, the Debye-Waller factors (B) needs to be provided in Ų and these values are converted to RMS displacement by:

\[RMS = \frac{B}{8\pi^2}\]
occupancies: float or dictionary of float with atom type as key (optional)

Occupancy of each atoms. Default value is \(1.0\).

comment: str (optional)

Comments to be written in the first line of the file. If not provided, write the total number of atoms and the chemical formula.

fit_cell_to_atoms: bool (optional)

If \(True\), fit the cell to the atoms positions. If negative coordinates are present in the cell, the atoms are translated, so that all positions are positive. If \(False\) (default), the atoms positions and the cell are unchanged.

mysql, index, **kwargs), images, append=False, **kwargs)

netcdftrajectory, index=-1)[source], images)[source]

nomad-json, index)[source]

nwchem-in, index=-1)[source], atoms, properties=None, echo=False, **params)[source]

Writes NWChem input file.

See NWChem for available params.

  • fd – file descriptor

  • atoms – atomic configuration

  • properties – list of properties to compute; by default only the calculation of the energy is requested

  • echo – if True include the \(echo\) keyword at the top of the file, which causes the content of the input file to be included in the output file

  • params – dict of instructions blocks to be included

nwchem-out, index=-1)[source]

Splits an NWChem output file into chunks corresponding to individual single point calculations.

octopus-in, get_kwargs=False)[source]

onetep-in, **kwargs)[source]

Read a single ONETEP input.

This function can be used to visually check ONETEP inputs, using the ase gui. It can also be used to get access to the input parameters attached to the ONETEP calculator returned

The function should work on inputs which contain ‘include_file’ command(s), (possibly recursively but untested)

The function should work on input which contains exotic element(s) name(s) if the specie block is present to map them back to real element(s)


fd (io-object) – File to read.


structure – Atoms object with cell and a Onetep calculator attached which contains the keywords dictionary

Return type:

Atoms, atoms, edft=False, xc='PBE', ngwf_count=-1, ngwf_radius=9.0, keywords={}, pseudopotentials={}, pseudo_path='.', pseudo_suffix=None, **kwargs)[source]

Write a single ONETEP input.

This function will be used by ASE to perform various workflows (Opt, NEB…) or can be used manually to quickly create ONETEP input file(s).

The function will first write keywords in alphabetic order in lowercase. Secondly, blocks will be written in alphabetic order in uppercase.

Two ways to work with the function:

  • By providing only (simple) keywords present in the parameters. ngwf_count and ngwf_radius accept multiple types as described in the Parameters section.

  • If the keywords parameters is provided as a dictionary these keywords will be used to write the input file and will take priority.

If no pseudopotentials are provided in the parameters and the function will try to look for suitable pseudopotential in the pseudo_path.

  • fd (file) – File to write.

  • atoms (Atoms) – Atoms including Cell object to write.

  • edft (Bool) – Activate EDFT.

  • xc (str) – DFT xc to use e.g (PBE, RPBE, …)

  • ngwf_count (int|list|dict) –

    Behaviour depends on the type:

    int: every species will have this amount of ngwfs. list: list of int, will be attributed alphabetically to species: dict: keys are species name(s), value are their number:

  • ngwf_radius (int|list|dict) –

    Behaviour depends on the type:

    float: every species will have this radius. list: list of float, will be attributed alphabetically to species: [10.0, 9.0] dict: keys are species name(s), value are their radius: {‘Na’: 9.0, ‘Cl’: 10.0}

  • keywords (dict) – Dictionary with ONETEP keywords to write, keywords with lists as values will be treated like blocks, with each element of list being a different line.

  • pseudopotentials (dict) –

    Behaviour depends on the type:

    keys are species name(s) their value are the pseudopotential file to use: {‘Na’: ‘Na.usp’, ‘Cl’: ‘Cl.usp’}

  • pseudo_path (str) – Where to look for pseudopotential, correspond to the pseudo_path keyword of ONETEP.

  • pseudo_suffix (str) – Suffix for the pseudopotential filename to look for, useful if you have multiple sets of pseudopotentials in pseudo_path.

onetep-out, index=-1, improving=False, **kwargs)[source]

Read ONETEP output(s).

!!! This function will be used by ASE when performing various workflows (Opt, NEB…) !!!

  • fd (file) – File to read.

  • index (slice) – Which atomic configuration to read

  • improving (Bool) – If the output is a geometry optimisation, improving = True will keep line search configuration from BFGS


structure (Atoms|list of Atoms)

png, atoms, **parameters)[source]

postgresql, index, **kwargs), images, append=False, **kwargs)

pov, atoms, *, povray_settings=None, isosurface_data=None, **generic_projection_settings)[source]


Import prismatic and computem xyz input file as an Atoms object.

Reads cell, atom positions, occupancies and Debye Waller factor. The occupancy values and the Debye Waller factors are obtained using the \(get_array\) method and the \(occupancies\) and \(debye_waller_factors\) keys, respectively. The root means square (RMS) values from the prismatic/computem xyz file are converted to Debye-Waller factors (B) in Ų by:

\[B = RMS^2 * 8\pi^2\], *args, **kwargs)[source]

Write xyz input file for the prismatic and computem software. The cell needs to be orthorhombric. If the cell contains the \(occupancies\) and \(debye_waller_factors\) arrays (see the \(set_array\) method to set them), these array will be written to the file. If the occupancies is not specified, the default value will be set to 0.


atoms: Atoms object

debye_waller_factors: float or dictionary of float or None (optional).

If float, set this value to all atoms. If dictionary, each atom needs to specified with the symbol as key and the corresponding Debye-Waller factor as value. If None, the \(debye_waller_factors\) array of the Atoms object needs to be set (see the \(set_array\) method to set them), otherwise raise a ValueError. Since the prismatic/computem software use root means square (RMS) displacements, the Debye-Waller factors (B) needs to be provided in Ų and these values are converted to RMS displacement by:

\[RMS = \sqrt{\frac{B}{8\pi^2}}\]

Default is None.

comment: str (optional)

Comments to be written in the first line of the file. If not provided, write the total number of atoms and the chemical formula.

proteindatabank, index=-1, read_arrays=True)[source]

Read PDB files., images, write_arrays=True)[source]

Write images to PDB-file.

py, images)[source]

Write to ASE-compatible python script.

qbox, index=-1)[source]

Read data from QBox output file


f - str or fileobj, path to file or file object to read from index - int or slice, which frames to return


list of Atoms or atoms, requested frame(s)

res, index=-1)[source]

Read input in SHELX (.res) format

Multiple frames are read if \(filename\) contains a wildcard character, e.g. \(file_*.res\). \(index\) specifes which frames to retun: default is last frame only (index=-1)., images, write_info=True, write_results=True, significant_figures=6)[source]

Write output in SHELX (.res) format

To write multiple images, include a % format string in filename, e.g. \(file_%03d.res\).

Optionally include contents of dictionary if \(write_info\) is True, and/or results from attached calculator if \(write_results\) is True (only energy results are supported).

rmc6f, atom_type_map=None)[source]

Parse a RMCProfile rmc6f file into ASE Atoms object

  • filename (file|str) – A file like object or filename.

  • atom_type_map (dict{str:str}) –

    Map of atom types for conversions. Mainly used if there is an atom type in the file that is not supported by ASE but want to map to a supported atom type instead.

    Example to map deuterium to hydrogen: atom_type_map = { ‘D’: ‘H’ }


structure – The Atoms object read in from the rmc6f file.

Return type:

Atoms, atoms, order=None, atom_type_map=None)[source]

Write output in rmc6f format - RMCProfile v6 fractional coordinates

  • filename (file|str) – A file like object or filename.

  • atoms (Atoms object) – The Atoms object to be written.

  • order (list[str]) – If not None, gives a list of atom types for the order to write out each.

  • atom_type_map (dict{str:str}) –

    Map of atom types for conversions. Mainly used if there is an atom type in the Atoms object that is a placeholder for a different atom type. This is used when the atom type is not supported by ASE but is in RMCProfile.

    Example to map hydrogen to deuterium: atom_type_map = { ‘H’: ‘D’ }

sdf TextIO) Atoms[source]

Read the sdf data and compose the corresponding Atoms object.


struct, ase=True)[source], atoms2=None, rmt=None, lattice='P', zza=None)[source]


Read a siesta struct file


Function to read a qb@ll sys file.

fileobj: file (object) to read from., atoms)[source]

Function to write a sys file.

fileobj: file object

File to which output is written.

atoms: Atoms object

Atoms object specifying the atomic configuration.

traj, index)[source], images)[source]

Write image(s) to trajectory.


Method to read turbomole coord file

coords in bohr, atom types in lowercase, format: $coord x y z atomtype x y z atomtype f $end Above ‘f’ means a fixed atom., atoms)[source]

Method to write turbomole coord file

turbomole-gradient, index=-1)[source]

Method to read turbomole gradient file


Import V_Sim input file.

Reads cell, atom positions, etc. from v_sim ascii file. V_sim format is specified here:, atoms)[source]

Write V_Sim input file.

Writes the atom positions and unit cell. V_sim format is specified here:


Import POSCAR/CONTCAR type file.

Reads unitcell, atom positions and constraints from the POSCAR/CONTCAR file and tries to read atom types from POSCAR/CONTCAR header, if this fails the atom types are read from OUTCAR or POTCAR file. TextIO, atoms: Atoms, direct: bool = False, sort: bool = False, symbol_count: Optional[List[Tuple[str, int]]] = None, vasp5: bool = True, vasp6: bool = False, ignore_constraints: bool = False, potential_mapping: Optional[dict] = None) None[source]

Method to write VASP position (POSCAR/CONTCAR) files.

Writes label, scalefactor, unitcell, # of various kinds of atoms, positions in cartesian or scaled coordinates (Direct), and constraints to file. Cartesian coordinates is default and default label is the atomic species, e.g. ‘C N H Cu’.

  • fd (TextIO) – writeable Python file descriptor

  • atoms (ase.Atoms) – Atoms to write

  • direct (bool) – Write scaled coordinates instead of cartesian

  • sort (bool) – Sort the atomic indices alphabetically by element

  • symbol_count (list of tuples of str and int, optional) – Use the given combination of symbols and counts instead of automatically compute them

  • vasp5 (bool) – Write to the VASP 5+ format, where the symbols are written to file

  • vasp6 (bool) – Write symbols in VASP 6 format (which allows for potential type and hash)

  • ignore_constraints (bool) – Ignore all constraints on \(atoms\)

  • potential_mapping (dict, optional) – Map of symbols to potential file (and hash). Only works if \(vasp6=True\). See \(_symbol_string_count\)


RuntimeError – raised if any of these are true: 1. \(atoms\) is not a single \(ase.Atoms\) object. 2. The cell dimensionality is lower than 3 (0D-2D) 3. One FixedPlane normal is not parallel to a unit cell vector 4. One FixedLine direction is not parallel to a unit cell vector

vasp-out'OUTCAR', index=-1)[source]

Import OUTCAR type file.

Reads unitcell, atom positions, energies, and forces from the OUTCAR file and attempts to read constraints (if any) from CONTCAR/POSCAR, if present.

vasp-xdatcar'XDATCAR', index=-1)[source]

Import XDATCAR file.


index (int or slice or str) – Which frame(s) to read. The default is -1 (last frame). See for details.


Constraints ARE NOT stored in the XDATCAR, and as such, Atoms objects retrieved from the XDATCAR will not have constraints., images, label=None)[source]

Write VASP MD trajectory (XDATCAR) file

Only Vasp 5 format is supported (for consistency with read_vasp_xdatcar)

  • fd (str, fp) – Output file

  • images (iterable of Atoms) – Atoms images to write. These must have consistent atom order and lattice vectors - this will not be checked.

  • label (str) – Text for first line of file. If empty, default to list of elements.

vasp-xml'vasprun.xml', index=-1)[source]

Parse vasprun.xml file.

Reads unit cell, atom positions, energies, forces, and constraints from vasprun.xml file


>>> import
>>>"out.traj","vasprun.xml", index=":"))

vti, atoms, data=None)[source]

vtu, atoms, data=None)[source]

wout IO[str], include_wannier_function_centers: bool = True) Atoms[source]

Read atoms and wannier function centers (as symbol X).

x3d, atoms, format='X3D', style=None)[source]

Writes to html using X3DOM.

  • object (filename or output file) –

  • object

  • rendered (atoms - Atoms object to be) –

  • str (format -) – to be readable by Blender. \(None\) to detect format based on file extension (‘.html’ -> ‘X3DOM’, ‘.x3d’ -> ‘X3D’)

  • 'X3D' (either 'X3DOM' for web-browser compatibility or) – to be readable by Blender. \(None\) to detect format based on file extension (‘.html’ -> ‘X3DOM’, ‘.x3d’ -> ‘X3D’)

  • dict (style -) –

  • element (css style attributes for the X3D) –

xsd[source], images, connectivity=None)[source]

Takes Atoms object, and write materials studio file atoms: Atoms object filename: path of the output file connectivity: number of atoms by number of atoms matrix for connectivity between atoms (0 not connected, 1 connected)

note: material studio file cannot use a partial periodic system. If partial perodic system was inputted, full periodicity was assumed.

xsf, index=-1, read_data=False)[source], images, data=None, origin=None, span_vectors=None)[source]

xtd, index=-1)[source]

Import xtd file (Materials Studio)

Xtd files always come with arc file, and arc file contains all the relevant information to make atoms so only Arc file needs to be read, images, connectivity=None, moviespeed=10)[source]

Takes Atoms object, and write materials studio file atoms: Atoms object filename: path of the output file moviespeed: speed of animation. between 0 and 10

note: material studio file cannot use a partial periodic system. If partial perodic system was inputted, full periodicity was assumed.

xyz, index)[source], images, comment='', fmt='%22.15f')[source]