Architecture

DifferentialLab is organized around clear subsystem boundaries:

config: validated environment and constants
solver: numerical engines and expression parsing
plotting: matplotlib figure builders
frontend: Tkinter dialogs and embedding
pipeline: orchestration for the standard Solve path
complex_problems: plugin-based specialized workflows
transforms: scalar transform tools
utils: shared infrastructure (logging, export, exceptions, update checks)

High-level project layout

src/
  main_program.py
  pipeline.py
  config/
  solver/
  plotting/
  transforms/
  complex_problems/
  frontend/
  utils/

Standard solve path

EquationDialog -> ParametersDialog -> run_solver_pipeline
  -> validation + parser + solver
  -> statistics + export
  -> ResultDialog

Key design goal: keep the general solver stack independent from UI-specific behavior.

Complex Problems architecture

complex_problems uses a lazy plugin registry.

Core pieces:

base.py: ProblemDescriptor and ComplexProblem protocol
problem_registry.py: lazy registration and dispatch
complex_problems_dialog.py: selector window
common/: shared helpers for plugin modules
- background execution (run_solver_with_loading)
- safe expression compilation
- numeric UI parsing helpers

Plugin contract:

problem.py exposes PROBLEM with descriptor + open_dialog(parent)
ui.py gathers validated input
solver.py returns structured result dataclass
result_dialog.py renders module-specific diagnostics
model.py optional physical/math helpers

Registered complex problem plugins

coupled_oscillators
membrane_2d
nonlinear_waves
schrodinger_td
antenna_radiation
aerodynamics_2d
pipe_flow

Configuration lifecycle

main_program.py calls initialize_and_validate_config().
.env is loaded and validated against ENV_SCHEMA.
Invalid values are corrected to defaults and logged.
Runtime reads values through get_env_from_schema(key).
In-app Configuration rewrites .env and restarts the app.

API and import strategy

Public APIs are re-exported in package __init__.py files.
Heavy libraries are imported lazily where practical.
Internal modules import siblings directly to avoid circular re-export issues.

Error handling and safety

Expression inputs are AST-validated before evaluation.
Solver failures propagate as user-facing dialog errors, not hard crashes.
Plugin solvers run in background threads with loading/progress dialogs.

Extensibility principles

Keep numeric kernels separate from UI code.
Use result dataclasses with explicit fields (metadata, magnitudes, raw fields).
Add plugin modules without changing generic solver pipeline.
Register new plugins only in problem_registry.py.