LtdResidue

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

`LtdResidue`

class LtdResidue

One retained signed residue in an LTD representation.

The cut edges obey :math:q_e^0=\sigma_e E_e, with signs relative to the stored momentum arrows. The diagram’s ordered routing and contours determine these assignments; several residues may share a spanning tree. Higher-order poles can contribute several additive terms to one residue.

energy_map gives every internal energy at the residue. Substituting these energies into an uncut propagator gives the surface_pairs factors :math:q_e^0-E_e and :math:q_e^0+E_e.

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")
residue = ltd.residues[0]
signs = residue.pole_signs

Attributes

Name	Description
`cut_edges`	Physical IDs of the on-shell edges complementary to the spanning tree.
`energy_map`	Internal energies :math:`q_e^0` evaluated at this residue.
`id`	Stable residue index within this representation.
`pole_signs`	Cut-edge pole signs relative to the diagram’s stored momentum arrows
`surface_pairs`	The two factors of each surviving uncut propagator
`tree_edges`	Physical IDs of uncut internal edges in the spanning tree.

`cut_edges`

LtdResidue.cut_edges: builtins.list[builtins.int]

Physical IDs of the on-shell edges complementary to the spanning tree.

Examples

cuts = residue.cut_edges

`energy_map`

LtdResidue.energy_map: builtins.dict[builtins.int, Expression]

Internal energies :math:q_e^0 evaluated at this residue.

Examples

energies = residue.energy_map

Returns

dict[int, Expression] Physical internal-edge IDs mapped to affine combinations of OSE and external Q symbols. Cut entries equal :math:\sigma_e E_e.

`id`

LtdResidue.id: builtins.int

Stable residue index within this representation.

Examples

index = residue.id

`pole_signs`

LtdResidue.pole_signs: builtins.dict[builtins.int, builtins.int]

Cut-edge pole signs relative to the diagram’s stored momentum arrows.

Each entry fixes :math:q_e^0=\sigma_e E_e, with :math:\sigma_e\in\{-1,+1\}. The ordered routing and successive energy contours determine these signs for the entire residue. Selecting another surface factor does not change them.

Examples

assignments = residue.pole_signs

Returns

dict[int, int] Physical cut-edge IDs mapped to their pole signs.

`surface_pairs`

LtdResidue.surface_pairs: builtins.dict[builtins.int, SurfacePair]

The two factors of each surviving uncut propagator.

Each pair preserves :math:q_e^0-E_e and :math:q_e^0+E_e after evaluating :math:q_e^0 at the residue. Each factor’s sign relates it to its stored surface; it does not change the cut-edge pole assignment.

Examples

pairs = residue.surface_pairs

Returns

dict[int, SurfacePair] Physical tree-edge IDs mapped to their ordered minus/plus factors.

`tree_edges`

LtdResidue.tree_edges: builtins.list[builtins.int]

Physical IDs of uncut internal edges in the spanning tree.

Examples

tree = residue.tree_edges

Methods

Name	Description
`__repr__`	Summarize this residue’s cut edges and pole signs.
`_display_`	Display this residue in Marimo.
`_repr_html_`	Inspect this residue’s expression, fixed cuts and surface pairs.
`to_expression`	Return this residue’s contribution, including its signed coefficient.

`repr`

LtdResidue.__repr__() -> builtins.str

Summarize this residue’s cut edges and pole signs.

Examples

text = repr(residue)

`_display_`

LtdResidue._display_() -> typing.Any

Display this residue in Marimo.

Examples

view = residue._display_()

`_repr_html_`

LtdResidue._repr_html_() -> builtins.str

Inspect this residue’s expression, fixed cuts and surface pairs.

Examples

html = residue._repr_html_()

`to_expression`

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

Return this residue’s contribution, including its signed coefficient.

Examples

Using the setup in the class example:

expression = residue.to_expression()

Parameters

expand_surfaces (bool, optional) Replace stored surface placeholders by affine energy definitions. Defaults to True. On-shell energies remain symbolic in either case.

Returns

TensorExpression The scalar residue, including multiplicities and on-shell energy factors.