CffResult

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

CffResult

class CffResult

The Cross-Free Family representation of a Feynman diagram.

A result bundles the energy-flow orientations, their denominator surfaces, generation statistics, and conversion to a native Symbolica expression.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
model = hep.Model.phi4()
process = model.process(["phi", "phi"], ["phi", "phi"])
result = process.generate_diagrams(loops=1)
diagram = result.diagrams[0]
result = diagram.build_cff()
expression = result.to_expression()
assert result.report.acyclic_orientations == len(result.orientations)

Attributes

Name Description
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.

orientations

CffResult.orientations: builtins.list[CffOrientation]

Return the acyclic energy-flow orientations in this result.

Examples

Using the setup in the CffResult class example:

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

report

CffResult.report: CffReport

Return generation statistics for this CFF result.

Examples

Using the setup in the CffResult class example:

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

surfaces

CffResult.surfaces: builtins.list[CffSurface]

Return all unique energy and H surfaces in this result.

Examples

Using the setup in the CffResult class example:

energies = [result.surface_expression(surface) 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.
_repr_html_ Render the CFF report and its native Symbolica expression as HTML
_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
surface_expression Expand one surface belonging to this result into canonical energy symbols.
to_expression Convert to the canonical eta/H denominator expression

__len__

CffResult.__len__() -> builtins.int

Return the number of unfolded denominator terms.

Examples

Using the setup in the CffResult class example:

denominator_term_count = len(result)

__repr__

CffResult.__repr__() -> builtins.str

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

Examples

Using the setup in the CffResult class example:

print(result)

_repr_html_

CffResult._repr_html_() -> builtins.str

Render the CFF report and its native Symbolica expression as HTML.

The expression fragment comes from Expression._repr_html_ so its Symbolica formatting is preserved in notebook output.

Examples

Using the setup in the CffResult class example:

from IPython.display import display
display(result)

_repr_pretty_

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

Write a summary with Symbolica’s native expression formatting.

Examples

Using the setup in the CffResult 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

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

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 CffResult 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

CffResult.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 CffResult 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

CffResult.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],
    normalized: builtins.bool = False,
    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,
) -> Expression

Related types: CffSurfaceGroup, Expression, Float, ComplexFloat

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 CffResult, illustrate a simple pole locally parameterized by surface=t with constant remaining coefficient:

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.
  • normalized (bool) Include the generated CFF normalization in the coefficient.
  • replacements (list[tuple[Expression, Expression]], optional) Route all energy dependence to the integration variable before differentiating. 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 CffResult, illustrate a simple pole locally parameterized by surface=t with constant remaining coefficient:

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.
  • normalized (bool) Include the generated CFF normalization in the coefficient.
  • replacements (list[tuple[Expression, Expression]], optional) Route all energy dependence to the integration variable before differentiating.

surface_expression

CffResult.surface_expression(surface: CffSurface) -> Expression

Related types: CffSurface, Expression

Expand one surface belonging to this result into canonical energy symbols.

Examples

Using the setup in the CffResult class example:

result.surface_expression(result.surfaces[0])

Parameters

  • surface (CffSurface) A surface obtained from this result.

to_expression

CffResult.to_expression(
    *,
    expand_surfaces: builtins.bool = False,
    normalized: builtins.bool = False,
) -> Expression

Related type: Expression

Convert to the canonical eta/H denominator expression.

expand_surfaces substitutes on-shell/external energies. normalized additionally includes the -1/(2 E) factors and GammaLoop loop measure; it implies expand_surfaces. Numerators and global weights stay separate.

Examples

Using the setup in the CffResult class example:

result.to_expression(normalized=True)

Parameters

  • expand_surfaces (bool) Substitute canonical on-shell and external energies.
  • normalized (bool) Include the energy products and spatial loop measure.