plotting – Visualization

Plotting module for DifferentialLab.

plotting.create_contour_plot(x, y, z, title='f(x, y)', xlabel='x', ylabel='f')

Create a 2D contour plot for 2D scalar field data.

Parameters:

• x (ndarray) – 1D array of x values.

• y (ndarray) – 1D array of y values.

• z (ndarray) – 2D array of values, shape (len(y), len(x)).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_energy_evolution_plot(t, E_kin, E_pot, E_tot, title='Energy vs time', xlabel='t')

Create a plot of kinetic, potential, and total energy vs time.

Parameters:

• t (ndarray) – Time values (1D).

• E_kin (ndarray) – Kinetic energy at each time step.

• E_pot (ndarray) – Potential energy at each time step.

• E_tot (ndarray) – Total energy at each time step.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_energy_per_mode_plot(t, E_modes, selected_indices, labels, title='Energy per mode', xlabel='t')

Create a multi-line plot of energy per mode (or oscillator) vs time.

Parameters:

• t (ndarray) – Time values (1D).

• E_modes (ndarray) – Energy array shape (n_modes, n_points).

• selected_indices (list[int]) – Indices of modes/oscillators to plot.

• labels (list[str]) – Legend labels for each selected index.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_phase_3d_plot(data_x, data_y, data_z, title='Phase Space 3D', xlabel='f₀', ylabel='f₁', zlabel='f₂')

Create a 3D phase-space trajectory plot.

Parameters:

• data_x (ndarray) – Values for the x-axis.

• data_y (ndarray) – Values for the y-axis.

• data_z (ndarray) – Values for the z-axis.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• zlabel (str) – Label for z-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_phase_plot(y, title='Phase Portrait', xlabel='f', ylabel="f'", x=None)

Create a phase portrait for an ODE.

For second-order (or higher): plots y vs y’ (position vs velocity). For first-order: plots y vs dy/dx using numerical derivative (requires x).

Parameters:

• y (ndarray) – Solution array — shape (n_vars, n_points).

• title (str) – Plot title.

• xlabel (str) – Label for horizontal axis.

• ylabel (str) – Label for vertical axis.

• x (ndarray | None) – Independent variable (required for first-order to compute dy/dx).

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_solution_plot(x, y, title='f(x)', xlabel='x', ylabel='f', show_markers=False, selected_derivatives=None, labels=None)

Create a publication-ready plot of the ODE solution.

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution values — shape (n_vars, n_points) or (n_points,).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• show_markers (bool) – Whether to overlay data-point markers.

• selected_derivatives (list[int] | None) – Indices of solution components to plot.

• labels (list[str] | None) – Custom legend labels for each derivative (f-notation).

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_surface_plot(x, y, z, title='f(x, y)', xlabel='x', ylabel='y', zlabel='f')

Create a 3D surface plot for 2D scalar field data.

Parameters:

• x (ndarray) – 1D array of x values.

• y (ndarray) – 1D array of y values.

• z (ndarray) – 2D array of values, shape (len(y), len(x)).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• zlabel (str) – Label for z-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.create_vector_animation_3d(x, y, order, vector_components, title='f_i(x) — 3D', deriv_offset=0)

Create a 3D plot: x (independent), component index i, f_i(x).

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• title (str) – Plot title.

• deriv_offset (int) – Derivative order to display (0=value, 1=first derivative, etc.).

Return type:

Figure

Returns:

A matplotlib Figure with 3D surface.

plotting.create_vector_animation_plot(x, y, order, vector_components, title='f_i(x) vs component', deriv_offset=0, component_labels=None)

Create an interactive plot: x-axis = component index i, y-axis = f_i(x).

The figure stores _animation_update(idx) and _animation_n_points for use with a Tkinter Scale (matplotlib Slider is unreliable when embedded in Tk). For vector ODE: y has shape (n_state, n_points), with f_i at y[i*order].

Parameters:

• x (ndarray) – Independent variable values (1D).

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• title (str) – Plot title.

• deriv_offset (int) – Derivative order to display (0=value, 1=first derivative, etc.).

• component_labels (list[str] | None)

Return type:

Figure

Returns:

A matplotlib Figure (use with embed_animation_plot_in_tk).

plotting.export_animation_to_mp4(x, y, order, vector_components, filepath, *, title='f_i(x) vs component', duration_seconds=10.0, deriv_offset=0)

Export vector animation as MP4 video.

Frames are downsampled to at most _MAX_MP4_FRAMES to avoid memory exhaustion. Requires ffmpeg to be installed on the system.

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• filepath (Path) – Output path for the MP4 file.

• title (str) – Plot title.

• duration_seconds (float) – Desired video duration in seconds. FPS is computed.

• deriv_offset (int)

Return type:

Path

Returns:

The path that was written.

Raises:

RuntimeError – If ffmpeg is not available.

plotting.plot_utils

Matplotlib plotting utilities for ODE solutions.

plotting.plot_utils.create_solution_plot(x, y, title='f(x)', xlabel='x', ylabel='f', show_markers=False, selected_derivatives=None, labels=None)

Create a publication-ready plot of the ODE solution.

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution values — shape (n_vars, n_points) or (n_points,).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• show_markers (bool) – Whether to overlay data-point markers.

• selected_derivatives (list[int] | None) – Indices of solution components to plot.

• labels (list[str] | None) – Custom legend labels for each derivative (f-notation).

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_energy_evolution_plot(t, E_kin, E_pot, E_tot, title='Energy vs time', xlabel='t')

Create a plot of kinetic, potential, and total energy vs time.

Parameters:

• t (ndarray) – Time values (1D).

• E_kin (ndarray) – Kinetic energy at each time step.

• E_pot (ndarray) – Potential energy at each time step.

• E_tot (ndarray) – Total energy at each time step.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_energy_per_mode_plot(t, E_modes, selected_indices, labels, title='Energy per mode', xlabel='t')

Create a multi-line plot of energy per mode (or oscillator) vs time.

Parameters:

• t (ndarray) – Time values (1D).

• E_modes (ndarray) – Energy array shape (n_modes, n_points).

• selected_indices (list[int]) – Indices of modes/oscillators to plot.

• labels (list[str]) – Legend labels for each selected index.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_phase_plot(y, title='Phase Portrait', xlabel='f', ylabel="f'", x=None)

Create a phase portrait for an ODE.

For second-order (or higher): plots y vs y’ (position vs velocity). For first-order: plots y vs dy/dx using numerical derivative (requires x).

Parameters:

• y (ndarray) – Solution array — shape (n_vars, n_points).

• title (str) – Plot title.

• xlabel (str) – Label for horizontal axis.

• ylabel (str) – Label for vertical axis.

• x (ndarray | None) – Independent variable (required for first-order to compute dy/dx).

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_phase_3d_plot(data_x, data_y, data_z, title='Phase Space 3D', xlabel='f₀', ylabel='f₁', zlabel='f₂')

Create a 3D phase-space trajectory plot.

Parameters:

• data_x (ndarray) – Values for the x-axis.

• data_y (ndarray) – Values for the y-axis.

• data_z (ndarray) – Values for the z-axis.

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• zlabel (str) – Label for z-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_surface_plot(x, y, z, title='f(x, y)', xlabel='x', ylabel='y', zlabel='f')

Create a 3D surface plot for 2D scalar field data.

Parameters:

• x (ndarray) – 1D array of x values.

• y (ndarray) – 1D array of y values.

• z (ndarray) – 2D array of values, shape (len(y), len(x)).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• zlabel (str) – Label for z-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_contour_plot(x, y, z, title='f(x, y)', xlabel='x', ylabel='f')

Create a 2D contour plot for 2D scalar field data.

Parameters:

• x (ndarray) – 1D array of x values.

• y (ndarray) – 1D array of y values.

• z (ndarray) – 2D array of values, shape (len(y), len(x)).

• title (str) – Plot title.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

Return type:

Figure

Returns:

A matplotlib Figure.

plotting.plot_utils.create_vector_animation_plot(x, y, order, vector_components, title='f_i(x) vs component', deriv_offset=0, component_labels=None)

Create an interactive plot: x-axis = component index i, y-axis = f_i(x).

The figure stores _animation_update(idx) and _animation_n_points for use with a Tkinter Scale (matplotlib Slider is unreliable when embedded in Tk). For vector ODE: y has shape (n_state, n_points), with f_i at y[i*order].

Parameters:

• x (ndarray) – Independent variable values (1D).

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• title (str) – Plot title.

• deriv_offset (int) – Derivative order to display (0=value, 1=first derivative, etc.).

• component_labels (list[str] | None)

Return type:

Figure

Returns:

A matplotlib Figure (use with embed_animation_plot_in_tk).

plotting.plot_utils.create_vector_animation_3d(x, y, order, vector_components, title='f_i(x) — 3D', deriv_offset=0)

Create a 3D plot: x (independent), component index i, f_i(x).

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• title (str) – Plot title.

• deriv_offset (int) – Derivative order to display (0=value, 1=first derivative, etc.).

Return type:

Figure

Returns:

A matplotlib Figure with 3D surface.

plotting.plot_utils.export_animation_to_mp4(x, y, order, vector_components, filepath, *, title='f_i(x) vs component', duration_seconds=10.0, deriv_offset=0)

Export vector animation as MP4 video.

Frames are downsampled to at most _MAX_MP4_FRAMES to avoid memory exhaustion. Requires ffmpeg to be installed on the system.

Parameters:

• x (ndarray) – Independent variable values.

• y (ndarray) – Solution array, shape (n_state, n_points).

• order (int) – Order per component.

• vector_components (int) – Number of components.

• filepath (Path) – Output path for the MP4 file.

• title (str) – Plot title.

• duration_seconds (float) – Desired video duration in seconds. FPS is computed.

• deriv_offset (int)

Return type:

Path

Returns:

The path that was written.

Raises:

RuntimeError – If ffmpeg is not available.