# dune/duneanaobj architecture

> Architecture diagram of the GitHub repository dune/duneanaobj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dune/duneanaobj
- Repository: https://github.com/dune/duneanaobj

## Overview

#### Purpose and entry points
`duneanaobj` defines the C++ object schema for DUNE CAF (Common Analysis File) ROOT TTrees. Each TTree entry contains one `caf::StandardRecord`; this repository provides the headers, compiled library, ROOT dictionary metadata, and navigation/proxy interfaces needed to read that schema. It does not write CAFs; external FD/ND CAFMaker applications do.

Primary consumer entry point: `duneanaobj/StandardRecord/StandardRecord.h`. Library implementation and aggregate record behavior live in `duneanaobj/StandardRecord/StandardRecord.cxx`.

#### Build, packaging, and runtime boundary
The project is a CMake-built C++ library, rooted at `CMakeLists.txt`, with the schema target organized under `duneanaobj/StandardRecord/CMakeLists.txt`. It is distributed both as a normal linked library and a Fermilab UPS product via `ups/product_deps` and `ups/setup_for_development`.

Runtime dependencies are ROOT (CAF serialization, dictionaries, and interactive reading) and the Fermilab CET/UPS environment for the documented development build. Consumers need the library available at dynamic-link time and headers when compiling C++ readers.

#### Root record and schema composition
`caf::StandardRecord` is the top-level persisted event object. It aggregates global event data and detector-/domain-specific branches, rather than exposing low-level detector hit data.

Key schema surfaces:
- Root aggregate: `duneanaobj/StandardRecord/StandardRecord.h`, `duneanaobj/StandardRecord/StandardRecord.cxx`
- Global/shared event content: `duneanaobj/StandardRecord/SRGlobal.h`, `duneanaobj/StandardRecord/SRMeta.h`
- Common reconstruction branch types: `duneanaobj/StandardRecord/SRCommonRecoBranch.h`, `duneanaobj/StandardRecord/SRRecoParticlesBranch.h`
- Enumerated stable values: `duneanaobj/StandardRecord/SREnums.h`

The main compatibility boundary is the persisted object layout: changing record or branch fields affects CAF readers and writers across the DUNE software ecosystem.

#### Detector and experiment-domain branches
The schema partitions event content by source/detector while retaining a single event-level record. Far detector content is represented by `SRFD` and its branch; near-detector data has dedicated LAr and association structures; gas-argon and MINERvA data are independent domains.

Representative components:
- FD: `duneanaobj/StandardRecord/SRFD.h`, `duneanaobj/StandardRecord/SRFDBranch.h`
- ND LAr and cross-object associations: `duneanaobj/StandardRecord/SRNDLAr.h`, `duneanaobj/StandardRecord/SRNDTrackAssn.h`, `duneanaobj/StandardRecord/SRNDShowerAssn.h`
- GAr: `duneanaobj/StandardRecord/SRGAr.h`, `duneanaobj/StandardRecord/SRGArTrack.h`
- Beam and external detector summaries: `duneanaobj/StandardRecord/SRBeamBranch.h`, `duneanaobj/StandardRecord/SRMINERvA.h`

#### Reconstruction, truth, and links
CAF data flow is: upstream simulation/reconstruction systems populate high-level reconstructed objects and summary truth; CAFMaker serializes the populated `StandardRecord` into ROOT; analysis clients deserialize it and traverse object collections and associations.

Reconstructed entities include tracks, showers, PFParticles, and generic reco-particle abstractions:
`duneanaobj/StandardRecord/SRTrack.h`, `duneanaobj/StandardRecord/SRShower.h`, `duneanaobj/StandardRecord/SRPFP.h`.

Truth data represents interactions and particles, with event-level truth grouping:
`duneanaobj/StandardRecord/SRTruthBranch.h`, `duneanaobj/StandardRecord/SRTrueInteraction.h`, `duneanaobj/StandardRecord/SRTrueParticle.h`.

Associations and overlap collections are structural links between these collections, not external database references; readers must respect nested variable-length collection limits in ROOT `TTreeFormula`.

#### Math, weights, and systematic metadata
Portable schema-owned vector types avoid making consumers depend on an upstream physics framework:
`duneanaobj/StandardRecord/SRVector3D.h`, `duneanaobj/StandardRecord/SRLorentzVector.h`.

Event weighting and systematic parameter headers are modeled in-record:
`duneanaobj/StandardRecord/SRWeightGlobal.h`, `duneanaobj/StandardRecord/SRSystParamHeader.h`.

#### ROOT integration, navigation, and flattened access
ROOT dictionary generation is declared by `duneanaobj/StandardRecord/classes.h` and `duneanaobj/StandardRecord/classes_def.xml`; these are essential for object streaming and interactive ROOT access.

For traversal convenience, the project supplies navigation and generated proxy layers:
`duneanaobj/StandardRecord/Navigate.h`, `duneanaobj/StandardRecord/Proxy/Instantiations.cxx`.

A separate flat representation boundary exists under `duneanaobj/StandardRecord/Flat/Prolog.h`; flat CAF production is performed by external CAFMakers, enabling simpler branch-oriented analysis where deeply nested standard-record collections are inconvenient.

Main entry points: [`duneanaobj/StandardRecord/StandardRecord.h`](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/StandardRecord.h) (StandardRecord), [`duneanaobj/StandardRecord/CMakeLists.txt`](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/CMakeLists.txt) (StandardRecord target), [`duneanaobj/StandardRecord/SRCommonRecoBranch.h`](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRCommonRecoBranch.h) (Common reconstruction), [`duneanaobj/StandardRecord/classes.h`](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/classes.h) (ROOT dictionary metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Distribution"]
  node_cmake["CMake build<br/>[CMakeLists.txt]"]
  node_schema_target["StandardRecord target<br/>CMake target<br/>[CMakeLists.txt]"]
  node_ups["UPS product<br/>package metadata"]
end

subgraph group_schema["Persisted CAF Schema"]
  node_standard_record["StandardRecord<br/>persisted root record<br/>[StandardRecord.h]"]
  node_record_impl["Record implementation<br/>C++ implementation<br/>[StandardRecord.cxx]"]
  node_global["Global event data<br/>schema branch<br/>[SRGlobal.h]"]
  node_common_reco["Common reconstruction<br/>schema branch"]
  node_fd["Far detector<br/>schema branch<br/>[SRFDBranch.h]"]
  node_nd_lar["ND LAr &amp; associations<br/>schema branch<br/>[SRNDLAr.h]"]
  node_gar["Gas argon<br/>schema branch<br/>[SRGAr.h]"]
  node_beam_minerva["Beam &amp; MINERvA<br/>schema branch<br/>[SRBeamBranch.h]"]
  node_truth["Truth collections<br/>schema branch<br/>[SRTruthBranch.h]"]
  node_weights["Weights &amp; systematics<br/>schema metadata<br/>[SRWeightGlobal.h]"]
  node_math["Portable vector types<br/>schema value types<br/>[SRVector3D.h]"]
end

subgraph group_access["ROOT Access Layers"]
  node_dictionary["ROOT dictionary metadata<br/>[classes.h]"]
  node_navigation["Navigation API<br/>reader API<br/>[Navigate.h]"]
  node_proxy["Generated proxies<br/>ROOT proxy layer<br/>[Instantiations.cxx]"]
  node_flat["Flat CAF interface<br/>flat schema boundary<br/>[Prolog.h]"]
end

node_cafmaker["External CAFMaker<br/>external producer"]
node_root_ttree[("ROOT CAF TTree<br/>serialized CAF")]
node_analysis["Analysis clients<br/>external consumer"]

node_cmake -->|"includes"| node_schema_target
node_schema_target -->|"builds"| node_standard_record
node_ups -->|"packages"| node_schema_target
node_record_impl -->|"implements"| node_standard_record
node_standard_record -->|"aggregates"| node_global
node_standard_record -->|"aggregates"| node_common_reco
node_standard_record -->|"aggregates"| node_fd
node_standard_record -->|"aggregates"| node_nd_lar
node_standard_record -->|"aggregates"| node_gar
node_standard_record -->|"aggregates"| node_beam_minerva
node_standard_record -->|"aggregates"| node_truth
node_standard_record -->|"contains"| node_weights
node_common_reco -->|"uses"| node_math
node_dictionary -->|"streams"| node_standard_record
node_proxy -->|"uses"| node_dictionary
node_navigation -->|"traverses"| node_standard_record
node_cafmaker -->|"populates"| node_standard_record
node_cafmaker -->|"serializes"| node_root_ttree
node_root_ttree -->|"deserializes"| node_analysis
node_analysis -->|"uses"| node_navigation
node_flat -.->|"alternative flat layout"| node_root_ttree

click node_cmake "https://github.com/dune/duneanaobj/blob/main/CMakeLists.txt"
click node_schema_target "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/CMakeLists.txt"
click node_ups "https://github.com/dune/duneanaobj/blob/main/ups/product_deps"
click node_standard_record "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/StandardRecord.h"
click node_record_impl "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/StandardRecord.cxx"
click node_global "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRGlobal.h"
click node_common_reco "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRCommonRecoBranch.h"
click node_fd "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRFDBranch.h"
click node_nd_lar "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRNDLAr.h"
click node_gar "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRGAr.h"
click node_beam_minerva "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRBeamBranch.h"
click node_truth "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRTruthBranch.h"
click node_weights "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRWeightGlobal.h"
click node_math "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRVector3D.h"
click node_dictionary "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/classes.h"
click node_navigation "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Navigate.h"
click node_proxy "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Proxy/Instantiations.cxx"
click node_flat "https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Flat/Prolog.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_schema_target,node_ups toneBlue
class node_standard_record,node_record_impl,node_global,node_common_reco,node_fd,node_nd_lar,node_gar,node_beam_minerva,node_truth,node_weights,node_math toneAmber
class node_dictionary,node_navigation,node_proxy,node_flat toneMint
class node_cafmaker,node_root_ttree,node_analysis toneNeutral
```

## Components

### Build & Distribution

- [CMake build](https://github.com/dune/duneanaobj/blob/main/CMakeLists.txt): build · Builds the C++ schema library. · `CMakeLists.txt`
- [StandardRecord target](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/CMakeLists.txt): CMake target · `duneanaobj/StandardRecord/CMakeLists.txt`
- [UPS product](https://github.com/dune/duneanaobj/blob/main/ups/product_deps): package metadata · Packages the library for the Fermilab environment. · `ups/product_deps`

### Persisted CAF Schema

- [StandardRecord](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/StandardRecord.h): persisted root record · One CAF TTree entry's top-level event object. · `duneanaobj/StandardRecord/StandardRecord.h`
- [Record implementation](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/StandardRecord.cxx): C++ implementation · `duneanaobj/StandardRecord/StandardRecord.cxx`
- [Global event data](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRGlobal.h): schema branch · `duneanaobj/StandardRecord/SRGlobal.h`
- [Common reconstruction](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRCommonRecoBranch.h): schema branch · Shared reco collections and generic particle abstractions. · `duneanaobj/StandardRecord/SRCommonRecoBranch.h`
- [Far detector](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRFDBranch.h): schema branch · `duneanaobj/StandardRecord/SRFDBranch.h`
- [ND LAr & associations](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRNDLAr.h): schema branch · Near-detector LAr data and cross-object links. · `duneanaobj/StandardRecord/SRNDLAr.h`
- [Gas argon](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRGAr.h): schema branch · `duneanaobj/StandardRecord/SRGAr.h`
- [Beam & MINERvA](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRBeamBranch.h): schema branch · Beam summaries and external-detector content. · `duneanaobj/StandardRecord/SRBeamBranch.h`
- [Truth collections](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRTruthBranch.h): schema branch · Interactions and true particles grouped per event. · `duneanaobj/StandardRecord/SRTruthBranch.h`
- [Weights & systematics](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRWeightGlobal.h): schema metadata · `duneanaobj/StandardRecord/SRWeightGlobal.h`
- [Portable vector types](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/SRVector3D.h): schema value types · Framework-independent position and momentum types. · `duneanaobj/StandardRecord/SRVector3D.h`

### ROOT Access Layers

- [ROOT dictionary metadata](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/classes.h): ROOT dictionary · Declares streamable schema types for ROOT. · `duneanaobj/StandardRecord/classes.h`
- [Navigation API](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Navigate.h): reader API · Convenience traversal over record collections and associations. · `duneanaobj/StandardRecord/Navigate.h`
- [Generated proxies](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Proxy/Instantiations.cxx): ROOT proxy layer · `duneanaobj/StandardRecord/Proxy/Instantiations.cxx`
- [Flat CAF interface](https://github.com/dune/duneanaobj/blob/main/duneanaobj/StandardRecord/Flat/Prolog.h): flat schema boundary · Supports branch-oriented representations produced externally. · `duneanaobj/StandardRecord/Flat/Prolog.h`

### Other components

- **External CAFMaker**: external producer · Populates and serializes StandardRecord objects.
- **ROOT CAF TTree**: serialized CAF · Stores one StandardRecord per entry.
- **Analysis clients**: external consumer · Link the library and deserialize CAF records.

## Connections

- CMake build → StandardRecord target: includes
- StandardRecord target → StandardRecord: builds
- UPS product → StandardRecord target: packages
- Record implementation → StandardRecord: implements
- StandardRecord → Global event data: aggregates
- StandardRecord → Common reconstruction: aggregates
- StandardRecord → Far detector: aggregates
- StandardRecord → ND LAr & associations: aggregates
- StandardRecord → Gas argon: aggregates
- StandardRecord → Beam & MINERvA: aggregates
- StandardRecord → Truth collections: aggregates
- StandardRecord → Weights & systematics: contains
- Common reconstruction → Portable vector types: uses
- ROOT dictionary metadata → StandardRecord: streams
- Generated proxies → ROOT dictionary metadata: uses
- Navigation API → StandardRecord: traverses
- External CAFMaker → StandardRecord: populates
- External CAFMaker → ROOT CAF TTree: serializes
- ROOT CAF TTree → Analysis clients: deserializes
- Analysis clients → Navigation API: uses
- Flat CAF interface → ROOT CAF TTree: alternative flat layout