MatrixElement

class madspace.MatrixElement(*args, **kwargs)

Bases: 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

Overloaded function.

  1. __init__(self: madspace._madspace_py.MatrixElement, matrix_element_index: typing.SupportsInt, particle_count: typing.SupportsInt, inputs: collections.abc.Sequence[madspace._madspace_py.MatrixElement.MatrixElementInput], outputs: collections.abc.Sequence[madspace._madspace_py.MatrixElement.MatrixElementOutput], diagram_count: typing.SupportsInt = 1, sample_random_inputs: bool = False, me_frame: collections.abc.Sequence[typing.SupportsInt] = [], incoming_count: typing.SupportsInt = 2) -> None

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.

  1. __init__(self: madspace._madspace_py.MatrixElement, matrix_element_api: madspace._madspace_py.MatrixElementApi, inputs: collections.abc.Sequence[madspace._madspace_py.MatrixElement.MatrixElementInput], outputs: collections.abc.Sequence[madspace._madspace_py.MatrixElement.MatrixElementOutput], sample_random_inputs: bool = False, me_frame: collections.abc.Sequence[typing.SupportsInt] = [], incoming_count: typing.SupportsInt = 2) -> None

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.

class MatrixElementInput(*args, **kwargs)

Bases: pybind11_object

Members:

momenta_in

alpha_s_in

flavor_in

random_color_in

random_helicity_in

random_diagram_in

helicity_in

diagram_in

channel_in

particle_count_in

pdg_ids_in

momentum_fraction_in

scale_in

pdg_id_in

beam_index_in

Overloaded function.

  1. __init__(self: madspace._madspace_py.MatrixElement.MatrixElementInput, value: typing.SupportsInt) -> None

  2. __init__(self: madspace._madspace_py.MatrixElement.MatrixElementInput, name: str) -> None

alpha_s_in = <MatrixElementInput.alpha_s_in: 1>
beam_index_in = <MatrixElementInput.beam_index_in: 14>
channel_in = <MatrixElementInput.channel_in: 7>
diagram_in = <MatrixElementInput.diagram_in: 8>
flavor_in = <MatrixElementInput.flavor_in: 2>
helicity_in = <MatrixElementInput.helicity_in: 6>
momenta_in = <MatrixElementInput.momenta_in: 0>
momentum_fraction_in = <MatrixElementInput.momentum_fraction_in: 11>
MatrixElement.MatrixElementInput.name -> str
particle_count_in = <MatrixElementInput.particle_count_in: 9>
pdg_id_in = <MatrixElementInput.pdg_id_in: 13>
pdg_ids_in = <MatrixElementInput.pdg_ids_in: 10>
random_color_in = <MatrixElementInput.random_color_in: 3>
random_diagram_in = <MatrixElementInput.random_diagram_in: 5>
random_helicity_in = <MatrixElementInput.random_helicity_in: 4>
scale_in = <MatrixElementInput.scale_in: 12>
property value
class MatrixElementOutput(*args, **kwargs)

Bases: pybind11_object

Members:

matrix_element_out

diagram_amp2_out

color_index_out

helicity_index_out

diagram_index_out

cut_out

ren_scale_out

fact_scale1_out

fact_scale2_out

pdf_out

bias_out

Overloaded function.

  1. __init__(self: madspace._madspace_py.MatrixElement.MatrixElementOutput, value: typing.SupportsInt) -> None

  2. __init__(self: madspace._madspace_py.MatrixElement.MatrixElementOutput, name: str) -> None

bias_out = <MatrixElementOutput.bias_out: 10>
color_index_out = <MatrixElementOutput.color_index_out: 2>
cut_out = <MatrixElementOutput.cut_out: 5>
diagram_amp2_out = <MatrixElementOutput.diagram_amp2_out: 1>
diagram_index_out = <MatrixElementOutput.diagram_index_out: 4>
fact_scale1_out = <MatrixElementOutput.fact_scale1_out: 7>
fact_scale2_out = <MatrixElementOutput.fact_scale2_out: 8>
helicity_index_out = <MatrixElementOutput.helicity_index_out: 3>
matrix_element_out = <MatrixElementOutput.matrix_element_out: 0>
MatrixElement.MatrixElementOutput.name -> str
pdf_out = <MatrixElementOutput.pdf_out: 9>
ren_scale_out = <MatrixElementOutput.ren_scale_out: 6>
property value
alpha_s_in = <MatrixElementInput.alpha_s_in: 1>
beam_index_in = <MatrixElementInput.beam_index_in: 14>
bias_out = <MatrixElementOutput.bias_out: 10>
channel_in = <MatrixElementInput.channel_in: 7>
color_index_out = <MatrixElementOutput.color_index_out: 2>
cut_out = <MatrixElementOutput.cut_out: 5>
diagram_amp2_out = <MatrixElementOutput.diagram_amp2_out: 1>
diagram_count(self: madspace._madspace_py.MatrixElement) → int

Number of Feynman diagrams.

diagram_in = <MatrixElementInput.diagram_in: 8>
diagram_index_out = <MatrixElementOutput.diagram_index_out: 4>
external_inputs(self: madspace._madspace_py.MatrixElement) → list[madspace._madspace_py.MatrixElement.MatrixElementInput]

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

fact_scale1_out = <MatrixElementOutput.fact_scale1_out: 7>
fact_scale2_out = <MatrixElementOutput.fact_scale2_out: 8>
flavor_in = <MatrixElementInput.flavor_in: 2>
frame_mask(self: madspace._madspace_py.MatrixElement) → list[int]

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

helicity_in = <MatrixElementInput.helicity_in: 6>
helicity_index_out = <MatrixElementOutput.helicity_index_out: 3>
inputs(self: madspace._madspace_py.MatrixElement) → list[madspace._madspace_py.MatrixElement.MatrixElementInput]

The configured input quantities.

matrix_element_index(self: madspace._madspace_py.MatrixElement) → int

Index of the matrix element in the plugin.

matrix_element_out = <MatrixElementOutput.matrix_element_out: 0>
momenta_in = <MatrixElementInput.momenta_in: 0>
momentum_fraction_in = <MatrixElementInput.momentum_fraction_in: 11>
outputs(self: madspace._madspace_py.MatrixElement) → list[madspace._madspace_py.MatrixElement.MatrixElementOutput]

The configured output quantities.

particle_count(self: madspace._madspace_py.MatrixElement) → int

Number of external particles.

particle_count_in = <MatrixElementInput.particle_count_in: 9>
pdf_out = <MatrixElementOutput.pdf_out: 9>
pdg_id_in = <MatrixElementInput.pdg_id_in: 13>
pdg_ids_in = <MatrixElementInput.pdg_ids_in: 10>
random_color_in = <MatrixElementInput.random_color_in: 3>
random_diagram_in = <MatrixElementInput.random_diagram_in: 5>
random_helicity_in = <MatrixElementInput.random_helicity_in: 4>
reference_mask(self: madspace._madspace_py.MatrixElement) → list[int]

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.

ren_scale_out = <MatrixElementOutput.ren_scale_out: 6>
scale_in = <MatrixElementInput.scale_in: 12>