Atom, Structure, and HFTransform

class pylada.crystal.cppwrappers.Atom

Bases: object

Defines an atomic site.

__init__ accepts different kind of input.

• The position can be given as:

  • the first three positional argument
  • as a keyword argument position,

• The type can be given as:

  • arguments listed after the first three giving the position. A list is created to hold references to these arguments.
  • as a keyword argument type.

• All other keyword arguments become attributes. In other words, one could add magnetic=0.5 if one wanted to specify the magnetic moment of an atom.

For instance, the following will create a silicon atom at the origin:

atom = Atom(0, 0, 0, 'Si')

Or we could place a iron atom with a magntic moment:

atom = Atom(0.25, 0, 0.5, 'Si', moment=0.5)

The moment keyword will create a corresponding atom.moment keyword with a value of 0.5. There are strictly no limits on what kind of type to include as attributes. However, in order to work well with the rest of Pylada, it is best if extra attributes are pickle-able.

Note

the position is always owned by the object. Two atoms will not own the same position object. The position given on input is copied, not referenced. All other attributes behave like other python attributes: they are refence if complex objects and copies if a basic python type.

This class is also available directly under pylada.crystal.

copy() → Atom

Returns a deepcopy of the atom.

to_dict() → dict

Returns a dictionary with shallow copies of items.

pos

Position in cartesian coordinates.

The position does not yet have units. Units depend upon pylada.crystal.Structure.scale. Finally, the position is owned internally by the atom. It cannot be set to reference an object (say a list or numpy array). atom.pos = some_list will copy the values of``some_list``.

type

Occupation of this atomic site.

Can be any object whatsoever.

class pylada.crystal.cppwrappers.Structure

Bases: object

Defines a structure.

A structure is a special kind of sequence containing only Atom. It also sports attributes such a cell and scale.

__init__ accepts different kind of input.

• if 9 numbers are given as arguments, these create the cell vectors, where the first three numbers define the first row of the matrix(not the first cell vector, eg column).
• if only one object is given it should be the cell matrix.
• the cell can also be given as a keyword argument.
• the scale can only be given as a keyword argument.
• All other keyword arguments become attributes. In other words, one could add magnetic=0.5 if one wanted to specify the magnetic moment of a structure. It would later be accessible as an attribute, eg as structure.magnetic.

Note

The cell is always owned by the object. Two structures will not own the same cell object. The cell given on input is copied, not referenced. All other attributes behave like other python attributes: they are refence if complex objects and copies if a basic python type.

This class is also available directly under pylada.crystal.

volume

Volume of the structure.

Includes scale.

cell

Cell matrix in cartesian coordinates.

Unlike most ab-initio codes, cell-vectors are given in column vector format. The cell does not yet have units. Units depend upon Structure.scale. Across pylada, it is expected that a cell time this scale are angstroms. Finally, the cell is owned internally by the structure. It cannot be set to reference an object (say a list or numpy array). structure.cell = some_list will copy the values of some_list.

scale

Scale factor of this structure. Should be a number or unit given by the python package quantities. If given as a number, then the current units are kept. Otherwise, it changes the units.

copy() → Structure

Returns a deepcopy of the structure.

to_dict() → dict

Returns a dictionary with shallow copies of items.

clear() → None

Removes all atoms from structure.

insert(index, atom) → None

Inserts atom at given position.

Parameters:

• index – Position at which to insert the atom.
• atom – Atom or subtype to insert.

pop(index) → Atom

Removes and returns atom at given position.

extend(atoms) → None

Appends list of atoms to structure.

The argument is any iterable objects containing only atoms, e.g. another Structure.

append(atoms) → None

Appends an Atom or subtype to the structure.

transform(matrix) → Structure

Transform a structure in-place.

Applies an affine transformation to a structure. An affine transformation is a 4x3 matrix, where the upper 3 rows correspond to a rotation (applied first), and the last row to a translation (applied second).

Parameters:matrix – Affine transformation defined as a 4x3 numpy array. Returns:A new Structure (or derived) instance.

add_atom(...) → Structure

Adds atom to structure.

The argument to this function is either another atom, in which case a reference to that atom is appended to the structure. Or, it is any arguments used to initialize atoms in Atom. Finally, this function can be chained as follows:

structure.add_atom(0,0,0, 'Au')                        \
         .add_atom(0.25, 0.25, 0.25, ['Pd', 'Si'], m=5)\
         .add_atom(atom_from_another_structure)

In the example above, both structure and the other structure will reference the same atom (atom_from_another_structure). Changing, say, that atom’s type in one structure will also change it in the other.

Returns:The structure itself, so that add_atom methods can be chained.

__getitem__()

Retrieves atom or slice.

Parameters:index – If an integer, returns a refence to that atom. If a slice, returns a list with all atoms in that slice.

__setitem__()

Sets atom or atoms.

Parameters:

• index – If an integers, sets that atom to the input value. If a slice, then sets all atoms in refered to in the structure to the corresponding atom in the value.
• value – If index is an integer, this should be an atom. If index is a slice, then this should be a sequence of atoms of the exact length of the slice.

class pylada.crystal.cppwrappers.HFTransform

Bases: object

Defines a hftransform.

The Hart-Forcade transform computes the cyclic group of supercell with respect to its backbone lattice. It can then be used to index atoms in the supercell, irrespective of which periodic image is given [HF].

Parameters:

• lattice (Structure() or matrix) – Defines the cyclic group.
• supercell (Structure() or matrix) – Supercell for which to compute cyclic group.

This class is also available directly under pylada.crystal.

quotient

Periodicity quotient.

transform

Transformation matrix to go from position to hf index.

copy() → HFTransform

Returns a deepcopy of the hftransform.

indices(position) → numpy.array

indices of input atomic position in cyclic Z-group.

Parameters:vec – A 3d-vector in the sublattice of interest. Returns:The 3-d indices in the cyclic group.

flatten_indices(indices, index=0) → numpy.array

Flattens cyclic Z-group indices.

Parameters:

• i (int) – First index into cyclic Z-group.
• j (int) – Second index into cyclic Z-group.
• j – Third index into cyclic Z-group.
• site (int) – Optional site index for multilattices.

Returns:

An integer which can serve as an index into a 1d array.

index(position, index=0) → numpy.array

Flat index into cyclic Z-group.

Parameters:

• pos – (3d-vector) Atomic position with respect to the sublattice of interest. Do not forget to shift the sublattice back to the origin.
• site – (integer) Optional site index. If there are more than one sublattice in the structure, then the flattened indices need to take this into account.