API Reference

Only the entries listed on this page are part of the supported Python API. Underscored names and modules are implementation details; see API stability.

Package exports

moldenViz exports Atom, AtomType, GaussianPrimitive, GridType, MolecularOrbital, Parser, Plotter, Shell, Tabulator, and __version__.

The public moldenViz.qt module exports OrbitalViewer for embedding and ViewerConfig for validated per-instance configuration.

The public moldenViz.testing module exports without_rendering and NullInteractor for Qt host smoke tests that do not exercise VTK rendering.

Parser data models

class moldenViz.models.Atom(label, atomic_number, position, shells)

Bases: object

A parsed atom and its basis-function shells.

Parameters:

• label (str) – Atomic label from the Molden file.

• atomic_number (int) – Atomic number of the element.

• position (NDArray[np.floating]) – Three-dimensional position in Bohr.

• shells (list[Shell]) – Electron shells associated with the atom.

label: str

atomic_number: int

position: NDArray[np.floating]

shells: list[Shell]

class moldenViz.models.GaussianPrimitive(exp, coeff)

Bases: object

A Gaussian primitive with an exponent and contraction coefficient.

Parameters:

• exp (float)

• coeff (float)

class moldenViz.models.MolecularOrbital(sym, energy, spin, occ)

Bases: object

Metadata for a parsed molecular orbital.

Parameters:

• sym (str)

• energy (float)

• spin (str)

• occ (int)

sym: str

energy: float

spin: str

occ: int

class moldenViz.models.Shell(l, gtos)

Bases: object

An electron shell containing Gaussian primitives.

Parameters:

• l (int)

• gtos (list[GaussianPrimitive])

moldenViz.parser.BOHR_PER_ANGSTROM

Number of Bohr in one Angstrom.

Visualization configuration

AtomType is a visualization-specific model. Its supported import path is moldenViz.AtomType; it is not part of the parser-focused moldenViz.models namespace.

class moldenViz.AtomType(*, name, color, radius, max_num_bonds)

Bases: BaseModel

Validated visualization properties for an atomic element.

Parameters:

• name (str)

• color (str)

• radius (float)

• max_num_bonds (int)

name: str

color: str

radius: float

max_num_bonds: int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Parser

class moldenViz.parser.Parser(*, filename=None, content=None, only_molecule=False, mo_order='energy')

Bases: object

Parser for molden files.

Parameters:

• filename (str | os.PathLike[str] | None, optional) – Path to the Molden file. Exactly one of filename and content must be provided.

• content (str | None, optional) – Complete contents of a Molden file. Exactly one of filename and content must be provided.

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

• mo_order ({'energy', 'file'}, optional) – Order molecular orbitals by ascending energy or preserve their order in the Molden file. Default is 'energy'.

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 filename is not a string or path-like object, or content is not a string.

• ValueError – If exactly one input is not provided, or if mo_order is not 'energy' or 'file'.

Tabulator

class moldenViz.tabulator.Tabulator(*, filename=None, content=None, only_molecule=False, max_workers=None)

Bases: object

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

Parameters:

• filename (str | os.PathLike[str] | None, optional) – Path to the Molden file. Exactly one of filename and content must be provided.

• content (str | None, optional) – Complete contents of a Molden file. Exactly one of filename and content must be provided.

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

• max_workers (int | None, optional) – Maximum concurrent workers for GTO tabulation. None uses up to four workers through 125,000 grid points and switches to sequential work for larger grids. Explicit values override the grid-size policy but remain capped at four and further bounded by the CPU and atom counts. Set to 1 for sequential tabulation. Default is None.

Variables:

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

• gtos (NDArray[np.floating]) – The cached Gaussian-type orbitals (GTOs) on the grid. Access raises RuntimeError when no cache is available.

• has_gtos (bool) – Whether GTO values are currently cached.

• max_workers (int) – Effective GTO worker count after applying the configured policy.

property grid: NDArray[floating]

The 2D array of Cartesian grid points used for tabulation.

set_grid(new_grid)

Set an arbitrary Cartesian point grid after validating its structure.

Parameters:

new_grid (Any) – Candidate 2D array whose rows are XYZ coordinates.

Raises:

• TypeError – If new_grid is not a NumPy array.

• ValueError – If the array does not have three columns or contains no rows.

Return type:

None

property has_gtos: bool

Whether Gaussian-type orbitals are currently cached.

property gtos: NDArray[floating]

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

Raises:

RuntimeError – If GTOs have not been tabulated or the cache was cleared.

clear_gtos()

Release any cached Gaussian-type orbital values.

Return type:

None

property max_workers: int

Configured GTO worker ceiling after CPU and atom limits.

set_gtos(gtos)

Install GTO values produced for the current grid.

Parameters:

gtos (NDArray[np.floating]) – Two-dimensional GTO values with one row per grid point.

Raises:

ValueError – If the values are not two-dimensional or do not match the grid.

Return type:

None

property atoms: list[Atom]

Atoms parsed from the Molden input.

property molecular_orbitals: list[MolecularOrbital]

Molecular-orbital metadata parsed from the Molden input.

property grid_type: GridType

The coordinate grid type.

property grid_dimensions: tuple[int, int, int]

The three-dimensional grid shape used by structured exporters.

property grid_axes: tuple[NDArray[floating], ...] | None

The original coordinate axes, if the grid was built from axes.

static spherical_to_cartesian(r, theta, phi)

Convert spherical coordinates to Cartesian coordinates.

Returns:

Tuple containing the Cartesian coordinates (x, y, z).

Return type:

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

Parameters:

• r (NDArray[floating])

• theta (NDArray[floating])

• phi (NDArray[floating])

static cartesian_to_spherical(x, y, z)

Convert Cartesian coordinates to spherical coordinates.

Returns:

Tuple containing spherical coordinates (r, theta, phi).

Return type:

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

Parameters:

• x (NDArray[floating])

• y (NDArray[floating])

• z (NDArray[floating])

cartesian_grid(x, y, z, *, tabulate_gtos=True)

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)

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.

compute_gtos(grid, *, point_chunk_size=32768)

Compute GTO values for an explicit Cartesian grid.

This method does not read or update the Tabulator’s current grid or GTO cache, so it is safe to use for background work on a grid snapshot. By default, each worker evaluates at most 32,768 points at a time so temporary arrays do not grow with the full grid.

Parameters:

• grid (NDArray[np.floating]) – Cartesian grid points with shape (n_points, 3).

• point_chunk_size (int or None, optional) – Maximum number of points evaluated by one worker task. None evaluates each atom on the full grid and is mainly useful for performance comparisons. Defaults to 32,768.

Returns:

Array containing the tabulated GTO data.

Return type:

NDArray[np.floating]

Raises:

• RuntimeError – If the only_molecule flag is set to True.

• ValueError – If point_chunk_size is not a positive integer or None.

tabulate_gtos(*, point_chunk_size=32768)

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

Parameters:

point_chunk_size (int or None, optional) – Maximum number of points evaluated by one worker task. None evaluates each atom on the full grid. Defaults to 32,768.

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, *, gtos=None)

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.

• gtos (NDArray[np.floating] or None, optional) – Explicit GTO values to contract instead of the current grid cache. This does not modify the current grid or cached GTOs.

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)

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)

Write orbital data to a VTK structured-grid dataset.

Parameters:

• destination (Path)

• mo_index (int | None)

Return type:

None

export_cube(destination, mo_index)

Write a single molecular orbital to a Gaussian cube file.

Parameters:

• destination (Path)

• mo_index (int)

Return type:

None

class moldenViz.tabulator.GridType(*values)

Bases: Enum

Grid types allowed.

SPHERICAL = 'spherical'

CARTESIAN = 'cartesian'

UNKNOWN = 'unknown'

Plotter

class moldenViz.plotter.Plotter(*args, **kwargs)

Bases: QMainWindow

Free-floating Qt window containing an OrbitalViewer.

If no QApplication exists, Plotter creates one and blocks in its event loop until the window closes. Inside an existing Qt application, construction returns immediately and the host keeps ownership of the loop.

Parameters:

• filename (str | os.PathLike[str] | None, optional) – Path to the Molden file. Required when neither content nor tabulator is provided.

• content (str | None, optional) – Complete contents of a Molden file. Required when neither filename nor tabulator is provided.

• only_molecule (bool, optional) – Skip molecular-orbital parsing and controls.

• tabulator (Tabulator, optional) – Existing structured-grid tabulator with cached GTO values.

• config (Config | MainConfig | Mapping, optional) – Per-window configuration overrides.

• parent (QWidget, optional) – Optional Qt parent for the free-floating window.

property tabulator: Tabulator

Tabulator used by the contained viewer.

show_orbital(index)

Delegate orbital selection to the contained viewer.

Parameters:

index (int)

Return type:

None

plot_orbital(index)

Compatibility alias for show_orbital().

Parameters:

index (int)

Return type:

None

wait_for_gtos(timeout=None)

Wait for background GTO tabulation.

Parameters:

timeout (float | None)

Return type:

None

toggle_molecule()

Toggle all molecule actors.

Return type:

None

toggle_atoms()

Toggle atom actors.

Return type:

None

toggle_bonds()

Toggle bond actors.

Return type:

None

is_molecule_visible()

Return whether molecule actors are visible.

Returns:

Whether at least one molecule actor is visible.

Return type:

bool

are_atoms_visible()

Return whether atom actors are visible.

Returns:

Whether at least one atom actor is visible.

Return type:

bool

are_bonds_visible()

Return whether bond actors are visible.

Returns:

Whether at least one bond actor is visible.

Return type:

bool

closeEvent(event)

Close VTK resources before the top-level Qt window is destroyed.

Parameters:

event (PySide6.QtGui.QCloseEvent)

Return type:

None

OrbitalViewer

class moldenViz.qt.OrbitalViewer(*args, **kwargs)

Bases: QWidget, _PlotterRendering

Embeddable Qt widget for molecules and molecular orbitals.

The host must create and run QApplication. Constructing this widget never starts an event loop or shows a top-level window.

Parameters:

• filename (str | os.PathLike[str] | None, optional) – Path to the Molden file.

• content (str | None, optional) – Complete contents of a Molden file.

• only_molecule (bool, optional) – Skip molecular-orbital parsing and controls.

• tabulator (Tabulator, optional) – Existing structured-grid tabulator with cached GTO values.

• config (Config | MainConfig | Mapping, optional) – Per-viewer configuration overrides.

• show_controls (bool, optional) – Show the built-in control panel. Disable it when the host supplies its own dashboard.

• parent (QWidget, optional) – Parent widget supplied by the host application.

loading_changed

alias of bool

orbital_changed

alias of int

error_occurred

alias of str

export_requested

alias of str

property config: Config

Per-instance visualization configuration.

property gtos_ready: bool

Whether orbital data can be rendered.

property axes_visible: bool

Whether the orientation axes are visible.

set_axes_visible(*, visible)

Show or hide the orientation axes.

Parameters:

visible (bool) – Whether the orientation axes should be visible.

Return type:

None

reset_camera()

Restore the default isometric view and fit all visible actors.

Return type:

None

showEvent(event)

Watch for screen changes once the native window exists.

Parameters:

event (QShowEvent)

Return type:

None

eventFilter(watched, event)

Repaint native widgets after a device-pixel-ratio change.

Returns:

Whether the event should stop propagating.

Return type:

bool

Parameters:

• watched (PySide6.QtCore.QObject)

• event (PySide6.QtCore.QEvent)

property controls_visible: bool

Whether the built-in control panel is enabled for display.

property current_orbital_index: int

Currently displayed orbital index, or -1 when cleared.

property has_export_handler: bool

Whether a host has connected a receiver to export_requested.

property molecular_orbitals: tuple[MolecularOrbital, ...]

Molecular orbitals available to host-provided controllers.

set_input(*, filename=None, content=None, tabulator=None, only_molecule=None)

Load or replace the Molden input displayed by this widget.

Parameters:

• filename (str | PathLike[str] | None)

• content (str | None)

• tabulator (Tabulator | None)

• only_molecule (bool | None)

Return type:

None

show_orbital(index)

Show one orbital, or clear it when index is -1.

Parameters:

index (int)

Return type:

None

set_controls_visible(*, visible)

Show or hide the built-in control panel.

Parameters:

visible (bool)

Return type:

None

update_grid(axes, grid_type, *, mode=None, adaptive_scale=None)

Replace the structured grid and schedule fresh GTO tabulation.

Parameters:

• axes (tuple[NDArray[np.floating], NDArray[np.floating], NDArray[np.floating]])

• grid_type (GridType)

• mode (str | None)

• adaptive_scale (AdaptiveScale | None)

Return type:

None

set_spherical_grid(*, radius, radial_points, theta_points, phi_points)

Build and apply a spherical grid from dashboard-friendly values.

Parameters:

• radius (float)

• radial_points (int)

• theta_points (int)

• phi_points (int)

Return type:

None

set_cartesian_grid(*, x_range, y_range, z_range, x_points, y_points, z_points)

Build and apply a Cartesian grid from bounds and point counts.

Parameters:

• x_range (tuple[float, float])

• y_range (tuple[float, float])

• z_range (tuple[float, float])

• x_points (int)

• y_points (int)

• z_points (int)

Return type:

None

set_adaptive_grid(*, x_range, y_range, z_range, x_points, y_points, z_points, scale)

Build and apply an adaptive Cartesian grid from explicit values.

Parameters:

• x_range (tuple[float, float])

• y_range (tuple[float, float])

• z_range (tuple[float, float])

• x_points (int)

• y_points (int)

• z_points (int)

• scale (float | tuple[float, float, float])

Return type:

None

apply_appearance(*, contour, mo_opacity, color_scheme, custom_colors, molecule_opacity, show_atoms, show_bonds, bond_max_length, bond_radius, bond_color_type, bond_color, background_color)

Apply validated appearance settings to this viewer instance.

Parameters:

• contour (float)

• mo_opacity (float)

• color_scheme (str)

• custom_colors (list[str] | None)

• molecule_opacity (float)

• show_atoms (bool)

• show_bonds (bool)

• bond_max_length (float)

• bond_radius (float)

• bond_color_type (str)

• bond_color (str)

• background_color (str)

Return type:

None

update_appearance(*, contour=None, mo_opacity=None, color_scheme=None, custom_colors=None, molecule_opacity=None, show_atoms=None, show_bonds=None, bond_max_length=None, bond_radius=None, bond_color_type=None, bond_color=None, background_color=None)

Apply a partial appearance update for host-provided controllers.

Parameters:

• contour (float | None)

• mo_opacity (float | None)

• color_scheme (str | None)

• custom_colors (list[str] | None)

• molecule_opacity (float | None)

• show_atoms (bool | None)

• show_bonds (bool | None)

• bond_max_length (float | None)

• bond_radius (float | None)

• bond_color_type (str | None)

• bond_color (str | None)

• background_color (str | None)

Return type:

None

set_background_color(color)

Set this viewer’s render background color.

Parameters:

color (str)

Return type:

None

export_data(path, *, file_format, scope='current')

Export orbital data to an explicit destination without dialogs.

Parameters:

• path (str | Path)

• file_format (str)

• scope (str)

Return type:

None

export_image(path, *, file_format, transparent=False)

Export the current render to an explicit destination without dialogs.

Parameters:

• path (str | Path)

• file_format (str)

• transparent (bool)

Return type:

None

save_settings()

Persist this viewer’s current settings to the user TOML file.

Return type:

None

wait_for_gtos(timeout=None)

Block until background GTO tabulation finishes.

Parameters:

timeout (float | None)

Return type:

None

wait_for_adaptive_grid(timeout=None)

Block until adaptive-grid tabulation finishes.

Parameters:

timeout (float | None)

Return type:

None

report_error(title, exc)

Log an exception and notify the host without opening a dialog.

Parameters:

• title (str)

• exc (Exception)

Return type:

None

close()

Close the viewer and explicitly release its VTK render window.

Returns:

Whether Qt accepted the close request.

Return type:

bool

closeEvent(event)

Release rendering resources during parent-driven teardown.

Parameters:

event (QCloseEvent)

Return type:

None

moldenViz.qt.ViewerConfig

alias of MainConfig

Testing Qt hosts

moldenViz.testing.without_rendering()

Use NullInteractor for viewers constructed in this context.

This allows Qt host pages to be smoke-tested under the offscreen Qt platform without asking VTK to create an unavailable OpenGL context.

Yields:

None – Control while the non-rendering interactor override is active.

Return type:

Iterator[None]

class moldenViz.testing.NullInteractor(*args, **kwargs)

Bases: QWidget

Non-rendering QtInteractor replacement for UI smoke tests.

This widget records scene operations but creates no VTK render window or OpenGL context. It is intended only for layout, lifecycle, and controller tests performed inside without_rendering().

Parameters:

• parent (QWidget | None)

• _kwargs (object)

set_background(color)

Record the requested background color.

Parameters:

color (str)

Return type:

None

show_axes()

Record that the orientation axes are visible.

Return type:

None

hide_axes()

Record that the orientation axes are hidden.

Return type:

None

add_mesh(_mesh, **_kwargs)

Record a mesh addition and return a minimal actor stand-in.

Returns:

Actor recording later visibility and opacity changes.

Return type:

_NullActor

Parameters:

• _mesh (object)

• _kwargs (object)

remove_actor(actor)

Remove a previously recorded actor.

Parameters:

actor (_NullActor)

Return type:

None

update()

Accept a render update without drawing.

Return type:

None

close()

Record explicit render-window cleanup.

Return type:

None

save_graphic(path)

Record a requested vector export destination.

Parameters:

path (str | Path)

Return type:

None

screenshot(path, *, transparent_background)

Record a requested raster export destination.

Parameters:

• path (str | Path)

• transparent_background (bool)

Return type:

None

reset_camera()

Record a camera-reset request.

Return type:

None

view_isometric()

Record a default-view request.

Return type:

None