Mapping

class madspace.Mapping(self: madspace._madspace_py.Mapping, name: str, input_types: madspace._madspace_py.NamedTypes, output_types: madspace._madspace_py.NamedTypes, condition_types: madspace._madspace_py.NamedTypes)

Bases: pybind11_object

Base class for invertible phase-space mappings.

Cross-section and event-generation integrals have the form

\[I = \int_\Phi f(x)\,\mathrm{d}x,\]

with \(f(x)\) the fully differential cross section over the phase-space point \(x\) [1]. Monte-Carlo integration draws \(x\) through an invertible map \(G\) from the unit hypercube, \(r \in [0,1]^d \leftrightarrow x \in \Phi\). This induces the normalized sampling density

\[g(x) = \left| \frac{\partial G^{-1}(x)}{\partial x} \right|, \qquad \int_\Phi g(x)\,\mathrm{d}x = 1,\]

so that \(I = \int_U \left. f(x)/g(x) \right|_{x = G(r)}\,\mathrm{d}r\). The integration variance shrinks as \(g\) approaches \(f/I\).

A Mapping records one such \(G\) as a pair of compute-graph builders. build_forward maps the inputs (the unit-hypercube numbers) to the outputs (momenta and invariants). build_inverse maps the outputs back to the inputs. Both also return a weight, the Jacobian \(1/g\) of the transformation. Conditions are external quantities the mapping needs but does not transform, such as masses, the collision energy or cut boundaries. They are the same for the forward and inverse direction.

Random-number inputs are named after the variable they generate (r_phi, r_theta, r_t, r_s, …). Time-like invariants are called s_i, space-like ones t_i. Entries marked with an index i are repeated per particle. batch is the leading batch dimension of every tensor. Concrete subclasses list their Inputs, Conditions and Outputs individually.

build_forward and build_inverse each come in two overloads. One takes a NamedVector<Value>. The other takes a positional ValueVec and attaches the names from input_types() / output_types() and condition_types(). Subclasses may be written in Python by deriving from this class.

References

Parameters:

  • name – Identifier used for the generated compute graph.

  • input_types – Types of the values consumed by the forward map (produced by the inverse map).

  • output_types – Types of the values produced by the forward map (consumed by the inverse map).

  • condition_types – Types of the pass-through conditioning values.

build_forward(*args, **kwargs)

Overloaded function.

  1. build_forward(self: madspace._madspace_py.Mapping, builder: madspace._madspace_py.FunctionBuilder, inputs: collections.abc.Sequence[madspace._madspace_py.Value], conditions: collections.abc.Sequence[madspace._madspace_py.Value]) -> madspace._madspace_py.NamedValues

Add the forward map to fb and return its named outputs.

The positional overload attaches names from input_types() and condition_types().

  1. build_forward(self: madspace._madspace_py.Mapping, builder: madspace._madspace_py.FunctionBuilder, inputs: madspace._madspace_py.NamedValues, conditions: madspace._madspace_py.NamedValues) -> madspace._madspace_py.NamedValues

Add the forward map to fb and return its named outputs.

The positional overload attaches names from input_types() and condition_types().

build_inverse(*args, **kwargs)

Overloaded function.

  1. build_inverse(self: madspace._madspace_py.Mapping, builder: madspace._madspace_py.FunctionBuilder, inputs: collections.abc.Sequence[madspace._madspace_py.Value], conditions: collections.abc.Sequence[madspace._madspace_py.Value]) -> madspace._madspace_py.NamedValues

Add the inverse map to fb and return the recovered inputs.

The positional overload attaches names from output_types() and condition_types().

  1. build_inverse(self: madspace._madspace_py.Mapping, builder: madspace._madspace_py.FunctionBuilder, inputs: madspace._madspace_py.NamedValues, conditions: madspace._madspace_py.NamedValues) -> madspace._madspace_py.NamedValues

Add the inverse map to fb and return the recovered inputs.

The positional overload attaches names from output_types() and condition_types().

forward_function(self: madspace._madspace_py.Mapping) → madspace._madspace_py.Function

Build a standalone Function for the forward map.

inverse_function(self: madspace._madspace_py.Mapping) → madspace._madspace_py.Function

Build a standalone Function for the inverse map.

map_forward(inputs=[], conditions=[], **kwargs)
map_inverse(inputs=[], conditions=[], **kwargs)
release_inputs()