Matter Element and MaterialP

source/element-kinds.md

@@ -214,26 +214,6 @@ Element parameter groups associated with this element kind are:
 - [**MetaP**](#s:meta.params): Meta parameters.
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 
-%---------------------------------------------------------------------------------------------------
-(s:foil)=
-## Foil Element
-
-Material that can strip electrons from a particle.
-Will also cause energy loss and diffusion.
-
-Under Construction...
-
-Element parameter groups associated with this element kind are:
-- [**ApertureP**](#s:aperture.params): Aperture parameters.
-- [**BodyShiftP**](#s:bodyshift.params): Orientation of element with respect to its nominal position.
-- [**FloorP**](#s:floor.params): Floor position and orientation.
-- [**MetaP**](#s:meta.params): Meta parameters.
-- [**ReferenceP**](#s:ref.params): Reference parameters.
-- [**ReferenceChangeP**](#s:ref.change.params): Reference energy change and/or reference time correction.
-- [**TrackingP**](#s:tracking.params): Tracking parameters.
-
-The length of this element is considered to be zero so if `length` is specified, it must be zero.
-
 %---------------------------------------------------------------------------------------------------
 (s:fork)=
 ## Fork Element
@@ -358,6 +338,23 @@ Element parameter groups associated with this element kind are:
 
 The length of this element is considered to be zero so if `length` is specified, it must be zero.
 
+%---------------------------------------------------------------------------------------------------
+(s:matter)=
+## Matter Element
+
+Materials which fully occupy the beamline, like targets, (stripper-)foils, vacuum windows, gas cells or degraders.
+This element can cause energy-loss, angualar and energy straggling, as well as change of charge state or particle type.
+
+Element parameter groups associated with this element kind are:
+- [**ApertureP**](#s:aperture.params): Aperture parameters of the outer (blocking) aperture.
+- [**BodyShiftP**](#s:bodyshift.params): Orientation of element with respect to its nominal position.
+- [**FloorP**](#s:floor.params): Floor position and orientation.
+- [**MetaP**](#s:meta.params): Meta parameters.
+- [**ReferenceP**](#s:ref.params): Reference parameters.
+- [**ReferenceChangeP**](#s:refchange.params): Reference energy change and/or reference time correction.
+- [**TrackingP**](#s:tracking.params): Tracking parameters.
+- [**MaterialP**](#s:material.params): Matter parameters. 
+
 %---------------------------------------------------------------------------------------------------
 (s:multipole)=
 ## Multipole Element

source/element-parameters.md

@@ -145,6 +145,9 @@ element-by-element.
 ```{include} parameters/master.md
 ```
 
+```{include} parameters/material.md
+```
+
 ```{include} parameters/meta.md
 ```
 

source/parameters/aperture.md

@@ -10,7 +10,7 @@ ApertureP:
   shape: ""                        # [string] Aperture shape switch
   location: ENTRANCE_END           # [enum] Aperture location switch
   vertices: []                     # [array] Array of vertex points. See below.
-  material: ""                     # [string] Material of the Aperture
+  material: ""                     # [MaterialP] Material of the Aperture
   thickness: 0                     # [m] Real number
   aperture_shifts_with_body: false # [Boolean] See below.
   aperture_active: true            # [Boolean] false implies aperture is not operating.
@@ -106,7 +106,6 @@ The difference between the two lists is simply that lines 2 and 3 are switched a
 ### material
 
 The `material` parameter sets the material of the aperture. 
-Using chemical formulas like `Cu` and `Fe` is the most portable.
 
 ### vertices component
 

source/parameters/material.md

@@ -0,0 +1,65 @@
+(s:material.params)=
+## MaterialP:  Definition of materials
+
+```{code} yaml
+MaterialP:
+- state:             # ["solid", "liquid", "gas"]
+- material:          # [CompoundP,ElementP] definiton of the material in terms of compounds or elements.
+```
+
+The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"Cu"`, `"H"`, ...) or compound (`"G4_STAINLESS-STEEL"`).
+In the future all elements and materials in the [G4 Manual](https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Appendix/materialNames.html) will be supported, without the `G4_`-prefix for elements.
+
+Alternatively custom elements can be defined by
+
+```{code} yaml
+ElementP:
+- name:      # [string] The name of the material
+- density:   # [kg/m^3] The density of the material
+- Z:         # [int]    The atomic number
+- A:         # [int]    The mass number (equals Z+N)
+- N:         # [int]    The neutron number
+- m:         # [u]      The atomic mass
+```
+
+and compounds by
+
+```{code} yaml
+CompoundP:
+- name:       # [string] The name of the material
+- density:    # [kg/m^3] The density of the material
+- elements:   # List of MaterialP or CompoundP of which the compound consists
+- ratio:      # List of ratios of the elements
+- mass_ratio: # List of mass-ratios of the elements
+```
+
+`ratio` describes the ratio in terms of atom/molecule count, while `mass_ratio` describes it int terms of mass fractions.
+If density is not given it will be inferred form the densities and mass fractions of the elements.
+
+
+### Examples
+`material: "Cu"` or `material: "G4_STAINLESS-STEEL"` or define a new material.
+
+Liquid deuterium can be defined with the `ElementP` parameters:
+```{code} yaml
+ElementP:
+- name: "Deuterium(l)"
+- density: 160
+- Z: 1
+- A: 1
+- m: 2.01
+```
+and deuterated polyethylene (C2H4) can be defined based on the previous definition
+```{code} yaml
+CompoundP:
+- name: "deutPE"
+- density: 1050
+- elements:
+  - "C"
+  - "Deuterium(l)"
+- ratio:
+  - 2
+  - 4
+```
+
+

source/parameters/matter.md

@@ -0,0 +1,10 @@
+(s:matter.params)=
+## MatterP:  Definition of materials
+
+```{code} yaml
+MatterP:
+- thickness:         # [m] Thickness in meter
+- area_density:      # [kg/m^2] Density times thickness
+- MaterialP:          # [MatterP or name] the material
+```
+Only one of the parameters `thickness` or `area_density` is required.