Apply batch of suggestions

Author: EZoni

docs/source/conf.py

@@ -14,6 +14,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ["myst_parser", "sphinx_copybutton"]
+myst_heading_anchors = 2
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/dashboard.md

@@ -1,7 +1,7 @@
 # Dashboard
 
 The dashboard is a Trame application rooted at `dashboard/app.py`.
-It discovers experiments from `experiments/synapse-*`, reads each experiment's `config.yaml`, connects to MongoDB, loads MLflow models, and builds the GUI for operator control.
+It discovers experiments from `experiments/synapse-*`, reads each experiment's `config.yaml`, connects to MongoDB, loads MLflow models, and builds the GUI used to inspect data and launch jobs.
 
 ## Main Managers
 
@@ -19,7 +19,7 @@ It discovers experiments from `experiments/synapse-*`, reads each experiment's `
 
 - `/`: experiment selection, plots, parameter controls, optimization, ML controls, calibration controls, and errors.
 - `/hpc`: NERSC Superfacility API credential and Perlmutter status panel.
-- `/chat`: embedded assistant route.
+- `/chat`: embedded assistant route for experiment support; currently backed by `https://synapse-chat.lbl.gov/`.
 
 ## NERSC Credentials
 

docs/source/data-model.md

@@ -10,7 +10,7 @@ The collection name should match `experiment` in `config.yaml`.
 
 ## Required Fields
 
-Records should include fields for the configured input and output variable names.
+Each record must contain fields for the configured input and output variables, named to match `config.yaml`.
 
 Simulation records may use simulation-space names when `simulation_calibration` maps them back to experimental names.
 
@@ -21,7 +21,7 @@ The dashboard uses these when present:
 - `date`: filtering and hover text for experimental records.
 - `scan_number`: hover text.
 - `shot_number`: hover text.
-- `_id`: hover text and simulation media lookup.
+- `_id`: hover text and lookup for linked simulation media, such as MP4 files described in [Simulation Outputs](simulations.md#simulation-outputs).
 
 ## Date Filtering
 

docs/source/deployment.md

@@ -18,6 +18,8 @@ From the repository root:
 docker build --platform linux/amd64 --output type=image,oci-mediatypes=true -t synapse-ml -f ml.Dockerfile .
 ```
 
+The two build commands differ only by image tag and Dockerfile.
+
 ## Publish Helper
 
 ```bash
@@ -29,4 +31,4 @@ python publish_container.py --gui --ml
 - Dashboard runs on Spin.
 - Training and simulations run on Perlmutter through Superfacility API.
 - Images are pushed to `registry.nersc.gov/m558/superfacility`.
-- Production changes should be tested carefully before publishing images.
+- Before publishing, validate locally and, when possible, against a staging Spin deployment.

docs/source/developer-notes.md

@@ -8,7 +8,7 @@ Python code is linted and formatted with Ruff through pre-commit:
 pre-commit run --files <modified files>
 ```
 
-There is no project `pyproject.toml` or `ruff.toml`; Ruff uses default rules.
+Ruff runs with its default rule set; there is no `pyproject.toml` or `ruff.toml` to override it.
 
 ## Environments
 
@@ -18,7 +18,7 @@ There is no project `pyproject.toml` or `ruff.toml`; Ruff uses default rules.
 
 ## Testing
 
-There is no broad pytest suite.
+The project does not have a full pytest suite.
 The main integration check is:
 
 ```bash

docs/source/experiment-configuration.md

@@ -46,10 +46,12 @@ Simulation launch uses:
 simulation = alpha * (experimental - beta)
 ```
 
+These are inverse conversions: display maps simulation to experimental units, while launch maps dashboard parameters back to simulation units.
+
 ## Add an Experiment
 
 1. Clone or create `experiments/synapse-<experiment>/`.
 2. Add `config.yaml`.
-3. Ensure MongoDB records match the configured names.
+3. Ensure MongoDB fields match the configured input and output variable names.
 4. Add `simulation_scripts/` only if dashboard launch is needed.
 5. Train and register a model if dashboard predictions are needed.

docs/source/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-Use the lock files for normal setup.
+For a reproducible install, use `environment-lock.yml` rather than the unpinned `environment.yml`.
 
 ## Dashboard
 
@@ -37,4 +37,4 @@ python train_model.py --test --config_file ../experiments/synapse-bella-ip2/conf
 
 - `SF_DB_HOST`: MongoDB host for the dashboard.
 - `SF_DB_READONLY_PASSWORD`: read-only MongoDB password.
-- `AM_SC_API_KEY`: AmSC MLflow API key when the config uses AmSC.
+- `AM_SC_API_KEY`: American Science Cloud MLflow API key when the config uses that service.

docs/source/index.rst

@@ -11,8 +11,8 @@ Welcome to the Synapse documentation!
    overview
    getting-started
    dashboard
-   experiment-configuration
    data-model
+   experiment-configuration
    simulations
    ml-training
    deployment

docs/source/ml-training.md

@@ -9,7 +9,7 @@ Use `--model` with one of:
 
 - `GP`: Gaussian Process.
 - `NN`: single neural network.
-- `ensemble_NN`: ensemble of 10 neural networks.
+- `ensemble_NN`: ensemble neural network. The current ensemble size is defined in `train_nn_ensemble()` in `ml/train_model.py`.
 
 ## Command
 
@@ -24,7 +24,7 @@ Use `--test` to skip MLflow registration.
 1. Load config, variables, database records, and MLflow settings.
 2. Build calibration and normalization transforms.
 3. Train on simulation data.
-4. Train calibration on experimental data when available.
+4. Train [calibration](experiment-configuration.md#calibration) on experimental data when available.
 5. Build a `lume-model`.
 6. Register to MLflow unless `--test` is set.
 

docs/source/overview.md

@@ -1,12 +1,14 @@
 # Overview
 
-Synapse is a modular framework for building digital twin components that connect experimental data, simulation data, and machine learning models.
+Synapse is a modular framework for connecting experimental data, simulation data, and machine learning models for digital twin workflows.
 
-The repository has three main parts:
+The main source areas are:
 
 - `dashboard/`: a Trame web application for exploring experiments, simulations, model predictions, optimization, calibration, and NERSC job controls.
 - `ml/`: model training code for Gaussian Process, single Neural Network, and Neural Network ensemble models.
 - `experiments/`: experiment-specific configuration and scripts, usually cloned from private repositories.
+- `tests/`: integration checks for the ML pipeline.
+- `docs/`: Sphinx documentation source.
 
 The typical workflow is:
 
@@ -27,7 +29,7 @@ Synapse currently assumes these external services:
 - NERSC Superfacility API for Perlmutter jobs.
 - NERSC container registry for dashboard and ML images.
 
-## Map
+## Repository Map
 
 ```text
 dashboard/      Trame GUI and dashboard managers