Quickstart

Start a Python project. In your manifest file, add a dependency on the COI. Make sure to pick a COI version that is supported by the application that will optimize your problem:

pyproject.toml

[build-system]
requires = ['setuptools']
build-backend = 'setuptools.build_meta'

[project]
name = 'my-project'
version = '1.0'
dependencies = [
    'cernml-coi >= 0.9.0',
]

setup.cfg

[metadata]
name = my-project
version = 1.0

[options]
install_requires =
    cernml-coi >= 0.9.0

setup.py

from setuptools import setup

setup(
    name='my-project',
    version='1.0',
    install_requires=[
        'cernml-coi >= 0.9.0',
    ],
)

Now consider the following optimization problem: It is defined by an objective function and an initial point:

my_project/__init__.py

import numpy as np

def objective_function(x):
    goal = np.array([0.123, -0.456])
    return np.linalg.norm(x - goal)

x0 = np.zeros(2)

Now, write a class that implements multiple of the optimization interfaces, specifically interfaces for single-objective numerical optimization and reinforcement learning.

my_project/__init__.py

import gymnasium as gym
import numpy as np
from cernml import coi

class Parabola(coi.SingleOptimizable, gym.Env):
    metadata = {
        "render_modes": [],
        "cern.machine": coi.Machine.NO_MACHINE,
    }

    # Obervations for RL are 2D vectors in the box from -2 to +2.
    observation_space = gym.spaces.Box(-2.0, 2.0, shape=(2,))

    # RL agents may make steps that are 2D vectors from -1 to +1.
    action_space = gym.spaces.Box(-1.0, 1.0, shape=(2,))

    # Numerical optimization searches within a 2D box from -2 to +2.
    optimization_space = gym.spaces.Box(-2.0, 2.0, shape=(2,))

    def __init__(self, render_mode=None):
        super().__init__(render_mode)
        self.pos = x0.copy()

    # Single-objective optimization methods:

    def get_initial_params(self, *, seed=None, options=None):
        super().reset(seed=seed, options=options)
        self.pos = x0.copy()
        return self.pos.copy()

    def compute_single_objective(self, params):
        # Force parameters into observable space.
        space = self.optimization_space
        self.pos = np.clip(params, space.low, space.high)
        return objective_function(self.pos)

    # Reinforcement learning methods:

    def reset(self, *, seed=None, options=None):
        super().reset(seed=seed, options=options)
        self.pos = x0.copy()
        obs = self.pos.copy()
        info = {}
        return obs, info

    def step(self, action):
        space = self.observation_space
        self.pos = np.clip(self.pos + action, space.low, space.high)
        obs = self.pos.copy()
        reward = -objective_function(self.pos)
        terminated = (reward > -0.05)
        truncated = next_pos not in ob_space
        info = {}
        return obs, reward, terminated, truncated, info

coi.register("Parabola-v0", entry_point=Parabola, max_episode_steps=10)

Do take note of that last statement, which registers your class whenever your package is imported.

We still need to declare how to find our class. We put the entry point cernml.envs into our manifest file for this:

pyproject.toml

[project.entry-points.'cernml.envs']
my-project = 'my_project'

setup.cfg

[entry_points]
cernml.envs =
    my-project = my_project

setup.py

from setuptools import setup

setup(
    name='my-project',
    version='1.0',
    install_requires=[
        'cernml-coi >= 0.9.0',
    ],
    entry_points={
        'cernml.envs': [
            'my-project = my_project',
        ],
    }
)

Any host application (e.g. Geoff) may now instantiate your optimization problem by passing both the namespace of your entry point and the environment ID of the register call. If you don’t have a proper application available, the package :doc:` cernml-coi-optimizers <optimizers:index>` provides a simple optimization loop:

solve_parabola.py

from cernml import coi, optimizers

# Imports happens automatically behind the scene!
env = coi.make("my-project/Parabola-v0")
opt = optimizers.make("BOBYQA")

# Uses the BOBYQA algorithm to solve our quadratic problem.
optimizers.solve(opt, env)

See also

Example of Using Both Optimization and RL

A more fully featured version of the above code.

The Core API

The rest of the user guide.

Packaging Crash Course

A tutorial on how to package your Python code so it can be installed and reused.

Implementing SingleOptimizable

A thorough and step-by-step tour of one optimization interface and all the customization points that it provides.

Install Extras

This package defines the following optional dependencies. You can include them by adding the names of all extras in a comma-separated list in brackets behind the name of this package, e.g.:

# pyproject.toml
[project]
dependencies = [
    'cernml-coi[matplotlib, optimizers] >= 0.8.0',
]

matplotlib

Adds a dependency on matplotlib. This is used by a few Problem Checkers.

optimizers

Adds a dependency on cernml-coi-optimizers. This is only used for the type annotations of CustomOptimizerProvider.

robotics

Adds a dependency on gymnasium-robotics. We extend the Multi-Goal Environments that it defines. But if this package isn’t installed, we poly-fill GoalEnv with our own implementation.

all

Adds all optional dependencies except the one on gymnasium-robotics. This exists mostly for convenience.

For easier maintenance, this package also defines the following extras:

doc

Adds all dependencies necessary to build the documentation for this package.

examples

Adds all dependencies necessary to run the Code Examples provided by this package.

test

Adds all dependencies to run the unit tests defined for this package.