Flow

class Flow : public madspace::Mapping

Normalizing-flow adaptive-sampling mapping.

A coupling-based normalizing flow built from rational-quadratic spline transformations, whose bin positions are predicted by MLP subnetworks [1, 2]. It reparametrizes the unit hypercube into a learned sampling distribution and is trained with MadNIS [3]. The subnetwork weights are compute-graph globals named after prefix; call initialize_globals(context) once before use.

batch is the leading batch dimension.

Inputs

• latent – float, shape (batch, input_dim) – uniform coordinates in [0, 1).

Conditions

• c – float, shape (batch, condition_dim) – conditioning input. Present only when condition_dim is nonzero.

Outputs

• data – float, shape (batch, input_dim) – the transformed coordinates.

In addition every mapping returns a weight (float, shape (batch,)), the Jacobian of the transformation.

References

• [1] T. Heimel, O. Mattelaer, R. Winterhalder, “MadSpace”, https://arxiv.org/abs/2602.06895 (Sec. 3.2.2)

• [2] C. Durkan et al., “Neural spline flows”, https://arxiv.org/abs/1906.04032

• [3] T. Heimel et al., “MadNIS - Neural multi-channel importance sampling”, https://arxiv.org/abs/2212.06172

Public Functions

Flow(std::size_t input_dim, std::size_t condition_dim = 0, const std::string &prefix = "", std::size_t bin_count = 10, std::size_t subnet_hidden_dim = 32, std::size_t subnet_layers = 3, MLP::Activation subnet_activation = MLP::leaky_relu, bool invert_spline = true)

Parameters:

• input_dim – Number of dimensions to transform.

• condition_dim – Width of the conditioning input; 0 for an unconditional flow.

• prefix – Prefix for the trainable global names.

• bin_count – Number of spline bins per dimension.

• subnet_hidden_dim – Hidden width of the MLP subnetworks.

• subnet_layers – Number of layers in the subnetworks.

• subnet_activation – Activation of the subnetworks.

• invert_spline – Whether the spline is applied in the inverse direction.

inline std::size_t input_dim() const

Number of transformed dimensions.

inline std::size_t condition_dim() const

Width of the conditioning input.

void initialize_globals(ContextPtr context, std::optional<std::uint64_t> seed = std::nullopt) const

Register the flow’s trainable parameters on context.

Parameters:

• context – Context receiving the globals.

• seed – Seed for the random initialization. If unset (the default), the initialization is non-deterministic.

void initialize_from_vegas(ContextPtr context, const std::string &grid_name, std::optional<std::uint64_t> seed = std::nullopt) const

Initialize the flow to reproduce a trained VEGAS grid.

Parameters:

• context – Context receiving the globals.

• grid_name – Global name of the VEGAS grid to copy.

• seed – Seed for the random initialization of the remaining parameters. If unset (the default), that initialization is non-deterministic.