Overview

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

One-loop integrals

One-loop integral reduction and master-integral evaluation.

Symbolic reduction is available in the browser build. Numerical scalar master evaluation and native compilation require a native build with the corresponding backend.

Classes

DecimalComplex	A complex number with Python Decimal components
Evaluator	Reuse a numerical evaluator for one scalar one-loop master family
MasterIntegral	A scalar tadpole, bubble, triangle or box returned in Reduction.terms
Reduction	A symbolic linear combination of scalar one-loop master integrals

Functions

a0	Evaluate a scalar tadpole A0(mass_squared, mu_squared)
b0	Evaluate a scalar bubble B0(momentum_squared, mass_0_squared, mass_1_squared, mu_squared)
c0	Evaluate C0(p1_squared, p2_squared, p3_squared, mass_0_squared, mass_1_squared, mass_2_squared, mu_squared)
compile_native	Compile symbolic combinations of master coefficients for repeated evaluation
d0	Evaluate D0 with four external squared momenta, s12, s23, four squared masses, and the squared scale
db0	Evaluate the derivative of B0 with respect to its external momentum squared
get_expression	Expand a complete master call into symbolic Laurent-coefficient formulas
is_initialized	Report whether the native one-loop module has initialized its evaluation support.
master_coefficients	Return the three Laurent coefficients of a complete primitive master call
reduce	Reduce a one-loop hep.IntegralFamily to scalar master integrals
reduction_coefficients	Expand a reduction about d=4-2*eps and combine its master coefficients
select_branch	Resolve piecewise conditions using replacements, preserving symbolic branch values

a0

a0(
    mass_squared: Number,
    mu_squared: Number | None = None,
    *,
    rebuild: bool = False,
    prec: int = 16,
    backend: Backend = 'auto',
) -> Coefficients

Evaluate a scalar tadpole A0(mass_squared, mu_squared).

Results are ordered (finite, 1/eps, 1/eps**2). Invariants and masses are squared quantities; omitted mu_squared is exactly one. prec is the positive decimal significant-digit count (default 16). Decimal inputs or higher precision produce DecimalComplex values. backend selects “auto”, “native”, “symjit” (binary64 only), “expression”, or “symbolica”. rebuild=True refreshes the evaluator workspace.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
finite, pole, double_pole = oneloop.a0(1.0, 1.0)

Parameters

• mass_squared (Number) Squared mass of the tadpole propagator.
• mu_squared (Number or None, optional) Squared renormalization scale; None uses exactly one.
• rebuild (bool, optional) Refresh the evaluator workspace before evaluation; default False.
• prec (int, optional) Positive number of decimal significant digits; default 16. Use Decimal inputs to retain input digits beyond binary64 precision.
• backend ({“auto”, “native”, “symjit”, “expression”, “symbolica”}, optional) Evaluation backend; default “auto” selects a supported backend for the requested precision. “symjit” supports binary64 only; “symbolica” is an alias for “expression”.

b0

b0(
    momentum_squared: Number,
    mass_0_squared: Number,
    mass_1_squared: Number,
    mu_squared: Number | None = None,
    *,
    rebuild: bool = False,
    prec: int = 16,
    backend: Backend = 'auto',
) -> Coefficients

Evaluate a scalar bubble B0(momentum_squared, mass_0_squared, mass_1_squared, mu_squared).

Results are ordered (finite, 1/eps, 1/eps**2). Invariants and masses are squared quantities; omitted mu_squared is exactly one. prec is the positive decimal significant-digit count (default 16). Decimal inputs or higher precision produce DecimalComplex values. backend selects “auto”, “native”, “symjit” (binary64 only), “expression”, or “symbolica”. rebuild=True refreshes the evaluator workspace.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
finite, pole, double_pole = oneloop.b0(-1.0, 1.0, 1.0, 1.0)

Parameters

• momentum_squared (Number) External momentum squared; negative values describe spacelike momentum.
• mass_0_squared, mass_1_squared (Number) Squared masses of the two propagators, in B0 argument order.
• mu_squared (Number or None, optional) Squared renormalization scale; None uses exactly one.
• rebuild (bool, optional) Refresh the evaluator workspace before evaluation; default False.
• prec (int, optional) Positive number of decimal significant digits; default 16. Use Decimal inputs to retain input digits beyond binary64 precision.
• backend ({“auto”, “native”, “symjit”, “expression”, “symbolica”}, optional) Evaluation backend; default “auto” selects a supported backend for the requested precision. “symjit” supports binary64 only; “symbolica” is an alias for “expression”.

c0

c0(
    p1_squared: Number,
    p2_squared: Number,
    p3_squared: Number,
    mass_0_squared: Number,
    mass_1_squared: Number,
    mass_2_squared: Number,
    mu_squared: Number | None = None,
    *,
    rebuild: bool = False,
    prec: int = 16,
    backend: Backend = 'auto',
) -> Coefficients

Evaluate C0(p1_squared, p2_squared, p3_squared, mass_0_squared, mass_1_squared, mass_2_squared, mu_squared).

Results are ordered (finite, 1/eps, 1/eps**2). Invariants and masses are squared quantities; omitted mu_squared is exactly one. prec is the positive decimal significant-digit count (default 16). Decimal inputs or higher precision produce DecimalComplex values. backend selects “auto”, “native”, “symjit” (binary64 only), “expression”, or “symbolica”. rebuild=True refreshes the evaluator workspace.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
finite, pole, double_pole = oneloop.c0(-1.0, -2.0, -3.0, 1.0, 1.0, 1.0, 1.0)

Parameters

• p1_squared, p2_squared, p3_squared (Number) Three external momentum invariants, in C0 argument order.
• mass_0_squared, mass_1_squared, mass_2_squared (Number) Squared masses of the three propagators, in C0 argument order.
• mu_squared (Number or None, optional) Squared renormalization scale; None uses exactly one.
• rebuild (bool, optional) Refresh the evaluator workspace before evaluation; default False.
• prec (int, optional) Positive number of decimal significant digits; default 16. Use Decimal inputs to retain input digits beyond binary64 precision.
• backend ({“auto”, “native”, “symjit”, “expression”, “symbolica”}, optional) Evaluation backend; default “auto” selects a supported backend for the requested precision. “symjit” supports binary64 only; “symbolica” is an alias for “expression”.

compile_native

compile_native(
    expressions: Sequence[Expression | int | float | complex],
    parameters: Sequence[Expression],
) -> SymbolicaEvaluator

Related type: Expression

Compile symbolic combinations of master coefficients for repeated evaluation.

Returns a Symbolica evaluator retaining the primitive master definitions. Use its complex evaluation method and pass parameter values in the supplied order. This operation builds an evaluator; it does not evaluate a point.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
m2 = S("m2")
coefficients = oneloop.master_coefficients(oneloop.A0(m2, 1))
compiled = oneloop.compile_native(coefficients, [m2])
values = compiled.evaluate_complex([1+0j])

Parameters

• expressions (sequence[Expression | int | float | complex]) Outputs to compile, usually master or reduction coefficients.
• parameters (sequence[Expression]) Ordered independent symbols receiving numerical values.

d0

d0(
    p1_squared: Number,
    p2_squared: Number,
    p3_squared: Number,
    p4_squared: Number,
    s12: Number,
    s23: Number,
    mass_0_squared: Number,
    mass_1_squared: Number,
    mass_2_squared: Number,
    mass_3_squared: Number,
    mu_squared: Number | None = None,
    *,
    rebuild: bool = False,
    prec: int = 16,
    backend: Backend = 'auto',
) -> Coefficients

Evaluate D0 with four external squared momenta, s12, s23, four squared masses, and the squared scale.

Results are ordered (finite, 1/eps, 1/eps**2). Invariants and masses are squared quantities; omitted mu_squared is exactly one. prec is the positive decimal significant-digit count (default 16). Decimal inputs or higher precision produce DecimalComplex values. backend selects “auto”, “native”, “symjit” (binary64 only), “expression”, or “symbolica”. rebuild=True refreshes the evaluator workspace.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
finite, pole, double_pole = oneloop.d0(-1.0, -1.0, -1.0, -1.0, -3.0, -4.0, 1.0, 1.0, 1.0, 1.0, 1.0)

Parameters

• p1_squared, p2_squared, p3_squared, p4_squared (Number) Four external momenta squared, in D0 argument order.
• s12 (Number) Channel invariant (p1 + p2)**2.
• s23 (Number) Channel invariant (p2 + p3)**2.
• mass_0_squared, mass_1_squared, mass_2_squared, mass_3_squared (Number) Squared masses of the four propagators, in D0 argument order.
• mu_squared (Number or None, optional) Squared renormalization scale; None uses exactly one.
• rebuild (bool, optional) Refresh the evaluator workspace before evaluation; default False.
• prec (int, optional) Positive number of decimal significant digits; default 16. Use Decimal inputs to retain input digits beyond binary64 precision.
• backend ({“auto”, “native”, “symjit”, “expression”, “symbolica”}, optional) Evaluation backend; default “auto” selects a supported backend for the requested precision. “symjit” supports binary64 only; “symbolica” is an alias for “expression”.

db0

db0(
    momentum_squared: Number,
    mass_0_squared: Number,
    mass_1_squared: Number,
    mu_squared: Number | None = None,
    *,
    rebuild: bool = False,
    prec: int = 16,
    backend: Backend = 'auto',
) -> Coefficients

Evaluate the derivative of B0 with respect to its external momentum squared.

Results are ordered (finite, 1/eps, 1/eps**2). Invariants and masses are squared quantities; omitted mu_squared is exactly one. prec is the positive decimal significant-digit count (default 16). Decimal inputs or higher precision produce DecimalComplex values. backend selects “auto”, “native”, “symjit” (binary64 only), “expression”, or “symbolica”. rebuild=True refreshes the evaluator workspace.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
finite, pole, double_pole = oneloop.db0(-1.0, 1.0, 1.0, 1.0)

Parameters

• momentum_squared (Number) External momentum squared at which the derivative of B0 is evaluated.
• mass_0_squared, mass_1_squared (Number) Squared masses held fixed while differentiating B0.
• mu_squared (Number or None, optional) Squared renormalization scale; None uses exactly one.
• rebuild (bool, optional) Refresh the evaluator workspace before evaluation; default False.
• prec (int, optional) Positive number of decimal significant digits; default 16. Use Decimal inputs to retain input digits beyond binary64 precision.
• backend ({“auto”, “native”, “symjit”, “expression”, “symbolica”}, optional) Evaluation backend; default “auto” selects a supported backend for the requested precision. “symjit” supports binary64 only; “symbolica” is an alias for “expression”.

get_expression

get_expression(
    master: Expression,
    *,
    coefficient: Literal[0, -1, -2] | None = None,
    max_nodes: int = 1000000,
    max_depth: int = 512,
) -> Expression | tuple[Expression, Expression, Expression]

Related type: Expression

Expand a complete master call into symbolic Laurent-coefficient formulas.

Without coefficient return (finite, simple_pole, double_pole). With tag 0, -1 or -2 return that coefficient only. Piecewise branches remain explicit until their conditions can be decided. max_nodes and max_depth bound formula expansion and raise an error when exceeded.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
m2 = S("m2")
pole = oneloop.get_expression(oneloop.A0(m2, 1), coefficient=-1)

Parameters

• master (Expression) Untagged primitive master call with physical arguments and squared scale.
• coefficient ({0, -1, -2} or None, optional) Laurent power to select; None returns all three coefficients.
• max_nodes (int, optional) Expression expansion budget; default 1_000_000.
• max_depth (int, optional) Expansion nesting limit; default 512.

is_initialized

is_initialized() -> bool

Report whether the native one-loop module has initialized its evaluation support.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
initialized = oneloop.is_initialized()

master_coefficients

master_coefficients(master: Expression) -> list[Expression]

Related type: Expression

Return the three Laurent coefficients of a complete primitive master call.

The input includes physical arguments and squared scale, without a Laurent tag. The returned symbolic expressions carry tags 0, -1 and -2 for finite, simple-pole and double-pole coefficients and retain native evaluation hooks.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
s = S("s")
coefficients = oneloop.master_coefficients(oneloop.B0(s, 0, 0, 1))
assert len(coefficients) == 3

Parameters

• master (Expression) Complete untagged A0/B0/dB0/C0/D0 call, including squared scale.

reduce

reduce(
    family: IntegralFamily,
    powers: typing.Sequence[builtins.int],
    *,
    numerator: typing.Optional[Expression] = None,
) -> Reduction

Related types: IntegralFamily, Expression, Reduction

Reduce a one-loop hep.IntegralFamily to scalar master integrals.

powers follows the family denominator order. Negative powers contribute numerator factors and zero powers omit denominators. numerator is an additional scalar expression written using family.kinematics.scalar_product. Exactly one loop and a symbolic dimension are required. Positive powers of eikonal denominators and uncontracted loop tensors raise ValueError.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
d, k, p, s = S("d", "k", "p", "s")
kin = hep.Kinematics(d, momenta=[k, p]).with_scalar_product(p, p, s)
family = hep.IntegralFamily([k], [p], [kin.scalar_product(k, k),
    kin.scalar_product(k-p, k-p)], kinematics=kin)
reduction = oneloop.reduce(family, [1, 1])
assert reduction.to_expression() == oneloop.B0(s, 0, 0, 1)

Parameters

• family (IntegralFamily) One-loop denominator family with symbolic dimension.
• powers (sequence[int]) One signed integer per denominator.
• numerator (Expression or None, optional) Additional scalar numerator; None uses one.

reduction_coefficients

reduction_coefficients(
    reduction: Reduction,
    mu_squared: Expression | None = None,
) -> list[Expression]

Related types: Reduction, Expression

Expand a reduction about d=4-2*eps and combine its master coefficients.

Returns [finite, simple_pole, double_pole] with native evaluation hooks. Raises ValueError for coefficient poles at d=4 requiring unavailable positive-order master coefficients, fractional Taylor powers, or dimension-dependent kinematics or scale.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
d, k, p, s = S("d", "k", "p", "s")
kin = hep.Kinematics(d, momenta=[k, p]).with_scalar_product(p, p, s)
family = hep.IntegralFamily([k], [p], [kin.scalar_product(k, k),
    kin.scalar_product(k-p, k-p)], kinematics=kin)
reduction = oneloop.reduce(family, [1, 1])
coefficients = oneloop.reduction_coefficients(reduction)
assert len(coefficients) == 3

Parameters

• reduction (Reduction) Symbolic one-loop reduction with dimension dependence retained.
• mu_squared (Expression or None, optional) Squared scale; None uses one.

select_branch

select_branch(expression: _Expressions, replacement_rules: Sequence[Replacement]) -> _Expressions

Related type: Replacement

Resolve piecewise conditions using replacements, preserving symbolic branch values.

Replacements act only in conditions, not in the selected result expressions. Unresolved predicates remain symbolic. Input may be one expression or a list or tuple; the returned container has the same shape.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
from symbolica import Replacement
m2 = S("m2")
expressions = oneloop.get_expression(oneloop.A0(m2, 1))
selected = oneloop.select_branch(expressions, [Replacement(m2, E("1"))])
assert len(selected) == 3

Parameters

• expression (Expression, list[Expression] or tuple[Expression, …]) Piecewise formula or collection to inspect.
• replacement_rules (sequence[Replacement]) Kinematic assumptions used only to decide branch conditions.

Constants

A0

A0: Expression

B0

B0: Expression

C0

C0: Expression

COEFFICIENT_ORDER

COEFFICIENT_ORDER: tuple[Literal[0], Literal[-1], Literal[-2]]

D0

D0: Expression

DEFAULT_BACKEND

DEFAULT_BACKEND: str

EXPRESSION_INTEROP

EXPRESSION_INTEROP: bool

SYMBOLICA_REVISION

SYMBOLICA_REVISION: str

dB0

dB0: Expression