Connection objects

class quippy.atoms.Connection(n, nbuffer[, pos, lattice, g, origin, extent, nn_guess, store_rij, fill])[source]

Bases: quippy._atoms.Connection

The Connection type stores the topology of a set of Atoms

We do not use a minimum image convention, rather, collect all the images of a neigbouring atoms that fall within the neighbour cutoff. The different images are made distinct in the connection list by having different shift vectors associated with them.

To save storage, the neighbour1 table contains all information about the connection but is only filled in for \(i <= j\). neighbour2 is just a list of those of \(i\)’s neighbours with \(i > j\) together with an index into the neighbour1 table of atom \(j\).

In normal use (i.e. outside this module) you don’t need direct access to the tables so you should use the interface functions atoms_n_neighbours and atoms_neighbour which hide the distiction between the cases \(i <= j\) and \(i > j\).

Table neighbour1 (i): \(i \le j\) for all \(j\) in table, intsize=4, realsize=1

connect.neighbour1(i)%int

+----------+----------+----------+----------+
|    1     |    2     |    3     |    4     |
+----------+----------+----------+----------+
|    j     | shift_a  | shift_b  | shift_c  |
+----------+----------+----------+----------+

connect.neighbour1(i)%real

+----------+
|    1     |
+----------+
|  r_ij    |
+----------+

Table neighbour2 (i): \(i > j\) for all \(j\) in table, intsize =2, realsize=0

connect.neighbour2(i)%int

+----------+----------+
|    1     |    2     |
+----------+----------+
|    j     |    n     |
+----------+----------+

Table cell (i,j,k) with intsize = 1, realsize = 0

connect.cell(i,j,k)2.int

+----------+
|    1     |
+----------+
|  atom    |
+----------+

N.B. If \(i\) and \(j\) are neighbours with shift shift, then norm(atoms.pos(j) - atoms.pos(i) + shift) is a minimum. Mnemonic: shift is added to \(j\) to get closer to \(i\).

Initialise a Connection object for a given number of atoms N. If the optional Atoms argument is present then we calculate the atomic density to initialise the default lengths of the neighbour list for efficient memory usage.

The Connection is a subclass of _atoms.Connection which adds supports for iteration over all atoms, and indexing e.g. at.connect.neighbours[1] returns a list of the neighbours of the atom with index 1.

When indexed with an integer from 1 to at.n, returns an array of NeighbourInfo objects, each of which corresponds to a particular pair (i,j) and has attributes j, distance, diff, cosines and shift.

If fortran_indexing is True, atom and neighbour indices start from 1; otherwise they are numbered from zero.

If connectivity information has not already been calculated calc_connect() will be called automatically. The code to loop over the neighbours of all atoms is quite idiomatic:

for i in at.indices:
   for neighb in at.connect[i]:
       print (neighb.j, neighb.distance, neighb.diff,
              neighb.cosines, neighb.shift)

Note that this provides a more Pythonic interface to the atomic connectivity information than the wrapped Fortran functions Atoms.n_neighbours() and Atoms.neighbour().

Parameters:
n : input int
nbuffer : input int
pos : input rank-2 array(‘d’) with bounds (qp_n0,qp_n1), optional
lattice : input rank-2 array(‘d’) with bounds (3,3), optional
g : input rank-2 array(‘d’) with bounds (3,3), optional
origin : input rank-1 array(‘d’) with bounds (3), optional
extent : input rank-2 array(‘d’) with bounds (3,3), optional
nn_guess : input int, optional
store_rij : input int, optional
fill : input int, optional

References

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

Methods

distances([Z1, Z2]) Distances between pairs of neighbours, optionally filtered by species (Z1,Z2)
get_neighbors(i) Variant spelling of get_neighbours()
get_neighbours(i) Return neighbours of atom i
iterneighbours() Iterate over the neighbours of all atoms
pairs() Yield pairs of atoms (i,j) with i < j which are neighbours
add_bond(pos, lattice, i, j, shift, d[, dv, error])
Parameters:
pos : input rank-2 array(‘d’) with bounds (qp_n0,qp_n1)
lattice : input rank-2 array(‘d’) with bounds (3,3)
i : input int
j : input int
shift : input rank-1 array(‘i’) with bounds (3)
d : input float
dv : input rank-1 array(‘d’) with bounds (3), optional
error : in/output rank-0 array(int,’i’), optional

References

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

assignment(to, from)

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

Parameters:
to : Connection object
from : Connection object

References

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

calc_connect(at[, own_neighbour, store_is_min_image, skip_zero_zero_bonds, store_n_neighb, cutoff_skin, max_pos_change, did_rebuild, error])

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

Parameters:
at : Atoms object
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
cutoff_skin : input float, 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(at, cutoff_factor, cutoff_break_factor[, origin, extent, own_neighbour, store_is_min_image, store_n_neighb, error])

As for calc_connect, but perform the connectivity update hystertically: atoms must come within cutoff to be considered neighbours, and then will remain connect until them move apart further than cutoff_break.

Parameters:
at : Atoms object
cutoff_factor : input float
cutoff_break_factor : input float
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(at[, parallel, error])

The subroutine calc_dists updates the stored distance tables using the stored connectivity and shifts. This should be called every time any atoms are moved (e.g. it is called by DynamicalSystem.advance_verlet).

Parameters:
at : Atoms object
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.

cell_n(i, j, k[, error])
Parameters:
i : input int
j : input int
k : input int
error : in/output rank-0 array(int,’i’), optional
Returns:
ret_cell_n : int

References

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

cell_of_pos(lat_pos)
Parameters:
lat_pos : input rank-1 array(‘d’) with bounds (3)
i : int
j : int
k : int

References

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

cells_initialise(cellsna, cellsnb, cellsnc[, natoms])

OMIT

Parameters:
cellsna : input int
cellsnb : input int
cellsnc : input int
natoms : input int, optional

References

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

distances(Z1=None, Z2=None)[source]

Distances between pairs of neighbours, optionally filtered by species (Z1,Z2)

fill(n, nbuffer[, pos, lattice, g, origin, extent, nn_guess, store_rij, error])
Parameters:
n : input int
nbuffer : input int
pos : input rank-2 array(‘d’) with bounds (qp_n0,qp_n1), optional
lattice : input rank-2 array(‘d’) with bounds (3,3), optional
g : input rank-2 array(‘d’) with bounds (3,3), optional
origin : input rank-1 array(‘d’) with bounds (3), optional
extent : input rank-2 array(‘d’) with bounds (3,3), optional
nn_guess : input int, optional
store_rij : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

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

get_neighbors(i)[source]

Variant spelling of get_neighbours()

get_neighbours(i)[source]

Return neighbours of atom i

Return arrays of indices and offsets to neighbouring atoms. The positions of the neighbor atoms can be calculated like this:

indices, offsets = atoms.connect.get_neighbors(42)
for i, offset in zip(indices, offsets):
   print atoms.positions[i] + dot(offset, atoms.get_cell())

Compatible with ase.calculators.neighborlist.NeighborList.get_neighbors(), providing that NeighborList is constructed with bothways=True and self_interaction=False.

iterneighbours()[source]

Iterate over the neighbours of all atoms

n_neighbours(*args, **kwargs)

Neighbour list stuff

Wrapper around Fortran interface n_neighbours containing multiple routines:

n_neighbours(i[, error])

Return the total number of neighbour that atom \(i\) has.

Parameters:
  • i (input int) –
  • error (in/output rank-0 array(int,'i'), optional) –
Returns:

ret_n – int

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

n_neighbours(at, i[, max_dist, max_factor, error])

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.

Parameters:
  • at (Atoms object) –
  • i (input int) –
  • max_dist (input float, optional) –
  • max_factor (input float, optional) –
  • error (in/output rank-0 array(int,'i'), optional) –
Returns:

ret_n – int

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

n_neighbours_total([error])

Return the total number of neighbour, i.e. the number of bonds in the system

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

References

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

neighbour(*args, **kwargs)

Wrapper around Fortran interface neighbour containing multiple routines:

neighbour(at, i, n[, distance, diff, cosines, shift, index, max_dist, jn, error])

Return the index of the \(n^{\mbox{\small{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 an 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

Parameters:
  • at (Atoms object) –
  • 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) –
  • error (in/output rank-0 array(int,'i'), optional) –
Returns:

ret_j – int

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

neighbour(i, n)
Parameters:
  • i (input int) –
  • n (input int) –
  • shift (rank-1 array('i') with bounds (3)) –
  • index (int) –
  • ret_j (int) –

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

pairs()[source]

Yield pairs of atoms (i,j) with i < j which are neighbours

partition_atoms(at[, dont_wipe, error])

Spatially partition the atoms into cells. The number of cells in each dimension must already be set (cellsNa,b,c). Pre-wiping of the cells can be skipped (e.g. if they are already empty).

Parameters:
at : Atoms object
dont_wipe : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

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

print_([file, error])

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.

remove_bond(i, j[, shift, error])
Parameters:
i : input int
j : input int
shift : 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 remove_bond defined in file src/libAtoms/Atoms_types.f95.

remove_bonds(at, bonds[, error])

Remove all bonds listed in the Table bonds from connectivity

Parameters:
at : Atoms object
bonds : Table object
error : in/output rank-0 array(int,’i’), optional

References

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

wipe(*args, **kwargs)

connection_wipe

Wipe the contents of the connection tables, but keep the allocation

References

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

cell_heads

First entry in cell atoms structure

cellsna

no. of cells in the lattice directions

is_min_image

True if i is a minimum image

last_connect_cutoff

Value of cutoff used last time connectivity was updated

last_connect_lattice

Lattice last time connectivity was updated

last_connect_pos

Positions of atoms last time connnectivity was updated

n

no. of atoms at last calc_connect

next_atom_in_cell

List of atoms, terminated by zero

quippy.atoms.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 and centred on the origin, what parameters must we pass to supercell to make a system big enough from our original cell defined by lattice for the box to fit inside?

The required supercell parameters are returned in Na, Nb, Nc respectively. If, e.g. Na = 1 then we don``t need to supercell in the a direction. Na > 1 means we must supercell by ``Na’ times in the \(x\) direction.

Parameters:
rx : input float
ry : input float
rz : input float
lattice : input rank-2 array(‘d’) with bounds (3,3)
na : int
nb : int
nc : int

References

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

quippy.atoms.divide_cell(lattice, cutoff)

Given a simulation cell defined by lattice vectors, how many times can the cell be divided along the lattice vectors into subcells such that a sphere of radius cutoff with centre in one subcell does not spill out of the surrounding \(3 \times 3\) subcell block?

Parameters:
lattice : input rank-2 array(‘d’) with bounds (3,3)

Box defined by lattice vectors

cutoff : input float

Radius of sphere

na : int

Number of supercells required along \(x\), \(y\) and \(z\)

nb : int

Number of supercells required along \(x\), \(y\) and \(z\)

nc : int

Number of supercells required along \(x\), \(y\) and \(z\)

References

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

quippy.atoms.get_min_max_images(is_periodic, cellsna, cellsnb, cellsnc, cell_image_na, cell_image_nb, cell_image_nc, i, j, k, do_i, do_j, do_k)
Parameters:
is_periodic : input rank-1 array(‘i’) with bounds (3)
cellsna : input int
cellsnb : input int
cellsnc : input int
cell_image_na : input int
cell_image_nb : input int
cell_image_nc : input int
i : input int
j : input int
k : input int
do_i : input int
do_j : input int
do_k : input int
min_cell_image_na : int
max_cell_image_na : int
min_cell_image_nb : int
max_cell_image_nb : int
min_cell_image_nc : int
max_cell_image_nc : int

References

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

quippy.atoms.max_cutoff(lattice[, error])

Returns the maximum cutoff radius for calc_connect, given the lattice if we want to avoid image neghbours

Parameters:
lattice : input rank-2 array(‘d’) with bounds (3,3)
error : in/output rank-0 array(int,’i’), optional
Returns:
ret_max_cutoff : float

References

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