Configuration Reference#
moldenViz looks for a TOML configuration file at ~/.config/moldenViz/config.toml. Any values you set there override the built-in defaults.
Default Configuration#
The full set of built-in defaults is bundled with the package. Use it as a reference when you only want to override a handful of options:
smooth_shading = true
background_color = 'white'
show_axes = true
[grid]
min_radius = 5
max_radius_multiplier = 2
default_type = 'spherical'
[grid.spherical]
num_r_points = 100
num_theta_points = 60
num_phi_points = 120
[grid.cartesian]
num_x_points = 100
num_y_points = 100
num_z_points = 100
[grid.adaptive]
num_x_points = 20
num_y_points = 20
num_z_points = 20
scale = 5.0
[MO]
contour = 0.1
opacity = 1
color_scheme = 'bwr'
# custom_colors = ['blue', 'red'] # Uncomment to use custom colors instead of color_scheme
[molecule]
opacity = 1
[molecule.atom]
show = true
[molecule.bond]
show = true
max_length = 4
color_type = 'uniform'
color = 'grey'
radius = 0.15
Configuration Files#
Create the directory (if needed) and add a config file:
mkdir -p ~/.config/moldenViz
$EDITOR ~/.config/moldenViz/config.toml
Visualization Settings#
Control the appearance of the 3D visualization window:
background_color = 'white' # Background color for the 3D plot window
show_axes = true # Show the orientation axes
The background_color option accepts any valid matplotlib color format (color names, hex codes). Common choices include:
'white'(default)'black''lightgray''#F0F0F0'(custom hex color)
Examples:
# Use a black background
background_color = 'black'
# Or use a custom gray with hex code
background_color = '#2A2A2A'
Set show_axes = false to keep the orientation axes hidden when viewers open.
Bond Settings#
Tune how bonds are rendered:
[molecule.bond]
show = true # Show or hide bonds entirely
max_length = 4.0 # Maximum bond length to display
color_type = 'uniform' # 'uniform' or 'split'
color = 'grey' # Hex string or colour name
radius = 0.15 # Cylinder radius
Switch to per-atom colouring and thicker cylinders:
[molecule.bond]
color_type = 'split'
radius = 0.25
Grid Settings#
Control the grid used when tabulating molecular orbitals:
[grid]
min_radius = 5
max_radius_multiplier = 2
default_type = 'spherical' # 'spherical', 'cartesian', or 'adaptive'
[grid.spherical]
num_r_points = 100
num_theta_points = 60
num_phi_points = 120
[grid.cartesian]
num_x_points = 100
num_y_points = 100
num_z_points = 100
[grid.adaptive]
num_x_points = 20
num_y_points = 20
num_z_points = 20
scale = 5.0
The default_type option determines which grid type is used when the plotter is first loaded:
'spherical'(default): Uses spherical coordinates (r, theta, phi)'cartesian': Uses Cartesian coordinates (x, y, z)'adaptive': Uses a coarse Cartesian grid to locate contour-crossed cells, then tabulates a finer grid only within the union of those cells
Users can switch between grid types within the plotter interface, but this setting controls the initial grid type.
Set cartesian as the default grid type:
[grid]
default_type = 'cartesian'
Increase the resolution in the cartesian grid only:
[grid.cartesian]
num_x_points = 150
num_y_points = 150
num_z_points = 150
Adaptive Cartesian Grids#
Adaptive mode first contours every available molecular orbital on a coarse Cartesian grid. PyVista maps the generated contour faces back to the coarse cells they cross. moldenViz takes the union of those cells, refines that cell set, and tabulates one reusable fine-grid GTO cache. Changing molecular orbitals then uses the same inexpensive matrix contraction as a single grid; it does not repeat GTO tabulation.
Select adaptive mode and configure its coarse resolution and fine scale:
[grid]
default_type = 'adaptive'
[grid.adaptive]
num_x_points = 20
num_y_points = 20
num_z_points = 20
scale = 5.0
Fine spacing is approximately coarse_spacing / scale. The scale must be
at least 1.0 and may be fractional. For example, 1.5 inserts a point at
two-thirds of each selected coarse-cell edge before the cell boundary. An
anisotropic scale can be saved as a TOML array:
scale = [3.0, 5.0, 2.5] # x, y, z
The Grid Settings window accepts the same values as 5.0 or
(3.0, 5.0, 2.5). Cartesian bounds and coarse point counts remain editable
there as well.
Benefits and tradeoffs#
Benefits:
The initial coarse grid is much faster and smaller to tabulate than a dense global grid.
Fine-grid GTO memory is spent only around contour regions crossed by at least one available MO.
The fine GTO cache is shared by every MO, so changing the selected orbital does not rebuild the adaptive grid.
Per-axis scales can concentrate resolution along an anisotropic direction.
Tradeoffs:
Changing the contour value changes which cells are crossed, so it discards and rebuilds the complete all-MO adaptive grid and fine GTO cache. Changing bounds, coarse counts, or scale does the same.
A coarse grid can miss a small contour that never appears in its sampled values. Increase the coarse point counts when orbitals contain small or rapidly varying features.
Taking the union over every MO can select much of the domain for molecules with many spatially diverse orbitals, reducing the time and memory savings.
Fine-grid cell count grows approximately with the product of the three scale values. Large scales can therefore consume substantial memory.
Fractional scales produce a shorter final interval at the edge of each coarse cell when the scale is not an integer; the refined grid remains conforming, but spacing within a cell is not perfectly uniform.
Adaptive grids affect interactive contour rendering only. VTK and cube exports continue to use the Tabulator’s structured coarse grid.
Local benchmark#
The benchmark suite includes TimeInitialGridTabulation,
TimeAdaptiveGridPreparation, and TimeAdaptiveMeshRefinement in
benchmarks/grids.py. On the bundled CO
example over identical [-5, 5] Cartesian bounds, using an Apple M1 with
8 GB RAM and at least three timed repetitions, the median development
measurements were:
Stage |
Points |
Median |
GTO array |
|---|---|---|---|
Uniform initial grid (100³) |
1,000,000 |
0.254 s |
198.4 MiB |
Adaptive coarse initial grid (21³) |
9,261 |
0.00129 s |
1.84 MiB |
Full adaptive preparation (scale 5.0) |
177,787 fine points from 1,320 crossed cells |
0.155 s |
35.3 MiB |
The initial coarse GTO stage was about 198 times faster and used about 108 times less GTO storage than the uniform initial grid. After vectorizing fine-cell extraction, full adaptive preparation was about 1.6 times faster than the uniform-grid GTO calculation in this small CO case, and its retained fine GTO cache was about 5.6 times smaller. Results depend strongly on the molecule, contour, coarse resolution, scale, worker count, and hardware; run the ASV benchmarks locally before choosing production defaults.
Molecular Orbital Settings#
Adjust the appearance of orbital isosurfaces:
[mo]
contour = 0.1
opacity = 1.0
color_scheme = 'bwr' # Any matplotlib colormap
The color_scheme option accepts any valid matplotlib colormap name. Diverging colormaps work best for molecular orbitals since they show positive and negative phases. Popular choices include:
bwr(blue-white-red, default)RdBu(red-blue)seismiccoolwarm
You can also define custom two-color gradients:
[mo]
custom_colors = ['blue', 'red'] # [negative phase color, positive phase color]
Custom colors accept any matplotlib color format (names, hex codes, RGB tuples as strings). When custom_colors is specified, it takes precedence over color_scheme.
Examples with different colormaps:
# Use a red-blue diverging colormap
[mo]
color_scheme = 'RdBu'
# Or define custom colors with hex codes
[mo]
custom_colors = ['#0000FF', '#FF0000']
# Or use named colors
[mo]
custom_colors = ['cyan', 'magenta']
Atom Settings#
Drive molecule-wide and per-element rendering tweaks:
[molecule]
opacity = 0.9
[molecule.atom]
show = true
Per-atom overrides use the Atom.<atomic number> table name:
[Atom.1] # Hydrogen
color = "FFFFFF"
radius = 0.25
[Atom.6] # Carbon
color = "404040"
radius = 0.7
[Atom.8] # Oxygen
color = "FF4040"
radius = 0.6
Control the maximum bonding for a specific element (for example, iron):
[Atom.26]
max_num_bonds = 6
Worked Examples#
The snippets below combine the most common overrides so you can copy them into ~/.config/moldenViz/config.toml and adjust as needed.
Reduce bond clutter on dense organic rings while highlighting a metal centre:
[molecule]
opacity = 0.85
[molecule.bond]
max_length = 2.0
radius = 0.08
color_type = 'split'
[Atom.6] # Carbon
color = "2A2A2A"
radius = 0.7
[Atom.8] # Oxygen
color = "FF4040"
radius = 0.6
[Atom.26] # Iron centre
color = "FFB347"
radius = 1.1
max_num_bonds = 4
Tighten radius settings for a very large biomolecule to keep rendering performant:
[grid.cartesian]
num_x_points = 80
num_y_points = 80
num_z_points = 80
[mo]
contour = 0.07
opacity = 0.6
[Atom.1]
radius = 0.25
[Atom.6]
radius = 0.65
max_num_bonds = 3
[molecule.bond]
radius = 0.05
For troubleshooting tips tied to these overrides, see Troubleshooting, especially the sections on configuration validation and export errors.
Complete Example#
Combine several tweaks in one file:
smooth_shading = true
background_color = 'white'
[grid]
min_radius = 3
max_radius_multiplier = 2.5
default_type = 'spherical'
[grid.spherical]
num_r_points = 120
num_theta_points = 80
num_phi_points = 160
[grid.cartesian]
num_x_points = 120
num_y_points = 120
num_z_points = 120
[mo]
contour = 0.05
opacity = 0.8
[molecule]
opacity = 0.9
[molecule.bond]
show = true
max_length = 3.5
color_type = 'split'
radius = 0.12
[Atom.1]
color = "FFFFFF"
radius = 0.3
[Atom.6]
color = "303030"
radius = 0.75
[Atom.7]
color = "0060FF"
radius = 0.65
[Atom.8]
color = "FF3030"
radius = 0.6
Applying Custom Settings#
The CLI and API automatically load your config file:
from moldenViz import Plotter
from moldenViz.examples import benzene
Plotter(content=benzene)
No extra arguments are required—the overrides take effect as soon as the file exists.