Calibration¶
Calibration fits the detector's optical parameters (scattering and absorption lengths, reflectivities, QE) and one efficiency per PMT to the charge seen from known light sources, by gradient-based fitting through the forward model. It uses lasers and flashers, not a particle emitter.
Runnable: examples/hello_calibrate.py (seven parameters and 10764 per-PMT gains, about 4
minutes on a GPU) and examples/hello_calibrate_own_optimiser.py (one problem, four solvers).
Both fit scalar optics (wavelength_mode=False).
Minimal calibration¶
The core of examples/hello_calibrate.py:
det = generate_detector(GEOM)
NS = len(det.all_points)
top, bot, R = det.H / 2 - 0.1, -det.H / 2 + 0.1, det.r
# truth optics; per-PMT qe_corrections is the gain map (the fit profiles it)
dp = DetectorParams.from_flat(
scatter_length=70.0,
mie_scatter_length=3000.0,
g=0.9,
wall_reflection_rate=0.2,
sensor_reflection_rate=0.2,
absorption_length=60.0,
qe=0.07,
qe_corrections=jnp.ones(NS),
)
# source diversity is the lever: lasers from the caps and the wall, and an isotropic flasher
sources = [
laser_source(position=[0, 0, top], direction=[0, 0, -1], intensity=1e6),
laser_source(position=[0, 0, bot], direction=[0, 0, 1], intensity=1e6),
laser_source(position=[R - 0.1, 0, 0], direction=[-1, 0, 0], intensity=1e6),
isotropic_source(position=[0, 0, 0], intensity=1e6),
]
sim = setup_event_simulator(
GEOM,
n_photons,
source="light_source",
temperature=None,
K=8,
wavelength_mode=False,
n_cap=100,
n_angular=150,
n_height=100,
)
params = FieldParams(dp, FIELDS) # fit these leaves of dp, in log space
model = CalibrationForward(sim, sources, params) # predicted charge, every source
theta_true = params.theta_from_physical()
# Closure data: the model at truth with a 5% per-PMT gain spread baked in, averaged over 8
# draws (closure_data's default, as the paper's calibration does). With real data: the
# observed (n_sources, n_sensors) charge.
rng = np.random.default_rng(0)
k_true = np.exp(rng.normal(0.0, 0.05, NS))
k_true /= np.exp(np.mean(np.log(k_true)))
data = closure_data(model, theta_true, k_true)
problem = CalibrationProblem(model, data, jacobian_draws=2)
start = theta_true + rng.uniform(-0.15, 0.15, params.P)
res = calibrate(problem, start, steps=steps, refresh=15, max_step=0.08, polyak=0)
sigma = crb(model, theta_true)["sigma"] # Cramer-Rao bound, fractional, per field
# res['real']: the fitted globals (compare params.to_real(theta_true)); res['gains']: the gains
The pieces, all in lucid.fitting:
FieldParams(dp, fields): whichDetectorParamsfields to fit, in log space; the rest ofdpstays fixed.params.theta_from_physical()isdpas a fit vector,params.to_real(theta)the reverse.CalibrationForward(sim, sources, params): the model, the predicted charge of every source.simis asource='light_source'simulator.closure_data(model, theta, gains, n_draws=8): pseudo-data from the model at known parameters and gains. With real data, use the observed charge, shape(n_sources, n_sensors).CalibrationProblem(model, data): the model, the data and the estimator.calibrate(problem, theta0): the fit. It returns a dict with the fitted parameters ('real') and the per-PMT gains ('gains').crb(model, theta): the Cramér-Rao bound, from the model alone.
Run the closure test first on a new detector: you set the truth, so a poor recovery is a
property of the setup (sources, photon count, parameterisation) and not of the data. Average the
pseudo-data over several draws (n_draws=8, the default): the estimator weights each sensor by
its observed charge, and one noisy draw at about 1.6 photoelectrons per sensor biases the fit.
calibrate defaults: 600 steps, a Jacobian rebuild every 20 (refresh), a 0.5 clip on each
log-space step (max_step), and the mean of the last 50 iterates as the result (polyak).
CalibrationProblem averages 8 Jacobian draws (jacobian_draws). The example lowers these for
speed. The paper's working point (CALIB in analysis/paper/utils/calibration.py) runs 1200
steps: the diffuse wall and sensor reflectances need about that many, while the other
parameters settle by about 300.
To hold parameters fixed, fit fewer fields, or keep the layout and pass
calibrate(problem, theta0, fix=[...]).
Choosing a solver¶
The snippets are from examples/hello_calibrate_own_optimiser.py, which runs all four from one
start and prints them against the bound.
The default, damped Gauss-Newton with the per-PMT gains profiled (tx=gauss_newton_tx(lam, mu)
changes the damping):
gn = calibrate(problem, start, steps=steps, refresh=3, polyak=20)
Any optax rule, on the same driver (step clip, Polyak readout and fix still apply):
adam = calibrate(problem, start, tx=optax.adam(2e-2), steps=steps, refresh=3, polyak=20)
Your own loop: problem.grad_metric_loss(theta, step) returns the gradient Jᵀr (gains
profiled), the metric JᵀJ and the loss; step selects the random draw:
opt = optax.adam(2e-2)
theta = jnp.asarray(start, jnp.float32)
state = opt.init(theta)
for step in range(steps):
g, _, loss = problem.grad_metric_loss(theta, step)
updates, state = opt.update(g, state)
theta = optax.apply_updates(theta, updates)
scipy, on one fixed draw so the objective is deterministic:
sol = least_squares(
lambda t: np.ravel(problem.residuals(t, step=0)),
start,
jac=lambda t: np.reshape(problem.jacobian(t, step=0), (-1, params.P)),
max_nfev=steps,
)
First-order rules such as Adam move slowly along stiff directions (Mie, g, the
reflectivities), which is why Gauss-Newton is the default.
What can be fitted¶
Any leaf of DetectorParams (parameters) can be named in
FieldParams. The usual ones are scatter_length (Rayleigh), mie_scatter_length with g,
absorption_length, wall_reflection_rate, sensor_reflection_rate and qe. The per-PMT
gains are qe_corrections, profiled rather than fitted (below). The refractive index is not a
parameter.
The reflection model is a simulator argument. The default 'scalar_mix' adds the
specular/diffuse fractions wall_fspec and sensor_fspec as fittable parameters without
needing wavelength mode. 'angular' makes the reflectance depend on angle and wavelength
(Schlick wall wall_R0, wall_p; Fresnel cathode cathode_nr, cathode_nk), evaluated at
reflection_wavelength (default 400 nm).
The estimator¶
- Sources. Mix lasers at several positions (and wavelengths) with an isotropic flasher. One source alone leaves pairs such as Mie length and gains, absorption and QE, or wall and sensor reflectivity degenerate.
- Residual. The Neyman χ² residual
(k·M − Q)/√max(Q, q_floor), withMthe predicted andQthe observed charge. Its weight depends on the data only, so it is linear in the Monte-Carlo forward, which is redrawn every step. A residual nonlinear in the forward would converge to a biased point. - Gains. The per-PMT gains
k = ΣQ/ΣMare solved in closed form at every step and fixed tomean(log k) = 0(gauge='linear'givesmean(k) = 1). They never enter the optimiser. The profiled gain has a bias that grows with the forward's noise;CalibrationProblem(..., n_forward_draws=N)averages draws to reduce it. - Correlated QE trends. A smooth, position-dependent QE pattern mimics the optical parameters and can pull the reflectivities off.
Charge constrains most parameters. First-arrival timing is nearly independent of absorption and
constrains reflection and scattering geometry, but at detector scale it does not measure the
Mie length. lucid.fitting.calibrate_timing recovers per-PMT t0 and the global TTS from
per-PMT first-arrival means and variances over many flashes.
Per-wavelength optics¶
CalibrationParams(n_wavelengths=W) fits a separate scattering length, absorption length and
QE at each of W laser wavelengths, with the gains and the four reflection parameters shared.
This is the paper's estimand (five SK laser lines). Mie is held fixed in it.
Fitting the wavelength deviation curves instead (FieldParams(dp, ['abs_dev', ...]) with
wavelength_mode=True and monochromatic sources, laser_source(..., wavelength=405)) is
implemented but has not been validated end to end. A QE fit must keep
wavelength_sampling='cherenkov' (optics).
Uncertainty¶
crb(model, theta)['sigma'] is the fractional Cramér-Rao bound per parameter, from the
autodiff Fisher information of the Poisson likelihood; it needs no data and marginalises the
per-PMT gains. The expected-value forward has less variance than real shot noise, so the bound
is inflated by √12 by default (honesty=; cov_raw is the uninflated covariance). For the same
reason, a closure fit on expected-value pseudo-data looks better than a real one; to test against
shot noise, generate the data with transport='sampled', detection='sampled'.
If the calibration misbehaves¶
- Parameters trade off, or the bound is huge in some direction: add source diversity.
- The fit settles at a biased point on closure data: average more draws (
n_draws), raise the photon count, or average forward draws (n_forward_draws). - The diffuse reflectances have not converged: run more steps (the paper uses 1200).