libome_rs/lib.rs
1//! # libome-rs
2//!
3//! Rust bindings for [libome](https://gitlab.com/libome/libome/), a C++ library
4//! implementing massive operator matrix elements (OMEs) of the QCD twist-2
5//! operators in x-space.
6//!
7//! ## What are OMEs?
8//!
9//! Operator matrix elements describe the transition between partonic states in
10//! quantum chromodynamics (QCD). They appear in the variable flavour number
11//! scheme (VFNS) for deep-inelastic scattering and are essential for matching
12//! parton distribution functions (PDFs) across heavy-quark thresholds.
13//!
14//! Each OME is a function of:
15//! - **`as_`** — the strong coupling constant `a_s(μ) = α_s(μ) / (4π)`
16//! - **`lm`** — the mass logarithm `L_M = ln(m² / μ²)`
17//! - **`nf`** — the number of massless quark flavours
18//! - **`x`** — the momentum fraction (Bjorken-x)
19//!
20//! ## Distribution structure
21//!
22//! OMEs are distributions in `x` with up to three parts:
23//!
24//! - **Regular** (`reg`) — a smooth function of `x`, present for all OMEs.
25//! - **Plus** (`plus`) — a plus-distribution `[f(x)]₊` proportional to
26//! `log^k(1-x) / (1-x)`, present only for
27//! [`AqqQNSEven`], [`AqqQNSOdd`], [`AggQ`] and their polarized variants.
28//! - **Delta** (`delta`) — a `δ(1-x)` contribution (independent of `x`),
29//! present alongside `plus`.
30//!
31//! ## Available OMEs
32//!
33//! ### Unpolarized
34//!
35//! | Struct | Physics notation | Parts |
36//! |---|---|---|
37//! | [`AqqQNSEven`] | A_{qq,Q}^{NS,+} | reg, plus, delta |
38//! | [`AqqQNSOdd`] | A_{qq,Q}^{NS,−} | reg, plus, delta |
39//! | [`AggQ`] | A_{gg,Q} | reg, plus, delta |
40//! | [`AQqPS`] | A_{Qq}^{PS} | reg |
41//! | [`AQqPSs`] | A_{Qq}^{PS,s} | reg |
42//! | [`AqqQPS`] | A_{qq,Q}^{PS} | reg |
43//! | [`AqgQ`] | A_{qg,Q} | reg |
44//! | [`AgqQ`] | A_{gq,Q} | reg |
45//! | [`AQg`] | A_{Qg} | reg |
46//!
47//! ### Polarized
48//!
49//! The polarized variants carry a `Pol` prefix and correspond to the
50//! ΔA matrix elements: [`PolAqqQNSEven`], [`PolAqqQNSOdd`], [`PolAggQ`],
51//! [`PolAQqPS`], [`PolAQqPSs`], [`PolAqqQPS`], [`PolAqgQ`], [`PolAgqQ`],
52//! [`PolAQg`].
53//!
54//! ## Quick start
55//!
56//! ```
57//! use libome_rs::AqqQNSEven;
58//!
59//! let as_ = 0.118 / (4.0 * std::f64::consts::PI); // a_s
60//! let lm = 0.0; // L_M = ln(m²/μ²)
61//! let nf = 5.0; // number of light flavours
62//! let x = 0.1; // momentum fraction
63//!
64//! // Full evaluation of the regular part
65//! let reg = AqqQNSEven::reg(as_, lm, nf, x);
66//!
67//! // Truncated in a_s at order 2
68//! let trunc = AqqQNSEven::reg_trunc_as(2, as_, lm, nf, x);
69//!
70//! // Individual a_s coefficient
71//! let coeff = AqqQNSEven::reg_coeff_as(2, lm, nf, x);
72//!
73//! // Plus and delta parts (only for RPD OMEs)
74//! let plus = AqqQNSEven::plus(as_, lm, nf, x);
75//! let delta = AqqQNSEven::delta(as_, lm, nf);
76//! ```
77//!
78//! ## Iterating over coefficients
79//!
80//! Each part exposes power-range getters for systematic iteration:
81//!
82//! ```
83//! use libome_rs::AggQ;
84//!
85//! for order_as in AggQ::reg_min_power()..=AggQ::reg_max_power() {
86//! for order_lm in AggQ::reg_coeff_as_min_power(order_as)
87//! ..=AggQ::reg_coeff_as_max_power(order_as) {
88//! for order_nf in AggQ::reg_coeff_as_lm_min_power(order_as, order_lm)
89//! ..=AggQ::reg_coeff_as_lm_max_power(order_as, order_lm) {
90//! let c = AggQ::reg_coeff_as_lm_nf(order_as, order_lm, order_nf, 0.5);
91//! // use coefficient c
92//! }
93//! }
94//! }
95//! ```
96//!
97//! ## Feature: `mellin`
98//!
99//! Enable the `mellin` feature to compute Mellin moments and convolutions via
100//! numerical integration (requires system GSL at build time).
101//!
102//! ```toml
103//! [dependencies]
104//! libome-rs = { git = "https://github.com/t7phy/libome_rs", locked = true, features = ["mellin"] }
105//! ```
106//!
107//! ```ignore
108//! use libome_rs::{AQqPS, IntegrationStatus};
109//!
110//! let res = AQqPS::mellin_moment(2, 0.25, -5.0, 3.0, 0.0, 3e-11);
111//! assert_eq!(res.status, IntegrationStatus::Success);
112//! println!("N=2 moment: {} ± {}", res.value, res.abs_error);
113//! ```
114//!
115//! ## Citation
116//!
117//! Users of this library must comply with the citation requirements of the
118//! upstream libome project. See `CITATION` and `CITATION.bib` in the
119//! repository root for the full list of required references.
120
121pub mod ffi;
122
123#[cfg(feature = "mellin")]
124#[macro_use]
125pub mod mellin;
126
127#[macro_use]
128mod macros;
129
130pub mod polarized;
131pub mod unpolarized;
132
133pub use polarized::{
134 PolAQg, PolAQqPS, PolAQqPSs, PolAggQ, PolAgqQ, PolAqgQ, PolAqqQNSEven, PolAqqQNSOdd, PolAqqQPS,
135};
136pub use unpolarized::{AQg, AQqPS, AQqPSs, AggQ, AgqQ, AqgQ, AqqQNSEven, AqqQNSOdd, AqqQPS};
137
138#[cfg(feature = "mellin")]
139pub use mellin::{IntegrationResult, IntegrationStatus};