mbi.estimation.Estimator

class mbi.estimation.Estimator(*, marginal_oracle: MarginalOracle | None = None)[source]

Bases: ABC

An object that estimates a Model from a marginal-based loss function.

Subclasses implement _init, _step, and _finalize. The ABC provides a default estimate loop and a shared asynchronous precompile that works for any estimator with a jitted _step.

State convention: the first element of the state tuple returned by _init / _step is the current solution (passed to callback_fn). Override _callback_value only if the callback needs a transformation.

marginal_oracle

Callable for computing marginals from potentials. If None, auto-selected via default_oracle().

Type:: mbi.marginal_oracles.MarginalOracle | None

Examples of subclasses:

MirrorDescent
DualAveraging
InteriorGradient
extensions.MixtureOfProductsEstimator
extensions.ReweightedDatasetEstimator

Methods

`__init__`
`estimate`	Estimate a Model from noisy marginal measurements.
`precompile`	Warm up the JIT cache for `estimate` asynchronously.

Attributes

marginal_oracle

marginal_oracle: MarginalOracle | None = None

estimate(domain: Domain, loss_fn: MarginalLossFn | Sequence[LinearMeasurement], known_total: float | None = None, constraints: Sequence[Constraint] = (), iters: int = 1000, callback_fn: Callable | None = None, warm_start: Model | CliqueVector | None = None, tol: float | None = 0.001) → Model[source]

Estimate a Model from noisy marginal measurements.

If warm_start is provided, the estimator initializes from a previously estimated model instead of from scratch. For potential-based estimators the model’s potentials are expanded to cover any new cliques; for MixtureOfProducts the model is used directly.

If tol is set (default 1e-3), optimization stops early once the normalized primal-dual gap falls at or below tol. Pass tol=None to disable early stopping and run the full iters.

precompile(domain: Domain, measurements: Sequence[LinearMeasurement] | None = None, *, extra_cliques: Sequence[tuple[str | int, ...]] | None = None, constraints: Sequence[Constraint] = ()) → Future[source]

Warm up the JIT cache for estimate asynchronously.

Returns a Future that completes when compilation finishes. Callers may ignore the return value (fire-and-forget) or call future.result() to block until compilation is done.