Go Back to: C++ Manual General Site

LDMX.Biasing package

Submodules

LDMX.Biasing.eat module

Example configurations for producing biased interactions in the ECal.

This module is built for the ECal as Target (EaT) analysis channel where we are studying the events that have a primary electron reaching the ECal at nearly full energy.

Example

from LDMX.Biasing import eat

LDMX.Biasing.eat.dark_brem(ap_mass, db_event_lib, detector, generator, scale_aprime=False, decay_mode='no_decay', ap_tau=-1.0, dist_decay_min=0.0, dist_decay_max=1.0)

Example configuration for producing dark brem interactions in the ECal.

This configures the simulator to fire a 4 GeV electron upstream of the tagger tracker. The electron is allowed to propagate into the ECal where the dark-photon production cross-section is biased up. Only events that result in a dark-photon being produced in the ECal are kept.

Parameters:

• ap_mass (float) – The mass of the A’ in MeV.

• db_event_lib (str) – The path to the reference library to use as vertices of the dark brem.

• detector (str) – Path to the detector.

• generator (simcfg.PrimaryGenerator) – Beam generator for this simulation which should be a ParticleGun so we can configure the PrimaryToEcalFilter to select events where beam electrons retain 87.5% of their energy.

• scale_aprime (bool) – Whether to scale the A’ momentum along with the recoil electron.

• decay_mode (str) – The A’ decay mode. Either no_decay, flat_decay, or geant_decay

• ap_tau (float) – The A’ decay lifetime in seconds

• dist_decay_min (float) – The minimum lab-frame distance at which to decay the A’

• dist_decay_max (float) – The maximum lab-frame distance at which to decay the A’

Return type:

Instance of the simulator configured for dark-brem production in the ECal.

Example

from LDMX.SimCore import generators eat_ap_sim = eat.dark_brem(

1000., ‘path/to/1GeV_mA_library’, ‘ldmx-det-v14’, generators.single_e_4gev_upstream_tagger()

)

LDMX.Biasing.eat.midshower_dimuon(detector, generator, bias_factor, bias_threshold, min_dimuon_energy)

Example configuration for producing mid-shower dimuon interactions in the ECal that fake a missing energy (ME) signal.

In this particular example, 4 GeV electrons are fired upstream of the tagger tracker. Then simulation events are then put through a series of filters.

Parameters:

• detector (str) – Name of the detector

• generator (simcfg.PrimaryGenerator) – Beam generator for this simulation which should be a ParticleGun so we can configure the PrimaryToEcalFilter to select events where beam electrons retain 87.5% of their energy.

• bias_factor (float) – Factor to multiply GammaToMuPair xsec by within the ECal

• bias_threshold (float) – Minium energy [MeV] to bias a photon

• min_dimuon_energy (float) – Minium total energy [MeV] that went to muons to keep event

Returns:

configured for mid-shower dimuon interactions and far-upstream generator

Return type:

simulator

Example

from LDMX.Biasing import eat from LDMX.SimCore import generators eat_dimuon = eat.midshower_dimuon(

‘ldmx-det-v14’, generators.single_e_4gev_upstream_tagger(), 1e4, 500., 1000.

)

LDMX.Biasing.eat.midshower_nuclear(detector, generator, bias_factor, bias_threshold, min_nuclear_energy)

Example configuration for producing mid-shower nuclear interactions in the ECal that fake a missing energy (ME) signal.

In this particular example, 4 GeV electrons are fired upstream of the tagger tracker. Then simulation events are then put through a series of filters.

Parameters:

• detector (str) – Name of the detector

• generator (simcfg.PrimaryGenerator) – Beam generator for this simulation which should be a ParticleGun so we can configure the PrimaryToEcalFilter to select events where beam electrons retain 87.5% of their energy.

• bias_factor (float) – Factor to multiply EN/PN xsecs by

• bias_threshold (float) – Minium energy [MeV] to bias a particle

• min_nuclear_energy (float) – Minium total energy [MeV] that went nuclear to keep event

Returns:

configured for mid-shower nuclear interactions and far-upstream generator

Return type:

simulator

Example

from LDMX.Biasing import eat from LDMX.SimCore import generators eat_dimuon = eat.midshower_nuclear(

‘ldmx-det-v14’, generators.single_e_4gev_upstream_tagger(), 200, 1500., 2500.

)

LDMX.Biasing.ecal module

Example configurations for producing biased interactions in the ECal.

Example

from LDMX.Biasing import ecal

LDMX.Biasing.ecal.deep_photo_nuclear(detector, generator, bias_threshold, processes, ecal_min_z, require_photon_from_target=False)

LDMX.Biasing.ecal.gamma_mumu(detector, generator)

Example configuration for biasing gamma to mu+ mu- conversions in the ecal.

In this particular example, 4 GeV elecrons are fired upstream of the tagger tracker. The TargetBremFilter filters out all events that don’t produce a brem in the target with an energy greater than 2.5 GeV.

Parameters:

detector (str) – Path to the detector

Return type:

Instance of the sim configured for target gamma to muon conversions.

Example

ecal_mumu_sim = ecal.gamma_mumu(‘ldmx-det-v12’)

LDMX.Biasing.ecal.nonfiducial_photo_nuclear(detector, generator)

LDMX.Biasing.ecal.photo_nuclear(detector, generator)

Example configuration for producing photo-nuclear reactions in the ECal.

In this particular example, 4 GeV electrons are fired upstream of the tagger tracker. The TargetBremFilter filters out all events that don’t produced a brem in the target with an energy greater than 2.5 GeV. The brems are allowed to propagate to the ECal at which point they are checked by the EcalProcessFilter. Only events that see the brem photon undergo a photo-nuclear reaction in the ECal are kept.

Parameters:

• detector (str) – Path to the detector

• generator (PrimaryGenerator) – generator to use

Return type:

Instance of the simulator configured for ECal photo-nuclear.

Example

ecal_pn_sim = ecal.photo_nuclear(‘ldmx-det-v12’)

LDMX.Biasing.filters module

configuration for event filtering user actions

class LDMX.Biasing.filters.DeepEcalProcessFilter(bias_threshold: float, processes: list[str], ecal_min_z: float, require_photon_from_target: bool, instance_name: str = 'biasing::DeepEcalProcessFilter')

Bases: UserAction

Configuration for keeping events where the pn happens deep in the ECAL.

Parameters:

• bias_threshold (double) – Threshold for minimum energy that the products should have

• processes (vector of str) – The allowed processes that can happen deep inside the ECAL, default is conversion (conv) and photoelectron (photo)

• ecal_min_z (double) – Minimum Z location where the deep process should happen

• require_photon_from_target (bool) – Require that the hard brem photon originates from the target Default is False

bias_threshold: float

class_name: str = 'biasing::DeepEcalProcessFilter'

ecal_min_z: float

instance_name: str = 'biasing::DeepEcalProcessFilter'

module_name: str = 'Biasing'

processes: list[str]

require_photon_from_target: bool

class LDMX.Biasing.filters.EcalDarkBremFilter(threshold: float, instance_name: str = 'biasing::EcalDarkBremFilter')

Bases: UserAction

Configuration for filtering A’ events

Parameters:

threshold (float) – Minimum A’ energy to keep the event [MeV]

class_name: str = 'biasing::EcalDarkBremFilter'

instance_name: str = 'biasing::EcalDarkBremFilter'

module_name: str = 'Biasing'

threshold: float

class LDMX.Biasing.filters.EcalProcessFilter(process: str = 'photonNuclear', instance_name: str = 'biasing::EcalProcessFilter')

Bases: UserAction

Configuration for filtering events that don’t see a hard brem undergo a photo-nuclear reaction in the ECal.

Parameters:

process (str) – Geant4 process to look for in the ecal

class_name: str = 'biasing::EcalProcessFilter'

instance_name: str = 'biasing::EcalProcessFilter'

module_name: str = 'Biasing'

process: str = 'photonNuclear'

class LDMX.Biasing.filters.MidShowerDiMuonBkgdFilter(threshold: float, instance_name: str = 'biasing::MidShowerDiMuonBkgdFilter')

Bases: UserAction

Configuration used to reject events that don’t have enough energy given to muon conversion

Parameters:

threshold (float) – Minimum energy [MeV] that needs to go into creating the muons

class_name: str = 'biasing::MidShowerDiMuonBkgdFilter'

instance_name: str = 'biasing::MidShowerDiMuonBkgdFilter'

module_name: str = 'Biasing'

threshold: float

class LDMX.Biasing.filters.MidShowerNuclearBkgdFilter(threshold: float, instance_name: str = 'biasing::MidShowerNuclearBkgdFilter')

Bases: UserAction

Configuration used to reject events that don’t have enough energy given to the input process.

Parameters:

threshold (float) – Minimum energy [MeV] that the kinetic energy of the products needs to sum to

class_name: str = 'biasing::MidShowerNuclearBkgdFilter'

instance_name: str = 'biasing::MidShowerNuclearBkgdFilter'

module_name: str = 'Biasing'

threshold: float

class LDMX.Biasing.filters.NonFiducialFilter(recoil_max_p: float, abort_fiducial: bool = True, instance_name: str = 'biasing::NonFiducialFilter')

Bases: UserAction

Configuration for rejecting events that are fiducial.

Parameters:

• recoil_max_p (float) – Maximum momentum the recoil electron can have [MeV]

• abort_fiducial (bool) – If true, aborts fiducial events. Otherwise, the fiducial events will be only tagged

abort_fiducial: bool = True

class_name: str = 'biasing::NonFiducialFilter'

instance_name: str = 'biasing::NonFiducialFilter'

module_name: str = 'Biasing'

recoil_max_p: float

class LDMX.Biasing.filters.PrimaryToEcalFilter(threshold: float, instance_name: str = 'biasing::PrimaryToEcalFilter')

Bases: UserAction

Configuration used to reject events where the primary doesn’t reach the ecal with a mimimum energy

Parameters:

threshold (float) – Minimum energy [MeV] that primary electron should have when hitting ecal

class_name: str = 'biasing::PrimaryToEcalFilter'

instance_name: str = 'biasing::PrimaryToEcalFilter'

module_name: str = 'Biasing'

threshold: float

class LDMX.Biasing.filters.TaggerHitFilter(layers_hit: int = 8, instance_name: str = 'biasing::TaggerHitFilter')

Bases: UserAction

Configuration used to reject off-energy electrons in the tagger tracker.

Parameters:

layers_hit (int) – Minimum number of tagger layers with a hit needed to persist the event.

class_name: str = 'biasing::TaggerHitFilter'

instance_name: str = 'biasing::TaggerHitFilter'

layers_hit: int = 8

module_name: str = 'Biasing'

class LDMX.Biasing.filters.TaggerVetoFilter(threshold: float, reject_events_missing_tagger: bool = True, instance_name: str = 'biasing::TaggerVetoFilter')

Bases: UserAction

Configuration used to reject off-energy electrons in the tagger tracker.

Parameters:

• threshold (float) – Minimum energy [MeV] that electron should have

• reject_events_missing_tagger (bool) – Also veto events where the primary particle misses the tagger region

class_name: str = 'biasing::TaggerVetoFilter'

instance_name: str = 'biasing::TaggerVetoFilter'

module_name: str = 'Biasing'

reject_events_missing_tagger: bool = True

threshold: float

class LDMX.Biasing.filters.TargetBremFilter(recoil_max_p_threshold: float, brem_min_energy_threshold: float, kill_recoil_track: bool = False, instance_name: str = 'biasing::TargetBremFilter')

Bases: UserAction

Configuration for filtering events that don’t see a hard brem in the target.

An event is vetoed if one of two conditions is satisfied: 1) The recoil electron exits the target area with an energy above 1500 MeV 2) The recoil electorn brems, but the energy of at least one of the brems isn’t above 2500 MeV.

Parameters:

• recoil_max_p_threshold (float) – Maximum momentum the recoil electron can have [MeV]

• brem_min_energy_threshold (float) – Minimum energy the brem photon can have [MeV]

kill_recoil_track

Should we kill the recoil electron track for a worst case scenario?

Type:

bool

brem_min_energy_threshold: float

class_name: str = 'biasing::TargetBremFilter'

instance_name: str = 'biasing::TargetBremFilter'

kill_recoil_track: bool = False

module_name: str = 'Biasing'

recoil_max_p_threshold: float

class LDMX.Biasing.filters.TargetDarkBremFilter(threshold: float, instance_name: str = 'biasing::TargetDarkBremFilter')

Bases: UserAction

Configuration for filtering A’ events

Parameters:

threshold (float) – Minimum A’ energy to keep the event [MeV]

class_name: str = 'biasing::TargetDarkBremFilter'

instance_name: str = 'biasing::TargetDarkBremFilter'

module_name: str = 'Biasing'

threshold: float

class LDMX.Biasing.filters.TargetENFilter(recoil_threshold: float, instance_name: str = 'biasing::TargetENProcessFilter')

Bases: UserAction

Configuration for filtering electro-nuclear events in the target.

Parameters:

recoil_threshold (float) – Maximum energy recoil electron is allowed to have [MeV]

class_name: str = 'biasing::TargetENProcessFilter'

instance_name: str = 'biasing::TargetENProcessFilter'

module_name: str = 'Biasing'

recoil_threshold: float

class LDMX.Biasing.filters.TargetProcessFilter(process: str = 'photonNuclear', instance_name: str = 'biasing::TargetProcessFilter')

Bases: UserAction

Configuration for filtering photo-nuclear events in the target.

aprime_to_fcp()

class_name: str = 'biasing::TargetProcessFilter'

gamma_mu_mu()

gamma_to_fcp()

instance_name: str = 'biasing::TargetProcessFilter'

module_name: str = 'Biasing'

photo_nuclear()

process: str = 'photonNuclear'

LDMX.Biasing.particle_filter module

PN topology filtering user actions

class LDMX.Biasing.particle_filter.PhotoNuclearProductsFilter(pdg_ids: list[int] = <factory>, min_e: float = 0.0, instance_name: str = 'biasing::PhotoNuclearProductsFilter')

Bases: UserAction

Configuration for keeping events with specific products of PN interactions

pdg_ids

List of PDG product IDs to look for in PN products

Type:

list of ints

min_e

minimum energy

Type:

float

class_name: str = 'biasing::PhotoNuclearProductsFilter'

instance_name: str = 'biasing::PhotoNuclearProductsFilter'

kaon()

Configuration for filtering photo-nuclear events whose products don’t contain a kaon.

Return type:

Instance of configured PhotoNuclearProductsFilter

min_e: float = 0.0

module_name: str = 'Biasing'

pdg_ids: list[int]

class LDMX.Biasing.particle_filter.PhotoNuclearTopologyFilter(hard_particle_threshold: float, count_light_ions: bool = True, instance_name: str = 'UNDEFINED')

Bases: UserAction

Configuration for keeping events with a PN reaction producing a particular event topology.

Parameters:

• instance_name (str) – Name for this filter

• class_name (str) – Name of the class that implements this filter. Should correspond to the invocation of DECLARE_ACTION in PhotoNuclearTopologyFilters.cxx

hard_particle_threshold

The kinetic energy threshold required to count a particle as “hard”

Type:

float

count_light_ions

Whether or not light ions (e.g. deutrons) should be considered when applying the filter. Setting this to False can produce misleading results such as classifying events with very high kinetic energy light ions as “Nothing Hard” but it is the current default choice in the PhotoNuclearDQM.

Type:

bool

class_name: str = 'UNDEFINED'

count_light_ions: bool = True

hard_particle_threshold: float

instance_name: str = 'UNDEFINED'

module_name: str = 'Biasing'

nothing_hard()

Configuration for keeping photonuclear events no particles received significant kinetic energy.

Return type:

Instance of configured PhotoNuclearTopologyFilter

single_neutron()

Configuration for keeping photonuclear events where a single neutron carries most of the kinetic energy from the interaction

Return type:

Instance of configured PhotoNuclearTopologyFilter

LDMX.Biasing.target module

Example configurations for producing biased interactions in the target.

Example

from LDMX.Biasing import target

LDMX.Biasing.target.aprime_to_fcp(ap_mass, fcp_mass, lhe, detector, generator, fcp_charge=0.1, fcp_xsec_factor=10000000000.0, scale_aprime=False, decay_mode='no_decay', ap_tau=-1.0, dist_decay_min=0.0, dist_decay_max=1.0)

Example configuration for producing A’ -> fcp+ fcp- in the target.

This configures the sim to fire an 8 GeV electron upstream of the tagger tracker. The dark-photon production cross-section is biased up in the target. The A’ then converts to a pair of fractionally charged particles (fcp+ fcp-) via the APrimeToFCPPair process.

Parameters:

• ap_mass (float) – The mass of the A’ in MeV (should be small / near zero).

• fcp_mass (float) – The mass of the fcp in MeV.

• lhe (str) – The path to the directory containing LHE files to use as events of the dark brem.

• detector (str) – Name of detector to simulate in.

• generator (PrimaryGenerator) – Generator to use for the primary particles.

• fcp_charge (float, optional) – Electric charge of the fcp in units of e (default: 0.1).

• fcp_xsec_factor (float, optional) – Cross section biasing factor for A’ -> fcp conversion. The physical cross section scales as q^4, so for q=0.1e a factor ~1e8 is needed for conversions (default: 1e8).

• scale_aprime (bool, optional) – Should we scale the A’ (default: False).

• decay_mode (str, optional) – Decay mode for the A’ (default: ‘no_decay’).

• ap_tau (float, optional) – Proper lifetime of the A’ (default: -1.0).

• dist_decay_min (float, optional) – Minimum decay distance (default: 0.0).

• dist_decay_max (float, optional) – Maximum decay distance (default: 1.0).

Return type:

Instance of the sim configured for A’ -> fcp+ fcp- production in the target.

Example

from LDMX.SimCore import makePath target_fcp_sim = target.aprime_to_fcp(

0.01, 100., makePath.makeLHEPath(0.01), ‘ldmx-det-v15-8gev’, generators.single_8gev_e_upstream_tagger())

LDMX.Biasing.target.dark_brem(ap_mass, lhe, detector, generator, scale_aprime=False, decay_mode='no_decay', ap_tau=-1.0, dist_decay_min=0.0, dist_decay_max=1.0)

Example configuration for producing dark brem interactions in the target.

This configures the sim to fire a 8 GeV electron upstream of the tagger tracker. The dark-photon production cross-section is biased up in the target. Only events that result in a dark-photon being produced in the target are kept.

Parameters:

• ap_mass (float) – The mass of the A’ in MeV.

• lhe (str) – The path to the directory containing LHE files to use as events of the dark brem.

• detector (str) – Name of detector to simulate in

Return type:

Instance of the sim configured for dark-brem production in the target.

Example

In general, the second argument should be the full path to the LHE event library.

target_ap_sim = target.dark_brem(1000, ‘path/to/lhe’, ‘ldmx-det-v12’)

LDMX.Biasing.target.electro_nuclear(detector, generator)

Example configuration for producing electro-nuclear reactions in the target.

In this particular example, 8 GeV electrons are fired upstream of the tagger tracker. TargetENFilter filters out events that don’t see an electro-nuclear reaction take places in the target.

Parameters:

detector (str) – Path to the detector

Return type:

Instance of the sim configured for target electro-nuclear.

Example

target_en_sim = target.electro_nuclear(‘ldmx-det-v12’)

LDMX.Biasing.target.gamma_mumu(detector, generator)

Example configuration for biasing gamma to mu+ mu- conversions in the target.

In this particular example, 8 GeV electrons are fired upstream of the tagger tracker. The TargetBremFilter filters out all events that don’t produced a brem in the target with an energy greater than 5 GeV.

Parameters:

detector (str) – Path to the detector

Return type:

Instance of the sim configured for target gamma to muon conversions.

Example

target_mumu_sim = target.gamma_mumu(‘ldmx-det-v12’)

LDMX.Biasing.target.gamma_to_fcp(detector, generator, fcp_mass, fcp_charge=0.1)

Example configuration for biasing gamma to fcp+ fcp- target conversions

In this particular example, electrons are fired upstream of the tagger tracker. The TargetBremFilter filters out all events that don’t produce a brem in the target with sufficient energy. The gamma -> fcp conversion process is then biased up.

This is the SM-photon analogue of gamma_mumu(), producing fractionally charged particles instead of muons.

Parameters:

• detector (str) – Path to the detector

• generator (PrimaryGenerator) – Generator to use for the primary particles.

• fcp_mass (float) – The mass of the fcp in MeV.

• fcp_charge (float, optional) – Electric charge of the fcp in units of e (default: 0.1).

Return type:

Instance of the sim configured for target gamma to fcp conversions.

Example

target_fcp_sim = target.gamma_to_fcp(‘ldmx-det-v15-8gev’,

generators.single_8gev_e_upstream_tagger(), 100.0)

LDMX.Biasing.target.photo_nuclear(detector, generator)

Example configuration for producing photo-nuclear reactions in the ECal.

In this particular example, 4 GeV electrons are fired upstream of the tagger tracker. The TargetBremFilter filters out all events that don’t produced a brem in the target with an energy greater than 2.5 GeV. TargetBremFilter filters out events that don’t see the brem photon undergo a photo-nuclear reaction in the target.

Parameters:

detector (str) – Path to the detector

Return type:

Instance of the sim configured for target photo-nuclear.

Example

target_pn_sim = target.photo_nuclear(‘ldmx-det-v12’)

LDMX.Biasing.util module

Utility classes for Simulation

class LDMX.Biasing.util.DecayChildrenKeeper(parents: list[int], instance_name: str = 'biasing::utility::DecayChildrenKeeper')

Bases: UserAction

Configuration used to store children of specific particle decays

Parameters:

parents (list[int]) – list of PDG ID of particles whose decay products we want to keep

class_name: str = 'biasing::utility::DecayChildrenKeeper'

instance_name: str = 'biasing::utility::DecayChildrenKeeper'

module_name: str = 'Biasing_Utility'

parents: list[int]

class LDMX.Biasing.util.PartialEnergySorter(threshold: float, instance_name: str = 'biasing::utility::PartialEnergySorter')

Bases: UserAction

Process particles such that all particles above the input threshold are processed first.

Parameters:

threshold (float) – Minimum energy [MeV] to process a track first

class_name: str = 'biasing::utility::PartialEnergySorter'

instance_name: str = 'biasing::utility::PartialEnergySorter'

module_name: str = 'Biasing_Utility'

threshold: float

class LDMX.Biasing.util.StepPrinter(process_name: str = '', track_id: int = 1, depth: int = 0, instance_name: str = 'biasing::utility::StepPrinter')

Bases: UserAction

Print each step of the input track ID

The default track ID is 1 (the primary particle).

Parameters:

track_id (int, optional) – Geant4 track ID to print each step of

class_name: str = 'biasing::utility::StepPrinter'

depth: int = 0

instance_name: str = 'biasing::utility::StepPrinter'

module_name: str = 'Biasing_Utility'

process_name: str = ''

track_id: int = 1

class LDMX.Biasing.util.TrackProcessFilter(process: str, instance_name: str = 'biasing::utility::TrackProcessFilter')

Bases: UserAction

Configuration used to tag all tracks produced via the given process to persist them to the event.

Parameters:

process (str) – The Geant4 process name (e.g. photonNuclear) via which the tracks were produced.

aprime_to_fcp()

Configuration used to tag all A’ –> fcp+ fcp- tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag A’ –> fcp+ fcp- tracks.

class_name: str = 'biasing::utility::TrackProcessFilter'

conversion()

Configuration used to tag all electron conversion tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag conversion tracks.

dark_brem()

Configuration used to tag all dark brem tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag dark brem tracks.

electro_nuclear()

Configuration used to tag all electro-nuclear tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag electro-nuclear tracks.

electron_brem()

Configuration used to tag all electron brem tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag eBrem tracks.

gamma_mumu()

Configuration used to tag all gamma –> mu+ mu- tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag gamma –> mu+ mu- tracks.

gamma_to_fcp()

Configuration used to tag all gamma –> fcp+ fcp- tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag gamma –> fcp+ fcp- tracks.

instance_name: str = 'biasing::utility::TrackProcessFilter'

module_name: str = 'Biasing_Utility'

photo_nuclear()

Configuration used to tag all photo-nuclear tracks to persist them to the event.

Return type:

Instance of TrackProcessFilter configured to tag photo-nuclear tracks.

process: str

LDMX.Biasing.util.biasing_utility(class_name: str)

Module contents