DifferentialLab

Desktop numerical lab for ODEs, vector ODEs, difference equations, scalar 2D/3D PDEs, vector 2D PDEs, function transforms, and specialized scientific simulation workflows.

Documentation | Report Bug | Request Feature

Current State

• Python: >=3.12
• Package name: differential-lab
• GUI: Tkinter/ttk with embedded Matplotlib figures
• Predefined catalog: 125 equations loaded from YAML
  • 48 ODEs
  • 50 vector ODE systems
  • 10 difference equations
  • 12 2D PDE examples
  • 4 scalar 3D PDE examples
  • 1 coupled Vector PDE example
• Advanced Problems: 10 registered, lazily loaded plugins
• Quality tooling: pytest, ruff, and a repo-local pyright configuration
• Documentation: Sphinx + MyST under docs/

What It Solves

• Scalar ODEs with SciPy IVP integrators, safe terminal/directional events, and a dedicated endpoint-BVP backend with shooting retained for true multipoint conditions
• Vector ODE systems with component-aware notation and visualizations
• Difference equations and recurrence systems
• Scalar linear elliptic 2D PDE workflows with rectangular or masked domains, structured Dirichlet/Neumann/Robin boundaries, non-duplicated periodic axes, component-aware ellipticity validation, and algebraic diagnostics
• Linear strongly elliptic Vector PDE systems in 2D with matrix-valued coupling, component-aware boundaries, sparse block assembly, component/magnitude views, component/magnitude spatial axis sweeps, and Cartesian quiver, stream, and radial/tangential visualizations for exactly two-component systems
• Scalar linear elliptic PDEs on rectangular 3D grids with all six second-order coefficients, Dirichlet/Neumann/Robin faces, periodic axes, sparse diagnostics, pre-run memory advice, selectable coordinate-labelled orthogonal result slices, and selectable spatial axis sweeps
• Cartesian scalar PDE views plus polar re-sampling for visualization; coordinate transforms are display-only and never alter the solved equation
• Function transforms: Fourier, Laplace, Taylor, Hilbert, and Z-transform
• Advanced Problems subsystem with specialized models, custom UI, solvers, diagnostics, and result dialogs

Core Features

• Predefined equation catalog in src/config/equations/*.yaml
• Safe expression parsing with AST validation
• Unified f[...] notation (f[0], f[1], f[i,k])
• Interactive result dialogs with derivative/component selection and dynamic redraw
• CSV and JSON data exports, static figure export through the Matplotlib toolbar, and MP4 export from animated views
• Environment-backed configuration through .env and the in-app Settings dialog
• Rotating application logs with optional console output

Security

• Report security issues privately using SECURITY.md.
• Local .env, generated outputs, update-check state, logs, caches, and virtual environments are ignored by git.
• GitHub checks include Dependabot, CodeQL default setup, and a weekly Python dependency audit.

Advanced Problems

Advanced Problems is a ten-plugin subsystem. Internally, its Python package is named complex_problems; each plugin provides its own configuration dialog, solver, structured result, and result dialog.

Gravitational N-Body Dynamics adds curated Figure-eight, Lagrange equilateral, and Pythagorean three-body studies plus configurable 2D/3D systems of 2--100 point masses. It uses self-consistent user-selected units; positive softening epsilon is explicitly the Plummer-softened model, while epsilon zero is exact Newtonian point gravity.

Fermi-Pasta-Ulam-Tsingou Experiment is a dedicated fixed-end alpha/beta chain workflow. It uses Velocity Verlet for recommended long-time exploration and offers legacy RK4 for historical comparison. Its exact nonlinear Hamiltonian is distinct from the linear normal-mode energy diagnostic; the result notebook includes modal recurrence fidelity, entropy/participation, strain structures, phase space, and sequential recurrence scaling.

Current modules:

• coupled_oscillators: 1D coupled oscillator chains and FPUT-style variants
• membrane_2d: 2D nonlinear membrane lattice
• nonlinear_waves: NLSE and KdV pseudo-spectral propagation
• schrodinger_td: 1D/2D time-dependent Schrodinger solver
• antenna_radiation: far-field patterns and antenna metrics
• aerodynamics_2d: 2D incompressible obstacle-flow approximations
• aerodynamics_3d: incompressible 3D structured-grid flow in a periodic Cartesian domain with immersed/penalized obstacles and 3D vector, streamline, and slice visualization
• pipe_flow: steady and transient 1D pipe-flow models
• gravitational_n_body: softened Newtonian N-body dynamics and orbit diagnostics
• fput_experiment: dedicated Fermi-Pasta-Ulam-Tsingou recurrence and strain studies

Requirements

• Python >=3.12
• Windows 10/11, macOS, or Linux
• Tkinter available in the Python runtime
• A virtual environment named .venv is the expected local setup

Quick Start

First-time setup

Windows:

install.bat

Linux/macOS:

chmod +x install.sh
./install.sh

Existing clone

Windows:

bin\setup.bat
bin\run.bat

Linux/macOS:

./bin/setup.sh
./bin/run.sh

The setup and run scripts use the project-local .venv directly, so you do not need to activate it first. Manual activation remains useful for development commands you run yourself. Running ./bin/run.sh or .venv/bin/differential-lab keeps imports tied to the installed project environment and avoids mismatches from accidentally using the system Python. On Linux, install.sh adds an application-menu launcher and a Desktop launcher when the XDG Desktop directory exists.

For development dependencies:

bin\setup.bat --dev

or on Linux/macOS:

./bin/setup.sh --dev

Manual run from an activated environment (activation is optional when using the project scripts above):

python src/main_program.py

Installed console entry point:

differential-lab

Documentation

• Documentation Home
• Getting Started
• User Guide
• Complex Problems Guide
• Configuration Reference
• Architecture
• Developer Guide
• Testing
• API Reference

To build docs locally:

pip install -e ".[docs]"
python -m sphinx -W --keep-going -b html docs docs/_build/html

Output directory: docs/_build/html/.

Development

Install development dependencies:

pip install -e ".[dev]"

Recommended checks before sharing changes:

ruff check . --fix
ruff format .
pytest
pyright
python -m pip_audit

Run pyright when it is installed in your environment.

Contribution guide: CONTRIBUTING.md.

License

MIT License. See license.md.

Asset provenance and attribution notes: NOTICE.

Third-party licenses: THIRD_PARTY_LICENSES.md.

Citation metadata: CITATION.cff.