MICE Documentation
==================

MICE (Multi-Iteration stochastiC Estimator) is a gradient estimator for
stochastic optimization that uses successive control variates along the
optimization path to reduce variance. By adaptively selecting which iterates
to include in its index set and optimally distributing samples, MICE achieves
accurate mean gradient estimation at minimal computational cost.

The method is described in the paper `Multi-iteration Stochastic Optimizers
<https://link.springer.com/article/10.1007/s00245-026-10451-x>`_
(*Applied Mathematics & Optimization*, Vol. 93, Article 93, 2026).

Key Features
------------

- **Adaptive variance reduction**: Controls relative L\ :sup:`2` error with
  user-specified tolerance ε
- **Efficient sample allocation**: Minimizes gradient sampling cost subject to
  error constraints
- **Index-set operators**: Add, Drop, Restart, and Clip operations for optimal
  hierarchy management
- **Flexible integration**: Non-intrusive design couples seamlessly with SGD,
  Adam, and other optimizers
- **Dual problem support**: Handles both expectation minimization and
  finite-sum problems
- **Robust stopping**: Resampling-based gradient norm estimation for stable
  termination criteria

Quick Install
-------------

.. code-block:: bash

   pip install mice

See the :doc:`installation` page for development installs and optional
dependencies.

Quick Start
-----------

.. code-block:: python

   import numpy as np
   from mice import MICE
   from mice.policy import DropRestartClipPolicy

   def gradient(x, thetas):
       return x - thetas

   def sampler(n):
       return np.random.randn(n, 1)

   estimator = MICE(
       grad=gradient,
       sampler=sampler,
       eps=0.577,
       min_batch=10,
       policy=DropRestartClipPolicy(
           drop_param=0.5,
           restart_param=0.0,
           max_hierarchy_size=100,
       ),
       max_cost=10_000,
       stop_crit_norm=1e-6,
   )

   x = np.array([10.0])
   for _ in range(100):
       g = estimator(x)
       if estimator.terminate:
           break
       x = x - 0.1 * g

See the :doc:`quickstart` guide for detailed examples including finite-sum
problems and policy configuration.

Getting Help
------------

- :doc:`theory` — Theoretical background and key concepts
- :doc:`api/index` — Complete module and class reference
- :doc:`citation` — How to cite MICE in your research

.. toctree::
   :maxdepth: 2
   :caption: Contents
   :hidden:

   installation
   quickstart
   theory
   api/index
   citation
   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`