API Reference#

The entries below are generated directly from the source docstrings so class and method signatures stay in sync with the codebase.

Parser#

class moldenViz.parser.Parser(source, only_molecule=False)[source]#

Bases: object

Parser for molden files.

Parameters:

  • source (str | list[str]) – The path to the molden file, or the lines from the file.

  • only_molecule (bool, optional) – Only parse the atoms and skip molecular orbitals. Default is False.

Variables:

  • atoms (list[_Atom]) – A list of Atom objects containing the label, atomic number, and position for each atom.

  • shells (list[_Shell]) – A list of _Shell objects containing the atom, angular momentum quantum number (l), and GTOs for each shell.

  • mos (list[_MolecularOrbital]) – A list of MolecularOrbital objects containing the symmetry, energy, and coefficients for each MO.

  • mo_coeffs (NDArray[np.floating]) – A 2D array containing all molecular orbital coefficients, where each row represents the coefficients for one molecular orbital.

Raises:

TypeError – If the source is not a valid molden file path, or molden file lines.

ANGSTROM_TO_BOHR = 1.8897259886#
check_molden_format()[source]#

Check if the provided molden lines conform to the expected format.

Raises:

ValueError – If the molden lines do not contain the required sections or if they are in an unsupported format.

Return type:

None

divide_molden_lines()[source]#

Divide the molden lines into sections for atoms, GTOs, and MOs.

Returns:

Indices of the ‘[Atoms]’, ‘[GTO]’, and ‘[MO]’ lines.

Return type:

tuple[int, int, int]

Raises:

ValueError – If the molden lines do not contain the required sections.

get_atoms()[source]#

Parse the atoms from the molden file.

Returns:

A list of Atom objects containing the label, atomic number, and position for each atom.

Return type:

list[_Atom]

get_shells()[source]#

Parse the Gaussian-type orbitals (GTOs) from the molden file.

Returns:

A list of _Shell objects containing the atom, angular momentum quantum number (l), and GTOs for each shell.

Return type:

list[_Shell]

Raises:

ValueError – If the shell label is not supported or if the GTOs are not formatted correctly in the molden file.

get_mos(sort=True)[source]#

Parse the molecular orbitals (MOs) from the molden file.

Parameters:

sort (bool, optional) – If true (default), returns the MOs sorted by energy. If false, returns the MOs in the order given in the molden file.

Returns:

Two-item tuple: the first element contains the parsed molecular orbitals (symmetry, energy, spin, occupation), and the second is a 2D NumPy array of orbital coefficients shaped (num_mos, num_basis_functions).

Return type:

tuple[list[_MolecularOrbital], NDArray[np.floating]]

Tabulator#

class moldenViz.tabulator.Tabulator(source, only_molecule=False)[source]#

Bases: object

Extends Parser, create grids and tabulates Gaussian-type orbitals (GTOs) from Molden files.

Parameters:

  • source (str | list[str]) – The path to the molden file, or the lines from the file.

  • only_molecule (bool, optional) – Only parse the atoms and skip molecular orbitals. Default is False.

Variables:

  • grid (NDArray[np.floating]) – The grid points where GTOs and MOs are tabulated.

  • gtos (NDArray[np.floating]) – The tabulated Gaussian-type orbitals (GTOs) on the grid.

property grid: ndarray[tuple[Any, ...], dtype[floating]]#

Return the 2D array of Cartesian grid points used for tabulation.

property gtos: ndarray[tuple[Any, ...], dtype[floating]]#

Get the tabulated Gaussian-type orbitals (GTOs) on the grid.

cartesian_grid(x, y, z, tabulate_gtos=True)[source]#

Create cartesian grid from x, y, z arrays and tabulate GTOs.

Parameters:

  • x (NDArray[np.floating]) – 1D array of x coordinates.

  • y (NDArray[np.floating]) – 1D array of y coordinates.

  • z (NDArray[np.floating]) – 1D array of z coordinates.

  • tabulate_gtos (bool, optional) – Whether to tabulate Gaussian-type orbitals (GTOs) after creating the grid. Defaults to True.

Return type:

None

spherical_grid(r, theta, phi, tabulate_gtos=True)[source]#

Create spherical grid from r, theta, phi arrays and tabulate GTOs.

Parameters:

  • r (NDArray[np.floating]) – 1D array of radial coordinates.

  • theta (NDArray[np.floating]) – 1D array of polar angles (radians).

  • phi (NDArray[np.floating]) – 1D array of azimuthal angles (radians).

  • tabulate_gtos (bool, optional) – Whether to tabulate Gaussian-type orbitals (GTOs) after creating the grid. Defaults to True.

Return type:

None

Notes

Grid points are converted to Cartesian coordinates.

tabulate_gtos()[source]#

Tabulate Gaussian-type orbitals (GTOs) on the current grid.

Returns:

Array containing the tabulated GTOs data.

Return type:

NDArray[np.floating]

Raises:

RuntimeError – If the grid is not defined before tabulating GTOs, or if the only_molecule flag is set to True.

tabulate_mos(mo_inds=None)[source]#

Tabulate molecular orbitals (MOs) on the current grid.

Parameters:

mo_inds (int, array-like, or None, optional) – Indices of the MOs to tabulate. If None, all MOs are tabulated.

Returns:

Array containing the tabulated MOs data.

If an integer is provided, it will tabulate only that MO. If an array-like is provided, it will tabulate the MOs at those indices.

Return type:

NDArray[np.floating]

Raises:

  • RuntimeError – If the grid is not defined before tabulating MOs.

  • RuntimeError – If GTOs are not tabulated before tabulating MOs.

  • ValueError – If provided mo_inds is invalid.

export(path, *, mo_index=None)[source]#

Export the current grid data to a VTK-based or cube file.

Parameters:

  • path (str | Path) – Target path for the exported data. The file extension should match the desired exporter (.vtk for VTK, .cube for cube files).

  • mo_index (int | None, optional) – Molecular orbital index to export. The parameter is optional for VTK exports. If none is given then all the molecular orbitals will be exported. Required for cube exports.

Raises:

  • RuntimeError – If a grid has not been generated or only the molecular geometry was parsed.

  • ValueError – If an unsupported filetype is provided, or if mo_index is missing when exporting cube files.

Return type:

None

export_vtk(destination, mo_index=None)[source]#

Write orbital data to a VTK multiblock dataset.

Parameters:

  • destination (Path)

  • mo_index (int | None)

Return type:

None

export_cube(destination, mo_index)[source]#

Write a single molecular orbital to a Gaussian cube file.

Parameters:

  • destination (Path)

  • mo_index (int)

Return type:

None

static check_bounds(x)[source]#

Ensure that x is within the open interval (-1, 1) for scipy’s associated Legendre polynomial.

Parameters:

x (np.ndarray) – Input array of x values.

Returns:

Clipped array with values in the open interval (-1, 1).

Return type:

np.ndarray

Plotter#