API reference

Acceleration

pydaarem.daarem(par, fixptfn, objfn=None, *args, control=None, **kwargs)

Accelerate a fixed-point iteration with DAAREM.

DAAREM is a damped Anderson acceleration scheme with periodic restarts and monotonicity control. It is intended as an off-the-shelf accelerator for smooth, monotone, slowly converging fixed-point iterations, including expectation-maximization (EM), minorization-maximization (MM), and related algorithms.

Parameters:
pararray, shape (n_parameters,)

Starting values for the parameter vector. par can be an array of any library that supports the Python array API standard, for example NumPy, PyTorch or CuPy. A list or a scalar is converted to a NumPy array. The computation uses the namespace and the device of par, with the float64 data type.

fixptfncallable

Fixed-point mapping G. The callable must accept the current parameter vector as its first argument and return a vector with the same length. It defines the iteration x[k + 1] = G(x[k]). For an EM algorithm, this function performs one E/M update.

objfncallable or None, optional

Scalar merit function L that is maximized at the fixed point of G. The callable must accept the parameter vector as its first argument and return a scalar. For an EM algorithm, this is typically the observed-data log-likelihood. Supplying objfn is optional but preferable because it enables monotonicity control. If None is passed, DAAREM uses the residual-norm acceptance rule from the R implementation’s no-objective path; value_objfn, objfevals, and objfn_track are returned as None, and residuals contains the recorded residual norms.

*args

Additional positional arguments passed to both fixptfn and objfn.

controldict, optional

Algorithm controls. The accepted keys are the R control names with each dot replaced by an underscore. No other keys are allowed.

maxiterint, default=2000

Maximum number of iterations or fixed-point evaluations, following the R implementation’s accounting for the selected algorithm path.

orderint, default=5

Order of the DAAREM acceleration scheme. Internally this is capped at ceil(len(par) / 2).

tolfloat, default=1e-8

Convergence tolerance. With convtype="param", iteration stops when ||G(x[k]) - x[k]|| < tol. With convtype="objfn", iteration stops when abs(L(x[k + 1]) - L(x[k])) < tol.

mon_tolfloat, default=0.01

Nonnegative tolerance for objective monotonicity. With an objective function, an accelerated proposal is rejected when L(x[k + 1]) < L(x[k]) - mon_tol.

cycl_mon_tolfloat, default=0.0

Nonnegative tolerance for the cycle-level monotonicity check at restart boundaries.

kappafloat, default=25

Half-life parameter controlling how quickly the relative damping factor approaches one.

alphafloat, default=1.2

Parameter greater than one controlling the initial relative damping factor and its rate of relaxation.

resid_tolfloat, default=0.95

Residual-change tolerance used when objfn is not supplied. A proposed accelerated step is accepted when its residual norm is at most the previous residual norm times 1 + resid_tol**k.

convtype{“param”, “objfn”}, default=”param”

Convergence criterion used when objfn is supplied.

intermedbool, default=False

If true, return intermediate iterates in p_intermed. With an objective function, the first column is the objective value and the remaining columns are parameters.

**kwargs

Additional keyword arguments passed to both fixptfn and objfn.

Returns:
dict

Dictionary with the keys of the R result, with each dot replaced by an underscore.

pararray

Final parameter vector.

fpevalsint

Number of fixed-point function evaluations or iterations, following the R implementation’s accounting.

value_objfnfloat or None

Objective function value at termination, or None when no objective function is supplied.

objfevalsint or None

Number of objective function evaluations, or None when no objective function is supplied.

convergencebool

True if the algorithm converged before reaching maxiter.

objfn_trackarray or None

Objective values recorded during iteration, or None when no objective function is supplied.

residualsarray, optional

Residual norms recorded during iteration. Returned only when objfn is not supplied.

p_intermedarray or None

Intermediate iterates when intermed is true, otherwise None.

The arrays have the namespace and the device of par, and the float64 data type.

Warns:
RuntimeWarning

If the algorithm reaches the iteration limit without convergence.

Notes

The public API and control names follow the R package daarem. Unknown control names and a convtype other than "param" or "objfn" raise ValueError. The R package also stops with an error in these cases.

fixptfn receives and must return an array of the namespace of par. pydaarem converts its output to float64 on the device of par. objfn must return a value that float() accepts, for example a Python float or a 0-dimensional array.

DAAREM decides each step from the values of the residual norm and the objective. These values are converted to Python floats, so each iteration copies a small number of scalars from the device to the host. For the same reason, pydaarem does not support tracing transformations such as jax.jit or torch.compile.

References

Henderson, N. C. and Varadhan, R. (2019). Damped Anderson acceleration with restarts and monotonicity control for accelerating EM and EM-like algorithms. Journal of Computational and Graphical Statistics, 28(4), 834-846. https://doi.org/10.1080/10618600.2019.1594835

Examples

>>> import numpy as np
>>> from pydaarem import daarem
>>> def fixpt(x):
...     return np.cos(x)
>>> out = daarem(np.array([1.0]), fixpt, control={"maxiter": 100})
>>> out["par"].shape
(1,)

Data sets

pydaarem.datasets.fetch_mixdata()

Download and load the mixture proportions example data.

The data comes from the mixem analysis in the stephenslab/daarem repository. The first call downloads the file and verifies its SHA-256 hash. Later calls use the local copy.

Returns:
Lndarray, shape (n_samples, n_components)

Conditional likelihood matrix. Row i contains the likelihood of sample i under each mixture component.

xndarray, shape (n_components,)

Mixture proportions of the reference solution. The upstream analysis computed this solution with the mixsqp package.

Examples

>>> from pydaarem.datasets import fetch_mixdata
>>> L, x = fetch_mixdata()
>>> L.shape
(100000, 10)