species type extension: formulate ideas from openPMD#256 (clarificati…

…ons, adding ABNF...)
s9105947 · Jan 26, 2022 · f0a6e6e · f0a6e6e
1 parent 07bb7c5
commit f0a6e6e
Showing 1 changed file with 115 additions and 39 deletions.
diff --git a/EXT_SpeciesType.md b/EXT_SpeciesType.md
@@ -3,13 +3,15 @@ Convention for Specifying Particle Species
 
 openPMD extension name: `SpeciesType`
 
-
 Introduction
 ------------
 
 This convention is for standardizing the names of particle species, e.g. in
 particle physics.
 
+This document uses ABNF as speciefied by [RFC 5234][rfc5234].
+
+[rfc5234]: https://datatracker.ietf.org/doc/html/rfc5234
 
 Additional Record Attribute
 ---------------------------
@@ -24,76 +26,150 @@ The following additional attribute for openPMD `mesh records` and
                  species to be specified, they can be specified using a
                  semicolon separated list.
   - allowed values:
-    - *see the lists below* and additionally
-    - `other` if none of the ones below applies, user are free to append a
-      free text after a colon, e.g. `other:neutralino` or `other:cherry`
+    - a single *particle species*, which is either:
+      - one of the list entries below, or
+      - `other:` followed by any number of spaces (ascii 0x20) or
+        visible ("printing") ascii characters, i.e. ascii 0x21 to 0x7e
+    - a *particle species list*, which is multiple entries of the
+      list below separated by a single semicolon character `;`.
+      A trailing semicolon `;` is allowed, but not required.
+  - ABNF:
+    ```
+    species-type = species-single / species-list / species-other
+    species-other = "other:" *( VCHAR / SP )
+    species-list = species-single *( ";" species-single ) [ ";" ]
+    species-single = elementary / hadron-or-jet / atom
+    ```
   - examples:
     - `electron` (e.g. on an electron `particle record` or an electron
                   density `mesh record`)
     - `electron;proton;#12C` (e.g. on a `mesh record` for a plasma's
                               local charge density)
-    - `other:apple;other:orange` (for a `record` mixing apples & oranges)
+    - `other:apple` (e.g. for an apple `particle record`)
 
 This attribute can be used with any `record` (including `mesh records`).
 
+A particle species list containing only a single item MUST be treated as a
+single species.
+
+> Note that `other:` can *only* be used for single species, it is
+> forbidden in lists.
+>
+> The list separator is a sole `;`. Neither spaces around it nor empty
+> list items (two semicolons following each other `;;`) are allowed.
+> However, a single trailing semicolon `;` MUST be ignored.
+
+The following values SHOULD NOT be used by an implementation, even if
+they are allowed above:
+
+- `other:`, as it does not specify any content.
+- Trailing spaces, as they can lead to ambiguous display.
+
 ### Elementary Particles
 
 Namings for fundamental fermions and their anti-matter particles.
 
 Quarks:
-  - `up`, `anti-up`
-  - `down`, `anti-down`
-  - `charm`, `anti-charm`
-  - `strange`, `anti-strange`
-  - `top`, `anti-top`
-  - `bottom`, `anti-bottom`
+
+- `up`, `anti-up`
+- `down`, `anti-down`
+- `charm`, `anti-charm`
+- `strange`, `anti-strange`
+- `top`, `anti-top`
+- `bottom`, `anti-bottom`
 
 Leptons:
-  - `electron`, `positron`
-  - `electron-neutrino`, `anti-electron-neutrino`
-  - `muon`, `anti-muon`
-  - `muon-neutrino`, `anti-muon-neutrino`
-  - `tau`, `anti-tau`
-  - `tau-neutrino`, `anti-tau-neutrino`
+
+- `electron`, `positron`
+- `electron-neutrino`, `anti-electron-neutrino`
+- `muon`, `anti-muon`
+- `muon-neutrino`, `anti-muon-neutrino`
+- `tau`, `anti-tau`
+- `tau-neutrino`, `anti-tau-neutrino`
 
 Gauge & Higgs Bosons:
-  - `photon`
-  - `gluon`
-  - `w-boson`
-  - `z-boson`
-  - `higgs`
+
+- `photon`
+- `gluon`
+- `w-boson`
+- `z-boson`
+- `higgs`
+
+ABNF:
+
+```
+elementary = quark / lepton / boson
+
+quark = quark-anti / quark-normal
+qurak-anti = "anti-" quark-normal
+quark-normal = "up" / "down" / "charm" / "strange" / "top" / "bottom"
+
+lepton = lepton-anti / lepton-normal
+lepton-anti = "positron" / "anti-electron-neutrino" / "anti-muon" / "anti-muon-neutrino" / "anti-tau" / "anti-tau-neutrino"
+lepton-normal = "electron" / "electron-neutrino" / "muon" / "muon-neutrino" / "tau" / "tau-neutrino"
+
+boson = "photon" / "gluon" / "w-boson" / "z-boson" / "higgs"
+```
 
 ### Hadrons and Jets
 
 We currently do not define spellings of hadrons besides the commonly used ones
-below and suggest for this version to use `other:` with namings from the
-[particle data group (PDG)](http://pdg.lbl.gov/). Other means of grouping e.g.
-jets can be used, e.g. additional attributes outside of the definition of this
-extension.
+below.
+
+For particle species not mentioned here we suggest to use `other:`
+with namings from the [particle data group (PDG)](http://pdg.lbl.gov/).
 
 Examples:
-  - `proton`, `anti-proton`
-  - `neutron`, `anti-neutron`
-  - `other:sigma`, `other:anti-sigma`
-  - `other:kaon`, ...
+
+- `proton`, `anti-proton`
+- `neutron`, `anti-neutron`
+- `other:sigma`, `other:anti-sigma`
+- `other:kaon`, ...
+
+> Keep in mind that particle species with `other:` can't be used in
+> particle species lists.
+
+ABNF:
+
+```
+hadron-or-jet = hadron-or-jet-normal / hadron-or-jet-anti
+hadron-or-jet-anti = "anti-" hadron-or-jet-normal
+hadron-or-jet-normal = "proton" / "neutron"
+```
 
 ### Atoms & Isotopes
 
-Element namings follow the abbreviated namings of the periodic table, defined
+Valid element names are the symbols of the periodic table, defined
 by *The International Union of Pure and Applied Chemistry* (IUPAC).
 An example would be `Si` for silicon.
 
+The names are case sensitive.
+
 Specifications of isotopes are denoted by a pound symbol `#` followed
-by the isotopic number followed by the chemical symbol, e.g.: `#3He`
-for Helium-3.
+by the isotopic number followed by an element, e.g.: `#3He` for
+Helium-3.
+
+ABNF:
+
+```
+atom = element / isotope
+isotope = "#" 1*DIGIT element
+element = "H" / "He" / "Li" / "Be" / "B" / "C" / "N" / "O" / "F" / "Ne" / "Na" / "Mg" / "Al" / "Si" / "P" / "S" / "Cl" / "Ar" / "K" / "Ca" / "Sc" / "Ti" / "V" / "Cr" / "Mn" / "Fe" / "Co" / "Ni" / "Cu" / "Zn" / "Ga" / "Ge" / "As" / "Se" / "Br" / "Kr" / "Rb" / "Sr" / "Y" / "Zr" / "Nb" / "Mo" / "Tc" / "Ru" / "Rh" / "Pd" / "Ag" / "Cd" / "In" / "Sn" / "Sb" / "Te" / "I" / "Xe" / "Cs" / "Ba" / "La" / "Ce" / "Pr" / "Nd" / "Pm" / "Sm" / "Eu" / "Gd" / "Tb" / "Dy" / "Ho" / "Er" / "Tm" / "Yb" / "Lu" / "Hf" / "Ta" / "W" / "Re" / "Os" / "Ir" / "Pt" / "Au" / "Hg" / "Tl" / "Pb" / "Bi" / "Po" / "At" / "Rn" / "Fr" / "Ra" / "Ac" / "Th" / "Pa" / "U" / "Np" / "Pu" / "Am" / "Cm" / "Bk" / "Cf" / "Es" / "Fm" / "Md" / "No" / "Lr" / "Rf" / "Db" / "Sg" / "Bh" / "Hs" / "Mt" / "Ds" / "Rg" / "Cn" / "Nh" / "Fl" / "Mc" / "Lv" / "Ts" / "Og"
+```
+
 
 The charge state is not encoded by the `speciesType` attribute.
-Any extension using this standard can define how to specify the charge state.
 
-### Molecules
+The charge state ("ionization") is an attribute of an individual
+particle, and therefore an implementation SHOULD NOT encode a charge
+state as part of the `speciesType` in any way.
+In the case that the implementation does treat the charge state
+("ionization") as a global, unmodifiable property of the `speciesType`
+it MAY encode a charge state in an implementation-defined way.
 
-Use standard chemical notation, e.g.: `H20`.
+### Molecules
+Molecules are not supported by the `speciesType` attribute.
 
-The isotope prefix can be used with molecules as well.
-Examples for heavy water: `#2H2O` for two deuterium and `#2HHO` for one
-deuterium.
+However, an implementation MAY encode molecules using an
+implementation-defined syntax. In this case typical chemical notation
+SHOULD be accepted, e.g. `H2O` for water.