Skip to content

Visualization API

Plotting functions and interactive dashboards for visualizing results.

Static Plots

Publication-quality plots using Plotly.

carriercapture.visualization.static

Static plotting functions using Plotly.

Provides publication-quality plots for: - Potential energy surfaces with wavefunctions - Capture coefficient (Arrhenius plots) - Eigenvalue spectra - Configuration coordinate diagrams

plot_potential(potential, show_wavefunctions=True, wf_scale=0.02, wf_sampling=5, show_data=True, color='blue', title=None, fig=None, show_eigenvalues=True, max_wf_to_plot=None)

Plot potential energy surface with optional wavefunctions.

Parameters:

Name Type Description Default
potential Potential

Potential object with Q, E, and optionally eigenvalues/eigenvectors

 required
show_wavefunctions bool

Whether to plot wavefunction envelopes

 True
wf_scale float

Scaling factor for wavefunction amplitude

 0.02
wf_sampling int

Plot every Nth wavefunction

 5
show_data bool

Whether to show original data points

 True
color str

Color for the potential curve

 "blue"
title str

Plot title (defaults to potential name)

 None
fig Figure

Existing figure to add to

 None
show_eigenvalues bool

Whether to show eigenvalue lines

 True
max_wf_to_plot int

Maximum number of wavefunctions to plot

 None

Returns:

Type Description
Figure

Plotly figure object

Examples:

>>> fig = plot_potential(pot, show_wavefunctions=True)
>>> fig.show()
>>> fig.write_html("potential.html")

plot_capture_coefficient(cc, color='red', title=None, fig=None, show_temps=True)

Plot capture coefficient as Arrhenius plot (log C vs 1000/T).

Parameters:

Name Type Description Default
cc ConfigCoordinate

ConfigCoordinate object with capture_coefficient and temperature

 required
color str

Color for the line

 "red"
title str

Plot title

 None
fig Figure

Existing figure to add to

 None
show_temps bool

Whether to show temperature labels on secondary x-axis

 True

Returns:

Type Description
Figure

Plotly figure object

Examples:

>>> fig = plot_capture_coefficient(cc)
>>> fig.show()

plot_eigenvalue_spectrum(potential, max_levels=30, color='blue', title=None)

Plot eigenvalue spectrum as energy levels.

Parameters:

Name Type Description Default
potential Potential

Potential object with eigenvalues

 required
max_levels int

Maximum number of levels to plot

 30
color str

Color for the levels

 "blue"
title str

Plot title

 None

Returns:

Type Description
Figure

Plotly figure object

Examples:

>>> fig = plot_eigenvalue_spectrum(pot, max_levels=20)
>>> fig.show()

plot_configuration_coordinate(pot_initial, pot_final, Q0=None, title=None, show_wavefunctions=False)

Plot configuration coordinate diagram with both potentials.

Parameters:

Name Type Description Default
pot_initial Potential

Initial state potential

 required
pot_final Potential

Final state potential

 required
Q0 float

Q coordinate for overlap calculation (shown as vertical line)

 None
title str

Plot title

 None
show_wavefunctions bool

Whether to show wavefunctions

 False

Returns:

Type Description
Figure

Plotly figure object

Examples:

>>> fig = plot_configuration_coordinate(pot_i, pot_f, Q0=10.0)
>>> fig.show()

plot_overlap_matrix(cc, title=None, log_scale=True)

Plot wavefunction overlap matrix as heatmap.

Parameters:

Name Type Description Default
cc ConfigCoordinate

ConfigCoordinate object with overlap_matrix

 required
title str

Plot title

 None
log_scale bool

Whether to use log scale for colors

 True

Returns:

Type Description
Figure

Plotly figure object

Examples:

>>> fig = plot_overlap_matrix(cc)
>>> fig.show()

Interactive Dashboard

Web-based interactive dashboard using Dash.

Optional Dependency

The dashboard requires pip install carriercapture[viz]

carriercapture.visualization.interactive

Interactive Dash application for CarrierCapture visualization.

Provides a web-based dashboard for: - Loading and visualizing potential energy surfaces - Interactive parameter adjustment and real-time fitting - Parameter scanning with 2D heatmap visualization - Multi-potential comparison mode - Capture coefficient calculation - Export functionality (JSON, HDF5, PNG)

create_app(debug=False)

Create and configure the Dash application.

Parameters:

Name Type Description Default
debug bool

Whether to run in debug mode

 False

Returns:

Type Description
Dash

Configured Dash app

Examples:

>>> app = create_app()
>>> app.run(port=8050)

create_potential_tab(theme)

Create the potential viewer tab layout.

create_scan_tab(theme)

Create the parameter scan tab layout.

create_comparison_tab(theme)

Create the multi-potential comparison tab layout.

create_capture_tab(theme)

Create the capture calculation tab layout.

register_callbacks(app)

Register all Dash callbacks.

register_potential_callbacks(app)

Register callbacks for potential viewer tab.

register_scan_callbacks(app)

Register callbacks for parameter scan tab.

register_comparison_callbacks(app)

Register callbacks for comparison tab.

register_capture_callbacks(app)

Register callbacks for capture calculation tab.

serialize_potential(pot)

Serialize Potential to JSON-compatible dict.

deserialize_potential(data)

Deserialize Potential from dict.

serialize_scan_results(results)

Serialize ScanResult to dict.

deserialize_scan_results(data)

Deserialize ScanResult from dict.

create_potential_figure(pot, display_options, wf_scale)

Create figure for potential plot.

create_scan_figure(results, plot_type, log_scale)

Create figure for scan results.

create_comparison_figure(potentials)

Create figure for potential comparison.

run_server(port=8050, debug=False, host='127.0.0.1')

Run the Dash server.

Parameters:

Name Type Description Default
port int

Port to run server on

 8050
debug bool

Whether to run in debug mode

 False
host str

Host address

 "127.0.0.1"

Examples:

>>> run_server(port=8050)

Themes

Styling and color schemes for plots.

carriercapture.visualization.themes

Theming and styling utilities for CarrierCapture visualizations.

Provides consistent color schemes, layouts, and styling for publication-quality figures.

get_default_layout(title='', xaxis_title='', yaxis_title='', width=900, height=600, **kwargs)

Get default layout configuration for CarrierCapture plots.

Parameters:

Name Type Description Default
title str

Plot title

 ''
xaxis_title str

X-axis label

 ''
yaxis_title str

Y-axis label

 ''
width int

Figure width in pixels

 900
height int

Figure height in pixels

 600
**kwargs

Additional layout parameters to override defaults

 {}

Returns:

Type Description
dict

Layout configuration dictionary

Examples:

>>> layout = get_default_layout(title="My Plot", xaxis_title="X", yaxis_title="Y")
>>> fig = go.Figure(layout=layout)

apply_publication_style(fig)

Apply publication-quality styling to a Plotly figure.

Parameters:

Name Type Description Default
fig Figure

Plotly figure to style

 required

Returns:

Type Description
Figure

Styled figure

Examples:

>>> fig = go.Figure()
>>> fig = apply_publication_style(fig)

get_colorscale(name='viridis')

Get a colorscale for heatmaps and contour plots.

Parameters:

Name Type Description Default
name str

Colorscale name: "viridis", "plasma", "inferno", "magma", "cividis"

 "viridis"

Returns:

Type Description
list

Colorscale specification

Examples:

>>> colorscale = get_colorscale("plasma")

format_scientific(value, precision=2)

Format a number in scientific notation for display.

Parameters:

Name Type Description Default
value float

Number to format

 required
precision int

Number of decimal places

 2

Returns:

Type Description
str

Formatted string

Examples:

>>> format_scientific(1.23e-10, precision=2)
'1.23×10⁻¹⁰'

create_dash_theme()

Create theme configuration for Dash applications.

Returns:

Type Description
dict

Dash theme configuration

Examples:

>>> theme = create_dash_theme()
>>> app.layout = html.Div(style=theme["container"])

Usage Examples

Plot Potential Energy Surface

from carriercapture.visualization import plot_potential
from carriercapture.core import Potential

# Create and solve potential
pot = Potential.from_harmonic(hw=0.008, Q0=0.0, E0=0.0)
pot.solve(nev=60)

# Plot with wavefunctions
fig = plot_potential(
    pot,
    title="Harmonic Potential",
    show_wavefunctions=True,
    n_states=10,  # Show first 10 states
    show_eigenvalues=True
)

# Display
fig.show()

# Save
fig.write_html('potential.html')
fig.write_image('potential.png', width=800, height=600)

Plot Capture Coefficient

from carriercapture.visualization import plot_capture_coefficient

# After calculating capture coefficient
cc = ConfigCoordinate(...)
cc.calculate_capture_coefficient(...)

# Arrhenius plot
fig = plot_capture_coefficient(
    cc,
    title="Capture Coefficient vs Temperature",
    arrhenius=True,  # Log scale, 1000/T x-axis
    show_activation_energy=True
)

fig.show()

Configuration Coordinate Diagram

from carriercapture.visualization import plot_configuration_coordinate

# Plot CC diagram with both potentials
fig = plot_configuration_coordinate(
    pot_initial,
    pot_final,
    show_crossing=True,
    show_wavefunctions=True
)

fig.show()

Eigenvalue Spectrum

from carriercapture.visualization import plot_eigenvalue_spectrum

fig = plot_eigenvalue_spectrum(
    pot,
    title="Vibrational Energy Levels",
    max_states=20
)

fig.show()

Overlap Matrix Heatmap

from carriercapture.visualization import plot_overlap_matrix

# After calculating overlaps
cc = ConfigCoordinate(...)
cc.calculate_overlap(...)

fig = plot_overlap_matrix(
    cc,
    title="Franck-Condon Overlaps",
    log_scale=True  # Use log scale for small values
)

fig.show()

Parameter Scan 2D Heatmap

from carriercapture.visualization import plot_scan_heatmap
from carriercapture.analysis import ParameterScanner

# After running scan
results = scanner.run_harmonic_scan(...)

fig = plot_scan_heatmap(
    results,
    title="Capture Coefficient Scan",
    log_scale=True,
    colorscale='Viridis'
)

fig.show()

Interactive Dashboard

from carriercapture.visualization import create_app

# Create Dash app
app = create_app(
    pot_initial=pot_i,
    pot_final=pot_f,
    cc=cc
)

# Run server
app.run_server(debug=False, port=8050)

Or from command line:

carriercapture viz --port 8050

Plot Customization

Themes

from carriercapture.visualization import COLORS, get_default_layout

# Access color scheme
colors = COLORS
primary = colors['primary']
secondary = colors['secondary']

# Get default layout
layout = get_default_layout(
    title="My Plot",
    xaxis_title="Configuration Coordinate (amu^0.5·Å)",
    yaxis_title="Energy (eV)"
)

# Create custom figure
fig = go.Figure(layout=layout)
fig.add_trace(...)

Publication Style

from carriercapture.visualization import apply_publication_style

fig = plot_potential(pot)

# Apply publication styling
fig = apply_publication_style(
    fig,
    width=800,
    height=600,
    font_size=14,
    line_width=2
)

# Export high-res
fig.write_image('figure.pdf', scale=2)

Plot Types

Function Purpose Key Options
plot_potential PES with wavefunctions show_wavefunctions, n_states
plot_capture_coefficient C(T) vs temperature arrhenius, show_activation_energy
plot_configuration_coordinate CC diagram show_crossing, show_wavefunctions
plot_eigenvalue_spectrum Energy levels max_states, show_spacing
plot_overlap_matrix Franck-Condon factors log_scale
plot_scan_heatmap 2D parameter scan log_scale, colorscale

Interactive Features

All Plotly plots support:

  • Zoom: Click and drag to zoom
  • Pan: Shift + drag to pan
  • Hover: Hover for data values
  • Export: Camera icon to save as PNG
  • Reset: Home icon to reset axes

See Also