MoleculeConfiguration

class MoleculeConfiguration(elements=None, cartesian_coordinates=None, xyz_format=None, ghost_atoms=None, padding_length=None, velocities=None, tag_data=None, fast_init=False, bonds=None, dielectric_regions=None, metallic_regions=None, partial_charges=None, improper_dihedral_indices=None)

A molecule configuration consisting elements and coordinates.

Parameters:

• elements (array of PeriodicTableElement) – The elements that should be in the configuration.

• cartesian_coordinates (PhysicalQuantity of type length) – The Cartesian coordinates of the atoms in the configuration.

• xyz_format (str) – A XYZ formatted string representing the configuration. The parameter is mutually exclusive to elements and cartesian_coordinates.

• ghost_atoms (list of ints | None) – Indices of atoms that should be treated as ghost.
  Default: No ghost atoms.

• padding_length (PhysicalQuantity of type length) – Length of additional vacuum put around the molecule configuration when inscribed in a calculation box.
  Default: 0.0*Angstrom

• tag_data (dict) – Mapping between tags and associated indices.
  Default: No tags

• velocities (PhysicalQuantity of type velocity | None) – The velocities to set on the configuration. Has the dimensionality nx3.
  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

• bonds (array with shape (n,2) or (n,5) | None) – An array with two atom indices for each bond along with the vector which periodic images this bond connects to.

• dielectric_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of dielectric regions to set.

• metallic_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of metallic regions to set.

• partial_charges (PhysicalQuantity of type charge | None) – A PhysicalQuantity array of the atomic partial charge for each atom.

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

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 that can be used for bonded potentials in ATK-ForceField.

The connectivity indices refer to the wrapped configuration.

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

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

coarseGrainDescriptors()

Returns:

The list of either elements or coarse grain particles for each element. Isotopes are returned as just their base element, UnitedAtoms and Particle are given as their specific type.

Return type:

list of type ParticleDescriptor or PeriodicTableElement

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:

MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration

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 bonds 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)

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.

fixedSpinDirections()

Returns:

The fixed spin directions for the configuration.

Return type:

FixedSpin | None

generateShifts()

The method is defined only to support the same interface for all derived classes.

No shifts by default.

Returns:

The array of shifts.

Return type:

PhysicalQuantity of type length

ghostAtoms()

Returns:

The list of ghost atoms.

Return type:

list of ints

hillFormula()

Returns:

The Hill formula for the molecule.

Return type:

str

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

indices()

Returns:

The indices of the atoms.

Return type:

list of int

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

magneticMoments()

Returns:

The magnetic moments of the atoms. Has the dimensionality nx3.

Return type:

PhysicalQuantity of type Bohr magneton.

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

nlinfo()

Returns:

The configuration information.

Return type:

dict

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

paddingLength()

Returns:

The padding length.

Return type:

PhysicalQuantity of type length

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

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.

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.

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) | None.) – A list which contains for each bond the indices of the two connected atoms.

• skip_checks (bool) – Skip argument type checking and just directly assign the value.
  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:

• calculator (Calculator | None) – The calculator object that should be attached to the configuration.

• initial_state (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration 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: InitialSpin(), except when used with a calculator of type HuckelCalculator, SlaterKosterCalculator, SemiEmpiricalCalculator, DeviceHuckelCalculator, DeviceSlaterKosterCalculator, DeviceSemiEmpiricalCalculator. In this case InitialSpin([0., 0., ...]) is used, i.e. the scaled spins for each atom are set to 0.

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.

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.

setMagneticMoments(magnetic_moments=None, skip_checks=False)

Function to set magnetic moments on the configuration.

Parameters:

• magnetic_moments (PhysicalQuantity of type Bohr magneton.) – The magnetic_moments 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.

setMetallicRegions(metallic_regions)

Set the metallic regions for the configuration.

Parameters:

metallic_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of metallic regions to set.

setMetatext(metatext)

Set a given metatext string on the object.

Parameters:

metatext (str | 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 to update and attached Forcefield calculator with the new charges.
  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)

Translate some atoms.

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.

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

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(ordered=False)

Parameters:

ordered (bool) – If the elements should be returned in ascending order by atomic number.

Returns:

The unique elements contained in the configuration.

Return type:

list of PeriodicTableElement

uniqueString()

Return a unique string representing the state of the object.

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 and construct a water molecule:

# Set up elements and positions
elm = [ Oxygen, Hydrogen, Hydrogen ]
pos = [[ 0.000, 0.000, 0.0],
       [ 0.757, 0.586, 0.0],
       [-0.757, 0.586, 0.0]]*Angstrom

# Add them to a configuration
h2o = MoleculeConfiguration(elm, pos)

molecule_configuration.py

Alternative way of specification:

# Set up elements and positions using xyz format
h2o = MoleculeConfiguration(xyz_format=
    """3

       O   0.000 0.000 0.0
       H   0.757 0.586 0.0
       H  -0.757 0.586 0.0""")

molecule_configuration_xyz.py

Notes

ATK recognizes four types of atomic geometries:

• Molecules (MoleculeConfiguration)

• Bulk (BulkConfiguration)

• One Probe (SurfaceConfiguration)

• Two Probe (DeviceConfiguration)

A molecule is considered to be a system isolated in space. The QuantumATK calculators will place the molecule within an unit cell, in order to obtain a real space grid for describing the effective potential of the system.

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.