Add o2-sim-geometry-doctor, a geometry against field audit

This commit provides a new tool o2-sim-geometry-doctor that reads a placed
geometry and a magnetic field and reports where the two do not fit together:
logical volumes placed both inside and outside the field, mothers whose own
material straddles the boundary, daughter clusters that would need a container
of their own, and media asking for straight-line transport while sitting in
real field.

The tool was motivated from the idea to check the consistency of geometry and
Geant4 media properties against the properties of the magnetic field, and to
potentially optimize this assignment in a second step. It is related to these
O2 JIRA tickets:

  https://its.cern.ch/jira/browse/O2-174
  https://its.cern.ch/jira/browse/O2-175
  https://its.cern.ch/jira/browse/O2-181

In the future it can be extended to provide automatic repair PRs.

It:
- builds an outer bound on the field support per threshold, phi sampled by
  arc length and every threshold crossing bisected, and checks the bound
  against the field before using it
- concludes field-free from geometry only; sampling is used only to disprove
- takes placement extents from the shapes, testing TGeoEltu before TGeoTube
- verifies a field read from a file against stored reference vectors and
  repairs the polarity inversion re-initialisation introduces
- reads the ifield and sensitivity flags from the geometry file itself, so it
  links no detector code and no simulation engine
- ships the ALICE anchor verdicts for --verify-anchors

Example:

  o2-sim-geometry-doctor --geometry-file o2sim_geometry.root --field-current -5

writes geometry-doctor-proposals.json (findings with suggested actions),
geometry-doctor-placements.csv (one classified row per placement) and
geometry-doctor-report.txt, and prints the report.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0178JHAQ2biaX5ac9ThppBXi

Author: sawenzel

run/CMakeLists.txt

@@ -108,6 +108,16 @@ o2_add_executable(g4-determine-unknown-pdg-properties
                   SOURCES g4DetermineUnknownPdgProperties.cxx
                   PUBLIC_LINK_LIBRARIES O2::O2TrivialMC MC::Geant4 MC::Geant4VMC O2::SimConfig)
 
+# Reads a geometry file and a field and reports where the two do not fit together.
+# It needs neither the simulation engines nor any detector code -- the medium flags
+# it reasons about are GSTMED parameters stored in the geometry file itself -- so it
+# deliberately does not link internal::allsim.
+o2_add_executable(geometry-doctor
+                  COMPONENT_NAME sim
+                  SOURCES o2sim_geometry_doctor.cxx
+                  PUBLIC_LINK_LIBRARIES O2::Field ROOT::Geom Boost::program_options
+                                        nlohmann_json::nlohmann_json)
+
 o2_add_executable(mctracks-proxy
                   COMPONENT_NAME sim
                   SOURCES o2sim_mctracks_proxy.cxx

run/geometry-doctor-anchors.json

@@ -0,0 +1,15 @@
+{
+	"comment": "Volumes of the ALICE Run 3 geometry whose relation to the field is known independently of this tool, from the geometry of the LHC machine elements around the RB24 beam pipe. Pass this file to o2-sim-geometry-doctor --verify-anchors to check a run against them. The five copper tubes sit 14 to 63 cm clear of the machine band in z and must come out field-free; RB243 and RB243A are assemblies, so they carry no material and nothing can be flagged on them; caveRB24 must NOT come out field-free, because what its daughters leave over is a sliver of cave air between an oval beam pipe and a circular field cylinder that carries more than 13 kG; and RB24B1BellowM is placed in the solenoid fringe while carrying a field-free medium, which is what the reverse audit exists to find.",
+	"anchors": [
+		{"volume": "voRB242CuTube", "expect": "OUT", "placements": 2},
+		{"volume": "voRB243CuTube", "expect": "OUT", "placements": 2},
+		{"volume": "voRB24CuTubeF", "expect": "OUT", "placements": 7},
+		{"volume": "voRB24cCuTube", "expect": "OUT", "placements": 1},
+		{"volume": "voRB24cCuTubeM", "expect": "OUT", "placements": 1},
+		{"volume": "RB243", "expect": "ASSEMBLY", "placements": 1},
+		{"volume": "RB243A", "expect": "ASSEMBLY", "placements": 2},
+		{"volume": "caveRB24", "expect": "NOT_OUT", "min_max_B_kG": 13.0},
+		{"volume": "voRB24CuTubeM", "expect": "IN", "min_max_B_kG": 4.0},
+		{"volume": "RB24B1BellowM", "expect": "REVERSE_AUDIT_FLAGGED", "min_max_B_kG": 4.0}
+	]
+}