Getting Started#

moldenViz lets you inspect Molden outputs either from the command line or directly in Python. This page covers the essentials so you can install the package and render your first molecule quickly.

What is a Molden file?#

A Molden file stores the atomic structure and molecular orbital information produced by many quantum-chemistry codes (GAUSSIAN, ORCA, Molpro, and others). Each file contains [Atoms] coordinates, contracted Gaussian shells in [GTO], and orbital coefficients under [MO]. moldenViz currently reads Molden files that use spherical Gaussian functions; Cartesian variants (sometimes labelled 5D/9G) raise an error during parsing. For the full format specification, refer to the official Molden format description.

Installation#

Install the core package from PyPI for parsing and tabulation:

pip install moldenViz

Or add it to a project with uv:

uv add moldenViz

The core package does not install Qt, PyVista, or other visualization dependencies. To use the interactive viewer or the moldenViz CLI, install the GUI extra:

pip install 'moldenViz[gui]'

With uv:

uv add 'moldenViz[gui]'

Or install the CLI as a standalone uv tool:

uv tool install 'moldenViz[gui]'

This makes the moldenViz command available on your PATH.

The GUI extra uses PySide6 as the supported Qt binding. The root package keeps Atom, Parser, Tabulator, and the parser result types as intentional eager imports; importing them loads NumPy. The visualization-specific AtomType model and Plotter remain lazy imports, so core-only workflows do not load or require Pydantic or the rest of the GUI stack.

Qt ownership#

The standalone CLI and moldenViz.Plotter create a PySide6 application when needed. When called from an existing Qt application, Plotter creates a free-floating window and returns immediately because the host already owns the event loop.

Use moldenViz.qt.OrbitalViewer when the visualization belongs inside an existing layout. The host must create QApplication before constructing the viewer and must keep its event loop running.

Quick CLI Preview#

Render a provided example molecule directly from the command line:

moldenViz -e benzene

This will open an interactive 3D visualization window showing the benzene molecule with its molecular orbitals:

The viewer provides controls to:

  • Navigate through different molecular orbitals

  • Adjust contour levels and opacity

  • Switch between spherical, Cartesian, and cell-local adaptive grids

  • Modify coarse-grid resolution and adaptive fine scaling

  • Export data and images

Use your own Molden file instead:

moldenViz my-calculation.molden

Get comfortable with the logging toggles early:

moldenViz -v my-calculation.molden
moldenViz -q my-calculation.molden

These flags help you audit which steps the CLI performs or keep output quiet during batch runs. See Command Line Guide for more combinations.

Quick Python Preview#

Create plots programmatically by importing the high-level API:

from moldenViz import Plotter
from moldenViz.examples import benzene

Plotter(content=benzene)

This opens an interactive PySide6 window with the orbital controls and 3D renderer side by side.

The Python API provides the same interactive capabilities as the CLI, with additional programmatic control over grid settings, tabulation, and export workflows.

Next Steps#

Once you can run the basics, move on to the topic-focused guides: