DeviceConfiguration

class DeviceConfiguration(central_region, electrodes, equivalent_electrode_lengths=None)

A two-probe configuration consisting of a central region coupled to two electrodes.

Parameters:
  • central_region (BulkConfiguration) – The scattering region of the device.
  • electrodes (list of BulkConfiguration) – The semi-infinite regions on either side of the device.
  • equivalent_electrode_lengths (Sequence of length 2 of PhysicalQuantity of type length
    Default: Length of the actual electrodes given.) – The lengths to use for the equivalent electrode regions in the central region.
class RestartInformation(initial_state, initial_spin, restart_step_length, max_diff)
count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

initial_spin

Alias for field number 1

initial_state

Alias for field number 0

max_diff

Alias for field number 3

restart_step_length

Alias for field number 2

DeviceConfiguration.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.
DeviceConfiguration.atomicMasses()
Returns:The masses of the atoms in the configuration.
Return type:PhysicalQuantity of type mass
DeviceConfiguration.atomicNumbers()
Returns:The list of atomic numbers associated with the elements.
Return type:list of ints
DeviceConfiguration.bias()

Calculate the bias of the attached calculator If no calculator is attached return None.

Returns:The bias.
Return type:PhysicalQuantity with electric potential units | None
DeviceConfiguration.bonds()
Returns:An array with the the two atom indices for each bond in the central region along with the vector which periodic images this bond connects.
Return type:array
DeviceConfiguration.bravaisLattice()
Returns:The bravais lattice of the central region.
Return type:BravaisLattice
DeviceConfiguration.calculator()
Returns:The calculator attached to the configuration, i.e. the calculator that will be used for both simulation and analysis.
Return type:Calculator
DeviceConfiguration.cartesianCoordinates()

The Cartesian coordinates of the atoms in the the central region of the configuration.

Returns:The Cartesian coordinates.
Return type:PhysicalQuantity of type length
DeviceConfiguration.centralRegion()

The central region of the device.

Returns:The central region.
Return type:BulkConfiguration
DeviceConfiguration.copy()
Returns:A copy of the current configuration.
Return type:MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
DeviceConfiguration.crossSection()

Return the cross-sectional area of the central region.

Returns:The cross-sectional area
Return type:float
DeviceConfiguration.dielectricRegions()
Returns:The dielectric regions in the central region.
Return type:list of BoxRegion | SphereRegion | TubeRegion
DeviceConfiguration.electrodes()

The electrodes of the device.

Returns:The pair of electrodes belonging to this configuration.
Return type:list of BulkConfiguration
DeviceConfiguration.electrodesDisplacement()

The displacements of the BravaisLattice of the electrodes in the C-direction in order to match the BravaisLattice of the central_region.

Returns:The electrode displacements.
Return type:PhysicalQuantity of type length
DeviceConfiguration.elements()
Returns:The elements in configuration.
Return type:list of PeriodicTableElement
DeviceConfiguration.externalPotential()
Returns:The external potential present in the central region.
Return type:AtomicShift | AtomicCompensationCharge
DeviceConfiguration.findBonds(fuzz_factor=1.1, pair_selection=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.
DeviceConfiguration.fixedSpinDirections()
Returns:The fixed spin directions for the configuration.
Return type:FixedSpin | None
DeviceConfiguration.fractionalCoordinates()
Returns:The fractional coordinates of the central region.
Return type:array of floats
DeviceConfiguration.ghostAtoms()
Returns:The list of ghost atoms of the central region.
Return type:list of ints
DeviceConfiguration.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
DeviceConfiguration.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
DeviceConfiguration.metallicRegions()
Returns:The metallic regions in the central region.
Return type:list of BoxRegion | SphereRegion | TubeRegion
DeviceConfiguration.metatext()
Returns:The metatext of the object or None if no metatext is present.
Return type:str | unicode | None
DeviceConfiguration.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()
DeviceConfiguration.numberOfAtoms()
Returns:The total number of atoms in the configuration.
Return type:int
DeviceConfiguration.periodicBoundaries()
Returns:The periodic boundary conditions of the configuration.
Return type:list
DeviceConfiguration.primitiveVectors()
Returns:The primitive lattice vectors.
Return type:PhysicalQuantity of type length
DeviceConfiguration.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
DeviceConfiguration.repeat(na=1, nb=1, nc=1, stack_systems=False)

Repeat the derived class 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
Returns:

The repeated system.

Return type:

DeviceConfiguration | SurfaceConfiguration

DeviceConfiguration.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.
  • indices (int(n) | None) – The indices of the atoms to set the list of bonds.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
DeviceConfiguration.setCalculator(calculator, initial_state=None, initial_spin=None)

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

Parameters:
  • calculator (Calculator) – The calculator object that should be attached to the configuration.
  • initial_state (DeviceConfiguration with a calculator | None) – The initial state to be used for this configuration.
    Default: No initial state.
  • initial_spin (InitialSpin | None) – The initial InitialSpin object to be used for this configuration.
    Default: No initial spin.
DeviceConfiguration.setCartesianCoordinates(cartesian_coordinates, indices=None, skip_checks=False)

Set the Cartesian coordinates of the atoms in the central region. Changes in the coordinates of the electrode extension will be synchronized with the corresponding coordinates in the electrodes.

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
DeviceConfiguration.setDielectricRegions(dielectric_regions)

Set the dielectric regions for the central region.

Parameters:dielectric_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of dielectric regions to set.
DeviceConfiguration.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.
DeviceConfiguration.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.
DeviceConfiguration.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.
DeviceConfiguration.setMetallicRegions(metallic_regions)

Set the metallic regions for the central region.

Parameters:metallic_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of metallic regions to set.
DeviceConfiguration.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.
DeviceConfiguration.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
DeviceConfiguration.symbols()
Returns:The element symbols of the configuration.
Return type:list of str
DeviceConfiguration.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
DeviceConfiguration.uniqueElements()
Returns:The unique elements contained in the configuration.
Return type:list of PeriodicTableElement
DeviceConfiguration.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
DeviceConfiguration.velocities()
Returns:The velocities of the atoms. Has the dimensionality nx3.
Return type:PhysicalQuantity of type velocity

Usage Examples

Construct a device system consisting of a hydrogen molecule connected with two chains of Lithium atoms:

# Define A,B directions of lattice
vector_a = [5.0, 0.0, 0.0]*Angstrom
vector_b = [0.0, 5.0, 0.0]*Angstrom

#  setup electrode
electrode = BulkConfiguration(
    bravais_lattice=UnitCell(vector_a, vector_b,
                             [0.0, 0.0, 9.0]*Angstrom),
    elements=[Lithium, Lithium, Lithium],
    cartesian_coordinates=[[ 2.5,  2.5,  1.5],
                           [ 2.5,  2.5,  4.5],
                           [ 2.5,  2.5,  7.5]]*Angstrom
    )

# setup  Central region
central_region = BulkConfiguration(
    bravais_lattice= UnitCell(vector_a, vector_b,
                             [0.0, 0.0, 22.0]*Angstrom),
    elements=[Lithium, Lithium, Lithium, Hydrogen, Hydrogen,
              Lithium, Lithium,  Lithium],
    cartesian_coordinates=[[  2.5,   2.5,   1.5],
                           [  2.5,   2.5,   4.5],
                           [  2.5,   2.5,   7.5],
                           [  2.5,   2.5,  10.5],
                           [  2.5,   2.5,  11.5],
                           [  2.5,   2.5,  14.5],
                           [  2.5,   2.5,  17.5],
                           [  2.5,   2.5,  20.5]]*Angstrom
     )

#setup Device configuration
device_configuration = DeviceConfiguration(
    central_region,
    [electrode, electrode]
    )

li_h2_li.py

Notes

ATK recognizes four types of atomic geometries:

A two probe setup is created by attaching two bulk electrodes to the left and the right of a central region. The properties within the electrode regions are fixed at their bulk properties, whereas the central region is described self-consistently. The device configuration must fulfill the following properties:

  • The electrodes and the central BulkConfiguration objects must have the same cell vectors in the A and B direction.
  • The C direction must be perpendicular to the A and B directions.
  • The first atoms in the central region must be positioned identical to the atoms in the left electrode when the central region AB faces are aligned with the AB faces of the electrodes. See Fig. 124 for an example.
  • Similarly, the last atoms in the central region must be positioned identical to the atoms in the right electrode. See Fig. 124 for an example.
../../../_images/device_configuration_def.png

Fig. 124 Upper panel: Example for the constituents of a device system with 2 electrodes. The constituents are Left Electrode, Central Region, Right Electrode. Lower panel: The (periodically-repeated) two-probe system. The unit cell of the central region is indicated with dashed lines while the unit cells of the electrodes are indicated by solid lines.

Vacuum basis sets (ghost atoms) can be included in the DeviceConfiguration by specifying a ghost_atoms list for the BulkConfiguration of the central and electrode regions.