docs: Document Track EDM (acts-project#2797)

Blocked by:

- acts-project#2816 
- acts-project#2817
- acts-project#2819

.github/workflows/docs.yml

@@ -50,6 +50,7 @@ jobs:
           --keep-going
           -t run_doxygen
           -t lazy_autodoc
+          -t white_papers
           -b linkcheck
           . _build/html/
 

Core/include/Acts/EventData/TrackContainerBackendConcept.hpp

@@ -83,6 +83,8 @@ concept MutableTrackContainerBackend = ConstTrackContainerBackend<T> &&
 
   {v.setParticleHypothesis_impl(
       itrack, std::declval<const Acts::ParticleHypothesis&>())};
+
+  {v.clear()};
 };
 
 template <typename T>

Plugins/Podio/include/Acts/Plugins/Podio/PodioTrackContainer.hpp

@@ -186,6 +186,9 @@ class MutablePodioTrackContainer : public PodioTrackContainerBase {
   }
 
   std::size_t size_impl() const { return m_collection->size(); }
+
+  void clear() { m_collection->clear(); }
+
   // END INTERFACE HELPER
 
   const Surface* referenceSurface_impl(IndexType itrack) const {

docs/Doxyfile

@@ -776,6 +776,8 @@ WARN_LOGFILE           =
 INPUT                  = ../Core/include \
                          ../Fatras/include \
                          ../Plugins/DD4hep/include \
+                         ../Plugins/EDM4hep/include \
+                         ../Plugins/Podio/include \
                          ../Plugins/Geant4/include \
                          ../Plugins/Identification/include \
                          ../Plugins/Json/include \

docs/_extensions/lazy_autodoc.py

@@ -72,6 +72,7 @@ def run() -> None:
         "Acts::FreeToBoundMatrix",
         "Acts::FreeSquareMatrix",
         "Acts::FreeToPathMatrix",
+        "Acts::HashedString",
     }
 
     role_instances["struct"] |= {
@@ -117,6 +118,8 @@ def run() -> None:
         "Acts::Logging::TimedOutputDecorator",
         "Acts::Logging::DefaultFilterPolicy",
         "Acts::Logging::DefaultPrintPolicy",
+        "Acts::Measurement",
+        "Acts::SourceLink",
     }
 
     role_instances["func"] = {
@@ -136,6 +139,7 @@ def run() -> None:
         "Acts::BoundIndices",
         "Acts::FreeIndices",
         "Acts::MagneticFieldError",
+        "Acts::TrackStatePropMask",
     }
 
     role_ex = re.compile(r"[{:](" + "|".join(roles) + r")[}:]`(.+?)`")

docs/conf.py

@@ -33,6 +33,7 @@
     "breathe",
     "myst_parser",
     "sphinx.ext.mathjax",
+    "sphinx.ext.graphviz",
     "sphinx.ext.todo",
     "warnings_filter",
 ]
@@ -167,9 +168,10 @@
     extensions += ["lazy_autodoc"]
 
 
-import white_papers
+if tags.has("white_papers"):
+    import white_papers
 
-white_papers.render()
+    white_papers.render()
 
 # -- Markdown bridge setup hook (must come last, not sure why) ----------------
 

docs/core/eventdata/index.md

@@ -5,8 +5,47 @@ This section is **incomplete!**
 :::
 
 :::{toctree}
+:maxdepth: 1
 parametrization
 tracks
 measurements
 particle_hypothesis
 :::
+
+The various tracking components in ACTS can be assembled into a full
+reconstruction chain.  Between these components, data needs to be exchanged in
+a well-defined way. This is achieved through the {term}`EDM` (Event Data Model), which
+is a set of data types and interfaces representing the content of an event.
+Until very recently, ACTS has focused mainly on an *internal* {term}`EDM`, which
+is really focused on efficient interchange between components inside the
+toolkit, sometimes at the cost of usability for clients. With the main
+reconstruction chain becomes more and more mature, however, the focus has
+shifted to a more client-oriented {term}`EDM` encapsulating the outputs of tracking.
+
+(edm_chain)=
+:::{figure} figures/edm_chain.svg
+:width: 100%
+Diagram showing the stages and data flow of a track reconstruction chain. The
+boxes show {term}`EDM` objects that are passed between the stages.
+:::
+
+
+{numref}`edm_chain` shows an overview of the {term}`EDM` data types and how
+they form a data-flow sequence. Measurements coming from the experiment
+software are the main inputs of the chain. This data-type is abstracted in ACTS
+in a way that allows the details of these measurements to be fully
+experiment-specific. See [](#edm_uncalib_meas) for details.
+
+ACTS ships with a clusterization algorithm, which can turn segmented raw
+measurements into clusters, the second {term}`EDM` object in the chain,
+representing particle intersections with the sensors. For the creation of track
+seeds, clusters need to be converted into three-dimensional space-points,
+combining information from multiple clusters where needed, e.g. for
+one-dimensional silicon strip sensors.  The space-points and seeds are part of
+the {term}`EDM` as well, since they are handed over to the track finding
+component. This component is responsible for the creation of completed tracks,
+which can then optionally be refitted with a precision track fitter.
+
+Both the track finding and the precision track fit produce track objects, which
+are the primary output of the tracking chain. More on the track EDM can be
+found in [](#edm_tracks).

docs/core/eventdata/measurements.md

@@ -1,11 +1,12 @@
 # Measurements
 
-Measurements exist as *uncalibrated* and *calibrated* types. *Uncalibrated*
-measurements are the direct output of the data formation. *Calibrated*
-measurements are used during track fitting. When trajectory information
-(or information about the trajectory hypothesis) is available, certain calibration
-steps can help to improve the track fit quality.
+Measurements exist as *uncalibrated* and *calibrated* types. While
+*uncalibrated* measurements are the direct output of the data formation, during
+the track fit, when trajectory information (or information about the trajectory
+hypothesis) is available, certain calibration steps can help to improve the
+track fit quality.
 
+(edm_uncalib_meas)=
 ## Uncalibrated measurements / source links