Evaluator

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

Evaluator

class Evaluator

Reuse a numerical evaluator for one scalar one-loop master family.

Pass a bare primitive symbol: oneloop.A0, B0, dB0, C0 or D0. Every evaluation takes physical arguments in that primitive’s order, with the squared renormalization scale last. Unlike the lowercase convenience functions, evaluate requires the scale explicitly.

Results are ordered (finite, 1/eps, 1/eps**2). prec counts decimal significant digits. Binary64 evaluation returns Python complex values; arbitrary-precision evaluation returns DecimalComplex components. Use decimal strings through Decimal to avoid rounding your inputs before evaluation. Per-call precision/backend overrides do not change the stored defaults.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
finite, pole, double_pole = evaluator.evaluate([1.0, 1.0])
assert pole == 1+0j and double_pole == 0j
rows = evaluator.evaluate_batch([[1.0, 1.0], [2.0, 1.0]])
assert len(rows) == 2

Attributes

Name Description
arity Number of physical arguments including the final squared scale.
backend Requested default backend name; “auto” remains “auto” after backend selection.
family Primitive family name, such as “A0” or “B0”.
prec Default decimal significant-digit count; per-call overrides leave it unchanged.

arity

Evaluator.arity: int

Number of physical arguments including the final squared scale.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
assert evaluator.arity == 2
assert oneloop.Evaluator(oneloop.B0).arity == 4

backend

Evaluator.backend: str

Requested default backend name; “auto” remains “auto” after backend selection.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
assert evaluator.backend == "auto"

family

Evaluator.family: str

Primitive family name, such as “A0” or “B0”.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
assert evaluator.family == "A0"

prec

Evaluator.prec: int

Default decimal significant-digit count; per-call overrides leave it unchanged.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
assert evaluator.prec == 16

Methods

Name Description
__init__ Prepare an evaluator and retain default precision and backend choices
__repr__ Summarize the selected family, precision and requested backend.
evaluate Evaluate one kinematic point and return (finite, simple pole, double pole)
evaluate_batch Evaluate a sequence of kinematic rows, returning one coefficient tuple per row
rebuild Recreate cached evaluator workspaces while preserving the configured family and defaults

__init__

Evaluator.__init__(
    family: Expression,
    rebuild: bool = False,
    *,
    prec: int = 16,
    backend: Backend = 'auto',
) -> None

Related type: Expression

Prepare an evaluator and retain default precision and backend choices.

auto selects a supported backend for the requested precision. native uses native numerical evaluation; symjit supports binary64 only. expression (also named symbolica) evaluates Symbolica formulas. Unsupported backend/precision combinations raise an error.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
assert evaluator.family == "A0" and evaluator.arity == 2

Parameters

  • family (Expression) Bare primitive symbol such as oneloop.B0, not a B0(…) call.
  • rebuild (bool, optional) Recreate the evaluator’s workspace; default False.
  • prec (int, optional) Positive number of decimal significant digits; default 16.
  • backend (str, optional) “auto”, “native”, “symjit”, “expression” or “symbolica”; default “auto”.

__repr__

Evaluator.__repr__() -> str

Summarize the selected family, precision and requested backend.

Examples

from symbolica.community.hepkit import oneloop
summary = repr(oneloop.Evaluator(oneloop.A0))

evaluate

Evaluator.evaluate(
    arguments: Sequence[Number],
    *,
    prec: int | None = None,
    backend: Backend | None = None,
) -> Coefficients

Evaluate one kinematic point and return (finite, simple pole, double pole).

Supply exactly arity numeric arguments including the squared scale. Inputs must satisfy the selected primitive’s kinematic domain. A per-call prec or backend override changes only this evaluation.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
finite, pole, double_pole = evaluator.evaluate([1.0, 1.0])
assert pole == 1+0j
from decimal import Decimal
high_precision = evaluator.evaluate([Decimal("1"), Decimal("1")], prec=40)
assert high_precision[1].real == Decimal("1")

Parameters

  • arguments (sequence[Number]) Ordered invariants, squared masses and squared scale for the primitive.
  • prec (int or None, optional) Decimal significant digits; None uses the constructor default.
  • backend (str or None, optional) Backend override; None uses the constructor default.

evaluate_batch

Evaluator.evaluate_batch(
    rows: Sequence[Sequence[Number]],
    *,
    prec: int | None = None,
    backend: Backend | None = None,
) -> list[Coefficients]

Evaluate a sequence of kinematic rows, returning one coefficient tuple per row.

All rows have arity entries and use the same precision/backend choice. An empty batch returns an empty list. No NumPy array is required.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
rows = evaluator.evaluate_batch([[1.0, 1.0], [2.0, 1.0]])
assert rows[0] == evaluator.evaluate([1.0, 1.0])
assert evaluator.evaluate_batch([]) == []

Parameters

  • rows (sequence[sequence[Number]]) Ordered physical arguments, including the squared scale, for each point.
  • prec (int or None, optional) Decimal significant digits; None uses the constructor default.
  • backend (str or None, optional) Backend override; None uses the constructor default.

rebuild

Evaluator.rebuild() -> None

Recreate cached evaluator workspaces while preserving the configured family and defaults.

Native evaluation refreshes constants/workspaces; a SymJIT evaluator is recompiled. This is usually unnecessary between evaluations at new points.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
from symbolica.community.hepkit import oneloop
evaluator = oneloop.Evaluator(oneloop.A0)
before = evaluator.evaluate([1.0, 1.0])
evaluator.rebuild()
assert evaluator.evaluate([1.0, 1.0]) == before