API Reference#

This section provides detailed documentation for all modules, classes, and functions in moldenViz.

Parser Module#

The parser module provides functionality to read and parse molden files.

class Parser(source, only_molecule=False)#

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.

Attributes:

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

  • mos (list): A list of molecular orbital objects (only available when only_molecule=False).

Example Usage:

from moldenViz import Parser

# Parse from file
parser = Parser('molden.inp')

# Access atoms and molecular orbitals
atoms = parser.atoms
mos = parser.mos

# Parse only molecule structure (skip MOs)
parser = Parser('molden.inp', only_molecule=True)

Plotter Module#

The plotter module provides 3D visualization capabilities for molecules and molecular orbitals.

class Plotter(source, only_molecule=False, tabulator=None)#

Create interactive 3D plots of molecules and molecular orbitals.

Parameters:

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

  • only_molecule (bool, optional) – Only plot the molecule structure without orbitals. Default is False.

  • tabulator (Tabulator, optional) – Pre-configured tabulator object for custom grids.

Example Usage:

from moldenViz import Plotter

# Plot molecule with orbitals
Plotter('molden.inp')

# Plot only the molecule structure
Plotter('molden.inp', only_molecule=True)

# Use example molecules
from moldenViz.examples import benzene
Plotter(benzene)

Tabulator Module#

The tabulator module provides functionality to create grids and tabulate molecular orbitals on those grids.

class Tabulator(source, only_molecule=False)#

Create grids and tabulate Gaussian-type orbitals (GTOs) and molecular orbitals.

Parameters:

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

  • only_molecule (bool, optional) – Only load molecule structure. Cannot create grids when True.

Attributes:

  • grid (numpy.ndarray): The generated grid points.

  • gtos (numpy.ndarray): Tabulated Gaussian-type orbital data on the grid.

Methods:

spherical_grid(r, theta, phi)#

Create a spherical coordinate grid.

Parameters:

  • r – Radial distances.

  • theta – Polar angles.

  • phi – Azimuthal angles.

cartesian_grid(x, y, z)#

Create a Cartesian coordinate grid.

Parameters:

  • x – X coordinates.

  • y – Y coordinates.

  • z – Z coordinates.

tabulate_mos(indices=None)#

Tabulate molecular orbitals on the current grid.

Parameters:

indices (int | list[int] | range, optional) – Specific orbital indices to tabulate. If None, tabulates all.

Returns:

Tabulated molecular orbital data.

Return type:

numpy.ndarray

Example Usage:

from moldenViz import Tabulator
import numpy as np

# Create tabulator
tab = Tabulator('molden.inp')

# Create spherical grid
tab.spherical_grid(
    r=np.linspace(0, 5, 20),
    theta=np.linspace(0, np.pi, 20),
    phi=np.linspace(0, 2 * np.pi, 40)
)

# Tabulate molecular orbitals
mo_data = tab.tabulate_mos([0, 1, 2])  # First three orbitals

Examples Module#

The examples module provides pre-defined molecular structures for testing and demonstration.

Available Examples:

  • co

  • o2

  • co2

  • h2o

  • benzene

  • prismane

  • pyridine

  • furan

  • acrolein

Example Usage:

from moldenViz.examples import benzene, h2o
from moldenViz import Plotter

# Use example molecules
Plotter(benzene)
Plotter(h2o, only_molecule=True)