|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## About |
6 | | - |
7 | | -ATTPCROOT is a ROOT/FairRoot-based C++ framework for simulation and analysis of Active Target Time Projection Chamber (AT-TPC) detector data. It integrates with FairSoft (provides ROOT, Geant4, VMC) and FairRoot (provides the task/run framework). |
8 | | - |
9 | | -## Environment Setup |
10 | | - |
11 | | -Before building or running anything, the environment must be loaded. The VSCode terminal auto-sources this on startup: |
12 | | - |
13 | | -```bash |
14 | | -source build/config.sh |
15 | | -``` |
16 | | - |
17 | | -This sets `LD_LIBRARY_PATH`, `ROOTSYS`, `VMCWORKDIR`, `ROOT_INCLUDE_PATH`, and Geant4 data paths. The key install paths on this machine are: |
18 | | -- FairRoot: `~/fair_install/FairRootInstall` |
19 | | -- FairSoft: `~/fair_install/FairSoftInstall` |
20 | | - |
21 | | -For CMake configuration (not the build itself), the following env vars are needed: |
22 | | -```bash |
23 | | -export FAIRROOTPATH=~/fair_install/FairRootInstall |
24 | | -export SIMPATH=~/fair_install/FairSoftInstall |
25 | | -``` |
26 | | - |
27 | | -## Build Commands |
28 | | - |
29 | | -```bash |
30 | | -# Configure (from repo root, out-of-source into build/) |
31 | | -cmake -S . -B build -DCMAKE_PREFIX_PATH=~/fair_install/hdf5 |
32 | | - |
33 | | -# Build (10 parallel jobs) |
34 | | -cmake --build build -j10 |
35 | | - |
36 | | -# Build a specific target |
37 | | -cmake --build build --target AtSimulationData -j10 |
38 | | - |
39 | | -# Run all unit tests |
40 | | -cd build && ctest -V |
41 | | - |
42 | | -# Run a specific test binary directly |
43 | | -./build/tests/AtSimulationDataTests |
44 | | -./build/tests/AtGeneratorsTests |
45 | | -./build/tests/AtToolsTests |
46 | | -``` |
47 | | - |
48 | | -Tests are built by default (`BUILD_TESTS=ON`). Test binaries are placed in `build/tests/`. |
49 | | - |
50 | | -## Code Formatting |
51 | | - |
52 | | -The project uses `clang-format-17` with the config in `.clang-format` (based on LLVM style, 3-space indent, 120-char column limit). Format on save is configured in VSCode. To format manually: |
| 3 | +ATTPCROOT is a ROOT/FairRoot-based C++ framework for simulation and analysis of Active Target Time Projection Chamber (AT-TPC) detector data. |
| 4 | + |
| 5 | +## Documentation |
| 6 | + |
| 7 | +Full developer documentation lives in `docs/`. See [docs/index.md](../docs/index.md) for the full map. Quick topic links: |
| 8 | + |
| 9 | +| Topic | File | |
| 10 | +|-------|------| |
| 11 | +| First-time install | [tooling/installation.md](../docs/tooling/installation.md) | |
| 12 | +| Daily use (build/test) | [tooling/daily-use.md](../docs/tooling/daily-use.md) | |
| 13 | +| Testing patterns | [tooling/testing.md](../docs/tooling/testing.md) | |
| 14 | +| Contributor guide | [contributing/guide.md](../docs/contributing/guide.md) | |
| 15 | +| Adding a new module | [contributing/new-module.md](../docs/contributing/new-module.md) | |
| 16 | +| Code style | [contributing/code-style.md](../docs/contributing/code-style.md) | |
| 17 | +| Module overview | [reference/modules.md](../docs/reference/modules.md) | |
| 18 | +| Data model | [reference/data-model.md](../docs/reference/data-model.md) | |
| 19 | +| Branch I/O contracts | [reference/branch-io-contracts.md](../docs/reference/branch-io-contracts.md) | |
| 20 | +| Simulation pipeline | [subsystems/simulation-pipeline.md](../docs/subsystems/simulation-pipeline.md) | |
| 21 | +| Reconstruction pipeline | [subsystems/reconstruction-pipeline.md](../docs/subsystems/reconstruction-pipeline.md) | |
| 22 | +| Event generators | [subsystems/generators.md](../docs/subsystems/generators.md) | |
| 23 | +| Pulse shape analysis | [subsystems/psa.md](../docs/subsystems/psa.md) | |
| 24 | +| Energy loss | [subsystems/energy-loss.md](../docs/subsystems/energy-loss.md) | |
| 25 | + |
| 26 | +## Quick Reference: Build & Test |
53 | 27 |
|
54 | 28 | ```bash |
55 | | -clang-format-17 -i <file> |
56 | | -# Or format all changed files: |
57 | | -scripts/formatAll.sh |
| 29 | +source build/config.sh # load environment (do this first) |
| 30 | +cmake --build build -j10 # build everything |
| 31 | +cd build && ctest -V # run all unit tests |
58 | 32 | ``` |
59 | 33 |
|
60 | | -Static analysis uses `clang-tidy` (config in `.clang-tidy`): modernize-* and cppcoreguidelines-* checks. |
61 | | - |
62 | | -## Architecture |
63 | | - |
64 | | -The framework follows FairRoot's task pipeline pattern: data flows through a chain of `FairTask` subclasses, persisted as ROOT TClonesArrays in a TTree. |
65 | | - |
66 | | -### Module Overview |
67 | | - |
68 | | -| Module | Purpose | |
69 | | -|--------|---------| |
70 | | -| `AtSimulationData` | MC truth data: `AtStack`, `AtMCTrack`, `AtMCPoint`, `AtVertexPropagator` | |
71 | | -| `AtGenerators` | FairGenerator subclasses for beam/reaction/decay event generation | |
72 | | -| `AtDetectors` | Geant4 sensitive detector implementations (AT-TPC, GADGET-II, SpecMAT, etc.) | |
73 | | -| `AtDigitization` | Converts MC points → simulated pad signals (`AtClusterize`, `AtPulse`) | |
74 | | -| `AtUnpack` | Unpacks raw experimental data (GET/GRAW, HDF5, ROOT formats) | |
75 | | -| `AtData` | Core data classes: `AtRawEvent`, `AtEvent`, `AtHit`, `AtPad`, `AtTrack` | |
76 | | -| `AtMap` | Pad mapping between electronics channels and detector geometry | |
77 | | -| `AtParameter` | FairRuntimeDb parameter containers | |
78 | | -| `AtReconstruction` | PSA, pattern recognition, fitting tasks | |
79 | | -| `AtTools` | Utilities: energy loss (CATIMA), kinematics, space charge, hit sampling | |
80 | | -| `AtAnalysis` | High-level analysis tasks and `AtRunAna` | |
81 | | -| `AtS800` | S800 spectrograph data handling | |
82 | | -| `AtEventDisplay` | ROOT Eve-based event display | |
83 | | - |
84 | | -### Data Flow |
85 | | - |
86 | | -**Simulation pipeline** (macros in `macro/Simulation/`): |
87 | | -1. `FairPrimaryGenerator` with an `AtReactionGenerator` subclass → particle stack |
88 | | -2. Geant4/VMC transport → `AtMCPoint` hits in sensitive volumes |
89 | | -3. `AtClusterizeTask` → electron clusters from ionization |
90 | | -4. `AtPulseTask` → simulated pad signals (`AtRawEvent`) |
91 | | - |
92 | | -**Reconstruction pipeline** (macros in `macro/Unpack_*/` and `macro/Analysis/`): |
93 | | -1. `AtUnpackTask` → `AtRawEvent` (raw pad traces) |
94 | | -2. `AtFilterTask` → filtered `AtRawEvent` |
95 | | -3. `AtPSAtask` (Pulse Shape Analysis) → `AtEvent` with `AtHit` objects |
96 | | -4. `AtSampleConsensusTask` / `AtPRAtask` → `AtPatternEvent` with `AtTrack` objects |
97 | | -5. `AtMCFitterTask` / `AtFitterTask` → fitted tracks with kinematics |
98 | | - |
99 | | -### Key Design Patterns |
100 | | - |
101 | | -**FairTask subclasses**: Each processing step is a `FairTask`. They retrieve input branches via `TClonesArray*` from `FairRootManager` in `Init()` and process them in `Exec()`. |
102 | | - |
103 | | -**AtReactionGenerator**: Abstract base for all reaction generators. Subclasses implement `GenerateReaction()`. The `ReadEvent()` method is `final` and handles the beam/reaction event alternation via `AtVertexPropagator`. Generators can be chained for sequential decays using `SetSequentialDecay(true)`. |
104 | | - |
105 | | -**AtVertexPropagator**: Singleton (`AtVertexPropagator::Instance()`) that communicates vertex, momentum, and kinematics between chained generators and downstream tasks. Alternates beam/reaction events via `EndEvent()`. Use `ResetForTesting()` in unit tests. |
106 | | - |
107 | | -**PSA (Pulse Shape Analysis)**: `AtPSA` is the abstract base. Concrete implementations (`AtPSAMax`, `AtPSAFull`, `AtPSADeconv`, etc.) extract hits from pad traces. `AtPSAComposite` allows chaining PSA methods. |
108 | | - |
109 | | -**Energy loss**: `AtELossModel` is the base; `AtELossCATIMA` wraps the CATIMA library (fetched automatically if not installed). Used via `AtELossManager`. |
110 | | - |
111 | | -### Adding a New Module Library |
112 | | - |
113 | | -Each module's `CMakeLists.txt` follows this pattern: |
114 | | -```cmake |
115 | | -set(LIBRARY_NAME MyModule) |
116 | | -set(SRCS file1.cxx file2.cxx) |
117 | | -set(DEPENDENCIES ATTPCROOT::AtData ROOT::Core ...) |
118 | | -set(TEST_SRCS MyModuleTest.cxx) |
119 | | -attpcroot_generate_tests(${LIBRARY_NAME}Tests SRCS ${TEST_SRCS} DEPS ${LIBRARY_NAME}) |
120 | | -generate_target_and_root_library(${LIBRARY_NAME} LINKDEF ${LIBRARY_NAME}LinkDef.h SRCS ${SRCS} DEPS_PUBLIC ${DEPENDENCIES}) |
121 | | -``` |
| 34 | +## Code-Writing Rules |
122 | 35 |
|
123 | | -ROOT dictionary generation requires a `*LinkDef.h` file listing every class that needs ROOT reflection. Every class with `ClassDef` in its header must appear in the LinkDef. |
| 36 | +These rules apply whenever editing or adding C++ code in this repo. |
124 | 37 |
|
125 | | -**LinkDef streamer suffix** — the suffix after the class name controls whether ROOT generates a full I/O streamer: |
| 38 | +### LinkDef Streamer Suffixes |
126 | 39 |
|
127 | | -- `ClassName +;` — generates a full streamer. Use this **only** for classes that are written to a ROOT file (i.e. stored as a branch in a `TClonesArray` or `TTree`). Examples: `AtHit`, `AtEvent`, `AtRawEvent`, `AtMCPoint`. |
128 | | -- `ClassName -!;` — registers the class for reflection (usable in interpreted macros, usable as a pointer type) but **suppresses the streamer**. Use this for every class that is never written to disk: tasks, algorithms, models, samplers, etc. Examples: `AtELossModel`, `AtSpaceChargeModel`, `AtSample` subclasses. |
| 40 | +Every class in a `*LinkDef.h` file must use the correct suffix: |
129 | 41 |
|
130 | | -Generating an unnecessary streamer bloats the dictionary and binary with unused I/O code, so the default should be `-!` unless disk persistence is actually required. |
| 42 | +- `ClassName +;` — generates a full I/O streamer. **Only** for classes written to a ROOT file (stored in a `TClonesArray` or `TTree` branch). Examples: `AtHit`, `AtEvent`, `AtRawEvent`, `AtMCPoint`. |
| 43 | +- `ClassName -!;` — reflection only, no streamer. Use for **everything else**: tasks, algorithms, models, samplers. Examples: `AtPSAMax`, `AtELossModel`, `AtFitterTask`. |
131 | 44 |
|
132 | | -**C++ vs ROOT typedefs** — use plain C++ types (`bool`, `int`, `double`, `std::string`) in all classes that are not written to a ROOT file. Only use ROOT's portability typedefs (`Bool_t`, `Int_t`, `Double_t`, etc.) in classes that are persisted to disk, where ROOT's cross-platform I/O guarantees matter. Mixing ROOT types into purely algorithmic or task classes is unnecessary overhead. |
| 45 | +Default to `-!` unless disk persistence is actually required. |
133 | 46 |
|
134 | | -### Unit Tests |
| 47 | +### C++ vs ROOT Typedefs |
135 | 48 |
|
136 | | -Tests use Google Test, placed alongside source files (e.g., `AtVertexPropagatorTest.cxx` in `AtSimulationData/`). Register them in the module's `CMakeLists.txt` via `attpcroot_generate_tests()`. Tests must not access external files or network resources. |
| 49 | +- Non-persisted classes (tasks, algorithms, models): use `bool`, `int`, `double`, `std::string`. |
| 50 | +- Persisted data classes only: use `Bool_t`, `Int_t`, `Double_t`, etc. |
137 | 51 |
|
138 | | -### Macros |
| 52 | +### Test Isolation |
139 | 53 |
|
140 | | -ROOT macros (`.C` files) in `macro/` are the primary user interface for running simulations and analyses. They are not compiled into libraries—they run interpreted by ROOT. Integration tests live in `macro/tests/`. |
| 54 | +Unit tests must not access external files or network resources. Hardcode test data inline. |
141 | 55 |
|
142 | 56 | ## Contributing |
143 | 57 |
|
144 | | -- PRs must target the `develop` branch and apply cleanly (fast-forward, no merge commits). |
145 | | -- Commit messages: present imperative mood, ≤72 characters summary. |
146 | | -- All PRs are checked by `clang-format`, `clang-tidy`, and the unit test suite. |
| 58 | +- PRs target the `develop` branch; fast-forward only (no merge commits). |
| 59 | +- Commit messages: present imperative mood, ≤72 characters. |
| 60 | +- All PRs must pass `clang-format`, `clang-tidy`, and unit tests. |
0 commit comments