objects#

Module defining the main classes used to access orbital data.

Data is organised hierarchically. The top-level Orbitals objects provide access to the FMOs and MOs objects, which provide access to individual FMO and MO objects. The Orbitals objects serves as the loader of the calculation results.

Typical usage example:

orbs = Orbitals(‘path/to/adf.rkf’)

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

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

cube_file(gridsize='medium', overwrite=False, cube_file_prefix=None, preambles=[], grid_around_mol=None, gridextend=6)#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.
cube_file_prefix (str) – prefix for the cube file path.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

property degeneracy: int#: The number of Orbital objects that are degenerate with this one.

property degeneracy_index: int#: The index of this Orbital among its degenerate Orbital objects.

property degenerate: bool#: Whether the Orbital is degenerate.

property degenerate_orbitals: List[Orbital]#: Orbital objects that are very close in energy to this Orbital.

property doubly_occupied: bool#: Whether the orbital is doubly occupied.

draw(gridsize='medium', isovalue=0.03, overwrite=False, screen=None, transform=None)#

Generate and draw a cube-file for this Orbital object.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen (tcviewer.screen.Screen) – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

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

property fully_occupied: bool#: Whether the orbital is fully occupied.

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'

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

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.

property partially_occupied: bool#: Whether the orbital is not empty and not fully occupied.

property relative_name: str#: The relative name of the orbital. E.g. HOMO or HOMO-1

screenshot(output_path=None, gridsize='medium', isovalue=0.03, overwrite=False, transform=None)#

Generate a screenshot for this Orbital object.

Parameters:

output_path (str) – the path to save the image to.
gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

Return type:

str

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.draw() to draw and open a TCviewer screen showing this Orbital.

property singly_occupied: bool#: Whether the orbital is singly occupied.

property spin_match_orbs: Orbital#

property spin_total_occupation: int#

The occupation of this orbital plus its spin counterpart if it exists.

E.g. if orbital 5A_A has an occupation of 1 and orbitals 5A_B``has an occupation of 0 then both orbitals will have the ``spin_total_occupation set to 1.

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.

property symmetry_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.

property unoccupied: bool#: Whether the orbital is unoccupied.

vtk_file(gridsize='medium', overwrite=False, preambles=[], grid_around_mol=None, gridextend=6)#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

class FMOs(orbitals, parent)[source]#

Bases: OrbitalSelector

Object storing all FMO objects for the given calculation.

decode_key(key)#

Decode a key into the relevant parts. Keys are given in the following format:

{fragname}({orbname}[_{spin}][ {symmetry}])

Where [:fragment_index], [_{spin}], and [ {symmetry}] are optional.

If an FMO is desired you must begin the key with the fragment name and put the rest of the key within parentheses.

Return type:: dict
Returns:: A dictionary containing index, fragment, orbname, spin, symmetry.

Examples

Decode a key specifying an MO.

>>> MOs.decode_key('4A1')
{'orbname': '4A1'}

One can also use relative naming. Also specify alpha spin.

>>> MOs.decode_key('HOMO-2_A')
{'orbname': 'HOMO-2', 'spin': 'A'}

Decode a key for an FMO specifying the fragment, orbname and spin.

>>> FMOs.decode_key('NH3(1E1:1_B)')
{'fragment': 'NH3', 'orbname': '1E1:1_B'}

If multiple fragments have the same name (e.g. in a non-fragment analysis with atomic fragments) we can specify the fragment index with the colon.

>>> FMOs.decode_key('C:4(1P:x)')
{'fragment': 'C:4', 'orbname': '1P:x'}

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.

filter(index=None, global_index=None, symmetry=None, subspecies=None, spin=None, fragment=None, fragment_index=None, orbname=None, occupation=None)#

filter Orbital objects that match the given parameters. If any of the arguments is given as a Container we check for membership.

Parameters:

index (int) – the index of the orbital.
global_index (int) – the global index of the orbital.
symmetry (str) – the symmetry label of the orbital.
subspecies (str) – the subspecies label of the orbital.
spin (str) – the spin label of the orbital, should be one of [A, B, AB].
fragment (str) – the fragment name of the FMO.
fragment_index (int) – the index of the fragment of the FMO.
orbname (str) – the name of the orbital. Can be either the proper name or a relative name, e.g. SOMO or LUMO+5.
occupation (float) – what kind of occupation to allow. Can be a floating point number specifying the occupation or a string from one of [unoccupied, partially_occupied, fully_occupied]. Floating point numbers will be rounded to 2 decimals before comparison.

Return type:

Orbital

Returns:

The Orbital objects that match the provided arguments. If there is only one Orbital object selected, return only that one. Otherwise return a list of Orbital objects. Returns None if no matching Orbital objects were found.

Examples

Select all FMOs of a given fragment.

>>> FMOs.filter(fragment='NH3')
[NH3(1A1), NH3(2A1), NH3(3A1), ...]

Select all FMOs from the A2 irrep of the BH3 fragment.

>>> FMOs.filter(symmetry='A2', fragment='BH3')
[BH3(1A2), BH3(2A2), BH3(3A2), BH3(4A2)]

Select all MOs that are named ‘1E1:1’ or ‘1E1:2’.

>>> MOs.filter(orbname=('1E1:1', '1E1:2'))
[1E1:1, 1E1:2]

Select the HOMO of the NH3 fragment.

>>> FMOs.filter(orbname='HOMO', fragment='NH3')
NH3(3A1)

Get 1P orbitals for all carbons

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C')
[C:1(1P:x), C:1(1P:y), C:1(1P:z), C:2(1P:x), C:2(1P:y), C:2(1P:z), C:3(1P:x), C:3(1P:y), C:3(1P:z), C:4(1P:x), C:4(1P:y), C:4(1P:z)]

Get 1P orbitals for the second carbon

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C:2')
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]
>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C', fragment_index=2)
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]

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

get(key)#

Get Orbital objects based on the given key.

Parameters:: key (int) – a string describing the orbital to be selected or the integer index of the orbital.
Return type:: List[Orbital]
Returns:: A list of Orbital objects that match the given key. If there is only one return a single Orbital object.

Examples

Select the HOMO of the NH3 fragment.

>>> FMOs.get('NH3(HOMO)')
NH3(3A1)
>>> FMOs['NH3(HOMO)']
NH3(3A1)

Select a specific MO.

>>> MOs.get('6A1')
6A1
>>> MOs['6A1']
6A1

See also

filter() and decode_key().

Note

The __getitem__ method of this class redirects to this method, allowing you to use indexing notation to obtain orbitals.

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

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

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

property unrestricted: bool#: Whether the calculation was performed in an unrestricted manner.

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.

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

cube_file(gridsize='medium', overwrite=False, cube_file_prefix=None, preambles=[], grid_around_mol=None, gridextend=6)#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.
cube_file_prefix (str) – prefix for the cube file path.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

property degeneracy: int#: The number of Orbital objects that are degenerate with this one.

property degeneracy_index: int#: The index of this Orbital among its degenerate Orbital objects.

property degenerate: bool#: Whether the Orbital is degenerate.

property degenerate_orbitals: List[Orbital]#: Orbital objects that are very close in energy to this Orbital.

property doubly_occupied: bool#: Whether the orbital is doubly occupied.

draw(gridsize='medium', isovalue=0.03, overwrite=False, screen=None, transform=None)#

Generate and draw a cube-file for this Orbital object.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen (tcviewer.screen.Screen) – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

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

property fully_occupied: bool#: Whether the orbital is fully occupied.

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

property partially_occupied: bool#: Whether the orbital is not empty and not fully occupied.

property relative_name: str#: The relative name of the orbital. E.g. HOMO or HOMO-1

screenshot(output_path=None, gridsize='medium', isovalue=0.03, overwrite=False, transform=None)#

Generate a screenshot for this Orbital object.

Parameters:

output_path (str) – the path to save the image to.
gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

Return type:

str

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.draw() to draw and open a TCviewer screen showing this Orbital.

property singly_occupied: bool#: Whether the orbital is singly occupied.

property spin_match_orbs: Orbital#

property spin_total_occupation: int#

The occupation of this orbital plus its spin counterpart if it exists.

E.g. if orbital 5A_A has an occupation of 1 and orbitals 5A_B``has an occupation of 0 then both orbitals will have the ``spin_total_occupation set to 1.

property symmetry_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.

property unoccupied: bool#: Whether the orbital is unoccupied.

vtk_file(gridsize='medium', overwrite=False, preambles=[], grid_around_mol=None, gridextend=6)#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

class MOs(orbitals, parent)[source]#

Bases: OrbitalSelector

Object storing all MO objects for the Orbitals objects.

decode_key(key)#

Decode a key into the relevant parts. Keys are given in the following format:

{fragname}({orbname}[_{spin}][ {symmetry}])

Where [:fragment_index], [_{spin}], and [ {symmetry}] are optional.

If an FMO is desired you must begin the key with the fragment name and put the rest of the key within parentheses.

Return type:: dict
Returns:: A dictionary containing index, fragment, orbname, spin, symmetry.

Examples

Decode a key specifying an MO.

>>> MOs.decode_key('4A1')
{'orbname': '4A1'}

One can also use relative naming. Also specify alpha spin.

>>> MOs.decode_key('HOMO-2_A')
{'orbname': 'HOMO-2', 'spin': 'A'}

Decode a key for an FMO specifying the fragment, orbname and spin.

>>> FMOs.decode_key('NH3(1E1:1_B)')
{'fragment': 'NH3', 'orbname': '1E1:1_B'}

If multiple fragments have the same name (e.g. in a non-fragment analysis with atomic fragments) we can specify the fragment index with the colon.

>>> FMOs.decode_key('C:4(1P:x)')
{'fragment': 'C:4', 'orbname': '1P:x'}

filter(index=None, global_index=None, symmetry=None, subspecies=None, spin=None, fragment=None, fragment_index=None, orbname=None, occupation=None)#

filter Orbital objects that match the given parameters. If any of the arguments is given as a Container we check for membership.

Parameters:

index (int) – the index of the orbital.
global_index (int) – the global index of the orbital.
symmetry (str) – the symmetry label of the orbital.
subspecies (str) – the subspecies label of the orbital.
spin (str) – the spin label of the orbital, should be one of [A, B, AB].
fragment (str) – the fragment name of the FMO.
fragment_index (int) – the index of the fragment of the FMO.
orbname (str) – the name of the orbital. Can be either the proper name or a relative name, e.g. SOMO or LUMO+5.
occupation (float) – what kind of occupation to allow. Can be a floating point number specifying the occupation or a string from one of [unoccupied, partially_occupied, fully_occupied]. Floating point numbers will be rounded to 2 decimals before comparison.

Return type:

Orbital

Returns:

The Orbital objects that match the provided arguments. If there is only one Orbital object selected, return only that one. Otherwise return a list of Orbital objects. Returns None if no matching Orbital objects were found.

Examples

Select all FMOs of a given fragment.

>>> FMOs.filter(fragment='NH3')
[NH3(1A1), NH3(2A1), NH3(3A1), ...]

Select all FMOs from the A2 irrep of the BH3 fragment.

>>> FMOs.filter(symmetry='A2', fragment='BH3')
[BH3(1A2), BH3(2A2), BH3(3A2), BH3(4A2)]

Select all MOs that are named ‘1E1:1’ or ‘1E1:2’.

>>> MOs.filter(orbname=('1E1:1', '1E1:2'))
[1E1:1, 1E1:2]

Select the HOMO of the NH3 fragment.

>>> FMOs.filter(orbname='HOMO', fragment='NH3')
NH3(3A1)

Get 1P orbitals for all carbons

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C')
[C:1(1P:x), C:1(1P:y), C:1(1P:z), C:2(1P:x), C:2(1P:y), C:2(1P:z), C:3(1P:x), C:3(1P:y), C:3(1P:z), C:4(1P:x), C:4(1P:y), C:4(1P:z)]

Get 1P orbitals for the second carbon

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C:2')
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]
>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C', fragment_index=2)
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]

get(key)#

Get Orbital objects based on the given key.

Parameters:: key (int) – a string describing the orbital to be selected or the integer index of the orbital.
Return type:: List[Orbital]
Returns:: A list of Orbital objects that match the given key. If there is only one return a single Orbital object.

Examples

Select the HOMO of the NH3 fragment.

>>> FMOs.get('NH3(HOMO)')
NH3(3A1)
>>> FMOs['NH3(HOMO)']
NH3(3A1)

Select a specific MO.

>>> MOs.get('6A1')
6A1
>>> MOs['6A1']
6A1

See also

filter() and decode_key().

Note

The __getitem__ method of this class redirects to this method, allowing you to use indexing notation to obtain orbitals.

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

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

property unrestricted: bool#: Whether the calculation was performed in an unrestricted manner.

class Orbital(data, parent)[source]#

Bases: object

Main class holding orbital information for MO and FMO objects. This class is used to obtain information about the orbital, generate cube-files, and visualize orbitals.

cube_file(gridsize='medium', overwrite=False, cube_file_prefix=None, preambles=[], grid_around_mol=None, gridextend=6)[source]#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.
cube_file_prefix (str) – prefix for the cube file path.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

property degeneracy: int#: The number of Orbital objects that are degenerate with this one.

property degeneracy_index: int#: The index of this Orbital among its degenerate Orbital objects.

property degenerate: bool#: Whether the Orbital is degenerate.

property degenerate_orbitals: List[Orbital]#: Orbital objects that are very close in energy to this Orbital.

property doubly_occupied: bool#: Whether the orbital is doubly occupied.

draw(gridsize='medium', isovalue=0.03, overwrite=False, screen=None, transform=None)[source]#

Generate and draw a cube-file for this Orbital object.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen (tcviewer.screen.Screen) – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

property fully_occupied: bool#: Whether the orbital is fully occupied.

property partially_occupied: bool#: Whether the orbital is not empty and not fully occupied.

property relative_name: str#: The relative name of the orbital. E.g. HOMO or HOMO-1

screenshot(output_path=None, gridsize='medium', isovalue=0.03, overwrite=False, transform=None)[source]#

Generate a screenshot for this Orbital object.

Parameters:

output_path (str) – the path to save the image to.
gridsize (str) – the size of the grid to generate the cube-file with.
isovalue (float) – the value with which to generate the isosurface of this Orbital.
overwrite (bool) – whether to overwrite the previous calculation if found.
screen – the tcviewer.screen.Screen object to use to draw this orbital. If not given we start a new screen.
transform (tcmu.geometry.Transform) – the geometrical tranfmormation to use with this orbital.

Return type:

str

See also

Orbital.cube_file() to generate and return a cube-file for this Orbital. Orbital.draw() to draw and open a TCviewer screen showing this Orbital.

property singly_occupied: bool#: Whether the orbital is singly occupied.

property spin_match_orbs: Orbital#

property spin_total_occupation: int#

The occupation of this orbital plus its spin counterpart if it exists.

E.g. if orbital 5A_A has an occupation of 1 and orbitals 5A_B``has an occupation of 0 then both orbitals will have the ``spin_total_occupation set to 1.

property symmetry_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.

property unoccupied: bool#: Whether the orbital is unoccupied.

vtk_file(gridsize='medium', overwrite=False, preambles=[], grid_around_mol=None, gridextend=6)[source]#

Generate a cube-file for this Orbital with a certain grid-size.

Parameters:

gridsize (str) – the size of the grid to generate the cube-file with.
overwrite (bool) – whether to overwrite the previous calculation if found.

See also

Orbital.draw() to draw and open a TCviewer screen showing this Orbital. Orbital.screenshot() to generate a screenshot of this Orbital.

class OrbitalSelector(orbitals, parent)[source]#

Bases: object

Class used to select MOs or FMOs. It is responsible for decoding selection keys and filtering orbitals based on the selection key.

Parameters:

orbitals (List[Orbital]) – a list of FMOs or MOs that will be managed by this class.
parent (Orbitals) – the parent Orbitals object.

decode_key(key)[source]#

Decode a key into the relevant parts. Keys are given in the following format:

{fragname}({orbname}[_{spin}][ {symmetry}])

Where [:fragment_index], [_{spin}], and [ {symmetry}] are optional.

If an FMO is desired you must begin the key with the fragment name and put the rest of the key within parentheses.

Return type:: dict
Returns:: A dictionary containing index, fragment, orbname, spin, symmetry.

Examples

Decode a key specifying an MO.

>>> MOs.decode_key('4A1')
{'orbname': '4A1'}

One can also use relative naming. Also specify alpha spin.

>>> MOs.decode_key('HOMO-2_A')
{'orbname': 'HOMO-2', 'spin': 'A'}

Decode a key for an FMO specifying the fragment, orbname and spin.

>>> FMOs.decode_key('NH3(1E1:1_B)')
{'fragment': 'NH3', 'orbname': '1E1:1_B'}

If multiple fragments have the same name (e.g. in a non-fragment analysis with atomic fragments) we can specify the fragment index with the colon.

>>> FMOs.decode_key('C:4(1P:x)')
{'fragment': 'C:4', 'orbname': '1P:x'}

filter(index=None, global_index=None, symmetry=None, subspecies=None, spin=None, fragment=None, fragment_index=None, orbname=None, occupation=None)[source]#

filter Orbital objects that match the given parameters. If any of the arguments is given as a Container we check for membership.

Parameters:

index (int) – the index of the orbital.
global_index (int) – the global index of the orbital.
symmetry (str) – the symmetry label of the orbital.
subspecies (str) – the subspecies label of the orbital.
spin (str) – the spin label of the orbital, should be one of [A, B, AB].
fragment (str) – the fragment name of the FMO.
fragment_index (int) – the index of the fragment of the FMO.
orbname (str) – the name of the orbital. Can be either the proper name or a relative name, e.g. SOMO or LUMO+5.
occupation (float) – what kind of occupation to allow. Can be a floating point number specifying the occupation or a string from one of [unoccupied, partially_occupied, fully_occupied]. Floating point numbers will be rounded to 2 decimals before comparison.

Return type:

Orbital

Returns:

The Orbital objects that match the provided arguments. If there is only one Orbital object selected, return only that one. Otherwise return a list of Orbital objects. Returns None if no matching Orbital objects were found.

Examples

Select all FMOs of a given fragment.

>>> FMOs.filter(fragment='NH3')
[NH3(1A1), NH3(2A1), NH3(3A1), ...]

Select all FMOs from the A2 irrep of the BH3 fragment.

>>> FMOs.filter(symmetry='A2', fragment='BH3')
[BH3(1A2), BH3(2A2), BH3(3A2), BH3(4A2)]

Select all MOs that are named ‘1E1:1’ or ‘1E1:2’.

>>> MOs.filter(orbname=('1E1:1', '1E1:2'))
[1E1:1, 1E1:2]

Select the HOMO of the NH3 fragment.

>>> FMOs.filter(orbname='HOMO', fragment='NH3')
NH3(3A1)

Get 1P orbitals for all carbons

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C')
[C:1(1P:x), C:1(1P:y), C:1(1P:z), C:2(1P:x), C:2(1P:y), C:2(1P:z), C:3(1P:x), C:3(1P:y), C:3(1P:z), C:4(1P:x), C:4(1P:y), C:4(1P:z)]

Get 1P orbitals for the second carbon

>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C:2')
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]
>>> FMOs.filter(orbname=('1P:x', '1P:y', '1P:z'), fragment='C', fragment_index=2)
[C:2(1P:x), C:2(1P:y), C:2(1P:z)]

get(key)[source]#

Get Orbital objects based on the given key.

Parameters:: key (int) – a string describing the orbital to be selected or the integer index of the orbital.
Return type:: List[Orbital]
Returns:: A list of Orbital objects that match the given key. If there is only one return a single Orbital object.

Examples

Select the HOMO of the NH3 fragment.

>>> FMOs.get('NH3(HOMO)')
NH3(3A1)
>>> FMOs['NH3(HOMO)']
NH3(3A1)

Select a specific MO.

>>> MOs.get('6A1')
6A1
>>> MOs['6A1']
6A1

See also

filter() and decode_key().

Note

The __getitem__ method of this class redirects to this method, allowing you to use indexing notation to obtain orbitals.

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

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

property unrestricted: bool#: Whether the calculation was performed in an unrestricted manner.

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

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

get_mixer()[source]#

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

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.

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.