Changelog¶

This package uses a variant of Semantic Versioning that makes additional promises during the initial development (major version 0): whenever breaking changes to the public API are published, the first non-zero version number will increase. This means that code that uses COI version 0.9.0 will continue to work with version 0.9.1, but may break with version 0.10.0.

Unreleased¶

No changes yet!

v0.9¶

v0.9.4¶

Bug fixes¶

cernml.coi.check() now reports for SingleOptimizable and FunctionOptimizable the values of parameters that are out of range of their respective optimization space

Other changes¶

The package is now tested on NumPy 2.0 and Matplotlib 3.10.
the Quickstart document has been expanded and more links have been added to guide newcomers.

v0.9.3¶

Bug fixes¶

Fix the type guard is_configurable() erroneously requiring the object to have the unwrapped property.

v0.9.2¶

Bug fixes¶

Fix superfluous warnings in cernml.coi.checkers.check_problem() when looking for deprecated attributes.
The function cernml.coi.check() now loads all plugins first before executing them. It also logs faulty plugins, but otherwise ignores them. This should catch bugs quicker.
Restrict Gymnasium to versions below v1.0 until our compatibility story is figured out.

v0.9.1¶

Bug fixes¶

Relax dependencies to allow use of NumPy 2.0
Fix bug in which building the docs would fail due to double slashes in the URLs of other package documentations.

v0.9.0¶

Breaking changes¶

Require Python 3.9.
Switched dependency from Gym 0.21 to Gymnasium.
Update NumPy requirement from 1.0 to 1.22.
Update optional Matplotlib requirement from 3.0 to 3.8.
Update optional cernml-coi-optimizers requirement from 1.1 to 2.0.
Update built-time setuptools-scm requirement from 7.0 to 8.
Update importlib-metadata from < 7 to >= 4.8.
Add dependency on typing-extensions >= 4.3.
The metadata key "render.modes" has been renamed to "render_modes". Its meaning has not changed.
New rendering API: Problem.render() now longer accepts the arguments render_mode. This argument is now instead passed to Problem.__init__(), which automatically sets the new property Problem.render_mode. In rendering mode "human", problems are now expected to call render() automatically at every iteration.
SingleOptimizable.get_initial_params(), FunctionOptimizable.get_initial_params() and Env.reset() now accept new arguments seed and options. The latter is ignored by default, the former is used to seed the new property Problem.np_random.
The convention around the return value of get_initial_params() has been clarified. Unless and until a new API has been worked out, its return value must now be accepted by compute_single_objective() and compute_function_objective() even if its out-of-bounds.
The Core Classes of This Package have been completely rewritten. Instance and subclass checks are now based on the Protocol implementation from Python 3.12. Dynamically set attributes may no longer be found and checks now also consider whether an attribute is a data member, a method or a class method.
The entry point used by the Problem Checkers has been renamed from cernml.coi.checkers to cernml.checkers.
The attributes SingleOptimizable.objective_range and FunctionOptimizable.objective_range have been removed in anticipation of the planned removal of gymnasium.Env.reward_range in Gymnasium 1.0.

Additions¶

Support for Python 3.10 through 3.12.
New extra robotics, which adds a dependency on Gymnasium-Robotics 1.0 and sources GoalEnv from there.
If Gymnasium-Robotics isn’t installed, we provide our own implementation of cernml.coi.GoalEnv.
New entry point cernml.envs through which problems can be registered.
The warn parameter of the Problem Checkers now is an integer instead of a bool. The meaning stays largely the same. Values greater than 2 now represent the stacklevel parameter passed to warnings.warn() to adjust the reported code location when a warning is issued. Internally, the checkers adjust warn so that warnings are never reported within the Problem Checkers package itself.
A large family of Typeguards to require that an instance or class implement a specific interface.
The Core Classes of This Package are now all context managers; entering their context does nothing, leaving it calls Problem.close().
The method Problem.get_wrapper_attr().

Bug fixes¶

For FunctionOptimizable, the type of the constraints attribute has been changed from List to Sequence. It has also been marked as a typing.ClassVar and the default value has been changed from the empty list [] to the empty tuple (). The same has been done in SingleOptimizable for its attributes param_names, constraints, and constraint_names This prevents bugs where the default values are modified on accident. A similar strategy has long been used for the metadata attribute.

Other changes¶

The Problem Registry has been rewritten from scratch. It still largely follows the Gymnasium implementation and should be backwards-compatible, but minor details may have changed inadvertently.

v0.8¶

v0.8.16¶

Additions¶

CustomPolicyProvider and a user guide section about it.

v0.8.15¶

CustomOptimizerProvider and a user guide section about it.
A user guide section on the Configurable API.

v0.8.14¶

Additions¶

Config.add() now has a different default value for the type parameter in cases where value is a bool or numpy.bool_. The new value treats most inputs as before, but specifically the string "False" is converted to the boolean False of the correct type. This ensures that bools roundtrip through string conversion and makes config handling in host applications less error-prone.

Bug fixes¶

The Problem Checkers now run their isinstance() checks on the unwrapped optimization problem instead of the problem itself. This solves a bug where a SingleOptimizable inside a Wrapper is mistaken for an Env.
Add missing argument order_enforce to register() for compatibility with the equivalent Gym function.

v0.8.13¶

Bug fixes¶

Add compatibility with importlib-metadata 5 and 6 if we’re on Python 3.8+. On Python 3.7 (Acc-Py 2020.11), we are still forced to use importlib-metadata 4.

v0.8.12¶

Bug fixes¶

Bad CI configuration that prevented the package from being released.

v0.8.11¶

Bug fixes¶

Bad CI configuration that prevented docs from being built.

v0.8.10¶

Bug fixes¶

Improve cross-linking in the docs.
Update packaging tutorial to latest version of tools.
General small rewrite of the docs.

Other changes¶

Documentation previously written in Markdown is now consistently written in ReST.
Open-source this package by adding the appropriate license notices.

v0.8.9¶

Additions¶

override_skeleton_points() for optimization problems that need to customize the way skeleton points are selected by the user.

Other changes¶

The online docs are now built with Python 3.9. Consequently, type annotations like Union[str, List[str]] and Optional[str] now use the new type union syntax added in Python 3.10, and so look like str | List[str] and str | None respectively.

v0.8.8¶

Bug fixes¶

Improve various cross-references in the docs.

Other changes¶

The project’s Gitlab group has been renamed from be-op-ml-optimization to geoff. This also changes the URL of these docs inside CERN. Please adjust your links, bookmarks and Git clones.

v0.8.7¶

Additions¶

Support for Python 3.9 has been added.

Bug fixes¶

Do not require Matplotlib/PyJapc to build documentation
Drop the install extra “pyjapc”.

Other changes¶

Bump build dependencies.
Switch project layout to src-based and migrate almost all configs to pyproject.toml.

v0.8.6¶

Additions¶

Config.get_field_values() for convenience.

v0.8.5¶

Additions¶

Variants AD and ELENA to enum Machine.

v0.8.4¶

Bug fixes¶

Change syntax highlighter for shell sessions in docs from bash to shell-session.

Other changes¶

Upgrade CI templates to v2.
Use Gitlab Releases and Gitlab badges.
Add key project_urls to setup.cfg.

v0.8.3¶

Additions¶

Add install extra doc_only to build docs in a non-CERN environment. (This skips the PyJapc dependency.)

Bug fixes¶

Restrict Gym compatibility, as Gym v0.22 removes GoalEnv.
v0.8.0 nominally increased the minimum required version of importlib-metadata, but this was never enforced. Now, at least version 3.6 is required.

v0.8.2¶

Additions¶

New optional attributes objective_name, param_names and constraint_names to SingleOptimizable.

Bug fixes¶

Adjust the documentation of get_objective_function_name() and get_param_function_names() to be in line with its SingleOptimizable counter-parts.

v0.8.1¶

Additions¶

Config.extend() to make configuration more composable.
ConfigValues as a convenience alias for types.SimpleNamespace.
check_configurable() for all implementors of the Configurable interface.

Bug fixes¶

Broken links in the API docs of the Problem Checkers.

v0.8.0¶

Breaking changes¶

Drop Python 3.6 support.
Require importlib-metadata 3.6 (was 3.4).
Drop the __version__ attribute. To query the COI version, use instead importlib_metadata. (With Python 3.8+, this is in the standard library as importlib.metadata.)
Remove PascalPase-style members of Machine. Use the SCREAMING_SNAKE_CASE-style members intead.
Remove unstable.japc_utils. It is now provided by cernml-coi-utils as cernml.japc_utils.
Remove unstable.renderer and mpl_utils. Both are now provided by cernml-coi-utils’s cernml.mpl_utils.
Remove unstable.cancellation. The module is now available as cernml.coi.cancellation.
Remove unstable. The module is now empty.
Change Field from a NamedTuple into a dataclass().

Additions¶

Support for importlib-metadata 4.

v0.7¶

v0.7.6¶

Bug fixes¶

Backport change from v0.8.x that removes iter_matplotlib_figures() calls from check(). This avoids deprecation warnings introduced in the previous version.

v0.7.5¶

Bug fixes¶

Increase the stacklevel of the v0.7.4 deprecation warnings so that they appear more reliably.

v0.7.4¶

Additions¶

Merge FunctionOptimizable and check_function_optimizable() from cernml-coi-funcs v0.2.2.
Deprecate unstable.japc_utils, renderer and mpl_utils. The same features are provided by the cernml-coi-utils package.
Stabilize the cernml.coi.cancellation module. It is now available under cancellation. The old location at unstable.cancellation remains available but is deprecated.

Bug fixes¶

Correct the type annotation on get_initial_params() from Any to ndarray.

v0.7.3¶

Additions¶

Split the COI tutorial into a tutorial on packaging and a tutorial on the COI proper.

Bug fixes¶

Improve the documentation of Env and other Gym classes.

Other changes¶

Upgraded docs. Switch markdown parser from Recommonmark to Myst. Change theme from Read the Docs to Sphinxdoc.
Changes to the CI pipeline. Version of code checkers are pinned now. Added Pycodestyle to the list of checkers to run.

v0.7.2¶

Additions¶

ParamStream.next_if_ready() no longer checks stream’s the cancellation token.
ParamStream.parameter_name and ParamGroupStream.parameter_names.

Bug fixes¶

repr() of ParamGroupStream called wrong Java API.

v0.7.1¶

Additions¶

Enum member Machine.ISOLDE.

v0.7.0¶

Breaking changes¶

Remove Cancellation tokens. The stable API did not accommodate all required use cases and could not be fixed in a backwards-compatible manner.

Additions¶

Re-add Cancellation tokens as an unstable module. The new API supports cancellation completion and resets.

v0.6¶

v0.6.2¶

Additions¶

Rename all variants of Machine to SCREAMING_SNAKE_CASE. The PascalCase names remain available, but issue a deprecation warning.
Cancellation tokens.
Cancellation support to parameter streams.
Property locked to parameter streams.
Document parameter streams.
Document plugin support in check().

Bug fixes¶

Add default values for all known metadata keys.
Missing figure.show() when calling SimpleRenderer.update("human").

v0.6.1¶

Additions¶

title parameter to SimpleRenderer.from_generator().

Bug fixes¶

Missing figure.draw() when calling SimpleRenderer.update("human").

v0.6.0¶

Breaking changes¶

Instate a variant of semantic versioning.
Move the Matplotlib utilities into mpl_utils.

Additions¶

unstable.renderer.
unstable.japc_utils.
Allow a single Figure as return value of render("matplotlib_figure").

v0.5¶

v0.5.0¶

Breaking changes¶

Add Problem.close().

v0.4¶

v0.4.7¶

Bug fixes¶

Typo in metadata key "cern.machine".
Mark metadata as a class variable.
Make base metadata a MappingProxyType to prevent accidental mutation.

v0.4.6¶

Breaking changes¶

Remove keyword arguments from the signature of render().

Additions¶

Start distributing wheels.

v0.4.5¶

Additions¶

Plugin entry point and logging to check().

v0.4.4¶

Additions¶

Export some (for now) undocumented helper functions from checkers.

v0.4.3¶

Breaking changes¶

Switch to setuptools-scm for versioning.

Additions¶

Unmark render() as an abstract method.

v0.4.2¶

Additions¶

Make dependency on Matplotlib optional.

Bug fixes¶

Add missing check for defined render modes to check().

v0.4.1¶

Bug fixes¶

Expose check() argument headless.

v0.4.0¶

Breaking changes¶

Mark the package as fully type-annotated.
Switch to pyproject.toml and setup.cfg based building.
Rewrite check_env() as check().

Additions¶

mpl_utils.iter_matplotlib_figures().

v0.3¶

v0.3.3¶

Bug fixes¶

Set window title in example configurable.py.

v0.3.2¶

Additions¶

help argument to Config.add().

v0.3.1¶

Breaking changes¶

Make all submodules private.

Additions¶

Configurable interface.

v0.3.0¶

Breaking changes¶

Rename Optimizable to SingleOptimizable.
Add dependency on Numpy.

Additions¶

Problem interface.
Environment registry.

Bug fixes¶

Check inheritance of env.unwrapped in check_env().

v0.2¶

v0.2.1¶

Bug fixes¶

Fix broken CI tests.

v0.2.0¶

Breaking changes¶

Rename package from cernml.abc to cernml.coi (And the distribution from cernml-abc to cernml-coi).
Rename OptimizeMixin to Optimizable.
Add metadata key "cern.machine".
Add more restrictions to env_checker().

Additions¶

Virtual inheritance: Any class that implements the required methods of our interfaces automatically subclass them, even if they are not direct bases.