LDMX Software
ldmx::PulseFitter Class Reference

Fits a pulse shape to the ADC samples of a single readout channel to extract hit amplitude and time. More...

#include <PulseFitter.h>

Classes

struct  FitResult
 

Public Member Functions

 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)
 
FitResult fit (const std::vector< short > &samples, const std::vector< bool > &used={}) const
 Fit the pulse to the given ADC sample vector.
 
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.
 
void setZSThreshold (double thr_adc)
 Zero-suppression threshold [ADC over pedestal] for the samples left out by the mask: a model above it adds ((model − thr)/σ)² to χ², so the fit cannot hide the pulse in suppressed samples.
 

Private Member Functions

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.
 

Private Attributes

const PulseShape * shape_
 
double t0_offset_ns_
 
double sampling_interval_ns_
 
double pedestal_adc_
 
double inv_sigma2_
 1/σ², pre-computed.
 
double t_scan_min_ns_
 
double t_scan_max_ns_
 
double t_scan_step_ns_
 
double zs_threshold_adc_ {0.}
 

Detailed Description

Fits a pulse shape to the ADC samples of a single readout channel to extract hit amplitude and time.

Algorithm

With N ADC samples and 2 free parameters (amplitude A and hit time T), the chi-squared is:

χ²(T) = Σ_i [(S_i − ped − A(T)·f(t_i − T)) / σ]²

where t_i = t0_offset + i·Δt are the sample times and f is the pulse shape. For each candidate T, A is solved analytically:

A(T) = Σ_i (S_i − ped)·f(t_i − T) / Σ_i f(t_i − T)²

A 1-D scan over T followed by a parabolic refinement near the minimum gives the fitted values. This is O(n_scan × N_samples) per strip and runs in < 1 µs. In a masked fit (zero suppression) with a flat χ² minimum, e.g. one kept sample, T is the middle of the flat range.

The fit result t0 is defined as T − t0_offset, i.e. the hit arrival time relative to sample 0. A value of t0 = tp (peaking time) means the pulse peak coincides with sample 0.

Timing convention

Sample i is taken at time t_i = t0_offset_ns + i · sampling_interval_ns The pulse shape is evaluated at f(t_i − T) where T is the absolute hit arrival time in the same frame. The output t0 = T is stored directly so the caller can subtract their own reference as needed.

Definition at line 41 of file PulseFitter.h.

Constructor & Destructor Documentation

◆ PulseFitter()

ldmx::PulseFitter::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 )
Parameters
shapePulse shape function (owned externally).
t0_offset_nsTime of sample 0 in the hit-time frame [ns].
sampling_interval_nsInterval between samples [ns].
pedestal_adcPer-sample pedestal [ADC counts].
noise_sigma_adcPer-sample noise RMS [ADC counts], used for χ².
t_scan_min_nsLower bound of the T scan range [ns].
t_scan_max_nsUpper bound of the T scan range [ns].
t_scan_step_nsStep size of the coarse T scan [ns].

Definition at line 24 of file PulseFitter.cxx.

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) {}
double inv_sigma2_
1/σ², pre-computed.

Member Function Documentation

◆ evalAtT()

std::pair< double, double > ldmx::PulseFitter::evalAtT ( const std::vector< short > & samples,
double T,
const std::vector< bool > & used ) const
private

Evaluate χ²(T) and the corresponding best-fit amplitude.

Definition at line 41 of file PulseFitter.cxx.

43 {
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}
virtual double eval(double t) const =0
Evaluate the peak-normalised pulse amplitude at time t [ns] after charge arrival.

References ldmx::PulseShape::eval(), and inv_sigma2_.

Referenced by fit(), and fitFixed().

◆ fit()

PulseFitter::FitResult ldmx::PulseFitter::fit ( const std::vector< short > & samples,
const std::vector< bool > & used = {} ) const

Fit the pulse to the given ADC sample vector.

Parameters
samplesADC values (one per sample, any integer type cast to short).
usedSamples to fit, e.g. not zero suppressed; empty = all.

Definition at line 93 of file PulseFitter.cxx.

94 {
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}
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.

References ldmx::PulseFitter::FitResult::amplitude, ldmx::PulseFitter::FitResult::chi2, ldmx::PulseFitter::FitResult::converged, evalAtT(), ldmx::PulseFitter::FitResult::ndf, and ldmx::PulseFitter::FitResult::t0.

Referenced by ecal::EcalRecProducer::produce(), and tracking::reco::SiStripWaveformFitProcessor::produce().

◆ fitFixed()

PulseFitter::FitResult ldmx::PulseFitter::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.

from another detector.

Parameters
samplesADC values (one per sample).
THit time in the same frame as t0_offset [ns].
usedSamples to fit, e.g. not zero suppressed; empty = all.

Definition at line 187 of file PulseFitter.cxx.

189 {
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}

References ldmx::PulseFitter::FitResult::amplitude, ldmx::PulseFitter::FitResult::chi2, ldmx::PulseFitter::FitResult::converged, evalAtT(), ldmx::PulseFitter::FitResult::ndf, and ldmx::PulseFitter::FitResult::t0.

Referenced by ecal::EcalRecProducer::produce().

◆ setZSThreshold()

void ldmx::PulseFitter::setZSThreshold ( double thr_adc)
inline

Zero-suppression threshold [ADC over pedestal] for the samples left out by the mask: a model above it adds ((model − thr)/σ)² to χ², so the fit cannot hide the pulse in suppressed samples.

≤ 0 (default) turns it off.

Definition at line 96 of file PulseFitter.h.

96{ zs_threshold_adc_ = thr_adc; }

Referenced by ecal::EcalRecProducer::produce().

Member Data Documentation

◆ inv_sigma2_

double ldmx::PulseFitter::inv_sigma2_
private

1/σ², pre-computed.

Definition at line 107 of file PulseFitter.h.

Referenced by evalAtT().

◆ pedestal_adc_

double ldmx::PulseFitter::pedestal_adc_
private

Definition at line 106 of file PulseFitter.h.

◆ sampling_interval_ns_

double ldmx::PulseFitter::sampling_interval_ns_
private

Definition at line 105 of file PulseFitter.h.

◆ shape_

const PulseShape* ldmx::PulseFitter::shape_
private

Definition at line 103 of file PulseFitter.h.

◆ t0_offset_ns_

double ldmx::PulseFitter::t0_offset_ns_
private

Definition at line 104 of file PulseFitter.h.

◆ t_scan_max_ns_

double ldmx::PulseFitter::t_scan_max_ns_
private

Definition at line 109 of file PulseFitter.h.

◆ t_scan_min_ns_

double ldmx::PulseFitter::t_scan_min_ns_
private

Definition at line 108 of file PulseFitter.h.

◆ t_scan_step_ns_

double ldmx::PulseFitter::t_scan_step_ns_
private

Definition at line 110 of file PulseFitter.h.

◆ zs_threshold_adc_

double ldmx::PulseFitter::zs_threshold_adc_ {0.}
private

Definition at line 111 of file PulseFitter.h.

111{0.};

The documentation for this class was generated from the following files: