LDMX Software
PulseFitter.cxx
1#include "Tools/PulseFitter.h"
2
3#include <algorithm>
4#include <cmath>
5#include <limits>
6#include <tuple>
7#include <vector>
8
9namespace ldmx {
10
11namespace {
12// empty mask: every sample is used
13bool isUsed(const std::vector<bool>& used, std::size_t i) {
14 return used.empty() || used.at(i);
15}
16
17int nUsed(const std::vector<short>& samples, const std::vector<bool>& used) {
18 int n = 0;
19 for (std::size_t i = 0; i < samples.size(); ++i) n += isUsed(used, i);
20 return n;
21}
22} // namespace
23
24PulseFitter::PulseFitter(const PulseShape& shape, double t0_offset_ns,
25 double sampling_interval_ns, double pedestal_adc,
26 double noise_sigma_adc, double t_scan_min_ns,
27 double t_scan_max_ns, double t_scan_step_ns)
28 : shape_(&shape),
29 t0_offset_ns_(t0_offset_ns),
30 sampling_interval_ns_(sampling_interval_ns),
31 pedestal_adc_(pedestal_adc),
32 inv_sigma2_(1.0 / (noise_sigma_adc * noise_sigma_adc)),
33 t_scan_min_ns_(t_scan_min_ns),
34 t_scan_max_ns_(t_scan_max_ns),
35 t_scan_step_ns_(t_scan_step_ns) {}
36
37// ---------------------------------------------------------------------------
38// Private helper: chi2 and amplitude for a fixed hit time T
39// ---------------------------------------------------------------------------
40
41std::pair<double, double> PulseFitter::evalAtT(
42 const std::vector<short>& samples, double T,
43 const std::vector<bool>& used) const {
44 const int n = static_cast<int>(samples.size());
45
46 // Evaluate pulse shape at each sample time.
47 // t_i = t0_offset + i * dt → argument to shape = t_i - T
48 double sum_sf = 0.0; // Σ (S_i - ped) * f_i
49 double sum_f2 = 0.0; // Σ f_i²
50
51 for (int i = 0; i < n; ++i) {
52 if (!isUsed(used, i)) continue;
53 const double t_arg = t0_offset_ns_ + i * sampling_interval_ns_ - T;
54 const double fi = shape_->eval(t_arg);
55 const double si = static_cast<double>(samples[i]) - pedestal_adc_;
56 sum_sf += si * fi;
57 sum_f2 += fi * fi;
58 }
59
60 // Degenerate: pulse shape is zero everywhere in the window.
61 if (sum_f2 < 1.0e-12) {
62 return {std::numeric_limits<double>::max(), 0.0};
63 }
64
65 const double amplitude = sum_sf / sum_f2;
66
67 // Compute chi2 for this (T, amplitude) pair.
68 double chi2 = 0.0;
69 for (int i = 0; i < n; ++i) {
70 if (!isUsed(used, i)) {
71 // suppressed sample: penalize a model above the ZS threshold
72 if (zs_threshold_adc_ > 0.) {
73 const double t_arg = t0_offset_ns_ + i * sampling_interval_ns_ - T;
74 const double over = amplitude * shape_->eval(t_arg) - zs_threshold_adc_;
75 if (over > 0.) chi2 += over * over * inv_sigma2_;
76 }
77 continue;
78 }
79 const double t_arg = t0_offset_ns_ + i * sampling_interval_ns_ - T;
80 const double fi = shape_->eval(t_arg);
81 const double si = static_cast<double>(samples[i]) - pedestal_adc_;
82 const double resid = si - amplitude * fi;
83 chi2 += resid * resid * inv_sigma2_;
84 }
85
86 return {chi2, amplitude};
87}
88
89// ---------------------------------------------------------------------------
90// Public: fit
91// ---------------------------------------------------------------------------
92
93PulseFitter::FitResult PulseFitter::fit(const std::vector<short>& samples,
94 const std::vector<bool>& used) const {
95 FitResult result;
96 result.ndf = nUsed(samples, used) - 2;
97
98 // Quick sanity: check that at least one sample is above pedestal.
99 bool any_signal = false;
100 for (std::size_t i = 0; i < samples.size(); ++i) {
101 if (isUsed(used, i) && static_cast<double>(samples[i]) > pedestal_adc_) {
102 any_signal = true;
103 break;
104 }
105 }
106 if (!any_signal) {
107 return result; // converged = false
108 }
109
110 // -------------------------------------------------------------------
111 // Coarse scan over T to find the approximate minimum.
112 // -------------------------------------------------------------------
113 std::vector<double> scan_t, scan_chi2, scan_amp;
114 for (double t = t_scan_min_ns_; t <= t_scan_max_ns_; t += t_scan_step_ns_) {
115 auto [chi2, amp] = evalAtT(samples, t, used);
116 scan_t.push_back(t);
117 scan_chi2.push_back(chi2);
118 scan_amp.push_back(amp);
119 }
120 if (scan_t.empty()) {
121 return result; // converged = false
122 }
123
124 const std::size_t i_best = static_cast<std::size_t>(
125 std::min_element(scan_chi2.begin(), scan_chi2.end()) - scan_chi2.begin());
126 double best_chi2 = scan_chi2[i_best];
127 double best_t = scan_t[i_best];
128 double best_amp = scan_amp[i_best];
129
130 // Masked fit with a flat minimum: T is not constrained, e.g. a single kept
131 // sample fits exactly for any T where the suppressed samples stay below
132 // threshold. Take the middle of the flat range; its first point would
133 // give the largest amplitude the threshold allows. Full-sample fits keep
134 // the first minimum.
135 std::size_t i_lo = i_best, i_hi = i_best;
136 const bool masked = nUsed(samples, used) < static_cast<int>(samples.size());
137 if (masked && best_chi2 < std::numeric_limits<double>::max()) {
138 const double flat = best_chi2 + 1.0e-6 * (1.0 + best_chi2);
139 while (i_lo > 0 && scan_chi2[i_lo - 1] <= flat) --i_lo;
140 while (i_hi + 1 < scan_t.size() && scan_chi2[i_hi + 1] <= flat) ++i_hi;
141 }
142 if (i_hi > i_lo) {
143 best_t = 0.5 * (scan_t[i_lo] + scan_t[i_hi]);
144 std::tie(best_chi2, best_amp) = evalAtT(samples, best_t, used);
145 } else if (i_best > 0 && i_best + 1 < scan_t.size() &&
146 scan_chi2[i_best - 1] > best_chi2 &&
147 scan_chi2[i_best + 1] > best_chi2) {
148 // -----------------------------------------------------------------
149 // Parabolic refinement around the minimum.
150 // -----------------------------------------------------------------
151 const double t_lo = scan_t[i_best - 1], chi2_lo = scan_chi2[i_best - 1];
152 const double t_hi = scan_t[i_best + 1], chi2_hi = scan_chi2[i_best + 1];
153 // Fit a parabola through (T_lo, chi2_lo), (best_T, best_chi2), (T_hi,
154 // chi2_hi).
155 const double d1 = best_t - t_lo;
156 const double d2 = t_hi - best_t;
157 const double dc1 = chi2_lo - best_chi2;
158 const double dc2 = chi2_hi - best_chi2;
159 // Vertex of parabola: ΔT = (d2²·dc1 - d1²·dc2) / (2·(d1·dc2 + d2·dc1))
160 const double denom = 2.0 * (d1 * dc2 + d2 * dc1);
161 if (std::abs(denom) > 1.0e-12) {
162 const double delta = (d2 * d2 * dc1 - d1 * d1 * dc2) / denom;
163 // Only accept the refinement if it stays within the bracket.
164 if (std::abs(delta) < std::max(d1, d2)) {
165 const double t_refined = best_t + delta;
166 auto [chi2_ref, amp_ref] = evalAtT(samples, t_refined, used);
167 if (chi2_ref < best_chi2) {
168 best_t = t_refined;
169 best_amp = amp_ref;
170 best_chi2 = chi2_ref;
171 }
172 }
173 }
174 }
175
176 result.amplitude = best_amp;
177 result.t0 = best_t;
178 result.chi2 = best_chi2;
179 result.converged = true;
180 return result;
181}
182
183// ---------------------------------------------------------------------------
184// Public: fitFixed
185// ---------------------------------------------------------------------------
186
188 const std::vector<short>& samples, double T,
189 const std::vector<bool>& used) const {
190 FitResult result;
191 result.ndf = nUsed(samples, used) - 1;
192 auto [chi2, amp] = evalAtT(samples, T, used);
193 result.amplitude = amp;
194 result.t0 = T;
195 result.chi2 = chi2;
196 result.converged = chi2 < std::numeric_limits<double>::max();
197 return result;
198}
199
200} // namespace ldmx
std::pair< double, double > evalAtT(const std::vector< short > &samples, double T, const std::vector< bool > &used) const
Evaluate χ²(T) and the corresponding best-fit amplitude.
FitResult fitFixed(const std::vector< short > &samples, double T, const std::vector< bool > &used={}) const
Amplitude only fit with the hit time T known, e.g.
FitResult fit(const std::vector< short > &samples, const std::vector< bool > &used={}) const
Fit the pulse to the given ADC sample vector.
PulseFitter(const PulseShape &shape, double t0_offset_ns, double sampling_interval_ns, double pedestal_adc, double noise_sigma_adc, double t_scan_min_ns=-50.0, double t_scan_max_ns=150.0, double t_scan_step_ns=1.0)
double inv_sigma2_
1/σ², pre-computed.
Abstract base class for front-end readout pulse shapes.
Definition PulseShape.h:30
virtual double eval(double t) const =0
Evaluate the peak-normalised pulse amplitude at time t [ns] after charge arrival.
double chi2
Chi-squared value at the minimum.
Definition PulseFitter.h:50
bool converged
False if no above-pedestal samples found.
Definition PulseFitter.h:52
double t0
Fitted hit arrival time T [ns].
Definition PulseFitter.h:49
double amplitude
Fitted peak amplitude [ADC counts], ped-subtracted.
Definition PulseFitter.h:47
int ndf
Degrees of freedom = n_used_samples − 2.
Definition PulseFitter.h:51