Backend module guide

twin_engine.py

This is the computational heart of the Digital Twin. It owns excitation modelling, latent decay PDFs, detector-transfer approximation, gate distillation, Fisher analysis, Monte Carlo validation, image synthesis, fitting, phasors, diagnostics, and optimisation.

Important current intent:

• collected-photon conditional precision is canonical
• photon-basis modes are reporting rescalings, not different estimators
• the fast Poisson core can include a detector transfer function
• the event-driven core is the explicit chronological detector model

models.py

Defines PhysicsConfig and related lightweight state containers. This is the shared contract between controller widgets, profiles, the service API, the HTTP API, and MCP tooling.

decay_model_store.py

Holds built-in and custom decay-model metadata, including parameter labels, units, sweep defaults, descriptions, and editable custom expressions.

service_api.py

Provides the stable orchestration layer used by the desktop, HTTP API, and MCP server. New manual pages should assume this service layer, not the GUI, is the programmatic source of truth.

event_driven.py

Hosts the chronological detector backend. It simulates event acceptance in time order and supports dead-time mode, routing/arbitration, shared-resource groups, finite multihit capacity, and chunked parallel execution.

Profiles and import modules

profile_store.py persists instrument profiles, repairs older JSON definitions, and resolves profile names robustly. The service layer and MCP tools now expose structured instrument-profile drafting/finalisation workflows tied to vendor documentation.

python/frontend/

The repository includes a React/Vite browser client. It is currently a secondary interface and still uses some compatibility HTTP routes, but it is a real module in the codebase and should be documented as such rather than ignored.