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'
[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
[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
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'
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' or 'cartesian'
[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
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)
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
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(benzene)
No extra arguments are required—the overrides take effect as soon as the file exists.