Controller

The Digital Twin Controller

The controller is the complete front-end for PhysicsConfig. Every major workflow in the desktop, service API, HTTP API, and MCP path eventually reads these same fields. The controller is therefore both the operator UI and the most concrete documentation of the active instrument/state model.

Decay Model tab

Plain English

This tab defines the fluorescence model, the active Fisher sweep parameter, and the numerical precision-analysis setup. It also shows which simulation cores the workspace will actually use.

For specialists

This tab controls decay_model, n_components, taus, amplitudes, beta, background_level, b_decay_wrapping, the sweep definition, and both the simulation and validation mode preferences. The model metadata are provided by python/backend/decay_model_store.py.

Element	What it does	Current intent
`Decay`	Selects the active built-in or custom model.	Changing the decay family changes the visible parameters, default sweep limits, and the meaning of the Fisher sweep.
`N components`	Sets the active number of exponential components where relevant.	Controls whether `tau2` and `alpha` exist and whether resolvability is allowed later.
Model editor icon	Opens the custom model editor.	Custom models are persisted, carry parameter metadata, and can be used by the same fitting/precision workflow as built-ins.
Model maths icon	Expands the current model equation.	The maths pane renders symbolic maths for the active model rather than raw source text.
`Decay wrapping`	Wraps earlier-pulse contributions into the current acquisition window.	This is a decay/PDF decision, separate from gate wrap-around.
`Sim. core`	Shows the active backend used by the simulation-first workflows.	Displays `Poisson`, `Poisson (+DTF)`, or `Event-driven`. This is the one authoritative core selector exposed in the controller.
`Background (%)`	Sets decay-model background in percent.	The analysis/fitting path now treats this as additive background counts rather than only a fragile latent-mixture parameter.
`Precision Sweep Configuration`	Controls X-axis parameter, range, steps, scaling, and lookup-grid refinement.	These values drive both theory and gridded MLE validation.

Excitation tab

Plain English

This tab defines the laser/excitation waveform that drives the latent fluorescence. In burst mode, the chosen laser profile acts as the envelope of a sub-pulse train.

For specialists

The excitation controls drive dt_excitation(). Profiles include Gaussian, Rectangular, Free Form, and Ideal. The burst controls define the interpulse period and sub-pulse width inside the selected envelope. Gaussian envelope mode disables burst excitation in the UI because that combination is intentionally unsupported.

Element	What it does	Current notes
`Period (ns)`	Sets repetition period / acquisition window.	Used by decay wrapping, gate constraints, count-rate interpretation, and phasor frequency.
`Laser profile`	Selects Gaussian, Rectangular, Free Form, or Ideal.	Free Form uses the interactive waveform editor; Gaussian disables burst excitation.
`FWHM / Duration`, `Position`, edge times	Parameterise the selected pulse family.	Rectangular profiles also use rise/fall times and are shown in diagnostics exactly as distilled by the backend.
`Burst Excitation`	Enables a sub-pulse train within the envelope.	The UI exposes `Interpulse distance (ps)`, the equivalent repetition rate, and `Pulse FWHM (ps)`. Backend synthesis now avoids aliasing artefacts for very narrow burst pulses.
Detector-transfer maths icon	Shown in Detection rather than here.	The excitation tab now focuses on laser-envelope intent; detector-transfer exposition is separated explicitly.

Detection tab

Plain English

This tab defines what photons survive the instrument and how they are collected. It covers timing blur, dead time, dark counts, multihit capacity, gate geometry, gate overlap semantics, and the basis used when reporting F.

For specialists

The detection path now distinguishes collected-photon conditional precision from photon survival. The detector pane drives the fast detector-transfer approximation and, when needed, the event-driven backend. The gate controls define the distilled collection geometry and its overlap semantics.

Element	What it does	Current notes
`Ideal detector` + maths icon	Explains the detector transfer model.	The expanded maths pane shows the detector-transfer description in rendered maths, with explanatory text rather than live numeric substitutions.
`Jitter`	Sets detector timing jitter in ps.	Used by the fast detector-transfer model and in the event-driven approximation path where appropriate.
`Deadtime`	Sets detector dead time in ns.	Can trigger `Poisson (+DTF)` or `Event-driven`, depending on the requested and required mode.
`Dark count rate`	Detector-originated background in counts/s.	This is distinct from decay-model background and disables the manual decay-model background control when active.
`Multihit Detection` and capacity	Defines first-hit, finite-capacity, or effectively unbounded per-period acceptance.	The event-driven core treats this as detector-event logic; profiles can encode vendor-specific capacities.
`Pixel dwell` and derived count rate	Define how a photon budget maps to acquisition rate.	Important for dead time and count-rate sweeps. Batch Sweep can now hold photons fixed and sweep count rate by varying dwell time.
`Gate type`, alignment, overlap, wrap-around	Define the gate geometry.	Ideal gates are encoded explicitly by sharp edges, histogram collection, no overlap, and no wrap-around.
`Compute F-value on`	Selects the reporting basis for `F`.	Collected-photon conditional precision is canonical; acquisition-period/all-photon modes are reporting rescalings.

Precision / Fisher pane

Plain English

This section defines how precision is computed, how much Monte Carlo validation is done, and how uncertainty is summarised.

Element	Purpose	Current notes
`Defaults`	Loads built-in low-, medium-, or high-resolution Fisher presets.	Presets set photons, MC repeats, estimator-accuracy p-value, bootstrap resamples, and the photon-basis radio to acquisition-period reporting.
`Photons`	Sets the precision photon budget.	This same count is also used for resolvability unless the precision widget override is engaged.
`Validate with Monte Carlo`	Runs repeat simulations against the same sweep.	Needed when testing estimator bias or event-driven departures from the fast theory path.
`Evaluate CI`, CI level, and sigma label	Computes bootstrap confidence intervals and shows the corresponding Gaussian sigma-equivalent.	The default level is `99.7%`, displayed as `3.0σ` next to the spinner.
`Bootstrap resamples`	Sets bootstrap sample count.	Higher values stabilise CI estimates at the cost of runtime.
`Estimator accuracy p-value`	Threshold for compatibility flags.	Used to grey/flag MC points that fail the configured compatibility criterion.
`Dead-time correction`	Selects the companion correction family used to build corrected estimates and corrected Fisher reporting alongside the raw detector-limited baseline.	The dropdown now exposes `None`, `Isbaner-lite`, `Rapp (MCPDF-lite)`, `Rapp (MCPDF-full)`, `Rapp (MCHC-lite)`, and `Rapp (MCHC-full)`. The raw Monte Carlo accuracy curve remains identical to the `None` setting. The Isbaner-lite and `Rapp (MCHC-lite)` companions first correct the gated histogram with surrogate models and then refit it with the standard detector-free gridded MLE, `Rapp (MCPDF-lite)` remains a detector-aware surrogate companion fit on the observed gated histogram, `Rapp (MCPDF-full)` evaluates the stationary detected-histogram model directly, and `Rapp (MCHC-full)` reconstructs the arrival histogram through the stationary model before the standard detector-free gridded MLE. `Isbaner-lite` is intentionally labeled as a surrogate method: the original Isbaner paper uses raw photon timestamps and the inter-photon-time distribution, which the current gated-histogram companion does not reproduce paper-faithfully. The lite methods use the observed gated histogram plus calibrated detector settings only; the full stationary variants additionally depend on the configured photon-budget / count-rate basis because the stationary model needs an arrival-rate assumption.
`Compute F-value on`	Chooses collected, acquisition-period, or all-photon reporting.	The estimator statistics do not change when this is toggled; existing cached runs can often be rescaled rather than recomputed.

MC image validation tab

This tab controls synthetic image generation and fitting. It uses the active sweep parameter to generate validation images, then routes them into the map, decay, and phasor widgets. Image fitting and one-dimensional precision analysis now share the same repaired parameter semantics, including the fixed tau2 and background paths.

Optimisation tab

The optimisation tab exposes detection-gate optimisation, excitation-profile optimisation, count-rate optimisation, and the joint alternating workflow. The history plots are retained and exportable. The objective can be Fisher information, Fisher throughput, photon-efficiency AUC, or throughput AUC.

Displayed Fisher curves still respect the selected photon-basis reporting mode, but throughput objectives are internally evaluated in the all-photon basis so rate sweeps remain physically comparable under pile-up and dead-time losses. When dead-time correction is enabled, the count-rate throughput objective uses the corrected Fisher curve rather than the raw detector-limited one.

Count-rate optimisation also supports an accuracy-protection guard: the scan rejects rates whose predicted estimator bias exceeds the configured maximum, then chooses the highest-throughput feasible rate. Internally, the search now runs as a coarse scan plus a refinement pass around the best feasible region and the first accuracy boundary.

Batch Sweep tab

Sweep family	Purpose
Laser pulse width	Compare excitation broadening.
Detector jitter	Compare timing blur.
Detector dead time	Compare dead-time distortion at fixed count rate.
Max events/period	Compare multihit-capacity assumptions.
Gate rise/fall	Compare non-ideal gate edges.
Number of gates	Compare gate-count architectures.
Burst rise/fall	Compare burst-edge shapes.
Count Rate via Pixel Dwell	Fixes precision photons to 1000 and varies dwell time to hit the target count rates.

Main actions below the controller

Button	Role
`Profiles`	Open the instrument profile manager.
`Run Analysis`	Run the main one-dimensional precision workflow.
`Run Optimisation`	Shown when optimisation mode is active.
`Interrupt`	Request cancellation of long workflows.
`SAVE AS`	Export reports and figures.
`2D MC tests`	Run the synthetic validation-image workflow.