API reference

UndefinedParity

Parity character '±' when parity is not fixed or not specified. possible_ls_more skips the parity filter when any participating line carries it.

AbstractLineshape

Abstract supertype for propagator or lineshape payloads attached to internal cascade lines.

AbstractVertex

Abstract supertype for local binary-decay vertex payloads.

CascadeDecay(chains, reference_topology; couplings, names)

Container for a coherent set of decay chains that share compatible external spin axes and one reference topology. Each chain has a coupling coefficient and a string name for selection and display.

chains is stored as a concretely typed tuple of DecayChain objects. couplings and names are homogeneous NTuples of one numeric type and String, respectively. Vector inputs are accepted at the constructor boundary and converted immediately.

ConstantLineshape(value)

Minimal callable lineshape useful for tests and early prototypes.

CurrentFrame()

Start generated helicity-angle programs in the current axes. Use this when the input four-vectors are already expressed in the intended system frame.

DecayChain(topology, spins; propagators, vertices)

Static cascade model made from a validated flat topology and typed payloads. The public constructor accepts bracket-addressed address => payload pairs and stores the resolved flat graph information in typed static arrays. The spins input is consumed at construction time to build line_two_js(chain); it is not stored on the chain.

Propagator and vertex payloads are stored as Tuples, so a chain that mixes lineshape or form-factor types keeps every payload concretely typed and is evaluated without dynamic dispatch.

DecayChain(topology, spins; propagators, vertices)

Build a static cascade model from bracket-addressed payload pairs. User-facing addresses are resolved immediately to internal line and vertex ids. External, internal, and root spins are stored as the line-indexed line_two_js(chain); parities are consumed by LS helpers before chain construction.

DecayChainKinematics{Nl, Nv, T, A}
DecayChainKinematics(topology, line_masses2; vertex_angles)

Runtime kinematic input point for one decay topology and one event.

The object stores line invariant masses squared and local helicity angles in the internal indexing of a DecayTopology. Prefer the retrieval helpers line_invariant, vertex_masses2, and vertex_angles, which accept line or vertex ids and, with a topology, bracket addresses.

Fields

• line_masses2::SVector{Nl, T}: invariant masses squared indexed by line id.
• vertex_angles::SVector{Nv, A}: helicity angles indexed by vertex id.

DecayChainKinematics(topology, objs; initial_frame=HelicityRootFrame())

Compute a single-topology DecayChainKinematics from external four-vectors.

DecayTopology(bracket)

Construct a decay topology from bracket notation, for example DecayTopology((((1, 2), 3), 4)) or DecayTopology((1, 2, 3, 4)).

Final-state particles are numbered by the integer leaves. The left/right order inside each tuple is preserved because helicity conventions depend on child order. Internally the topology is stored as a flat line-vertex graph.

HelicityRootFrame()

Start generated helicity-angle programs by transforming to the root/system helicity frame. This is the default for fully general four-vectors.

KinematicPoint

Evaluated kinematic data for one event and one KinematicTask. It stores one DecayChainKinematics object per task topology, plus one external-axis alignment tuple per topology for the final particles requested by task.wigner_finals.

KinematicPoint(task, objs)

Build one KinematicPoint for external four-vectors objs. The point stores one DecayChainKinematics per task topology plus requested relative Wigner alignment angles.

KinematicTask(topologies; reference_topology, wigner_finals, initial_frame)

Reusable kinematic specification: topologies, reference frame for alignment, which final indices to align, and precompiled IDT programs. initial_frame is stored so evaluation can fall back to CurrentFrame() when the reconstructed parent momentum is numerically already at rest.

Propagator(two_j, lineshape)
Propagator(jp, lineshape)

Propagator payload for an internal cascade line, analogous to Vertex for vertices.

• two_j: twice the spin of the propagating system
• lineshape: callable propagator model (typically AbstractLineshape)
• extra: optional metadata (nothing, or (; parity=...) from SpinParity)

See also PropagatorWithParity for the LS-coupling case.

Alias of Propagator with parity metadata in extra.

Alias of SystemSpins for external helicity assignments in amplitude.

SystemParities(P1, P2, ...; P0)

External system parity descriptor. Final-state parities are positional; the root parity is always supplied as the keyword P0.

SystemSpinParities(spins, parities)
SystemSpinParities(spins, P1, P2, ...; P0)
SystemSpinParities(jp1, jp2, ...; jp0)
SystemSpinParities("1+", "0-", ...; jp0="1±")

External spin and parity descriptor for LS enumeration when explicit final-state and root parities are needed.

Spin-parity labels use the same jp"…" / string syntax as ThreeBodyDecays.ThreeBodySpinParities.

Alias of SystemSpins for external spin-projection assignments.

SystemSpins(two_h1, two_h2, ...; h0=nothing, two_h0=nothing)
SystemSpins(spins, two_λ1, two_λ2, ...; h0=nothing, two_h0=nothing)

External line-indexed doubled spin or helicity descriptor. Final-state values are positional (line 1, 2, …); the root is always supplied with two_h0=... or h0=....

Type aliases SystemHelicities and SystemSpinProjections name the same struct for amplitude helicities and spin projections.

Pass a SystemSpins as the first argument when building helicities to check each value against the corresponding line spin (|two_λ| ≤ two_j).

Vertex{R,F}

Local two-body decay vertex payload (alias of ThreeBodyDecays.VertexFunction).

Wraps a recoupling scheme h::R and optional form factor ff::F. Used in DecayChain vertex slots.

See also AbstractVertex.

WignerAngles

Standard ZYZ Wigner angles (α, cosβ, γ) for an external helicity axis. Identity rotation: (α=0, cosβ=1, γ=0).

merge(cascade1, cascade2, cascades...)

Concatenate decay chains from compatible CascadeDecay models. All inputs must share the same reference_topology and compatible external spin axes. Duplicate chain names are rejected.

This extends Base.merge for CascadeDecay arguments.

_vertex_factor(chain, x, vertex_ind)

Local vertex amplitude $V_{λ_0 λ_1 λ_2}$ on the three lines of topology vertex vertex_ind, as a dense array (cf. VRk / Vij in ThreeBodyDecays.aligned_amplitude).

alignment_angles_at(point, topology)

Return the relative Wigner alignment angles stored in point for topology. Axes follow final-state particle order. Final particles not requested by point.task.wigner_finals carry the identity rotation.

all_ls_decay_chains(topology, quantum, propagator_specs)

Build every DecayChain obtained from the Cartesian product of local LS couplings at all vertices. quantum must be a SystemSpinParities value.

What the function does is equivalent to the example below.

Example (three-body decay)

let
    (l1, itr_v1), (l2, itr_v2) = possible_vertex_couplings(topology, weak, propagators)
    map(Iterators.product(itr_v1, itr_v2)) do ((two_l1, two_s1), (two_l2, two_s2))
        DecayChain(topology, weak.spins;
            propagators,
            vertices = (
                l1 => Vertex(RecouplingLS((two_l1, two_s1))),
                l2 => Vertex(RecouplingLS((two_l2, two_s2))),
            ),
        )
    end
end

amplitude(chain, x, external_two_λs)

Return one helicity component of amplitude(chain, x). external_two_λs is a SystemHelicities value (alias of SystemSpins: positional finals, root via two_h0=... or h0=...).

amplitude(cascade, point::KinematicPoint)

Coherent helicity amplitude sum(cᵢ * Aᵢ) for all chains in cascade.

amplitude(chain, x)

Route masses, angles, and spins through the cascade and return the full amplitude array in the external helicity space. Final-state axes follow final_line_inds order; the root helicity is the last axis.

Build vertex factors, multiply into a line-indexed buffer, then contract internal helicities with @tullio (aligned-style chain, as in ThreeBodyDecays.aligned_amplitude). Helicity-frame Wigner rotations of ThreeBodyDecays.amplitude(dc, σs) are not applied yet.

amplitude(chain, point::KinematicPoint)

Chain-local helicity amplitude in the topology of chain, followed by external Wigner rotations on the final-state axes listed in point.task.wigner_finals (relative to point.task.reference_topology).

arity(topology, vertex_ind)

Return the number of ordered child lines attached to topology vertex vertex_ind.

bracket(topology; labels=nothing)

Reconstruct a compact bracket notation from the flat topology.

bracket_notation(topology; labels=nothing)

Return the compact nested-tuple notation for a topology, for example "((1,2),3)".

child_line_inds(topology, vertex_ind)

Return the outgoing lines of topology vertex vertex_ind in stored child order.

external_helicity_amplitude(F, chain)
external_helicity_amplitude(F, ext_dims, int_dims)

Sum internal propagator helicities and return the external-helicity array. For a DecayChain{Nf,Np}, external axes are Nf + 1 (finals + root) and internal axes are Np (propagating lines).

final_line_inds(topology)

Return the final-state line ids in canonical order (1:nfinal).

helicity_angle_program(topology, vertex_ind; initial_frame=HelicityRootFrame())

Build an InstructionalDecayTrees.jl instruction program that measures the local (cosθ, ϕ) angle at topology vertex vertex_ind in helicity convention.

helicity_angle_programs(topology; initial_frame=HelicityRootFrame())

Return one helicity-angle measurement program per topology vertex.

helicity_frame_path(topology, particle_index; initial_frame=HelicityRootFrame())

Build an InstructionalDecayTrees.jl instruction path that defines the helicity quantization frame for final-state particle particle_index. A final particle is represented internally by a topology line; this method keeps that line id out of the user-facing API.

incoming_line_ind(topology, vertex_ind)

Return the unique incoming graph line at topology vertex vertex_ind.

incoming_line_inds(topology, vertex_ind)

Return incoming graph lines at topology vertex vertex_ind in canonical line order. Valid rooted-tree topologies have exactly one incoming line per vertex; use incoming_line_ind when that invariant is required.

is_binary_vertex(topology, vertex_ind)

Return true when topology vertex vertex_ind has exactly two outgoing child lines.

kinematics_at(point, topology)

Return the DecayChainKinematics stored in point for topology. This is a retrieval helper; all kinematic values were computed when the KinematicPoint was built.

line_amplitude_tensor(chain, x)

Line-indexed amplitude buffer $F_{λ_{\mathrm{line}_1} \ldots} = \prod_v V_v$ before summing internal propagator helicities.

line_ind_for(topology, address)

Resolve a bracket address such as (1, 2) or ((1, 2), 3) to the internal line id used by the flat topology. The root address resolves to root_line_ind.

line_inds_at_vertex(topology, vertex_ind)

Return (parent, children...) for a topology vertex. Unlike vertex_line_inds, this helper supports vertices with any arity.

line_invariant(x, line_ind)
line_invariant(topology, x, address)

Return the invariant mass squared for a topology line. Pass a line id directly, or pass a DecayTopology and bracket address.

line_spin_parities(topology, quantum, propagator_specs)

Assemble a line-indexed SpinParity view. Requires SystemSpinParities. Final and root entries combine external spins and parities; internal entries come from each Propagator built with Propagator(jp, lineshape).

line_values(topology; finals, root, internals=())

Assemble a complete line-indexed SVector from public topology addresses. finals are ordered by final-state labels, root is the mother value, and internals are bracket-addressed pairs such as (1, 2) => value.

minimal_ls_decay_chain(topology, quantum, propagator_specs)

Build one DecayChain using the smallest allowed orbital coupling at each vertex. quantum must be a SystemSpinParities value.

This is the same as all_ls_decay_chains, but takes first of each local coupling list from possible_vertex_couplings.

minimal_vertex_coupling(jp0, jp1, jp2)

Smallest-two_l coupling allowed by possible_vertex_ls.

minimal_vertex_couplings(topology, quantum, propagator_specs)

Return a tuple of address => (two_l, two_s) pairs, one per topology vertex. Pair ordering follows the same root-first preorder convention as possible_vertex_couplings.

outgoing_line_inds(topology, vertex_ind)

Return outgoing graph lines at topology vertex vertex_ind in canonical line order as read from relation. Use child_line_inds when the stored child order matters for traversal or helicity conventions.

possible_ls_more(jp1, jp2; jp)

Allowed (two_l, two_s) for a two-body vertex. Same spin ranges as ThreeBodyDecays.possible_ls. Parity is enforced with the usual ⊗ rule unless any line has UndefinedParity ('±').

possible_vertex_couplings(topology, quantum, propagator_specs)

Return a tuple of address => couplings pairs, one per topology vertex. Each address is a bracket key such as (1, 2) or ((1, 2), 3); each couplings is a list of allowed (two_l, two_s) tuples sorted by increasing two_l.

Pairs appear in root-first preorder: the outer/root-attached vertex first, then deeper vertices from left to right — the same order as DecayChain expects for its vertices keyword. Within each list, couplings are sorted by increasing two_l.

possible_vertex_ls(jp0, jp1, jp2)

Return allowed (two_l, two_s) couplings at one binary vertex using possible_ls_more (including UndefinedParity, '±').

propagating_line_inds(chain)

Return the internal line ids that carry propagators, in propagator-index order.

relation(topology)

Return the line-vertex incidence matrix of a decay topology. Rows are graph lines and columns are vertices; -1 marks the incoming line at a vertex, +1 marks outgoing child lines, and 0 marks unrelated line-vertex pairs.

relative_wigner_angles(reference_topology, topology, particle_index, objs; T=Float64)

Compare helicity-frame instruction paths for final-state particle particle_index and return ZYZ Wigner angles (ϕ, θ, ψ) of the rotation from the reference topology frame to the topology frame.

unpolarized_intensity(cascade, point::KinematicPoint)

Return sum(abs2, amplitude(cascade, point)).

validate_topology(topology)

Validate that a topology is a connected rooted tree with an explicit root line. Throws ArgumentError on invalid input and returns true otherwise.

vertex_address(topology, vertex_ind)

Return the bracket address of a decay vertex, i.e. the same key used in vertex_ind_for and in DecayChain vertex payloads.

vertex_angles(x, vertex_ind)
vertex_angles(topology, x, address)

Return the local helicity-angle record (cosθ, ϕ) for a topology vertex. Pass a vertex id directly, or pass a DecayTopology and bracket address.

vertex_ind_for(topology, address)

Resolve the parent bracket address of a binary decay to the vertex id. For example, (1, 2) resolves to the vertex (1,2) -> 1,2.

vertex_line_inds(topology, vertex_ind)

Return (parent, child1, child2) for a binary vertex. The children are returned in stored child order.

vertex_masses2(topology, x, vertex_ind)
vertex_masses2(topology, x, address)

Return (m0², m1², m2²) for the parent and ordered children at a topology vertex. Pass a vertex id directly, or use a bracket address.