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
[grid]
min_radius = 5
max_radius_multiplier = 2
[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
[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
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
[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
Increase the resolution in the cartesian grid only:
[grid.cartesian]
num_x_points = 150
num_y_points = 150
num_z_points = 150
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
[grid]
min_radius = 3
max_radius_multiplier = 2.5
[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(benzene)
No extra arguments are required—the overrides take effect as soon as the file exists.