include/G4OCCT/G4OCCTMaterialMapReader.hh

0001 // SPDX-License-Identifier: LGPL-2.1-or-later
0002 // Copyright (C) 2026 G4OCCT Contributors
0003
0004 /// @file G4OCCTMaterialMapReader.hh
0005 /// @brief Declaration of G4OCCTMaterialMapReader.
0006
0007 #ifndef G4OCCT_G4OCCTMaterialMapReader_hh
0008 #define G4OCCT_G4OCCTMaterialMapReader_hh
0009
0010 #include "G4OCCT/G4OCCTMaterialMap.hh"
0011
0012 #include <G4GDMLReadStructure.hh>
0013 #include <G4String.hh>
0014
0015 /**
0016  * @brief Parses an XML material-map file into a G4OCCTMaterialMap.
0017  *
0018  * Subclasses `G4GDMLReadStructure` to gain zero-duplication access to all
0019  * `G4GDMLReadMaterials` protected parsing methods (`MaterialRead`,
0020  * `ElementRead`, `IsotopeRead`, `FractionRead`, `DRead`, …).  Only the
0021  * dispatching logic for the custom G4OCCT attributes (`stepName` and
0022  * `geant4Name`) is new code.
0023  *
0024  * ## File format
0025  *
0026  * The root element must be `<materials>`.  Two entry types are supported:
0027  *
0028  * **Type 1 — Named lookup** (no `<fraction>` children required):
0029  * ```xml
0030  * <material stepName="AISI 316L" geant4Name="G4_STAINLESS-STEEL"/>
0031  * <material stepName="CaloModule" geant4Name="LeadGlass"/>
0032  * ```
0033  * `geant4Name` is passed to `G4NistManager::FindOrBuildMaterial()`, which
0034  * first checks the global `G4MaterialTable` and then falls back to the NIST
0035  * database.  This means any material already registered (e.g. by a preceding
0036  * `G4GDMLParser::Read()` call with name-stripping) can be referenced by its
0037  * plain name — not only NIST materials.  An unrecognised name is a fatal
0038  * error.
0039  *
0040  * **Type 2 — Inline GDML material definition**:
0041  * ```xml
0042  * <element name="Si" Z="14"><atom value="28.085"/></element>
0043  * <material stepName="FR4" name="FR4" state="solid">
0044  *   <D value="1.86" unit="g/cm3"/>
0045  *   <fraction n="0.18" ref="Si"/>
0046  *   <fraction n="0.39" ref="O"/>
0047  *   ...
0048  * </material>
0049  * ```
0050  * The `name` attribute is the GDML registry key; it must be present for
0051  * inline definitions.  Setting `name` equal to `stepName` is recommended
0052  * for clarity.  If a material with the same `name` (or its GDML-generated
0053  * decorated form) is already in the G4MaterialTable, it is reused without
0054  * re-creation.  **Prefer Type 1 when the material is already defined in the
0055  * reference geometry GDML**, to avoid creating duplicate G4 objects (extra
0056  * elements and materials) that can disturb the Geant4 thread-local cache.
0057  *
0058  * `<element>` and `<isotope>` definitions must appear before `<material>`
0059  * entries that reference them.
0060  *
0061  * ## Usage
0062  * ```cpp
0063  * G4OCCTMaterialMapReader reader;
0064  * G4OCCTMaterialMap map = reader.ReadFile("materials.xml");
0065  * auto* assembly = G4OCCTAssemblyVolume::FromSTEP("detector.step", map);
0066  * ```
0067  */
0068 class G4OCCTMaterialMapReader : public G4GDMLReadStructure {
0069 public:
0070   G4OCCTMaterialMapReader()           = default;
0071   ~G4OCCTMaterialMapReader() override = default;
0072
0073   /**
0074    * Parse the material-map XML file at @p path and return the populated map.
0075    *
0076    * @param path Filesystem path to the XML material-map file.
0077    * @return `G4OCCTMaterialMap` with one entry per `<material>` element.
0078    * @throws G4Exception (FatalException) on any parse or resolution error.
0079    */
0080   G4OCCTMaterialMap ReadFile(const G4String& path);
0081 };
0082
0083 #endif // G4OCCT_G4OCCTMaterialMapReader_hh