Prepare v0.9.0 (#204)

thopkins32 · web-flow · commit 76e2ecaa6539 · 2025-12-08T15:27:03.000-05:00
* Deprecate a whole bunch more

* Update for v0.9.0
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,11 +1,13 @@
 
 .. warning::
 
-    **Important Notice for upcoming v1.0.0 release**
+    **Important notice for the upcoming v1.0.0 release**
 
-    Major changes are expected in the v1.0.0 release of Blop. We are removing the older way of using agents and performing optimization in favor of using the Ax agent backend. The legacy agent interface will be deprecated, and users are encouraged to migrate to the new `blop.ax.Agent` interface for all optimization workflows. Please refer to the :doc:`tutorials`, :doc:`how-to-guides`, and :doc:`explanation` sections for the new interface.
+    Major changes are coming in the v1.0.0 release of Blop. We are removing the older way of using agents and performing optimization in favor of using `Ax <https://ax.dev>`_ as the backend for optimization and experiment tracking. The legacy agent interface is now deprecated, and users are encouraged to migrate to the new `blop.ax.Agent` interface for all optimization workflows. Please refer to the :doc:`tutorials`, :doc:`how-to-guides`, and :doc:`explanation` sections for the new interface.
+
+    Furthermore, Blop is moving to a more modular architecture. The core architecture is now protocol-based, allowing users to plug in their own optimization backends, acquisition plans, and evaluation functions.
     
-    Ax will be the primary backend for optimization and experiment tracking. We will also be adding support for the `gest-api <https://github.com/campa-consortium/gest-api>`_ standard with integration into Ax experiment tracking.
+    Ax will have first-class support as the default backend for optimization and experiment tracking.
 
 
 What is Blop?
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
@@ -9,4 +9,5 @@ API Reference
     reference/dof-constraint.rst
     reference/objective.rst
     reference/outcome-constraint.rst
+    reference/plans.rst
     reference/protocols.rst
diff --git a/docs/source/reference/plans.rst b/docs/source/reference/plans.rst
@@ -0,0 +1,8 @@
+Plans
+=====
+
+.. autofunction:: blop.plans.optimize
+
+.. autofunction:: blop.plans.optimize_step
+
+.. autofunction:: blop.plans.default_acquire
diff --git a/docs/source/reference/protocols.rst b/docs/source/reference/protocols.rst
@@ -10,7 +10,6 @@ AcquisitionPlan
    :show-inheritance:
    :inherited-members:
    :special-members: __call__
-   :no-index:
 
 EvaluationFunction
 ------------------
@@ -29,7 +28,6 @@ Optimizer
    :undoc-members:
    :show-inheritance:
    :inherited-members:
-   :no-index:
 
 OptimizationProblem
 -------------------
@@ -39,4 +37,3 @@ OptimizationProblem
    :undoc-members:
    :show-inheritance:
    :inherited-members:
-   :no-index:
diff --git a/docs/source/release-history.rst b/docs/source/release-history.rst
@@ -2,6 +2,31 @@
 Release History
 ===============
 
+v0.9.0 (2025-12-08)
+-------------------
+
+What's Changed
+..............
+* Protocols for optimization with Bluesky by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/185
+* Evaluation functions by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/186
+* Standard plans for optimization that work with protocols by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/187
+* Refactor Ax agent to use new protocols by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/188
+* Remove default evaluation options by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/189
+* Direct AxOptimizer protocol impelementation by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/191
+* Remove unused Ax helpers by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/193
+* Simplified DOF classes for Ax backend by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/195
+* Simpler Objective class, ScalarizedObjective, and OutcomeConstraints by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/196
+* Protocol explanation by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/192
+* New DOFConstraint class and Agent update by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/198
+* Agent composition over inheritance by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/199
+* Add how-to-guide for outcome constraints by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/200
+* Extensive updates to reference docs by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/201
+* Change furo theme -> pydata-sphinx-theme by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/202
+* Update docstrings with much more detail by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/203
+
+
+`Full Changelog <https://github.com/NSLS-II/blop/compare/v0.8.1...v0.9.0>`__
+
 v0.8.1 (2025-11-06)
 -------------------
 
@@ -78,16 +103,16 @@ What's Changed
 * Fix documentation CI error by `@jennmald <https://github.com/jennmald>`_ in https://github.com/NSLS-II/blop/pull/84
 * Fix fitness and constraint plots by `@jennmald <https://github.com/jennmald>`_ in https://github.com/NSLS-II/blop/pull/80
 * Refactor: Make agent default compatible with Bluesky Adaptive by `@maffettone <https://github.com/maffettone>`_ in https://github.com/NSLS-II/blop/pull/86
-* Ruff linter support; Removal of black, flake8, and isort by `@thomashopkins32 <https://github.com/thomashopkins32>`_ in https://github.com/NSLS-II/blop/pull/95
-* Add type hints by `@thomashopkins32 <https://github.com/thomashopkins32>`_ in https://github.com/NSLS-II/blop/pull/87
-* Remove Python 3.9 support by `@thomashopkins32 <https://github.com/thomashopkins32>`_ in https://github.com/NSLS-II/blop/pull/101
+* Ruff linter support; Removal of black, flake8, and isort by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/95
+* Add type hints by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/87
+* Remove Python 3.9 support by `@thopkins32 <https://github.com/thopkins32>`_ in https://github.com/NSLS-II/blop/pull/101
 * Add XRT demo to blop tutorials by `@jennmald <https://github.com/jennmald>`_ in https://github.com/NSLS-II/blop/pull/102
 
 New Contributors
 ................
 * `@jennmald <https://github.com/jennmald>`_ made their first contribution in https://github.com/NSLS-II/blop/pull/84
 * `@maffettone <https://github.com/maffettone>`_ made their first contribution in https://github.com/NSLS-II/blop/pull/86
-* `@thomashopkins32 <https://github.com/thomashopkins32>`_ made their first contribution in https://github.com/NSLS-II/blop/pull/95
+* `@thopkins32 <https://github.com/thopkins32>`_ made their first contribution in https://github.com/NSLS-II/blop/pull/95
 
 `Full Changelog <https://github.com/NSLS-II/blop/compare/v0.7.2...v0.7.3>`__
 
diff --git a/examples/benchmark.py b/examples/benchmark.py
diff --git a/examples/prepare_bluesky.py b/examples/prepare_bluesky.py
diff --git a/examples/prepare_chx_shadow.py b/examples/prepare_chx_shadow.py
diff --git a/examples/prepare_tes_shadow.py b/examples/prepare_tes_shadow.py
diff --git a/examples/prepare_tes_srw.py b/examples/prepare_tes_srw.py
diff --git a/pixi.toml b/pixi.toml
@@ -3,7 +3,7 @@ authors = ["jessica-moylan <jessicamoylan10@gmail.com>", "Thomas Hopkins <thopki
 channels = ["conda-forge", "pytorch"]
 name = "blop"
 platforms = ["linux-64"]
-version = "0.8.1"
+version = "0.9.0"
 
 [dependencies]
 python = ">=3.10.0,<3.13"
diff --git a/src/blop/data_access.py b/src/blop/data_access.py
@@ -1,10 +1,18 @@
+import warnings
 from abc import ABC, abstractmethod
 from typing import Any
 
 import numpy as np
 import pandas as pd
 import xarray as xr
 
+warnings.warn(
+    "The data_access module is deprecated and will be removed in Blop v1.0.0. "
+    "Data access should be done within your custom ``blop.protocols.EvaluationFunction``.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 
 class DataAccess(ABC):
     @abstractmethod
diff --git a/src/blop/de/__init__.py b/src/blop/de/__init__.py
@@ -0,0 +1,3 @@
+import warnings
+
+warnings.warn("The de module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2)
diff --git a/src/blop/digestion/__init__.py b/src/blop/digestion/__init__.py
@@ -1,7 +1,11 @@
+import warnings
+
 import pandas as pd
 
 from ..utils import get_beam_stats
 
+warnings.warn("The digestion module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2)
+
 
 def default_digestion_function(df: pd.DataFrame) -> pd.DataFrame:
     return df
diff --git a/src/blop/digestion/tests.py b/src/blop/digestion/tests.py
@@ -1,9 +1,14 @@
+import warnings
 from typing import Any
 
 import numpy as np
 
 from ..utils import functions
 
+warnings.warn(
+    "The digestion.tests module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2
+)
+
 
 def himmelblau_digestion(df: dict[str, Any]) -> dict[str, Any]:
     """
diff --git a/src/blop/digestion_function.py b/src/blop/digestion_function.py
@@ -1,9 +1,17 @@
+import warnings
 from typing import Any
 
 from ax.api.types import TOutcome
 
 from .objectives import Objective
 
+warnings.warn(
+    "The digestion_function module is deprecated and will be removed in Blop v1.0.0. "
+    "See `blop.protocols.EvaluationFunction` as an alternative.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 
 def default_digestion_function(
     trial_index: int,
diff --git a/src/blop/dofs.py b/src/blop/dofs.py
@@ -57,6 +57,9 @@ def __init__(
     ):
         """A degree of freedom (DOF), to be used by an agent.
 
+        .. deprecated:: v0.9.0
+            This class is deprecated and will be removed in Blop v1.0.0. Use ``blop.ax.DOF`` instead.
+
         Parameters
         ----------
         name: str
diff --git a/src/blop/objectives.py b/src/blop/objectives.py
@@ -74,6 +74,9 @@ def __init__(
     ) -> None:
         """An objective to be used by an agent.
 
+        .. deprecated:: v0.9.0
+            This class is deprecated and will be removed in Blop v1.0.0. Use ``blop.ax.Objective`` instead.
+
         Parameters
         ----------
         name: str
diff --git a/src/blop/plotting.py b/src/blop/plotting.py
@@ -1,3 +1,5 @@
+import warnings
+
 import matplotlib as mpl
 import numpy as np
 import torch
@@ -13,6 +15,8 @@
 
 MAX_TEST_INPUTS = 2**11
 
+warnings.warn("The plotting module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2)
+
 
 def _plot_objs_one_dof(agent, size=16, lw=1e0):
     fitness_objs = agent.objectives(fitness=True)
diff --git a/src/blop/utils/__init__.py b/src/blop/utils/__init__.py
@@ -1,3 +1,5 @@
+import warnings
+
 import botorch  # type: ignore[import-untyped]
 import numpy as np
 import scipy as sp  # type: ignore[import-untyped]
@@ -6,6 +8,8 @@
 
 from . import functions  # noqa
 
+warnings.warn("The utils module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2)
+
 
 def get_beam_stats(image: np.ndarray, threshold: float = 0.5) -> dict[str, float | np.ndarray]:
     ny, nx = image.shape
diff --git a/src/blop/utils/functions.py b/src/blop/utils/functions.py
@@ -1,6 +1,10 @@
+import warnings
+
 import numpy as np
 import torch
 
+warnings.warn("The functions module is deprecated and will be removed in Blop v1.0.0.", DeprecationWarning, stacklevel=2)
+
 
 def approximate_erf(x):
     """
diff --git a/src/blop/utils/sets.py b/src/blop/utils/sets.py
