Lenticulum.jl

Implicit machine learning on factor graphs: learning relations $R_\theta \subseteq X_1\times\cdots\times X_n$ rather than functions $f_\theta : X \to Y$.

Under development

Interfaces are not stable. Several packages document known gaps rather than hiding them; the per-package pages say what is missing.

The idea in one page

An ordinary neural network is a function. You feed it an input, you get an output, and the direction is fixed when you build the layer. Lenticulum's unit of computation is a factor: a relation among several named channels, with no distinguished input or output. Which channels are inputs is decided per call, and the same factor can be run in whichever direction the graph needs.

A diffusion model of points on a circle as a relation: its field (left) and three queries answered by one model (right)

Left: the field of a diffusion model of points on a circle; its stable roots are the relation. Right: "given $x$, find $y$" has two answers, "given $y$, find $x$" uses the same model the other way round, and a query just off the circle returns the nearest ridge point. The first tutorial builds exactly this picture.

# a Lux layer knows which side is the input
Dense(3 => 5)

# a factor does not — you tell it, when you use it
GaussianFactor(1 => 1; noise = Q, channels = (:x, :y))

Factors are wired into a factor graph — a bipartite graph of factors and variables — and inference is message passing rather than a forward pass. That is the whole design:

Lux.jlLenticulum.jl
unita layer: a functiona factor: a relation
directionfixed at constructionchosen per message
wiringa DAGany connected graph
running itone forward passscheduled messages until convergence
backward passa gradienta posterior belief

The packages

Five packages. Most users need Lenticulum (which brings the first three) or VariationalDiffusion.

packagewhat it gives you
LenticulumCorewhat a factor is: channels, polarities, beliefs, energies
Myceliuminference: graphs, messages, schedules, plates, cluster nodes, the free energy
MyceliumLearninglearning: free-energy gradients, expectation maximisation, the optimiser step
Lenticulumthe factors: linear-Gaussian, nonlinear, constraints, switching and regime factors, likelihoods
VariationalDiffusiona diffusion model as a relation (implicit inference, Laplace answers, sampling, RED-Diff, ProxDM)

Three more packages sit off those paths and have not yet been reviewed as the core was:

packagewhat it gives you
ImplicitLayersDEQs and neural ODEs as factors
AdversarialFactorsimplicit generative models: generators and density ratios
AlgebraicFactorsfinite toric models: exact discrete messages and free energy

Installation

In the MathStruct registry, next to General:

using Pkg
Pkg.Registry.add(RegistrySpec(url = "https://github.com/MathStruct/Registry.git"))   # once
Pkg.add("Lenticulum")             # Gaussian graphs, structure and regimes
Pkg.add("VariationalDiffusion")   # relation learners

A registered version is a snapshot and falls behind the development branch. For the newest code, use a clone:

Pkg.develop(path = "/path/to/Lenticulum.jl/lib/Lenticulum.jl")
Pkg.develop(path = "/path/to/Lenticulum.jl/lib/VariationalDiffusion.jl")   # and the others under lib/

Every package depends on LuxCore, not Lux, so wrapping a Lux model costs nothing and pulls in nothing. Neither Lux nor any automatic-differentiation package is a dependency of anything here.

Where to go next

Where the theory is

Not here. This repository is also an Obsidian vault, and the mathematics — the categorical foundations, the papers, the derivations, and an honest account of what does not work — lives there. It is rendered as a website, the front page of this one:

The theory vault →

See the Theory vault page for a map of it.

Per-file implementation notes sit next to the source they describe, as *.md beside *.jl, and are part of the vault too.

These docs describe the code. If a docstring below cites something in double brackets like [[Bethe Free Energy]], that is a link into the vault, not a broken link on this site.