Experimental Program API¶

mixle.experimental.program contains a move-based optimization-program API. It is kept for research workflows that do not fit the stable declarative surfaces yet. It is not the recommended first path for ordinary neural, probabilistic, or task modeling.

For new code, prefer:

mixle.stats and mixle.inference for explicit probabilistic models;
mixle.ppl for symbolic model expressions;
mixle.models for incubating neural leaves and applied model helpers;
mixle.task for task replacement, distillation, cascades, tool calling, and planning.

The compatibility module mixle.program re-exports the experimental program API so older imports continue to work.

Core Idea¶

The program API describes optimization as a set of moves:

minimize(objective, over=params): Minimize a closure over parameters.
maximize(objective, over=params): Maximize a closure over parameters.
em(estimator, data, init): Treat EM as a move.
alternate(move_a, move_b, ...): Alternate between moves.
weighted([(loss_a, weight_a), ...], over=params): Combine weighted objectives.
constrain(g, bound=0.0, kind="<="): Add a constraint to an optimization move.
reinforce(sample_and_reward): Construct a policy-gradient style objective.
fit(program, ...): Execute a move or program.

The surface can express useful research patterns, but it depends heavily on closures. That is why stable Mixle workflows favor declarative estimators, PPL expressions, and task solvers when possible.

Parameter Helpers¶

The module includes helpers for selecting and adapting trainable parameters:

trainable(module): Return trainable parameters from a module-like object.
freeze(module): Freeze a module’s parameters.
subset(module, *name_substrings): Select parameter subsets by name.
lora(module, rank=8, alpha=16.0): Add low-rank adaptation parameters to compatible linear modules.

These helpers are useful when experimenting with neural leaves or adaptation methods that are not yet expressed as stable Mixle model objects.

Examples¶

Minimize a Torch loss:

from mixle.experimental.program import fit, minimize, trainable

move = minimize(lambda: loss_fn(batch), over=trainable(net), lr=1.0e-3)
fit(move, steps=200)

Alternate EM with a neural move:

from mixle.experimental.program import alternate, em, fit, minimize, trainable

program = alternate(
    em(estimator, rows, init=model0),
    minimize(lambda: neural_loss(rows), over=trainable(net)),
)

fit(program, steps=20)

Adapt a module with LoRA-style parameters:

from mixle.experimental.program import fit, lora, minimize

params = lora(module, rank=4)
fit(minimize(lambda: adaptation_loss(batch), over=params), steps=100)

Advanced Moves¶

The module also contains experimental support for:

Stream and ReplayBuffer: Streaming data and replay workflows.
snapshot / replay / distill / ewc / fisher_diagonal: Continual-learning and distillation-style objectives.
bilevel: Bilevel optimization experiments.
pareto: Multi-objective optimization with Pareto-style moves.
streaming_em: EM over a stream abstraction.
gail and maxent_irl: Imitation-learning and inverse-reinforcement-learning experiments.

Status And Stability¶

This API is explicitly experimental:

names and call signatures may change;
behavior may move into mixle.ppl, mixle.task, or a more mature mixle.models surface;
examples should be treated as research scaffolding, not deployment guidance;
production artifacts should prefer stable estimator and inference interfaces whenever possible.

Use this surface when the optimization problem is genuinely program-shaped. Use the stable APIs when the goal is to fit, score, calibrate, explain, or operate a model.