A collection of ROOT/C++ macros, Python DAQ scripts and a Geant4 simulation for characterising silicon photomultipliers (SiPMs) for the ePIC dual-radiator RICH (dRICH). It consolidates — organised by measurement type — the work that was previously scattered across several divergent repositories: IV / DCR / gain / breakdown-voltage analysis, laser-based timing and PDE, ALCOR µreadout decoding, Keithley acquisition, irradiation (NIEL) simulation, and slew-rate / TDC studies.

Purpose

This repository aims to:

Provide a single home for the electrical / dark characterisation of SiPM sensors — current-voltage (IV) curves, dark-count rate (DCR), gain, breakdown voltage (Vbd), threshold scans, and their temperature / annealing dependence.
Collect the complementary measurements of the same sensors made with other techniques: laser-based timing and photon-detection efficiency, ALCOR micro-readout fine-tune calibration and noise, and slew-rate / TDC studies.
Keep the acquisition side (Keithley source-meter DAQ scripts) and the irradiation modelling (Geant4 NIEL simulation) next to the analysis they feed, so the full characterisation chain lives in one versioned tree.

Each top-level directory is one measurement / stage; they share sensors and conventions but are otherwise independent and run on their own.

Repository structure

.
├── source/         # Core analysis library: run database, IV/DCR scan builders, DCR getter
├── utils/          # Reusable helpers: graph utilities, breakdown-voltage finder,
│                   #   tree database, general/utility headers
├── macros/         # IV/DCR/gain/breakdown/threshold analysis + paper-plot macros
├── scripts/        # Helper shell scripts
├── laser/          # Laser-based characterisation (a different measurement of the same sensors)
│   ├── waveform/   #   - LeCroy waveform fitting, time-walk, signal analysis (+ lib/)
│   └── tgraphs/    #   - txt → TGraph → TTree → analysis pipeline
├── readout/        # ALCOR µreadout decoding: fine-tune calibration, noise, mini-frame
├── daq/            # Acquisition: Keithley IV/forward-scan DAQ (Python) + plotting macros
├── irradiation/    # Geant4 NIEL irradiation simulation (C++ src, CMake, GPS macros, NIEL tables)
├── slewrate/       # TDC calibration, laser time-coincidence, slew-rate macros
├── legacy/         # Salvaged unique macros from retired forks/snapshots (reference only)
├── docs/           # Doxygen configuration (Doxyfile); generated HTML lands in docs/_site/
├── Data/           # Input data (symlinked / gitignored — see Data)
└── .github/workflows/docs.yml   # Doxygen build + GitHub Pages publish

Generated outputs (*.pdf, *.png, *.eps), raw Data/ and the local Archive/ are gitignored — only source is versioned.

Components

Directory	Language	Measurement / role
`source/` + `utils/`	C++ (ROOT)	Core: parse the run database, build IV/DCR/gain graphs, find `Vbd`
`macros/`	C++ (ROOT)	Electrical/dark analysis, temperature & annealing scans, paper plots
`laser/waveform/`	C++ (ROOT)	LeCroy scope waveform decoding + fitting, time-walk
`laser/tgraphs/`	C++ (ROOT)	ASCII → `TGraph`/`TTree` laser-characterisation pipeline
`readout/`	C++ (ROOT)	ALCOR TDC fine-tune calibration, noise analysis, frame decoding
`daq/`	Python + C++	Keithley 2470/2600 IV & forward-scan acquisition, quick-look macros
`irradiation/`	C++ (Geant4)	NIEL displacement-damage simulation for the irradiation campaigns
`slewrate/`	C++ (ROOT)	TDC calibration, laser coincidence, slew-rate

Prerequisites

ROOT ≥ 6.x with root / root-config in PATH — for all .C macros.
Python ≥ 3.8 with numpy and matplotlib — for daq/keithley/.
Geant4 ≥ 11 and CMake ≥ 3.16 — only for irradiation/.
Doxygen ≥ 1.9 and Graphviz — only to build the documentation locally.

There is no top-level build: the analysis is run as ROOT macros, and each component is self-contained. The only compiled component is irradiation/.

Usage

ROOT analysis macros

The macros are meant to be loaded interactively in ROOT. From the repository root, for example:

root -l
root [0] .L utils/graphutils.C
root [1] .L source/database.C
root [2] .x macros/example.C

Data locations are configured through the database::basedir variable (or, in readout/, the ALCOR_DATA_DIR / ALCOR_WORK_DIR environment variables). See the TODO in DISCUSSION.md about hardcoded paths before running on a new machine.

Keithley acquisition (<tt>daq/</tt>)

python daq/keithley/ivscan.py # reverse-bias IV scan

python daq/keithley/fwdscan.py # forward-bias scan

The instrument IP and IDN live at the top of daq/keithley/keithley.py.

Irradiation simulation (<tt>irradiation/</tt>)

cd irradiation
cmake -B build && cmake --build build
./build/irradSiPM irradSiPM.gps.tifpa.mac

Data

Input data is not tracked in git. The repository expects a Data/ symlink (or directory) at the root pointing at the run database and per-run folders. The heavyweight raw datasets (e.g. the 2021/2022 irradiation campaign) are kept outside the repository under a local Archive/ and are gitignored.

Documentation

API reference (Doxygen, auto-deployed on push to main): https://nikolajal.github.io/sipm-characterisation/
Design log: `DISCUSSION.md` — open design questions, the TODO queue surfaced by the latest code audit, attention points, and the feature queue. Read this before proposing changes.

The Doxygen site is built and published by .github/workflows/docs.yml on every push to main (pull requests build the docs but do not publish); manual rebuilds are possible from the Actions tab via the workflow_dispatch trigger.

‍One-time setup: in Settings → Pages, set the source to GitHub Actions so the first deploy can publish.

</blockquote>

Open design questions

The canonical record lives in `DISCUSSION.md`, which follows the hub / triage-taxonomy template shared with the sibling repositories (mist, beam-test-analysis):

**D-XX** — open design questions awaiting a decision.
**TODO** — concrete fixes in the queue (bugs from the latest sweep), no design pending.
Attention points — latent caveats to keep in mind (ROOT ownership idioms, silent fallbacks).
**F-XX** — feature queue (deduplication, parameterisation, packaging).

Project history

This tree consolidates several pre-v1 R&D repositories — one per measurement — into a single versioned codebase. Code was merged organised by measurement type; raw data, build artifacts and the original git histories were left out of the tracked tree. The granular history is intentionally collapsed: per the project policy, the full pre-v1 history is kept only until the first v1.0.0 tag, at which point a clean-root reset is performed.

Authors

Nicola Rubini and collaborators, ePIC dRICH / SiPM characterisation effort.

Table of Contents