MatrixElement

class MatrixElement : public madspace::FunctionGenerator

Calls a matrix element through the UMAMI interface.

UMAMI (Unified MAtrix eleMent Interface) is madspace’s uniform way of calling matrix-element code — currently the cudacpp plugin — for both integration and event generation [1] (Sec. 3.3 of [2]). Which quantities are passed and returned is chosen by inputs and outputs, given as integer keys so the interface can be extended without breaking binary compatibility.

batch is the leading batch dimension.

Arguments (a subset, selected by inputs)

  • momenta – float, shape (batch, particle_count, 4).

  • alpha_s – float, shape (batch,).

  • flavor, helicity, diagram, channel – int, shape (batch,).

  • random_color, random_helicity, random_diagram – float, shape (batch,) (omitted when sample_random_inputs draws them internally).

Returns (a subset, selected by outputs)

  • matrix_element – float, shape (batch,) – the squared matrix element.

  • diagram_amp2 – float, shape (batch, diagram_count) – per-diagram squared amplitudes.

  • color_index, helicity_index, diagram_index – int, shape (batch,) – the sampled color, helicity and diagram.

References

Public Types

enum MatrixElementInput

A quantity the matrix element can be asked to consume.

Values:

enumerator momenta_in

Final-state momenta.

enumerator alpha_s_in

Strong coupling.

enumerator flavor_in

Flavour assignment.

enumerator random_color_in

Random number for the color draw.

enumerator random_helicity_in

Random number for the helicity draw.

enumerator random_diagram_in

Random number for the diagram draw.

enumerator helicity_in

Fixed helicity.

enumerator channel_in

Multi-channel index.

enumerator diagram_in

Fixed diagram.

enumerator particle_count_in

Number of external particles (custom functions).

enumerator pdg_ids_in

PDG ids of the external particles.

enumerator momentum_fraction_in

Momentum fraction of an incoming parton.

enumerator scale_in

Energy scale, e.g. the factorization scale.

enumerator pdg_id_in

PDG id of a single parton.

enumerator beam_index_in

Index of the beam (0 or 1).

enum MatrixElementOutput

A quantity the matrix element can be asked to produce.

Values:

enumerator matrix_element_out

Squared matrix element.

enumerator diagram_amp2_out

Per-diagram squared amplitudes.

enumerator color_index_out

Sampled color.

enumerator helicity_index_out

Sampled helicity.

enumerator diagram_index_out

Sampled diagram.

enumerator cut_out

Custom cut value, 0 rejects the event.

enumerator ren_scale_out

Custom renormalization scale.

enumerator fact_scale1_out

Custom factorization scale, first incoming.

enumerator fact_scale2_out

Custom factorization scale, second incoming.

enumerator pdf_out

Custom parton density x f(x, Q).

enumerator bias_out

Custom event bias.

Public Functions

MatrixElement(std::size_t matrix_element_index, std::size_t particle_count, const std::vector<MatrixElementInput> &inputs = {momenta_in}, const std::vector<MatrixElementOutput> &outputs = {matrix_element_out}, std::size_t diagram_count = 1, bool sample_random_inputs = false, const std::vector<me_int_t> &me_frame = {}, std::size_t incoming_count = 2)
Parameters:

  • matrix_element_index – Index of the matrix element in the plugin.

  • particle_count – Number of external particles.

  • inputs – Quantities to pass in (default: just momenta_in; required in Python).

  • outputs – Quantities to return (default: just matrix_element_out; required in Python).

  • diagram_count – Number of Feynman diagrams.

  • sample_random_inputs – If true, the random_* inputs are drawn internally instead of being passed in.

  • me_frame – One-based indices of the external particles whose momentum sum defines the rest frame the matrix element is evaluated in (the run card’s me_frame). Empty means no boost, so the matrix element sees the momenta in the frame they are generated in.

  • incoming_count – How many of the external particles are incoming. The frame is reached the way madevent reaches it, starting from the rest frame of the incoming system (the partonic centre of mass of a collision, the decaying particle’s rest frame of a decay): boosts do not commute, so going there straight from the lab frame would leave a Wigner rotation behind and rotate the polarisation axes.

inline MatrixElement(const MatrixElementApi &matrix_element_api, const std::vector<MatrixElementInput> &inputs = {momenta_in}, const std::vector<MatrixElementOutput> &outputs = {matrix_element_out}, bool sample_random_inputs = false, const std::vector<me_int_t> &me_frame = {}, std::size_t incoming_count = 2)

Take matrix_element_index, particle_count and diagram_count from an already-loaded matrix element.

Parameters:

  • matrix_element_api – The loaded matrix element.

  • inputs – Quantities to pass in.

  • outputs – Quantities to return.

  • sample_random_inputs – See the other constructor.

inline std::size_t matrix_element_index() const

Index of the matrix element in the plugin.

inline std::size_t diagram_count() const

Number of Feynman diagrams.

inline std::size_t particle_count() const

Number of external particles.

inline const std::vector<MatrixElementInput> &inputs() const

The configured input quantities.

inline const std::vector<MatrixElementOutput> &outputs() const

The configured output quantities.

std::vector<MatrixElementInput> external_inputs() const

The inputs that must be supplied by the caller (excludes the ones drawn internally when sample_random_inputs is set).

inline const std::vector<me_int_t> &frame_mask() const

Per-particle 0/1 selector built from me_frame, empty if no boost is applied.

inline const std::vector<me_int_t> &reference_mask() const

Per-particle 0/1 selector of the incoming particles, whose rest frame the me_frame boost starts from; empty when no boost is applied or when it is already the frame me_frame asks for.