libome-rs

Rust bindings for libome, a C++ library implementing massive operator matrix elements (OMEs) of the QCD twist-2 operators in x-space.

This crate vendors the upstream C++ source and compiles it at build time — no system-wide installation of libome is required.

License and citation

The vendored C++ source in native/libome/ is licensed under GPL-3.0-or-later (see native/libome/LICENSE). Because this crate links statically against that code, the combined work is also subject to the GPL-3.0 terms.

Citation requirements

Users of this library must comply with the citation requirements of the upstream libome project. The required references depend on which OMEs (unpolarized and/or polarized) you use. The full list is in CITATION, with BibTeX entries in CITATION.bib.

Build requirements

• A C++17-capable compiler (GCC >= 7, Clang >= 5, MSVC >= 2017)
• Rust stable (edition 2024)
• The cc crate handles compilation; no CMake needed
• Optional: GSL (libgsl-dev / gsl via Homebrew) for the mellin feature

Crate structure

native/libome/       Vendored upstream C++ source
build.rs             Compiles C++ into a static library via the cc crate
src/ffi.rs           Unsafe extern "C" declarations matching libome's C ABI
src/unpolarized/     Safe wrappers for unpolarized OMEs
src/polarized/       Safe wrappers for polarized (Delta) OMEs
src/mellin.rs        Mellin moment/convolution types (feature = "mellin")
src/gsl_shim.cpp     C++ shim bridging template-based Mellin API to C ABI

Exposed OMEs

Unpolarized (9 matrix elements):

Struct	C prefix	Parts
AqqQNSEven	ome_AqqQNSEven_	reg, plus, delta
AqqQNSOdd	ome_AqqQNSOdd_	reg, plus, delta
AggQ	ome_AggQ_	reg, plus, delta
AQqPS	ome_AQqPS_	reg
AQqPSs	ome_AQqPSs_	reg
AqqQPS	ome_AqqQPS_	reg
AqgQ	ome_AqgQ_	reg
AgqQ	ome_AgqQ_	reg
AQg	ome_AQg_	reg

Polarized variants have the same structure, prefixed with Pol (e.g. PolAqqQNSEven).

Installation

From crates.io

As a library:

[dependencies]
libome-rs = "0.0.1"

As a CLI binary:

cargo install libome-rs

With Mellin moment support:

[dependencies]
libome-rs = { version = "0.0.1", features = ["mellin"] }

cargo install libome-rs --features mellin

The mellin feature requires system GSL, for example libgsl-dev on Debian/Ubuntu or gsl via Homebrew on macOS.

From GitHub during development

As a library:

[dependencies]
libome-rs = { git = "https://github.com/t7phy/libome_rs", locked = true }

As a CLI binary:

cargo install --locked --git https://github.com/t7phy/libome_rs

With Mellin support:

[dependencies]
libome-rs = { git = "https://github.com/t7phy/libome_rs", locked = true, features = ["mellin"] }

cargo install --locked --git https://github.com/t7phy/libome_rs --features mellin

CLI usage

# Evaluate the regular part of AqqQNSEven
libome-rs eval AqqQNSEven reg 0.25 -5.0 3.0 0.1

# Evaluate the plus part
libome-rs eval AqqQNSEven plus 0.25 -5.0 3.0 0.5

# Evaluate the delta part (no x argument)
libome-rs eval AqqQNSEven delta 0.25 -5.0 3.0

# Truncated evaluation in a_s at order 2
libome-rs eval AqqQNSEven reg-trunc 2 0.25 -5.0 3.0 0.1

# Mellin moment (requires --features mellin at install time)
libome-rs moment AQqPS 2 0.25 -5.0 3.0

Library usage

use libome_rs::AqqQNSEven;

let as_ = 0.118 / (4.0 * std::f64::consts::PI); // a_s
let lm = 0.0;   // L_M = ln(m^2/mu^2)
let nf = 5.0;   // number of light flavours
let x = 0.1;    // momentum fraction

// Full evaluation
let reg = AqqQNSEven::reg(as_, lm, nf, x);

// Truncated in a_s at a given order
let trunc = AqqQNSEven::reg_trunc_as(2, as_, lm, nf, x);

// Individual coefficient
let coeff = AqqQNSEven::reg_coeff_as(2, lm, nf, x);

// Power ranges for iteration
let as_min = AqqQNSEven::reg_min_power();
let as_max = AqqQNSEven::reg_max_power();

The low-level numerical wrappers assume physically meaningful inputs, in particular 0 < x < 1 where an x-space regular or plus part is evaluated. Invalid domain inputs are passed to the upstream implementation and may produce NaN, infinities, or upstream-defined behavior.

Feature: mellin

Enable the mellin feature to get Mellin moment and convolution helpers. This links against system GSL (libgsl-dev on Debian/Ubuntu, gsl on macOS).

[dependencies]
libome-rs = { git = "https://github.com/t7phy/libome_rs", locked = true, features = ["mellin"] }

use libome_rs::{AqqQNSEven, IntegrationStatus};

let res = AqqQNSEven::mellin_moment(
    2,     // Mellin moment N
    0.25,  // a_s
    -5.0,  // L_M
    3.0,   // N_F
    0.0,   // eps_abs
    3e-11, // eps_rel
);
assert_eq!(res.status, IntegrationStatus::Success);
println!("N=2 moment: {} +/- {}", res.value, res.abs_error);

// Convolution with a user-provided test function
unsafe extern "C" fn f(x: f64) -> f64 { x }

let conv = AqqQNSEven::mellin_convolution(
    0.5,   // x
    0.25,  // a_s
    -5.0,  // L_M
    3.0,   // N_F
    f,     // test function
    0.0,   // eps_abs
    1e-6,  // eps_rel
);

Running tests

cargo test                  # base tests (no GSL required)
cargo test --features mellin   # includes Mellin moment/convolution tests