Format Specific Options

abinit-in

ase.io.abinit.read_abinit_in(fd)

Import ABINIT input file.

Reads cell, atom positions, etc. from abinit input file

ase.io.abinit.write_abinit_in(fd, atoms, param=None, species=None, pseudos=None)

abinit-out

ase.io.abinit.read_abinit_out(fd)

acemolecule-input

ase.io.acemolecule.read_acemolecule_input(filename)

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

Return type

ASE atoms object containing geometry only.

acemolecule-out

ase.io.acemolecule.read_acemolecule_out(filename)

Interface to ACEMoleculeReader and return values for corresponding quantity :param filename: :type filename: ACE-Molecule log file. :param quantity: :type quantity: One of atoms, energy, forces, excitation-energy.

Returns

• - 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

ase.io.aims.read_aims(fd, apply_constraints=True)

Import FHI-aims geometry type files.

Reads unitcell, atom positions and constraints from a geometry.in file.

If geometric constraint (symmetry parameters) are in the file include that information in atoms.info[“symmetry_block”]

ase.io.aims.write_aims(fd, atoms, scaled=False, geo_constrain=False, velocities=False, ghosts=None, info_str=None, wrap=False)

Method to write FHI-aims geometry files.

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

Parameters

• 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: https://arxiv.org/abs/1908.01610

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

• 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

aims-output

ase.io.aims.read_aims_output(fd, index=-1)

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

bundletrajectory

ase.io.bundletrajectory.read_bundletrajectory(filename, index=-1)

Reads one or more atoms objects from a BundleTrajectory.

Arguments:

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).

ase.io.bundletrajectory.write_bundletrajectory(filename, images, append=False)

Write image(s) to a BundleTrajectory.

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

castep-castep

ase.io.castep.read_castep_castep(fd, index=None)

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 ase.io

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

ase.io.castep.read_castep_cell(fd, 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})

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.

ase.io.castep.write_castep_cell(fd, atoms, positions_frac=False, force_write=False, precision=6, magnetic_moments=None, castep_cell=None)

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 formats.py

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

Parameters

• 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

ase.io.castep.read_castep_geom(fd, 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})

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 formats.py. Note that there is a fallback routine read_geom() that behaves like previous versions did.

castep-md

ase.io.castep.read_castep_md(fd, 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})

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

ase.io.castep.read_castep_phonon(fd, 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})

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.

cfg

ase.io.cfg.read_cfg(fd)

Read atomic configuration from a CFG-file (native AtomEye format). See: http://mt.seas.upenn.edu/Archive/Graphics/A/

ase.io.cfg.write_cfg(fd, atoms)

Write atomic configuration to a CFG-file (native AtomEye format). See: http://mt.seas.upenn.edu/Archive/Graphics/A/

cif

ase.io.cif.read_cif(fileobj, index, store_tags=False, primitive_cell=False, subtrans_included=True, fractional_occupancies=True, reader='ase') → Iterator[Atoms]

Read Atoms object from CIF file. index specifies the data block number or name (if string) to return.

If index is None or a slice object, a list of atoms objects will be returned. In the case of index is None or slice(None), only blocks with valid crystal data will be included.

If store_tags is true, the info attribute of the returned Atoms object will be populated with all tags in the corresponding cif data block.

If primitive_cell is true, the primitive cell will be built instead of the conventional cell.

If subtrans_included is 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.

If fractional_occupancies is 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.

String reader is used to select CIF reader. Value \(ase\) selects built-in CIF reader (default), while \(pycodcif\) selects CIF reader based on \(pycodcif\) package.

ase.io.cif.write_cif(fd, images, cif_format=None, wrap=True, labels=None, loop_keys=None) → None

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.

cmdft

ase.io.cmdft.read_cmdft(fileobj)

cml

ase.io.cml.read_cml(fileobj)

cp2k-dcd

ase.io.cp2k.read_cp2k_dcd(fileobj, index=-1, ref_atoms=None, aligned=False)

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: https://groups.google.com/forum/#!searchin/cp2k/Outputting$20cell$20information$20and$20fractional$20coordinates%7Csort:relevance/cp2k/72MhYykrSrQ/5c9Jaw7S9yQJ.

cp2k-restart

ase.io.cp2k.read_cp2k_restart(fileobj)

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.

crystal

ase.io.crystal.read_crystal(fd)

Method to read coordinates form ‘fort.34’ files additionally read information about periodic boundary condition

ase.io.crystal.write_crystal(fd, atoms)

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

cube

ase.io.cube.read_cube(fileobj, read_data=True, program=None, verbose=False)

Read atoms and data from CUBE file.

fileobjstr or file

Location to the cubefile.

read_databoolean

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.

verbosebool

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.

ase.io.cube.write_cube(fileobj, atoms, data=None, origin=None, comment=None)

Function to write a cube file.

fileobj: str or file object

File to which output is written.

atoms: Atoms object

Atoms object specifying the atomic configuration.

data3dim numpy array, optional (default = None)

Array containing volumetric data as e.g. electronic density

origin3-tuple

Origin of the volumetric data (units: Angstrom)

commentstr, optional (default = None)

Comment for the first line of the cube file.

dacapo-text

ase.io.dacapo.read_dacapo_text(fd)

db

ase.io.db.read_db(filename, index, **kwargs)

ase.io.db.write_db(filename, images, append=False, **kwargs)

dftb

ase.io.dftb.read_dftb(fd)

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 \(ase.io.gen\).

ase.io.dftb.write_dftb(fileobj, images)

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

dlp-history

ase.io.dlp4.read_dlp_history(f, index=-1, symbols=None)

Read a HISTORY file.

Compatible with DLP4 and DLP_CLASSIC.

Index can be integer or slice.

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

dlp4

ase.io.dlp4.read_dlp4(f, symbols=None)

Read a DL_POLY_4 config/revcon file.

Typically used indirectly through read(‘filename’, atoms, format=’dlp4’).

Can be unforgiven with custom chemical element names. Please complain to alin@elena.space for bugs.

ase.io.dlp4.write_dlp4(fd, atoms, levcfg=0, title='CONFIG generated by ASE')

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 alin@elena.space in case of bugs

dmol-arc

ase.io.dmol.read_dmol_arc(fd, index=-1)

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

ase.io.dmol.write_dmol_arc(fd, images)

Writes all images to file filename in arc format.

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

dmol-car

ase.io.dmol.read_dmol_car(fd)

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

Notes

Cell is constructed from cellpar so orientation of cell might be off.

ase.io.dmol.write_dmol_car(fd, atoms)

Write a dmol car-file from an Atoms object

Notes

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

ase.io.dmol.read_dmol_incoor(fd, bohr=True)

Reads an incoor file and returns an atoms object.

Notes

If bohr is True then incoor is assumed to be in bohr and the data is rescaled to Angstrom.

ase.io.dmol.write_dmol_incoor(fd, atoms, bohr=True)

Write a dmol incoor-file from an Atoms object

Notes

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.

elk

ase.io.elk.read_elk(fd)

Import ELK atoms definition.

Reads unitcell, atom positions, magmoms from elk.in/GEOMETRY.OUT file.

elk-in

ase.io.elk.write_elk_in(fd, atoms, parameters=None)

eon

ase.io.eon.read_eon(fileobj, index=-1)

Reads an EON reactant.con file. If fileobj is the name of a “states” directory created by EON, all the structures will be read.

ase.io.eon.write_eon(fileobj, images)

Writes structure to EON reactant.con file Multiple snapshots are allowed.

eps

ase.io.eps.write_eps(fd, atoms, **parameters)

espresso-in

ase.io.espresso.read_espresso_in(fileobj)

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.

Parameters

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

Returns

atoms – Structure defined in the input file.

Return type

Atoms

Raises

KeyError – Raised for missing keys that are required to process the file

ase.io.espresso.write_espresso_in(fd, atoms, input_data=None, pseudopotentials=None, kspacing=None, kpts=None, koffset=(0, 0, 0), crystal_coordinates=False, **kwargs)

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

  ase.constraints.FixCartesian.

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

• Automatic assignment of options to their correct sections.

• Interpretation of ibrav (cell must exactly match the vectors defined in the QE docs).

Not implemented:

• Lists of k-points

• Other constraints

• Hubbard parameters

• Validation of the argument types for input

• Validation of required options

• Reorientation for ibrav settings

• Noncollinear magnetism

Parameters

• fd (file) – A file like object to write the input file to.

• 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

ase.io.espresso.read_espresso_out(fileobj, index=-1, results_required=True)

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.

Parameters

• 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.

Yields

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

exciting

ase.io.exciting.read_exciting(fileobj, index=-1)

Reads structure from exiting xml file.

Parameters

• fileobj (file object) – File handle from which data should be read.

• index (integer -1) – Not used in this implementation.

ase.io.exciting.write_exciting(fileobj, images)

writes exciting input structure in XML

Parameters

• filename (str) – Name of file to which data should be written.

• images (Atom Object or List of Atoms objects) – This function will write the first Atoms object to file.

extxyz

ase.io.extxyz.read_extxyz(fileobj, 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

8
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

8
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:

Properties="species:S:1:pos:R:3:vel:R:3:select:I:1"

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 ase.Atoms.atoms.info 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 \(atoms.info\).

• 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 (from v2.4 beta onwards).

ase.io.extxyz.write_extxyz(fileobj, images, comment='', columns=None, write_info=True, write_results=True, plain=False, vec_cell=False, append=False)

Write output in extended XYZ format

Optionally, specify which columns (arrays) to include in output, whether to write the contents of the \(atoms.info\) 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. If \(append\) is set to True, the file is for append (mode \(a\)), otherwise it is overwritten (mode \(w\)).

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

findsym

ase.io.findsym.write_findsym(fileobj, images)

gamess-us-in

ase.io.gamess_us.write_gamess_us_in(fd, atoms, properties=None, **params)

gamess-us-out

ase.io.gamess_us.read_gamess_us_out(fd)

gamess-us-punch

ase.io.gamess_us.read_gamess_us_punch(fd)

gaussian-in

ase.io.gaussian.read_gaussian_in(fd, attach_calculator=False)

Reads a gaussian input file and returns an Atoms object.

Parameters

• 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).

Returns

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

Return type

Atoms

Notes

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).

ase.io.gaussian.write_gaussian_in(fd, 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)

Generates a Gaussian input file

Parameters

• 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

ase.io.gaussian.read_gaussian_out(fd, index=-1)

gen

ase.io.gen.read_gen(fileobj)

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

ase.io.gen.write_gen(fileobj, images)

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

gif

ase.io.animation.write_gif(filename, images, writer=None, interval=200, save_count=100, save_parameters=None, ax=None, **kwargs)

gpaw-out

ase.io.gpaw_out.read_gpaw_out(fileobj, index)

Read text output from GPAW calculation.

gpumd

ase.io.gpumd.read_gpumd(fd, species=None, isotope_masses=None)

Read Atoms object from a GPUMD structure input file

Parameters

• 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 ase.data.atomic_masses.

Returns

atoms – Atoms object

Return type

Atoms

Raises

ValueError – Raised if the list of species is incompatible with the input file

ase.io.gpumd.write_gpumd(fd, atoms, maximum_neighbors=None, cutoff=None, groupings=None, use_triclinic=False)

Writes atoms into GPUMD input format.

Parameters

• 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

Raises

ValueError – Raised if parameters are incompatible

gpw

ase.io.gpw.read_gpw(filename)

gromacs

ase.io.gromacs.read_gromacs(fd)

From: http://manual.gromacs.org/current/online/gro.html 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)

ase.io.gromacs.write_gromacs(fileobj, atoms)

Write gromacs geometry files (.gro).

Writes:

• atom positions,

• velocities (if present, otherwise 0)

• simulation cell (if present)

gromos

ase.io.gromos.read_gromos(fileobj)

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

ase.io.gromos.write_gromos(fileobj, atoms)

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

html

ase.io.x3d.write_html(fd, atoms)

Writes to html using X3DOM.

Parameters

• object (filename or output file) –

• object –

• rendered (atoms - Atoms object to be) –

json

ase.io.db.read_json(filename, index, **kwargs)

ase.io.db.write_json(filename, images, append=False, **kwargs)

jsv

ase.io.jsv.read_jsv(f)

Reads a JSV file.

ase.io.jsv.write_jsv(fd, atoms)

Writes JSV file.

lammps-data

ase.io.lammpsdata.read_lammps_data(fileobj, Z_of_type=None, style='full', sort_by_id=False, units='metal')

Method which reads a LAMMPS data file.

sort_by_id: Order the particles according to their id. Might be faster to switch it off. Units are set by default to the style=metal setting in LAMMPS.

ase.io.lammpsdata.write_lammps_data(fd, atoms, specorder=None, force_skew=False, prismobj=None, velocities=False, units='metal', atom_style='atomic')

Write atomic structure data to a LAMMPS data file.

lammps-dump-binary

ase.io.lammpsrun.read_lammps_dump_binary(fileobj, index=-1, colnames=None, intformat='SMALLBIG', **kwargs)

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

Parameters

• 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

Returns

list of Atoms-objects

Return type

list

lammps-dump-text

ase.io.lammpsrun.read_lammps_dump_text(fileobj, index=-1, **kwargs)

Process cleartext lammps dumpfiles

Parameters

• fileobj – filestream providing the trajectory data

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

Returns

list of Atoms objects

Return type

list

magres

ase.io.magres.read_magres(fd, include_unrecognised=False)

Reader function for magres files.

ase.io.magres.write_magres(fd, image)

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

mol

ase.io.mol.read_mol(fileobj)

mp4

ase.io.animation.write_mp4(filename, images, writer=None, interval=200, save_count=100, save_parameters=None, ax=None, **kwargs)

mustem

ase.io.mustem.read_mustem(fd)

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\]

ase.io.mustem.write_mustem(fd, *args, **kwargs)

Write muSTEM input file.

Parameters:

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

ase.io.db.read_mysql(filename, index, **kwargs)

ase.io.db.write_mysql(filename, images, append=False, **kwargs)

netcdftrajectory

ase.io.netcdftrajectory.read_netcdftrajectory(filename, index=-1)

ase.io.netcdftrajectory.write_netcdftrajectory(filename, images)

nomad-json

ase.io.nomad_json.read_nomad_json(fd, index)

nwchem-in

ase.io.nwchem.read_nwchem_in(fobj, index=-1)

ase.io.nwchem.write_nwchem_in(fd, atoms, properties=None, echo=False, **params)

Writes NWChem input file.

Parameters

• 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

ase.io.nwchem.read_nwchem_out(fobj, index=-1)

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

octopus-in

ase.io.octopus.read_octopus_in(fd, get_kwargs=False)

png

ase.io.png.write_png(filename, atoms, **parameters)

postgresql

ase.io.db.read_postgresql(filename, index, **kwargs)

ase.io.db.write_postgresql(filename, images, append=False, **kwargs)

pov

ase.io.pov.write_pov(filename, atoms, *, povray_settings=None, isosurface_data=None, **generic_projection_settings)

prismatic

ase.io.prismatic.read_prismatic(fd)

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\]

ase.io.prismatic.write_prismatic(fd, *args, **kwargs)

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.

Parameters:

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

ase.io.proteindatabank.read_proteindatabank(fileobj, index=-1, read_arrays=True)

Read PDB files.

ase.io.proteindatabank.write_proteindatabank(fileobj, images, write_arrays=True)

Write images to PDB-file.

py

ase.io.py.write_py(fileobj, images)

Write to ASE-compatible python script.

qbox

ase.io.qbox.read_qbox(f, index=-1)

Read data from QBox output file

Inputs:

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

Returns

list of Atoms or atoms, requested frame(s)

res

ase.io.res.read_res(filename, index=-1)

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).

ase.io.res.write_res(filename, images, write_info=True, write_results=True, significant_figures=6)

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 Atoms.info dictionary if \(write_info\) is True, and/or results from attached calculator if \(write_results\) is True (only energy results are supported).

rmc6f

ase.io.rmc6f.read_rmc6f(filename, atom_type_map=None)

Parse a RMCProfile rmc6f file into ASE Atoms object

Parameters

• 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’ }

Returns

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

Return type

Atoms

ase.io.rmc6f.write_rmc6f(filename, atoms, order=None, atom_type_map=None)

Write output in rmc6f format - RMCProfile v6 fractional coordinates

Parameters

• 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

ase.io.sdf.read_sdf(fileobj)

siesta-xv

ase.io.siesta.read_siesta_xv(fd)

struct

ase.io.wien2k.read_struct(fd, ase=True)

ase.io.wien2k.write_struct(fd, atoms2=None, rmt=None, lattice='P', zza=None)

struct_out

ase.io.siesta.read_struct_out(fd)

Read a siesta struct file

sys

ase.io.sys.read_sys(fileobj)

Function to read a qb@ll sys file.

fileobj: file (object) to read from.

ase.io.sys.write_sys(fileobj, atoms)

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

ase.io.trajectory.read_traj(fd, index)

ase.io.trajectory.write_traj(fd, images)

Write image(s) to trajectory.

turbomole

ase.io.turbomole.read_turbomole(fd)

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.

ase.io.turbomole.write_turbomole(fd, atoms)

Method to write turbomole coord file

turbomole-gradient

ase.io.turbomole.read_turbomole_gradient(fd, index=-1)

Method to read turbomole gradient file

v-sim

ase.io.v_sim.read_v_sim(fd)

Import V_Sim input file.

Reads cell, atom positions, etc. from v_sim ascii file

ase.io.v_sim.write_v_sim(fd, atoms)

Write V_Sim input file.

Writes the atom positions and unit cell.

vasp

ase.io.vasp.read_vasp(filename='CONTCAR')

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.

ase.io.vasp.write_vasp(filename, atoms, label=None, direct=False, sort=None, symbol_count=None, long_format=True, vasp5=True, ignore_constraints=False, wrap=False)

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’.

vasp-out

ase.io.vasp.read_vasp_out(filename='OUTCAR', index=-1)

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

ase.io.vasp.read_vasp_xdatcar(filename='XDATCAR', index=-1)

Import XDATCAR file

Reads all positions from the XDATCAR and returns a list of Atoms objects. Useful for viewing optimizations runs from VASP5.x

Constraints ARE NOT stored in the XDATCAR, and as such, Atoms objects retrieved from the XDATCAR will not have constraints set.

ase.io.vasp.write_vasp_xdatcar(fd, images, label=None)

Write VASP MD trajectory (XDATCAR) file

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

Parameters

• 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

ase.io.vasp.read_vasp_xml(filename='vasprun.xml', index=-1)

Parse vasprun.xml file.

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

vti

ase.io.vtkxml.write_vti(filename, atoms, data=None)

vtu

ase.io.vtkxml.write_vtu(filename, atoms, data=None)

wout

ase.io.wannier90.read_wout(fileobj: IO[str], include_wannier_function_centers: bool = True) → Atoms

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

x3d

ase.io.x3d.write_x3d(fd, atoms, format='X3D')

Writes to html using X3DOM.

Parameters

• 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’)

xsd

ase.io.xsd.read_xsd(fd)

ase.io.xsd.write_xsd(fd, images, connectivity=None)

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

ase.io.xsf.read_xsf(fileobj, index=-1, read_data=False)

ase.io.xsf.write_xsf(fileobj, images, data=None)

xtd

ase.io.xtd.read_xtd(filename, index=-1)

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

ase.io.xtd.write_xtd(filename, images, connectivity=None, moviespeed=10)

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

ase.io.xyz.read_xyz(fileobj, index)

ase.io.xyz.write_xyz(fileobj, images, comment='', fmt='%22.15f')