Bases: object

Morphing functionality for theory parameters. 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.

For a typical MadMiner application, it is not necessary to use the morphing classes directly. The other MadMiner classes use the morphing functions “under the hood” when needed. Only for an isolated study of the morphing setup (e.g. to optimize the morphing basis), the Morpher class itself may be of interest.

A typical morphing basis setup involves the following steps:

• The instance of the class is initialized with the parameter setup. The user can provide the parameters either in the format of MadMiner.parameters. Alternatively, human-friendly lists of the key properties can be provided.
• The function find_components can be used to find the relevant components, i.e. individual terms contributing to the squared matrix elements (alternatively they can be defined by the user with set_components()).
• The final step is the definition of the morphing basis, i.e. the benchmark points for which the squared matrix element will be evaluated before interpolating to other parameter points. Again the user can pick this basis manually with set_basis(). Alternatively, this class provides a basic optimization routine for the basis choice in optimize_basis().

The class also provides helper functions that are important for working with morphing:

• calculate_morphing_matrix() calculates the morphing matrix, i.e. the matrix that links the morphing basis to the
components.
• calculate_morphing_weights() calculates the morphing weights w_b(theta) for a given parameter point theta such that p(theta) = sum_b w_b(theta) p(theta_b).

Note that this class only implements the “theory morphing” (or, more specifically, “EFT morphing”) of the physics parameters of interest. Nuisance parameter morphing is implemented in the NuisanceMorpher class.

Parameters: parameters_from_madminer : OrderedDict or None, optional Parameters in the MadMiner.parameters convention. OrderedDict with keys equal to the parameter names and values equal to tuples (LHA_block, LHA_ID, morphing_max_power, param_min, param_max) parameter_max_power : None or list of int or list of tuple of int, optional Only used if parameters_from_madminer is None. Maximal power with which each parameter contributes to the squared matrix element. If tuples are 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). parameter_range : None or list of tuple of float, optional Only used if parameters_from_madminer is None. Parameter range (param_min, param_max) for each parameter.

Methods

 calculate_morphing_matrix([basis]) Calculates the morphing matrix that links the components to the basis benchmarks. calculate_morphing_weight_gradient(theta[, …]) Calculates the gradient of the morphing weights, grad_i w_b(theta). calculate_morphing_weights(theta[, basis, …]) Calculates the morphing weights w_b(theta) for a given morphing basis {theta_b}. evaluate_morphing([basis, morphing_matrix, …]) Evaluates the expected sum of the squared morphing weights for a given basis. find_components([max_overall_power]) Finds the components, i.e. optimize_basis([n_bases, …]) Optimizes the morphing basis. set_basis([basis_from_madminer, …]) Manually sets the basis benchmarks. set_components(components) Manually defines the components, i.e.
calculate_morphing_matrix(basis=None)

Calculates the morphing matrix that links the components to the basis benchmarks.

Parameters: basis : ndarray or None, optional Manually specified morphing basis for which the morphing matrix is calculated. This array has shape (n_basis_benchmarks, n_parameters). If None, the basis from the last call of set_basis() or find_basis() is used. Default value: None. morphing_matrix : ndarray Morphing matrix with shape (n_basis_benchmarks, n_components)

Parameters: theta : ndarray Parameter point theta with shape (n_parameters,). basis : ndarray or None, optional Manually specified morphing basis for which the weights are calculated. This array has shape (n_basis_benchmarks, n_parameters). If None, the basis from the last call of set_basis() or find_basis() is used. Default value: None. morphing_matrix : ndarray or None, optional Manually specified morphing matrix for the given morphing basis. This array has shape (n_basis_benchmarks, n_components). If None, the morphing matrix is calculated automatically. Default value: None. morphing_weight_gradients : ndarray Morphing weights as an array with shape (n_parameters, n_basis_benchmarks,), where the first component refers to the gradient direction.
calculate_morphing_weights(theta, basis=None, morphing_matrix=None)

Calculates the morphing weights w_b(theta) for a given morphing basis {theta_b}.

Parameters: theta : ndarray Parameter point theta with shape (n_parameters,). basis : ndarray or None, optional Manually specified morphing basis for which the weights are calculated. This array has shape (n_basis_benchmarks, n_parameters). If None, the basis from the last call of set_basis() or find_basis() is used. Default value: None. morphing_matrix : ndarray or None, optional Manually specified morphing matrix for the given morphing basis. This array has shape (n_basis_benchmarks, n_components). If None, the morphing matrix is calculated automatically. Default value: None. morphing_weights : ndarray Morphing weights as an array with shape (n_basis_benchmarks,).
evaluate_morphing(basis=None, morphing_matrix=None, n_test_thetas=100, return_weights_and_thetas=False)

Evaluates the expected sum of the squared morphing weights for a given basis.

Parameters: basis : ndarray or None, optional Manually specified morphing basis for which the weights are calculated. This array has shape (n_basis_benchmarks, n_parameters). If None, the basis from the last call of set_basis() or find_basis() is used. Default value: None. morphing_matrix : ndarray or None, optional Manually specified morphing matrix for the given morphing basis. This array has shape (n_basis_benchmarks, n_components). If None, the morphing matrix is calculated automatically. Default value: None. 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. return_weights_and_thetas : bool, optional If True, results for each evaluation theta are returned, rather than taking their average. Default value: False. thetas_test : ndarray Random parameter points used for evaluation. Only returned if return_weights_and_thetas=True is used. squared_weights : ndarray Squared summed morphing weights at each evaluation parameter point. Only returned if return_weights_and_thetas=True is used. negative_expected_sum_squared_weights : float Negative expected sum of the square of the morphing weights. Objective function in the optimization. Only returned with return_weights_and_thetas=False.
find_components(max_overall_power=4)

Finds the components, i.e. the individual terms contributing to the squared matrix element.

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 constructor). Typically, if parameters can affect the couplings at n vertices, this number is 2n. Default value: 4. components : ndarray Array with shape (n_components, n_parameters), where each entry gives the power with which a parameter scales a given component.

Optimizes the morphing basis. If either fixed_benchmarks_from_maxminer or fixed_benchmarks_numpy are not None, then these will be used as fixed basis points and only the remaining part of the basis will be optimized.

Parameters: 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. fixed_benchmarks_from_madminer : OrderedDict or None, optional Input basis vectors in the MadMiner.benchmarks conventions. Default value: None. fixed_benchmarks_numpy : ndarray or None, optional Input basis vectors as a ndarray with shape (n_fixed_basis_points, n_parameters). Default value: None. 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. basis : OrderedDict or ndarray Optimized basis in the same format (MadMiner or numpy) as the parameters provided during instantiation.

Manually sets the basis benchmarks.

Parameters: basis_from_madminer : OrderedDict or None, optional Basis in the MadMiner.benchmarks conventions. Default value: None. basis_numpy : ndarray or None, optional Only used if basis_from_madminer is None. Basis as a ndarray with shape (n_components, n_parameters). morphing_matrix : ndarray or None, optional Manually provided morphing matrix. If None, the morphing matrix is calculated automatically. Default value: None. None
set_components(components)

Manually defines the components, i.e. the individual terms contributing to the squared matrix element.

Parameters: components : ndarray Array with shape (n_components, n_parameters), where each entry gives the power with which a parameter scales a given component. For instance, a typical signal, interference, background situation with one parameter might be described by the components [[2], [1], [0]]. None

Bases: object

Morphing functionality for nuisance parameters.

For a typical MadMiner application, it is not necessary to use the morphing classes directly. The other MadMiner classes use the morphing functions “under the hood” when needed.

Parameters: nuisance_parameters_from_madminer : OrderedDict Nuisance parameters defined in the form {name: (benchmark_name_pos, benchmark_name_neg)}. Here benchmark_name_pos refers to the name of the benchmark with nu_i = 1, while benchmark_name_neg is either None or refers to the name of the benchmark with nu_i = -1. benchmark_names : list The names of the benchmarks. reference_benchmark : str Name of the reference benchmark.

Methods

 calculate_a(benchmark_weights) Calculates the first-order coefficients a_i(x) in dsigma(x | theta, nu) / dsigma(x | theta, 0) = exp[ sum_i (a_i(x) nu_i + b_i(x) nu_i(x)^2 )]. calculate_b(benchmark_weights) Calculates the second-order coefficients b_i(x) in dsigma(x | theta, nu) / dsigma(x | theta, 0) = exp[ sum_i (a_i(x) nu_i + b_i(x) nu_i(x)^2 )]. calculate_nuisance_factors(…) Calculates the rescaling of the event weights from non-central values of nuisance parameters.
calculate_a(benchmark_weights)

Calculates the first-order coefficients a_i(x) in dsigma(x | theta, nu) / dsigma(x | theta, 0) = exp[ sum_i (a_i(x) nu_i + b_i(x) nu_i(x)^2 )].

Parameters: benchmark_weights : ndarray Event weights dsigma(x | theta_i, nu_i) with shape (n_events, n_benchmarks). The benchmarks are expected to be sorted in the same order as the keyword benchmark_names used during initialization, and the nuisance benchmarks are expected to be rescaled to have the same physics parameters theta as the reference_benchmark given during initialization. a : ndarray Coefficients a_i(x) with shape (n_nuisance_parameters, n_events).
calculate_b(benchmark_weights)

Calculates the second-order coefficients b_i(x) in dsigma(x | theta, nu) / dsigma(x | theta, 0) = exp[ sum_i (a_i(x) nu_i + b_i(x) nu_i(x)^2 )].

Parameters: benchmark_weights : ndarray Event weights dsigma(x | theta_i, nu_i) with shape (n_events, n_benchmarks). The benchmarks are expected to be sorted in the same order as the keyword benchmark_names used during initialization, and the nuisance benchmarks are expected to be rescaled to have the same physics parameters theta as the reference_benchmark given during initialization. b : ndarray Coefficients b_i(x) with shape (n_nuisance_parameters, n_events).
calculate_nuisance_factors(nuisance_parameters, benchmark_weights)

Calculates the rescaling of the event weights from non-central values of nuisance parameters.

Parameters: nuisance_parameters : ndarray Values of the nuisance parameters nu, with shape (n_nuisance_parameters,). benchmark_weights : ndarray Event weights dsigma(x | theta_i, nu_i) with shape (n_events, n_benchmarks). The benchmarks are expected to be sorted in the same order as the keyword benchmark_names used during initialization, and the nuisance benchmarks are expected to be rescaled to have the same physics parameters theta as the reference_benchmark given during initialization. nuisance_factors : ndarray Nuisance factor dsigma(x | theta, nu) / dsigma(x | theta, 0) with shape (n_events,).