BulkConfiguration

class BulkConfiguration(bravais_lattice, elements, cartesian_coordinates=None, fractional_coordinates=None, ghost_atoms=None, velocities=None, tag_data=None, fast_init=False)

Class for representing a periodic structure, i.e bulk configuration.

Construction of a bulk configuration from a BravaisLattice object. The additional arguments are the elements, the Cartesian coordinates or fractional coordinates. The Cartesian coordinates and fractional coordinates cannot be given at the same time. The list arguments containing the elements and coordinates must have the same length.

Parameters:
  • bravais_lattice (BravaisLattice) – A lattice of the bulk configuration.
  • elements (PeriodicTableElement) – A sequence containing the elements of the configuration.
  • cartesian_coordinates (PhysicalQuantity of type length | None) – A sequence containing a sequence of atomic coordinates for each element in the configuration. Has the dimensionality nx3.
    Default: None
  • fractional_coordinates (array(n, 3) | None) – A sequence containing sequences of fractional coordinates for each element in the configuration.
    Default: None
  • ghost_atoms (int(n)) – A list of atom indices to treat as ghost atoms.
    Default: None
  • velocities (PhysicalQuantity of type length/time | None) – The velocities of the atoms. Has the dimensionality nx3.
    Default: None
  • tag_data (dict) – A dict of tag data, linking tags to a list of atom indices.
    Default: None
  • fast_init (bool) – Skip checking types and do not copy the arguments (i.e. only store references to them. This is an advanced option that should only be used internally.
    Default: False
addBonds(bond_list)

Add bonds.

Parameters:bond_list (numpy.ndarray) – The list of bonds to add.
addTags(tags, indices=None)

Add a set of tags to atoms matching a collection of indices.

Parameters:
  • tags (list | str) – The list of tags to add to matching atoms.
  • indices (list | int | None) – The list of indices to match atoms against.
    Default: All indices.
atomicMasses()
Returns:The masses of the atoms in the configuration.
Return type:PhysicalQuantity of type mass
atomicNumbers()
Returns:The list of atomic numbers associated with the elements.
Return type:list of ints
bonds()

Get the list of bond connections to can be used for bonded potentials in ATK-ForceField.

Returns:An array with the the two atom indices for each bond along with the vector which periodic images this bond connects.
Return type:array
bravaisLattice()
Returns:The bravais lattice of the configuration.
Return type:BravaisLattice
calculator()
Returns:The calculator attached to the configuration, i.e. the calculator that will be used for both simulation and analysis.
Return type:Calculator
cartesianCoordinates()
Returns:The Cartesian coordinates of the atoms as an nx3 array.
Return type:PhysicalQuantity of type length
center(x_axis=True, y_axis=True, z_axis=True)

Create a new BulkConfiguration by centering the atoms and the vacuum around the system.

The centered system is constructed with a cell of the type UnitCell.

Parameters:
  • x_axis (bool) – Boolean indicating if the system should be centered along the x-axis.
    Default: True.
  • y_axis (bool) – Boolean indicating if the system should be centered along the y-axis.
    Default: True.
  • z_axis (bool) – Boolean indicating if the system should be centered along the z-axis.
    Default: True.
Returns:

The centered bulk system.

Return type:

BulkConfiguration

cleave(h=1, k=0, l=0, max_perpendicular_repeats=100, outer_atom_index=0, surface_transformation=None, layers=None, top_vacuum=None, bottom_vacuum=None, outer_atom_placement=None)

Method to cleave the bulk system along the plane given by the Miller indices h, k, and l. Per the usual convention, the Miller indices defined a plane in the conventional unit cell.

Parameters:
  • h (int) – The first Miller index.
    Default: 1.
  • k (int) – The second Miller index.
    Default: 0.
  • l (int) – The third Miller index.
    Default: 0.
  • max_perpendicular_repeats (int) – The maximum number of times the crystal lattice should be repeated in order to become perpendicular to the surfaces plane. Will throw an exception if it is not possible. These repetitions are only used when layers is None.
    Default: 100
  • outer_atom_index (int) – The index of the configuration which should be the outer atom in the surface. This is the atom which intersects the cleave plane.
    Default: 0
  • surface_transformation (array of type float) – A 2x2 array that transforms the lattice vectors perpendicular to the surface normal (i.e. the surface vectors). This defaults to the identity matrix, which leaves them unchanged. If the values are non integral, this will result in a strained surface.
    Default: [[1, 0], [0, 1]]
  • layers (float) – The number of atomic layers in the repeated structure. By default the smallest number of layers that yields perpendicular unit cell (c-axis purely along the z-axis) is used.
    Default: None
  • top_vaccum (PhysicalQuantity of type length) – The vacuum padding to add to the top of the cell.
    Default: 0.0*Angstrom
  • bottom_vaccum (PhysicalQuantity of type length) – The vacuum padding to add to the bottom of the cell.
    Default: 0.0*Angstrom
  • outer_atom_placement (float) – The fractional c-coordinate of the outer atom. By default the location of this atom will be at c=1.0 if no top or bottom vacuum is used. If vacuum is used, then the atom will be located at the correct place in the unit cell to accommodate the vacuum settings.
    Default: None
Returns:

The cleaved bulk configuration.

Return type:

BulkConfiguration

copy()
Returns:A copy of the current configuration.
Return type:MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
copyAndDeleteAtoms(indices)

Create a new configuration by deleting some atoms from this configuration.

Parameters:indices (list of int) – The indices of the atoms to delete.
Returns:The configuration with some atoms deleted.
Return type:|ALL_CONFIGURAITONS|
copyAndMerge(other)

Create a new configuration by merging this configuration with another configuration.

Parameters:other (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration) – The other configuration.
Returns:The merged configuration.
Return type:MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
copyAndShiftAtoms(displacement, indices=None)

Create a new configuration with some atoms translated.

Parameters:
  • displacement (PhysicalQuantity of type length) – The displacement that should be applied to the atom positions.
  • indices (list of int) – The indices to shift.
    Default: All.
Returns:

The configuration with the translation applied.

Return type:

MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration

deleteAtoms(indices)

Delete atoms from the configuration by specifying their indices.

Parameters:indices (array of int) – The indices to delete.
deleteBonds(bond_list=None, pair_selection=None)

Delete bonds connected to atomic indices.

Parameters:
  • bond_list (A two-dimensional sequence) – The pairs of bondes indices.
  • pair_selection (list | None) – Specifies two groups between which bonds are delete. Selectable groups are elements, index lists, tag names, or None (all atoms).
dielectricRegions()
Returns:The dielectric regions in the configuration.
Return type:list of BoxRegion | SphereRegion | TubeRegion
elements()
Returns:The elements in configuration.
Return type:list of PeriodicTableElement
externalPotential()
Returns:The external potential present on the configuration.
Return type:AtomicShift | AtomicCompensationCharge | None
findBonds(fuzz_factor=1.1, pair_selection=None, periodic_boundaries=None)

Find bonds in the configuration according to the combined covalent radii of the element pairs, multiplied with a fuzz factor. Optionally, find bonds only between two specified sub-groups of atoms. The bonds are primarily used in to set the topology of bonded potentials in the TremoloX-calculator.

Parameters:
  • fuzz_factor (float) – The factor by which the covalent radii are multiplied to determine the cutoff distance for a bond.
  • pair_selection (list(2) of type PeriodicTableElement, list of int, or str) – Specifies two groups between which bonds are detected. Selectable groups are elements, index lists, tag names, or None (all atoms). By default bonds between all atoms in the configuration are taken into account.
  • periodic_boundaries (3-tuple of bool) – The periodic boundaries
    Default: The periodic boundaries for the configuration.
fixedSpinDirections()
Returns:The fixed spin directions for the configuration.
Return type:FixedSpin | None
fractionalCoordinates()
Returns:The fractional coordinates of the bulk configuration as a nx3 array.
Return type:array of floats
generateShifts()

Method for generating a list of origin shifts along all 3 lattice directions.

It will create a list of 27 shifts of the supercell origin (-1 to 1) in the three periodic directions.

Returns:The list of shifts (in units of Angstrom).
Return type:list of list (size 3) of float
ghostAtoms()
Returns:The list of ghost atoms.
Return type:list of ints
improperDihedralIndices()
Returns:The list of atom indices for each improper dihedral or None if no improper dihedrals are defined. Improper dihedrals are mainly used in bonded force fields.
Return type:numpy array | None
indicesFromIsotopes(isotopes)
Parameters:isotopes (list of type PeriodicTableElement or Isotope) – The isotopes to select.
Returns:The indices of the selected isotopes.
Return type:list of type int
indicesFromTags(tags=None)

List the indices associated with a given collection of tags.

Parameters:tags (list | str) – A list of tags for which all matching indices should be extracted.
Returns:The list of indices corresponding to the specified tag name(s).
Return type:list of ints
massDensity()
Returns:The mass density.
Return type:PhysicalQuantity of type mass per volume
merge(other)

Merge configuration with another configuration.

Parameters:other (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration) – A different configuration.
metallicRegions()
Returns:The metallic regions for the configuration.
Return type:list of BoxRegion | SphereRegion | TubeRegion
metatext()
Returns:The metatext of the object or None if no metatext is present.
Return type:str | unicode | None
nlprint(stream=None)

Print a string containing an ASCII table useful for plotting the AtomicConfiguration object.

Parameters:stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger().
numberOfAtoms()
Returns:The total number of atoms in the configuration.
Return type:int
partialCharges(indices=None)

Get the list of partial atomic charges that can be used for representing electrostatic interactions in ATK-ForceField.

Parameters:indices (list | int | None) – The indices for which to return the partial charges.
Default: All indices.
Returns:A PhysicalQuantity array of the atomic partial charge for each atom.
Return type:PhysicalQuantity of type charge | None
particleDescriptors()
Returns:The list of particle descriptors for each atom. This should return the exact same list as was given in the constructor argument “elements”.
Return type:list of type ParticleDescriptor or PeriodicTableElement
static periodicBoundaries()
Returns:The periodic boundary conditions of the configuration.
Return type:list
primitiveVectors()
Returns:The primitive lattice vectors.
Return type:PhysicalQuantity of type length
reduce(na=1, nb=1, nc=1, stack_systems=True)

Reduce the BulkConfiguration with the integer values na, nb, and nc along the three primitive unit cell vectors. The reduced system is constructed with a cell of the type UnitCell.

Parameters:
  • na (int) – The repetition along the a-axis.
    Default: 1.
  • nb (int) – The repetition along the b-axis.
    Default: 1.
  • nc (int) – The repetition along the c-axis.
    Default: 1.
  • stack_systems (bool) – If True the basis atoms are reduced as a unit, i.e. a0 and b0 are reduced as: a0,b0,a1,b1, … If False the basis atom are reduced individually, i.e. a0 and b0 are reduced as: a0,a1,…, b0,b1,…
    Default: True.
Returns:

The reduced bulk system.

Return type:

BulkConfiguration

removeTags(tags=None, indices=None, purge=False)

Remove a set of tags from atoms matching a collection of indices.

Parameters:
  • tags (list | str) – The list of tags to add to matching atoms.
    Default: All tags.
  • indices (list | int) – The list of indices to match atoms against.
    Default: All indices.
  • purge (bool) – When removing tags from the configuration, delete the tag completely when not associated with any atoms anymore.
    Default: False.
repeat(na=1, nb=1, nc=1, stack_systems=True, transfer_density_matrix=True)

Repeat the BulkConfiguration with the integer values na, nb, and nc along the three primitive unit cell vectors. The repeated system is constructed with a cell of the type UnitCell.

Parameters:
  • na (int) – The repetition along the a-axis.
    Default: 1.
  • nb (int) – The repetition along the b-axis.
    Default: 1.
  • nc (int) – The repetition along the c-axis.
    Default: 1.
  • stack_systems (bool) – If True the basis atoms are repeated as a unit, i.e. a0 and b0 are repeated as: a0,b0,a1,b1, … If False the basis atom are repeated individually, i.e. a0 and b0 are repeated as: a0,a1,…, b0,b1,…
    Default: True.
  • transfer_density_matrix (bool) – If True, the density matrix (or rather the schroedinger container) of the non-repeated system is used to set up the density matrix of the repeated system.
    Default: True.
Returns:

The repeated bulk system.

Return type:

BulkConfiguration

scalePartialCharges(scale_factor, indices=None)

Scale the partial charges with a given scale factor. These partial charges are used with Forcefield calculators.

Parameters:
  • scale_factor (float) – The factor for scaling charges.
  • indices (list | int | None) – The indices for which to set the total charge.
    Default: All indices.
scalePrimitiveVectors(scale_a=None, scale_b=None, scale_c=None)

Scale the length of each lattice vector. The fractional coordinates of the atoms and the Bravais lattice type will be remain unchanged if possible.

Parameters:
  • scale_a (float) – The scaling factor for the a-axis to apply.
    Default: 1.0.
  • scale_b (float) – The scaling factor for the b-axis to apply.
    Default: 1.0.
  • scale_c (float) – The scaling factor for the c-axis to apply.
    Default: 1.0.
scaleVolume(scaling_factor)

Scale the volume of the crystal by an isotropic expansion of the lattice vectors. The fractional coordinates of the atoms and the Bravais lattice type will be unchanged.

Parameters:scaling_factor (float) – The scaling factor to apply. A value of 1.01 leads to a 1% increase in the volume.
setBonds(bond_list, skip_checks=False)

Set the bonds on the configuration. The bonds are primarily used in to set the topology of bonded potentials in the TremoloX-calculator.

Parameters:
  • bond_list (list(n, 2) | list(n, 5) | None) – A list which contains for each bond the indices of the two connected atoms. Optionally, three more integers can be specified for each bond, which must be between -1 and 1, and which denote to which neighboring image cell the bond is connected. Without these additional indices, the minimum image convention is obeyed.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
    Default: False.
setBravaisLattice(bravais_lattice, conserve_coordinates=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Cartesian'>, skip_checks=False)

Change the bravais lattice.

Parameters:
  • bravais_lattice (BravaisLattice) – The new lattice.
  • conserve_coordinates (Cartesian | Fractional) – The type of coordinates to conserve..
    Default: Cartesian.
  • skip_checks (bool) – If True, ignores bond connectivity and input argument checks.
    Default: False.
setCalculator(calculator, initial_state=None, initial_spin=None)

Attach a Calculator to the configuration which will be used in calculations involving the configuration.

Parameters:
setCartesianCoordinates(cartesian_coordinates, indices=None, skip_checks=False)

Set the Cartesian coordinates of the atoms.

Parameters:
  • cartesian_coordinates (PhysicalQuantity of type length) – The new coordinates of the atoms in each image.
  • indices (list) – The indices of the atoms to set the positions of.
    Default: All indices.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
    Default: False.
setDielectricRegions(dielectric_regions)

Set the dielectric regions for the configuration.

Parameters:dielectric_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of dielectric regions to set.
setExternalPotential(external_potential)

Set an external potential on the configuration that will be used in calculations involving the configuration.

Parameters:external_potential (AtomicShift | AtomicCompensationCharge) – The external potential to apply.
setFractionalCoordinates(fractional_coordinates, indices=None, skip_checks=False)

Set the Cartesian coordinates of the atoms.

Parameters:
  • fractional_coordinates (array of floats) – The new coordinates of the atoms as a nx3 array.
  • indices (array of ints | None) – The indices of the atoms to set the positions of.
    Default: All indices.
  • skip_checks (bool) – If True, ignores bond connectivity and input argument checks.
    Default: False.
setImproperDihedralIndices(improper_dihedral_indices)

Set the list of atom indices for each improper dihedral in bonded force fields.

Parameters:improper_dihedral_indices (list or array with shape (m, 4) | None) – The list of the 4 indices defining the connectivity for each improper dihedral or None to delete the current dihedral connectivity.
setMagneticField(magnetic_field)

Set local magnetic field. The spins will be forced to point in the directions given by the magnetic_field object. The magnetic field can be defined for each atom. This only has an effect for Noncollinear or Spinorbit calculations.

Parameters:magnetic_field (FixedSpin) – The magnetic field to be applied.
setMetallicRegions(metallic_regions)

Set the metallic regions for the configuration.

:param metallic_regions:The list of metallic regions to set. :type metallic_regions:list of BoxRegion | SphereRegion | TubeRegion

setMetatext(metatext)

Set a given metatext string on the object.

Parameters:metatext (str | unicode | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.
setPartialCharges(charge_list, indices=None, skip_checks=False, update_calculator=True)

Set the partial charges on the configuration. The partial charges are used primarily to model electrostatic interactions in the TremoloX-calculator.

Parameters:
  • charge_list (PhysicalQuantity of type charge | None) – A list of atomic partial charges which contains a charge for each atom.
  • indices (list | int | None) – The indices for which to set the partial charges.
    Default: All indices.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
    Default: False.
  • update_calculator (bool) – Whether or not to update and attached Forcefield calculator with the new charges.
    Default: True.
setPrimitiveVectors(a, b, c, conserve_coordinates=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Cartesian'>, skip_checks=False)

Set the primitive lattice vectors for the configuration. This will change the BravaisLattice to a UnitCell. By default the Cartesian coordinates are not changed, which means that the relative positions of the atoms will change when the lattice vectors change.

Parameters:
  • a (PhysicalQuantity of type length) – The first lattice vector.
  • b (PhysicalQuantity of type length) – The second lattice vector.
  • c (PhysicalQuantity of type length) – The third lattice vector.
  • conserve_coordinates (Cartesian | Fractional) – The type of coordinates to conserve.
    Default: Cartesian.
  • skip_checks (bool) – If True, ignores bond connectivity and input argument checks.
    Default: True.
setVelocities(velocities=None, skip_checks=False)

Function to set velocities on the configuration.

Parameters:
  • velocities (PhysicalQuantity of type velocity | None) – The velocities to set on the configuration. Has the dimensionality nx3.
    Default: None.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
    Default: False.
shiftAtoms(displacement, indices=None, skip_checks=False)

Shift atoms by indices.

Parameters:
  • displacement (PhysicalQuantity of type length | array) – The displacement that should be applied to the atom positions. Can be given as cartesian or fractional coordinates.
  • indices (NoneType | list of ints) – The indices to shift.
  • skip_checks (bool) – True, if all consistency checks should be skipped.
shiftPartialCharges(total_charge, indices=None)

Shift the partial charges so that their sum is the given total charge value. These partial charges are used with Forcefield calculators.

Parameters:
  • total_charge (PhysicalQuantity of type charge) – The new total charge.
  • indices (list | int | None) – The indices for which to set the total charge.
    Default: All indices.
sortAlongC()

Method for sorting the atoms along C.

symbols()
Returns:The element symbols of the configuration.
Return type:list of str
tags(indices=None)

List the tags associated with a given collection of indices. The list returned is the set union of tags associated with the given indices. If no collection of indices is provided, then all tags on the configuration are returned.

Parameters:indices (list | int) – The indices to check.
Default: All indices.
Returns:The set union of tags present on the provided indices.
Return type:set
uniqueElements()
Returns:The unique elements contained in the configuration.
Return type:list of PeriodicTableElement
update(force_restart=False)

A self-consistent solution is generated, using the currently set calculator.

Parameters:force_restart (bool) – Force the self-consistent calculation to restart.
Default: False.
velocities()
Returns:The velocities of the atoms. Has the dimensionality nx3.
Return type:PhysicalQuantity of type velocity

Usage Examples

Define the geometry of a lithium BCC crystal:

lattice = BodyCenteredCubic( 3.509 * Ang)
li_bcc_bulk = BulkConfiguration(
    lattice,
    [Lithium],
    [ ( 0.0, 0.0, 0.0 ) * Ang ]
    )

li_bcc.py

Specify the geometry of a diamond crystal:

elements = [ Carbon ] * 2
coordinates = [
    ( 0.00, 0.00, 0.00 ),
    ( 0.25, 0.25, 0.25 )
    ]
diamond_lattice = FaceCenteredCubic( 3.567 * Ang )
diamond = BulkConfiguration(
    diamond_lattice,
    elements,
    fractional_coordinates = coordinates
    )

si_diamond.py

Notes

ATK recognizes four types of atomic geometries:

1D or 2D periodic geometries, such as nanotubes, slabs, and atomic chains must be represented as a BulkConfiguration with sufficient vacuum to isolate the system in the non-periodic directions.

It is possible to specify vacuum basis sets (ghost atoms) by adding an additional atom and include the index of that atom in the ghost_atom list. In this case the valence basis set of the atom is included in the orbital list, but there will be no atomic potential at the site.