Defining materials
Although it is certainly possible to define Geant4 materials in dgcode via classical Geant4 C++ code, materials in dgcode are instead mostly defined via a simple material definition string (see the geometry section for how this is done in practice). This mechanism, which in the past was also known as the “NamedMaterial” mechanism, has several advantages:
Defining materials is easier.
Materials can be easily modified from command line or Python code.
It integrates directly with how materials are defined in NCrystal, allowing direct usage of these high-fidelity materials, and exposing all features of NCrystal directly.
In the following, we will provide a few general remarks about the content of these material definition strings and how to investigate their effect. After that, most users will probably find the “cookbook” of actual material examples to be the most useful reference.
General remarks
The strings defining most materials in typical dgcode projects will actually be the same strings that are used with NCrystal (aka “NCrystal cfg-strings), so you might wish to consult the NCrystal documentation for those. Most of the entries in the cookbook are indeed such NCrystal cfg-strings.
On that note, be aware that outside the cookbook you
can look for specific NCrystal materials both online in the NCrystal data
library page, or in
your terminal via the nctool command by invoking nctool
--browse. Combined with the unix grep command, you can use this for a
quick-and-dirty material search in the terminal. As an example, searching for
materials with aluminium with the command nctool -b|grep Al quickly reveals
that Al_sg225.ncmat is the correct data file name for aluminium. And this
filename is itself actually already a valid NCrystal cfg-string for room
temperature aluminium. If you wish a different temperature, it could easily be
achieved with a string like Al_sg225.ncmat;temp=200K. If you do NOT find
your material in the NCrystal data library, you can always request help getting
it defined here.
You can also read more about the available NCrystal parameters like
temp=200K either online or by invoking nctool
--doc or nctool --doc --doc. Also, be aware that if you create your own
NCrystal data files in NCMAT format (for instance
according to the tutorials here), you can place them in
either your working directory or the data/ directory of a simplebuild
package. It can then be used in material definitions via the name
<pkgname>/<filename> syntax. In other words if you have added a file
MyPkg/data/mycoolmat.ncmat, you can load and use it in cfg-strings like
MyPkg/mycoolmat.ncmat;temp=300K.
Also, if you want to explicitly indicate that you only want the input file to
be taken from the official NCrystal data library, you can prefix the name with
stdlib:: (i.e. stdlib::Al_sg225.ncmat;temp=200K would use the
Al_sg225.ncmat file from the official data library, even if you happened to
have a file named Al_sg225.ncmat lying around in your working
directory). For this reason, most of the examples in the cookbook will use the stdlib:: prefix.
In addition to NCrystal materials, you can also use any material from Geant4’s
own built-in database of elements and NIST compounds,
and even override their temperature or density, using dedicated keywords
temp_kelvin (\(\mathrm{K}\)), density_gcm3
(\(\mathrm{g}/\mathrm{cm}^3\)), density_kgm3
(\(\mathrm{kg}/\mathrm{m}^3\)), and scale_density. For instance,
xenon at \(200\mathrm{K}\) and \(5.4\mathrm{kg}/\mathrm{m}^3\)
could be modelled with a string G4_Xe;temp_kelvin=200.0;density_kgm3=5.4
(although gases are in general more easily defined with the NCrystal
syntax).
Tip
Note that while Geant4 NIST materials provide material compositions, they in general do not contain information about any structure in the position and movements of atoms inside the material. This structure is often very important when modelling scattering interactions with thermal neutrons, so in general only use Geant4 NIST materials if your material is dominated by non-scattering effects (e.g. strongly absorbing materials) or you are not modelling thermal neutrons. If in doubt, prefer to use an NCrystal material.
Most users should not have a need for anything else than NCrystal cfg-strings
and Geant4 NIST materials, but a few other mostly deprecated options are
supported for backwards compatibility. As they are deprecated, they will not be
mentioned here or used in the cookbook, with the
exception of the special MAT_B4C keyword used for enriched boron
carbide.
Investigating materials
One advantage of defining materials via strings, is that it is possible to use various tools to investigate properties of the materials, besides just using them in a simulation. Below follows two recommended options for doing that in dgcode.
Inspect via NCrystal utilities
The material definitions which are also NCrystal cfg-strings,
can be investigated with NCrystal tools. The most easily used of these is the
command line tool nctool, and the usage is very simple. First of all,
detailed thermal neutron cross sections and sample neutron scattering
distributions for the material can be found simply by feeding the material
string in question directly to nctool (remember the ' quotes around
the string, or your terminal might misinterpret some of the special
characters inside it):
$> nctool 'stdlib::Al_sg225.ncmat;temp=250K'
Add a flag -a if you want absorption cross sections included as well, but
be aware that NCrystal only supports a simple 1/v model of absorption
which will break down at higher neutron energies. When using the material
inside a Geant4 simulation, the more detailed absorption models by Geant4
will be used instead.
It is also possible to compare two materials, for instance to see how the temperature affects the cross sections:
$> nctool 'stdlib::Al_sg225.ncmat;temp=250K' 'stdlib::Al_sg225.ncmat;temp=500K'
To get some printed information about the material, rather than cross section
plots, you can use the --dump (or the shorter -d) to get such
information printed:
$> nctool -d 'stdlib::Al_sg225.ncmat;temp=250K'
----------------------------------------------------------------------------------------------------
------------------------------------ NCrystal Material Info ------------------------------------
----------------------------------------------------------------------------------------------------
Data source: stdlib::Al_sg225.ncmat
----------------------------------------------------------------------------------------------------
Density : 2.69865 g/cm3, 0.0602324 atoms/Aa^3
----------------------------------------------------------------------------------------------------
Composition (by mole): 100% Al
----------------------------------------------------------------------------------------------------
Composition (by mass): 100% Al
----------------------------------------------------------------------------------------------------
Atom data:
Al = Al(cohSL=3.449fm cohXS=1.49485barn incXS=0.0082barn absXS=0.231barn mass=26.9815u Z=13)
----------------------------------------------------------------------------------------------------
Averaged quantities:
Atomic mass : 26.9815u
Absorption XS at 2200m/s : 0.231 barn
Free scattering XS : 1.39667 barn
Scattering length density : 2.07741 10^-6/Aa^2
----------------------------------------------------------------------------------------------------
Temperature : 250 kelvin
----------------------------------------------------------------------------------------------------
State of matter: Solid (crystalline)
----------------------------------------------------------------------------------------------------
Space group number : 225
Lattice spacings [Aa] : 4.04958 4.04958 4.04958
Lattice angles [deg] : 90 90 90
Unit cell volume [Aa^3] : 66.4095
Atoms / unit cell : 4
----------------------------------------------------------------------------------------------------
Atoms in unit cell (total 4):
4 Al atoms [T_Debye=412.198K, MSD=0.00851973Aa^2]
----------------------------------------------------------------------------------------------------
Atomic coordinates:
Al 0 0 0
Al 0 1/2 1/2
Al 1/2 0 1/2
Al 1/2 1/2 0
----------------------------------------------------------------------------------------------------
Dynamic info for Al (100%):
type: S(alpha,beta) [from VDOS]
VDOS Source: 4970 points
VDOS E_max: 39.829 meV
----------------------------------------------------------------------------------------------------
HKL info type: SymEqvGroup
----------------------------------------------------------------------------------------------------
HKL planes (d_lower = 0.1 Aa, d_upper = inf Aa):
H K L d_hkl[Aa] Mult. FSquared[barn]
1 1 1 2.33803 8 1.78972
2 0 0 2.02479 6 1.75338
2 2 0 1.43174 12 1.61528
3 1 1 1.22099 24 1.51889
2 2 2 1.16901 8 1.48805
4 0 0 1.01239 6 1.37084
3 3 1 0.929037 24 1.28904
4 2 0 0.905514 24 1.26287
4 2 2 0.826617 24 1.1634
5 1 1 0.779342 24 1.09397
(some planes left out for brevity, increase verbosity to show all)
----------------------------------------------------------------------------------------------------
If you wish to read about how the material inside Al_sg225.ncmat was
defined, and perhaps read some comments about how the material was created
(or which publications to cite, etc.), you can find the file in the online
data library, or simple ask NCrystal to show you the contents (for this usage,
first remove parameters like ;temp=250K):
$> nctool --extract 'stdlib::Al_sg225.ncmat'
Many more options exists, to see them all run:
$> nctool --help
In case nctool does not exactly provide the plots you need, you might
instead find it useful to simply investigate the material via the NCrystal
Python API. A short example is found here,
and Jupyter notebooks with much more details can be found here (do not forget to
scroll down and read the instructions).
Inspect via Geant4-based utilities
The NCrystal-based approaches outlined in the previous section are mostly suited for investigating scattering cross sections of thermal neutrons, and obviously only works for materials which are defined by NCrystal cfg-strings. To investigate other kinds of materials or cross sections, or the effects of different physics lists, it is useful to be able to inspect the cross sections directly as they actually manifest themselves in a Geant4 job. This is fortunately easily done in dgcode, and is documented on this dedicated page.
Additionally, if one is mostly interested in the basic composition of a given
material, one can simply feed the material string in question to the command
sb_g4materials_dump:
$> sb_g4materials_dump G4_STAINLESS-STEEL:temp_kelvin=200:scale_density=1.1
===================================================================================
Material defined by string "G4_STAINLESS-STEEL:temp_kelvin=200:scale_density=1.1":
Material: G4_STAINLESS-STEEL:temp_kelvin=200:scale_density=1.1 density: 8.800 g/cm3 RadL: 1.580 cm Nucl.Int.Length: 15.162 cm
Imean: 282.977 eV temperature: 200.00 K pressure: 1.00 atm
---> Element: Fe (Fe) Z = 26.0 N = 56 A = 55.845 g/mole
---> Isotope: Fe54 Z = 26 N = 54 A = 53.94 g/mole abundance: 5.845 %
---> Isotope: Fe56 Z = 26 N = 56 A = 55.93 g/mole abundance: 91.754 %
---> Isotope: Fe57 Z = 26 N = 57 A = 56.94 g/mole abundance: 2.119 %
---> Isotope: Fe58 Z = 26 N = 58 A = 57.93 g/mole abundance: 0.282 %
ElmMassFraction: 74.62 % ElmAbundance 74.00 %
---> Element: Cr (Cr) Z = 24.0 N = 52 A = 51.996 g/mole
---> Isotope: Cr50 Z = 24 N = 50 A = 49.95 g/mole abundance: 4.345 %
---> Isotope: Cr52 Z = 24 N = 52 A = 51.94 g/mole abundance: 83.789 %
---> Isotope: Cr53 Z = 24 N = 53 A = 52.94 g/mole abundance: 9.501 %
---> Isotope: Cr54 Z = 24 N = 54 A = 53.94 g/mole abundance: 2.365 %
ElmMassFraction: 16.90 % ElmAbundance 18.00 %
---> Element: Ni (Ni) Z = 28.0 N = 59 A = 58.693 g/mole
---> Isotope: Ni58 Z = 28 N = 58 A = 57.94 g/mole abundance: 68.077 %
---> Isotope: Ni60 Z = 28 N = 60 A = 59.93 g/mole abundance: 26.223 %
---> Isotope: Ni61 Z = 28 N = 61 A = 60.93 g/mole abundance: 1.140 %
---> Isotope: Ni62 Z = 28 N = 62 A = 61.93 g/mole abundance: 3.635 %
---> Isotope: Ni64 Z = 28 N = 64 A = 63.93 g/mole abundance: 0.926 %
ElmMassFraction: 8.48 % ElmAbundance 8.00 %
===================================================================================