Add common measurement-error models for synthetic diagnostics

[HongSik-Yun-Fusion]

Objective

Add a common measurement error / noise API to VAFT so synthetic diagnostics can reproduce realistic measurement uncertainty.

VAFT already contains forward models and signal-processing functionality for several diagnostics, including magnetics, but there is no common interface for applying measurement noise or calibration uncertainty to synthetic signals in a consistent way.

This work should use magnetics as the first consumer while providing a machine-independent API that can later be reused by Thomson scattering, SXR, cameras, interferometers, and other diagnostics.

Design principles

Synthetic diagnostics should keep the following stages separate:

physics state
    ↓
ideal diagnostic forward model
    ↓
ideal signal
    ↓
measurement / instrument error model
    ↓
synthetic measurement
    ↓
normal VAFT processing

Existing forward models should remain noise-free. Noise and calibration errors should not be embedded directly into forward models such as synthetic_vacuum_magnetics.

The API should also distinguish between two broad classes of uncertainty:

• stochastic noise that varies sample by sample
  • Gaussian additive noise
  • future extensions: colored noise, photon noise, etc.
• systematic errors that are fixed for a realization or channel
  • gain error
  • offset
  • geometry/calibration uncertainty, etc.

Proposed structure

The initial implementation should follow VAFT's existing formula → process → omas layering.

vaft/
├── formula/
│   └── noise.py
│
├── process/
│   └── synthetic.py
│
└── omas/
    └── synthetic_magnetics.py

vaft.formula.noise

Provide pure stochastic kernels that do not depend on ODS or on a specific diagnostic.

Initial candidates:

• Gaussian noise
• random walk
• correlated Gaussian noise

Random-number generation should use an explicitly passed numpy.random.Generator rather than global RNG state.

vaft.process.synthetic

Provide the common API for applying measurement errors to an ideal signal.

Initial error-model candidates:

• GaussianNoise
• GainError
• OffsetError
• RandomWalkDrift
• MeasurementModel
• SyntheticMeasurement

Conceptual usage:

model = MeasurementModel(
    errors=(
        GainError(relative_sigma=0.02),
        OffsetError(sigma=...),
        RandomWalkDrift(step_sigma=...),
        GaussianNoise(sigma=...),
    )
)

result = simulate_measurement(
    signal,
    time,
    model=model,
    rng=rng,
)

The result should at minimum distinguish:

result.ideal
result.measured
result.realization

Where useful, the realized gain, offset, drift, and other nuisance parameters should also be inspectable.

Magnetics integration

Magnetics should be the first consumer of the common API.

The common measurement model should be applicable to ideal flux / magnetic-field signals produced by the existing magnetic forward model.

Example:

ideal = synthetic_magnetics(...)

synthetic = perturb_magnetics(
    ideal,
    model=model,
    seed=42,
)

Do not overwrite existing measured diagnostic ODS data with synthetic data.

In particular, preserve the current noise-free behavior of the forward model used by vacuum-magnetics validation.

Geometry uncertainty

Probe-position and poloidal_angle uncertainty should be treated separately from ordinary waveform perturbations because they are forward-model input uncertainties rather than noise added to a completed signal.

A future extension could use a pipeline such as:

nominal geometry
    ↓
geometry realization
    ↓
magnetic forward model
    ↓
ideal instrument signal
    ↓
measurement error model

Geometry uncertainty is not required for the initial implementation.

Reproducibility / provenance

Synthetic measurements should be deterministically reproducible.

• Do not use global random state.
• Use an explicit seed or numpy.random.Generator.
• Where practical, preserve the realized nuisance parameters in the result.

If only the seed is stored, future changes in channel ordering or implementation details may prevent exact reproduction. The design should therefore allow the actual realization itself to be recorded.

v1 scope

• Add vaft.formula.noise
• Gaussian additive noise
• gain error
• offset error
• random-walk drift
• deterministic RNG handling
• measurement-model composition API
• result object separating ideal / measured / realization
• adapter for applying the model to synthetic magnetics
• unit tests
• minimal usage example or documentation

Follow-up scope

The following are explicitly out of scope for this issue and should be considered future extensions:

• colored noise / measured PSD
• channel-to-channel covariance
• PF/TF electromagnetic pickup
• sensor position / orientation uncertainty
• timing jitter
• analog transfer function / anti-alias filtering
• ADC quantization
• Thomson / SXR / camera photon statistics
• empirical machine-specific noise calibration
• ODS schema for storing synthetic diagnostic realizations

Completion criteria

• The same seed / realization reproduces the same synthetic measurement.
• Ideal signals and perturbed measurements remain clearly separated.
• Existing magnetics forward-model and vacuum-validation results are unchanged.
• Noise/error kernels are independent of a specific machine or diagnostic.
• The measurement-model primitives can be reused by diagnostics other than magnetics.