Updated list of tags and reformatted details. Updated in use cases too.

Author: sjdkay

_episodes/02-rucio_usage.md

@@ -188,48 +188,64 @@ The following tags are available as of March 2026:
 
 - **software\_release**
   - Software release used in the simulation. Written as a container version tag/simulation campaign naming:
-  - v**YY**.**MM**.**v**
-  - E.g. v25.06.2 -> June 2025 software container, version 2
+  - **YY**.**MM**.**v**
+  - E.g. 25.06.2-stable -> June 2025 software container, version 2
+- **is\_background\_mixed**
+  - True/false depending upon whether sample includes any background mixing
+- **data\_level**
+  - Level of simulation data, `simulation` or `reconstruction`
+- **geometry\_config**
+  - Geometry config tag, e.g. `craterlake_18x275`, `craterlake_5x41_He3`
+- **generator**
+  - MC event generator used to generate the simulated data
+    - `pythia6`, `pythia8`, `beagle`, `djangoh`, `rapgap`, `dempgen`, `sartre`, `lager`, `estarlight`, `eic_sr_geant4`, `eic_esr_xsuite`, `sherpa`, `single_particle`, `other` 
 - **requester\_pwg**
   - Defines the physics working group (PWG) that the simulated data relates to, options are:
-    - edt (exclusive, diffractive and tagging)
-    - inclusive
-    - jets\_hf
-    - semi\_inclusive
-    - ew\_bsm
-    - other
+    - `edt` (exclusive, diffractive and tagging), `inclusive`, `jets_hf`, `semi_inclusive`, `ew_bsm`, `other`
   - **Can be one or more**
-- **q2\_min**
-  - Minumum Q2 value (GeV^2) in the simulation file, entered as a number.
-  - **Optional tag** - Not all simulated files use this
-- **q2\_max**
-  - Maximum Q2 value (GeV^2) in the simulation file, entered as a number.
-  - **Optional tag** - Not all simulated files use this
-- **electron\_beam\_energy**
+  - Skipped for SINGLE/BACKGROUNDS
+- **requester\_dsc**
+  - Detector subsystem collaboration requester
+    - `tracking`, `other`
+  - Set to `tracking` for background related datasets
+- **electron\_beam\_energy\_gev**
   - Electron beam energy in GeV
-- **ion\_beam\_energy**
+- **ion\_beam\_energy\_gev**
   - Ion/nucleus beam energy in GeV
-- **is\_background\_mixed**
-  - True/false depending upon whether sample includes any background mixing
 - **ion\_species**
   - Ion species in the simulation, defaults to `p`, proton, if not specified
     - Typed as formatted in files, e.g. `Au197` for gold, `He3` for helium 3 etc.
     - `Cu63`, `H2`, `Ru96` and `p` are some other options 
-- **generator**
-  - MC event generator used to generate the simulated data
-  - E.g. Pythia8, Herwig etc
-  - Entered as all lower case
-    - E.g. `dempgen` *not* `DEMPgen`
-
-As noted on some items in this list, some tags are optional and may not be applied to all datasets. However, the following tags are **required** for all datasets:
+- **q2\_min\_gev2**
+  - Minimum Q2 value (GeV^2) in the simulation file, entered as a number.
+- **q2\_max_gev2**
+  - Maximum Q2 value (GeV^2) in the simulation file, entered as a number.
+- **gun\_particle**
+  - Single particle type
+    - `e-`, `e+`, `proton`, `neutron`, `pi+`, `pi-`, `pi0`, `kaon-`, `kaon+`, `gamma`, `mu-`
+- **gun\_momentum\_min\_gev**
+  - Minimum gun momentum in GeV
+- **gun\_momentum\_max\_gev**
+  - Maximum gun momentum in GeV
+- **gun\_theta\_min\_deg**
+  - Minimum gun polar angle in degrees
+- **gun\_theta\_max\_deg**
+  - Maximum gun polar angle in degrees
+- **gun\_phi\_min\_deg**
+  - Minimum gun azimuthal angle in degrees, default 0
+- **gun\_phi\_max\_deg**
+  - Maximum gun azimuthal angle in degrees, default 360
+- **gun\_distribution**
+  - Type of distribution for particle gun
+    - `uniform`, `cos(theta)`, `eta`, `pseudorapidity`, `ffbar`
+
+Most of the tags in this list are optional and may not be applied to all datasets. However, the following tags are **required** for all datasets:
 
-- software\_release
-- physics\_process
-- electron\_beam\_energy
-- ion\_beam\_energy
-- is\_background\_mixed
-- ion\_species
-- generator
+- **software\_release**
+- **is\_background\_mixed**
+- **data\_level**
+- **geometry\_config**
+- **generator**
 
 Note that as mentioned for the generator, tags are entered in lower case, **with the exception of ion species**.
 
@@ -242,13 +258,13 @@ rucio did list --filter 'TAG==*' 'scope:*'
 So, as an example, we could list all DIDs with electron beam energies of 10 GeV via:
 
 ```bash
-rucio did list --filter 'electron_beam_energy==10' 'epic:*'
+rucio did list --filter 'electron_beam_energy_gev==10' 'epic:*'
 ```
 
 We can also combine tags and filter on several at once, e.g:
 
 ```bash
-rucio did list --filter 'electron_beam_energy==10, ion_beam_energy==250' 'epic:*'
+rucio did list --filter 'electron_beam_energy_gev==10, ion_beam_energy_gev==250' 'epic:*'
 ```
 
 which will return only datasets with 10x250 collisions (10 GeV electrons on 250 GeV ions using the standard ePIC conventions). We can keep adding filters in this manner as we like to really narrow down the DIDs we return with our query.

_episodes/03-use_cases.md

@@ -30,22 +30,23 @@ To find files that meet their requirements they could utilise the following tags
 
 - software\_release
 - requester\_pwg
-- electron\_beam\_energy
-- ion\_beam\_energy
+- electron\_beam\_energy\_gev
+- ion\_beam\_energy\_gev
 - ion\_species
+- data\_level
 
 We can use these tags to filter through the DIDs and find datasets of interest:
 
 ```bash
-rucio did list --filter 'software_release==XXX, requester_pwg==YYY, electron_beam_energy==ZZ, ion_beam_energy==iii, ion_species==jjj' 'epic:*'
+rucio did list --filter 'software_release==XXX, requester_pwg==YYY, electron_beam_energy_gev==ZZ, ion_beam_energy_gev==iii, ion_species==jjj' 'epic:*'
 ```
 
 Where we can substitute in our chosen values for each in place of `XXX`, `YYY`, `ZZ`, `iii` and `jjj`.
 
 > ## `Beam Energies:` 
-> Whilst we can enter any number for the `electron_beam_energy` and `ion_beam_energy` values, there are only certain combinations actually in use.
-> `electron_beam_energy` is typically 5, 10 or 18 GeV
-> `ion_beam_energy` is typically 41, 100, 130, 250 or 275 GeV for protons.
+> Whilst we can enter any number for the `electron_beam_energy_gev` and `ion_beam_energy_gev` values, there are only certain combinations actually in use.
+> `electron_beam_energy_gev` is typically 5, 10 or 18 GeV
+> `ion_beam_energy_gev` is typically 41, 100, 130, 250 or 275 GeV for protons.
 > For other ion species, 110 and 166 may also be used.
 {: .callout}
 
@@ -89,11 +90,12 @@ To find files that meet their requirements they could utilise the following tags
 
 - software\_release
 - physics\_process
-- electron\_beam\_energy
-- ion\_beam\_energy
+- electron\_beam\_energy\_gev
+- ion\_beam\_energy\_gev
 - generator
+- data\_level
 
-They may also want to use the `q2_min` ad `q2_max` tags, along with the `ion_species` tags to narrow down to an even more specific subset of files. They may also want to analyse files with or without background enabled.
+They may also want to use the `q2_min_gev2` ad `q2_max_gev2` tags, along with the `ion_species` tags to narrow down to an even more specific subset of files. They may also want to analyse files with or without background enabled.
 
 As they want to process a large number of files, **it is unlikely (and not recommended) that they download a large number of files to process them locally**. Instead, they may want to stream their files directly in their analysis script. They could do this via: