# Atoms objects¶

This module defines the Atoms, which stores and manipulates a collection of atoms, as well as the Connection class which stores topology and neighbour lists, and the DomainDecomposition class.

Module contents for quippy.atoms:

Classes

 Connection(*args, **kwargs) The Connection type stores the topology of a set of Atoms DomainDecomposition(*args, **kwargs) Initialize the domain decomposition module Atoms([symbols, positions, numbers, tags, ...) Representation of an atomic configuration and its associated properties NeighbourInfo(j, distance, diff, cosines, shift) Store information about a single neighbour of an atom

Functions

get_lattice_params(lattice) Wrapper around Fortran get_lattice_params_()
make_lattice(a,[b,c,alpha,beta,gamma,error]) Make a matrix of lattice vectors from the lengths a,b,c and the angles alpha, beta and gamma.
divide_cell(lattice,cutoff) Given a simulation cell defined by lattice vectors, how many
max_cutoff(lattice,[error]) Returns the maximum cutoff radius for calc_connect, given the lattice if we want to avoid image neghbours
parse_atom_mask(mask_in,[error]) Parses an atom_mask, which is string consisting of the @ symbol followed by a comma separated list of indices or ranges into a table containing all the indices it represents.
fit_box_in_cell(rx,ry,rz,lattice) Given an orthogonal box, oriented along the cartesian axes with lengths 2*rx, 2*ry and 2*rz
difference(list1,list2,[error]) Return the difference between list1 and list2 in outlist.
bond_length(z1,z2) Returns the sum of the covalent radii of two atoms
is_in_subregion(...)
termination_bond_rescale(z1,z2) Calculates the rescale ratio of a Z1–H bond generate from a Z1–Z2 bond.
get_min_max_images(...)
cell_volume(*args, **kwargs) calculate volume of unit cell
map_into_cell(*args, **kwargs) Map atomic positions into the unit cell so that lattice
get_lattice_params_(*args, **kwargs) Opposite of Make_Lattice.
get_lattice_params(lattice) Wrapper around Fortran get_lattice_params_()

Attributes

Name Value
DD_WRAP_TO_DOMAIN 2
NOT_NEIGHBOUR 0
DEFAULT_NNEIGHTOL 1.2
CONNECT_LATTICE_TOL 1e-08
DD_WRAP_TO_CELL 1
class quippy.atoms.Atoms([symbols, positions, numbers, tags, momenta, masses, magmoms, charges, scaled_positions, cell, pbc, constraint, calculator, info, n, lattice, properties, params, fixed_size, **read_args])[source]

Bases: quippy._atoms.Atoms, ase.atoms.Atoms

Representation of an atomic configuration and its associated properties

An atoms object contains atomic numbers, all dynamical variables and connectivity information for all the atoms in the simulation cell. It is initialised like this:

call initialise(MyAtoms,N,lattice)


where N is the number of atoms to allocate space for and lattice is a $$3\times3$$ matrix of lattice vectors given as column vectors, so that lattice(:,i) is the i-th lattice vector.

Atoms also contains a Connection object, which stores distance information about the atom neghbours after calc_connect has been called. Rather than using a minimum image convention, all neighbours are stored up to a radius of cutoff, including images

Initialise type(Atoms), pointer objects. Shallow copies of these will survive even if the initial declaration goes out of scope. The object will automatically deallocate upon calling finalise_ptr when the last shallow copy goes out of scope

The Atoms class is a Pythonic wrapper over the auto-generated quippy._atoms.Atoms class. Atoms object are usually constructed either by reading from an input file in one of the Supported File Formats, or by using the structure creation functions in the quippy.structures or ase.lattice modules.

For example to read from an Extended XYZ file, use:

from quippy.atoms import Atoms
atoms = Atoms('filename.xyz')


Or, to create an 8-atom bulk diamond cubic cell of silicon:

from quippy.structures import diamond
si_bulk = diamond(5.44, 14)


The Atoms class is inherited from the ase.atoms.Atoms so has all the ASE Atoms attributes and methods. This means that quippy and ASE Atoms objects are fully interoperable.

Parameters: n : input int lattice : input rank-2 array(‘d’) with bounds (3,3) properties : Dictionary object, optional params : Dictionary object, optional fixed_size : input int, optional nbuffer : input int, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine __init__initialise_ptr defined in file src/libAtoms/Atoms_types.f95. Class is wrapper around Fortran type Atoms defined in file src/libAtoms/Atoms_types.f95.

Attributes

 adsorbate_info Return the adsorbate information set by one of the surface builder functions. arrays Provides access to ASE arrays, stored in QUIP properties dict calc Calculator object. cell Attribute for direct manipulation of the unit cell. connect Connection object constraints Constraints of the atoms. cutoff Cutoff distance for neighbour calculations. cutoff_skin If set, increase cutoff by this amount to reduce calc_connect() frequency domain Domain decomposition object fixed_size Can the number of atoms be changed after initialisation? g Inverse lattice (stored for speed) hysteretic_connect Hysteretic Connection object indices Return array of atoms indices info ASE info dictionary lattice Lattice vectors, as columns: n The number of atoms held (including ghost particles) nbuffer The number of atoms that can be stored in the buffers of this Atoms object ndomain The number of atoms held by the local process (excluding ghost particles) nneightol Count as nearest neighbour if sum of covalent radii times this.nneightol greater than distance between atoms. number_of_lattice_vectors Number of (non-zero) lattice vectors. numbers Attribute for direct manipulation of the atomic numbers. own_this Do I own myself? params Dictionary of parameters. Useful for storing data about this pbc Attribute for direct manipulation of the periodic boundary condition flags. positions Attribute for direct manipulation of the positions. properties Dictionary of atomic properties. A property is an array ref_count Reference counter

Methods

add_atoms(*args, **kwargs) Add one or more atoms to an Atoms object.
add_cut_hydrogens(...) Given an atoms structure and a list of quantum atoms, find X-H bonds which have been cut and include the other atom of the pair in the quantum list.
add_property(name, value[, n_cols, ...]) Add a new property to this Atoms object.
add_property_from_pointer(*args, **kwargs) Add a per-atom property to this atoms object, but point to existing space rather than allocating new space for it (as add_property does).
angular_momentum([origin,indices]) Return the angular momentum of all the atoms in this DynamicalSystem, defined by $$\mathbf{L} = \sum_{i} \mathbf{r_i} \times \mathbf{v_i}$$.
append(atom) Append atom to end.
assignment(*args, **kwargs) Overloaded assigment operators for Atoms objects.
bfs_grow_list(...) On exit, list will have been grown by n bond hops.
bfs_grow_single(...) On exit, list will contain atom (with shift 000) plus the atoms within n bonds hops of it.
bfs_step(...) Execute one Breadth-First-Search move on the atomic connectivity graph.
calc_connect(*args, **kwargs) Fast $$O(N)$$ connectivity calculation routine.
calc_connect_hysteretic(*args, **kwargs) As for calc_connect, but perform the connectivity update hystertically: atoms must come within a relative distance of cutoff_factor to be considered neighbours, and then will remain connected until them move apart further than a relative distance of cutoff_break_factor (all cutoff factors are relative to covalent radii).
calc_dists(*args, **kwargs) Update stored distance tables.
calc_msd(at,[mask,reset_msd,persistent]) calculate mean squared displacement, with or without persistent atoms object
calc_qw(...)
calc_qw_grad(...)
cell_volume(*args, **kwargs) atoms_cell_volume
center([vacuum, axis, about]) Center atoms in unit cell.
centre_of_mass(at,[index_list,mask,origin,error]) Calculate the centre of mass of an atoms object, using the closest images to the origin atom, or first atom if this is not specified.
closest_atom(...)
coalesce_in_one_periodic_image(...) move atoms around following neighbor list bonds so that all are in the same periodic image
complement(at,inlist) Return the complement of a list, i.e.
copy() Return a copy of this Atoms object
copy_entry(*args, **kwargs) Copy an atom to a different index Move a single atom from one location to another one.
copy_from(other) Replace contents of this Atoms object with data from other.
copy_properties(*args, **kwargs) Copy some properties from one atoms struct to another The destination will be overriden.
copy_without_connect(...) Make a copy of the atoms object from without including connectivity information.
cosine(i,j,k,[error]) Cosine of the angle j–i–k
cosine_neighbour(i,n,m) Cosine of the angle n–i–m where {$$n,m$$} are the {:math:nth, :math:mth} neighbours of i
density() Density in units of $$g/m^3$$.
diff(i,j,shift) Difference vector between atoms $$i$$ and $$j$$ if they are separated by a shift of shift
diff_min_image(*args, **kwargs) Return the minimum image difference vector between two atoms or positions.
direction_cosines(i,j,shift) Given two atoms $$i$$ and $$j$$ and a shift returns the direction cosines of the differnece vector from $$i$$ to $$j$$.
direction_cosines_min_image(i,j,[error]) Direction cosines of the difference vector from $$i$$ to $$j$$
directionality(origin,list,[method,error]) Given an origin atom and a list of other atoms, give information as to whether the other atoms are distributed roughly linearly, planar or spherically around the origin atom.
distance(i,j,shift) Return distance between atoms i and j if they are separated by a shift of shift.
distance_min_image(*args, **kwargs) This interface calculates the distance between the nearest periodic images of two points (or atoms).
edit() Modify atoms interactively through ase-gui viewer.
equivalent(other) Test for equivalence of two Atoms objects.
extend(other) Extend atoms object by appending atoms from other.
fake_smooth_pos(at,mix,[persistent])
get_all_distances([mic]) Return distances of all of the atoms with all of the atoms.
get_angle(list) Get angle formed by three atoms.
get_angular_momentum() Get total angular momentum with respect to the center of mass.
get_array(name[, copy]) Get an array.
get_atom(i) Return a dictionary containing the properties of the atom with index i.
get_atomic_numbers() Get integer array of atomic numbers.
get_calculator() Get currently attached calculator object.
get_cell([complete]) Get the three unit cell vectors as a 3x3 ndarray.
get_cell_lengths_and_angles() Get unit cell parameters.
get_celldisp() Get the unit cell displacement vectors.
get_center_of_mass([scaled]) Get the center of mass.
get_charges() Get calculated charges.
get_chemical_formula([mode]) Get the chemial formula as a string based on the chemical symbols.
get_chemical_symbols() Get list of chemical symbol strings.
get_dihedral(list) Calculate dihedral angle.
get_dipole_moment() Calculate the electric dipole moment for the atoms object.
get_distance(a0, a1[, mic, vector]) Return distance between two atoms.
get_distances(a, indices[, mic, vector]) Return distances of atom No.i with a list of atoms.
get_forces([apply_constraint, md]) Calculate atomic forces.
get_initial_charges() Get array of initial charges.
get_initial_magnetic_moments() Get array of initial magnetic moments.
get_kinetic_energy() Get the kinetic energy.
get_magnetic_moment() Get calculated total magnetic moment.
get_magnetic_moments() Get calculated local magnetic moments.
get_masses() Get array of masses.
get_momenta() Get array of momenta.
get_moments_of_inertia([vectors]) Get the moments of inertia along the principal axes.
get_number_of_atoms() Returns the global number of atoms in a distributed-atoms parallel simulation.
get_param_value(*args, **kwargs) get a (per-configuration) value from the atoms%params dictionary
get_pbc() Get periodic boundary condition flags.
get_positions([wrap]) Get array of positions.
get_potential_energies() Calculate the potential energies of all the atoms.
get_potential_energy([force_consistent, ...]) Calculate potential energy.
get_reciprocal_cell() Get the three reciprocal lattice vectors as a 3x3 ndarray.
get_scaled_positions([wrap]) Get positions relative to unit cell.
get_stress([voigt]) Calculate stress tensor.
get_stresses() Calculate the stress-tensor of all the atoms.
get_tags() Get integer array of tags.
get_temperature() Get the temperature in Kelvin.
get_total_energy() Get the total energy - potential plus kinetic energy.
get_velocities() Get array of velocities.
get_volume() Get volume of unit cell.
has(name) Check for existence of array.
has_property(*args, **kwargs) Convenience function to test if a property is present.
index_to_z_index(*args, **kwargs) Convert from a single index in range 1..this.N to a CASTEP-style (element, index) pair
is_domain_decomposed(*args, **kwargs) atoms_is_domain_decomposed
is_initialised(*args, **kwargs) Is this atoms object initialised?
is_min_image(*args, **kwargs)
is_nearest_neighbour(i,n,[alt_connect]) Test if an atom’s :math:nth neighbour is one if its nearest neighbours
is_nearest_neighbour_abs_index(i,j,[alt_connect]) Test if an atom j is one of is nearest neighbours
is_same_fortran_object(other) Test if self and other point to the same Fortan object.
iteratoms() Iterate over atoms, calling get_atom() for each one
kinetic_energy([mpi_obj,local_ke,error]) Return the total kinetic energy $$E_k = \sum_{i} \frac{1}{2} m v^2$$
kinetic_virial([mpi_obj,error]) Return the total kinetic virial $$w_ij = \sum_{k} \frac{1}{2} m v_i v_j$$
list_matching_prop(at,list,name,value,[error]) Find atoms which have integer property prop with value value and return them in a table list.
make_convex(list) Add atoms to list to make the selection region convex, i.e.
map_into_cell(*args, **kwargs) atoms_map_into_cell
mark_cylinder(...) Mark atoms in a cylinder centred on the point p with axis v and radius r
mark_sphere(...) Mark atoms in a cylinder centred on the point p with radius r
md5_hash(ndigits) Hash an atoms object with a precision of ndigits decimal digits.
mem_estimate() Estimate memory usage of this Atoms object, in bytes
moment_of_inertia_tensor([origin])
momentum([indices]) Return the total momentum $$\mathbf{p} = \sum_i \mathbf{m_i} \mathbf{v_i}$$.
n_neighbours(*args, **kwargs) Neighbour list stuff Return the number of neighbour that atom i has.
neighbour(*args, **kwargs) Return the index of the $$n^\mathrm{th}$$ neighbour of atom $$i$$.
pop([i]) Remove and return atom at index i (default last).
print_(*args, **kwargs) Print a verbose textual description of an Atoms object to the default logger or to a specificied Inoutput object.
print_atom(i) Pretty-print the properties of the atom with index i
prop_names_string([with_types,error])
rattle([stdev, seed]) Randomly displace atoms.
read(source[, format]) Class method to read Atoms object from file source according to format
read_cinoutput(...)
read_from(source, **readargs) Replace contents of this Atoms object with Atoms read from source
realpos(i) Return the real position of atom i, taking into account the stored travel across the periodic boundary conditions.
remove_atoms(*args, **kwargs) Remove one or more atoms from an Atoms object.
remove_property(*args, **kwargs) Remove a property from this atoms object
repeat(rep) Create new repeated atoms object.
repoint(*args, **kwargs) OMIT
rotate(*args, **kwargs) Rotate this Atoms object, transforming all rank 1 and rank 2 tensors parameters and properties
rotate_dihedral(list, angle[, mask]) Rotate dihedral angle.
rotate_euler([center, phi, theta, psi]) Rotate atoms via Euler angles.
select([mask, list, orig_index]) Return a new Atoms containing a subset of the atoms in this Atoms object
set_angle(list, angle[, mask]) Set angle formed by three atoms.
set_array(name, a[, dtype, shape]) Update array.
set_atomic_numbers(numbers[, set_species]) Set atomic numbers and optionally also species property (default True)
set_atoms(*args, **kwargs) Set atomic numbers (in the ‘z’ integer property), species names (in ‘species’ string property) and optionally masses (if ‘mass’ property exists in the Atoms object).
set_calculator([calc]) Attach calculator object.
set_cell(cell[, scale_atoms]) Set unit cell vectors.
set_celldisp(celldisp) Set the unit cell displacement vectors.
set_chemical_symbols(symbols[, set_species]) Set chemical symbols - sets Z and optionally also species properties (default True)
set_comm_property(*args, **kwargs) Set which properties to communicate when comm_atoms: Communicate when atom is moved to different domain.
set_constraint([constraint]) Apply one or more constrains.
set_cutoff(*args, **kwargs) set a uniform cutoff
set_cutoff_minimum(*args, **kwargs) increase cutoff
set_dihedral(list, angle[, mask, indices]) Set the dihedral angle between vectors list[0]->list[1] and list[2]->list[3] by changing the atom indexed by list[3] if mask is not None, all the atoms described in mask (read: the entire subgroup) are moved.
set_distance(a0, a1, distance[, fix, mic]) Set the distance between two atoms.
set_initial_charges([charges]) Set the initial charges.
set_initial_magnetic_moments([magmoms]) Set the initial magnetic moments.
set_lattice(lattice[, scale_positions]) Change the lattice vectors, keeping the inverse lattice vectors up to date.
set_map_shift([error])
set_masses([masses]) Set atomic masses.
set_momenta(momenta[, apply_constraint]) Set momenta.
set_param_value(*args, **kwargs) set a (per-configuration) value from the atoms%params dictionary
set_pbc(pbc) Set periodic boundary condition flags.
set_positions(newpositions[, apply_constraint]) Set positions, honoring any constraints.
set_scaled_positions(scaled) Set positions relative to unit cell.
set_tags(tags) Set tags for all atoms.
set_velocities(velocities) Set the momenta by specifying the velocities.
set_zs(*args, **kwargs) set Zs from species
shallow_copy() Return a shallow copy of self.
shallow_copy_from(other) Transform self into a shallow copy of other.
shuffle(*args, **kwargs) Reshuffle the order of the atomic indices to new_indices.
sort(*args, **kwargs) sort atoms according to an externally provided field
sort_by_rindex(sort_index,[error]) sort atoms according to an externally provided field
transform_basis(*args, **kwargs) Basis transformation of rank 0, 1 and 2 tensors real values in Atoms object.
translate(displacement) Translate atomic positions.
undo_com_motion(at,[persistent]) undo center of mass motion, with or without persistent atoms object
undo_pbc_jumps(at,[persistent]) undo pbc jumps, assuming nearest periodic image, with or without persistent atoms object
unskew_cell(*args, **kwargs) Unskew lattice so the cosines of the lattice angles fall between
wrap([center, pbc, eps]) Wrap positions to unit cell.
write([dest, format, properties, prefix]) Write this Atoms object to dest.
write_cinoutput(...)
z_index_to_index(*args, **kwargs) Inverse of atoms_index_to_z_index
zero(*args, **kwargs) Zero data in an Atoms structure — this doesnt finalise it or change its size.
zero_angular_momentum(*args, **kwargs) give the system a rigid body rotation so as to zero the angular momentum about the centre of mass
add_atoms(*args, **kwargs)

Add one or more atoms to an Atoms object. To add a single atom, ‘pos’ should be an array of size 3 and ‘z a single integer. To add multiple atoms either arrays of length ‘n_new’ should be passed, or another Atoms from which to copy data should be given as the ‘from’ argument.

Wrapper around Fortran interface add_atoms containing multiple routines:

add_atoms(pos, z[, mass, travel, error])
Parameters: pos (input rank-1 array('d') with bounds (3)) – z (input int) – mass (input float, optional) – travel (input rank-1 array('i') with bounds (3), optional) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine add_atom_single defined in file src/libAtoms/Atoms_types.f95.

add_atoms(from[, error])
Parameters: from (Atoms object) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_join defined in file src/libAtoms/Atoms_types.f95.

add_atoms(pos, z[, mass, velo, acc, travel, error])
Parameters: pos (input rank-2 array('d') with bounds (qp_n0,qp_n1)) – z (input rank-1 array('i') with bounds (qp_n2)) – mass (input rank-1 array('d') with bounds (qp_n3), optional) – velo (input rank-2 array('d') with bounds (qp_n4,qp_n5), optional) – acc (input rank-2 array('d') with bounds (qp_n6,qp_n7), optional) – travel (input rank-2 array('i') with bounds (qp_n8,qp_n9), optional) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine add_atom_multiple defined in file src/libAtoms/Atoms_types.f95.

add_cut_hydrogens(qmlist[, heuristics_nneighb_only, verbosity, alt_connect])

Given an atoms structure and a list of quantum atoms, find X-H bonds which have been cut and include the other atom of the pair in the quantum list.

Parameters: qmlist : Table object heuristics_nneighb_only : input int, optional verbosity : input int, optional alt_connect : Connection object, optional

References

Routine is wrapper around Fortran routine add_cut_hydrogens defined in file src/libAtoms/clusters.f95.

add_property(name, value, n_cols=None, overwrite=None, property_type=None)[source]

Add a new property to this Atoms object.

name is the name of the new property and value should be either a scalar or an array representing the value, which should be either integer, real, logical or string.

If a scalar is given for value it is copied to every element in the new property. n_cols can be specified to create a 2D property from a scalar initial value - the default is 1 which creates a 1D property.

If an array is given for value it should either have shape (self.n,) for a 1D property or (n_cols,self.n) for a 2D property. In this case n_cols is inferred from the shape of the value and shouldn’t be passed as an argument.

If property_type is present, then no attempt is made to infer the type from value. This is necessary to resolve ambiguity between integer and logical types.

If property with the same type is already present then no error occurs.If overwrite is true, the value will be overwritten with that given in value, otherwise the old value is retained.

Here are some examples:

a = Atoms(n=10, lattice=10.0*fidentity(3))

a.add_property('force', 0.0, n_cols=3)     # Vector real

a.add_property('norm_pos', a.pos.norm())         # From 1D array
a.add_property('pos', new_pos)                   # Overwrite positions with array new_pos
# which should have shape (3,10)

add_property_from_pointer(*args, **kwargs)

Add a per-atom property to this atoms object, but point to existing space rather than allocating new space for it (as add_property does).

Wrapper around Fortran interface add_property_from_pointer containing multiple routines:

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-3 array('S') with bounds (qp_n0,qp_n1,(1))) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_str defined in file src/libAtoms/Atoms_types.f95.

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-1 array('d') with bounds (qp_n0)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_real defined in file src/libAtoms/Atoms_types.f95.

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-1 array('i') with bounds (qp_n0)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_int defined in file src/libAtoms/Atoms_types.f95.

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-2 array('d') with bounds (qp_n0,qp_n1)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_real_a defined in file src/libAtoms/Atoms_types.f95.

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-2 array('i') with bounds (qp_n0,qp_n1)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_int_a defined in file src/libAtoms/Atoms_types.f95.

add_property_from_pointer(name, ptr[, error])
Parameters: name (input string(len=-1)) – ptr (input rank-1 array('i') with bounds (qp_n0)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_add_property_p_logical defined in file src/libAtoms/Atoms_types.f95.

angular_momentum([origin, indices])

Return the angular momentum of all the atoms in this DynamicalSystem, defined by $$\mathbf{L} = \sum_{i} \mathbf{r_i} \times \mathbf{v_i}$$.

Parameters: origin : input rank-1 array(‘d’) with bounds (3), optional indices : input rank-1 array(‘i’) with bounds (qp_n0), optional ret_l : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine atoms_angular_momentum defined in file src/libAtoms/DynamicalSystem.f95.

append(atom)[source]

Append atom to end.

assignment(*args, **kwargs)

Overloaded assigment operators for Atoms objects. Overloaded assigment operators for Connection objects.

Parameters: to : Atoms object from : Atoms object

References

Routine is wrapper around Fortran routine assignment defined in file src/libAtoms/Atoms_types.f95.

bfs_grow_list(list, n[, nneighb_only, min_images_only, alt_connect])

On exit, list will have been grown by n bond hops.

Parameters: list : Table object n : input int nneighb_only : input int, optional min_images_only : input int, optional alt_connect : Connection object, optional

References

Routine is wrapper around Fortran routine bfs_grow_list defined in file src/libAtoms/clusters.f95.

bfs_grow_single(atom, n[, nneighb_only, min_images_only, alt_connect])

On exit, list will contain atom (with shift 000) plus the atoms within n bonds hops of it.

Parameters: atom : input int n : input int nneighb_only : input int, optional min_images_only : input int, optional alt_connect : Connection object, optional list : Table object

References

Routine is wrapper around Fortran routine bfs_grow_single defined in file src/libAtoms/clusters.f95.

bfs_step(input[, nneighb_only, min_images_only, max_r, alt_connect, property, debugfile, error])

Execute one Breadth-First-Search move on the atomic connectivity graph.

Parameters: input : Table object Table with intsize 4. First integer column is indices of atoms already in the region, next 3 are shifts. nneighb_only : input int, optional If present and true, sets whether only neighbours within the sum of the two respective covalent radii (multiplied by the atom’s nneightol) are included, irrespective of the cutoff in the atoms structure (default is true). min_images_only : input int, optional If true, there will be no repeated atomic indices in final list - only the minimum shift image of those found will be included. Default is false. max_r : input float, optional if present, only neighbors within this range will be included alt_connect : Connection object, optional property : input rank-1 array(‘i’) with bounds (qp_n0), optional debugfile : InOutput object, optional error : in/output rank-0 array(int,’i’), optional output : Table object Table with intsize 4, containing the new atomic indices and shifts.

References

Routine is wrapper around Fortran routine bfs_step defined in file src/libAtoms/clusters.f95.

calc_connect(*args, **kwargs)

Fast $$O(N)$$ connectivity calculation routine. It divides the unit cell into similarly shaped subcells, of sufficient size that sphere of radius cutoff is contained in a subcell, at least in the directions in which the unit cell is big enough. For very small unit cells, there is only one subcell, so the routine is equivalent to the standard $$O(N^2)$$ method.> If own_neighbour is true, atoms can be neighbours with their own periodic images. If cutoff_skin is present, effective cutoff is increased by this amount, and full recalculation of connectivity is only done when any atom has moved more than 0.5*cutoff_skin - otherwise calc_dists() is called to update the stored distance tables.

Parameters: alt_connect : Connection object, optional own_neighbour : input int, optional store_is_min_image : input int, optional skip_zero_zero_bonds : input int, optional store_n_neighb : input int, optional max_pos_change : in/output rank-0 array(float,’d’), optional did_rebuild : in/output rank-0 array(int,’i’), optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine calc_connect defined in file src/libAtoms/Atoms_types.f95.

calc_connect_hysteretic(*args, **kwargs)
As for calc_connect, but perform the connectivity update hystertically: atoms must come within a relative distance of
cutoff_factor to be considered neighbours, and then will remain

connected until them move apart further than a relative distance of cutoff_break_factor (all cutoff factors are relative to covalent radii).

Typically alt_connect should be set to the hysteretic_connect attribute. origin and extent vectors can be used to restrict the hysteretic region to only part of the entire system – the estimate_origin_extent() routine in clusters.f95 can be used to guess suitable values.

Parameters: cutoff_factor : input float cutoff_break_factor : input float alt_connect : Connection object, optional origin : input rank-1 array(‘d’) with bounds (3), optional extent : input rank-2 array(‘d’) with bounds (3,3), optional own_neighbour : input int, optional store_is_min_image : input int, optional store_n_neighb : input int, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine calc_connect_hysteretic defined in file src/libAtoms/Atoms_types.f95.

calc_dists(*args, **kwargs)

Update stored distance tables. To be called after moving atoms, in between calls to calc_connect().

Parameters: alt_connect : Connection object, optional parallel : input int, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine calc_dists defined in file src/libAtoms/Atoms_types.f95.

calc_msd(at[, mask, reset_msd, persistent])

calculate mean squared displacement, with or without persistent atoms object without persistent atoms object, global storage is used, and calling on multiple trajcetories interspersed will not work. usually desirable to call undo_pbc_jumps and undo_CoM_motion first

Parameters: at : Atoms object mask : input rank-1 array(‘i’) with bounds (qp_n0), optional reset_msd : input int, optional persistent : input int, optional

References

Routine is wrapper around Fortran routine calc_msd defined in file src/libAtoms/Atoms_types.f95.

calc_qw(l[, do_q, do_w, cutoff, cutoff_transition_width, mask, error])
Parameters: l : input int do_q : input int, optional do_w : input int, optional cutoff : input float, optional cutoff_transition_width : input float, optional mask : input rank-1 array(‘i’) with bounds (qp_n0), optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine calc_qw defined in file src/libAtoms/steinhardt_nelson_qw.f95.

calc_qw_grad(grad_ind, l[, do_q, do_w, cutoff, cutoff_transition_width])
Parameters: grad_ind : input int l : input int do_q : input int, optional do_w : input int, optional cutoff : input float, optional cutoff_transition_width : input float, optional

References

Routine is wrapper around Fortran routine calc_qw_grad defined in file src/libAtoms/steinhardt_nelson_qw.f95.

cell_volume(*args, **kwargs)

atoms_cell_volume

calculate volume of unit cell Returns the (unsigned) volume of the simulation cell of this Atoms

Returns: ret_atoms_cell_volume : float

References

Routine is wrapper around Fortran routine cell_volume defined in file src/libAtoms/Atoms_types.f95.

center(vacuum=None, axis=(0, 1, 2), about=None)[source]

Center atoms in unit cell.

Centers the atoms in the unit cell, so there is the same amount of vacuum on all sides.

vacuum: float (default: None)
If specified adjust the amount of vacuum when centering. If vacuum=10.0 there will thus be 10 Angstrom of vacuum on each side.
axis: int or sequence of ints
Axis or axes to act on. Default: Act on all axes.
about: float or array (default: None)
centre_of_mass(at[, index_list, mask, origin, error])

Calculate the centre of mass of an atoms object, using the closest images to the origin atom, or first atom if this is not specified. If origin is zero, use actual position, not minimum image. If an index_list is present, just calculate it for that subset of atoms (then the origin atom is the first in this list unless it is specified separately).

Note: Because the origin can be specified separately it need not be one of the atoms in the calculation.

Parameters: at : atoms object index_list : input rank-1 array(‘i’) with bounds (qp_n0), optional mask : input rank-1 array(‘i’) with bounds (qp_n1), optional origin : input int, optional error : in/output rank-0 array(int,’i’), optional ret_com : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine centre_of_mass defined in file src/libAtoms/Atoms_types.f95.

closest_atom(r, cell_image_na, cell_image_nb, cell_image_nc[, mask, dist, diff, error])
Parameters: r : input rank-1 array(‘d’) with bounds (3) cell_image_na : input int cell_image_nb : input int cell_image_nc : input int mask : input rank-1 array(‘i’) with bounds (qp_n0), optional dist : in/output rank-0 array(float,’d’), optional diff : in/output rank-1 array(‘d’) with bounds (3), optional error : in/output rank-0 array(int,’i’), optional ret_closest_atom : int

References

Routine is wrapper around Fortran routine closest_atom defined in file src/libAtoms/Atoms_types.f95.

coalesce_in_one_periodic_image([seed, is_periodic, error])
move atoms around following neighbor list bonds so that all are in the same periodic image
(that of seed, if present)

poorly tested, especially for situations where not all atoms are in one connected clump probably needs a better subroutine name

Parameters: seed : input int, optional is_periodic : input rank-1 array(‘i’) with bounds (3), optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine coalesce_in_one_periodic_image defined in file src/libAtoms/Atoms_types.f95.

complement(at, inlist)

Return the complement of a list, i.e. all those atoms not included in list. Result is in outlist on exit.

Parameters: at : Atoms object inlist : Table object outlist : Table object

References

Routine is wrapper around Fortran routine complement defined in file src/libAtoms/Atoms_types.f95.

copy()[source]

Return a copy of this Atoms object

copy_entry(*args, **kwargs)

Copy an atom to a different index Move a single atom from one location to another one. The destination will be overriden.

Parameters: src : input int dst : input int swap : input int, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine copy_entry defined in file src/libAtoms/Atoms_types.f95.

copy_from(other)[source]

Replace contents of this Atoms object with data from other.

copy_properties(*args, **kwargs)

Copy some properties from one atoms struct to another The destination will be overriden.

Parameters: from : Atoms object property_list : input string(len=-1) case_sensitive : input int, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine copy_properties defined in file src/libAtoms/Atoms_types.f95.

copy_without_connect(to, from[, properties, properties_array, error])

Make a copy of the atoms object from without including connectivity information. Useful for saving the state of a dynamical simulation without incurring too great a memory cost.

Parameters: to : Atoms object from : Atoms object properties : input string(len=-1), optional properties_array : input rank-2 array(‘S’) with bounds (qp_n0,(*)), optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine atoms_copy_without_connect defined in file src/libAtoms/Atoms_types.f95.

cosine(i, j, k[, error])

Cosine of the angle j–i–k

Parameters: i : input int j : input int k : input int error : in/output rank-0 array(int,’i’), optional ret_cosine : float

References

Routine is wrapper around Fortran routine cosine defined in file src/libAtoms/Atoms_types.f95.

cosine_neighbour(i, n, m)

Cosine of the angle n–i–m where {$$n,m$$} are the {:math:nth, :math:mth} neighbours of i

Parameters: i : input int n : input int m : input int ret_cosine_neighbour : float

References

Routine is wrapper around Fortran routine cosine_neighbour defined in file src/libAtoms/Atoms_types.f95.

density()[source]

Density in units of $$g/m^3$$. If mass property exists, use that, otherwise we use z and ElementMass table.

diff(i, j, shift)

Difference vector between atoms $$i$$ and $$j$$ if they are separated by a shift of shift

$\mathbf{u}_{ij} = \mathbf{r}_j - \mathbf{r}_i + \mathbf{R} \cdot \mathbf{s}$

where $$\mathbf{R}$$ is the lattice matrix and $$\mathbf{s}$$ the shift

Parameters: i : input int j : input int shift : input rank-1 array(‘i’) with bounds (3) ret_diff : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine diff defined in file src/libAtoms/Atoms_types.f95.

diff_min_image(*args, **kwargs)
Return the minimum image difference vector between two atoms or
positions. End points can be specified by any combination of atoms indices ‘i’ and ‘j’ and absolute coordinates ‘u’ and ‘w’.

Wrapper around Fortran interface diff_min_image containing multiple routines:

diff_min_image(v, j)
Parameters: v (input rank-1 array('d') with bounds (3)) – j (input int) – ret_diff_vec_atom – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine diff_vec_atom defined in file src/libAtoms/Atoms_types.f95.

diff_min_image(i, w)
Parameters: i (input int) – w (input rank-1 array('d') with bounds (3)) – ret_diff_atom_vec – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine diff_atom_vec defined in file src/libAtoms/Atoms_types.f95.

diff_min_image(i, j[, shift])
Parameters: i (input int) – j (input int) – shift (input rank-1 array('i') with bounds (3), optional) – ret_diff_atom_atom – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine diff_atom_atom defined in file src/libAtoms/Atoms_types.f95.

diff_min_image(v, w)
Parameters: v (input rank-1 array('d') with bounds (3)) – w (input rank-1 array('d') with bounds (3)) – ret_diff_vec_vec – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine diff_vec_vec defined in file src/libAtoms/Atoms_types.f95.

direction_cosines(i, j, shift)

Given two atoms $$i$$ and $$j$$ and a shift returns the direction cosines of the differnece vector from $$i$$ to $$j$$.

Parameters: i : input int j : input int shift : input rank-1 array(‘i’) with bounds (3) ret_direction_cosines : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine direction_cosines defined in file src/libAtoms/Atoms_types.f95.

direction_cosines_min_image(i, j[, error])

Direction cosines of the difference vector from $$i$$ to $$j$$

Parameters: i : input int j : input int error : in/output rank-0 array(int,’i’), optional ret_direction_cosines_min_image : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine direction_cosines_min_image defined in file src/libAtoms/Atoms_types.f95.

directionality(origin, list[, method, error])

Given an origin atom and a list of other atoms, give information as to whether the other atoms are distributed roughly linearly, planar or spherically around the origin atom.

The most notable use is to check that the splines in adjustable potential will be able to reproduce a randomly oriented force difference well.

The information returned is the set of eigenvectors and associated eigenvalues of the directionality ellipsoid. One large e-value suggests roughly linear clustering, two similar and one small e-values suggest a planar distribution, while three similar e-values suggests almost spherical distribution (when copies of the atoms reflected through the origin atom are also considered).

To acheive a more spherical distribution, atoms along the e-vector(s) with the smallest e-value(s) should be added to the index list (See CosAngle_To_Line below).

The matrix which is diagonalised is an average of the outer products of the unit vectors from the origin atom to the other atoms.

An outer product has 1 eigenvector which is the vector it was constructed from with eigenvalue 1 and the other eigenvectors have eigenvalue 0.

The eigenvalues of the averaged matrix sum to 1.

Parameters: origin : input int The origin atom list : Table object Indices and shifts of the other atoms relative to origin evalues : rank-1 array(‘d’) with bounds (3) Eigenvalues of the directionality matrix evectors : rank-2 array(‘d’) with bounds (3,3) Eigenvectors of the directionality matrix method : input int, optional METHOD = 1 Directionality ellipsoid method. METHOD = 2 Singular Value Decomposition method (default) error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine directionality defined in file src/libAtoms/Atoms_types.f95.

distance(i, j, shift)

Return distance between atoms i and j if they are separated by a shift of shift.

$r_{ij} = \left| \mathbf{r}_j - \mathbf{r}_i + \mathbf{R} \cdot \mathbf{s} \right|$

where $$\mathbf{R}$$ is the lattice matrix and $$\mathbf{s}$$ the shift.

Parameters: i : input int j : input int shift : input rank-1 array(‘i’) with bounds (3) ret_distance : float

References

Routine is wrapper around Fortran routine distance defined in file src/libAtoms/Atoms_types.f95.

distance_min_image(*args, **kwargs)
This interface calculates the distance between the nearest periodic images of two points (or atoms).
Return minimum image distance between two atoms or positions. End points can be specified by any combination of atoms indices ‘i’ and ‘j’ and absolute coordinates ‘u’ and ‘w’. If ‘shift’ is present the periodic shift between the two atoms or points will be returned in it.

Wrapper around Fortran interface distance_min_image containing multiple routines:

distance_min_image(v, w[, shift])
Parameters: v (input rank-1 array('d') with bounds (3)) – w (input rank-1 array('d') with bounds (3)) – shift (in/output rank-1 array('i') with bounds (3), optional) – ret_distance8_vec_vec – float

Routine is wrapper around Fortran routine distance8_vec_vec defined in file src/libAtoms/Atoms_types.f95.

distance_min_image(i, j[, shift])
Parameters: i (input int) – j (input int) – shift (in/output rank-1 array('i') with bounds (3), optional) – ret_distance8_atom_atom – float

Routine is wrapper around Fortran routine distance8_atom_atom defined in file src/libAtoms/Atoms_types.f95.

distance_min_image(i, v[, shift])
Parameters: i (input int) – v (input rank-1 array('d') with bounds (3)) – shift (in/output rank-1 array('i') with bounds (3), optional) – ret_distance8_atom_vec – float

Routine is wrapper around Fortran routine distance8_atom_vec defined in file src/libAtoms/Atoms_types.f95.

distance_min_image(v, j[, shift])
Parameters: v (input rank-1 array('d') with bounds (3)) – j (input int) – shift (in/output rank-1 array('i') with bounds (3), optional) – ret_distance8_vec_atom – float

Routine is wrapper around Fortran routine distance8_vec_atom defined in file src/libAtoms/Atoms_types.f95.

edit()[source]

Modify atoms interactively through ase-gui viewer.

Conflicts leading to undesirable behaviour might arise when matplotlib has been pre-imported with certain incompatible backends and while trying to use the plot feature inside the interactive ase-gui. To circumvent, please set matplotlib.use(‘gtk’) before calling this method.

equivalent(other)[source]

Test for equivalence of two Atoms objects.

Equivalence is less strong than equality. Equality (written self == other) requires all properties and parameters to be equal. Equivalence requires only that the number of atoms, positions, atomic numbers, unit cell and periodic boundary conditions match.

Note

The quippy expression a.equivalent(b) has the same definition as a == b in ASE. This means that a quippy.Atoms instance can be compared with an ase.Atoms instance using this method.

extend(other)[source]

Extend atoms object by appending atoms from other.

fake_smooth_pos(at, mix[, persistent])
Parameters: at : Atoms object mix : input float persistent : input int, optional

References

Routine is wrapper around Fortran routine fake_smooth_pos defined in file src/libAtoms/Atoms_types.f95.

get_all_distances(mic=False)[source]

Return distances of all of the atoms with all of the atoms.

Use mic=True to use the Minimum Image Convention.

get_angle(list)[source]

Get angle formed by three atoms.

calculate angle between the vectors list[1]->list[0] and list[1]->list[2], where list contains the atomic indexes in question.

get_angular_momentum()[source]

Get total angular momentum with respect to the center of mass.

get_array(name, copy=True)[source]

Get an array.

Returns a copy unless the optional argument copy is false.

get_atom(i)[source]

Return a dictionary containing the properties of the atom with index i. If fortran_indexing=True (the default), i should be in range 1..self.n, otherwise it should be in range 0..(self.n-1).

get_atomic_numbers()[source]

Get integer array of atomic numbers.

get_calculator()[source]

Get currently attached calculator object.

get_cell(complete=False)[source]

Get the three unit cell vectors as a 3x3 ndarray.

get_cell_lengths_and_angles()[source]

Get unit cell parameters. Sequence of 6 numbers.

First three are unit cell vector lengths and second three are angles between them:

[len(a), len(b), len(c), angle(a,b), angle(a,c), angle(b,c)]


in degrees.

get_celldisp()[source]

Get the unit cell displacement vectors.

get_center_of_mass(scaled=False)[source]

Get the center of mass.

If scaled=True the center of mass in scaled coordinates is returned.

get_charges()[source]

Get calculated charges.

get_chemical_formula(mode='hill')[source]

Get the chemial formula as a string based on the chemical symbols.

Parameters:

mode: str

There are three different modes available:

‘all’: The list of chemical symbols are contracted to at string, e.g. [‘C’, ‘H’, ‘H’, ‘H’, ‘O’, ‘H’] becomes ‘CHHHOH’.

‘reduce’: The same as ‘all’ where repeated elements are contracted to a single symbol and a number, e.g. ‘CHHHOCHHH’ is reduced to ‘CH3OCH3’.

‘hill’: The list of chemical symbols are contracted to a string following the Hill notation (alphabetical order with C and H first), e.g. ‘CHHHOCHHH’ is reduced to ‘C2H6O’ and ‘SOOHOHO’ to ‘H2O4S’. This is default.

get_chemical_symbols()[source]

Get list of chemical symbol strings.

get_dihedral(list)[source]

Calculate dihedral angle.

Calculate dihedral angle between the vectors list[0]->list[1] and list[2]->list[3], where list contains the atomic indexes in question.

get_dipole_moment()[source]

Calculate the electric dipole moment for the atoms object.

Only available for calculators which has a get_dipole_moment() method.

get_distance(a0, a1, mic=False, vector=False)[source]

Return distance between two atoms.

Use mic=True to use the Minimum Image Convention. vector=True gives the distance vector (from a0 to a1).

get_distances(a, indices, mic=False, vector=False)[source]

Return distances of atom No.i with a list of atoms.

Use mic=True to use the Minimum Image Convention. vector=True gives the distance vector (from a to self[indices]).

get_forces(apply_constraint=True, md=False)[source]

Calculate atomic forces.

Ask the attached calculator to calculate the forces and apply constraints. Use apply_constraint=False to get the raw forces.

For molecular dynamics (md=True) we don’t apply the constraint to the forces but to the momenta.

get_initial_charges()[source]

Get array of initial charges.

get_initial_magnetic_moments()[source]

Get array of initial magnetic moments.

get_kinetic_energy()[source]

Get the kinetic energy.

get_magnetic_moment()[source]

Get calculated total magnetic moment.

get_magnetic_moments()[source]

Get calculated local magnetic moments.

get_masses()[source]

Get array of masses.

get_momenta()[source]

Get array of momenta.

get_moments_of_inertia(vectors=False)[source]

Get the moments of inertia along the principal axes.

The three principal moments of inertia are computed from the eigenvalues of the symmetric inertial tensor. Periodic boundary conditions are ignored. Units of the moments of inertia are amu*angstrom**2.

get_number_of_atoms()[source]

Returns the global number of atoms in a distributed-atoms parallel simulation.

DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING!

Equivalent to len(atoms) in the standard ASE Atoms class. You should normally use len(atoms) instead. This function’s only purpose is to make compatibility between ASE and Asap easier to maintain by having a few places in ASE use this function instead. It is typically only when counting the global number of degrees of freedom or in similar situations.

get_param_value(*args, **kwargs)

get a (per-configuration) value from the atoms%params dictionary

Wrapper around Fortran interface get_param_value containing multiple routines:

get_param_value(key[, error])
Parameters: key (input string(len=-1)) – error (in/output rank-0 array(int,'i'), optional) – value – float

Routine is wrapper around Fortran routine atoms_get_param_value_real defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key[, error])
Parameters: key (input string(len=-1)) – error (in/output rank-0 array(int,'i'), optional) – value – string(len=10240)

Routine is wrapper around Fortran routine atoms_get_param_value_str defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key, n0[, error])
Parameters: key (input string(len=-1)) – n0 (input int) – shape(qp_value,0) error (in/output rank-0 array(int,'i'), optional) – value – rank-1 array(‘d’) with bounds (qp_n0)

Routine is wrapper around Fortran routine atoms_get_param_value_real_a defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key[, error])
Parameters: key (input string(len=-1)) – error (in/output rank-0 array(int,'i'), optional) – value – int

Routine is wrapper around Fortran routine atoms_get_param_value_int defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key[, error])
Parameters: key (input string(len=-1)) – error (in/output rank-0 array(int,'i'), optional) – value – int

Routine is wrapper around Fortran routine atoms_get_param_value_logical defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key, n0, n1[, error])
Parameters: key (input string(len=-1)) – n0 (input int) – shape(qp_value,0) n1 (input int) – shape(qp_value,1) error (in/output rank-0 array(int,'i'), optional) – value – rank-2 array(‘d’) with bounds (qp_n0,qp_n1)

Routine is wrapper around Fortran routine atoms_get_param_value_real_a2 defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key, value[, error])
Parameters: key (input string(len=-1)) – value (Extendable_str object) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_get_param_value_es defined in file src/libAtoms/Atoms_types.f95.

get_param_value(key, n0[, error])
Parameters: key (input string(len=-1)) – n0 (input int) – shape(qp_value,0) error (in/output rank-0 array(int,'i'), optional) – value – rank-1 array(‘i’) with bounds (qp_n0)

Routine is wrapper around Fortran routine atoms_get_param_value_int_a defined in file src/libAtoms/Atoms_types.f95.

get_pbc()[source]

Get periodic boundary condition flags.

get_positions(wrap=False)[source]

Get array of positions. If wrap==True, wraps atoms back into unit cell.

get_potential_energies()[source]

Calculate the potential energies of all the atoms.

Only available with calculators supporting per-atom energies (e.g. classical potentials).

get_potential_energy(force_consistent=False, apply_constraint=True)[source]

Calculate potential energy.

Ask the attached calculator to calculate the potential energy and apply constraints. Use apply_constraint=False to get the raw forces.

When supported by the calculator, either the energy extrapolated to zero Kelvin or the energy consistent with the forces (the free energy) can be returned.

get_reciprocal_cell()[source]

Get the three reciprocal lattice vectors as a 3x3 ndarray.

Note that the commonly used factor of 2 pi for Fourier transforms is not included here.

get_scaled_positions(wrap=True)[source]

Get positions relative to unit cell.

If wrap is True, atoms outside the unit cell will be wrapped into the cell in those directions with periodic boundary conditions so that the scaled coordinates are between zero and one.

get_stress(voigt=True)[source]

Calculate stress tensor.

Returns an array of the six independent components of the symmetric stress tensor, in the traditional Voigt order (xx, yy, zz, yz, xz, xy) or as a 3x3 matrix. Default is Voigt order.

get_stresses()[source]

Calculate the stress-tensor of all the atoms.

Only available with calculators supporting per-atom energies and stresses (e.g. classical potentials). Even for such calculators there is a certain arbitrariness in defining per-atom stresses.

get_tags()[source]

Get integer array of tags.

get_temperature()[source]

Get the temperature in Kelvin.

get_total_energy()[source]

Get the total energy - potential plus kinetic energy.

get_velocities()[source]

Get array of velocities.

get_volume()[source]

Get volume of unit cell.

has(name)[source]

Check for existence of array.

name must be one of: ‘tags’, ‘momenta’, ‘masses’, ‘magmoms’, ‘charges’.

has_property(*args, **kwargs)

Convenience function to test if a property is present. No checking of property type is done. Property names are case-insensitive.

Parameters: name : input string(len=-1) ret_atoms_has_property : int

References

Routine is wrapper around Fortran routine has_property defined in file src/libAtoms/Atoms_types.f95.

index_to_z_index(*args, **kwargs)

Convert from a single index in range 1..this.N to a CASTEP-style (element, index) pair

Parameters: index : input int ret_z_index : int

References

Routine is wrapper around Fortran routine index_to_z_index defined in file src/libAtoms/Atoms_types.f95.

is_domain_decomposed(*args, **kwargs)

atoms_is_domain_decomposed

Is this atoms object domain decomposed?

Returns: ret_ : int

References

Routine is wrapper around Fortran routine is_domain_decomposed defined in file src/libAtoms/Atoms_types.f95.

is_initialised(*args, **kwargs)

Is this atoms object initialised?

Parameters: ret_ : int

References

Routine is wrapper around Fortran routine is_initialised defined in file src/libAtoms/Atoms_types.f95.

is_min_image(*args, **kwargs)
Parameters: i : input int alt_connect : Connection object, optional error : in/output rank-0 array(int,’i’), optional ret_is_min_image : int

References

Routine is wrapper around Fortran routine is_min_image defined in file src/libAtoms/Atoms_types.f95.

is_nearest_neighbour(i, n[, alt_connect])

Test if an atom’s :math:nth neighbour is one if its nearest neighbours

Parameters: i : input int n : input int alt_connect : Connection object, optional ret_is_nearest_neighbour : int

References

Routine is wrapper around Fortran routine is_nearest_neighbour defined in file src/libAtoms/Atoms_types.f95.

is_nearest_neighbour_abs_index(i, j[, alt_connect])

Test if an atom j is one of is nearest neighbours

Parameters: i : input int j : input int alt_connect : Connection object, optional ret_is_nearest_neighbour_abs_index : int

References

Routine is wrapper around Fortran routine is_nearest_neighbour_abs_index defined in file src/libAtoms/Atoms_types.f95.

iteratoms()[source]

Iterate over atoms, calling get_atom() for each one

kinetic_energy([mpi_obj, local_ke, error])

Return the total kinetic energy $$E_k = \sum_{i} \frac{1}{2} m v^2$$

Parameters: mpi_obj : MPI_context object, optional local_ke : input int, optional error : in/output rank-0 array(int,’i’), optional ret_ke : float

References

Routine is wrapper around Fortran routine atoms_kinetic_energy defined in file src/libAtoms/DynamicalSystem.f95.

kinetic_virial([mpi_obj, error])

Return the total kinetic virial $$w_ij = \sum_{k} \frac{1}{2} m v_i v_j$$

Parameters: mpi_obj : MPI_context object, optional error : in/output rank-0 array(int,’i’), optional ret_kv : rank-2 array(‘d’) with bounds (3,3)

References

Routine is wrapper around Fortran routine atoms_kinetic_virial defined in file src/libAtoms/DynamicalSystem.f95.

list_matching_prop(at, list, name, value[, error])

Find atoms which have integer property prop with value value and return them in a table list.

Parameters: at : atoms object list : Table object name : input string(len=-1) value : input int error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine list_matching_prop defined in file src/libAtoms/Atoms_types.f95.

make_convex(list)

Add atoms to list to make the selection region convex, i.e. if $$i$$ and $$j$$ are nearest neighbours, with $$i$$ in the list and not $$j$$ then $$j$$ will be added if more than half its nearest neighbours are in the list.

Parameters: list : Table object

References

Routine is wrapper around Fortran routine make_convex defined in file src/libAtoms/clusters.f95.

map_into_cell(*args, **kwargs)

atoms_map_into_cell

Map atomic positions into the unit cell so that lattice
coordinates satisfy $$-0.5 \le t_x,t_y,t_z < 0.5$$

Map atomic fractional positions back into the unit cell $$-0.5 \le t_x,t_y,t_z < 0.5$$

References

Routine is wrapper around Fortran routine map_into_cell defined in file src/libAtoms/Atoms_types.f95.

mark_cylinder(p, v, r[, periodic, mark_name, mark_value, intersection])

Mark atoms in a cylinder centred on the point p with axis v and radius r

Parameters: p : input rank-1 array(‘d’) with bounds (3) v : input rank-1 array(‘d’) with bounds (3) r : input float periodic : input int, optional mark_name : input string(len=-1), optional mark_value : input int, optional intersection : input int, optional

References

Routine is wrapper around Fortran routine mark_cylinder defined in file src/libAtoms/frametools.f95.

mark_sphere(p, r[, periodic, mark_name, mark_value, intersection])

Mark atoms in a cylinder centred on the point p with radius r

Parameters: p : input rank-1 array(‘d’) with bounds (3) r : input float periodic : input int, optional mark_name : input string(len=-1), optional mark_value : input int, optional intersection : input int, optional

References

Routine is wrapper around Fortran routine mark_sphere defined in file src/libAtoms/frametools.f95.

md5_hash(ndigits)[source]

Hash an atoms object with a precision of ndigits decimal digits. Atomic numbers, lattice and fractional positions are fed to MD5 to form the hash.

mem_estimate()[source]

Estimate memory usage of this Atoms object, in bytes

moment_of_inertia_tensor([origin])
Parameters: origin : input rank-1 array(‘d’) with bounds (3), optional ret_moi : rank-2 array(‘d’) with bounds (3,3)

References

Routine is wrapper around Fortran routine moment_of_inertia_tensor defined in file src/libAtoms/DynamicalSystem.f95.

momentum([indices])

Return the total momentum $$\mathbf{p} = \sum_i \mathbf{m_i} \mathbf{v_i}$$. Optionally only include the contribution of a subset of atoms.

Parameters: indices : input rank-1 array(‘i’) with bounds (qp_n0), optional ret_p : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine atoms_momentum defined in file src/libAtoms/DynamicalSystem.f95.

n_neighbours(*args, **kwargs)

Neighbour list stuff Return the number of neighbour that atom i has. If the optional arguments max_dist or max_factor are present then only neighbours closer than this cutoff are included. Do not use max_dist when iterating only over neighbours within a certain distance; instead, iterate over the full list and discard unnecessary neighbours in atoms_neighbour.

alt_connect can be set to another Connection object to use alternative connectivity information, for example hysteretic_connect.

Parameters: i : input int max_dist : input float, optional max_factor : input float, optional alt_connect : Connection object, optional error : in/output rank-0 array(int,’i’), optional ret_n : int

References

Routine is wrapper around Fortran routine n_neighbours defined in file src/libAtoms/Atoms_types.f95.

neighbour(*args, **kwargs)

Return the index of the $$n^\mathrm{th}$$ neighbour of atom $$i$$. Together with the previous function, this facilites a loop over the neighbours of atom $$i$$. Optionally, we return other geometric information, such as distance, direction cosines and difference vector, and also a direct index into the neighbour tables. If $$i <= j$$, this is an index into neighbour1(i); if $$i > j$$, it is an index into neighbour1(j).

do n = 1,atoms_n_neighbours(at, i)
j = atoms_neighbour(at, i, n, distance, diff, cosines, shift, index)

...
end do


If distance $$>$$ max_dist, return 0, and do not waste time calculating other quantities. This enables efficient iteration over the subset of neighbours located within the radius max_dist. However, as the neighbour list is not sorted, you must first iterate over the whole list (i.e. do not use the max_dist parameter in atoms_n_neighbours), then skip those neighbours where this function returns 0.

alt_connect has the same meaning as in n_neighbours.

Here’s a typical loop construct in Python. Note how r and u are created before the loop: arguments which are both optional and intent(out) in Fortran are converted to intent(in,out) for quippy. ::

r = farray(0.0)
u = fzeros(3)
for i in frange(at.n):
for n in frange(at.n_neighbours(i)):
j = at.neighbour(i, n, distance=r, diff=u)

Parameters: i : input int n : input int distance : in/output rank-0 array(float,’d’), optional diff : in/output rank-1 array(‘d’) with bounds (3), optional cosines : in/output rank-1 array(‘d’) with bounds (3), optional shift : in/output rank-1 array(‘i’) with bounds (3), optional index : in/output rank-0 array(int,’i’), optional max_dist : input float, optional jn : in/output rank-0 array(int,’i’), optional alt_connect : Connection object, optional error : in/output rank-0 array(int,’i’), optional ret_j : int

References

Routine is wrapper around Fortran routine neighbour defined in file src/libAtoms/Atoms_types.f95.

pop(i=-1)[source]

Remove and return atom at index i (default last).

print_(*args, **kwargs)

Print a verbose textual description of an Atoms object to the default logger or to a specificied Inoutput object. Print a verbose textual description of a Connection object to the default logger or to a specificied Inoutput object.

Parameters: file : InOutput object, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine print_ defined in file src/libAtoms/Atoms_types.f95.

print_atom(i)[source]

Pretty-print the properties of the atom with index i

prop_names_string([with_types, error])
Parameters: with_types : input int, optional error : in/output rank-0 array(int,’i’), optional ret_prop_names_string : string(len=10240)

References

Routine is wrapper around Fortran routine prop_names_string defined in file src/libAtoms/Atoms_types.f95.

rattle(stdev=0.001, seed=42)[source]

Randomly displace atoms.

This method adds random displacements to the atomic positions, taking a possible constraint into account. The random numbers are drawn from a normal distribution of standard deviation stdev.

For a parallel calculation, it is important to use the same seed on all processors!

classmethod read(source, format=None, **kwargs)[source]

Class method to read Atoms object from file source according to format

If format is None, filetype is inferred from filename. Returns a new Atoms instance; to read into an existing Atoms object, use the read_from() method.

If source corresponds to a known format then it used to construct an appropriate iterator from the AtomsReaders dictionary. See Supported File Formats for a list of supported file formats.

If source corresponds to an unknown format then it is expected to be an iterator returning Atoms objects.

read_cinoutput(cio[, properties, properties_array, frame, zero, range, str, estr, error])
Parameters: cio : CInOutput object properties : input string(len=-1), optional properties_array : input rank-2 array(‘S’) with bounds (qp_n0,(*)), optional frame : input int, optional zero : input int, optional range : input rank-1 array(‘i’) with bounds (2), optional str : input string(len=-1), optional estr : Extendable_str object, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine atoms_read_cinoutput defined in file src/libAtoms/CInOutput.f95.

read_from(source, **readargs)[source]

Replace contents of this Atoms object with Atoms read from source

realpos(i)

Return the real position of atom i, taking into account the stored travel across the periodic boundary conditions.

Parameters: i : input int ret_realpos : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine realpos defined in file src/libAtoms/Atoms_types.f95.

remove_atoms(*args, **kwargs)

Remove one or more atoms from an Atoms object.

Wrapper around Fortran interface remove_atoms containing multiple routines:

remove_atoms(mask[, error])
Parameters: mask (input rank-1 array('i') with bounds (qp_n0)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine remove_atom_multiple_mask defined in file src/libAtoms/Atoms_types.f95.

remove_atoms(i[, error])
Parameters: i (input int) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine remove_atom_single defined in file src/libAtoms/Atoms_types.f95.

remove_atoms(atom_indices[, error])
Parameters: atom_indices (input rank-1 array('i') with bounds (qp_n0)) – error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine remove_atom_multiple defined in file src/libAtoms/Atoms_types.f95.

remove_property(*args, **kwargs)

Remove a property from this atoms object

Parameters: name : input string(len=-1) error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine remove_property defined in file src/libAtoms/Atoms_types.f95.

repeat(rep)[source]

Create new repeated atoms object.

The rep argument should be a sequence of three positive integers like (2,3,1) or a single integer (r) equivalent to (r,r,r).

repoint(*args, **kwargs)

OMIT

References

Routine is wrapper around Fortran routine atoms_repoint defined in file src/libAtoms/Atoms_types.f95.

rotate(*args, **kwargs)

Rotate this Atoms object, transforming all rank 1 and rank 2 tensors parameters and properties

Parameters: axis : input rank-1 array(‘d’) with bounds (3) angle : input float rank1 : input string(len=-1), optional rank2 : input string(len=-1), optional

References

Routine is wrapper around Fortran routine rotate defined in file src/libAtoms/Atoms_types.f95.

rotate_dihedral(list, angle, mask=None)[source]

Rotate dihedral angle.

Complementing the two routines above: rotate a group by a predefined dihedral angle, starting from its current configuration

rotate_euler(center=(0, 0, 0), phi=0.0, theta=0.0, psi=0.0)[source]

Rotate atoms via Euler angles.

See e.g http://mathworld.wolfram.com/EulerAngles.html for explanation.

Parameters:

center :
The point to rotate about. A sequence of length 3 with the coordinates, or ‘COM’ to select the center of mass, ‘COP’ to select center of positions or ‘COU’ to select center of cell.
phi :
The 1st rotation angle around the z axis.
theta :
Rotation around the x axis.
psi :
2nd rotation around the z axis.
select(mask=None, list=None, orig_index=True)[source]

Return a new Atoms containing a subset of the atoms in this Atoms object

One of either mask or list should be present. If mask is given it should be a rank one array of length self.n. In this case atoms corresponding to true values in mask will be included in the result. If list is present it should be an arry of list containing atom indices to include in the result.

If orig_index is True (default), the new object will contain an orig_index property mapping the indices of the new atoms back to the original larger Atoms object.

set_angle(list, angle, mask=None)[source]

Set angle formed by three atoms.

Sets the angle between vectors list[1]->list[0] and list[1]->list[2].

Same usage as in set_dihedral.

set_array(name, a, dtype=None, shape=None)[source]

Update array.

If shape is not None, the shape of a will be checked. If a is None, then the array is deleted.

set_atomic_numbers(numbers, set_species=True)[source]

Set atomic numbers and optionally also species property (default True)

set_atoms(*args, **kwargs)
Set atomic numbers (in the ‘z’ integer property), species names
(in ‘species’ string property) and optionally masses (if ‘mass’ property exists in the Atoms object).

Wrapper around Fortran interface set_atoms containing multiple routines:

set_atoms(z)
Parameters: z (input int) –

Routine is wrapper around Fortran routine atoms_set_atoms_singlez defined in file src/libAtoms/Atoms_types.f95.

set_atoms(z[, mass])

Set atomic numbers and optionally masses (if mass property is present) If mass is not specified then ElementMass(Z) is used.

Parameters: z (input rank-1 array('i') with bounds (qp_n0)) – mass (input rank-1 array('d') with bounds (qp_n1), optional) –

Routine is wrapper around Fortran routine atoms_set_atoms defined in file src/libAtoms/Atoms_types.f95.

set_calculator(calc=None)[source]

Attach calculator object.

set_cell(cell, scale_atoms=False)[source]

Set unit cell vectors.

Parameters:

cell: 3x3 matrix or length 3 or 6 vector
Unit cell. A 3x3 matrix (the three unit cell vectors) or just three numbers for an orthorhombic cell. Another option is 6 numbers, which describes unit cell with lengths of unit cell vectors and with angles between them (in degrees), in following order: [len(a), len(b), len(c), angle(b,c), angle(a,c), angle(a,b)]. First vector will lie in x-direction, second in xy-plane, and the third one in z-positive subspace.
scale_atoms: bool
Fix atomic positions or move atoms with the unit cell? Default behavior is to not move the atoms (scale_atoms=False).

Examples:

Two equivalent ways to define an orthorhombic cell:

>>> atoms = Atoms('He')
>>> a, b, c = 7, 7.5, 8
>>> atoms.set_cell([a, b, c])
>>> atoms.set_cell([(a, 0, 0), (0, b, 0), (0, 0, c)])


FCC unit cell:

>>> atoms.set_cell([(0, b, b), (b, 0, b), (b, b, 0)])


Hexagonal unit cell:

>>> atoms.set_cell([a, a, c, 90, 90, 120])


Rhombohedral unit cell:

>>> alpha = 77
>>> atoms.set_cell([a, a, a, alpha, alpha, alpha])

set_celldisp(celldisp)[source]

Set the unit cell displacement vectors.

set_chemical_symbols(symbols, set_species=True)[source]

Set chemical symbols - sets Z and optionally also species properties (default True)

set_comm_property(*args, **kwargs)

Set which properties to communicate when comm_atoms: Communicate when atom is moved to different domain.

Forces, for example, may be excluded since they are updated on every time step.
comm_ghosts: Communicate when atom is dublicated as a ghost on a domain.
Masses, for example, might be excluded since atoms are propagated on the domain they reside in only.
comm_reverse: Communicate back from ghost atoms to the original domain atom
and accumulate

By default, properties are not communicated.

Parameters: propname : input string(len=-1) comm_atoms : input int, optional comm_ghosts : input int, optional comm_reverse : input int, optional

References

Routine is wrapper around Fortran routine set_comm_property defined in file src/libAtoms/Atoms_types.f95.

set_constraint(constraint=None)[source]

Apply one or more constrains.

The constraint argument must be one constraint object or a list of constraint objects.

set_cutoff(*args, **kwargs)

set a uniform cutoff Specify a uniform neighbour cutoff throughout the system. Optionally set cutoff_skin at the same time.

Parameters: cutoff : input float cutoff_skin : input float, optional

References

Routine is wrapper around Fortran routine set_cutoff defined in file src/libAtoms/Atoms_types.f95.

set_cutoff_minimum(*args, **kwargs)

increase cutoff Set the cutoff to at least the requested value Optionally set cutoff_skin at the same time.

Parameters: cutoff : input float cutoff_skin : input float, optional

References

Routine is wrapper around Fortran routine set_cutoff_minimum defined in file src/libAtoms/Atoms_types.f95.

set_dihedral(list, angle, mask=None, indices=None)[source]

Set the dihedral angle between vectors list[0]->list[1] and list[2]->list[3] by changing the atom indexed by list[3] if mask is not None, all the atoms described in mask (read: the entire subgroup) are moved. Alternatively to the mask, the indices of the atoms to be rotated can be supplied.

example: the following defines a very crude ethane-like molecule and twists one half of it by 30 degrees.

>>> from math import pi
>>> atoms = Atoms('HHCCHH', [[-1, 1, 0], [-1, -1, 0], [0, 0, 0],
...                          [1, 0, 0], [2, 1, 0], [2, -1, 0]])
>>> atoms.set_dihedral([1, 2, 3, 4], 7 * pi / 6,
...                    mask=[0, 0, 0, 1, 1, 1])

set_distance(a0, a1, distance, fix=0.5, mic=False)[source]

Set the distance between two atoms.

Set the distance between atoms a0 and a1 to distance. By default, the center of the two atoms will be fixed. Use fix=0 to fix the first atom, fix=1 to fix the second atom and fix=0.5 (default) to fix the center of the bond.

set_initial_charges(charges=None)[source]

Set the initial charges.

set_initial_magnetic_moments(magmoms=None)[source]

Set the initial magnetic moments.

Use either one or three numbers for every atom (collinear or non-collinear spins).

set_lattice(lattice, scale_positions=False)[source]

Change the lattice vectors, keeping the inverse lattice vectors up to date. Optionally map the existing atoms into the new cell and recalculate connectivity (by default scale_positions=False).

set_map_shift([error])
Parameters: error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine set_map_shift defined in file src/libAtoms/Atoms_types.f95.

set_masses(masses='defaults')[source]

Set atomic masses.

The array masses should contain a list of masses. In case the masses argument is not given or for those elements of the masses list that are None, standard values are set.

set_momenta(momenta, apply_constraint=True)[source]

Set momenta.

set_param_value(*args, **kwargs)

set a (per-configuration) value from the atoms%params dictionary

Wrapper around Fortran interface set_param_value containing multiple routines:

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input rank-1 array('i') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine atoms_set_param_value_int_a defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input rank-2 array('d') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine atoms_set_param_value_real_a2 defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input int) –

Routine is wrapper around Fortran routine atoms_set_param_value_int defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input string(len=-1)) –

Routine is wrapper around Fortran routine atoms_set_param_value_str defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input rank-1 array('d') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine atoms_set_param_value_real_a defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input float) –

Routine is wrapper around Fortran routine atoms_set_param_value_real defined in file src/libAtoms/Atoms_types.f95.

set_param_value(key, value)
Parameters: key (input string(len=-1)) – value (input int) –

Routine is wrapper around Fortran routine atoms_set_param_value_logical defined in file src/libAtoms/Atoms_types.f95.

set_pbc(pbc)[source]

Set periodic boundary condition flags.

set_positions(newpositions, apply_constraint=True)[source]

Set positions, honoring any constraints. To ignore constraints, use apply_constraint=False.

set_scaled_positions(scaled)[source]

Set positions relative to unit cell.

set_tags(tags)[source]

Set tags for all atoms. If only one tag is supplied, it is applied to all atoms.

set_velocities(velocities)[source]

Set the momenta by specifying the velocities.

set_zs(*args, **kwargs)

set Zs from species

Parameters: error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine set_zs defined in file src/libAtoms/Atoms_types.f95.

shuffle(*args, **kwargs)

Reshuffle the order of the atomic indices to new_indices.

Parameters: new_indices : input rank-1 array(‘i’) with bounds (qp_n0) error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine shuffle defined in file src/libAtoms/Atoms_types.f95.

sort(*args, **kwargs)

sort atoms according to an externally provided field

Parameters: sort_index : input rank-1 array(‘d’) with bounds (qp_n0) error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine sort_by_rindex defined in file src/libAtoms/Atoms_types.f95.

sort_by_rindex(sort_index[, error])

sort atoms according to an externally provided field

Parameters: sort_index : input rank-1 array(‘d’) with bounds (qp_n0) error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine atoms_sort_by_rindex defined in file src/libAtoms/Atoms_types.f95.

transform_basis(*args, **kwargs)

Basis transformation of rank 0, 1 and 2 tensors real values in Atoms object. This routine transforms rank 1 and rank 2 tensors in this.params and this.properties. Tensors are identified by having the correct type (real arrays) and shape (i.e. 3, (3, 3), (3, this.N) (9, this.N) for vector paramters, tensor parameters, vector properties and tensor properties respectively), and by having a name which is included in the relevant list. Extra names can be added to the lists with the rank1 and rank2 arguments.

Parameters: l : input rank-2 array(‘d’) with bounds (3,3) rank1 : input string(len=-1), optional rank2 : input string(len=-1), optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine transform_basis defined in file src/libAtoms/Atoms_types.f95.

translate(displacement)[source]

Translate atomic positions.

The displacement argument can be a float an xyz vector or an nx3 array (where n is the number of atoms).

undo_com_motion(at[, persistent])

undo center of mass motion, with or without persistent atoms object without persistent atoms object, global storage is used, and calling on multiple trajcetories interspersed will not work

Parameters: at : Atoms object persistent : input int, optional

References

Routine is wrapper around Fortran routine undo_com_motion defined in file src/libAtoms/Atoms_types.f95.

undo_pbc_jumps(at[, persistent])

undo pbc jumps, assuming nearest periodic image, with or without persistent atoms object without persistent atoms object, global storage is used, and calling on multiple trajcetories interspersed will not work

Parameters: at : Atoms object persistent : input int, optional

References

Routine is wrapper around Fortran routine undo_pbc_jumps defined in file src/libAtoms/Atoms_types.f95.

unskew_cell(*args, **kwargs)
Unskew lattice so the cosines of the lattice angles fall between
$$-0.5$$ and $$0.5$$

Unskew lattice so the cosines of the lattice angles fall between $$-0.5$$ and $$0.5$$

Parameters: error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine unskew_cell defined in file src/libAtoms/Atoms_types.f95.

wrap(center=(0.5, 0.5, 0.5), pbc=None, eps=1e-07)[source]

Wrap positions to unit cell.

Parameters:

center: three float
The positons in fractional coordinates that the new positions will be nearest possible to.
pbc: one or 3 bool
For each axis in the unit cell decides whether the positions will be moved along this axis. By default, the boundary conditions of the Atoms object will be used.
eps: float
Small number to prevent slightly negative coordinates from being wrapped.

See also the ase.geometry.wrap_positions() function. Example:

>>> a = Atoms('H',
...           [[-0.1, 1.01, -0.5]],
...           cell=[[1, 0, 0], [0, 1, 0], [0, 0, 4]],
...           pbc=[1, 1, 0])
>>> a.wrap()
>>> a.positions
array([[ 0.9 ,  0.01, -0.5 ]])

write(dest=None, format=None, properties=None, prefix=None, **kwargs)[source]

Write this Atoms object to dest. If format is absent it is inferred from the file extension or type of dest, as described for the read() method. If properties is present, it should be a list of property names to include in the output file, e.g. [‘species’, ‘pos’].

See Supported File Formats for a list of supported file formats.

write_cinoutput(cio[, properties, properties_array, prefix, int_format, real_format, frame, shuffle, deflate, deflate_level, estr, error])
Parameters: cio : CInOutput object properties : input string(len=-1), optional properties_array : input rank-2 array(‘S’) with bounds (qp_n0,(*)), optional prefix : input string(len=-1), optional int_format : input string(len=-1), optional real_format : input string(len=-1), optional frame : input int, optional shuffle : input int, optional deflate : input int, optional deflate_level : input int, optional estr : Extendable_str object, optional error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine atoms_write_cinoutput defined in file src/libAtoms/CInOutput.f95.

z_index_to_index(*args, **kwargs)

Inverse of atoms_index_to_z_index

Parameters: z : input int z_index : input int error : in/output rank-0 array(int,’i’), optional ret_index : int

References

Routine is wrapper around Fortran routine z_index_to_index defined in file src/libAtoms/Atoms_types.f95.

zero(*args, **kwargs)

Zero data in an Atoms structure — this doesnt finalise it or change its size. We zero this.pos, this.Z and this.species.

Parameters: indices : input int, optional Optionally only zero the specified indices.

References

Routine is wrapper around Fortran routine zero defined in file src/libAtoms/Atoms_types.f95.

zero_angular_momentum(*args, **kwargs)

give the system a rigid body rotation so as to zero the angular momentum about the centre of mass

References

Routine is wrapper around Fortran routine zero_angular_momentum defined in file src/libAtoms/DynamicalSystem.f95.

adsorbate_info

Return the adsorbate information set by one of the surface builder functions. This function is only supplied in order to give a warning if this attribute (atoms.adsorbate_info) is asked for. The dictionary with adsorbate information has been moved to the info dictionary, i.e. atoms.info[‘adsorbate_info’].

arrays

calc

Calculator object.

cell

Attribute for direct manipulation of the unit cell.

connect

Connection object

constraints

Constraints of the atoms.

cutoff

Cutoff distance for neighbour calculations. Default -1.0 (unset).

cutoff_skin

If set, increase cutoff by this amount to reduce calc_connect() frequency

domain

Domain decomposition object

fixed_size

Can the number of atoms be changed after initialisation?

g

Inverse lattice (stored for speed)

hysteretic_connect

Hysteretic Connection object

indices

Return array of atoms indices

If global fortran_indexing is True, returns FortranArray containing numbers 1..self.n. Otherwise, returns a standard numpuy array containing numbers in range 0..(self.n-1).

info

ASE info dictionary

Entries are actually stored in QUIP params dictionary.

lattice

Lattice vectors, as columns:

$\begin{split}\left( \begin{array}{ccc} | & | & | \\ \mathbf{a} & \mathbf{b} & \mathbf{c} \\ | & | & | \\ \end{array} \right) = \left( \begin{array}{ccc} R_{11} & R_{12} & R_{13} \\ R_{21} & R_{22} & R_{23} \\ R_{31} & R_{32} & R_{33} \\ \end{array} \right)\end{split}$

i.e. $$\mathbf{a}$$ = lattice(:,1), $$\mathbf{b}$$ = lattice(:,2) and $$\mathbf{c}$$ lattice(:,3).

n

The number of atoms held (including ghost particles)

nbuffer

The number of atoms that can be stored in the buffers of this Atoms object

ndomain

The number of atoms held by the local process (excluding ghost particles)

nneightol

Count as nearest neighbour if sum of covalent radii times this.nneightol greater than distance between atoms. Used in cluster carving.

number_of_lattice_vectors

Number of (non-zero) lattice vectors.

numbers

Attribute for direct manipulation of the atomic numbers.

own_this

Do I own myself?

params

Dictionary of parameters. Useful for storing data about this Atoms object, for example the temperature, total energy or applied strain. The data stored here is automatically saved to and loaded from XYZ and NetCDF files.

pbc

Attribute for direct manipulation of the periodic boundary condition flags.

positions

Attribute for direct manipulation of the positions.

properties

Dictionary of atomic properties. A property is an array of shape (m,n) where n is the number of atoms and m is either one (for scalar properties) or three (vector properties). Properties can be integer, real, string or logical. String properties have a fixed length of TABLE_STRING_LENGTH=10 characters.

From Fortran, the following default properties are aliased with arrays within the Atoms type:

• Z - Atomic numbers, dimension is actually $$(N)$$
• species Names of elements
• move_mask Atoms with move_mask set to zero are fixed
• damp_mask Damping is only applied to those atoms with damp_mask set to 1. By default this is set to 1 for all atoms.
• thermostat_region Which thermostat is applied to each atoms. By default this is set to 1 for all atoms.
• travel Travel across periodic conditions. $$(3,N)$$ integer array. See meth:map_into_cell below.
• pos $$(3,N)$$ array of atomic positions, in $$\mathrm{\AA}$$. Position of atom $$i$$ is pos(:,i)
• mass Atomic masses, dimension is $$(N)$$
• velo $$(3,N)$$ array of atomic velocities, in $$\mathrm{AA}$$/fs.
• acc $$(3,N)$$ array of accelerations in $$\mathrm{AA}$$/fs:math:^2
• avgpos $$(3,N)$$ array of time-averaged atomic positions.
• oldpos $$(3,N)$$ array of positions of atoms at previous time step.
• avg_ke Time-averaged atomic kinetic energy

Custom properties are most conveniently accessed by assign a pointer to them with the assign_pointer() routines.

From Python, each property is automatically visible as a array attribute of the Atoms object, for example the atomic positions are stored in a real vector property called pos, and can be accessed as at.pos.

Properties can be added with the add_property() method and removed with remove_property().

ref_count

Reference counter

quippy.atoms.make_lattice(a[, b, c, alpha, beta, gamma, error])

Make a matrix of lattice vectors from the lengths a,b,c and the angles alpha, beta and gamma. One length must be supplied. Any missing angle is assumed to be 90 degrees and any missing length is assumed to be a. The vectors are created in a right-handed order.

Parameters: a : input float b : input float, optional c : input float, optional alpha : input float, optional beta : input float, optional gamma : input float, optional error : in/output rank-0 array(int,’i’), optional ret_lattice : rank-2 array(‘d’) with bounds (3,3)

References

Routine is wrapper around Fortran routine make_lattice defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.get_lattice_params(lattice)[source]

Wrapper around Fortran get_lattice_params_()

Returns parameters of lattice as 6-tuple (a,b,c,alpha,beta,gamma).

quippy.atoms.bond_length(z1, z2)

Returns the sum of the covalent radii of two atoms

Parameters: z1 : input int z2 : input int ret_bond_length : float

References

Routine is wrapper around Fortran routine bond_length defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.termination_bond_rescale(z1, z2)

Calculates the rescale ratio of a Z1–H bond generate from a Z1–Z2 bond.

Parameters: z1 : input int z2 : input int ret_termination_bond_rescale : float

References

Routine is wrapper around Fortran routine termination_bond_rescale defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.cell_volume(*args, **kwargs)

calculate volume of unit cell

Routine is wrapper around Fortran interface cell_volume containing multiple routines:

quippy.atoms.cell_volume(lattice)

Returns the (unsigned) volume of the simulation cell of lattice

Parameters: lattice (input rank-2 array('d') with bounds (3,3)) – ret_lattice_cell_volume – float

Routine is wrapper around Fortran routine lattice_cell_volume defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.map_into_cell(*args, **kwargs)
Map atomic positions into the unit cell so that lattice
coordinates satisfy $-0.5 le t_x,t_y,t_z < 0.5$

Routine is wrapper around Fortran interface map_into_cell containing multiple routines:

quippy.atoms.map_into_cell(pos, lattice, g)
Parameters: pos (in/output rank-2 array('d') with bounds (qp_n0,qp_n1)) – lattice (input rank-2 array('d') with bounds (3,3)) – g (input rank-2 array('d') with bounds (3,3)) –

Routine is wrapper around Fortran routine array_map_into_cell defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.map_into_cell(pos, lattice, g[, shift, mapped])
Parameters: pos (in/output rank-1 array('d') with bounds (3)) – lattice (input rank-2 array('d') with bounds (3,3)) – g (input rank-2 array('d') with bounds (3,3)) – shift (in/output rank-1 array('i') with bounds (3), optional) – mapped (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine vec_map_into_cell defined in file src/libAtoms/Atoms_types.f95.

quippy.atoms.parse_atom_mask(mask_in[, error])

Parses an atom_mask, which is string consisting of the @ symbol followed by a comma separated list of indices or ranges into a table containing all the indices it represents. E.g. @1,37-39,54,99-102 is expanded to a table with 1, 37, 38, 39, 54, 99, 100, 101, 102 as its first integer column. There must be no spaces in the mask.

Parameters: mask_in : input string(len=-1) error : in/output rank-0 array(int,’i’), optional atom_indices : Table object

References

Routine is wrapper around Fortran routine parse_atom_mask defined in file src/libAtoms/Atoms_types.f95.