madminer.lhe module

class madminer.lhe.LHEProcessor(filename)[source]

Bases: object

Detector simulation with smearing functions and simple calculation of observables.

After setting up the parameter space and benchmarks and running MadGraph and Pythia, all of which is organized in the madminer.core.MadMiner class, the next steps are the simulation of detector effects and the calculation of observables. Different tools can be used for these tasks, please feel free to implement the detector simulation and analysis routine of your choice.

This class provides a simple implementation in which detector effects are modeled with smearing functions. Its workflow consists of the following steps:

  • Initializing the class with the filename of a MadMiner HDF5 file (the output of madminer.core.MadMiner.save())
  • Adding one or multiple event samples produced by MadGraph and Pythia in LHEProcessor.add_sample().
  • Running Delphes on the samples that require it through LHEProcessor.run_delphes().
  • Optionally, smearing functions for all visible particles can be defined with LHEProcessor.set_smearing().
  • Defining observables through LHEProcessor.add_observable() or LHEProcessor.add_observable_from_function(). A simple set of default observables is provided in LHEProcessor.add_default_observables()
  • Optionally, cuts can be set with LHEProcessor.add_cut()
  • Calculating the observables from the Delphes ROOT files with LHEProcessor.analyse_delphes_samples()
  • Saving the results with LHEProcessor.save()

Please see the tutorial for a detailed walk-through.

Parameters:
filename : str or None, optional

Path to MadMiner file (the output of madminer.core.MadMiner.save()). Default value: None.

Methods

add_cut(definition[, pass_if_not_parsed]) Adds a cut as a string that can be parsed by Python’s eval() function and returns a bool.
add_default_observables([n_leptons_max, …]) Adds a set of simple standard observables: the four-momenta (parameterized as E, pT, eta, phi) of the hardest visible particles, and the missing transverse energy.
add_observable(name, definition[, required, …]) Adds an observable as a string that can be parsed by Python’s eval() function.
add_observable_from_function(name, fn[, …]) Adds an observable defined through a function.
add_sample(lhe_filename, sampled_from_benchmark) Adds an LHE sample of simulated events.
analyse_samples([reference_benchmark, …]) Main function that parses the LHE samples, applies detector effects, checks cuts, and extracts the observables and weights.
reset_cuts() Resets all cuts.
reset_observables() Resets all observables.
save(filename_out) Saves the observable definitions, observable values, and event weights in a MadMiner file.
set_smearing([pdgids, …]) Sets up the smearing of measured momenta from shower and detector effects.
add_cut(definition, pass_if_not_parsed=False)[source]

Adds a cut as a string that can be parsed by Python’s eval() function and returns a bool.

Parameters:
definition : str

An expression that can be parsed by Python’s eval() function and returns a bool: True for the event to pass this cut, False for it to be rejected. In the definition, all visible particles can be used: e, mu, j, a, and l provide lists of electrons, muons, jets, photons, and leptons (electrons and muons combined), in each case sorted by descending transverse momentum. met provides a missing ET object. visible and all provide access to the sum of all visible particles and the sum of all visible particles plus MET, respectively. All these objects are instances of MadMinerParticle, which inherits from scikit-hep’s [LorentzVector](http://scikit-hep.org/api/math.html#vector-classes). See the link for a documentation of their properties. In addition, MadMinerParticle have properties charge and pdg_id, which return the charge in units of elementary charges (i.e. an electron has e[0].charge = -1.), and the PDG particle ID. For instance, “len(e) >= 2” requires at least two electrons passing the cuts, while “mu[0].charge > 0.” specifies that the hardest muon is positively charged.

pass_if_not_parsed : bool, optional

Whether the cut is passed if the observable cannot be parsed. Default value: False.

Returns:
None
add_default_observables(n_leptons_max=2, n_photons_max=2, n_jets_max=2, include_met=True, include_visible_sum=True, include_numbers=True, include_charge=True)[source]

Adds a set of simple standard observables: the four-momenta (parameterized as E, pT, eta, phi) of the hardest visible particles, and the missing transverse energy.

Parameters:
n_leptons_max : int, optional

Number of hardest leptons for which the four-momenta are saved. Default value: 2.

n_photons_max : int, optional

Number of hardest photons for which the four-momenta are saved. Default value: 2.

n_jets_max : int, optional

Number of hardest jets for which the four-momenta are saved. Default value: 2.

include_met : bool, optional

Whether the missing energy observables are stored. Default value: True.

include_visible_sum : bool, optional

Whether observables characterizing the sum of all particles are stored. Default value: True.

include_numbers : bool, optional

Whether the number of leptons, photons, and jets is saved as observable. Default value: True.

include_charge : bool, optional

Whether the lepton charge is saved as observable. Default value: True.

Returns:
None
add_observable(name, definition, required=False, default=None)[source]

Adds an observable as a string that can be parsed by Python’s eval() function.

Parameters:
name : str

Name of the observable. Since this name will be used in eval() calls for cuts, this should not contain spaces or special characters.

definition : str

An expression that can be parsed by Python’s eval() function. As objects, all particles can be used: e, mu, tau, j, a, l, v provide lists of electrons, muons, taus, jets, photons, leptons ( electrons and muons combined), and neutrinos, in each case sorted by descending transverse momentum. met provides a missing ET object. p gives all particles in the same order as in the LHE file (i.e. in the same order as defined in the MadGraph process card). All these objects are instances of MadMinerParticle, which inherits from scikit-hep’s [LorentzVector](http://scikit-hep.org/api/math.html#vector-classes). See the link for a documentation of their properties. In addition, MadMinerParticle have properties charge and pdg_id, which return the charge in units of elementary charges (i.e. an electron has e[0].charge = -1.), and the PDG particle ID. For instance, “abs(j[0].phi() - j[1].phi())” defines the azimuthal angle between the two hardest jets.

required : bool, optional

Whether the observable is required. If True, an event will only be retained if this observable is successfully parsed. For instance, any observable involving “j[1]” will only be parsed if there are at least two jets passing the acceptance cuts. Default value: False.

default : float or None, optional

If required=False, this is the placeholder value for observables that cannot be parsed. None is replaced with np.nan. Default value: None.

Returns:
None
add_observable_from_function(name, fn, required=False, default=None)[source]

Adds an observable defined through a function.

Parameters:
name : str

Name of the observable. Since this name will be used in eval() calls for cuts, this should not contain spaces or special characters.

fn : function

A function with signature observable(particles) where the input arguments are lists of MadMinerParticle instances (ordered in the same way as in the LHE file) and a float is returned. The function should raise a RuntimeError to signal that it is not defined.

required : bool, optional

Whether the observable is required. If True, an event will only be retained if this observable is successfully parsed. For instance, any observable involving “j[1]” will only be parsed if there are at least two jets passing the acceptance cuts. Default value: False.

default : float or None, optional

If required=False, this is the placeholder value for observables that cannot be parsed. None is replaced with np.nan. Default value: None.

Returns:
None
add_sample(lhe_filename, sampled_from_benchmark, is_background=False, k_factor=1.0)[source]

Adds an LHE sample of simulated events.

Parameters:
lhe_filename : str

Path to the LHE event file (with extension ‘.lhe’ or ‘.lhe.gz’).

sampled_from_benchmark : str

Name of the benchmark that was used for sampling in this event file (the keyword sample_benchmark of madminer.core.MadMiner.run()).

is_background : bool, optional

Whether the sample is a background sample (i.e. without benchmark reweighting).

k_factor : float, optional

Multiplies the cross sections found in the sample. Default value: 1.

Returns:
None
analyse_samples(reference_benchmark=None, parse_events_as_xml=True)[source]

Main function that parses the LHE samples, applies detector effects, checks cuts, and extracts the observables and weights.

Parameters:
reference_benchmark : str or None, optional

The weights at the nuisance benchmarks will be rescaled to some reference theta benchmark: dsigma(x|theta_sampling(x),nu) -> dsigma(x|theta_ref,nu) = dsigma(x|theta_sampling(x),nu) * dsigma(x|theta_ref,0) / dsigma(x|theta_sampling(x),0). This sets the name of the reference benchmark. If None, the first one will be used. Default value: None.

parse_events_as_xml : bool, optional

Decides whether the LHE events are parsed with an XML parser (more robust, but slower) or a text parser (less robust, faster). Default value: True.

Returns:
None
reset_cuts()[source]

Resets all cuts.

reset_observables()[source]

Resets all observables.

save(filename_out)[source]

Saves the observable definitions, observable values, and event weights in a MadMiner file. The parameter, benchmark, and morphing setup is copied from the file provided during initialization. Nuisance benchmarks found in the LHE file are added.

Parameters:
filename_out : str

Path to where the results should be saved.

Returns:
None
set_smearing(pdgids=None, energy_resolution_abs=0.0, energy_resolution_rel=0.0, pt_resolution_abs=0.0, pt_resolution_rel=0.0, eta_resolution_abs=0.0, eta_resolution_rel=0.0, phi_resolution_abs=0.0, phi_resolution_rel=0.0)[source]

Sets up the smearing of measured momenta from shower and detector effects.

This function can be called with pdgids=None, in which case the settinigs are used for all visible particles, or with pdgids set to a list of PDG ids representing particles, for instance [11, -11] for electrons (and positrons).

For all particles of this type, and for the energy, pT, phi, and eta, the measurement error is drawn from a Gaussian with mean 0 and standard deviation given by (X_resolution_abs + X * X_resolution_rel). Here X is the quantity (E, pT, phi, eta) of interest and X_resolution_abs and X_resolution_rel are the corresponding keywords. In the case of energy and pT, values smaller than 0 will lead to a re-drawing of the measurement error.

Instead of such numerical values, either the energy or pT resolution (but not both!) may be set to None. In this case, this quantity is calculated from the mass of the particle and all other smeared particles. For instance, when pt_resolution_abs is None or pt_resolution_rel is None, for the given particles the energy, phi, and eta are smeared (according to their respective resolutions). Then the transverse momentum is calculated from the on-shell condition p^2 = m^2, or pT = sqrt(E^2 - m^2) / cosh(eta). When this does not have a solution, the pT is set to zero. On the other hand, when energy_resolution_abs is None or energy_resolution_abs is None, for the given particles the pT, phi, and eta are smeared, and then the energy is calculated as E = sqrt(pT * cosh(eta))^2 + m^2).

Parameters:
pdgids : None or list of int, optional

Defines the particles these smearing functions affect. If None, all particles are affected. Note that if set_smearing() is called multiple times for a given particle, the earlier calls will be forgotten and only the last smearing function will take effect. Default value: None.

energy_resolution_abs : float or None, optional

Absolute measurement uncertainty for the energy in GeV. None means that the energy is not smeared directly, but calculated from the on-shell condition. Default value: 0.

energy_resolution_rel : float or None, optional

Relative measurement uncertainty for the energy. None means that the energy is not smeared directly, but calculated from the on-shell condition. Default value: 0.

pt_resolution_abs : float or None, optional

Absolute measurement uncertainty for the pT in GeV. None means that the pT is not smeared directly, but calculated from the on-shell condition. Default value: 0.

pt_resolution_rel : float or None, optional

Relative measurement uncertainty for the pT. None means that the pT is not smeared directly, but calculated from the on-shell condition. Default value: 0.

eta_resolution_abs : float, optional

Absolute measurement uncertainty for eta. Default value: 0.

eta_resolution_rel : float, optional

Relative measurement uncertainty for eta. Default value: 0.

phi_resolution_abs : float, optional

Absolute measurement uncertainty for phi. Default value: 0.

phi_resolution_rel : float, optional

Relative measurement uncertainty for phi. Default value: 0.

Returns:
None