Warning, /swf-monitor/docs/PCS_BACKGROUND_TAG.md is written in an unsupported language. File is not indexed.
0001 # PCS Background Tag (`k`)
0002
0003 The fifth PCS tag type, prefix `k`. It names a background configuration —
0004 beam-gas, synchrotron radiation, or other pre-generated overlay samples — as a
0005 named, reusable tag, independent of any physics signal, taking its place in the
0006 dataset name alongside `p`, `e`, `s`, `r`.
0007
0008 ## Purpose
0009
0010 Background is generated independently of any physics signal and mixed into many.
0011 It is not a physics process tied to a particular signal — that
0012 independence is why it is a tag type of its own rather than a field on the
0013 physics or evgen tag. Folding background into the physics tag would multiply the
0014 physics tags by every background; a separate overlay keeps the count additive,
0015 not combinatorial. One background definition is reused across every signal it
0016 overlays.
0017
0018 Its configuration is currently spread across `EvgenTag` (`signal_freq`,
0019 `bg_tag_prefix`, `bg_files`) and `ProdConfig` (`bg_mixing`, `bg_cross_section`,
0020 `bg_evtgen_file`), unnamed and unversioned. The `k` tag gathers it into one
0021 locked record and gives it a place in the dataset identity, alongside those
0022 fields rather than replacing them.
0023
0024 ## Why `k`
0025
0026 A distinct letter keeps physics tags decimal, rather than folding a background
0027 digit into `p` and forcing rethinking numbering (e.g. hex). `b` is already the block suffix
0028 (`.b1`, `.b2`).
0029
0030 ## Schema
0031
0032 In `pcs/schemas.py`. Field values are open strings; the listed values are form
0033 suggestions, not a closed set, so the path parser passes through whatever a
0034 future sample names.
0035
0036 - Required: `background_type` (e.g. `BEAMGAS`, `SYNRAD`).
0037 - Sample-defining, populated by the campaign import: `bg_source` (e.g.
0038 `electron`, `proton`), `bg_mechanism` (e.g. `brems`, `coulomb`, `touschek`;
0039 blank when the path names a generator instead), `bg_generator` (generator/tool
0040 and version/release), `beam_energy_electron`, `beam_energy_hadron`.
0041 - Overlay/mixing, for a background mixed into a signal: `cross_section`,
0042 `signal_freq`, `bg_tag_prefix`, `evtgen_file`. Also `beam_species`, `notes`.
0043
0044 The beam energies the background was generated for live here, on the background
0045 tag; for a standalone background sample the physics slot is the signal-free
0046 `p6001` tag, which carries no beam.
0047
0048 ## Import
0049
0050 The campaign importer parses each EVGEN backgrounds path into these parameters,
0051 resolves or creates the `k` tag (`find_or_create_background_tag`, matching the
0052 sample-defining fields), and binds the dataset to `p6001` plus that `k` tag.
0053 A single 4th segment that is not a known mechanism is taken as the generator; a
0054 bare `NGeV` beam is assigned to the electron or hadron beam by source.
0055
0056 ## Behavior
0057
0058 `k` is structurally identical to `e`/`s`/`r`: sequential labels `k1`, `k2`, …,
0059 `draft → locked`, creator-owned, no categories. A dataset carries at most one
0060 background tag, set independently of its physics tag.
0061
0062 ## The no-signal physics tag
0063
0064 Every dataset names a physics tag. A standalone background sample has no signal,
0065 so it names `p6001` — a single physics tag in a new category 6, created once,
0066 all parameters blank. It means "no physics signal; see the background
0067 tag." A dataset that mixes background into a real signal keeps that signal's
0068 physics tag and adds a `k`.
0069
0070 During alpha commissioning, `k` tags and `p6001` are created `draft`, not
0071 `locked` — like every other PCS tag — so ops can shape the campaign-to-tag
0072 mapping freely; reproducibility locking moves to submission prep. See
0073 [Commissioning Relaxations](COMMISSIONING_RELAXATIONS.md).
0074
0075 ## Dataset name
0076
0077 `k` appends after reco, before the Rucio block:
0078
0079 ```
0080 {scope}.{detector_version}.{detector_config}.{p}.{e}.{s}.{r}.{k} → DID …{k}.b{N}
0081 ```
0082
0083 The segment is present only when the dataset carries a background.
