Mapping

class Mapping

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

Subclassed by madspace::ChiliMapping, madspace::ColorOrderedMapping, madspace::DiscreteFlow, madspace::DiscreteSampler, madspace::DoubleT, madspace::FastRamboMapping, madspace::Flow, madspace::Invariant, madspace::Luminosity, madspace::MultiChannelMapping, madspace::PhaseSpaceMapping, madspace::TPropagatorMapping, madspace::ThreeBodyDecay, madspace::TwoBodyDecay, madspace::TwoToThreeParticleScattering, madspace::TwoToTwoParticleScattering, madspace::VegasMapping

Public Types

using Result = std::tuple<NamedVector<Value>, Value>

Forward result: the transformed values together with the Jacobian weight.

Public Functions

inline Mapping(const std::string &name, const NamedVector<Type> &input_types, const NamedVector<Type> &output_types, const NamedVector<Type> &condition_types)
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.

virtual ~Mapping() = default
NamedVector<Value> build_forward(FunctionBuilder &fb, const NamedVector<Value> &inputs, const NamedVector<Value> &conditions = {}) const

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

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

inline NamedVector<Value> build_forward(FunctionBuilder &fb, const ValueVec &inputs, const ValueVec &conditions = {}) const

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

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

inline NamedVector<Value> build_inverse(FunctionBuilder &fb, const ValueVec &inputs, const ValueVec &conditions = {}) const

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

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

NamedVector<Value> build_inverse(FunctionBuilder &fb, const NamedVector<Value> &inputs, const NamedVector<Value> &conditions = {}) const

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

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

Function forward_function() const

Build a standalone Function for the forward map.

Function inverse_function() const

Build a standalone Function for the inverse map.

inline const NamedVector<Type> &input_types() const

Types of the forward inputs / inverse outputs.

inline const NamedVector<Type> &output_types() const

Types of the forward outputs / inverse inputs.

inline const NamedVector<Type> &condition_types() const

Types of the pass-through conditions.

inline const std::string &name() const

Compute-graph identifier passed to the constructor.

inline virtual std::size_t discrete_dim() const

Number of inputs that are discrete (integer) choices rather than continuous unit-hypercube coordinates.