The OPL schema catalogs optimization problems, suites, generators, and their implementations in a single, machine-readable format.

Three design choices shape everything below:

1. One flat library, keyed by ID. Every entity lives in a Library dict. Suites reference problems, problems reference implementations using their respective ID. There is no embedding of problems or implementations within suites to facilitate reuse. F.e. an implementation might be referenced by multiple problems or suites.
2. Numeric fields accept a scalar, a set, or a range. A problem may have exactly 2 objectives, one of {2, 3, 5}, or any value in {min: 2, max: 50}. The same union type is used for variable dimensions and constraint counts.
3. Three-valued logic for yes/no fields. Many boolean fields (f.e. hard, allows_partial_evaluation, ...) YesNoSome as their value. We lose some expressive power but simplify the data entry. If we force authors to decide on yes or no, then we would need more complex structures for variables, constraints etc. and that would make the usual case unnecessarily complex.

• Library
• Thing types
  • Implementation
  • ProblemLike (shared fields)
    • Problem
    • Suite
    • Generator
• Shared building blocks
  • Variable / VariableType
  • Constraint / ConstraintType
  • Reference / Link
  • ValueRange
  • YesNoSome

• When an attribute is followed by a ?, it is optional and can be left out.
• When we refer to a list of unique items, we call them a set. Technically they are a set in Python, but in the YAML representation they are a list. However, they must be unique (i.e. obey the set property)

A Library is a dict from ID to a Thing. IDs are free-form but must be unique and the convention is to add a prefix marking the type to avoid collisions:

On load the library validates that every ID referenced by a suite (problems) or problem (implementations) exists and has the correct type. Suites also have their fidelity_levels auto-populated from their problems.

impl_coco:
  type: implementation
  name: COCO
  description: Comparing Continuous Optimisers
fn_sphere:
  type: problem
  name: Sphere
  objectives: [1]
  implementations: [impl_coco]
suite_bbob:
  type: suite
  name: BBOB
  problems: [fn_sphere]

All entities inherit from Thing, which only carries a discriminator:

type: problem  # or: suite | generator | implementation

We want to have as flat a structure as possible to make exploring and searching OPL as easy as possible. That's one of the reasons the top level object is a dictionary of dissimilar things. But we need to be able to tell them apart so we have a type field to discriminate between them.

A pointer to code that implements one or more problems. Intentionally minimal so that the schema describes what a problem is, not how to run it. There are separate files which contain curated usage examples for problems or suites keyed by their respective IDs.

impl_coco:
  type: implementation
  name: COCO
  description: Comparing Continuous Optimisers benchmarking platform
  language: c
  links:
    - {type: repository, url: https://github.com/numbbo/coco-experiment}
impl_py_cocoex:
  type: implementation
  name: Python bindings for COCO
  description: The Python bindings for the experimental part of the COCO framework
  language: Python
  links:
    - {type: source, url: https://github.com/numbbo/coco-experiment/tree/main/build/python}
    - {type: package, url: https://pypi.org/project/coco-experiment/}

Fields shared by Problem, Suite, and Generator. The schema deliberately puts most descriptive fields here so suites can be characterised without explicitly having to add all problems in the suite.

objectives is a set of integers because we don't assume extreme scalability in this property so explicit enumeration is fine. Dimensions of variables on the other hand are ranges because here problems often are scalable over wide ranges.

When no evaluation_time is set, it percolates up from any referenced implementations. The same is true for the variables and constraints properties of a suite that has references to problems.

fidelity_levels is auto-unioned from member problems at validation time.

One optimization problem (possibly parameterised by instances).

Adds:

fn_sphere:
  type: problem
  name: Sphere
  objectives: [1]
  variables: [{type: continuous, dim: {min: 2, max: 40}}]
  modality: [unimodal]
  source: [artificial]
  instances: {min: 1, max: 15}
  implementations: [impl_coco]

A curated, fixed collection of problems.

Adds:

suite_bbob:
  type: suite
  name: BBOB
  problems: [fn_sphere, fn_rosenbrock, fn_rastrigin]
  objectives: [1]
  source: [artificial]
  implementations: [impl_coco]

A parametric family of problems — unlike a Suite, the member problems are not enumerated. Uses the same fields as ProblemLike with no additions; the distinction from Problem is that a generator produces instances on demand.

gen_mpm2:
  type: generator
  name: MPM2
  description: Multiple peaks model, second instantiation
  objectives: [1]
  variables: [{type: continuous, dim: {min: 1}}]
  modality: [multimodal]

A group of decision variables of the same type. Multi-type problems list multiple entries. While you can have multiple entries of the same type, this should be justified in some way like when you can evaluate the problem on only one subset of variables.

variables:
  - {type: continuous, dim: 10}
  - {type: integer, dim: {min: 1, max: 5}}

continuous | integer | binary | categorical | unknown. Use unknown for permutation/combinatorial problems the schema doesn't yet distinguish and add an appropriate tag. We are actively watching for unknown variable types and are open to extending the above list if there is a critical mass of problems to justify it.

A group of constraints. To indicate that the problem is unconstrained, you need an empty constraints field. A missing constraints field or if it is set to null means it is not known if unconstrained.

constraints:
  - {type: box, hard: yes, number: 10}
  - {type: linear, hard: some, equality: no, number: {min: 1}}

box | linear | function | unknown. function covers non-linear/black-box constraints.

Bibliographic pointer. Requires either a title or a link and optionally a list of authors.

references:
  - title: "Evolutionsstrategie - Optimisierung technischer Systeme nach Prinzipien der biologischen Evolution"
    authors: 
      - Ingo Rechenberg

{type?: str, url: str}. type is free-form (repository, arxiv, paper, doi, ...). url is a URL to some resource.

If type is doi, please use the full URL (starting with https://doi.org/...) instead of the raw DOI.

An inclusive numeric range type. At least one of min/max must be given. If min is given and max is missing, it does not imply that there is no upper bound. There might be one, it is just not known. The same applies for the case where max is given and min is missing.

dim: {min: 2}            # 2 or more
dim: {min: 2, max: 40}   # between 2 and 40
dim: {max: 100}          # up to 100

Used by Variable.dim, Constraint.number, Problem.instances.

Three-valued flag: yes | no | some | ? (the last serialises as the literal '?' string, meaning unknown). some captures the common case where part of something has some property. For example only some constraints might hard but we don't know the exact number of hard and soft constraints, only the total number.

constraints: [{type: box, hard: some}]
allows_partial_evaluation: "unknown"