Neutrino Reconstruction (pyc)

Analytical single and double neutrino reconstruction kernels implemented as batched CUDA/C++ operations. This module bridges the high-level nusol C++ module (see Neutrino Solution (NuSol) Module) with the PyTorch tensor interface.

pyc::nusol Functions

Function

Description

BaseMatrix(pmc_b, pmc_mu, masses)

Computes the \(3\times3\) neutrino constraint matrix from b-quark, lepton, and mass hypothesis tensors. Returns a dict with key "H".

Nu(pmc_b, pmc_mu, met_xy, masses, sigma, null)

Single-neutrino analytical solution (ellipse intersection). Returns a dict with "nu_pmc" (Nx4), "chi2" (Nx1), and "is_valid" (Nx1).

NuNu(pmc_b1, pmc_b2, pmc_l1, pmc_l2, met_xy, masses, null, step, tol, timeout)

Double-neutrino solution assuming uniform mass hypotheses across the batch.

NuNu(…, mass1, mass2, …)

Double-neutrino solution with per-event mass hypothesis tensors.

NuNu<b,l>(bquark1, …, dev, null, step, tol, timeout)

Particle-pointer overload — accepts std::vector<particle_template*> for use in C++ selections.

nusol_ Internal Namespace

The nusol_ namespace contains the raw CUDA/CPU kernel implementations used by pyc::nusol:

  • BaseMatrix — three overloads: tensor masses, scalar masses (mT/mW), null check

  • Hperp — perpendicular H matrix

  • Intersection — ellipse intersection routine

  • Nu — single neutrino kernel

  • NuNu — double neutrino kernel (two overloads + iterative solver)

  • combinatorial — combinatorial neutrino assignment with PageRank

namespace nusol

Tensor-based neutrino reconstruction.

Functions

torch::Dict<std::string, torch::Tensor> BaseMatrix(torch::Tensor pmc_b, torch::Tensor pmc_mu, torch::Tensor masses)

Compute the H̃ and related matrices for a (b, lepton) batch.

Parameters:

  • pmc_b – [N, 4] b-quark four-momenta.

  • pmc_mu – [N, 4] lepton four-momenta.

  • masses – [N, 3] mass constraints (mT, mW, mN).

Returns:

Dict with keys "H_perp_pmc_", "N_", …

torch::Dict<std::string, torch::Tensor> Nu(torch::Tensor pmc_b, torch::Tensor pmc_mu, torch::Tensor met_xy, torch::Tensor masses, torch::Tensor sigma, double null = 10e-10)

Single-neutrino reconstruction.

Parameters:

  • pmc_b – [N, 4] b-quark four-momenta.

  • pmc_mu – [N, 4] lepton four-momenta.

  • met_xy – [N, 2] missing transverse momentum.

  • masses – [N, 3] mass constraints.

  • sigma – [N, 2, 2] MET covariance.

  • null – Tolerance for near-zero tests.

torch::Dict<std::string, torch::Tensor> NuNu(torch::Tensor pmc_b1, torch::Tensor pmc_b2, torch::Tensor pmc_l1, torch::Tensor pmc_l2, torch::Tensor met_xy, torch::Tensor masses, double null = 10e-10, const double step = 1e-9, const double tolerance = 1e-6, const unsigned int timeout = 1000)

Di-neutrino reconstruction using the iterative NuNu solver.

torch::Dict<std::string, torch::Tensor> NuNu(torch::Tensor pmc_b1, torch::Tensor pmc_b2, torch::Tensor pmc_l1, torch::Tensor pmc_l2, torch::Tensor met_xy, double null, torch::Tensor mass1, torch::Tensor mass2, const double step = 1e-9, const double tolerance = 1e-6, const unsigned int timeout = 1000)
std::vector<std::pair<neutrino*, neutrino*>> NuNu(std::vector<std::vector<double>> *pmc_b1, std::vector<std::vector<double>> *pmc_b2, std::vector<std::vector<double>> *pmc_l1, std::vector<std::vector<double>> *pmc_l2, std::vector<double> *met, std::vector<double> *phi, std::vector<std::vector<double>> *mass1, std::vector<std::vector<double>> *mass2, std::string dev, const double null, const double step, const double tolerance, const unsigned int timeout)
template<typename b, typename l>
std::vector<std::pair<neutrino*, neutrino*>> NuNu(std::vector<b*> bquark1, std::vector<b*> bquark2, std::vector<l*> lepton1, std::vector<l*> lepton2, std::vector<double> met_, std::vector<double> phi_, std::vector<std::vector<double>> mass1, std::vector<std::vector<double>> mass2, std::string dev, double null, const double step, const double tolerance, const unsigned int timeout)
torch::Dict<std::string, torch::Tensor> combinatorial(torch::Tensor edge_index, torch::Tensor batch, torch::Tensor pmc, torch::Tensor pid, torch::Tensor met_xy, double mT = 172.62 * 1000, double mW = 80.385 * 1000, double null = 1e-10, double perturb = 1e-3, long steps = 100, bool gev = false)

Combinatorial di-neutrino reconstruction over all b–lepton pairs in a batched graph.

Parameters:

  • edge_index – COO edge index.

  • batch – Node-to-graph assignment.

  • pmc – [N, 4] four-momenta.

  • pid – [N] PDG particle IDs.

  • met_xy – [B, 2] MET vectors.

  • mT – Top-quark mass constraint (MeV, default 172.62 GeV).

  • mW – W-boson mass constraint (MeV, default 80.385 GeV).

  • null – Near-zero tolerance.

  • perturb – MET perturbation magnitude.

  • steps – Maximum solver steps.

  • gev – If true, inputs/outputs are in GeV.

std::vector<std::pair<neutrino*, neutrino*>> combinatorial(std::vector<double> *met_, std::vector<double> *phi_, std::vector<std::vector<double>> *pmc, std::vector<long> *bth, std::vector<long> *is_b, std::vector<long> *is_l, std::string dev, double mT, double mW, double null, double perturb, long steps)
std::vector<std::pair<neutrino*, neutrino*>> combinatorial(std::vector<double> met_, std::vector<double> phi_, std::vector<std::vector<particle_template*>> particles, std::string dev, double mT, double mW, double null, double perturb, long steps)
namespace nusol_

Internal namespace for batched neutrino reconstruction.

Functions

std::map<std::string, torch::Tensor> BaseMatrix(torch::Tensor *pmc_b, torch::Tensor *pmc_mu, torch::Tensor *masses)

Compute the H̃ and N matrices for a batched (b, lepton) input.

Parameters:

  • pmc_b – [N, 4] b-quark Cartesian momenta.

  • pmc_mu – [N, 4] lepton Cartesian momenta.

  • masses – [N, 3] mass constraints (mT, mW, mN) in MeV.

Returns:

Map with keys including "H_perp_pmc_", "N_".

torch::Tensor BaseMatrix(torch::Tensor *pmc_b, torch::Tensor *pmc_mu, torch::Tensor *masses, bool null)

Variant that returns only the H-perp matrix (or null mask).

Parameters:

  • pmc_b – [N, 4] b-quark Cartesian momenta.

  • pmc_mu – [N, 4] lepton Cartesian momenta.

  • masses – [N, 3] mass constraints (mT, mW, mN) in MeV.

  • null – If true, return a boolean validity mask.

std::map<std::string, torch::Tensor> BaseMatrix(torch::Tensor *pmc_b, torch::Tensor *pmc_mu, double mT, double mW, double mN)

Scalar-mass overload of BaseMatrix.

torch::Tensor Hperp(torch::Tensor *pmc_b, torch::Tensor *pmc_mu, torch::Tensor *masses)

Compute the H⊥ matrix.

Returns:

[N, 3, 3].

std::tuple<torch::Tensor, torch::Tensor> Intersection(torch::Tensor *A, torch::Tensor *B, double nulls)

Compute conic intersection for a batch of (A, B) conic pairs.

Parameters:

  • A – [N, 3, 3] first conic.

  • B – [N, 3, 3] second conic.

  • nulls – Near-zero tolerance.

Returns:

(solutions [N, 4, 3], valid_mask [N]).

std::map<std::string, torch::Tensor> Nu(torch::Tensor *pmc_b, torch::Tensor *pmc_mu, torch::Tensor *met_xy, torch::Tensor *masses, torch::Tensor *sigma, double null)

Single-neutrino reconstruction.

Parameters:

  • pmc_b – [N, 4] b-quark momenta.

  • pmc_mu – [N, 4] lepton momenta.

  • met_xy – [N, 2] MET x/y.

  • masses – [N, 3] mass constraints.

  • sigma – [N, 2, 2] MET covariance.

  • null – Tolerance.

Returns:

Map with "NuX", "NuY", "NuZ", "chi2", …

std::map<std::string, torch::Tensor> NuNu(torch::Tensor *pmc_b1, torch::Tensor *pmc_b2, torch::Tensor *pmc_mu1, torch::Tensor *pmc_mu2, torch::Tensor *met_xy, double null, torch::Tensor *m1, torch::Tensor *m2 = nullptr)

Di-neutrino reconstruction (no iteration).

std::map<std::string, torch::Tensor> NuNu(torch::Tensor *pmc_b1, torch::Tensor *pmc_b2, torch::Tensor *pmc_mu1, torch::Tensor *pmc_mu2, torch::Tensor *met_xy, double null, torch::Tensor *m1, torch::Tensor *m2, const double step, const double tolerance, const unsigned int timeout)

Di-neutrino reconstruction with iterative mass-line refinement.

Parameters:

  • pmc_b1 – [N, 4] first b-quark momenta.

  • pmc_b2 – [N, 4] second b-quark momenta.

  • pmc_mu1 – [N, 4] first lepton momenta.

  • pmc_mu2 – [N, 4] second lepton momenta.

  • met_xy – [N, 2] MET x/y.

  • null – Near-zero tolerance.

  • m1 – [N, 3] mass constraints for first top.

  • m2 – [N, 3] mass constraints for second top.

  • step – Mass line step size.

  • tolerance – Convergence tolerance.

  • timeout – Maximum iterations.

std::map<std::string, torch::Tensor> combinatorial(torch::Tensor *edge_index, torch::Tensor *batch, torch::Tensor *pmc, torch::Tensor *pid, torch::Tensor *met_xy, double mT = 172.62 * 1000, double mW = 80.385 * 1000, double null = 1e-10, double perturb = 1e-3, long steps = 100, bool gev = false)

Combinatorial di-neutrino reconstruction.

Parameters:

  • edge_index – [2, E] COO.

  • batch – [N] node-to-graph assignments.

  • pmc – [N, 4] four-momenta.

  • pid – [N] PDG IDs.

  • met_xy – [B, 2] MET.

  • mT – Top mass constraint (MeV or GeV depending on gev).

  • mW – W mass constraint (MeV or GeV depending on gev).

  • null – Near-zero tolerance.

  • perturb – Mass-line perturbation size.

  • steps – Number of mass-line steps.

  • gev – If true, treat inputs/outputs as GeV.