Maths

Mathematical model and code mapping

This page documents the current mathematical intent of the Python Digital Twin and how that intent maps to the implemented backend.

Latent optical model

Plain English

The model starts from a latent fluorescence decay, shapes it with the chosen laser/excitation profile, and then lets the detector/gate model decide which photons are actually used.

For specialists

The latent timing model is built by the decay family and the excitation model in twin_engine.py. Built-in decay models include exponential and stretched-exponential families; custom models are loaded from the decay-model store. Burst excitation is interpreted as a sub-pulse train inside the chosen envelope, not as an independent second excitation model.

Conceptually:
latent decay -> excitation envelope -> detector/gate transfer -> collected photons

Detector transfer and event distortion

Plain English

HILIGHTer now has two detector layers: a fast approximation used in the Poisson core, and a slower chronological event-driven detector model used when explicit detector-event behaviour matters.

For specialists

The fast path may still use a Poisson observation model, but it can include a detector transfer function (Poisson (+DTF)) so that timing-dependent distortions affect the detected conditional statistics. The event-driven core simulates accepted events chronologically, including resource sharing, arbitration, multihit capacity, and dead time. The event-driven mode is the physical reference; the fast detector-transfer path is the scalable surrogate.

Fisher metrics

The precision workflow reports related quantities derived from the same underlying collected-photon model.

sigma(theta_hat) / theta = F_cond / sqrt(Nc)

p = F_cond^-2

I_tilde = 1 / (theta^2 * F_cond^2)

Here Nc is the number of photons actually used by the estimator. In the lifetime case this is the collected-photon budget after the instrument has already removed or distorted events.

Photon basis and survival

Plain English

The important distinction is between precision conditional on the photons that survived and the survival of photons through the instrument.

For specialists

The backend now treats collected-photon precision as canonical. Reporting modes such as acquisition-period or all-photon F are rescalings by survival, not different estimators. Monte Carlo payloads expose f_value_conditional and survival_eta explicitly.

eta = Nc / Nref

F_eff = F_cond / sqrt(eta)

In the UI, Compute F-value on changes only the reporting basis. It does not change the collected-photon estimator or the conditional Fisher calculation.

Dead-time correction companions

When dead-time correction is enabled, the precision workflow keeps the raw detector-limited baseline and adds an optional corrected companion path. The raw Monte Carlo accuracy curve remains the same baseline that would be shown with correction disabled.

Plain English

The current correction families do not all mean the same thing. Some first correct the histogram and then reuse the standard gridded MLE, while one remains a detector-aware companion fit on the observed histogram. They should be compared as companion methods inside the same simulator, not assumed to be identical theory statements.

For specialists

Isbaner-lite applies a gated-histogram correction and then refits with the standard detector-free gridded MLE. It is not a paper-faithful implementation of Isbaner et al.: the original method estimates the mean photon-hit rate from raw photon timestamps via the inter-photon-time distribution and then uses that quantity inside a recursive dead-time correction. Rapp (MCHC-lite) is also a histogram-correction-plus-standard-MLE path, implemented as a gated-histogram MCHC-style surrogate rather than a paper-faithful stationary-chain inversion. Rapp (MCPDF-lite) remains a detector-aware companion fit on the observed gated histogram using detector-limited templates, which makes it MCPDF-like rather than a paper-faithful stationary-process implementation. Rapp (MCPDF-full) promotes the stationary detected-histogram model into the public correction surface: it fits the observed gated detection histogram directly against the stationary dead-time model. Rapp (MCHC-full) promotes the stationary inverse path into the public correction surface: it reconstructs the arrival histogram from the observed gated detection histogram through the stationary dead-time model and then feeds the resulting corrected histogram into the standard detector-free gridded MLE. Unlike the lite methods, both full stationary variants depend on the configured photon-budget / count-rate basis because that arrival-rate assumption is part of the stationary process.

Corrected Fisher curves are built from the corresponding method-matched surrogate probabilities in the backend. They are useful for internal comparison against the same simulator family, but they are still under scientific review and should not yet be treated as audited physical bounds.

Resolvability

Plain English

Resolvability is shown only for the supported case: a single-exponential model with tau1 swept on the x-axis.

For specialists

The widget uses the conditional F and the precision photon count. It also provides the inverse metric: the photons required to reach R = 3. These curves are hidden automatically whenever the run is not the supported single-exponential tau1 case.

R = sqrt(N / (8 * F_cond^2))

N_(R=3) = 72 * F_cond^2

Phasors

The phasor path uses the same timing model and calibration assumptions as the decay model. The widget shows both the universal semicircle and the discrete single-exponential locus implied by the actual gate scheme and harmonic.