AlgebraicFactors

Finite toric potentials over named discrete channels, implementing L-SPEC-004 §0 and §1.1–§1.7, plus Grassmannian parameters (§2.1–§2.2) and the Plücker map (§5). Toric messages, energies and entropies use exact enumeration; fitting uses Newton or binary-feature IPF. Polynomial tables, residuals and complete-data fitting (§3a) are implemented. Single-branch Gaussian messages and optional square-system homotopy mixtures are implemented. Sampson scalarisation comes from LenticulumCore and is checked on the real polynomial factor too.

using AlgebraicFactors, LenticulumCore, Mycelium, Random, LinearAlgebra

names, alphabets = (:a, :b), (2, 3)
A = independence(names, alphabets)   # a design matrix, not a factor
f = ToricFactor(names, alphabets, A)
ps, st = setup(Random.Xoshiro(1), f)
p = Polarity(a = Unobserved(), b = Observed())
site, st = factor_message(f, :a, p, (b = DiracBelief(2),), nothing, ps, st)

Joint states are ordered with the first variable fastest, as in CartesianIndices. Default labels are 1:alphabet; custom labels are a tuple of unique-label vectors. Diracs match actual labels. Unlabelled categoricals are positional; labelled categoricals are matched and reordered by label. Shared graph variables need consistent canonical label order because Mycelium combines outgoing categorical messages positionally.

hierarchical builds a marginal-cell indicator block for each generator, named by tuples of channels or indices. Both matrix builders retain redundant statistics. Parameters are (η = …,), initially zero; the factor retains redundant statistics. Fitting returns the minimum Euclidean norm representative modulo constant logits and null directions.

factor_message excludes the target prior and target input. Latent channels enter with unit weight, and the factor supports every observed/latent combination around one target. This is a direct-message factor: it provides no assembled lens, joint latent posterior or forward model. The common conformance checker uses independent site and pooled-posterior fixtures through its direct-message path.

local_free_energy computes the joint factor expectation minus joint entropy from the incoming cavity messages (Mycelium.uses_cavity(f) == true). Mycelium supplies the variable entropy counting correction and rejects Emitting() edges on cavity-reading factors, including PriorFactor; use Bidirectional() when they must also send messages (LP-014). The tree regression checks exact marginals for both prior edge directions and free energy against $-\log Z$ for Bidirectional priors; Emitting-prior free energy throws ArgumentError. Set normalised = true for standalone game quantities: free_energy(f, π, y, ps, st) and LenticulumCore.entropy(f, π, y, ps, st). Use disjoint NamedTuples of prior beliefs and observations, or one prior belief and observations naming every other channel.

fit_mle(f, counts; method = :newton, tol = 1e-10, maxiter = 1000) returns (η, p, converged, iterations, residual, existence). Counts can be a joint-state vector or an array of size alphabets. p is a vector; the parameter can be used with ps = (η = fit.η,). Newton removes the gauge by an SVD of centred logits; :ipf requires a 0/1 design and cycles over individual rows. At target moments zero or one, IPF uses finite log-odds steps of -32 or +32 to approximate the infinite endpoint update.

converged means the infinity norm of the moment residual is at most tol. existence == :exists certifies an ordinary MLE only when every count is positive. Otherwise it is :suspected_boundary when the centred logit norm has grown from zero to at least 10 and length(p)*minimum(p) <= 1e-8, or :unknown. The boundary status is a heuristic, not proof of non-existence; it can accompany moment convergence.

inmodel(f, p; atol = 1e-8) requires strictly positive probabilities and tests the Euclidean least-squares residual of log probabilities in the augmented row space [1'; A]. binomial_residuals(f, p, moves) permits zero probabilities and checks supplied integer moves in the exact kernel of [1'; A] before evaluating their binomials. No Markov basis is computed. Both check probability normalisation with atol=1e-12, rtol=1e-8, separately from the membership tolerance.

Positive independence tables and a decomposable chain are checked against their closed forms by both methods; the tests also cover an arbitrary integer design, likelihood finite differences, the gauge, empty-row extended MLEs and independence minors. The implementation note lib/AlgebraicFactors.jl/src/fit.md gives the numerical thresholds and limitations.

Grassmann(k, m) represents a row space by a real k × m matrix Θ with Θ * Θ' ≈ I. project_tangent(M, Θ, G) returns its horizontal gradient, retract(M, Θ, Δ) orthonormalises the rows with positive-diagonal thin QR, and ispoint(M, Θ; atol=1e-8) checks the representation. Retraction rejects non-finite or numerically rank-deficient input (see its docstring).

M = Grassmann(2, 6)
Θ = rand(Random.Xoshiro(2403), M)
r = Retracted(Momentum(0.04, 0.6), M)  # also accepts GradientDescent
state = zero(Θ)                       # use nothing for GradientDescent
of = OptimiserFactor(:θ, r)
S = Diagonal([-2.0, -1.0, 1.0, 2.0, 3.0, 5.0]) # using LinearAlgebra
state, Θ = optimiser_step(of, state, Θ, 2Θ * S)

Retracted preserves Mycelium's momentum recurrence s′ = γ*s - η*grad and transports the velocity by projection onto the new horizontal space. Mycelium has no rule-state initializer; initialise it as above. Factor message emission reads (p=Θ, state=state). Nesterov and other rules are rejected: Nesterov's look-ahead leaves the manifold. The geometry tests check first-order descent and both optimisers against a known eigenplane, using η=0.04 for 400 iterations; they check factor-driven updates against direct rule_put at every step. The implementation note lib/AlgebraicFactors.jl/src/grassmann.md records the exact problem, tolerances and limitations. This uses the canonical Grassmann metric; it does not implement a statistical model's Fisher metric.

plucker(z,w) returns the bivector in lexicographic (i,j) order (i<j), listed by plucker_pairs(r). plucker_jacobian differentiates with respect to vcat(z,w). plucker_relations(r) returns sparse quadric records with increasing quadruples, monomial coordinate-index pairs and coefficients (1,-1,1); plucker_residuals(r,p) evaluates them.

f = PluckerFactor(4)  # names default to (:z, :w, :p)
pol = only(supported_polarities(f))
site, st = factor_message(f, :p, pol,
    (z = DiracBelief([1.,2,3,4]), w = DiracBelief([5.,6,7,8])),
    nothing, NamedTuple(), NamedTuple())
# site.value == [-4,-8,-12,-4,-8,-4]

The only polarity observes both inputs and emits on p; inverse fibres are not represented. Parameters and state are empty. Diracs transport exactly; sample beliefs pair particles by index, requiring equal positive counts and matching normalised weights (rtol=1e-12, atol=0). The first cloud's weights survive. A Dirac may accompany a cloud. Samples are column matrices or vectors of vectors.

Separate proper Gaussian inputs are independent. Their exact output mean and covariance are returned in a moment-matched GaussianBelief; the bilinear law is generally non-Gaussian. plucker_moments(μ,S,ν,T) exposes the exact moments, including singular covariance (zero input covariance represents a Dirac). For example, Dirac/Gaussian output has rank r-1 for nonzero fixed input. Core Gaussian beliefs cannot represent singular covariance. By default the factor rejects it, using λmin <= n*eps(T)*λmax as the numerical rank threshold; it never adds jitter automatically. Explicit covariance_jitter=δ > 0 adds absolute variance δ*I, giving an approximate covariance. The implementation note lib/AlgebraicFactors.jl/src/plucker.md derives the formula and explains this distinction from singular precision.

Pointwise map energy is zero. Graph-local free energy is zero for point accounting, and minus output entropy for the exact scalar Gaussian fragment described below. For named Dirac observations on both inputs, game free energy and entropy are zero, matching graph energy. The shared direct-message checker covers this sole forward point polarity at r=2 and r=4, with independent exterior-product fixtures and option-1 agreement. There is no assembled lens or inverse fibre belief; distributional entropy is restricted to the exact scalar Gaussian fragment below. Tests also exercise the supported interface and a Mycelium DAG with two Gaussian priors, and compare moments to an independent second-moment expansion and seeded Monte Carlo. The 400-point Klein-quadric test now exercises fit_nullspace in monomial and Chebyshev bases.

Enumeration costs grow with the product of alphabet sizes. This implementation uses CPU arrays and makes no GPU or automatic differentiation guarantee.

The §2.3 Sampson gauge obligation (§2.3) test uses a test-only two-equation residual r = Θ*v(z) with the six degree-at-most-two monomials in two variables. It checks an exact Jacobian against the core finite-difference default and Sampson energy invariance under a well-conditioned invertible row transformation and QR row orthonormalisation (rtol=1e-10). Seed 2307, 20 random points, damping λ=0, 0.3, and identity/non-isotropic data covariances are used for the row-transform test. Gauge-compatible damping Θ*Θ' retains invariance at a constructed rank-zero Jacobian, where zero damping throws. Default identity damping at λ=0.3 and plain SquaredNorm() each change energy by more than 1e-3 at some tested point. The implementation note lib/LenticulumCore.jl/src/energy.md derives the covariance law and documents the numerical SPD threshold, localisation and frozen Gauss–Newton metric. That original test remains alongside the §3(a) real polynomial-factor tests. Polynomial single-branch messages (§3b) and optional homotopy mixtures (§4) are implemented.

ExponentTable, veronese, veronese_jacobian and basis_change implement monomial and Chebyshev tables (see lib/AlgebraicFactors.jl/src/veronese.md). Ordering is increasing degree, then descending lexicographic exponents. There is no implicit data scaling; Chebyshev is intended for [-1,1] without enforcing it. Degree-exact Chebyshev products need not be homogeneous; incompatible square basis conversions throw.

PolynomialFactor(dims,tab,k;Σ=I,λ=0,iterations=1) initialises seeded Grassmann rows and empty state. Raw energies accept named channel values split between x/y. For Sampson scalarisation pack all values in dims order into y=z, with x=nothing, wrt=:y. The exact Jacobian is ΘDv for all data coordinates. One polarity per channel produces a single-branch Gaussian site; likelihood_message and factor_message share the routine and invert pools with the cavity once. Proper Gaussian/Dirac observed inputs are required; the target starts at the cavity mean, or zero. Iteration relinearises the posterior with A=JΣJᵀ+JₒCᵢₙJₒᵀ+λΘΘᵀ frozen per step. Target-rank deficiency retains an improper information-form site; singular A throws. Exact degree-one game/free energy and full common conformance are available under the normalised-output conditions below (LP-009). Nonlinear game entropy remains unsupported. The actual linear constraint is the degree-one oracle for every polarity. Circle, rank-one fibre and a three-channel graph have independent objective checks. ΘΘ′ damping preserves row-gauge invariance; undamped energy is also invariant under polynomial basis conversion, while coefficient-identity damping is basis dependent. See the implementation note polynomial.md.

fit_nullspace(tab,X,k;rtol=1e-12) takes N×n points in columns and reports Θ, all m singular values, numericalrank, nullity and threshold. No centring, normalisation or column scaling is performed. `fitsampsonminimises the summed half squared Sampson cost with the full analytic gradient, horizontal projection, QR retraction and exchangeableAbstractSampsonMethodinstances.RiemannianGradient()is Armijo descent;FNS()is the corrected published one-equation update; the defaultRiemannianTrustRegion()uses truncated CG with the exact Riemannian Hessian, including the Grassmann curvature term.:riemannian,:fnsand:trustregionalias default instances. ImplementAlgebraicFactors.sampsonsolve(method, problem::SampsonProblem, Θ0;tol,maxiter)to plug in a method:problem.manifold,problem.costgradient(Θ)(Euclidean gradient),problem.hessianvector(Θ,ξ),projecttangentandretract` supply the objective and geometry. All stop at the horizontal Frobenius gradient norm, and return Θ,cost,gradientnorm,converged,iterations. RTR additionally reports hessian_products; its iteration count includes rejected trials. The seeded ellipse and noisy k=2 tests reach tol=1e-7 in four RTR iterations; the implementation note polyfit.md records the comparison. Singular covariance throws with point index; explicit λ adds λΘΘ′. No global optimality is claimed. The implementation note polyfit.md derives the gradient and records the seeded Klein/conic/two-equation checks and their numerical results.

Multi-branch polynomial inference

Load HomotopyContinuation (tested with 2.22.4 on Julia 1.13.1), then pass branches=HomotopyBranches() to PolynomialFactor; branches=:single remains the default. The solver requires a square target system k=q; other shapes use §3's single-branch site. Observations are Dirac/proper Gaussian beliefs at their means; target priors are proper Gaussian or trivial (flat in Lebesgue measure).

using AlgebraicFactors, HomotopyContinuation, LenticulumCore, Mycelium, LinearAlgebra
f = PolynomialFactor((x=1,y=1), ExponentTable(2,2), 1;
                     Σ=0.0025I, branches=HomotopyBranches())
ps = (Θ=reshape([-1.,0,0,1,0,1],1,:),) # x²+y²−1
info = polynomial_branches(f, :y, (x=DiracBelief(0.6),), Gaussian(0.3,0.4), ps)
info.posterior # MixtureBelief of two branch posteriors
branch_entropy_bounds(info.posterior) # label entropy and differential-entropy bounds

polynomial_branches returns finite root records, path diagnostics (including failed and at-infinity flags), per-root certification, determinants, residual covariances, sites, components and weights. Reality uses an absolute imaginary coordinate tolerance; singular roots are reported and never weighted. If no regular real root remains, factor_message/invert throw; inspection still returns diagnostics and nothing mixtures. Path results and certificates are not a proof of completeness. HC's certification uses interval arithmetic and Krawczyk's method (Breiding and Timme, 2018; Breiding et al., 2023).

For Sⱼ=Jⱼ⁻¹AⱼJⱼ⁻ᵀ, posterior masses are proportional to N(rootⱼ;μ,P+Sⱼ)/|det Jⱼ|. Likelihood messages contain normalised Gaussian sites N(rootⱼ,Sⱼ) with masses proportional to 1/|det Jⱼ|; Mycelium's overlap rule produces the posterior weights when pooled with the prior. Using posterior masses in the message would apply the prior overlap twice. This approximates the nonlinear residual likelihood locally at each regular real root.

The entropy helper reports H(w) and ΣwHⱼ ≤ H ≤ ΣwHⱼ+H(w), not an exact mixture entropy. test/homotopy.jl checks closed-form circle/cubic/product-conic roots, basis and row-gauge agreement, constant-residual-noise quadrature convergence, and seeded Monte Carlo entropy bounds. The implementation note homotopy.md gives the measure convention, limitations and measured test results. No game free energy, IFT derivative, parameter homotopy or positive-dimensional solve is supplied. The CI package test activates the extension through its test dependency; this docs environment loads it too.

AlgebraicFactors.AlgebraicFactors — Module
AlgebraicFactors

Exact finite log-linear factors for Lenticulum and Mycelium. See ToricFactor, independence, and hierarchical. fit_mle fits moments; inmodel and binomial_residuals check supplied probabilities. Grassmann and Retracted provide Grassmannian parameter updates. PluckerFactor transports beliefs through the bivector map plucker. ExponentTable and PolynomialFactor provide polynomial residuals and Gaussian messages via PolynomialModel, with optional multi-branch inference through HomotopyBranches; fit_nullspace and fit_sampson fit complete data.

source
AlgebraicFactors.ExponentTable — Type
ExponentTable(N, d; basis=:monomial, homogeneous=false)

Columns of exponents::Matrix{Int} are all N-variable multi-indices of total degree ≤ d (exactly d when homogeneous). Order: increasing total degree, then descending lexicographic order, e.g. (1,x,y,x²,xy,y²) for N=2,d=2. Chebyshev entries are products of first-kind T polynomials, intended for data scaled to [-1,1]; the domain is not enforced. With homogeneous=true the indices have degree d; Chebyshev polynomials need not be homogeneous.

source
AlgebraicFactors.FNS — Type
FNS()

One-equation Fundamental Numerical Scheme of Chojnacki et al. (2000), §4.2, Fig. 1. No tunable keywords. Uses the eigenvector with eigenvalue closest to zero, with sign alignment; stops on the full Sampson gradient norm. Only k=1 is supported. This iteration need not decrease the cost monotonically.

source
AlgebraicFactors.Grassmann — Type
Grassmann(k, m)

The real Grassmannian of k-dimensional subspaces of ℝ^m, with 1 ≤ k ≤ m. A point is represented by a real k × m matrix Θ with orthonormal rows. Representatives Θ and O * Θ for orthogonal O describe the same point. Geometry routines assume orthonormal input; use ispoint to check it.

source
AlgebraicFactors.HomotopyBranches — Type
HomotopyBranches(; real_tol=1e-8, singular_tol=1e-8, certify=true)

Use all isolated roots for a square PolynomialFactor target, after loading HomotopyContinuation. Pass as PolynomialFactor(...; branches=HomotopyBranches()); :single remains the default. Reality means max(abs(imag(root))) ≤ realtol. Singularity uses σmin(Ju) ≤ singulartol*max(1,σmax(Ju)), or HC's singular flag. Singular roots are reported but never weighted. Inference throws if there are no regular real roots; inspect polynomial_branches for diagnostics even then. Only proper Gaussian or trivial (Lebesgue-flat) target priors are supported. Certification uses HC's interval/Krawczyk certificates, not α-theory.

source
AlgebraicFactors.PluckerFactor — Type
PluckerFactor(r; names = (:z, :w, :p), covariance_jitter = 0)

Parameter-free deterministic map (z,w) → z ∧ w. Only the forward polarity is supported: the fibre of a nonzero decomposable bivector is an SL₂-orbit of pairs; no belief on that fibre is built, and p=0 is degenerate.

Dirac pairs give a Dirac. Sample pairs are transported by matching particle index, with equal nonzero counts and matching normalised weights (rtol=1e-12, atol=0); these are a joint empirical belief, not a Cartesian product of independent clouds. The first cloud's weights are preserved. A Dirac may accompany either sample cloud. Matrices store particles in columns; vectors store vector-valued particles.

Separate Gaussian inputs are assumed independent. Gaussian/Gaussian and Dirac/Gaussian messages match exact moments, but the bilinear output law is generally not Gaussian. GaussianBelief cannot represent singular covariance. Without explicit regularisation, a covariance with λmin ≤ n*eps(T)*λmax throws; plucker_moments still exposes its exact moments. Set covariance_jitter > 0 to explicitly add that absolute variance to every output coordinate before constructing the belief (then covariance is approximate). No jitter is ever added by default. Improper Gaussians and other belief pairs throw.

Pointwise energy is zero. Conditional fixed-Dirac games have zero entropy/free energy. For r=2, one nonzero fixed vector and one proper Gaussian give an exact scalar Gaussian forward game (no output conditioning or covariance jitter), including graph-local entropy. Other distributional games throw; an assembled Bayesian lens is not supplied.

source
AlgebraicFactors.PolynomialBelief — Type
PolynomialBelief(z0, free, m, S, H, basis)

A frozen joint factor belief of a degree-one PolynomialFactor: the Dirac channels' values in z0, and a Gaussian N(m, S) with entropy H on the coordinates free (indices into the concatenated channels). basis is the factor's degree-one basis (v0, V), a constant carried along so that differentiation does not enter it. Returned by Mycelium.factor_belief, read by Mycelium.belief_free_energy.

source
AlgebraicFactors.PolynomialFactor — Type
PolynomialFactor(dims::NamedTuple, tab::ExponentTable, k; Σ=I, λ=0, iterations=1, branches=:single)

Soft relation Θ*veronese(tab,z) ≈ 0 over named channels, concatenated in keys(dims) order. Parameters (Θ=...,) are seeded Haar Grassmann(k,m) rows; state is empty. Σ is a data-space PSD covariance, λ≥0.

energy(f,x,a,y,ps,st) accepts disjoint NamedTuples in x/y (or nothing), like LinearConstraintFactor. Scalars represent one-dimensional channels. For Sampson scalarisation and Jacobians use the packed convention x=nothing, y=z::Vector: wrt=:y differentiates all data coordinates. Named splits only support the raw residual; pack them before scalarising.

One polarity per target channel supplies a single-branch Gaussian likelihood site. Observed beliefs must be Dirac or proper Gaussian; the target expansion point is its proper Gaussian/Dirac cavity mean, or zero without a cavity. iterations ≥ 1 relinearises at the current posterior mode (frozen-metric Gauss–Newton). The returned site excludes the prior; invert pools it with the prior once. Singular target precision is retained; singular residual covariance throws. Set branches=HomotopyBranches() and load HomotopyContinuation for all isolated roots of square systems; see polynomial_branches. Exact game/free energy requires degree one, branches=:single, a square nonsingular last-channel block, positive-definite residual covariance and a proper pooled posterior. The last channel defines the normalised conditional output; nonlinear games throw (LP-009). iterations applies only to branches=:single.

Damping is λΘΘ′, invariant under invertible row gauges. Nonorthogonal basis changes preserve undamped energy, but do not preserve this coefficient metric.

source
AlgebraicFactors.PolynomialModel — Type
PolynomialModel(factor, polarity)

Single-target Gaussian model of a polynomial relation. By default it is local; HomotopyBranches() supplies a mixture over regular real isolated roots. Its solver uses exact polynomial Jacobians and frozen residual covariances, with Gauss–Newton curvature (not the full Laplace Hessian away from a zero residual). The single-branch default does not enumerate roots. Neither inference mode differentiates the solve by the implicit function theorem.

source
AlgebraicFactors.Retracted — Type
Retracted(rule, M::Grassmann) <: Mycelium.AbstractUpdateRule

Wrap Mycelium.GradientDescent or Mycelium.Momentum with horizontal projection and QR retraction. All other rules throw ArgumentError. Nesterov is excluded because its look-ahead leaves the manifold; a retracted look-ahead and consistent gradient transport would need a separate contract.

rule_get(r, state, Θ) = Θ. rule_put projects the gradient, calls the inner rule, projects its candidate displacement, and retracts. Momentum's new state is the inner rule's plain k × m velocity matrix, transported by horizontal projection at the new representative. It uses Mycelium's recurrence s′ = γ*s - η*grad (heavy-ball momentum).

Mycelium has no rule-state initializer: supply nothing for gradient descent (its state is passed through unchanged), or zero(Θ) for momentum. Works with Mycelium.OptimiserFactor(:θ, r) and Mycelium.optimiser_step directly; message emission uses st = (p = Θ, state = state) as in Mycelium.

source
AlgebraicFactors.RiemannianGradient — Type
RiemannianGradient(; c=1e-4, shrink=0.5, max_backtracks=60, initial_step=1.0)

Horizontal gradient descent with QR retraction and Armijo sufficient decrease c ∈ (0,1). Backtracking multiplies the step by shrink ∈ (0,1) at most max_backtracks ≥ 1 times. Each search starts at twice the last accepted step, capped at finite positive initial_step. Defaults reproduce :riemannian.

source
AlgebraicFactors.RiemannianTrustRegion — Type
RiemannianTrustRegion(; Δ0=1.0, Δmax=100.0, ρ_accept=0.1,
                      tcg_maxiter=100, κ=0.1, θ=1.0)

Riemannian trust regions with Steihaug–Toint truncated conjugate gradients, Frobenius metric on horizontal Grassmann lifts, and the existing QR retraction. Uses analytic Riemannian Hessian-vector products (no finite-difference step). See Absil, Mahony & Sepulchre (2008), Chapter 7, Algorithms 10–11.

Finite radii satisfy 0 < Δ0 ≤ Δmax. Accept a step when actual/predicted cost reduction exceeds ρ_accept ∈ [0,1/4). Ratios below 1/4 quarter the radius; ratios above 3/4 double it (up to Δmax) if CG reached the boundary. CG takes at most tcg_maxiter ≥ 1 iterations and stops when its residual is at most norm(grad)*min(κ,norm(grad)^θ), with finite κ ∈ (0,1) and θ > 0. Negative curvature and boundary crossings truncate CG at the trust sphere.

source
AlgebraicFactors.SampsonProblem — Type
SampsonProblem

Problem supplied by fit_sampson to sampson_solve. Public fields: manifold::Grassmann, cost_gradient(Θ) returning (cost, Euclidean_gradient), and hessian_vector(Θ, ξ) returning the horizontal Riemannian Hessian action for horizontal ξ. Use project_tangent(problem.manifold, Θ, G) and retract(problem.manifold, Θ, ξ) for geometry. Data are cached once per fit; solvers must not mutate the problem or the supplied initial Θ.

source
AlgebraicFactors.ToricBelief — Type
ToricBelief(logq)

A frozen joint factor belief of a ToricFactor: log-probabilities over the joint states, in CartesianIndices(alphabets) order. Returned by Mycelium.factor_belief and read by Mycelium.belief_free_energy, which re-scores it at the current parameters.

source
AlgebraicFactors.ToricFactor — Type
ToricFactor(names::Tuple, alphabets::Tuple, A::AbstractMatrix{<:Integer};
            normalised = false, labels = nothing)

Finite potential exp(dot(ps.η, A[:, x])), with one channel per name. Joint states follow CartesianIndices(alphabets): the first variable varies fastest. A has one column per joint state; its rows need not be independent or contain a constant. Parameters are (η = zeros(size(A, 1)),) initially (Float64); state is empty. The normalised distributions agree exactly when A' * (η - η′) is constant.

States are 1:alphabets[i], or labels[i] when a tuple of unique-label vectors is provided. Pointwise tuples and Diracs match labels by isequal, never by interpreting an integer label as a position. Unlabelled categorical inputs are positional; labelled ones must have exactly the channel's support and are reordered by label. Outgoing categoricals use the factor's label order (labels = nothing for default states).

Every polarity with one unobserved channel and all others observed or latent is supported. Missing, nothing, missing, TrivialBelief() and Latent() inputs have unit weight. Messages exclude both the target input and its prior. Enumeration visits all prod(alphabets) states; scoring also costs size(A, 1) per state. See fit_mle for fitting and inmodel for positive model membership.

source
AlgebraicFactors.basis_change — Method
basis_change(mon, cheb)

Exact BigInt matrix C with veronese(cheb,x) == C*veronese(mon,x) and Θ_mon = Θ_cheb*C. Tables must have identical indices and the indicated bases. Degree-exact Chebyshev tables generally contain lower-degree terms outside the homogeneous monomial span; those incompatible tables throw (d≥2).

source
AlgebraicFactors.binomial_residuals — Method
binomial_residuals(f::ToricFactor, p, moves) -> Vector{Float64}

Evaluate prod(p.^u⁺) - prod(p.^u⁻) for each supplied integer-vector move u. p is a finite non-negative probability vector/array in factor order, including boundary points. Every move must have length prod(f.alphabets), sum(u) == 0, and A*u == 0; these kernel checks use exact BigInt arithmetic. Invalid inputs throw ArgumentError. Products use log space, treating empty products as 1 and positive powers of zero as 0. A supplied collection need not be a Markov basis; vanishing on it alone does not certify general boundary membership. No basis is computed.

source
AlgebraicFactors.branch_entropy_bounds — Method
branch_entropy_bounds(m::MixtureBelief)

Return (label_entropy, lower, upper) in nats for a proper Gaussian mixture: Σw H(component) ≤ H(mixture) ≤ Σw H(component)+H(w). No exact mixture entropy or game-level entropy is implied. Zero masses contribute zero to H(w).

source
AlgebraicFactors.fit_mle — Method
fit_mle(f::ToricFactor, counts; method = :newton, tol = 1e-10, maxiter = 1000)

Fit the normalised model to finite non-negative real counts with positive total. counts is an array of size f.alphabets or a vector in joint-state order (first variable fastest). Calculations use dense CPU Float64 arrays and log probabilities.

Return (η, p, converged, iterations, residual, existence). p is a vector in factor order, reproduced by ps = (η = η,). η is the minimum Euclidean norm representative modulo ker((I - 11'/m)A'), computed by an SVD with relative cutoff max(size(A)...) * eps(Float64). residual = norm(A*p - A*counts/sum(counts), Inf); converged means exactly residual ≤ tol. iterations counts accepted Newton steps or complete IPF sweeps; an exhausted budget or stalled line search can return false.

:newton uses an orthonormal basis of centred logits, their covariance Hessian, and backtracking on the per-observation log-likelihood. Redundant rows and designs without a constant row are supported. :ipf requires entries in {0,1} and cycles over rows, exactly setting each binary feature's mean using its log odds. At target 0 or 1 the exact update is infinite; use a finite log-odds step of -32 or +32 per sweep instead, approaching the endpoint while retaining finite parameters.

existence is separate from convergence: :exists certifies the ordinary MLE only when every count is strictly positive (the target is then a positive convex combination of all columns, hence in their relative interior). Otherwise it is :suspected_boundary if the centred logit norm has grown from zero to at least 10 and m*minimum(p) ≤ 1e-8; it is :unknown otherwise. This heuristic is no proof of non-existence. A boundary extended MLE can satisfy the moment tolerance while its finite parameter approximations grow, so converged and :suspected_boundary can occur together. No LP existence test or exact boundary parameter is returned.

source
AlgebraicFactors.fit_nullspace — Method
fit_nullspace(tab, X, k; rtol=1e-12)

Fit the bottom k right singular vectors of V (points are columns of N×n X; V[i,:]=veronese(tab,X[:,i])). No centring, column scaling or normalisation. Returns (Θ, singular_values, numerical_rank, nullity, threshold). The m singular values are descending, padded with structural zeros when n<m. nullity counts values ≤ rtol*σmax, including exact zeros when σmax=0. Θ has orthonormal rows. The rank decision is diagnostic; k remains the caller's choice.

source
AlgebraicFactors.fit_sampson — Method
fit_sampson(tab, X, k; Σ=I, Θ0=nothing, method=RiemannianTrustRegion(),
            tol=1e-7, maxiter=10000, λ=0)

Minimise summed half squared Sampson distance on Grassmann(k,m). Initialisation uses fit_nullspace; supplied Θ0 must have orthonormal rows. No data or column scaling. The default method is RiemannianTrustRegion (since 2026-10-26; before, Armijo descent, now RiemannianGradient()). method accepts an AbstractSampsonMethod instance; symbols :riemannian, :fns, :trust_region alias default RiemannianGradient, FNS, RiemannianTrustRegion respectively. User methods implement sampson_solve. All built-in methods stop only at horizontal Frobenius gradient norm ≤ tol. Return (Θ,cost,gradient_norm,converged,iterations); RTR also reports hessian_products. For RTR, iterations count attempted outer steps (including rejected steps); for gradient descent and FNS, completed updates. Singular current or trial covariances throw with point index. Explicit λ≥0 adds λΘΘ′ to each pushed covariance. Dense real CPU data only; no global optimality.

source
AlgebraicFactors.hierarchical — Method
hierarchical(names, alphabets, generators) -> Matrix{Int}

Design matrix with one block of marginal-cell indicator rows per generator, in the supplied order. Each generator is a tuple of distinct channel names or 1-based indices. Within a block, cells follow the generator's order, first listed variable fastest. Columns follow CartesianIndices(alphabets). Empty generators give a constant row; an empty generator collection gives a zero-row (uniform) model. Redundant blocks are kept.

source
AlgebraicFactors.independence — Method
independence(names, alphabets) -> Matrix{Int}

The hierarchical design with singleton generators in channel order. For a 2×3 table there are five rows: two indicators for the first variable, then three for the second.

source
AlgebraicFactors.inmodel — Method
inmodel(f::ToricFactor, p; atol = 1e-8) -> Bool

Test positive model membership by least squares: log(p) must lie in the row space of [ones(1,m); A]. atol bounds the Euclidean (2-norm) projection residual in log probabilities, not a probability error. Uses the same SVD rank cutoff as fit_mle. p must be a finite, strictly positive probability vector or an array of size f.alphabets, in factor order; otherwise throw ArgumentError. Normalisation is checked with atol=1e-12, rtol=1e-8, independently of the membership tolerance. Boundary membership requires binomials; see binomial_residuals.

source
AlgebraicFactors.ispoint — Method
ispoint(M::Grassmann, Θ; atol = 1e-8)

Check shape, finiteness and Θ * Θ' ≈ I using absolute tolerance atol (and zero relative tolerance). Negative or non-finite tolerances throw.

source
AlgebraicFactors.plucker — Method
plucker(z, w)

The bivector z ∧ w: z[i]*w[j] - z[j]*w[i] in plucker_pairs order. Inputs must be vectors of equal length ≥ 2. Preserves generic arithmetic (including integers, rationals and complex numbers); no floating-point conversion.

source
AlgebraicFactors.plucker_jacobian — Method
plucker_jacobian(z, w)

Closed-form binomial(r,2) × 2r Jacobian. Columns differentiate with respect to vcat(z, w): all z coordinates first, then all w coordinates.

source
AlgebraicFactors.plucker_moments — Method
plucker_moments(μ, S, ν, T) -> (mean, cov)

Exact first two moments of z ∧ w for independent real random vectors with means μ, ν and covariances S, T. Gaussianity is unnecessary for this identity. Zero covariance represents a Dirac. Covariances are assumed valid; only shapes are checked. Returns the exact covariance even when singular; no jitter is added. See plucker.md for the derivation.

source
AlgebraicFactors.plucker_pairs — Method
plucker_pairs(r)

Coordinate indices for r ≥ 2, in lexicographic order: (1,2), (1,3), …, (1,r), (2,3), …, (r-1,r). There are binomial(r,2).

source
AlgebraicFactors.plucker_relations — Method
plucker_relations(r)

A vector of relation records in lexicographic quadruple order. Each record has indices = (i,j,k,l) and monomials = ((ij,kl), (ik,jl), (il,jk)), where each integer in a monomial indexes p in plucker_pairs(r) order, and coefficients = (1,-1,1). Thus each represents p[ij]*p[kl] - p[ik]*p[jl] + p[il]*p[jk]. There are binomial(r,4) records; for r=2,3 the vector is empty. This is sparse polynomial test data, not fitting.

source
AlgebraicFactors.polynomial_branches — Method
polynomial_branches(f, target, inputs, prior, ps; method=HomotopyBranches())

Inspect a square polynomial solve. Requires using HomotopyContinuation. Returns roots (distinct finite candidates, with real/singular/certified flags, detJu, A, site, posterior component and weight), paths (including failed and at-infinity flags), weights, components, likelihood, and posterior. Unweighted roots have zero weight; absent mixtures are nothing.

For regular real roots, S=Ju⁻¹ A Ju⁻ᵀ and posterior weights are proportional to N(root; μ,P+S)/abs(detJu), or 1/abs(detJu) for a Lebesgue-flat prior, computed in log space. The extrinsic likelihood is a mixture of normalised branch sites N(root,S), with masses proportional to 1/abs(detJu). Mycelium's overlap reweighting then reproduces the posterior. Its masses differ from posterior masses, as required to avoid applying the prior twice.

This is a root-local Gaussian approximation, not the exact nonlinear posterior at finite noise. Positive-dimensional square systems are outside its contract; path diagnostics and individual certificates do not certify completeness.

source
AlgebraicFactors.project_tangent — Method
project_tangent(M::Grassmann, Θ, G)

Return G - (G * Θ') * Θ. This is the horizontal lift of the Grassmann tangent space at the orthonormal representative Θ: Δ * Θ' = 0. It removes the vertical (row-basis rotation) directions from the Stiefel tangent space; it is not the full Stiefel tangent projection. Uses the Frobenius metric on horizontal lifts, with cost O(k²m).

source
AlgebraicFactors.retract — Method
retract(M::Grassmann, Θ, Δ)

Orthonormalise the rows of Θ + Δ by thin QR of its transpose, fixing signs so diag(R) > 0. Thus retract(M, Θ, zero(Θ)) ≈ Θ. For a retraction step, Θ must be orthonormal and Δ horizontal (see project_tangent); arbitrary displacements are also accepted as row orthonormalisation.

Throws ArgumentError on non-finite or numerically rank-deficient input: any abs(R[i,i]) ≤ max(k,m) * eps(T) * norm(R, Inf) is rejected, where T is the QR element type. This is a floating-point QR diagonal criterion, not an exact rank certificate. Dense real CPU arrays are the supported use.

source
AlgebraicFactors.sampson_solve — Function
sampson_solve(method::AbstractSampsonMethod, problem::SampsonProblem, Θ0;
              tol, maxiter)

Extension hook: implement this function for a user method subtype, accepting positive gradient tolerance tol and nonnegative iteration budget maxiter. fit_sampson validates the data and initial orthonormal representative first. Use the problem's callable fields and Grassmann geometry (see SampsonProblem). Return a named tuple containing Θ, cost, gradient_norm, converged, iterations; extra fields are allowed. Θ must have orthonormal rows, cost is the summed half squared Sampson objective there, gradientnorm is its horizontal Frobenius norm, converged means gradientnorm ≤ tol, and iterations ≤ maxiter. At maxiter=0 evaluate Θ0 without taking a step. Singular covariances throw; solvers must not silently regularise them. No global optimum is promised.

source
AlgebraicFactors.veronese — Method
veronese(tab, x)

Evaluate the ordered polynomial basis. Monomial arithmetic preserves the input element type (including integers and rationals); there is no scaling.

source
AlgebraicFactors.veronese_jacobian — Method
veronese_jacobian(tab, x)

Exact polynomial Jacobian, m × N. Products avoid division by coordinates, so zero coordinates and Chebyshev endpoints are supported.

source
Base.rand — Method
rand(rng::AbstractRNG, M::Grassmann)
rand(M::Grassmann)

Draw a Haar-random Grassmann point, represented by orthonormal rows, using thin QR of an m × k standard Gaussian matrix with positive-diagonal R. Returns a dense Float64 matrix.

source
LenticulumCore.energy — Method
LenticulumCore.energy(f::ToricFactor, x::Tuple, a, y, ps, st)

Pointwise scalar energy -dot(ps.η, a_x) (plus log partition when normalised). x contains all channel labels in channel order; a and y are unused. The shorter energy(f, x, ps, st) is equivalent. Both return (energy, st).

source
LenticulumCore.free_energy — Method
LenticulumCore.free_energy(f::ToricFactor, π, y, ps, st)
LenticulumCore.entropy(f::ToricFactor, π, y, ps, st)

Exact scalar game quantities for normalised = true, using the same joint factor belief as local_free_energy. π is a NamedTuple of incoming channel beliefs and y a disjoint NamedTuple of observations (beliefs or labels). A single belief π is assigned to the sole channel omitted from y. nothing supplies no evidence; unspecified channels are summed with unit weight. Entropy is positive Shannon entropy.

source
LenticulumCore.pushforward — Method
LenticulumCore.pushforward(f::PluckerFactor, (zbelief, wbelief), ps, st)

Push a pair of beliefs through the forward map, using the conventions of PluckerFactor. State is returned unchanged; no parameters are used.

source
Mycelium.factor_belief — Method
Mycelium.factor_belief(f::PolynomialFactor, msgs, ps, st) -> PolynomialBelief
Mycelium.belief_free_energy(f::PolynomialFactor, b::PolynomialBelief, ps, st)

The degree-one joint belief of local_free_energy, frozen, and the graded free energy at that belief for the current Θ: fit = E_b[r'Q⁻¹r]/2, complexity the residual normaliser minus log|det J_out|, negentropy = -H(b). Its parameter derivative is the envelope gradient of the Bethe free energy (LP-020). Same domain as local_free_energy: degree one, branches=:single.

source
Mycelium.factor_belief — Method
Mycelium.factor_belief(f::ToricFactor, msgs, ps, st) -> ToricBelief
Mycelium.belief_free_energy(f::ToricFactor, b::ToricBelief, ps, st)

The joint belief q ∝ exp(A'η) * prod(msgs) of local_free_energy, frozen, and E_q[energy_η] - H(q) at that q for the current η. At the belief they were evaluated at the two free energies agree, and the parameter derivative of the second is the envelope gradient of the Bethe free energy (LP-020): E_q[-a_x] plus, when normalised, E_{p_η}[a_x]. Holding the messages fixed instead differentiates q too, which is not that gradient once the messages are not points.

source
Mycelium.factor_message — Method
Mycelium.factor_message(f::PolynomialFactor, target, polarity, inputs, prior, ps, st)

Single-branch extrinsic Gaussian site at the final expansion point x0: Λ = J_u'*(A\J_u), h = Λ*x0 - J_u'*(A\r), with A = J*Σ*J' + sum(J_o*C_o*J_o') + λ*Θ*Θ' (all data coordinates in Σ). The Sampson metric is frozen per iteration; refreshing it is an approximation, not differentiation of the full varying-metric Sampson objective. Rank-deficient J_u gives an improper site, including zero precision at rank zero. Without a proper posterior no further relinearisation is attempted. No damping or backtracking is automatic, and iterations have no general descent guarantee. The target input is ignored; the cavity affects expansion but is excluded from the returned canonical parameters. invert combines it exactly once.

source
Mycelium.factor_message — Method
Mycelium.factor_message(f::ToricFactor, target, polarity, inputs, prior, ps, st)

Exact sum-product site on target, integrating every other channel. prior and any target entry in inputs are excluded. normalised changes only a constant and hence does not affect the returned categorical probabilities. Returns (belief, st).

source
Mycelium.local_free_energy — Method
Mycelium.local_free_energy(f::ToricFactor, msgs, ps, st)

E_q[energy] - H(q) for the joint factor belief q ∝ exp(A'η) * prod(msgs). These are variable-to-factor messages, not variable marginals. No incoming-message energy is charged. Mycelium separately adds sum((degree(v)-1) * H(b_v)); adding that correction here would count it twice. Returns a scalar and the unchanged state.

source

Exact game fragments (LP-009)

Degree-one PolynomialFactor has exact Gaussian game/graph free energy with branches=:single, a square nonsingular last-channel coefficient block, positive-definite constant residual covariance and a proper pooled posterior. The last channel defines a normalised conditional; its log-Jacobian enters the normaliser. π belongs to the first channel and y names all remaining channel beliefs. Nonlinear and singular conditional cases throw with reasons.

PluckerFactor at r=2 has exact scalar Gaussian output entropy with one fixed nonzero vector and one proper Gaussian input, no output conditioning and zero covariance jitter. Higher-dimensional fixed-vector images are singular relative to output Lebesgue measure; two Gaussian inputs are generally non-Gaussian. Those distributional games still throw. The common checker covers both degree-one polynomial polarities and the scalar Plucker fragment, with closed-form fixtures in test/game_exact.jl.