From 48fa10f639226f85173ecab4ec82a2f64b05dc83 Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:05:00 +0200
Subject: [PATCH 01/16] Create material.md

---
 source/parameters/material.md | 54 +++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 source/parameters/material.md

diff --git a/source/parameters/material.md b/source/parameters/material.md
new file mode 100644
index 0000000..37fe53f
--- /dev/null
+++ b/source/parameters/material.md
@@ -0,0 +1,54 @@
+(s:material.params)=
+## MaterialP:  Definition of materials
+
+The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"G4_Cu"`, `"G4_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.
+
+Alternatively custom elements can be defined by
+
+```
+ElementP:
+- name:      # [string] The name of the material
+- density:   # [g/cm^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:         # [g/mol]  The atomic mass
+```
+
+and compunds by
+
+```
+CompundP:
+- name:      # [string] The name of the material
+- density:   # [g/cm^3] The density of the material
+- elements:  # List of MaterialP
+- ratio:    # List of ratios of the elements
+```
+
+### Examples
+`MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
+
+Liquid deuterium can be defined with the `ElementP` parameters:
+```
+MaterialP:
+- name: "Deuterium(l)"
+- density: 0.16
+- Z: 1
+- A: 1
+- m: 2.01
+```
+and deuterated polyethylene (C2H4) can be defined based on the previous definition
+```
+MaterialP:
+- name: "deutPE"
+- density: 1.05
+- elements:
+  - "G4_C"
+  - "Deuterium(l)"
+- ratio:
+  - 2
+  - 4
+```
+
+

From 5c5112ad1dd344ee31c8c680dc52d8d3adbd6ae1 Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:08:54 +0200
Subject: [PATCH 02/16] Update aperture.md

---
 source/parameters/aperture.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/parameters/aperture.md b/source/parameters/aperture.md
index f0e9df3..3f84473 100644
--- a/source/parameters/aperture.md
+++ b/source/parameters/aperture.md
@@ -12,7 +12,7 @@ refp1:                            # [string] user-defined name
   location: ENTRANCE_END          # [string] Aperture location switch
   aperture_shifts_with_body: ...  # [Boolean] ... TODO: describe ... TODO: default
   vertices: {}                    # [Dictionary] ... TODO: describe ...
-  material: ""                    # [string] Material of the Aperture
+  material: ""                    # [MaterialP] Material of the Aperture
   thickness: 0                    # [m] Real number
 ```
 
@@ -103,7 +103,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
 

From 1e320d811c92803a925c7d473061390989e50b4d Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:11:06 +0200
Subject: [PATCH 03/16] Update material.md

---
 source/parameters/material.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index 37fe53f..d61e91c 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -6,7 +6,7 @@ In the future all elements and materials in the [G4 Manual](https://geant4-userd
 
 Alternatively custom elements can be defined by
 
-```
+```{code} yaml
 ElementP:
 - name:      # [string] The name of the material
 - density:   # [g/cm^3] The density of the material
@@ -14,32 +14,32 @@ ElementP:
 - A:         # [int]    The mass number (equals Z+N)
 - N:         # [int]    The neutron number
 - m:         # [g/mol]  The atomic mass
-```
+```{code} yaml
 
 and compunds by
 
-```
+```{code} yaml
 CompundP:
 - name:      # [string] The name of the material
 - density:   # [g/cm^3] The density of the material
 - elements:  # List of MaterialP
 - ratio:    # List of ratios of the elements
-```
+```{code} yaml
 
 ### Examples
 `MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
 
 Liquid deuterium can be defined with the `ElementP` parameters:
-```
+```{code} yaml
 MaterialP:
 - name: "Deuterium(l)"
 - density: 0.16
 - Z: 1
 - A: 1
 - m: 2.01
-```
+```{code} yaml
 and deuterated polyethylene (C2H4) can be defined based on the previous definition
-```
+```{code} yaml
 MaterialP:
 - name: "deutPE"
 - density: 1.05
@@ -49,6 +49,6 @@ MaterialP:
 - ratio:
   - 2
   - 4
-```
+```{code} yaml
 
 

From 8ee25a90725316ab63f5e57cf131f2c2cf2a13cc Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:11:37 +0200
Subject: [PATCH 04/16] Update material.md

---
 source/parameters/material.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index d61e91c..8fe243c 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -14,7 +14,7 @@ ElementP:
 - A:         # [int]    The mass number (equals Z+N)
 - N:         # [int]    The neutron number
 - m:         # [g/mol]  The atomic mass
-```{code} yaml
+```
 
 and compunds by
 
@@ -24,7 +24,7 @@ CompundP:
 - density:   # [g/cm^3] The density of the material
 - elements:  # List of MaterialP
 - ratio:    # List of ratios of the elements
-```{code} yaml
+```
 
 ### Examples
 `MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
@@ -37,7 +37,7 @@ MaterialP:
 - Z: 1
 - A: 1
 - m: 2.01
-```{code} yaml
+```
 and deuterated polyethylene (C2H4) can be defined based on the previous definition
 ```{code} yaml
 MaterialP:
@@ -49,6 +49,6 @@ MaterialP:
 - ratio:
   - 2
   - 4
-```{code} yaml
+```
 
 

From 549b3600d60d216f2341f184ae3c3669a8c4c342 Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:15:57 +0200
Subject: [PATCH 05/16] Update element-parameters.md

---
 source/element-parameters.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/element-parameters.md b/source/element-parameters.md
index 0a3d76d..3981462 100644
--- a/source/element-parameters.md
+++ b/source/element-parameters.md
@@ -126,6 +126,9 @@ element-by-element.
 ```{include} parameters/magneticmultipole.md
 ```
 
+```{include} parameters/material.md
+```
+
 ```{include} parameters/meta.md
 ```
 

From 112e061562c6ade1db6422d56cf594a95678ebba Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:38:29 +0200
Subject: [PATCH 06/16] Update element-kinds.md

---
 source/element-kinds.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/element-kinds.md b/source/element-kinds.md
index 9620e73..e4df9e7 100644
--- a/source/element-kinds.md
+++ b/source/element-kinds.md
@@ -215,22 +215,24 @@ Element parameter groups associated with this element kind are:
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 
 %---------------------------------------------------------------------------------------------------
-(s:foil)=
-## Foil Element
+(s:matter)=
+## Matter Element
 
+Materials which fully occupy the beamline, like targets, (stripper-)foils, vacuum windows, gas cells or degraders
 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.
+- [**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.
+- [**MatterP**](#s:matter.params)
 
 The length of this element is considered to be zero so if `length` is specified, it must be zero.
 

From 1591fcae6ece1284c42784a8282061db1e39ce05 Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:08:54 +0200
Subject: [PATCH 07/16] Update aperture.md

Update material.md

Update material.md

Update element-parameters.md

Update element-kinds.md
---
 source/element-kinds.md       | 8 +++++---
 source/element-parameters.md  | 3 +++
 source/parameters/aperture.md | 3 +--
 source/parameters/material.md | 8 ++++----
 4 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/source/element-kinds.md b/source/element-kinds.md
index 9620e73..e4df9e7 100644
--- a/source/element-kinds.md
+++ b/source/element-kinds.md
@@ -215,22 +215,24 @@ Element parameter groups associated with this element kind are:
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 
 %---------------------------------------------------------------------------------------------------
-(s:foil)=
-## Foil Element
+(s:matter)=
+## Matter Element
 
+Materials which fully occupy the beamline, like targets, (stripper-)foils, vacuum windows, gas cells or degraders
 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.
+- [**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.
+- [**MatterP**](#s:matter.params)
 
 The length of this element is considered to be zero so if `length` is specified, it must be zero.
 
diff --git a/source/element-parameters.md b/source/element-parameters.md
index 0a3d76d..3981462 100644
--- a/source/element-parameters.md
+++ b/source/element-parameters.md
@@ -126,6 +126,9 @@ element-by-element.
 ```{include} parameters/magneticmultipole.md
 ```
 
+```{include} parameters/material.md
+```
+
 ```{include} parameters/meta.md
 ```
 
diff --git a/source/parameters/aperture.md b/source/parameters/aperture.md
index f0e9df3..3f84473 100644
--- a/source/parameters/aperture.md
+++ b/source/parameters/aperture.md
@@ -12,7 +12,7 @@ refp1:                            # [string] user-defined name
   location: ENTRANCE_END          # [string] Aperture location switch
   aperture_shifts_with_body: ...  # [Boolean] ... TODO: describe ... TODO: default
   vertices: {}                    # [Dictionary] ... TODO: describe ...
-  material: ""                    # [string] Material of the Aperture
+  material: ""                    # [MaterialP] Material of the Aperture
   thickness: 0                    # [m] Real number
 ```
 
@@ -103,7 +103,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
 
diff --git a/source/parameters/material.md b/source/parameters/material.md
index 37fe53f..8fe243c 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -6,7 +6,7 @@ In the future all elements and materials in the [G4 Manual](https://geant4-userd
 
 Alternatively custom elements can be defined by
 
-```
+```{code} yaml
 ElementP:
 - name:      # [string] The name of the material
 - density:   # [g/cm^3] The density of the material
@@ -18,7 +18,7 @@ ElementP:
 
 and compunds by
 
-```
+```{code} yaml
 CompundP:
 - name:      # [string] The name of the material
 - density:   # [g/cm^3] The density of the material
@@ -30,7 +30,7 @@ CompundP:
 `MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
 
 Liquid deuterium can be defined with the `ElementP` parameters:
-```
+```{code} yaml
 MaterialP:
 - name: "Deuterium(l)"
 - density: 0.16
@@ -39,7 +39,7 @@ MaterialP:
 - m: 2.01
 ```
 and deuterated polyethylene (C2H4) can be defined based on the previous definition
-```
+```{code} yaml
 MaterialP:
 - name: "deutPE"
 - density: 1.05

From a0e1a05c1f47a38f9fcea8b769ae05bf54459553 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Fri, 26 Sep 2025 13:23:23 +0200
Subject: [PATCH 08/16] Reorderes element-kinds.md

---
 source/element-kinds.md | 40 ++++++++++++++++++----------------------
 1 file changed, 18 insertions(+), 22 deletions(-)

diff --git a/source/element-kinds.md b/source/element-kinds.md
index e4df9e7..b7f46b1 100644
--- a/source/element-kinds.md
+++ b/source/element-kinds.md
@@ -214,28 +214,6 @@ Element parameter groups associated with this element kind are:
 - [**MetaP**](#s:meta.params): Meta parameters.
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 
-%---------------------------------------------------------------------------------------------------
-(s:matter)=
-## Matter Element
-
-Materials which fully occupy the beamline, like targets, (stripper-)foils, vacuum windows, gas cells or degraders
-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 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.
-- [**MatterP**](#s:matter.params)
-
-The length of this element is considered to be zero so if `length` is specified, it must be zero.
-
 %---------------------------------------------------------------------------------------------------
 (s:fork)=
 ## Fork Element
@@ -360,6 +338,24 @@ 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.
+- [**MatterP**](#s:matter.params)
+
+
 %---------------------------------------------------------------------------------------------------
 (s:multipole)=
 ## Multipole Element

From 1e318227bbd3d2212c77f2e4941fbad16366c1d0 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Fri, 26 Sep 2025 13:25:19 +0200
Subject: [PATCH 09/16] Added Description

---
 source/element-kinds.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/element-kinds.md b/source/element-kinds.md
index b7f46b1..0a36207 100644
--- a/source/element-kinds.md
+++ b/source/element-kinds.md
@@ -353,7 +353,7 @@ Element parameter groups associated with this element kind are:
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 - [**ReferenceChangeP**](#s:refchange.params): Reference energy change and/or reference time correction.
 - [**TrackingP**](#s:tracking.params): Tracking parameters.
-- [**MatterP**](#s:matter.params)
+- [**MatterP**](#s:matter.params): Matter parameters.
 
 
 %---------------------------------------------------------------------------------------------------

From b2fbdb23ec329b08b30d4282f5403e0e8c87a859 Mon Sep 17 00:00:00 2001
From: danielkallendorf <103370285+danielkallendorf@users.noreply.github.com>
Date: Fri, 26 Sep 2025 01:05:00 +0200
Subject: [PATCH 10/16] Define matter in beamlines with MaterialP Update
 aperture.md to use MaterialP Update element-parameters.md Update
 element-kinds.md

---
 source/element-kinds.md       | 38 ++++++++++++------------
 source/element-parameters.md  |  3 ++
 source/parameters/aperture.md |  3 +-
 source/parameters/material.md | 54 +++++++++++++++++++++++++++++++++++
 4 files changed, 76 insertions(+), 22 deletions(-)
 create mode 100644 source/parameters/material.md

diff --git a/source/element-kinds.md b/source/element-kinds.md
index 9620e73..0a36207 100644
--- a/source/element-kinds.md
+++ b/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:refchange.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,24 @@ 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.
+- [**MatterP**](#s:matter.params): Matter parameters.
+
+
 %---------------------------------------------------------------------------------------------------
 (s:multipole)=
 ## Multipole Element
diff --git a/source/element-parameters.md b/source/element-parameters.md
index 0a3d76d..3981462 100644
--- a/source/element-parameters.md
+++ b/source/element-parameters.md
@@ -126,6 +126,9 @@ element-by-element.
 ```{include} parameters/magneticmultipole.md
 ```
 
+```{include} parameters/material.md
+```
+
 ```{include} parameters/meta.md
 ```
 
diff --git a/source/parameters/aperture.md b/source/parameters/aperture.md
index f0e9df3..3f84473 100644
--- a/source/parameters/aperture.md
+++ b/source/parameters/aperture.md
@@ -12,7 +12,7 @@ refp1:                            # [string] user-defined name
   location: ENTRANCE_END          # [string] Aperture location switch
   aperture_shifts_with_body: ...  # [Boolean] ... TODO: describe ... TODO: default
   vertices: {}                    # [Dictionary] ... TODO: describe ...
-  material: ""                    # [string] Material of the Aperture
+  material: ""                    # [MaterialP] Material of the Aperture
   thickness: 0                    # [m] Real number
 ```
 
@@ -103,7 +103,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
 
diff --git a/source/parameters/material.md b/source/parameters/material.md
new file mode 100644
index 0000000..8fe243c
--- /dev/null
+++ b/source/parameters/material.md
@@ -0,0 +1,54 @@
+(s:material.params)=
+## MaterialP:  Definition of materials
+
+The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"G4_Cu"`, `"G4_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.
+
+Alternatively custom elements can be defined by
+
+```{code} yaml
+ElementP:
+- name:      # [string] The name of the material
+- density:   # [g/cm^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:         # [g/mol]  The atomic mass
+```
+
+and compunds by
+
+```{code} yaml
+CompundP:
+- name:      # [string] The name of the material
+- density:   # [g/cm^3] The density of the material
+- elements:  # List of MaterialP
+- ratio:    # List of ratios of the elements
+```
+
+### Examples
+`MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
+
+Liquid deuterium can be defined with the `ElementP` parameters:
+```{code} yaml
+MaterialP:
+- name: "Deuterium(l)"
+- density: 0.16
+- Z: 1
+- A: 1
+- m: 2.01
+```
+and deuterated polyethylene (C2H4) can be defined based on the previous definition
+```{code} yaml
+MaterialP:
+- name: "deutPE"
+- density: 1.05
+- elements:
+  - "G4_C"
+  - "Deuterium(l)"
+- ratio:
+  - 2
+  - 4
+```
+
+

From c96aff8aa0c29b8b2e8c8a47b54174884582c25f Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 1 Oct 2025 17:00:54 +0200
Subject: [PATCH 11/16] Updated units to SI

---
 source/parameters/material.md | 108 +++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 54 deletions(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index 8fe243c..97f53a3 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -1,54 +1,54 @@
-(s:material.params)=
-## MaterialP:  Definition of materials
-
-The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"G4_Cu"`, `"G4_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.
-
-Alternatively custom elements can be defined by
-
-```{code} yaml
-ElementP:
-- name:      # [string] The name of the material
-- density:   # [g/cm^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:         # [g/mol]  The atomic mass
-```
-
-and compunds by
-
-```{code} yaml
-CompundP:
-- name:      # [string] The name of the material
-- density:   # [g/cm^3] The density of the material
-- elements:  # List of MaterialP
-- ratio:    # List of ratios of the elements
-```
-
-### Examples
-`MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
-
-Liquid deuterium can be defined with the `ElementP` parameters:
-```{code} yaml
-MaterialP:
-- name: "Deuterium(l)"
-- density: 0.16
-- Z: 1
-- A: 1
-- m: 2.01
-```
-and deuterated polyethylene (C2H4) can be defined based on the previous definition
-```{code} yaml
-MaterialP:
-- name: "deutPE"
-- density: 1.05
-- elements:
-  - "G4_C"
-  - "Deuterium(l)"
-- ratio:
-  - 2
-  - 4
-```
-
-
+(s:material.params)=
+## MaterialP:  Definition of materials
+
+The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"G4_Cu"`, `"G4_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.
+
+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 compunds by
+
+```{code} yaml
+CompundP:
+- name:      # [string] The name of the material
+- density:   # [kg/cm^3] The density of the material
+- elements:  # List of MaterialP
+- ratio:    # List of ratios of the elements
+```
+
+### Examples
+`MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
+
+Liquid deuterium can be defined with the `ElementP` parameters:
+```{code} yaml
+MaterialP:
+- 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
+MaterialP:
+- name: "deutPE"
+- density: 1050
+- elements:
+  - "G4_C"
+  - "Deuterium(l)"
+- ratio:
+  - 2
+  - 4
+```
+
+

From ca877c453d4415d7954781405c87c3731849ab14 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 22 Oct 2025 14:36:48 +0200
Subject: [PATCH 12/16] Fixed typos

---
 source/element-kinds.md     |  3 +--
 source/parameters/matter.md | 10 ++++++++++
 2 files changed, 11 insertions(+), 2 deletions(-)
 create mode 100644 source/parameters/matter.md

diff --git a/source/element-kinds.md b/source/element-kinds.md
index 0a36207..29268b3 100644
--- a/source/element-kinds.md
+++ b/source/element-kinds.md
@@ -353,8 +353,7 @@ Element parameter groups associated with this element kind are:
 - [**ReferenceP**](#s:ref.params): Reference parameters.
 - [**ReferenceChangeP**](#s:refchange.params): Reference energy change and/or reference time correction.
 - [**TrackingP**](#s:tracking.params): Tracking parameters.
-- [**MatterP**](#s:matter.params): Matter parameters.
-
+- [**MaterialP**](#s:material.params): Matter parameters. 
 
 %---------------------------------------------------------------------------------------------------
 (s:multipole)=
diff --git a/source/parameters/matter.md b/source/parameters/matter.md
new file mode 100644
index 0000000..19a50aa
--- /dev/null
+++ b/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
+- state:             # ["solid", "liquid", "gas"]
+```
+Only one of the parameters `thickness` or `area_density` is required.
\ No newline at end of file

From 65afa38639e76972ac82b66dc34328c06459d5d0 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 22 Oct 2025 15:49:33 +0200
Subject: [PATCH 13/16] Added mass_ratio and explanation, removed G4_ for
 elemnents

---
 source/parameters/material.md | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index dd42038..22505d6 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -1,8 +1,8 @@
 (s:material.params)=
 ## MaterialP:  Definition of materials
 
-The definition of materials is inspired by Geant4's material handling. One can either use the name, which is the symbol of an element (`"G4_Cu"`, `"G4_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.
+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
 
@@ -16,23 +16,27 @@ ElementP:
 - m:         # [u]      The atomic mass
 ```
 
-and compunds by
+and compounds by
 
 ```{code} yaml
-CompundP:
-- name:      # [string] The name of the material
-- density:   # [kg/cm^3] The density of the material
-- elements:  # List of MaterialP
-- ratio:     # List of ratios of the elements
-- mass_ratio:# List of mass-ratios of the elements
+CompoundP:
+- name:       # [string] The name of the material
+- density:    # [kg/cm^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
-`MaterialP: "G4_Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
+`MaterialP: "Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
 
 Liquid deuterium can be defined with the `ElementP` parameters:
 ```{code} yaml
-MaterialP:
+ElementP:
 - name: "Deuterium(l)"
 - density: 160
 - Z: 1
@@ -41,11 +45,11 @@ MaterialP:
 ```
 and deuterated polyethylene (C2H4) can be defined based on the previous definition
 ```{code} yaml
-MaterialP:
+CompoundP:
 - name: "deutPE"
 - density: 1050
 - elements:
-  - "G4_C"
+  - "C"
   - "Deuterium(l)"
 - ratio:
   - 2

From c21ae4f0354388fcf36d191ae8d91d56f6d261e2 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 22 Oct 2025 15:49:51 +0200
Subject: [PATCH 14/16] Moved state into MaterialP

---
 source/parameters/material.md | 120 ++++++++++++++++++----------------
 source/parameters/matter.md   |   2 +-
 2 files changed, 64 insertions(+), 58 deletions(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index 22505d6..619b43e 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -1,59 +1,65 @@
-(s:material.params)=
-## MaterialP:  Definition of materials
-
+(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/cm^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
-`MaterialP: "Cu"` or `MaterialP: "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
-```
-
-
+
+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/cm^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
+`MaterialP: "Cu"` or `MaterialP: "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
+```
+
+
diff --git a/source/parameters/matter.md b/source/parameters/matter.md
index 19a50aa..29c58c5 100644
--- a/source/parameters/matter.md
+++ b/source/parameters/matter.md
@@ -5,6 +5,6 @@
 MatterP:
 - thickness:         # [m] Thickness in meter
 - area_density:      # [kg/m^2] Density times thickness
-- state:             # ["solid", "liquid", "gas"]
+- MaterialP:          # [MatterP or name] the material
 ```
 Only one of the parameters `thickness` or `area_density` is required.
\ No newline at end of file

From a69ff4572c79783f88ec89cbccc242db352fd25b Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 22 Oct 2025 15:54:51 +0200
Subject: [PATCH 15/16] Fixed MatterP example

---
 source/parameters/material.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index 619b43e..72e87cc 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -38,7 +38,7 @@ If density is not given it will be inferred form the densities and mass fraction
 
 
 ### Examples
-`MaterialP: "Cu"` or `MaterialP: "G4_STAINLESS-STEEL"` or define a new material.
+`material: "Cu"` or `material: "G4_STAINLESS-STEEL"` or define a new material.
 
 Liquid deuterium can be defined with the `ElementP` parameters:
 ```{code} yaml

From ba4c56afb55e9e0feef2e16f5f0e463eb0a3b270 Mon Sep 17 00:00:00 2001
From: Daniel Kallendorf <daniel@kallendorf.com>
Date: Wed, 22 Oct 2025 15:58:00 +0200
Subject: [PATCH 16/16] Fix: fixed unit of CompoundP

---
 source/parameters/material.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/parameters/material.md b/source/parameters/material.md
index 72e87cc..2b4d138 100644
--- a/source/parameters/material.md
+++ b/source/parameters/material.md
@@ -27,7 +27,7 @@ and compounds by
 ```{code} yaml
 CompoundP:
 - name:       # [string] The name of the material
-- density:    # [kg/cm^3] The density 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