From 6a9bcdd00db8bc24c65b9a5066c4427e273881b4 Mon Sep 17 00:00:00 2001 From: Manuel Huber Date: Mon, 26 Aug 2024 15:55:01 +0200 Subject: [PATCH] improve docs on output filtering [skip ci] --- docs/g4manual2rst.py | 14 +++++++++++--- docs/rmg-commands.rst | 26 ++++++++++++++++++-------- src/RMGGermaniumOutputScheme.cc | 6 ++++-- src/RMGIsotopeFilterOutputScheme.cc | 8 +++++--- 4 files changed, 38 insertions(+), 16 deletions(-) diff --git a/docs/g4manual2rst.py b/docs/g4manual2rst.py index 583a53a..b34833d 100755 --- a/docs/g4manual2rst.py +++ b/docs/g4manual2rst.py @@ -35,6 +35,7 @@ def remove_whitespace_lines_end(lines: list): idx = 0 in_cmdblock = False +in_guidance = False lastlevel = -1 leveldiff = 0 @@ -52,9 +53,14 @@ def remove_whitespace_lines_end(lines: list): lastlevel = -1 leveldiff = 0 elif in_cmdblock and (line == "Guidance :"): - pass - elif in_cmdblock and (inlines[idx - 1] == "Guidance :") and not line.startswith(" " * 2): - outlines.extend([line, ""]) + in_guidance = True + elif in_cmdblock and in_guidance and not line.startswith(" "): + if line.startswith("note: "): + outlines.extend([".. note ::", "", (" " * 4) + line[6:], ""]) + elif line.strip() == "": + in_guidance = False + elif line != "": + outlines.extend([line, ""]) elif in_cmdblock and line == " Commands : " and not inlines[idx + 1].startswith(" " * 3): # ignore directories with no commands. pass @@ -62,6 +68,8 @@ def remove_whitespace_lines_end(lines: list): # ignore directories with no commands. pass elif in_cmdblock and line != "": + in_guidance = False + stripped_line = line.lstrip() indent = math.ceil((len(line) - len(stripped_line)) / 2) if line.startswith(" Range of parameters :"): diff --git a/docs/rmg-commands.rst b/docs/rmg-commands.rst index 0599f06..904943b 100644 --- a/docs/rmg-commands.rst +++ b/docs/rmg-commands.rst @@ -164,7 +164,7 @@ Commands for controlling output from hits in germanium detectors. * *SetEdepCutLow*: ``Set a lower energy cut that has to be met for this event to be stored.`` * *SetEdepCutHigh*: ``Set an upper energy cut that has to be met for this event to be stored.`` * *AddDetectorForEdepThreshold*: ``Take this detector into account for the filtering by /EdepThreshold.`` - * *DiscardPhotonsIfNoGermaniumEdep*: ``Discard optical photons (before simulating them), if no edep in germanium detectors.`` + * *DiscardPhotonsIfNoGermaniumEdep*: ``Discard optical photons (before simulating them), if no edep in germanium detectors occurred in the same event.`` Command /RMG/Output/Germanium/SetEdepCutLow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -206,7 +206,11 @@ Take this detector into account for the filtering by /EdepThreshold. Command /RMG/Output/Germanium/DiscardPhotonsIfNoGermaniumEdep ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Discard optical photons (before simulating them), if no edep in germanium detectors. +Discard optical photons (before simulating them), if no edep in germanium detectors occurred in the same event. + +.. note :: + + If another output scheme also requests the photons to be discarded, the germanium edep filter does not force the photons to be simulated. * **Parameter**: ``value`` * **Parameter type**: ``b`` @@ -292,13 +296,13 @@ Command directory path : /RMG/Output/IsotopeFilter/ Commands for filtering event out by created isotopes. * **Commands**: - * *AddIsotope*: ``Add an isotope to the list. Only events that have this isotope at any point in time will be persisted.`` - * *DiscardPhotonsIfIsotopeNotProduced*: ``Discard optical photons (before simulating them), if the specified isotopes had not been produced in this event.`` + * *AddIsotope*: ``Add an isotope to the list. Only events that have a track with this isotope at any point in time will be persisted.`` + * *DiscardPhotonsIfIsotopeNotProduced*: ``Discard optical photons (before simulating them), if the specified isotopes had not been produced in the same event.`` Command /RMG/Output/IsotopeFilter/AddIsotope ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Add an isotope to the list. Only events that have this isotope at any point in time will be persisted. +Add an isotope to the list. Only events that have a track with this isotope at any point in time will be persisted. * **Parameter**: ``A`` * **Parameter type**: ``i`` @@ -310,7 +314,11 @@ Add an isotope to the list. Only events that have this isotope at any point in t Command /RMG/Output/IsotopeFilter/DiscardPhotonsIfIsotopeNotProduced ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Discard optical photons (before simulating them), if the specified isotopes had not been produced in this event. +Discard optical photons (before simulating them), if the specified isotopes had not been produced in the same event. + +.. note :: + + If another output scheme also requests the photons to be discarded, the isotope filter does not force the photons to be simulated. * **Parameter**: ``value`` * **Parameter type**: ``b`` @@ -427,8 +435,10 @@ Command /RMG/Processes/Stepping/DaughterNucleusMaxLifetime Determines which unstable daughter nuclei will be killed, if they are at rest, depending on their lifetime. -* This applies to the defined lifetime of the nucleus, and not on the sampled actual halflife of the simulated particle. -* Set to -1 to disable this feature. +This applies to the defined lifetime of the nucleus, and not on the sampled actual halflife of the simulated particle. + +Set to -1 to disable this feature. + * **Parameter**: ``max_lifetime`` * **Parameter type**: ``d`` * **Omittable**: ``False`` diff --git a/src/RMGGermaniumOutputScheme.cc b/src/RMGGermaniumOutputScheme.cc index 1e2577c..bbe1e95 100644 --- a/src/RMGGermaniumOutputScheme.cc +++ b/src/RMGGermaniumOutputScheme.cc @@ -207,8 +207,10 @@ void RMGGermaniumOutputScheme::DefineCommands() { .SetStates(G4State_Idle); fMessenger->DeclareProperty("DiscardPhotonsIfNoGermaniumEdep", fDiscardPhotonsIfNoGermaniumEdep) - .SetGuidance( - "Discard optical photons (before simulating them), if no edep in germanium detectors.") + .SetGuidance("Discard optical photons (before simulating them), if no edep in germanium " + "detectors occurred in the same event.") + .SetGuidance("note: If another output scheme also requests the photons to be discarded, the " + "germanium edep filter does not force the photons to be simulated.") .SetStates(G4State_Idle); } diff --git a/src/RMGIsotopeFilterOutputScheme.cc b/src/RMGIsotopeFilterOutputScheme.cc index 10d283b..798a743 100644 --- a/src/RMGIsotopeFilterOutputScheme.cc +++ b/src/RMGIsotopeFilterOutputScheme.cc @@ -87,8 +87,8 @@ void RMGIsotopeFilterOutputScheme::DefineCommands() { "Commands for filtering event out by created isotopes."); fMessenger->DeclareMethod("AddIsotope", &RMGIsotopeFilterOutputScheme::AddIsotope) - .SetGuidance("Add an isotope to the list. Only events that have this isotope at any point in " - "time will be persisted.") + .SetGuidance("Add an isotope to the list. Only events that have a track with this isotope at " + "any point in time will be persisted.") .SetParameterName(0, "A", false, false) .SetParameterName(1, "Z", false, false) .SetStates(G4State_Idle); @@ -96,7 +96,9 @@ void RMGIsotopeFilterOutputScheme::DefineCommands() { fMessenger ->DeclareProperty("DiscardPhotonsIfIsotopeNotProduced", fDiscardPhotonsIfIsotopeNotProduced) .SetGuidance("Discard optical photons (before simulating them), if the specified isotopes " - "had not been produced in this event.") + "had not been produced in the same event.") + .SetGuidance("note: If another output scheme also requests the photons to be discarded, the " + "isotope filter does not force the photons to be simulated.") .SetStates(G4State_Idle); }