Reconstruction parameters

LARDON uses a two-level parameter system:

Global defaults — loaded from $LARDON_PATH/settings/default_reco_parameters.json for every run.
Detector overrides — loaded from $LARDON_PATH/settings/{detector}/reco_parameters.json on top of the defaults.
Run-range overrides — within the detector file, keys of the form "runstart-runend" are applied when the run number falls in that range.

The detector file must have a "default" section (applied to all runs) and may have additional run-range sections. Only the first matching run-range section is applied.

default_reco_parameters.json   ← always loaded
        ↓ overridden by
{detector}/reco_parameters.json["default"]   ← always loaded for that detector
        ↓ overridden by
{detector}/reco_parameters.json["runstart-runend"]   ← applied when run matches

Both files use JSONC (JSON with comments). C-style block comments (/* */) and line comments (//) are valid anywhere in these files.

To inspect the parameters actually used for a given run, LARDON prints them at startup when run with verbose output. You can also call reconstruction_parameters.dump() programmatically.

Parameter reference

`pedestal`

Controls the iterative RMS-based pedestal estimation used to define regions of interest (ROIs).

Parameter	Default	Description
`raw_rms_thr`	`3`	RMS multiplier for the initial ROI seed. Samples above `raw_rms_thr × RMS` are considered signal.
`n_iter`	`2`	Number of iterations for the ROI-constrained RMS computation. More iterations converge to a cleaner baseline estimate.

`mask`

Fine-grained ROI masking applied after the pedestal step. Parameters differ between collection (unipolar) and induction (bipolar) views.

`mask.coll` — collection views

Parameter	Default	Description
`min_dt`	`10`	Minimum ROI duration in ticks. Shorter regions are discarded.
`low_thr`	`[2.0, 2.0]`	Two-pass low RMS threshold `[first_pass, second_pass]` for the ROI opening.
`high_thr`	`[5.0, 3.0]`	Two-pass high RMS threshold `[first_pass, second_pass]` for peak confirmation.
`min_rise`	`3`	Minimum number of ticks on the rising edge of a pulse.
`min_fall`	`8`	Minimum number of ticks on the falling edge of a pulse.
`pad_bef`	`10`	Ticks added before the ROI start.
`pad_aft`	`15`	Ticks added after the ROI end.

`mask.ind` — induction views

Induction signals are bipolar (positive then negative lobe). Parameters are split into pos (positive lobe) and neg (negative lobe) sub-sections, plus shared parameters. Shared:

Parameter	Default	Description
`max_dt_pos_neg`	`20`	Maximum allowed tick separation between positive and negative lobes of the same bipolar signal.
`pad_bef`	`10`	Ticks added before the ROI start.
`pad_aft`	`15`	Ticks added after the ROI end.

mask.ind.pos — positive lobe:

Parameter	Default	Description
`min_dt`	`8`	Minimum duration of the positive lobe in ticks.
`low_thr`	`[1.8, 2.0]`	Two-pass low RMS threshold.
`high_thr`	`[2.5, 3.0]`	Two-pass high RMS threshold.
`min_rise`	`3`	Minimum rising-edge ticks.
`min_fall`	`1`	Minimum falling-edge ticks.

mask.ind.neg — negative lobe:

Parameter	Default	Description
`min_dt`	`8`	Minimum duration of the negative lobe in ticks.
`low_thr`	`[-1.8, -1.8]`	Two-pass low RMS threshold (negative values).
`high_thr`	`[-2.5, -2.5]`	Two-pass high RMS threshold (negative values).
`min_rise`	`1`	Minimum rising-edge ticks.
`min_fall`	`3`	Minimum falling-edge ticks.

`noise`

`noise.coherent` — coherent noise subtraction

Groups of channels sharing the same front-end card exhibit correlated (coherent) noise. LARDON subtracts the median waveform of each group.

Parameter	Default	Description
`groupings`	`[32]`	List of group sizes for coherent noise subtraction. Each value defines a grouping level.
`per_view`	`0`	If `1`, perform coherent subtraction per view rather than per card.
`per_view_per_card`	`1`	If `1`, perform coherent subtraction per view within each card group (default mode).
`capa_weight`	`0`	If `1`, weight channel contributions by their capacitance when computing the group median.
`calibrated`	`0`	If `1`, use calibrated channel gains when computing the coherent noise estimate.

`noise.fft` — FFT low-pass filter

Parameter	Default	Description
`freq`	`-1`	Frequency in MHz of a notch filter to remove a specific noise line. Set to `-1` to disable.
`low_cut`	`0.6`	Low-pass cutoff frequency in MHz. Frequencies above this value are attenuated.
`gaus_sigma`	`0.02`	Gaussian roll-off width in MHz for the low-pass filter edge.

`noise.microphonic` — microphonic noise removal

Parameter	Default	Description
`window`	`-1`	Size of the sliding median window in ticks for microphonic noise removal. Set to `-1` to disable.

`hit_finder`

`hit_finder.coll` — collection hit finding

Parameter	Default	Description
`amp_sig`	`[2.5, 5.5]`	Two-threshold amplitude in units of RMS: `[low_threshold, high_threshold]`. A hit is seeded at `high_threshold` and extends down to `low_threshold`.

`hit_finder.ind` — induction hit finding

Parameter	Default	Description
`amp_sig`	`2.0`	Amplitude threshold in units of RMS for induction hits.
`merge_tdc_thr`	`10`	Maximum tick gap between two adjacent induction hit candidates to merge them into one.

Shared hit-finder parameters

Parameter	Default	Description
`dt_min`	`10`	Minimum hit duration in ticks. Hits shorter than this are rejected.
`min_thr`	`0.5`	Absolute minimum amplitude threshold in RMS units.
`pad.left`	`10`	Ticks prepended to each hit window.
`pad.right`	`20`	Ticks appended to each hit window.

`track_2d`

Parameters for building 2D track segments within a single wire view using a Hough-transform seed and a Kalman-filter extension.

Parameter	Default	Description
`min_nb_hits`	`5`	Minimum number of hits required to form a 2D track.
`rcut`	`6.0`	Search radius in mm for associating hits to a track candidate.
`chi2cut`	`8.0`	Maximum χ² per degree of freedom for adding a hit to an existing track.
`y_error`	`0.5`	Initial position error estimate for the Kalman filter (in mm).
`slope_error`	`1.0`	Initial slope error estimate for the Kalman filter.
`pbeta`	`3.0`	Momentum–velocity product estimate used in the Kalman filter (in MeV).
`slope_max`	`50`	Maximum allowed track slope. Tracks steeper than this are rejected.
`hough_win_X`	`10.0`	Hough transform accumulator window in the X direction (mm).
`hough_win_Z`	`20.0`	Hough transform accumulator window in the Z direction (mm).
`hough_n_min`	`5`	Minimum number of hits in a Hough bin to declare a seed.
`hough_theta_res`	`1.0`	Angular resolution of the Hough accumulator in degrees.
`hough_rho_res`	`0.25`	Distance resolution of the Hough accumulator in mm.
`hough_min_score`	`4`	Minimum Hough score to accept a seed.
`max_gap`	`2.0`	Maximum gap in mm between consecutive hits along a track.
`dray_thr`	`2.0`	Delta-ray detection threshold (in RMS units).
`dray_dmax`	`6.0`	Maximum distance in mm to associate a hit with a delta ray.

`stitching_2d`

Parameters for stitching together 2D track segments within a module or across modules informed by 3D reconstruction.

Section	Parameter	Default	Description
`in_module`	`align_thr`	`0.98`	Minimum alignment (dot product) between track directions to stitch within a module.
`in_module`	`dma_thr`	`3.0`	Maximum distance of minimum approach in mm.
`in_module`	`dist_thr`	`10.0`	Maximum endpoint-to-endpoint distance in mm.
`from_3d`	`align_thr`	`0.96`	Alignment threshold when stitching using 3D information.
`from_3d`	`dma_thr`	`8.0`	Distance of minimum approach threshold when using 3D information (mm).
`from_3d`	`dist_thr`	`15.0`	Endpoint distance threshold when using 3D information (mm).

`track_3d`

Parameters for assembling 3D tracks from 2D segments across wire views.

Parameter	Default	Description
`trk_ztol`	`3.0`	Maximum Z difference in mm at 2D track boundaries for matching across views.
`hit_ztol`	`1.0`	Z tolerance in mm when matching individual hits across views.
`len_min`	`2.0`	Minimum 2D track length in mm to be considered as input to 3D building.
`d_thresh`	`0.5`	Tolerance in mm when searching for a 3D intersection point.
`min_z_overlap`	`10.0`	Minimum Z overlap in mm required between two 2D tracks to attempt 3D matching.
`trk_min_dz`	`15.0`	Minimum Z extent in mm for a 2D track to be considered in 3D matching.
`trk_min_dx`	`8.0`	Minimum X extent in mm for a 2D track to be considered in 3D matching.
`timing.dx_tol`	`[3.0, 0.5]`	X-boundary tolerance in mm per drift volume for timing-based matching.
`timing.dy_tol`	`[3.0, 3.0]`	Y-boundary tolerance in mm per drift volume.
`timing.dz_tol`	`2.0`	Z-boundary tolerance in mm.
`timing.drift_tol`	`10`	Drift-time tolerance in ticks.

`stitching_3d`

Parameters for stitching 3D track segments across module or cathode boundaries.

Section	Parameter	Default	Description
`module`	`dist_thr`	`8.0`	Maximum endpoint distance in mm for module-boundary stitching.
`module`	`align_thr`	`0.98`	Minimum direction alignment for module-boundary stitching.
`module`	`boundary_tol`	`5.0`	Tolerance in mm from the module boundary plane.
`cathode`	`dx_thresh`	`10.0`	Maximum X separation in mm across the cathode.
`cathode`	`dy_thresh`	`10.0`	Maximum Y separation in mm across the cathode.
`cathode`	`dz_thresh`	`10.0`	Maximum Z separation in mm across the cathode.
`cathode`	`align_thresh`	`0.96`	Minimum direction alignment across the cathode.
`cathode`	`boundary_tol`	`5.0`	Tolerance in mm from the cathode plane.

`ghost`

Parameter	Default	Description
`search`	`1`	Enable (`1`) or disable (`0`) ghost track identification.
`dmin`	`10.0`	Minimum distance in mm between a real track and a ghost track candidate.

`single_hit`

Parameters for reconstructing isolated charge deposits not associated with any track.

Parameter	Default	Description
`max_per_view`	`3`	Maximum number of single-hit candidates per view. Events with more candidates are vetoed.
`outlier_dmax`	`2.5`	Maximum distance in mm from the cluster centroid to accept a hit as non-outlier.
`cluster_eps`	`2.0`	DBSCAN epsilon parameter in mm for clustering single-hit candidates.
`dist_veto`	`5.0`	Minimum distance in mm from any track; hits closer than this are vetoed.
`max_bary`	`20.0`	Maximum barycenter displacement in mm.

`pds`

Parameters for reconstructing photon detection system (PDS) waveforms. These are only used when reconstruction is run with the -pds flag.

`pds.pedestal`

Parameter	Default	Description
`raw_adc_thresh`	`200`	ADC threshold for the initial PDS pedestal estimation.
`rms_thresh`	`3`	RMS multiplier for signal ROI detection in PDS waveforms.
`n_iter`	`3`	Number of iterations for PDS pedestal RMS computation.

`pds.noise`

Parameter	Default	Description
`flat_baseline_window`	`4000`	Window size in PDS ticks for flat baseline estimation.

`pds.hit_finder`

Parameter	Default	Description
`amp_sig`	`[5, 8]`	Two-threshold amplitude in RMS units `[low, high]` for PDS peak finding.
`dt_min`	`50`	Minimum PDS hit duration in ticks.
`pad.left`	`30`	Ticks prepended to each PDS hit window.
`pad.right`	`50`	Ticks appended to each PDS hit window.

`pds.cluster`

Parameter	Default	Description
`max_lag`	`50`	Maximum lag in PDS ticks for waveform cross-correlation alignment.
`time_tol`	`5`	Time tolerance in µs for grouping PDS hits into a cluster.

`pds.tpc_matching`

All time tolerances are in µs.

Parameter	Default	Description
`min_cluster_size`	`2`	Minimum number of PDS hits in a cluster to attempt TPC matching.
`trigger.time_tol_bef/aft`	`[5]` / `[5]`	Time window in µs before/after the trigger time.
`anode_crosser.time_tol_bef/aft`	`[5]` / `[5]`	Time window for anode-crossing track matching, per drift volume.
`cathode_crosser.time_tol_bef/aft`	`[5, 5]` / `[5, 5]`	Time window for cathode-crossing track matching, per drift volume.
`unknown.time_tol_bef/aft`	`[5, 5]` / `[5, 5]`	Time window for unclassified track types.
`single_hits.time_tol`	`5`	Time tolerance for matching PDS clusters to single hits.

Detector-specific example: pdvd

The pdvd detector overrides a number of defaults to account for its multi-module geometry. Parameters that accept arrays receive one value per module (4 modules in the default configuration). For example:

{
  "default": {
    "hit_finder": {
      "coll": {
        "amp_sig": [[1.8, 2.4], [1.8, 2.4], [1.6, 2.2], [1.6, 2.2]]
      },
      "ind": {
        "amp_sig": [1.6, 1.6, 1.5, 1.5]
      }
    },
    "noise": {
      "microphonic": {
        "window": 400
      },
      "coherent": {
        "calibrated": 1
      }
    },
    "track_2d": {
      "min_nb_hits": 10
    }
  },
  "42000-99999": {
    "hit_finder": {
      "coll": {
        "amp_sig": [[1.8, 2.8], [1.8, 2.8], [1.8, 2.8], [1.8, 2.8]]
      }
    }
  }
}

Key differences from the global defaults:

hit_finder.coll.amp_sig — per-module, per-pass thresholds instead of a single pair.
noise.microphonic.window — enabled at 400 ticks (disabled by default).
noise.coherent.calibrated — set to 1 to use calibrated gains.
track_2d.min_nb_hits — raised to 10 (global default is 5).

Get Started

Configuration

Running LARDON

Reconstruction Pipeline

Visualization & Output

Reconstruction parameters

Parameter reference

`pedestal`

`mask`

`mask.coll` — collection views

`mask.ind` — induction views

`noise`

`noise.coherent` — coherent noise subtraction

`noise.fft` — FFT low-pass filter

`noise.microphonic` — microphonic noise removal

`hit_finder`

`hit_finder.coll` — collection hit finding

`hit_finder.ind` — induction hit finding

Shared hit-finder parameters

`track_2d`

`stitching_2d`

`track_3d`

`stitching_3d`

`ghost`

`single_hit`

`pds`

`pds.pedestal`

`pds.noise`

`pds.hit_finder`

`pds.cluster`

`pds.tpc_matching`

Detector-specific example: pdvd

Build docs developers (and LLMs) love

Get Started

Configuration

Running LARDON

Reconstruction Pipeline

Visualization & Output

​Parameter reference

​pedestal

​mask

​mask.coll — collection views

​mask.ind — induction views

​noise

​noise.coherent — coherent noise subtraction

​noise.fft — FFT low-pass filter

​noise.microphonic — microphonic noise removal

​hit_finder

​hit_finder.coll — collection hit finding

​hit_finder.ind — induction hit finding

​Shared hit-finder parameters

​track_2d

​stitching_2d

​track_3d

​stitching_3d

​ghost

​single_hit

​pds

​pds.pedestal

​pds.noise

​pds.hit_finder

​pds.cluster

​pds.tpc_matching

​Detector-specific example: pdvd

Build docs developers (and LLMs) love

Parameter reference

`pedestal`

`mask`

`mask.coll` — collection views

`mask.ind` — induction views

`noise`

`noise.coherent` — coherent noise subtraction

`noise.fft` — FFT low-pass filter

`noise.microphonic` — microphonic noise removal

`hit_finder`

`hit_finder.coll` — collection hit finding

`hit_finder.ind` — induction hit finding

Shared hit-finder parameters

`track_2d`

`stitching_2d`

`track_3d`

`stitching_3d`

`ghost`

`single_hit`

`pds`

`pds.pedestal`

`pds.noise`

`pds.hit_finder`

`pds.cluster`

`pds.tpc_matching`

Detector-specific example: pdvd