Refresh DifferentialLab documentation after 1.0.0

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Synchronized maintained user, developer, API, and in-app reference documentation with the published 1.0.0 implementation.
+
 ## [1.0.0] - 2026-09-22
 
 ### Changed

README.md

@@ -63,7 +63,7 @@ vector 2D PDEs, function transforms, and specialized scientific simulation workf
 - 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, JSON, and static figure exports, plus MP4 export for every interactive animation result view
+- 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
 
@@ -185,9 +185,7 @@ To build docs locally:
 
 ```bash
 pip install -e ".[docs]"
-cd docs
-make html      # Linux/macOS
-make.bat html  # Windows
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 Output directory: `docs/_build/html/`.

docs/api/frontend.rst

@@ -50,6 +50,18 @@ frontend.ui_dialogs.parameters_dialog
 .. automodule:: frontend.ui_dialogs.parameters_dialog
    :members:
 
+frontend.ui_dialogs.solve_session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: frontend.ui_dialogs.solve_session
+   :members:
+
+frontend.ui_dialogs.symbol_palette
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: frontend.ui_dialogs.symbol_palette
+   :members:
+
 frontend.ui_dialogs.result_dialog
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/architecture.md

@@ -44,13 +44,19 @@ docs/
 
 ```text
 EquationDialog
-  -> ParametersDialog
+  -> SolveSession -> ParametersDialog
   -> run_solver_pipeline
   -> validation + parser + solver dispatch
   -> statistics + metadata
   -> ResultDialog
 ```
 
+`frontend.ui_dialogs.solve_session` owns the UI-only state between Equation and
+Configuration. It keeps family-specific browser/custom-editor state and
+configuration snapshots, so Equation -> Configuration navigation retains input;
+Results -> `Modify setup` returns to the compatible Configuration state rather
+than reconstructing it from scratch.
+
 The key design goal is to keep the general solver stack independent from
 UI-specific behavior. Plot generation is deferred to result dialogs so users can
 switch views without re-solving.
@@ -141,6 +147,11 @@ Core pieces:
 - `problem_docs.py`: structured help metadata shown in plugin dialogs
 - `common/`: shared helpers for plugin modules
 
+The shared Advanced Problem infrastructure in `complex_problems/common/` covers
+dialog layout, validation, expression handling, documentation panels, background
+execution, and result-dialog/animation cleanup. Plugins should reuse it instead
+of duplicating UI shells or lifecycle logic.
+
 Plugin contract:
 
 - `problem.py` exposes `PROBLEM` with descriptor and `open_dialog(parent)`
@@ -186,8 +197,16 @@ If file logging cannot start, the logger falls back to console output.
 - Solver input is validated before dispatch.
 - Solver failures are converted into user-facing dialog errors where possible.
 - Long-running plugin solvers use background helpers and loading dialogs.
+- `frontend.performance_guard` estimates dense output, sparse PDE grids,
+  volumetric histories, and selected Advanced Problem workloads before a GUI run;
+  it advises or requests confirmation but does not change numerical settings.
 - Export paths are centralized through `config.paths`.
 
+Standard Results owns CSV/JSON data export actions and delegates static-figure
+export to the Matplotlib toolbar. Animated views expose MP4 only where their
+plot payload supports it. Advanced-result derived caches (for example 3D slices
+and streamlines) remain in result dialogs rather than solver result objects.
+
 ## Quality Tooling
 
 - Tests: `pytest`

docs/complex-problems.md

@@ -129,7 +129,8 @@ instantaneous decomposition. The optional diagnostic residual is
 - Increase grid resolution only after the model behaves as expected.
 - Keep time steps conservative for nonlinear or wave-dominated models.
 - For 2D models, tune both spatial resolution and output sampling cadence.
-- Large animations and high-resolution fields can become memory-heavy.
+- For Aerodynamics 3D, `nx`, `ny`, `nz`, and the saved-frame cadence multiply retained volumetric history; build its streamline cache only when needed.
+- Large animations, MP4 export, and high-resolution fields can become memory-heavy.
 
 ## Extending with New Plugins
 

docs/configuration.md

@@ -14,6 +14,18 @@ DifferentialLab reads configuration from `.env` in the project root.
 - `int` and `float`: parsed numerically, with range checks where defined
 - `str`: must be non-empty; some keys enforce a fixed option list
 
+## Settings Dialog
+
+The in-app `Settings` dialog presents the schema as four operational groups:
+`Appearance`, `Plots`, `Solver Defaults`, and `Advanced`. The technical `.env`
+key remains available in each control's tooltip. Colour settings have an editable
+preview; selecting it opens the system colour chooser.
+
+`Restore Defaults` repopulates the current form but does not write `.env`.
+Choose `Save & Restart` to write the form values and restart the app. On startup,
+values are validated against `ENV_SCHEMA`; invalid values fall back to schema defaults
+and are logged.
+
 ## UI Settings
 
 | Key | Type | Default | Description |

docs/developer-guide.md

@@ -53,6 +53,8 @@ pip install -e ".[docs]"
 - Prefer typed dataclasses for solver outputs.
 - Validate user input before solver invocation.
 - Reuse helpers in `complex_problems/common` instead of duplicating dialog logic.
+- Reuse `frontend.ui_dialogs.solve_session` for retained standard-workflow state
+  and `frontend.ui_dialogs.symbol_palette` for supported expression insertion.
 - Keep plugin defaults computationally reasonable for interactive use.
 - Keep public-facing docs aligned with `pyproject.toml`, `ENV_SCHEMA`, and the plugin registry.
 
@@ -108,21 +110,24 @@ pytest tests/test_nonlinear_waves_solver.py
 pytest tests/test_schrodinger_td_solver.py
 pytest tests/test_antenna_radiation_solver.py
 pytest tests/test_aerodynamics_2d_solver.py
+pytest tests/test_aerodynamics_3d.py
+pytest tests/test_gravitational_n_body.py
+pytest tests/test_fput_experiment.py
 pytest tests/test_pipe_flow_solver.py
+pytest tests/test_advanced_config_dialog_ui.py
+pytest tests/test_complex_problem_result_dialog_ui.py
 ```
 
 ## Documentation Workflow
 
 ```bash
-pip install -e ".[docs]"
-cd docs
-make html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 For Windows:
 
 ```bat
-make.bat html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 Documentation should be updated when a change affects:

docs/faq.md

@@ -55,10 +55,11 @@ logs/run.log
 
 ## Complex problem runs too slowly
 
-- Reduce grid size (`nx`, `ny`) and simulation horizon (`t_max`).
-- Increase output sampling interval where available.
-- Start from defaults and scale up incrementally.
-- For animation-heavy results, reduce stored frames before increasing resolution.
+- Start from the module defaults or a lower resolution before scaling up.
+- For 2D models, reduce `nx` and `ny`; for Aerodynamics 3D, reduce `nx`, `ny`, and `nz`.
+- Shorten `t_max` and increase the saved-output interval where available; large volumetric histories consume memory quickly.
+- Build the Aerodynamics 3D streamline cache only when needed: it traces every saved frame and remains cached for that Results window.
+- Treat animation and MP4 export as additional work, especially for long histories or volumetric views.
 
 ## Numerical blow-up or NaNs
 
@@ -84,19 +85,17 @@ logs/run.log
 ## Sphinx docs build errors
 
 - Install docs extras: `pip install -e ".[docs]"`.
-- Build from the `docs/` directory.
+- Build from the repository root.
 - Remove stale `docs/_build/` if needed and rebuild.
 
 Windows:
 
 ```bat
-cd docs
-make.bat html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 Linux/macOS:
 
 ```bash
-cd docs
-make html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```

docs/getting-started.md

@@ -125,18 +125,18 @@ differential-lab
 ## First Run Checklist
 
 1. Open `Solve Equation`.
-2. Run a predefined equation to confirm the solver and result dialog work.
-3. Open `Settings` and save your preferred UI/plot defaults.
-4. Confirm `output/` receives CSV, JSON, plot, or animation exports.
-5. Optionally open `Advanced Problems` and run one module with default parameters.
+2. Use the searchable predefined-equation browser, select an equation, and choose `Continue`.
+3. Review the retained Configuration form, then choose `Solve`.
+4. Inspect the Results workspace summary, metrics, diagnostics, and available visualization controls.
+5. Use the fixed footer's CSV or JSON action, the Matplotlib toolbar for a static figure, or MP4 only from an animated view.
+6. Open `Settings` and save your preferred UI/plot defaults.
+7. Optionally open `Advanced Problems` and run one module with default parameters.
 
 ## Build Docs Locally
 
 ```bash
 pip install -e ".[docs]"
-cd docs
-make html      # Linux/macOS
-make.bat html  # Windows
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 Open `docs/_build/html/index.html`.

docs/index.md

@@ -8,7 +8,8 @@ workflows. The current repository includes:
 - scalar ODE solving
 - vector ODE systems
 - difference and recurrence equations
-- 2D PDE workflows
+- scalar elliptic 2D and 3D PDE workflows
+- linear strongly elliptic Vector PDE systems in 2D
 - function transforms
 - specialized `complex_problems` plugins
 - Sphinx-generated API documentation
@@ -17,7 +18,7 @@ workflows. The current repository includes:
 
 - Python: `>=3.12`
 - Predefined equation catalog: [`src/config/equations/`](../src/config/equations/)
-- Complex problem plugins: 7 registered modules
+- Advanced Problems: 10 registered, lazily loaded plugins
 - Configuration source of truth: `src/config/env.py`
 - Main entry point: `src/main_program.py`
 

docs/testing.md

@@ -38,7 +38,12 @@ pytest tests/test_nonlinear_waves_solver.py
 pytest tests/test_schrodinger_td_solver.py
 pytest tests/test_antenna_radiation_solver.py
 pytest tests/test_aerodynamics_2d_solver.py
+pytest tests/test_aerodynamics_3d.py
+pytest tests/test_gravitational_n_body.py
+pytest tests/test_fput_experiment.py
 pytest tests/test_pipe_flow_solver.py
+pytest tests/test_advanced_config_dialog_ui.py
+pytest tests/test_complex_problem_result_dialog_ui.py
 ```
 
 Frontend and utilities:
@@ -92,13 +97,15 @@ Docs verification:
 
 ```bash
 pip install -e ".[docs]"
-cd docs
-make html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 On Windows, use:
 
 ```bat
-cd docs
-make.bat html
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
+
+The GitHub Actions quality workflow checks Ruff linting and formatting, pytest,
+and Pyright. Packaging smoke checks and a warnings-as-errors Sphinx build are
+appropriate local release/documentation checks when those surfaces change.

docs/user-guide.md

@@ -27,7 +27,10 @@ The standard solver path currently supports:
 - Vector ODE
 - Vector PDE
 
-You can use the predefined YAML catalog or write custom expressions.
+Use the searchable predefined-equation browser or one of the Custom equation
+editors. The browser retains its search, category, and selection while you move
+through the standard workflow. Custom editors share a SymbolPalette: choosing a
+symbol inserts it literally at the last active supported editor.
 The current catalog has 125 entries:
 
 | Type | Entries |
@@ -61,6 +64,10 @@ For custom expressions:
 
 Typical safe math functions are available (`sin`, `cos`, `exp`, `log`, `sqrt`, etc.).
 
+Select `Continue` to open Configuration. Going back to Equation retains the
+selection and raw editor values; Configuration also retains a compatible form
+snapshot for each selected equation.
+
 ### 3. Configure numeric parameters
 
 Common settings include:
@@ -71,7 +78,9 @@ Common settings include:
 - statistics to compute
 - PDE operator and visualization mode
 
-For an initial-value ODE, the optional **IVP Event** panel accepts a safe scalar
+Configuration forms adapt to the equation family and window size. Optional
+controls use progressive disclosure; for example, expand **IVP Event** only for
+an initial-value ODE. That panel accepts a safe scalar
 expression in `x` and the current state, such as `f[0] - 1`. A zero marks an
 event. **Stop at event** makes it terminal, while direction `-1`, `0`, or `1`
 selects decreasing, either, or increasing zero crossings. Events are not applied
@@ -322,23 +331,37 @@ positive component count retain component and magnitude views.
 
 ### 4. Solve and inspect
 
+Choose `Solve` to run the configured equation. The resizable Results workspace
+keeps a factual run summary, computed metrics, detected events where applicable,
+and collapsible solver diagnostics separate from its visualization area. Controls
+can change the current derivative, component, slice, or display without
+re-solving, but available views depend on the result type.
+
+Choose `Modify setup` to return to the retained Configuration state, adjust it,
+and solve again.
+
 Result dialogs include:
 
 - metadata and solver quality information
 - selected statistics
 - interactive plots/tabs
 - derivative, component, or axis selection without re-solving
-- export options for data and figures
+- fixed-footer CSV and JSON data actions
+- static figure export through the Matplotlib toolbar
+- MP4 export from animated views that provide it
 
 ## Function Transform Workflow
 
 In `Function Transform`:
 
-1. Provide an `f(x)` expression and domain.
-2. Select transform type.
-3. Tune transform-specific parameters when shown.
-4. Switch between curve view and coefficient view.
-5. Export transformed data and plots.
+1. Provide an editable `f(x)` expression, optional parameters, and domain; the
+   SymbolPalette can insert directly into the last active field.
+2. Select a transform and tune transform-specific parameters when shown.
+3. Choose the curve or coefficient display.
+4. Press `Update`. Changes to the function, domain, transform, or display stay
+   pending until this explicit action recomputes the view.
+5. Use `Export CSV...` for the displayed data or the Matplotlib toolbar for a
+   static figure.
 
 Available transform types:
 
@@ -369,7 +392,10 @@ Current modules are:
 - `schrodinger_td`
 - `antenna_radiation`
 - `aerodynamics_2d`
+- `aerodynamics_3d`
 - `pipe_flow`
+- `gravitational_n_body`
+- `fput_experiment`
 
 Most plugin dialogs include a collapsed `How to configure` section with:
 
@@ -395,13 +421,12 @@ Common outputs:
 
 Use `Settings` in the main menu to edit environment-backed settings.
 
-Categories include:
-
-- UI colors, fonts, padding, and tooltips
-- plot style, fonts, phase-space markers, contour/surface style, and animation
-- solver defaults and tolerances
-- logging and update checks
+Settings has four user-facing groups: `Appearance`, `Plots`, `Solver Defaults`,
+and `Advanced`. Colour fields show an editable preview and open the system colour
+chooser. Technical `.env` key names remain available as tooltips.
 
-Saving from the dialog restarts the app so settings apply cleanly.
+`Restore Defaults` updates the form only; nothing is written until you choose
+`Save & Restart`. `Save & Restart` writes the settings and restarts the application;
+startup validation then applies the schema rules and falls back to defaults for invalid values.
 
 See [Configuration Reference](configuration.md) for the current key list.