LtdRepresentation

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

`LtdRepresentation`

class LtdRepresentation

A scalar loop-energy integral in the loop-tree duality (LTD) representation.

Create with diagram.integrate_energy(method="ltd"). Each residue puts edges complementary to a spanning tree on shell at :math:q_e^0=\sigma_e E_e, where :math:\sigma_e\in\{-1,+1\} and :math:E_e=\sqrt{\boldsymbol{q}_e^2+m_e^2}. The ordered loop-momentum basis and successive contours determine the retained pole assignments and coefficients. A spanning tree alone does not determine the signs.

to_expression() sums the residues, including signed coefficients and on-shell factors. The measure is :math:d\ell^0/(2\pi i) per loop, with contours closed below, as in CffRepresentation. Numerators, couplings, graph weights and the spatial integration measure are excluded. Repeated propagators are handled by higher-order residues.

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 residue and surface-pair explorer in Marimo or an HTML notebook. len(ltd) counts retained signed residues.

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]
ltd = diagram.integrate_energy(method="ltd")
expression = ltd.to_expression()
assert ltd.report.residues == len(ltd.residues)

Attributes

Name	Description
`diagram`	Originating diagram, retaining the ordered momentum routing and owner.
`on_shell_energies`	Shared symbolic energies and routed square roots, keyed by physical edge ID.
`report`	Counts of retained residues, distinct trees, unfolded terms and surfaces.
`residues`	Signed residues with tree, pole-sign and surface-pair inspection.
`surfaces`	All stored affine surfaces, with physical diagram edge IDs.

`diagram`

LtdRepresentation.diagram: FeynmanDiagram

Originating diagram, retaining the ordered momentum routing and owner.

Examples

routing = ltd.diagram.loop_momentum_basis

`on_shell_energies`

LtdRepresentation.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 ltd.on_shell_energies.values()]

`report`

LtdRepresentation.report: LtdReport

Counts of retained residues, distinct trees, unfolded terms and surfaces.

Examples

assert ltd.report.residues == len(ltd.residues)

`residues`

LtdRepresentation.residues: builtins.list[LtdResidue]

Signed residues with tree, pole-sign and surface-pair inspection.

Examples

residue = ltd.residues[0]

`surfaces`

LtdRepresentation.surfaces: builtins.list[EnergySurface]

All stored affine surfaces, with physical diagram edge IDs.

Examples

definitions = [s.to_expression() for s in ltd.surfaces]

Methods

Name	Description
`__len__`	Return the number of signed residues.
`__repr__`	Summarize the native LTD result.
`_display_`	Embed the explorer in Marimo’s script-enabled notebook frame.
`_repr_html_`	Explore native residues, surface pairs, and region-relative pole signs
`to_expression`	Return the scalar loop-energy integral as a Symbolica expression

`len`

LtdRepresentation.__len__() -> builtins.int

Return the number of signed residues.

Examples

Using the setup in LtdRepresentation:

residue_count = len(ltd)

`repr`

LtdRepresentation.__repr__() -> builtins.str

Summarize the native LTD result.

Examples

Using the setup in LtdRepresentation:

print(ltd)

`_display_`

LtdRepresentation._display_() -> typing.Any

Embed the explorer in Marimo’s script-enabled notebook frame.

Examples

Using the setup in LtdRepresentation:

presentation = ltd._display_()

`_repr_html_`

LtdRepresentation._repr_html_() -> builtins.str

Explore native residues, surface pairs, and region-relative pole signs.

Click cuts to navigate residues, tree edges to switch their pair, and hover cuts to trace the cycle fixing their signs in the ordered routing.

Examples

Using the setup in LtdRepresentation:

from IPython.display import display
display(ltd)

`to_expression`

LtdRepresentation.to_expression(*, expand_surfaces: builtins.bool = True) -> 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. Numerators, couplings, graph weights and the spatial measure are excluded. 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 = ltd.to_expression()
compact = ltd.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 residue contributions and prefactors.