CffRepresentation

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

CffRepresentation

class CffRepresentation

A loop-energy integral in the cross-free family (CFF) representation.

Create with diagram.integrate_energy(method="cff"). The result groups acyclic energy-flow orientations into cross-free families of denominators. With :math:E_e=\sqrt{\boldsymbol{q}_e^2+m_e^2}, its scalar expression is

\[ I_{\mathrm{CFF}}=\left(\prod_e\frac{-1}{2E_e}\right) \sum_o\sum_{F\in\mathcal{F}_o}\prod_{s\in F}\frac{1}{s}. \]

Repeated surfaces appear with their multiplicity. Family and orientation expressions include their energy prefactors, so they sum to the result. The measure is :math:d\ell^0/(2\pi i) per loop, with contours closed below, as in LtdRepresentation. The scalar formula above applies without a numerator. Supply numerator=... to integrate_energy to generate bounded polynomial energy numerators, including quadratic and higher powers. Each generalized family retains its own coefficient, numerator evaluation map and denominator powers. Couplings, graph weights and the spatial measure remain separate.

Both representations use gammalooprs::OSE(e) for :math:E_e and gammalooprs::Q(e, spenso::cind(0)) for external energies; e is a physical diagram edge ID. on_shell_energies supplies the routed square roots. Impose external momentum conservation when comparing CFF and LTD.

Displaying the object opens the orientation, family and surface explorer in Marimo or an HTML notebook. len(result) counts denominator products.

Examples

from symbolica.community import hepkit as hep
process = hep.Model.phi3().process(["phi"], ["phi", "phi"])
diagrams = process.generate_diagrams(
    loops=1, max_vertices=3, maximum_bridges=0, progress=None
)
diagram = diagrams.diagrams[0]
result = diagram.integrate_energy(method="cff")
expression = result.to_expression()
assert result.report.acyclic_orientations == len(result.orientations)

Attributes

Name Description
diagram Originating diagram or selected subgraph, retaining its routing and owner.
energy_degree_bounds Inferred polynomial energy-degree bounds keyed by physical internal edge ID
numerator Numerator supplied to energy integration; one for scalar generation.
on_shell_energies Shared symbolic energies and routed square roots, keyed by physical edge ID.
orientations Return the acyclic energy-flow orientations in this result.
report Return generation statistics for this CFF result.
surfaces Return all unique energy and H surfaces in this result.

diagram

CffRepresentation.diagram: FeynmanDiagram

Originating diagram or selected subgraph, retaining its routing and owner.

Examples

routing = result.diagram.loop_momentum_basis

energy_degree_bounds

CffRepresentation.energy_degree_bounds: builtins.dict[builtins.int, builtins.int]

Inferred polynomial energy-degree bounds keyed by physical internal edge ID.

Omitted edges have degree zero. Bounds are computed before applying routing.

Examples

bounds = result.energy_degree_bounds

numerator

CffRepresentation.numerator: Expression

Numerator supplied to energy integration; one for scalar generation.

Examples

numerator = result.numerator

on_shell_energies

CffRepresentation.on_shell_energies: builtins.dict[builtins.int, OnShellEnergy]

Shared symbolic energies and routed square roots, keyed by physical edge ID.

Examples

definitions = [(e.symbol, e.to_expression()) for e in result.on_shell_energies.values()]

orientations

CffRepresentation.orientations: builtins.list[CffOrientation]

Return the acyclic energy-flow orientations in this result.

Examples

Using the setup in the CffRepresentation class example:

products = [item.to_expression() for item in result.orientations]

report

CffRepresentation.report: CffReport

Return generation statistics for this CFF result.

Examples

Using the setup in the CffRepresentation class example:

assert result.report.acyclic_orientations == len(result.orientations)

surfaces

CffRepresentation.surfaces: builtins.list[EnergySurface]

Return all unique energy and H surfaces in this result.

Examples

Using the setup in the CffRepresentation class example:

energies = [surface.to_expression() for surface in result.surfaces]

Methods

Name Description
__len__ Return the number of unfolded denominator terms.
__repr__ Return a concise summary of the CFF expression and its surfaces.
_display_ Return Marimo’s interactive presentation in a script-enabled iframe
_repr_html_ Explore orientations, factored families and surface regions on the native graph
_repr_pretty_ Write a summary with Symbolica’s native expression formatting.
pole_coefficients Return coefficients of each inverse surface power, indexed from order one
raised_surface_groups Group equivalent energy surfaces after identifying raised propagator edges
residue Evaluate all pole-order contributions to a residue in an explicit variable
to_expression Return the scalar loop-energy integral as a Symbolica expression

__len__

CffRepresentation.__len__() -> builtins.int

Return the number of unfolded denominator terms.

Examples

Using the setup in the CffRepresentation class example:

denominator_term_count = len(result)

__repr__

CffRepresentation.__repr__() -> builtins.str

Return a concise summary of the CFF expression and its surfaces.

Examples

Using the setup in the CffRepresentation class example:

print(result)

_display_

CffRepresentation._display_() -> typing.Any

Return Marimo’s interactive presentation in a script-enabled iframe.

Marimo uses this hook automatically when displaying the result. Other notebook frontends use _repr_html_ without requiring Marimo.

Examples

Using the setup in the CffRepresentation class example:

presentation = result._display_()

_repr_html_

CffRepresentation._repr_html_() -> builtins.str

Explore orientations, factored families and surface regions on the native graph.

Arrowhead clicks select another retained orientation; they never change the result. Shift-click surface factors to inspect several circlings together. The displayed expression includes any supplied numerator and excludes the spatial measure.

Examples

Using the setup in the CffRepresentation class example:

from IPython.display import display
display(result)

_repr_pretty_

CffRepresentation._repr_pretty_(pretty: typing.Any, cycle: builtins.bool) -> None

Write a summary with Symbolica’s native expression formatting.

Examples

Using the setup in the CffRepresentation class example:

from IPython.lib.pretty import pretty
text = pretty(result)

Parameters

  • pretty (object) The IPython pretty-printer object.
  • cycle (bool) Whether this object is part of a recursive formatting cycle.

pole_coefficients

CffRepresentation.pole_coefficients(group: CffSurfaceGroup) -> builtins.list[CffRepresentation]

Related type: CffSurfaceGroup

Return coefficients of each inverse surface power, indexed from order one. These are pole coefficients, before analytic residue derivatives.

Examples

Using the setup in the CffRepresentation class example:

coefficients = result.pole_coefficients(result.raised_surface_groups()[0])
[coefficient.to_expression() for coefficient in coefficients]

Parameters

  • group (CffSurfaceGroup) A raised-surface group belonging to this result.

raised_surface_groups

CffRepresentation.raised_surface_groups(edge_representatives: typing.Optional[typing.Mapping[builtins.int, builtins.int]] = None) -> builtins.list[CffSurfaceGroup]

Related type: CffSurfaceGroup

Group equivalent energy surfaces after identifying raised propagator edges. edge_representatives maps repeated edges to their canonical edge.

Examples

Using the setup in the CffRepresentation class example:

groups = result.raised_surface_groups({3: 2})
[group.max_order for group in groups]

Parameters

  • edge_representatives (dict[int, int], optional) Repeated propagator edge IDs mapped to their canonical representative.

residue

CffRepresentation.residue(
    group: CffSurfaceGroup,
    *,
    variable: Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal],
    root: Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal],
    surface: Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal],
    coefficient: Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal],
    replacements: typing.Optional[typing.Sequence[tuple[Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal], Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal]]]] = None,
) -> TensorExpression

Related types: CffSurfaceGroup, Expression, Float, ComplexFloat, TensorExpression

Evaluate all pole-order contributions to a residue in an explicit variable. surface must be the group’s energy surface expressed in that variable; coefficient is the complete remaining coefficient, including any factors whose derivatives must act. The supplied root is assumed to be a simple zero.

Examples

Using the setup in CffRepresentation, illustrate a simple pole locally parameterized by surface=t with constant remaining coefficient:

from symbolica import E, S
t = S("t")
group = result.raised_surface_groups()[0]
residue = result.residue(group, variable=t, root=E("0"), surface=t, coefficient=E("1"))

Parameters

  • group (CffSurfaceGroup) A raised-surface group belonging to this result.
  • variable (Expression) Independent integration variable.
  • root (Expression) Simple zero of the surface, independent of variable.
  • surface (Expression) Energy surface expressed in the integration variable.
  • coefficient (Expression) Complete remaining coefficient to differentiate.
  • replacements (list[tuple[Expression, Expression]], optional) Route all energy dependence to the integration variable before differentiating.

to_expression

CffRepresentation.to_expression(*, expand_surfaces: builtins.bool = True) -> TensorExpression

Related type: TensorExpression

Return the scalar loop-energy integral as a Symbolica expression.

Includes contour signs and on-shell energy factors for :math:d\ell^0/(2\pi i) per loop, with contours closed below. A supplied numerator is included; couplings, graph weights and the spatial measure are separate. expand_surfaces expands affine denominators while leaving gammalooprs::OSE(e) symbolic. Use on_shell_energies for their routed definitions or custom evaluation.

Examples

Using the setup in the class example:

expression = result.to_expression()
compact = result.to_expression(expand_surfaces=False)

Parameters

  • expand_surfaces (bool, optional) Replace surface placeholders by their affine energy definitions. Defaults to True. False keeps placeholders local to this representation.

Returns

  • TensorExpression Rank-zero tensor summing all orientation contributions and prefactors.