include/G4OCCT/G4OCCTMaterialMapReader.hh
| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | // SPDX-License-Identifier: LGPL-2.1-or-later | ||
| 2 | // Copyright (C) 2026 G4OCCT Contributors | ||
| 3 | |||
| 4 | /// @file G4OCCTMaterialMapReader.hh | ||
| 5 | /// @brief Declaration of G4OCCTMaterialMapReader. | ||
| 6 | |||
| 7 | #ifndef G4OCCT_G4OCCTMaterialMapReader_hh | ||
| 8 | #define G4OCCT_G4OCCTMaterialMapReader_hh | ||
| 9 | |||
| 10 | #include "G4OCCT/G4OCCTMaterialMap.hh" | ||
| 11 | |||
| 12 | #include <G4GDMLReadStructure.hh> | ||
| 13 | #include <G4String.hh> | ||
| 14 | |||
| 15 | /** | ||
| 16 | * @brief Parses an XML material-map file into a G4OCCTMaterialMap. | ||
| 17 | * | ||
| 18 | * Subclasses `G4GDMLReadStructure` to gain zero-duplication access to all | ||
| 19 | * `G4GDMLReadMaterials` protected parsing methods (`MaterialRead`, | ||
| 20 | * `ElementRead`, `IsotopeRead`, `FractionRead`, `DRead`, …). Only the | ||
| 21 | * dispatching logic for the custom G4OCCT attributes (`stepName` and | ||
| 22 | * `geant4Name`) is new code. | ||
| 23 | * | ||
| 24 | * ## File format | ||
| 25 | * | ||
| 26 | * The root element must be `<materials>`. Two entry types are supported: | ||
| 27 | * | ||
| 28 | * **Type 1 — Named lookup** (no `<fraction>` children required): | ||
| 29 | * ```xml | ||
| 30 | * <material stepName="AISI 316L" geant4Name="G4_STAINLESS-STEEL"/> | ||
| 31 | * <material stepName="CaloModule" geant4Name="LeadGlass"/> | ||
| 32 | * ``` | ||
| 33 | * `geant4Name` is passed to `G4NistManager::FindOrBuildMaterial()`, which | ||
| 34 | * first checks the global `G4MaterialTable` and then falls back to the NIST | ||
| 35 | * database. This means any material already registered (e.g. by a preceding | ||
| 36 | * `G4GDMLParser::Read()` call with name-stripping) can be referenced by its | ||
| 37 | * plain name — not only NIST materials. An unrecognised name is a fatal | ||
| 38 | * error. | ||
| 39 | * | ||
| 40 | * **Type 2 — Inline GDML material definition**: | ||
| 41 | * ```xml | ||
| 42 | * <element name="Si" Z="14"><atom value="28.085"/></element> | ||
| 43 | * <material stepName="FR4" name="FR4" state="solid"> | ||
| 44 | * <D value="1.86" unit="g/cm3"/> | ||
| 45 | * <fraction n="0.18" ref="Si"/> | ||
| 46 | * <fraction n="0.39" ref="O"/> | ||
| 47 | * ... | ||
| 48 | * </material> | ||
| 49 | * ``` | ||
| 50 | * The `name` attribute is the GDML registry key; it must be present for | ||
| 51 | * inline definitions. Setting `name` equal to `stepName` is recommended | ||
| 52 | * for clarity. If a material with the same `name` (or its GDML-generated | ||
| 53 | * decorated form) is already in the G4MaterialTable, it is reused without | ||
| 54 | * re-creation. **Prefer Type 1 when the material is already defined in the | ||
| 55 | * reference geometry GDML**, to avoid creating duplicate G4 objects (extra | ||
| 56 | * elements and materials) that can disturb the Geant4 thread-local cache. | ||
| 57 | * | ||
| 58 | * `<element>` and `<isotope>` definitions must appear before `<material>` | ||
| 59 | * entries that reference them. | ||
| 60 | * | ||
| 61 | * ## Usage | ||
| 62 | * ```cpp | ||
| 63 | * G4OCCTMaterialMapReader reader; | ||
| 64 | * G4OCCTMaterialMap map = reader.ReadFile("materials.xml"); | ||
| 65 | * auto* assembly = G4OCCTAssemblyVolume::FromSTEP("detector.step", map); | ||
| 66 | * ``` | ||
| 67 | */ | ||
| 68 | class G4OCCTMaterialMapReader : public G4GDMLReadStructure { | ||
| 69 | public: | ||
| 70 | 21 | G4OCCTMaterialMapReader() = default; | |
| 71 | 21 | ~G4OCCTMaterialMapReader() override = default; | |
| 72 | |||
| 73 | /** | ||
| 74 | * Parse the material-map XML file at @p path and return the populated map. | ||
| 75 | * | ||
| 76 | * @param path Filesystem path to the XML material-map file. | ||
| 77 | * @return `G4OCCTMaterialMap` with one entry per `<material>` element. | ||
| 78 | * @throws G4Exception (FatalException) on any parse or resolution error. | ||
| 79 | */ | ||
| 80 | G4OCCTMaterialMap ReadFile(const G4String& path); | ||
| 81 | }; | ||
| 82 | |||
| 83 | #endif // G4OCCT_G4OCCTMaterialMapReader_hh | ||
| 84 |