frontend – GUI

Frontend module for DifferentialLab.

class frontend.MainMenu(root)

Bases: object

Application main menu window.

Presents five actions: Solve, Function Transform, Information, Configuration, Quit.

Parameters:

root (Tk) – The root Tk window.

frontend.theme

TTK theme configuration built from environment variables.

frontend.theme.get_contrast_foreground(bg_color)

Return a foreground color with high contrast against the given background.

Uses luminance to choose black or white for maximum readability.

Parameters:

bg_color (str) – Background color (name or hex).

Return type:

str

Returns:

Hex color string (#000000 or #ffffff).

frontend.theme.get_select_colors(element_bg, text_fg)

Compute select background and foreground from element colors.

Selected text: 20% lighter than unselected text. Selected background: 25% darker than the element’s background.

Parameters:

• element_bg (str) – Background color of the element (e.g. UI_BUTTON_BG).

• text_fg (str) – Foreground/text color (e.g. UI_FOREGROUND).

Return type:

tuple[str, str]

Returns:

Tuple of (select_background, select_foreground) as hex strings.

frontend.theme.get_font()

Return the configured (family, size) font tuple.

Return type:

tuple[str, int]

Returns:

Tuple of font family name and size.

frontend.theme.configure_ttk_styles(root)

Apply the dark theme to all ttk widgets based on env configuration.

Parameters:

root (Tk) – The root Tk window.

Return type:

None

frontend.window_utils

Window management utilities for Tkinter.

frontend.window_utils.center_window(window, width=None, height=None, *, preserve_size=False, max_width_ratio=0.85, max_height_ratio=0.85, resizable=False, y_offset_up=40)

Center window on the screen.

When preserve_size is True the window is sized to its requested (content-driven) dimensions instead of the supplied width/height. Maximum dimensions are clamped to max_width_ratio / max_height_ratio of the screen.

Parameters:

• window (Tk | Toplevel) – The Tk or Toplevel window.

• width (int | None) – Desired minimum width (ignored when preserve_size is set).

• height (int | None) – Desired minimum height (ignored when preserve_size is set).

• preserve_size (bool) – Use the widget-requested size instead of explicit dims.

• max_width_ratio (float) – Max fraction of screen width.

• max_height_ratio (float) – Max fraction of screen height.

• resizable (bool) – Whether the window can be resized by the user.

• y_offset_up (int) – Pixels to shift the window up from center (avoids bottom overflow).

Return type:

None

frontend.window_utils.fit_and_center(window, min_width=400, min_height=300, padding=40, *, max_ratio=0.9, **center_kwargs)

Size window to fit its content (with minimums) and center it.

Computes dimensions from the window’s requested size, clamps to [min_width, screen * max_ratio], then delegates to center_window().

Parameters:

• window (Tk | Toplevel) – The Tk or Toplevel window.

• min_width (int) – Minimum window width in pixels.

• min_height (int) – Minimum window height in pixels.

• padding (int) – Extra pixels added to the requested size.

• max_ratio (float) – Maximum fraction of the screen for each dimension.

• **center_kwargs (object) – Forwarded to center_window().

Return type:

None

frontend.window_utils.make_modal(dialog, parent)

Make a Toplevel dialog modal relative to parent.

Parameters:

• dialog (Toplevel) – The dialog window.

• parent (Tk | Toplevel) – The parent window to block.

Return type:

None

frontend.window_utils.bind_wraplength(frame, label_or_labels, pad=20, min_wrap=200, debounce_ms=50)

Bind label(s) wraplength to the width of a frame.

Automatically adjusts wraplength when the frame is resized, ensuring text wraps nicely within the available space. Supports debouncing to avoid excessive updates during rapid resize.

Parameters:

• frame (Widget) – The frame whose width determines the wraplength.

• label_or_labels (Widget | list[Widget]) – Single label widget or list of labels to update.

• pad (int) – Padding in pixels to subtract from frame width.

• min_wrap (int) – Minimum wraplength in pixels.

• debounce_ms (int) – Debounce delay for Configure events (0 = no debounce).

Return type:

None

frontend.plot_embed

Tkinter embedding utilities for matplotlib figures.

frontend.plot_embed.embed_animation_plot_in_tk(fig, parent, *, on_export_mp4=None)

Embed an animation figure with Scale, Play button, duration entry, and Export MP4.

The figure must have _animation_update(idx) and _animation_n_points attributes. Duration (seconds) controls both playback speed and MP4 export length.

Parameters:

• fig (Figure) – Matplotlib figure from create_vector_animation_plot.

• parent (Widget) – Tkinter parent widget.

• on_export_mp4 (Optional[Callable[[float], None]]) – Optional callback(duration_seconds) when user clicks Export MP4.

Return type:

FigureCanvasTkAgg

Returns:

The canvas object.

frontend.plot_embed.embed_plot_in_tk(fig, parent, toolbar=True)

Embed a matplotlib figure in a Tkinter parent widget.

Parameters:

• fig (Figure) – Figure to embed.

• parent (Widget) – Tkinter parent (Frame, Toplevel, etc.).

• toolbar (bool) – Whether to add the navigation toolbar.

Return type:

FigureCanvasTkAgg

Returns:

The canvas object.

frontend.ui_main_menu

Main menu window for DifferentialLab (Tkinter/ttk).

class frontend.ui_main_menu.MainMenu(root)

Bases: object

Application main menu window.

Presents five actions: Solve, Function Transform, Information, Configuration, Quit.

Parameters:

root (Tk) – The root Tk window.

frontend.ui_dialogs

UI dialog modules for DifferentialLab.

frontend.ui_dialogs.setup_arrow_enter_navigation(widgets_grid, on_enter=None)

Set up arrow-key and Enter navigation on a 2-D grid of widgets.

Parameters:

• widgets_grid (Sequence[Sequence[Any]]) – Rows of widgets (None cells are skipped).

• on_enter (Callable[[Any, Event], bool] | None) – Optional callback (widget, event) -> handled. If it returns True the default invoke is skipped.

Return type:

None

class frontend.ui_dialogs.ToolTip(widget, text, delay=None)

Bases: object

Hover tooltip for any Tkinter widget.

Parameters:

• widget (Widget) – The widget to attach the tooltip to.

• text (str) – The tooltip text.

• delay (int | None) – Delay in milliseconds before showing.

frontend.ui_dialogs.equation_dialog

Equation selection dialog — choose predefined or write custom ODE.

class frontend.ui_dialogs.equation_dialog.EquationDialog(parent)

Bases: object

Dialog for selecting or entering an ODE.

Parameters:

parent (Tk | Toplevel) – Parent window.

frontend.ui_dialogs.parameters_dialog

Parameters dialog — configure domain, ICs, method, and statistics.

class frontend.ui_dialogs.parameters_dialog.ParametersDialog(parent, *, expression=None, function_name=None, order, parameters, equation_name, default_y0, default_domain, parameters_schema=None, display_formula=None, equation_type='ode', variables=None, vector_expressions=None, vector_components=1, pde_operator='neg_laplacian', component_orders=None)

Bases: object

Dialog for configuring solver parameters, ICs, and statistics.

Parameters:

• parent (Tk | Toplevel) – Parent window.

• expression (str | None) – ODE expression string (optional).

• function_name (str | None) – Name of function in config.equations (optional).

• order (int) – ODE order.

• parameters (dict[str, float]) – Parameter name-value mapping.

• equation_name (str) – Display name.

• default_y0 (list[float]) – Default initial conditions.

• default_domain (list[float]) – Default [x_min, x_max].

• parameters_schema (dict[str, dict[str, Any]] | None)

• display_formula (str | None)

• equation_type (str)

• variables (list[str] | None)

• vector_expressions (list[str] | None)

• vector_components (int)

• pde_operator (str)

• component_orders (tuple[int, ...] | None)

frontend.ui_dialogs.result_dialog

Result dialog — left panel (stats, info, export) + right panel (interactive plots).

class frontend.ui_dialogs.result_dialog.ResultDialog(parent, *, result)

Bases: object

Window showing the solution with interactive plot tabs.

Plots are generated on-demand from the raw solver data. The user selects what to visualise (derivatives, phase-space axes, etc.) inside the result window rather than before solving.

Parameters:

• parent (Tk | Toplevel) – Parent window.

• result (SolverResult) – A data-only SolverResult from the pipeline.

frontend.ui_dialogs.config_dialog

Configuration dialog — edit .env variables with collapsible sections.

class frontend.ui_dialogs.config_dialog.ConfigDialog(parent)

Bases: object

Scrollable form to edit all .env configuration values.

After calling, inspect self.accepted to know if the user saved.

Parameters:

parent (Tk | Toplevel) – Parent window.

frontend.ui_dialogs.loading_dialog

Loading dialog shown while the solver runs.

class frontend.ui_dialogs.loading_dialog.LoadingDialog(parent, *, message='Solving...')

Bases: object

Modal loading overlay shown during solver execution.

Parameters:

• parent (Tk | Toplevel) – Parent window.

• message (str) – Text to display (e.g. “Solving…”).

destroy()

Stop the progress bar and close the dialog.

Return type:

None

frontend.ui_dialogs.help_dialog

Help / Information dialog with collapsible sections.

class frontend.ui_dialogs.help_dialog.HelpDialog(parent)

Bases: object

Information window with collapsible sections.

Parameters:

parent (Tk | Toplevel) – Parent window.

frontend.ui_dialogs.scrollable_frame

Reusable scrollable frame widget with cross-platform mousewheel and keyboard support.

class frontend.ui_dialogs.scrollable_frame.ScrollableFrame(parent, **kwargs)

Bases: Frame

A frame that wraps a Canvas + Scrollbar + inner Frame.

Children should be packed/gridded inside self.inner.

Parameters:

• parent (Widget) – Parent widget.

• **kwargs – Extra keyword arguments forwarded to the outer ttk.Frame.

apply_bg(bg)

Set the canvas background to match the theme.

Parameters:

bg (str) – Background colour (hex or Tk colour name).

Return type:

None

refresh_scroll_region()

Force-update the scroll region after dynamic content changes.

Call after adding or removing widgets in self.inner.

Return type:

None

bind_new_children()

Re-bind mousewheel on all descendants (call after adding widgets).

Return type:

None

frontend.ui_dialogs.collapsible_section

Reusable collapsible section widget for Tkinter dialogs.

class frontend.ui_dialogs.collapsible_section.CollapsibleSection(parent, scroll, title, *, expanded=False, pad=6)

Bases: object

A header bar that toggles the visibility of an inner content frame.

Usage:

section = CollapsibleSection(parent, scroll, "Title", expanded=True)
ttk.Label(section.content, text="Hello").pack()

Parameters:

• parent (Frame) – Parent widget to pack into.

• scroll (ScrollableFrame) – The ScrollableFrame that hosts the section (used to refresh the scroll region and rebind mousewheel events).

• title (str) – Section header text.

• expanded (bool) – Whether the section starts open.

• pad (int) – Vertical padding above the wrapper.

frontend.ui_dialogs.tooltip

Tooltip widget for Tkinter/ttk elements.

class frontend.ui_dialogs.tooltip.ToolTip(widget, text, delay=None)

Bases: object

Hover tooltip for any Tkinter widget.

Parameters:

• widget (Widget) – The widget to attach the tooltip to.

• text (str) – The tooltip text.

• delay (int | None) – Delay in milliseconds before showing.

frontend.ui_dialogs.keyboard_nav

Keyboard navigation utilities for Tkinter dialogs.

frontend.ui_dialogs.keyboard_nav.setup_arrow_enter_navigation(widgets_grid, on_enter=None)

Set up arrow-key and Enter navigation on a 2-D grid of widgets.

Parameters:

• widgets_grid (Sequence[Sequence[Any]]) – Rows of widgets (None cells are skipped).

• on_enter (Callable[[Any, Event], bool] | None) – Optional callback (widget, event) -> handled. If it returns True the default invoke is skipped.

Return type:

None

frontend.ui_dialogs.transform_dialog

Transform dialog — enter function, apply Fourier/Laplace/Taylor, visualize and export.

class frontend.ui_dialogs.transform_dialog.TransformDialog(parent)

Bases: object

Dialog for entering a function, applying transforms, and exporting data.

Parameters:

parent (Tk | Toplevel) – Parent window.