Problem Checkers

These functions help validate your Problem for API conformity.

The core of this package is cernml.coi.check(). It tests which interfaces your problem implements and automatically calls the correct specialized checkers. can also be extended with additional checks using cernml.checkers entry points.

You can also invoke the individual checkers yourself, see e.g. check_problem().

cernml.coi.check(
env: Problem,
warn: int = True,
headless: bool = True,
) → None

Check that a problem follows the API of this package.

Parameters:

  • env – The object whose API is to be checked. Must at least be a Problem. If it satisfies other interfaces, like SingleOptimizable or Env, all of their APIs are checked as well.

  • headless – If True (the default), do not run tests that require a GUI.

  • warn – If True (the default), run additional tests that might be indicative of problems but might also exhibit false positives. if False, no warnings are given.

Raises:

AssertionError – if any check fails.

Note

The warn parameter is actually an integer. If it’s nonzero, max(2, warn) is used to calculate the stacklevel passed to warn(). Higher values push the reported offending location further up the stack trace. This allows you to attribute a warning to the correct optimization problem even when calling this function from a wrapper.

cernml.coi.checkers.check_problem(
problem: Problem,
*,
warn: int = True,
headless: bool = True,
) → None

Check the run-time invariants of the given interface.

cernml.coi.checkers.check_single_optimizable(
opt: SingleOptimizable,
warn: int = True,
) → None

Check the run-time invariants of the given interface.

cernml.coi.checkers.check_function_optimizable(
opt: FunctionOptimizable,
warn: int = True,
) → None

Check the run-time invariants of the given interface.

cernml.coi.checkers.check_env(env: Env, warn: int = True) → None

Check the run-time invariants of the given interface.

cernml.coi.checkers.check_configurable(
problem: Configurable,
warn: int = True,
) → None

Check the run-time invariants of the given interface.

entry point group cernml.checkers

Entry points defined under this group allow you to extend the functionality of this package. Each one should point at a function using the syntax module_name:function_name. When called, cernml.coi.check() first runs all built-in checks, then loads all entry points in this group and calls each one with the signature checker(problem, warn=warn, headless=headless).

The warn parameter passed to the entry point is guaranteed to either be False or an integer ≥ 3. This means that if your checker uses warn as a stacklevel parameter to warnings.warn(), the warning will be reported from the line where check() was called. This makes it easier to attribute a warning to the correct optimization problem.