Skip to content

fix: Make references top level objects #181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
olafmersmann wants to merge 1 commit into
base: pr-convert-problems.yaml
Choose a base branch
from
Open

fix: Make references top level objects #181

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 37 additions & 20 deletions SCHEMA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,15 @@ Three design choices shape everything below:
- [Library](#library)
- [Thing types](#thing-types)
- [Implementation](#implementation)
- [Reference](#reference)
- [ProblemLike](#problemlike) (shared fields)
- [Problem](#problem)
- [Suite](#suite)
- [Generator](#generator)
- [Shared building blocks](#shared-building-blocks)
- [Variable](#variable) / [VariableType](#variabletype)
- [Constraint](#constraint) / [ConstraintType](#constrainttype)
- [Reference](#reference) / [Link](#link)
- [Link](#link)
- [ValueRange](#valuerange)
- [YesNoSome](#yesnosome)

Expand All @@ -43,26 +44,33 @@ IDs are free-form but must be unique and the convention is to add a prefix marki
| Prefix | Type |
|---------|------------------|
| `impl_` | Implementation |
| `ref_` | Reference |
| `fn_` | Problem |
| `suite_`| Suite |
| `gen_` | Generator |

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.
On load the library validates that every ID referenced by a suite (`problems`), problem (`implementations`), or any [ProblemLike](#problemlike) (`references`) exists and has the correct type. Suites also have their `fidelity_levels` auto-populated from their problems.

```yaml
impl_coco:
type: implementation
name: COCO
description: Comparing Continuous Optimisers
ref_bbob:
type: reference
title: "Real-Parameter Black-Box Optimization Benchmarking: Experimental Setup"
link: {type: url, url: "https://numbbo.github.io/coco/"}
fn_sphere:
type: problem
name: Sphere
objectives: [1]
implementations: [impl_coco]
references: [ref_bbob]
suite_bbob:
type: suite
name: BBOB
problems: [fn_sphere]
references: [ref_bbob]
```

---
Expand Down Expand Up @@ -112,6 +120,32 @@ impl_py_cocoex:
- {type: package, url: https://pypi.org/project/coco-experiment/}
```

### Reference

A bibliographic pointer stored at the top level of the [Library](#library) so that a single reference can be shared by multiple problems, suites, generators, and implementations.
Requires either a `title` or a `link` and optionally a list of `authors`.

| Field | Type | Notes |
|-----------|------------------------|------------------------------------------|
| `title` | str? | required if `link` is not given |
| `authors` | list of str? | |
| `link` | [Link](#link)? | required if `title` is not given |

```yaml
ref_honey_badger:
type: reference
title: "Honey Badger Algorithm: New metaheuristic algorithm for solving optimization problems."
authors:
- Fatma A. Hashim
- Essam H. Houssein
- Kashif Hussain
- Mai S. Mabrouk
- Walid Al-Atabany
link: {type: doi, url: "https://doi.org/10.1016/j.matcom.2021.08.013"}
```

[ProblemLike](#problemlike) entities refer to a reference by its ID in the `references` field.

### ProblemLike

Fields shared by [Problem](#problem), [Suite](#suite), and [Generator](#generator).
Expand All @@ -123,7 +157,7 @@ The schema deliberately puts most descriptive fields here so suites can be chara
| `long_name` | str? | |
| `description` | str? (markdown) | longer prose |
| `tags` | set of str? | free-form keywords |
| `references` | set of [Reference](#reference)? | |
| `references` | set of IDs? | must resolve to [Reference](#reference)s |
| `implementations` | set of IDs? | must resolve to [Implementation](#implementation)s |
| `objectives` | set of int? | e.g. `{1}`, `{2, 3}` — **not** a ValueRange |
| `variables` | set of [Variable](#variable)? | |
Expand Down Expand Up @@ -252,23 +286,6 @@ constraints:

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

### Reference

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

```yaml
references:
- title: "Honey Badger Algorithm: New metaheuristic algorithm for solving optimization problems."
authors:
- Fatma A. Hashim
- Essam H. Houssein
- Kashif Hussain
- Mai S. Mabrouk
- Walid Al-Atabany
link: {type: doi, url: "https://doi.org/10.1016/j.matcom.2021.08.013"]
```

### Link

`{type?: str, url: str}`.
Expand Down
14 changes: 7 additions & 7 deletions examples/cobi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@
requirements="https://github.com/numbbo/cobi-problem-generator/blob/main/requirements.txt",
)

things["cobi_ref"] = Reference(
title="Pareto Set Characterization in Constrained Multiobjective Optimization and the COBI Problem Generator",
authors=["Anne Auger", "Dimo Brockhoff", "Luka Opravš", "Tea Tušar"],
link={"type": "arxiv", "url": "https://arxiv.org/abs/2604.09131"},
)

things["cobi_problem"] = Generator(
name="COBI Problem",
description="Generator of COnstrained BI-objective optimization problems",
Expand All @@ -32,13 +38,7 @@
"multi-peak",
"convex-quadratic",
},
references=[
Reference(
title="Pareto Set Characterization in Constrained Multiobjective Optimization and the COBI Problem Generator",
authors=["Anne Auger", "Dimo Brockhoff", "Luka Opravš", "Tea Tušar"],
link={"type": "arxiv", "url": "https://arxiv.org/abs/2604.09131"},
)
],
references={"cobi_ref"},
objectives={2},
variables=[Variable(type="continuous", dim={"min": 1})],
implementations={"cobi_impl"},
Expand Down
16 changes: 7 additions & 9 deletions examples/emdo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from opltools import Library, Problem, Implementation
from opltools import Library, Problem, Implementation, Reference
from pydantic_yaml import to_yaml_str

#! - name: Electric Motor Design Optimization
Expand Down Expand Up @@ -39,6 +39,11 @@
language="python",
evaluation_time=["8 minutes"]
),
"ref_emdo": Reference(
title="A Multi-Step Evaluation Process in Electric Motor Design",
authors=["Tea Tušar", "Peter Korošec", "Bogdan Filipič"],
link={"url": "https://dis.ijs.si/tea/Publications/Tusar23Multistep.pdf"},
),
"fn_emdo": Problem(
name="Electric Motor Design Optimization",
description="""# Goal
Expand Down Expand Up @@ -67,14 +72,7 @@
noise_type=["yes"],
fidelity_levels=[1],
source=["real-world"],
references=[
{
"title": "A Multi-Step Evaluation Process in Electric Motor Design",
"lang": "sj",
"authors": ["Tea Tušar", "Peter Korošec", "Bogdan Filipič"],
"link": {"url": "https://dis.ijs.si/tea/Publications/Tusar23Multistep.pdf"}
}
],
references={"ref_emdo"},
implementations=["impl_emdo"]
)
})
Expand Down
Loading
Loading