orbitals#

Module contents:

class Orbitals(path, path_SCF0=None, path_fragments=None, path_output=None)[source]#

Bases: object

Container class that stores information about both MOs and FMOs. Orbitals can also be given the paths to adf.rkf files from related calculations to obtain more information. For example, the path to a calculation with the number of SCF cycles set to 0 populates the effective_energy_SCF0 properties of the FMOs.

Parameters:

path (str) – the path to an adf.rkf file containing information about the system of interest.
path_SCF0 (str) – the path to an adf.rkf file containing information about a calculation with 0 SCF cycles. This argument is required to populate the FMO.effective_energy_scf0 property
path_fragments (Dict[str, str]) – dictionary containing fragment name as the key and path to its adf.rkf as the value.
path_output (str) – the path to an .out file generated by ADF. This is required to read the kinetic energies for the MOs.

fmos#

the FMOs object storing the FMO objects associated with this system. Use this to select specific FMO for further analysis.

Type:: FMOs

mos#

the MOs object storing the MO objects associated with this system.

Type:: MOs

charges#

a dictionary storing formal charges of the complex and each fragment.

Type:: Dict[str,int]

property molecule: Molecule#: The molecule corresponding to the overall system.

property fragments: List[str]#: The names of the fragments defined in the calculation.

write_excel(out_file=None)[source]#

Write the data corresponding to the system into an Excel file.

Parameters:: out_file (str) – The filename of the Excel file to write.

property fmo_energy_types: List[str]#: Get the orbital energy types that are available for the provided system.

See also

This property is a redirection of FMOs.energy_types.

rename_fragment(old, new)[source]#

Rename the old fragment to new.

Parameters:

old (str) – the name of the fragment to rename.
new (str) – the name to rename the fragment to.

Raises:

ValueError – if the new name is already in use.

See also

See Orbitals.fragments to obtain a list of fragment names that are currently used.

get_mixer()[source]#

class MO(data, parent)[source]#

Bases: Orbital

Class holding data specifically for molecular orbitals.

Each MO holds the following data that can be accessed like attributes.

Variable	Type	Description
`index`	`int`	The index of this `MO` in the overal `MOs`.
`name`	`str`	The regular name of this `MO` as it would show up in ADFLevels.
`symmetry`	`str`	The irreducible representation this `MO` belongs to.
`symmetry_index`	`int`	The index of this `MO` in the overal `MOs` that belong to the same irreducible representation.
`spin`	`str`	The spin of this `MO`, either `'A'`, `'B'` or `'AB'`
`energy`	`float`	The energy of the `MO` in \(\text{kcal mol}^{-1}\).
`kinetic_energy`	`float`	The kinetic energy of the `MO` in \(\text{kcal mol}^{-1}\) if it could be read from the calculation.
`occupation`	`int`	The occupation number of this `MO`. Either `0`, `1` or `2`.
`occupied`	`bool`	Whether the `MO` has electrons in it.

fragment_character(fragment)[source]#

Calculate the total contribution of FMO objects from a specific fragment to this MO. The sum of all fragment characters is always 1 for each MO.

Parameters:: fragment (str) – the fragment to calculate the character for.
Return type:: float

Example

>>> MO.fragment_character('NH3')
0.469475215528633
>>> MO.fragment_character('BH3')
0.530524784471364

coefficient(other)[source]#

Get the coefficient of an FMO into this MO.

Parameters:: other (FMO) – the orbital that contributes to this MO.
Return type:: float

mulliken_contribution(other)[source]#

Get the Mulliken contribution of an FMO into this MO.

Parameters:: other (FMO) – the orbital that contributes to this MO.
Return type:: float

class FMO(data, parent)[source]#

Bases: Orbital

Class holding data specifically for symmetry-adapted fragment orbitals.

Each FMO holds the following data that can be accessed like attributes.

Variable	Type	Description
`index`	`int`	The index of this `FMO` in the overal `FMOs`.
`name`	`str`	The regular name of this `FMO` as it would show up in ADFLevels.
`symmetry`	`str`	The irreducible representation this `FMO` belongs to.
`symmetry_index`	`int`	The index of this `FMO` in the overal `FMOs` that belong to the same irreducible representation.
`fragment`	`str`	The name of the fragment the `FMO` belongs to.
`fragment_unique`	`str`	If fragments do not have unique names (i.e. with atomic fragments) this name will be unique for the atom.
`fragment_index`	`int`	The index of the `FMO` within the `FMOs` of the same fragment.
`spin`	`str`	The spin of this `FMO`, either `'A'`, `'B'` or `'AB'`
`energy`	`float`	The regular energy of the `FMO` in \(\text{kcal mol}^{-1}\).
`approx_effective_energy`	`float`	Approximated diagonal element of the Fock matrix belonging to the `FMO` in \(\text{kcal mol}^{-1}\). This is available even if the Fock matrix cannot be read from the calculation.
`effective_energy`	`float`	The diagonal element of the Fock matrix belonging to the `FMO` in \(\text{kcal mol}^{-1}\) if it could be read from the calculation.
`effective_energy_SCF0`	`float`	The diagonal element of the Fock matrix after 0 SCF cycles belonging to the `FMO` in \(\text{kcal mol}^{-1}\) if it could be read from the calculation.
`occupation`	`int`	The occupation number of this `FMO`. Either `0`, `1`, `2`, or a fractional value if the electronic configuration is non-aufbau.
`occupied`	`bool`	Whether the `FMO` has electrons in it.
`gross_population`	`float`	The gross Mulliken population of this `FMO`.
`gross_spin`	`float`	The gross Mulliken spin population of this `FMO`.
`molecule`	`plams.Molecule`	The molecule object containing the atoms belonging to the fragment of this `FMO`.

overlap(other)[source]#

Get the overlap between this FMO and another FMO.

Parameters:: other (FMO) – the orbital to get the overlap with.
Return type:: float

Note

The matmul operation @ redirects to this method.

fock(other)[source]#

Get the Fock matrix element between this FMO and another FMO.

Parameters:: other (FMO) – the orbital to get the Fock matrix element with.
Return type:: float

mulliken_contribution(other, normalized=False)[source]#

Get the mulliken contribution of this FMO into an MO.

Parameters:: other (MO) – the orbital to get the Mulliken contribution with.
Return type:: float

coefficient(other)[source]#

Get the coefficient of this FMO into an MO.

Parameters:: other (MO) – the orbital to get the coefficient with.
Return type:: float

make_name(spin=True, frag_name=True, relative_name=False)[source]#

Generate a name for this FMO with several options to modify it.

Parameters:

spin (bool) – whether to include spin in the name. It will be appended to the end as _{spin}.
frag_name (bool) – whether to include the fragment’s unique name in the name as {fragment_unique}(...).
relative_name (bool) – whether to use the relative name instead of the regular name.

Return type:

str

Examples

Generate the regular name of this FMO. This is the default name when printing the object.

>>> fmo.make_name()
'NH3(4A1)'

One can also use relative naming.

>>> fmo.make_name(relative_name=True)
'NH3(LUMO)'

One can also only get the name of the orbital by disabling the fragment name.

>>> fmo.make_name(frag_name=False)
'4A1'

property subspecies_relative_name: str#: The relative name of the orbital in its irreducible representation. E.g. the overall HOMO-2 could be the HOMO of its irreducible representation.

class MOs(orbitals, parent)[source]#

Bases: OrbitalSelector

Object storing all MO objects for the Orbitals objects.

class FMOs(orbitals, parent)[source]#

Bases: OrbitalSelector

Object storing all FMO objects for the given calculation.

property fragments: List[str]#: Return a list of fragment names found in the orbitals.

property energy_types: List[str]#

Object storing all FMO objects for the Orbitals objects.

Returns:: A list potentially containing energy, effective_energy and effective_energy_SCF0.

property subspecies: List[str]#: The spin species that are present in the given orbitals.

Submodules: