madminer.morphing module¶

class
madminer.morphing.
Morpher
(parameters_from_madminer=None, parameter_max_power=None, parameter_range=None)¶ 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, humanfriendly 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).
 calculate_morphing_weight_gradient() calculates the gradient of the morphing weights, grad_theta w_b(theta).
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.
Returns:  morphing_matrix : ndarray
Morphing matrix with shape (n_basis_benchmarks, n_components)

calculate_morphing_weight_gradient
(theta, basis=None, morphing_matrix=None)¶ Calculates the gradient of the morphing weights, grad_i w_b(theta).
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.
Returns:  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.
Returns:  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.
Returns:  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.
Returns:  components : ndarray
Array with shape (n_components, n_parameters), where each entry gives the power with which a parameter scales a given component.

optimize_basis
(n_bases=1, fixed_benchmarks_from_madminer=None, fixed_benchmarks_numpy=None, n_trials=100, n_test_thetas=100)¶ 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.
Returns:  basis : OrderedDict or ndarray
Optimized basis in the same format (MadMiner or numpy) as the parameters provided during instantiation.

set_basis
(basis_from_madminer=None, basis_numpy=None, morphing_matrix=None)¶ 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.
Returns:  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]].
Returns:  None

class
madminer.morphing.
NuisanceMorpher
(nuisance_parameters_from_madminer, benchmark_names, reference_benchmark)¶ 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 firstorder 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 secondorder 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 noncentral values of nuisance parameters. 
calculate_a
(benchmark_weights)¶ Calculates the firstorder 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.
Returns:  a : ndarray
Coefficients a_i(x) with shape (n_nuisance_parameters, n_events).

calculate_b
(benchmark_weights)¶ Calculates the secondorder 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.
Returns:  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 noncentral 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.
Returns:  nuisance_factors : ndarray
Nuisance factor dsigma(x  theta, nu) / dsigma(x  theta, 0) with shape (n_events,).