developer-guide.md

Developer Guide

This guide is for contributors extending DifferentialLab internals or adding new problem modules.

Local environment

pip install -e ".[dev]"

Optional docs toolchain:

pip install -e ".[docs]"

Repository layout

• src/config: schema, constants, paths, equation catalogs
• src/solver: parser + numerical solvers + statistics
• src/frontend: Tk dialogs and plotting embedding
• src/complex_problems: plugin subsystem
• src/pipeline.py: orchestration for standard solve flow
• tests: pytest suite
• docs: Sphinx + MyST docs

Coding conventions

• Keep compute kernels independent from UI code.
• Prefer typed dataclasses for solver outputs.
• Validate user input in UI before solver invocation.
• Use shared helpers in complex_problems/common for safe expressions and background solve handling.
• Keep plugin defaults computationally reasonable (interactive-scale runtime).

UI text conventions

• Use Unicode math formatting in labels when it improves readability (xₘᵢₙ, Nₓ, |ψ|², ...).
• If a Unicode subscript is unavailable for a symbol, use base_subscript fallback (for example N_θ, N_φ).
• Prefer non-selectable labels for static help/description text.
• Keep copy-oriented text areas only where users intentionally need to paste symbols/expressions (custom-equation and transform helpers).

Adding a new complex problem plugin

1. Create package under src/complex_problems/<plugin_id>/.
2. Implement:
   • problem.py with descriptor and open_dialog
   • ui.py for inputs
   • solver.py for numerics
   • result_dialog.py for plots
   • optional model.py
3. Export in package __init__.py.
4. Register module in src/complex_problems/problem_registry.py.
5. Add tests in tests/:
   • solver behavior
   • registry dispatch
6. Update docs (docs/complex-problems.md and docs/api/complex_problems.rst).

Typical quality loop

1. Implement feature.
2. Run focused tests.
3. Run broader regression set.
4. Update docs and examples.

Useful commands

pytest
pytest tests/test_complex_problems_registry.py
ruff check src tests
mypy src

Documentation workflow

pip install -e ".[docs]"
cd docs
make html

For Windows:

make.bat html

Release hygiene checklist

• Version updated where required.
• Changelog entry added.
• Tests pass in CI scope.
• Docs updated for user-visible changes.
• New plugin appears in registry and guide pages.