Name

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

Synopsis

Namespace: NanoLanguage
MoleculeConfiguration(
elements,
cartesian_coordinates,
xyz_format,
ghost_atoms,
padding_length,
velocities
)

Description

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

elements

A sequence containing the elements of the configuration.

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

cartesian_coordinates

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.

xyz_format

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 http://openbabel.org/wiki/XYZ_(format).

ghost_atoms

A list of atom indices to treat as ghost atoms.

Type: A list of integer numbers.

Default: None
padding_length

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
velocities

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

MoleculeConfiguration Methods

A MoleculeConfiguration object provides the following methods:

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

    tags

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

    indices

    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.

  • ghostAtoms(): Return list of ghost_atoms.

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

    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.

    stream

    The stream the XYZ representation should be written to.

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

    Default: sys.stdout
    name

    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.

    tags

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

    indices

    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.

    purge

    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.

    calculator

    The calculator object that should be attached to the configuration.

    Type: A calculator compatible with the configuration.

    Default: None
    initial_state

    The initial state to be used for this configuration.

    Type: A Configuration with an attached calculator.

    Default: None
    initial_spin

    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.

    dielectric_regions

    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.

    external_potential

    The external potential to apply.

    Type: AtomicShift or AtomicCompensationCharge

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

    metallic_regions

    A sequence of SpatialRegion's.

    Type: A sequence of SpatialRegion's

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

    velocities

    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 is returned.

    indices

    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.

  • uniqueElements(): Returns the unique elements contained in the configuration.

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

    force_restart

    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)

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

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.