MoleculeConfiguration — Class for representing an isolated structure, i.e a molecule.


Namespace: NanoLanguage


Construction of an atomic configuration from its elements and the corresponding Cartesian coordinates. The input can be given in two ways: (i) Either by supplying the elements and Cartesian coordinates as two separate lists of the same length, or (ii) by supplying a formatted XYZ string as input.

MoleculeConfiguration Arguments


A sequence containing the elements of the configuration.

Type: A list or tuple containing objects of the type PeriodicTable, e.g. [Carbon, Oxygen].


A sequence containing a sequence of atomic coordinates for each element in the configuration,

Type: A list of 3-d coordinates given as a PhysicalQuantity of the type length, e.g. [[0,0,0], [1,1,1]]*Angstrom.


A XYZ formatted string representing the configuration. When the xyz_format argument is used, the arguments elements and cartesian_coordinates cannot be used.

Type: A description of the XYZ format can be found at


A list of atom indices to treat as ghost atoms.

Type: A list of integer numbers.

Default: None

Length of additional vacuum put around the molecule configuration when inscribed in a calculational box.

Type: Physical Quantity with unit length

Default: 0.0*Angstrom

The velocities on the atoms.

Type: A list of PhysicalQuantity with velocity units, with the same dimensions as the coordinates, or None for no velocities.

Default: None

A dict of tag data, linking tags to a list of atom indices.

Type: dict

Default: None

MoleculeConfiguration Methods

A MoleculeConfiguration object provides the following methods:

  • addTags(tags, indices): Add a set of tags to atoms matching a collection of indices.


    The set, list or tuple of tags to add to matching atoms. Single strings may also be allowed.


    The set, list or tuple of indices to match atoms against. Single integers may also be allowed. If None, then all atoms are matched.

  • calculator(): Return the calculator attached to the configuration, i.e. the calculator that will be used for both simulation and analysis.

  • cartesianCoordinates(): The Cartesian coordinates of the atoms.

  • dielectricRegions(): Get the dielectric regions for the configuration.

  • elements(): The elements of the configuration.

  • externalPotential(): Obtain the external potential present on the configuration.

  • fixedSpinDirections(): Get the fixed spin directions for the configuration.

  • ghostAtoms(): Return list of ghost_atoms.

  • indicesFromTags(tags): List the indices associated with a given collection of tags.


    A sequence of tags for which all matching indices should be extracted.

  • metallicRegions(): Get the metallic regions for the configuration.

  • nlprint(stream, name): Print a string containing an XYZ representation of the MoleculeConfiguration.


    The stream the XYZ representation should be written to.

    Type: A stream that supports strings being written to using 'write'.

    Default: sys.stdout

    The name of the configuration being printed.

    Type: String.

    Default: 'Molecule'
  • numberOfAtoms(): Returns the total number of atoms in the configuration

  • paddingLength(): Return the padding length for the molecule configuration

  • removeTags(tags, indices, purge): Remove a set of tags from atoms matching a collection of indices.


    The list, tuple or set of tags to remove from matching atoms. If None, then all tags are removed.


    The list, tuple or set of indices to match atoms against. A numpy array of integers may be provided, as well as single integers. If None, then all atoms are matched.


    When removing tags from the configuration, delete the tag completely when not associated with any atoms anymore.

  • setCalculator(calculator, initial_state, initial_spin): Attach a Calculator class to the configuration which will be used in calculations involving the configuration.


    The calculator object that should be attached to the configuration.

    Type: A calculator compatible with the configuration.

    Default: None

    The initial state to be used for this configuration.

    Type: A Configuration with an attached calculator.

    Default: None

    The initial InitialSpin object to be used for this configuration.

    Type: InitialSpin | None

    Default: None for calculators not supporting spin. Maximally spin-polarized InitialSpin for calculators supporting spin.
  • setDielectricRegions(dielectric_regions): Set the dielectric regions for the configuration.


    A sequence of SpatialRegion's.

    Type: A sequence of SpatialRegion's

  • setExternalPotential(external_potential): Set an external potential on the configuration that will be used in calculations involving the configuration.


    The external potential to apply.

    Type: AtomicShift or AtomicCompensationCharge

    Default: None
  • setMagneticField(magnetic_field): FSet 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.


    The magnetic field apply.

    Type: FixedSpin

    Default: None
  • setMetallicRegions(metallic_regions): Set the metallic regions for the configuration.


    A sequence of SpatialRegion's.

    Type: A sequence of SpatialRegion's

  • setVelocities(velocities): Function to set velocities on the configuration.


    The velocities to set on the configuration.

    Type: A sequence of velocities, with the same length as the number of elements, or None, which deletes all velocities saved on the configurartion.

    Default: None
  • symbols(): The element symbols of the configuration.

  • tags(indices): 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.


    A tuple, list, or set of indices for which tags should be counted. Numpy arrays of integers may also be provided. Single integer values may also be provided. If None, all indices are selected.

  • update(force_restart): Using the configurations set calculator, a self-consistent solution is generated.


    Force the self-consistent calculation to restart.

  • velocities(): The velocities of the atoms.

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)

Alternative way of specification

# Set up elements and positions using xyz format
h2o = MoleculeConfiguration(xyz_format=
       O   0.000 0.000 0.0
       H   0.757 0.586 0.0
       H  -0.757 0.586 0.0""")


A molecule is considered to be a system isolated in space. The ATK 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.