madminer.core module

class madminer.core.MadMiner[source]

Bases: object

The central class to manage parameter spaces, benchmarks, and the generation of events through MadGraph and Pythia.

An instance of this class is the starting point of most MadMiner applications. It is typically used in four steps:

  • Defining the parameter space through MadMiner.add_parameter
  • Defining the benchmarks, i.e. the points at which the squared matrix elements will be evaluated in MadGraph, with MadMiner.add_benchmark() or, if operator morphing is used, with MadMiner.set_benchmarks_from_morphing()
  • Saving this setup with MadMiner.save() (it can be loaded in a new instance with MadMiner.load())
  • Running MadGraph and Pythia with the appropriate settings with MadMiner.run() or MadMiner.run_multiple() (the latter allows the user to combine runs from multiple run cards and sampling points)

Please see the tutorial for a hands-on introduction to its methods.

Methods

add_benchmark(parameter_values[, …]) Manually adds an individual benchmark, that is, a parameter point that will be evaluated by MadGraph.
add_parameter(lha_block, lha_id[, …]) Adds an individual parameter.
load(filename[, disable_morphing]) Loads MadMiner setup from a file.
run(mg_directory, proc_card_file, …[, …]) High-level function that creates the the MadGraph process, all required cards, and prepares or runs the event generation for one combination of cards.
run_multiple(mg_directory, proc_card_file, …) High-level function that creates the the MadGraph process, all required cards, and prepares or runs the event generation for multiple combinations of run_cards or importance samplings (sample_benchmarks).
save(filename) Saves MadMiner setup into a file.
set_benchmarks([benchmarks, verbose]) Manually sets all benchmarks, that is, parameter points that will be evaluated by MadGraph.
set_morphing([max_overall_power, n_bases, …]) Sets up the morphing environment.
set_parameters([parameters]) Manually sets all parameters, overwriting previously added parameters.
set_systematics([scale_variation, scales, …]) Prepares the simulation of the effect of different nuisance parameters, including scale variations and PDF changes.
add_benchmark(parameter_values, benchmark_name=None, verbose=True)[source]

Manually adds an individual benchmark, that is, a parameter point that will be evaluated by MadGraph.

If this command is called before

Parameters:
parameter_values : dict

The keys of this dict should be the parameter names and the values the corresponding parameter values.

benchmark_name : str or None, optional

Name of benchmark. If None, a default name is used. Default value: None.

verbose : bool, optional

If True, prints output about each benchmark. Default value: True.

Returns:
None
Raises:
RuntimeError

If a benchmark with the same name already exists, if parameter_values is not a dict, or if a key of parameter_values does not correspond to a defined parameter.

add_parameter(lha_block, lha_id, parameter_name=None, param_card_transform=None, morphing_max_power=2, parameter_range=(0.0, 1.0))[source]

Adds an individual parameter.

Parameters:
lha_block : str

The name of the LHA block as used in the param_card. Case-sensitive.

lha_id : int

The LHA id as used in the param_card.

parameter_name : str or None

An internal name for the parameter. If None, a the default ‘benchmark_i’ is used.

morphing_max_power : int or tuple of int

The maximal power with which this parameter contributes to the squared matrix element of the process of interest. If a tuple is given, gives this maximal power for each of several operator configurations. Typically at tree level, this maximal number is 2 for parameters that affect one vertex (e.g. only production or only decay of a particle), and 4 for parameters that affect two vertices (e.g. production and decay). Default value: 2.

param_card_transform : None or str

Represents a one-parameter function mapping the parameter (“theta”) to the value that should be written in the parameter cards. This str is parsed by Python’s eval() function, and “theta” is parsed as the parameter value. Default value: None.

parameter_range : tuple of float

The range of parameter values of primary interest. Only affects the basis optimization. Default value: (0., 1.).

Returns:
None
load(filename, disable_morphing=False)[source]

Loads MadMiner setup from a file. All parameters, benchmarks, and morphing settings are overwritten. See save for more details.

Parameters:
filename : str

Path to the MadMiner file.

disable_morphing : bool, optional

If True, the morphing setup is not loaded from the file. Default value: False.

Returns:
None
run(mg_directory, proc_card_file, param_card_template_file, run_card_file=None, mg_process_directory=None, pythia8_card_file=None, sample_benchmark=None, is_background=False, only_prepare_script=False, ufo_model_directory=None, log_directory=None, temp_directory=None, initial_command=None, python2_override=False)[source]

High-level function that creates the the MadGraph process, all required cards, and prepares or runs the event generation for one combination of cards.

If only_prepare_scripts=True, the event generation is not run directly, but a bash script is created in <process_folder>/madminer/run.sh that will start the event generation with the correct settings.

High-level function that creates the the MadGraph process, all required cards, and prepares or runs the event generation for multiple combinations of run_cards or importance samplings (sample_benchmarks).

If only_prepare_scripts=True, the event generation is not run directly, but a bash script is created in <process_folder>/madminer/run.sh that will start the event generation with the correct settings.

Parameters:
mg_directory : str

Path to the MadGraph 5 base directory.

proc_card_file : str

Path to the process card that tells MadGraph how to generate the process.

param_card_template_file : str

Path to a param card that will be used as template to create the appropriate param cards for these runs.

run_card_file : str

Paths to the MadGraph run card. If None, the default run_card is used.

mg_process_directory : str or None, optional

Path to the MG process directory. If None, MadMiner uses ./MG_process. Default value: None.

pythia8_card_file : str or None, optional

Path to the MadGraph Pythia8 card. If None, the card present in the process folder is used. Default value: None.

sample_benchmark : list of str or None, optional

Lists the names of benchmarks that should be used to sample events. A different sampling does not change the expected differential cross sections, but will change which regions of phase space have many events (small variance) or few events (high variance). If None, the benchmark added first is used. Default value: None.

is_background : bool, optional

Should be True for background processes, i.e. process in which the differential cross section does not depend on the parameters (i.e. is the same for all benchmarks). In this case, no reweighting is run, which can substantially speed up the event generation. Default value: False.

only_prepare_script : bool, optional

If True, the event generation is not started, but instead a run.sh script is created in the process directory. Default value: False.

only_prepare_script : bool, optional

If True, MadGraph is not executed, but instead a run.sh script is created in the process directory. Default value: False.

ufo_model_directory : str or None, optional

Path to an UFO model directory that should be used, but is not yet installed in mg_directory/models. The model will be copied to the MadGraph model directory before the process directory is generated. (Default value = None.

log_directory : str or None, optional

Directory for log files with the MadGraph output. If None, ./logs is used. Default value: None.

temp_directory : str or None, optional

Path to a temporary directory. If None, a system default is used. Default value: None.

initial_command : str or None, optional

Initial shell commands that have to be executed before MG is run (e.g. to load a virtual environment). Default value: None.

python2_override : bool, optional

If True, MadMiner explicitly calls “python2” instead of relying on the system Python version to be Python 2.6 or Python 2.7. If you use systematics, make sure that the python interface of LHAPDF was compiled with the Python version you are using. Default: False.

Returns:
None
run_multiple(mg_directory, proc_card_file, param_card_template_file, run_card_files, mg_process_directory=None, pythia8_card_file=None, sample_benchmarks=None, is_background=False, only_prepare_script=False, ufo_model_directory=None, log_directory=None, temp_directory=None, initial_command=None, python2_override=False)[source]

High-level function that creates the the MadGraph process, all required cards, and prepares or runs the event generation for multiple combinations of run_cards or importance samplings (sample_benchmarks).

If only_prepare_scripts=True, the event generation is not run directly, but a bash script is created in <process_folder>/madminer/run.sh that will start the event generation with the correct settings.

Parameters:
mg_directory : str

Path to the MadGraph 5 base directory.

proc_card_file : str

Path to the process card that tells MadGraph how to generate the process.

param_card_template_file : str

Path to a param card that will be used as template to create the appropriate param cards for these runs.

run_card_files : list of str

Paths to the MadGraph run card.

mg_process_directory : str or None, optional

Path to the MG process directory. If None, MadMiner uses ./MG_process. Default value: None.

pythia8_card_file : str, optional

Path to the MadGraph Pythia8 card. If None, the card present in the process folder is used. Default value: None.

sample_benchmarks : list of str or None, optional

Lists the names of benchmarks that should be used to sample events. A different sampling does not change the expected differential cross sections, but will change which regions of phase space have many events (small variance) or few events (high variance). If None, a run is started for each of the benchmarks, which should map out all regions of phase space well. Default value: None.

is_background : bool, optional

Should be True for background processes, i.e. process in which the differential cross section does not depend on the parameters (i.e. is the same for all benchmarks). In this case, no reweighting is run, which can substantially speed up the event generation. Default value: False.

only_prepare_script : bool, optional

If True, the event generation is not started, but instead a run.sh script is created in the process directory. Default value: False.

only_prepare_script : bool, optional

If True, MadGraph is not executed, but instead a run.sh script is created in the process directory. Default value: False.

ufo_model_directory : str or None, optional

Path to an UFO model directory that should be used, but is not yet installed in mg_directory/models. The model will be copied to the MadGraph model directory before the process directory is generated. (Default value = None)

log_directory : str or None, optional

Directory for log files with the MadGraph output. If None, ./logs is used. Default value: None.

temp_directory : str or None, optional

Path to a temporary directory. If None, a system default is used. Default value: None.

initial_command : str or None, optional

Initial shell commands that have to be executed before MG is run (e.g. to load a virtual environment). Default value: None.

python2_override : bool, optional

If True, MadMiner explicitly calls “python2” instead of relying on the system Python version to be Python 2.6 or Python 2.7. If you use systematics, make sure that the python interface of LHAPDF was compiled with the Python version you are using. Default: False.

Returns:
None
save(filename)[source]

Saves MadMiner setup into a file.

The file format follows the HDF5 standard. The saved information includes:

  • the parameter definitions,
  • the benchmark points,
  • the systematics setup (if defined), and
  • the morphing setup (if defined).

This file is an important input to later stages in the analysis chain, including the processing of generated events, extraction of training samples, and calculation of Fisher information matrices. In these downstream tasks, additional information will be written to the MadMiner file, including the observations and event weights.

Parameters:
filename : str

Path to the MadMiner file.

Returns:
None
set_benchmarks(benchmarks=None, verbose=True)[source]

Manually sets all benchmarks, that is, parameter points that will be evaluated by MadGraph. Calling this function overwrites all previously defined benchmarks.

Parameters:
benchmarks : dict or list or None, optional

Specifies all benchmarks. If None, all benchmarks are reset. If dict, the keys are the benchmark names and the values are dicts of the form {parameter_name:value}. If list, the entries are dicts {parameter_name:value} (and the benchmark names are chosen automatically). Default value: None.

verbose : bool, optional

If True, prints output about each benchmark. Default value: True.

Returns:
None
set_morphing(max_overall_power=4, n_bases=1, include_existing_benchmarks=True, n_trials=100, n_test_thetas=100)[source]

Sets up the morphing environment.

Sets benchmarks, i.e. parameter points that will be evaluated by MadGraph, for a morphing algorithm, and calculates all information required for morphing. Morphing is a technique that allows MadMax to infer the full probability distribution p(x_i | theta) for each simulated event x_i and any theta, not just the benchmarks.

The morphing basis is optimized with respect to the expected mean squared morphing weights over the parameter region of interest. If keep_existing_benchmarks=True, benchmarks defined previously will be incorporated in the morphing basis and only the remaining basis points will be optimized.

Note that any subsequent call to set_benchmarks or add_benchmark will overwrite the morphing setup. The correct order is therefore to manually define benchmarks first, using set_benchmarks or add_benchmark, and then to create the morphing setup and complete the basis by calling set_benchmarks_from_morphing(keep_existing_benchmarks=True).

Parameters:
max_overall_power : int or tuple of int, optional

The maximal sum of powers of all parameters contributing to the squared matrix element. If a tuple is given, gives the maximal sum of powers for each of several operator configurations (see add_parameter). Typically, if parameters can affect the couplings at n vertices, this number is 2n. Default value: 4.

n_bases : int, optional

The number of morphing bases generated. If n_bases > 1, multiple bases are combined, and the weights for each basis are reduced by a factor 1 / n_bases. Currently only the default choice of 1 is fully implemented. Do not use any other value for now. Default value: 1.

include_existing_benchmarks : bool, optional

If True, the previously defined benchmarks are included in the morphing basis. In that case, the number of free parameters in the optimization routine is reduced. If False, the existing benchmarks will still be simulated, but are not part of the morphing routine. Default value: True.

n_trials : int, optional

Number of random basis configurations tested in the optimization procedure. A larger number will increase the run time of the optimization, but lead to better results. Default value: 100.

n_test_thetas : int, optional

Number of random parameter points used to evaluate the expected mean squared morphing weights. A larger number will increase the run time of the optimization, but lead to better results. Default value: 100.

Returns:
None
set_parameters(parameters=None)[source]

Manually sets all parameters, overwriting previously added parameters.

Parameters:
parameters : dict or list or None, optional

If parameters is None, resets parameters. If parameters is an dict, the keys should be str and give the parameter names, and the values are tuples of the form (LHA_block, LHA_ID, morphing_max_power, param_min, param_max) or of the form (LHA_block, LHA_ID). If parameters is a list, the items should be tuples of the form (LHA_block, LHA_ID). Default value: None.

Returns:
None
set_systematics(scale_variation=None, scales='together', pdf_variation=None)[source]

Prepares the simulation of the effect of different nuisance parameters, including scale variations and PDF changes.

Parameters:
scale_variation : None or tuple of float, optional

If not None, the regularization and / or factorization scales are varied. A tuple like (0.5,1.,2.) specifies the factors with which they are varied. Default value: None.

scales : {“together”, “independent”, “mur”, “muf”}, optional

Whether only the regularization scale (“mur”), only the factorization scale (“muf”), both simultanously (“together”) or both independently (“independent”) are varied. Default value: “together”.

pdf_variation : None or str, optional

If not None, the PDFs are varied. The option is passed along to the –pdf option of MadGraph’s systematics module. See https://cp3.irmp.ucl.ac.be/projects/madgraph/wiki/Systematics for a list. The option “CT10” would, as an example, run over all the eigenvectors of the CTEQ10 set.

Returns:
None