Materials
GEMC supports four ways to assign a material to a volume: referencing a Geant4 built-in, referencing a GEMC prebuilt special material, composing by atom count, or composing by fractional mass. Optical properties can be attached to any custom material.
All custom materials are created with the GMaterial class.
from gmaterial import GMaterial
Geant4 built-in materials
The Geant4 NIST Material Database
provides several pre-defined materials. Assign the name directly to gvolume — no
GMaterial object is needed:
gvolume.material = "G4_C" # graphite
gvolume.material = "G4_AIR"
gvolume.material = "G4_WATER"
gvolume.material = "G4_lH2" # liquid hydrogen
gvolume.material = "G4_Pb"
gvolume.material = "G4_Cu"
gvolume.material = "G4_Si"
gvolume.material = "G4_PLASTIC_SC_VINYLTOLUENE"
GEMC prebuilt special materials
GEMC defines a small set of isotopically pure materials that are not in the NIST database. These are built automatically at startup and can be used like any Geant4 material:
| Name | Formula | Density (g/cm³) | Temperature | Notes |
|---|---|---|---|---|
HydrogenGas |
H | 0.00275 | 50 K | Pure protium gas |
DeuteriumGas |
D₂ | 0.000452 | 294 K | Deuterium gas at room temperature |
LD2 |
D₂ | 0.169 | 22 K | Liquid deuterium |
ND3 |
ND₃ | 1.007 | 1 K | Frozen ammonia (deuterated) |
Helium3Gas |
³He | 1.65×10⁻⁴ | 294 K | Helium-3 gas at room temperature |
H3Gas |
T₂ | 0.0034 | 40 K | Tritium gas |
gvolume.material = "LD2" # liquid deuterium target
gvolume.material = "Helium3Gas" # He-3 detector
gvolume.material = "ND3" # polarized ammonia target
Custom materials
All custom materials share these mandatory fields:
| Field | Type | Description |
|---|---|---|
name |
str | Unique name used in gvolume.material |
density |
float | Density in g/cm³ |
| composition | set by method | Set via addNAtoms or addMaterialWithFractionalMass |
The optional description field is for documentation only.
The two composition methods are mutually exclusive: using both on the same instance exits with an error.
By molecular composition
Use addNAtoms(element, n) to build a material from chemical elements. Element symbols must match
Geant4 NIST element names (single capital letter or capital + lowercase: "H", "He", "Na", "Pb").
The total atom count across all calls must be greater than 1.
water = GMaterial("custom_water")
water.description = "Water (H2O)"
water.density = 1.0
water.addNAtoms("H", 2)
water.addNAtoms("O", 1)
water.publish(cfg)
quartz = GMaterial("SiO2")
quartz.density = 2.65
quartz.addNAtoms("Si", 1)
quartz.addNAtoms("O", 2)
quartz.publish(cfg)
nai = GMaterial("NaI_crystal")
nai.density = 3.67
nai.addNAtoms("Na", 1)
nai.addNAtoms("I", 1)
nai.publish(cfg)
By fractional mass
Use addMaterialWithFractionalMass(material, fraction) to blend existing materials by weight.
The fractions must sum to exactly 1.0 (checked at publish time with a relative tolerance of 1×10⁻⁶).
mixture = GMaterial("air_water_mixture")
mixture.description = "80% air / 20% water by mass"
mixture.density = 0.9601
mixture.addMaterialWithFractionalMass("G4_AIR", 0.80)
mixture.addMaterialWithFractionalMass("G4_WATER", 0.20)
mixture.publish(cfg)
Component names may be Geant4 built-ins (G4_*), GEMC prebuilt specials, or the names of custom materials that have already been published.
# mix a custom material with a Geant4 built-in
scint_mix = GMaterial("plastic_scintillator")
scint_mix.density = 1.032
scint_mix.addMaterialWithFractionalMass("G4_POLYSTYRENE", 0.975)
scint_mix.addMaterialWithFractionalMass("G4_NAPHTHALENE", 0.025)
scint_mix.publish(cfg)
Validation
publish(cfg) calls check_validity() before writing, which will exit with an error if:
densitywas not set- no composition method was called
addNAtomstotal atom count is ≤ 1addMaterialWithFractionalMassfractions do not sum to 1.0
Working example
The Materials example exercises definition methods and applies optical properties in a single geometry: five tubes along the z-axis, each using a different material type.
