implementation

AlgebraicFactors starts the algebraic family with exact finite toric potentials. It supplies discrete messages, energies and entropies, moment fitting and model checks, Grassmannian parameter geometry and retracted updates, and forward Plücker transport. Polynomial basis tables, residuals and complete-data fitting are implemented; single-branch Gaussian messages and optional square-system homotopy mixtures are implemented.

Sources: original implementation of L-SPEC-004 Algebraic Factors Toric and Grassmannian §0, §1.1–§1.7, §2.1–§2.3, §3(a,b), §4 and §5; code: AlgebraicFactors.jl, toric.jl, fit.jl, grassmann.jl, plucker.jl, veronese.jl, polynomial.jl, polyfit.jl, ../test/runtests.jl, ../test/polynomial.jl, homotopy.jl, ../ext/AlgebraicFactorsHomotopyContinuationExt.jl, ../test/homotopy.jl.

Theory (CT-ML wiki): Statistical Game · Bayesian Lens

The module depends on LenticulumCore, Mycelium, LinearAlgebra, LuxCore and Random. The last two implement the repository’s parameter/state interface; they add no inference algorithm. Newton and binary-feature IPF use only LinearAlgebra; there is no external optimiser, LP solver, AD backend or manifold package.

ToricFactor supplies the finite potentials. independence and hierarchical return integer design matrices so callers can inspect the statistics before constructing a factor. toric records the state ordering, label rules and free-energy accounting. fit describes fit_mle, inmodel and binomial_residuals, their independent closed-form checks, and the separate moment-convergence and MLE-existence statuses.

The package test environment follows AdversarialFactors’s workspace layout. Tests include the repository’s lib/LenticulumCore.jl/test/support/factor_conformance.jl through its direct-message path, with independent site and pooled-posterior fixtures for every supported polarity of the test factors. The CI matrix and API documentation include this package separately from the top-level Lenticulum package.

The main integration difficulty was the difference between an extrinsic site and a posterior: graph messages exclude the target prior, whereas pooling multiplies it back in. The core lens contract also asks for a joint latent posterior, which these marginal sites do not expose; the conformance checker has a separate path for direct-message factors, retaining its existing lens checks by default. Another was entropy counting: Mycelium already supplies the variable correction. Neither operation belongs in the outgoing site itself.

grassmann describes Grassmann, project_tangent, retract, ispoint and Retracted. The latter wraps Mycelium’s gradient descent and momentum without changing its state layout or recurrence. Projection and QR use only LinearAlgebra; sampling uses Random. The geometry tests compare descent on a trace objective with a known eigenplane and drive the same iterates through OptimiserFactor. No Mycelium changes or new dependencies are required.

plucker records the coordinate order, sparse relation tables and forward-only PluckerFactor. Dirac and paired-particle transport are exact. Independent Gaussian inputs give exact moments and a Gaussian approximation to the output law. plucker_moments exposes singular covariances; messages reject those unless callers explicitly request covariance jitter, since the core belief type needs positive-definite covariance. Conditional Dirac-input game quantities are scalar zero; the common checker runs its direct-message path on that forward point game (2026-10-26). No assembled lens, inverse fibre belief or distributional entropy is supplied. Other tests check direct messages and a Mycelium DAG. The Klein test now uses the real nullspace-fitting API in both polynomial bases.

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. energy 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; see homotopy.

Not implemented: general MLE existence certification, Markov-basis computation, parameter homotopy, positive-dimensional polynomial solves or inverse Plücker fibres.

ExponentTable, veronese, veronese_jacobian and basis_change implement monomial and Chebyshev tables (veronese). 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. No game free energy or entropy is provided (LP-009), so the full conformance checker does not apply. 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, numerical_rank, nullity and threshold. No centring, normalisation or column scaling is performed. fit_sampson minimises the summed half squared Sampson cost with the full analytic gradient, horizontal projection, QR retraction and exchangeable AbstractSampsonMethod instances. RiemannianGradient() is Armijo descent; FNS() is the corrected published one-equation update; the default RiemannianTrustRegion() uses truncated CG with the exact Riemannian Hessian, including the Grassmann curvature term. :riemannian, :fns and :trust_region alias default instances. Implement AlgebraicFactors.sampson_solve(method, problem::SampsonProblem, Θ0;tol,maxiter) to plug in a method: problem.manifold, problem.cost_gradient(Θ) (Euclidean gradient), problem.hessian_vector(Θ,ξ), project_tangent and retract supply the objective and geometry. All stop at the horizontal Frobenius gradient norm, and return Θ,cost,gradient_norm,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; polyfit records the method comparison and its limits. 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.