complex_problems – Special Problems with Custom UIs (Experimental)

Warning

This module is still in development and may contain bugs. Use with caution.

Complex problems module — specialized cases with custom solvers and visualizations.

complex_problems.problem_registry

Registry of available complex problems.

class complex_problems.problem_registry.ProblemDescriptor(id, name, description, open_dialog)[source]

Bases: object

Descriptor for a complex problem.

Variables:

  • id – Unique identifier for the problem.

  • name – Display name for the UI.

  • description – Short description of the problem.

  • open_dialog – Callable(parent) -> None that opens the problem-specific dialog.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • open_dialog (Callable[['Tk | Toplevel'], None])

id: str
name: str
description: str
open_dialog: Callable[[Tk | Toplevel], None]

complex_problems.complex_problems_dialog

Dialog for selecting which complex problem to solve.

class complex_problems.complex_problems_dialog.ComplexProblemsDialog(parent)[source]

Bases: object

Window for selecting a complex problem to solve.

Parameters:

parent (Tk | Toplevel) – Parent window.

complex_problems.coupled_oscillators

Coupled harmonic oscillators — one-dimensional chain with configurable parameters.

complex_problems.coupled_oscillators.build_ode_function(n_oscillators, masses, k_coupling, boundary='fixed', coupling_types=None, nonlinear_coeff=0.0, nonlinear_fput_alpha=0.0, nonlinear_quartic=0.0, nonlinear_quintic=0.0, k_2nn=0.0, k_3nn=0.0, k_4nn=0.0, external_amplitude=0.0, external_frequency=1.0)[source]

Build the ODE right-hand side for coupled oscillators.

State vector y has shape (2*N,): [x_0, …, x_{N-1}, v_0, …, v_{N-1}].

Parameters:

  • n_oscillators (int) – Number of oscillators N.

  • masses (Union[float, list[float], Callable[[int], float]]) – Mass per oscillator (constant, list, or callable).

  • k_coupling (Union[float, list[float], Callable[[int], float]]) – Coupling constant for 1st neighbors.

  • boundary (str) – “fixed” (x_{-1}=x_N=0) or “periodic”.

  • coupling_types (list[str] | None) – List of “linear”, “nonlinear”, “nonlinear_fput_alpha”, “nonlinear_quartic”, “nonlinear_quintic”, “external_force”.

  • nonlinear_coeff (float) – Coefficient for cubic nonlinear coupling (FPUT-β).

  • nonlinear_fput_alpha (float) – Coefficient for FPUT-α: α·(x_{i+1}+x_{i-1}-2x_i)·(x_{i+1}-x_{i-1}).

  • nonlinear_quartic (float) – Coefficient for quartic nonlinear (F ∝ sign(Δ)·Δ⁴).

  • nonlinear_quintic (float) – Coefficient for quintic nonlinear (F ∝ Δ⁵).

  • k_2nn (float) – Coupling for 2nd neighbors (0 = disabled).

  • k_3nn (float) – Coupling for 3rd neighbors (0 = disabled).

  • k_4nn (float) – Coupling for 4th neighbors (0 = disabled).

  • external_amplitude (float) – Amplitude of external driving force.

  • external_frequency (float) – Angular frequency of external force.

Return type:

Callable[[float, ndarray], ndarray]

Returns:

ODE function (t, y) -> dydt.

complex_problems.coupled_oscillators.solve_coupled_oscillators(n_oscillators, masses, k_coupling, boundary='fixed', coupling_types=None, nonlinear_coeff=0.0, nonlinear_fput_alpha=0.0, nonlinear_quartic=0.0, nonlinear_quintic=0.0, k_2nn=0.0, k_3nn=0.0, k_4nn=0.0, external_amplitude=0.0, external_frequency=1.0, t_min=0.0, t_max=30.0, n_points=None, y0=None, method=None)[source]

Solve the coupled oscillators system.

Parameters:

  • n_oscillators (int) – Number of oscillators.

  • masses (Union[float, list[float], Callable[[int], float]]) – Mass specification.

  • k_coupling (Union[float, list[float], Callable[[int], float]]) – Coupling specification.

  • boundary (str) – “fixed” or “periodic”.

  • coupling_types (list[str] | None) – List of coupling types.

  • nonlinear_coeff (float) – Cubic nonlinear coupling coefficient (FPUT-β).

  • nonlinear_fput_alpha (float) – FPUT-α quadratic nonlinear coefficient.

  • nonlinear_quartic (float) – Quartic nonlinear coefficient.

  • nonlinear_quintic (float) – Quintic nonlinear coefficient.

  • k_2nn (float) – 2nd-neighbor linear coupling (0 = disabled).

  • k_3nn (float) – 3rd-neighbor linear coupling (0 = disabled).

  • k_4nn (float) – 4th-neighbor linear coupling (0 = disabled).

  • external_amplitude (float) – External force amplitude.

  • external_frequency (float) – External force frequency.

  • t_min (float) – Start time.

  • t_max (float) – End time.

  • n_points (int | None) – Number of output points (default from env).

  • y0 (list[float] | None) – Initial conditions [x_0, …, x_{N-1}, v_0, …, v_{N-1}].

  • method (str | None) – Solver method.

Return type:

CoupledOscillatorsResult

Returns:

CoupledOscillatorsResult with solution and metadata.

Raises:

SolverFailedError – If integration fails.

complex_problems.coupled_oscillators.model

Physics model for coupled harmonic oscillators.

complex_problems.coupled_oscillators.model.build_ode_function(n_oscillators, masses, k_coupling, boundary='fixed', coupling_types=None, nonlinear_coeff=0.0, nonlinear_fput_alpha=0.0, nonlinear_quartic=0.0, nonlinear_quintic=0.0, k_2nn=0.0, k_3nn=0.0, k_4nn=0.0, external_amplitude=0.0, external_frequency=1.0)[source]

Build the ODE right-hand side for coupled oscillators.

State vector y has shape (2*N,): [x_0, …, x_{N-1}, v_0, …, v_{N-1}].

Parameters:

  • n_oscillators (int) – Number of oscillators N.

  • masses (Union[float, list[float], Callable[[int], float]]) – Mass per oscillator (constant, list, or callable).

  • k_coupling (Union[float, list[float], Callable[[int], float]]) – Coupling constant for 1st neighbors.

  • boundary (str) – “fixed” (x_{-1}=x_N=0) or “periodic”.

  • coupling_types (list[str] | None) – List of “linear”, “nonlinear”, “nonlinear_fput_alpha”, “nonlinear_quartic”, “nonlinear_quintic”, “external_force”.

  • nonlinear_coeff (float) – Coefficient for cubic nonlinear coupling (FPUT-β).

  • nonlinear_fput_alpha (float) – Coefficient for FPUT-α: α·(x_{i+1}+x_{i-1}-2x_i)·(x_{i+1}-x_{i-1}).

  • nonlinear_quartic (float) – Coefficient for quartic nonlinear (F ∝ sign(Δ)·Δ⁴).

  • nonlinear_quintic (float) – Coefficient for quintic nonlinear (F ∝ Δ⁵).

  • k_2nn (float) – Coupling for 2nd neighbors (0 = disabled).

  • k_3nn (float) – Coupling for 3rd neighbors (0 = disabled).

  • k_4nn (float) – Coupling for 4th neighbors (0 = disabled).

  • external_amplitude (float) – Amplitude of external driving force.

  • external_frequency (float) – Angular frequency of external force.

Return type:

Callable[[float, ndarray], ndarray]

Returns:

ODE function (t, y) -> dydt.

complex_problems.coupled_oscillators.model.compute_normal_modes(n_oscillators, masses, k_coupling, boundary='fixed', k_2nn=0.0, k_3nn=0.0, k_4nn=0.0)[source]

Compute normal modes for linear system (fixed or periodic boundary).

For fixed ends and uniform chain with only 1st-neighbor coupling: uses analytic formula u_j^(k) = sin((k+1)*pi*(j+1)/(N+1)) for mode k, oscillator j.

Otherwise solves K @ v = omega^2 * M @ v.

Return type:

tuple[ndarray, ndarray]

Returns:

Tuple of (M_modes, omega_modes). M_modes has shape (n, n), columns are mode vectors. omega_modes is 1D array of angular frequencies.

Parameters:

complex_problems.coupled_oscillators.solver

Solver for coupled harmonic oscillators.

class complex_problems.coupled_oscillators.solver.CoupledOscillatorsResult(x, y, n_oscillators, masses, k_coupling, M_modes, omega_modes, has_modes, metadata=<factory>)[source]

Bases: object

Result from solving coupled oscillators.

Variables:

  • x – Time values (1D).

  • y – State array shape (2*N, n_points): [x_0..x_{N-1}, v_0..v_{N-1}].

  • n_oscillators – Number of oscillators.

  • masses – Mass array (n_oscillators,).

  • k_coupling – Coupling array (n_oscillators-1 or n_oscillators for periodic).

  • M_modes – Mode matrix (n, n), columns are eigenvectors.

  • omega_modes – Angular frequencies of modes (1D).

  • has_modes – True if normal modes were computed (linear only).

  • metadata – Additional solver metadata.

Parameters:
x: ndarray
y: ndarray
n_oscillators: int
masses: ndarray
k_coupling: ndarray
M_modes: ndarray
omega_modes: ndarray
has_modes: bool
metadata: dict[str, Any]
complex_problems.coupled_oscillators.solver.solve_coupled_oscillators(n_oscillators, masses, k_coupling, boundary='fixed', coupling_types=None, nonlinear_coeff=0.0, nonlinear_fput_alpha=0.0, nonlinear_quartic=0.0, nonlinear_quintic=0.0, k_2nn=0.0, k_3nn=0.0, k_4nn=0.0, external_amplitude=0.0, external_frequency=1.0, t_min=0.0, t_max=30.0, n_points=None, y0=None, method=None)[source]

Solve the coupled oscillators system.

Parameters:

  • n_oscillators (int) – Number of oscillators.

  • masses (Union[float, list[float], Callable[[int], float]]) – Mass specification.

  • k_coupling (Union[float, list[float], Callable[[int], float]]) – Coupling specification.

  • boundary (str) – “fixed” or “periodic”.

  • coupling_types (list[str] | None) – List of coupling types.

  • nonlinear_coeff (float) – Cubic nonlinear coupling coefficient (FPUT-β).

  • nonlinear_fput_alpha (float) – FPUT-α quadratic nonlinear coefficient.

  • nonlinear_quartic (float) – Quartic nonlinear coefficient.

  • nonlinear_quintic (float) – Quintic nonlinear coefficient.

  • k_2nn (float) – 2nd-neighbor linear coupling (0 = disabled).

  • k_3nn (float) – 3rd-neighbor linear coupling (0 = disabled).

  • k_4nn (float) – 4th-neighbor linear coupling (0 = disabled).

  • external_amplitude (float) – External force amplitude.

  • external_frequency (float) – External force frequency.

  • t_min (float) – Start time.

  • t_max (float) – End time.

  • n_points (int | None) – Number of output points (default from env).

  • y0 (list[float] | None) – Initial conditions [x_0, …, x_{N-1}, v_0, …, v_{N-1}].

  • method (str | None) – Solver method.

Return type:

CoupledOscillatorsResult

Returns:

CoupledOscillatorsResult with solution and metadata.

Raises:

SolverFailedError – If integration fails.

complex_problems.coupled_oscillators.ui

UI dialog for configuring and solving coupled harmonic oscillators.

class complex_problems.coupled_oscillators.ui.CoupledOscillatorsDialog(parent)[source]

Bases: object

Dialog for configuring coupled harmonic oscillators parameters.

Parameters:

parent (Tk | Toplevel) – Parent window.

complex_problems.coupled_oscillators.result_dialog

Result dialog for coupled harmonic oscillators.

class complex_problems.coupled_oscillators.result_dialog.CoupledOscillatorsResultDialog(parent, *, result)[source]

Bases: object

Result window for coupled harmonic oscillators.

Shows tabs: Energy, Energy per mode, Animation, Heatmap, 3D Surface. Phase 1: Animation tab only. Phase 3 adds the rest.

Parameters: