MATE-libraries 1.0.0.dev0__tar.gz → 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/.gitignore +2 -0
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/PKG-INFO +23 -7
- mate_libraries-1.1.0/README.md +38 -0
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/pyproject.toml +11 -3
- mate_libraries-1.1.0/src/MATE_libraries/analysis/__init__.py +43 -0
- mate_libraries-1.1.0/src/MATE_libraries/analysis/__main__.py +57 -0
- mate_libraries-1.1.0/src/MATE_libraries/analysis/_performance.py +295 -0
- mate_libraries-1.1.0/src/MATE_libraries/analysis/_read.py +218 -0
- mate_libraries-1.1.0/src/MATE_libraries/analysis/_replay.py +589 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/__init__.py +76 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_catalogue.py +282 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_compiled.py +520 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_graph.py +139 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_networkx.py +249 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_opencl.py +599 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_organ.py +100 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_prepare.py +594 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_propagate.py +194 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_state.py +364 -0
- mate_libraries-1.1.0/src/MATE_libraries/networks/_techniques.py +466 -0
- mate_libraries-1.1.0/src/MATE_libraries/operators/__init__.py +54 -0
- mate_libraries-1.1.0/src/MATE_libraries/operators/_draws.py +121 -0
- mate_libraries-1.1.0/src/MATE_libraries/operators/_selection.py +607 -0
- mate_libraries-1.1.0/src/MATE_libraries/operators/_variation.py +121 -0
- mate_libraries-1.0.0.dev0/README.md +0 -28
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/COPYING +0 -0
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/COPYING.LESSER +0 -0
- {mate_libraries-1.0.0.dev0 → mate_libraries-1.1.0}/src/MATE_libraries/__init__.py +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: MATE-libraries
|
|
3
|
-
Version: 1.
|
|
4
|
-
Summary: Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules, analysis library for recorded runs
|
|
5
5
|
Project-URL: Homepage, https://gitlab.com/artificial_evolution/mate/mate
|
|
6
6
|
Project-URL: Issues, https://gitlab.com/artificial_evolution/mate/mate/-/issues
|
|
7
7
|
Author: Sébastien Billès
|
|
@@ -15,18 +15,32 @@ Classifier: Intended Audience :: Science/Research
|
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
16
|
Classifier: Topic :: Scientific/Engineering
|
|
17
17
|
Requires-Python: >=3.14
|
|
18
|
-
Requires-Dist: mate-contract<2,>=1.
|
|
18
|
+
Requires-Dist: mate-contract<2,>=1.1
|
|
19
|
+
Provides-Extra: analysis
|
|
20
|
+
Requires-Dist: matplotlib>=3.9; extra == 'analysis'
|
|
21
|
+
Provides-Extra: opencl
|
|
22
|
+
Requires-Dist: pyopencl>=2024.1; extra == 'opencl'
|
|
23
|
+
Provides-Extra: replay
|
|
24
|
+
Requires-Dist: lib-anim>=1.0.14; extra == 'replay'
|
|
19
25
|
Description-Content-Type: text/markdown
|
|
20
26
|
|
|
21
27
|
# MATE-libraries
|
|
22
28
|
|
|
23
29
|
The libraries of [MATE](https://gitlab.com/artificial_evolution/mate/mate), the
|
|
24
30
|
Modular Algorithmic Toolkit for Evolution: the network library and the standard
|
|
25
|
-
operators library, which method and system modules may use
|
|
26
|
-
`MATE-contract`
|
|
31
|
+
operators library, which method and system modules may use, and the analysis
|
|
32
|
+
library, which reads recorded runs and draws them. It depends on `MATE-contract`
|
|
33
|
+
only.
|
|
27
34
|
|
|
28
|
-
|
|
29
|
-
|
|
35
|
+
The standard operators library (`MATE_libraries.operators`) gives a variation
|
|
36
|
+
operator per domain and the standard selections. The network library
|
|
37
|
+
(`MATE_libraries.networks`) compiles batches of `Network` organs and propagates
|
|
38
|
+
them on the CPU, with results that do not depend on the batch. Each of these two
|
|
39
|
+
libraries has its own `version`, recorded in every run whose modules import it.
|
|
40
|
+
The analysis library (`MATE_libraries.analysis`) plots the performance of a
|
|
41
|
+
workdir's runs, one run at a time beside the others, and replays the evaluation
|
|
42
|
+
of an individual frame by frame; its figures need the `analysis` extra, its
|
|
43
|
+
replay window the `replay` extra (lib-anim).
|
|
30
44
|
|
|
31
45
|
## Installation
|
|
32
46
|
|
|
@@ -34,6 +48,8 @@ Requires Python 3.14 or later.
|
|
|
34
48
|
|
|
35
49
|
```
|
|
36
50
|
pip install MATE-libraries
|
|
51
|
+
pip install "MATE-libraries[analysis]" # with the figures of the analysis library
|
|
52
|
+
pip install "MATE-libraries[replay]" # with its replay window
|
|
37
53
|
```
|
|
38
54
|
|
|
39
55
|
A module that uses it declares it as a dependency; the runtime does not need it.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# MATE-libraries
|
|
2
|
+
|
|
3
|
+
The libraries of [MATE](https://gitlab.com/artificial_evolution/mate/mate), the
|
|
4
|
+
Modular Algorithmic Toolkit for Evolution: the network library and the standard
|
|
5
|
+
operators library, which method and system modules may use, and the analysis
|
|
6
|
+
library, which reads recorded runs and draws them. It depends on `MATE-contract`
|
|
7
|
+
only.
|
|
8
|
+
|
|
9
|
+
The standard operators library (`MATE_libraries.operators`) gives a variation
|
|
10
|
+
operator per domain and the standard selections. The network library
|
|
11
|
+
(`MATE_libraries.networks`) compiles batches of `Network` organs and propagates
|
|
12
|
+
them on the CPU, with results that do not depend on the batch. Each of these two
|
|
13
|
+
libraries has its own `version`, recorded in every run whose modules import it.
|
|
14
|
+
The analysis library (`MATE_libraries.analysis`) plots the performance of a
|
|
15
|
+
workdir's runs, one run at a time beside the others, and replays the evaluation
|
|
16
|
+
of an individual frame by frame; its figures need the `analysis` extra, its
|
|
17
|
+
replay window the `replay` extra (lib-anim).
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
Requires Python 3.14 or later.
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
pip install MATE-libraries
|
|
25
|
+
pip install "MATE-libraries[analysis]" # with the figures of the analysis library
|
|
26
|
+
pip install "MATE-libraries[replay]" # with its replay window
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
A module that uses it declares it as a dependency; the runtime does not need it.
|
|
30
|
+
|
|
31
|
+
## Authors and acknowledgment
|
|
32
|
+
|
|
33
|
+
Crafted with ❤️ by Raphaël Candelier and Sébastien Billès.
|
|
34
|
+
|
|
35
|
+
## License
|
|
36
|
+
|
|
37
|
+
This project is licensed under the terms of the GNU Lesser General Public
|
|
38
|
+
License v3.0 or later (`LGPL-3.0-or-later`).
|
|
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "MATE-libraries"
|
|
7
|
-
version = "1.
|
|
8
|
-
description = "Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules"
|
|
7
|
+
version = "1.1.0"
|
|
8
|
+
description = "Libraries of MATE, the Modular Algorithmic Toolkit for Evolution: network library and standard operators library for MATE modules, analysis library for recorded runs"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.14"
|
|
11
11
|
license = "LGPL-3.0-or-later"
|
|
@@ -21,7 +21,15 @@ classifiers = [
|
|
|
21
21
|
"Programming Language :: Python :: 3",
|
|
22
22
|
"Topic :: Scientific/Engineering",
|
|
23
23
|
]
|
|
24
|
-
dependencies = ["MATE-contract>=1.
|
|
24
|
+
dependencies = ["MATE-contract>=1.1,<2"]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
# The device path of the network library: propagation on an OpenCL device.
|
|
28
|
+
opencl = ["pyopencl>=2024.1"]
|
|
29
|
+
# The figures of the analysis library.
|
|
30
|
+
analysis = ["matplotlib>=3.9"]
|
|
31
|
+
# The replay window of the analysis library.
|
|
32
|
+
replay = ["lib-anim>=1.0.14"]
|
|
25
33
|
|
|
26
34
|
[project.urls]
|
|
27
35
|
Homepage = "https://gitlab.com/artificial_evolution/mate/mate"
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""The analysis library: basic tools that read recorded runs and draw them, outside any run.
|
|
2
|
+
|
|
3
|
+
MATE records and does not analyse within a run; this library gives a quick look at what runs
|
|
4
|
+
recorded, the analyses of a study being written apart. It reads the files MATE writes, as the
|
|
5
|
+
formats reference of the main documentation describes them: the run table of a workdir, then
|
|
6
|
+
the database and the status of each run. It never imports the runtime, and no run imports it.
|
|
7
|
+
Drawing needs matplotlib, the ``analysis`` extra of MATE-libraries, imported by the functions
|
|
8
|
+
that draw.
|
|
9
|
+
|
|
10
|
+
Unlike the libraries that compute for modules, it has no ``version``: no run imports it and
|
|
11
|
+
nothing it draws enters a run, while the runtime records in a run's provenance the version of
|
|
12
|
+
every library imported in its process. Its changes are dated by the release notes of
|
|
13
|
+
MATE-libraries.
|
|
14
|
+
|
|
15
|
+
Attributes
|
|
16
|
+
----------
|
|
17
|
+
SCHEMA : int
|
|
18
|
+
The version of the database schema the library reads.
|
|
19
|
+
|
|
20
|
+
It also replays an evaluation: :func:`replay` draws a recording (the ``Recording`` a system
|
|
21
|
+
returns from ``record``) frame by frame, a panel per track, with lib-anim, the ``replay`` extra.
|
|
22
|
+
Given a run directory, it asks the runtime for the recording of an individual
|
|
23
|
+
(``MATE record``), which the runtime keeps in the run's ``replays/``.
|
|
24
|
+
|
|
25
|
+
Examples
|
|
26
|
+
--------
|
|
27
|
+
>>> from MATE_libraries import analysis
|
|
28
|
+
>>> analysis.performance("Files/DEBoG_XOR") # doctest: +SKIP
|
|
29
|
+
>>> runs = analysis.read_runs("Files/DEBoG_XOR") # doctest: +SKIP
|
|
30
|
+
>>> x, best = analysis.best_so_far(runs[0], "score") # doctest: +SKIP
|
|
31
|
+
|
|
32
|
+
>>> analysis.replay("Files/DEBoG_XOR/run_003") # doctest: +SKIP
|
|
33
|
+
|
|
34
|
+
From a terminal: ``python -m MATE_libraries.analysis performance Files/DEBoG_XOR``, and
|
|
35
|
+
``python -m MATE_libraries.analysis replay Files/DEBoG_XOR/run_003``.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
from ._performance import best_so_far, performance
|
|
39
|
+
from ._read import SCHEMA, RecordedRun, read_run, read_runs
|
|
40
|
+
from ._replay import layout, replay, window
|
|
41
|
+
|
|
42
|
+
__all__ = ["SCHEMA", "RecordedRun", "read_run", "read_runs", "best_so_far", "performance",
|
|
43
|
+
"replay", "window", "layout"]
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""``python -m MATE_libraries.analysis``: the tools of the analysis library, from a terminal."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import sys
|
|
5
|
+
from collections.abc import Sequence
|
|
6
|
+
|
|
7
|
+
from ._performance import performance
|
|
8
|
+
from ._replay import replay
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
12
|
+
"""Run a tool of the analysis library.
|
|
13
|
+
|
|
14
|
+
Parameters
|
|
15
|
+
----------
|
|
16
|
+
argv : sequence of str, optional
|
|
17
|
+
The arguments; those of the command line by default.
|
|
18
|
+
|
|
19
|
+
Returns
|
|
20
|
+
-------
|
|
21
|
+
int
|
|
22
|
+
The exit status: 0, or 1 when the tool cannot draw (a path that is not a run, an
|
|
23
|
+
extra missing, a run the runtime cannot record), the reason written to stderr.
|
|
24
|
+
"""
|
|
25
|
+
parser = argparse.ArgumentParser(prog="python -m MATE_libraries.analysis",
|
|
26
|
+
description="Tools that read recorded runs and draw them.")
|
|
27
|
+
tools = parser.add_subparsers(dest="tool", required=True)
|
|
28
|
+
plot = tools.add_parser("performance", help="the performance of the runs, a run at a time")
|
|
29
|
+
plot.add_argument("path", help="a workdir or a run directory")
|
|
30
|
+
plot.add_argument("--objective", help="the objective shown first")
|
|
31
|
+
plot.add_argument("--subpop", help="the subpopulation shown (mandatory with several)")
|
|
32
|
+
plot.add_argument("--x", choices=("evaluation", "generation"), default="evaluation",
|
|
33
|
+
help="the horizontal axis (default: evaluation)")
|
|
34
|
+
view = tools.add_parser("replay", help="replay an evaluation, a run's best by default")
|
|
35
|
+
view.add_argument("path", help="a recording file, or a run directory")
|
|
36
|
+
view.add_argument("--genome", type=int, help="the genome to replay (a run's best by default)")
|
|
37
|
+
view.add_argument("--subpop", help="its subpopulation (mandatory with several)")
|
|
38
|
+
view.add_argument("--objective", help="the objective that defines the best")
|
|
39
|
+
view.add_argument("--force", action="store_true",
|
|
40
|
+
help="record again, replacing the recording the run keeps")
|
|
41
|
+
view.add_argument("--fixed", action="store_true", help="a fixed view instead of following")
|
|
42
|
+
view.add_argument("--movie", help="a movie file written while the replay plays")
|
|
43
|
+
args = parser.parse_args(argv)
|
|
44
|
+
try:
|
|
45
|
+
if args.tool == "performance":
|
|
46
|
+
performance(args.path, objective=args.objective, subpop=args.subpop, x=args.x)
|
|
47
|
+
else:
|
|
48
|
+
replay(args.path, genome=args.genome, subpop=args.subpop, objective=args.objective,
|
|
49
|
+
force=args.force, follow=not args.fixed, movie=args.movie)
|
|
50
|
+
except (ImportError, OSError, RuntimeError, ValueError) as exc:
|
|
51
|
+
print(exc, file=sys.stderr)
|
|
52
|
+
return 1
|
|
53
|
+
return 0
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
if __name__ == "__main__":
|
|
57
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
"""The performance of recorded runs: one run in front, the others behind, a selector between them."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Iterable
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from types import MappingProxyType
|
|
6
|
+
from typing import Any, Final
|
|
7
|
+
|
|
8
|
+
import numpy as np
|
|
9
|
+
|
|
10
|
+
from ._read import RecordedRun, read_runs
|
|
11
|
+
|
|
12
|
+
_X: Final[tuple[str, ...]] = ("evaluation", "generation")
|
|
13
|
+
# The two series of the run in front take the first two slots of the reference palette; the
|
|
14
|
+
# other runs stay behind in grey; ink, grid and axes are recessive.
|
|
15
|
+
_EVALUATION: Final[str] = "#2a78d6"
|
|
16
|
+
_BEST: Final[str] = "#eb6834"
|
|
17
|
+
_CONTEXT: Final[str] = "#c3c2b7"
|
|
18
|
+
_INK: Final[str] = "#52514e"
|
|
19
|
+
_MUTED: Final[str] = "#898781"
|
|
20
|
+
_STYLE: Final = MappingProxyType({
|
|
21
|
+
"axes.spines.top": False,
|
|
22
|
+
"axes.spines.right": False,
|
|
23
|
+
"axes.edgecolor": "#c3c2b7",
|
|
24
|
+
"axes.grid": True,
|
|
25
|
+
"grid.color": "#e1e0d9",
|
|
26
|
+
"grid.linewidth": 0.8,
|
|
27
|
+
"axes.labelcolor": _INK,
|
|
28
|
+
"xtick.color": _MUTED,
|
|
29
|
+
"ytick.color": _MUTED,
|
|
30
|
+
"font.size": 10,
|
|
31
|
+
})
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def best_so_far(run: RecordedRun, objective: str, subpop: str | None = None,
|
|
35
|
+
x: str = "evaluation") -> tuple[np.ndarray, np.ndarray]:
|
|
36
|
+
"""Return the best value of an objective reached so far along a run.
|
|
37
|
+
|
|
38
|
+
Parameters
|
|
39
|
+
----------
|
|
40
|
+
run : RecordedRun
|
|
41
|
+
The run.
|
|
42
|
+
objective : str
|
|
43
|
+
The name of the objective; the best is the largest value (objectives are maximised).
|
|
44
|
+
subpop : str, optional
|
|
45
|
+
Only the evaluations of this subpopulation; all of them by default.
|
|
46
|
+
x : {"evaluation", "generation"}, default "evaluation"
|
|
47
|
+
At each evaluation (by rank), or at the end of each generation in which evaluations
|
|
48
|
+
were requested.
|
|
49
|
+
|
|
50
|
+
Returns
|
|
51
|
+
-------
|
|
52
|
+
x, best : numpy.ndarray
|
|
53
|
+
float64 arrays of equal length; ``best`` is NaN before the first valid evaluation.
|
|
54
|
+
Empty when the run lacks the objective or has no evaluation.
|
|
55
|
+
|
|
56
|
+
Raises
|
|
57
|
+
------
|
|
58
|
+
ValueError
|
|
59
|
+
For an unknown ``x``.
|
|
60
|
+
"""
|
|
61
|
+
if x not in _X:
|
|
62
|
+
raise ValueError(f"analysis: x must be one of {list(_X)}, got {x!r}")
|
|
63
|
+
if objective not in run.objectives:
|
|
64
|
+
return np.zeros(0), np.zeros(0)
|
|
65
|
+
mask = np.ones(len(run.rank), dtype=bool)
|
|
66
|
+
if subpop is not None:
|
|
67
|
+
mask = run.subpop == (run.subpops.index(subpop) if subpop in run.subpops else -1)
|
|
68
|
+
values = run.values[mask, run.objectives.index(objective)]
|
|
69
|
+
best = np.fmax.accumulate(values) if values.size else values
|
|
70
|
+
if x == "evaluation":
|
|
71
|
+
return run.rank[mask].astype(np.float64), best
|
|
72
|
+
generation = run.generation[mask]
|
|
73
|
+
last = np.flatnonzero(np.r_[generation[1:] != generation[:-1], True]) if values.size \
|
|
74
|
+
else np.zeros(0, dtype=np.int64)
|
|
75
|
+
return generation[last].astype(np.float64), best[last]
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _steps(x: np.ndarray, best: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
|
|
79
|
+
"""The corners of a best-so-far step line: where it starts, where it rises, where it ends.
|
|
80
|
+
|
|
81
|
+
Drawn in ``steps-post``, they give the same line as every point, with far fewer of them.
|
|
82
|
+
"""
|
|
83
|
+
keep = np.isfinite(best)
|
|
84
|
+
x, best = x[keep], best[keep]
|
|
85
|
+
if best.size < 3:
|
|
86
|
+
return x, best
|
|
87
|
+
corner = np.r_[True, best[1:] != best[:-1]]
|
|
88
|
+
corner[-1] = True
|
|
89
|
+
return x[corner], best[corner]
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _source(source: str | Path | Iterable[RecordedRun]) -> tuple[RecordedRun, ...]:
|
|
93
|
+
"""The runs of a path, or the runs given."""
|
|
94
|
+
if isinstance(source, (str, Path)):
|
|
95
|
+
return read_runs(source)
|
|
96
|
+
runs = tuple(source)
|
|
97
|
+
for run in runs:
|
|
98
|
+
if not isinstance(run, RecordedRun):
|
|
99
|
+
raise TypeError(f"analysis: expected a path or RecordedRun objects, got "
|
|
100
|
+
f"{type(run).__name__}")
|
|
101
|
+
return runs
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _describe(run: RecordedRun, index: int, count: int) -> str:
|
|
105
|
+
"""The name of a run, its place and its axis values."""
|
|
106
|
+
axes = ", ".join(f"{k} = {v}" for k, v in run.axes.items())
|
|
107
|
+
parts = [run.name, f"{index + 1}/{count}"]
|
|
108
|
+
if axes:
|
|
109
|
+
parts.append(axes)
|
|
110
|
+
if run.replicate is not None:
|
|
111
|
+
parts.append(f"replicate {run.replicate}")
|
|
112
|
+
if run.status and run.status != "stopped":
|
|
113
|
+
parts.append(run.status) # still running, failed...: a normal end is not shown
|
|
114
|
+
return " · ".join(parts)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def performance(source: str | Path | Iterable[RecordedRun], *, objective: str | None = None,
|
|
118
|
+
subpop: str | None = None, x: str = "evaluation", show: bool = True) -> Any:
|
|
119
|
+
"""Plot the performance of recorded runs, one run at a time beside the others.
|
|
120
|
+
|
|
121
|
+
The run in front shows each evaluation (a dot; invalid ones are left out) and the best
|
|
122
|
+
value reached so far (a step line); the best-so-far lines of the other runs stay behind in
|
|
123
|
+
grey, on the same axes, so that a run reads against the protocol. A slider below the plot,
|
|
124
|
+
or the left and right arrow keys, selects the run; with several objectives, buttons on the
|
|
125
|
+
side, or the up and down arrow keys, select the objective.
|
|
126
|
+
|
|
127
|
+
Parameters
|
|
128
|
+
----------
|
|
129
|
+
source : str, Path or iterable of RecordedRun
|
|
130
|
+
A workdir (every run of its run table), a run directory, or runs read by
|
|
131
|
+
:func:`read_runs`.
|
|
132
|
+
objective : str, optional
|
|
133
|
+
The objective shown first; the first one by default.
|
|
134
|
+
subpop : str, optional
|
|
135
|
+
The subpopulation whose evaluations are shown; mandatory when the runs have several.
|
|
136
|
+
x : {"evaluation", "generation"}, default "evaluation"
|
|
137
|
+
The horizontal axis: the rank of each evaluation, or the generation in which it was
|
|
138
|
+
requested.
|
|
139
|
+
show : bool, default True
|
|
140
|
+
Show the figure (``matplotlib.pyplot.show``), which blocks until it closes.
|
|
141
|
+
|
|
142
|
+
Returns
|
|
143
|
+
-------
|
|
144
|
+
matplotlib.figure.Figure
|
|
145
|
+
The figure; its attribute ``analysis_widgets`` holds the run slider (``"run"``) and
|
|
146
|
+
the objective buttons (``"objective"``), ``None`` when there is a single choice.
|
|
147
|
+
|
|
148
|
+
Raises
|
|
149
|
+
------
|
|
150
|
+
ValueError
|
|
151
|
+
For no run, an unknown objective, subpopulation or ``x``, or several subpopulations
|
|
152
|
+
and none named.
|
|
153
|
+
ImportError
|
|
154
|
+
Without matplotlib, the ``analysis`` extra of MATE-libraries.
|
|
155
|
+
"""
|
|
156
|
+
runs = _source(source)
|
|
157
|
+
if not runs:
|
|
158
|
+
raise ValueError("analysis: no run to plot")
|
|
159
|
+
if x not in _X:
|
|
160
|
+
raise ValueError(f"analysis: x must be one of {list(_X)}, got {x!r}")
|
|
161
|
+
names = tuple(dict.fromkeys(n for run in runs for n in run.objectives))
|
|
162
|
+
if not names:
|
|
163
|
+
raise ValueError("analysis: the runs declare no objective")
|
|
164
|
+
if objective is not None and objective not in names:
|
|
165
|
+
raise ValueError(f"analysis: no objective {objective!r}; the runs have {list(names)}")
|
|
166
|
+
subpops = tuple(dict.fromkeys(s for run in runs for s in run.subpops))
|
|
167
|
+
if subpop is None and len(subpops) > 1:
|
|
168
|
+
raise ValueError(f"analysis: the runs have several subpopulations {list(subpops)}; "
|
|
169
|
+
"name one with subpop=")
|
|
170
|
+
if subpop is not None and subpop not in subpops:
|
|
171
|
+
raise ValueError(f"analysis: no subpopulation {subpop!r}; the runs have "
|
|
172
|
+
f"{list(subpops)}")
|
|
173
|
+
try:
|
|
174
|
+
import matplotlib.pyplot as plt
|
|
175
|
+
from matplotlib.backend_bases import key_press_handler
|
|
176
|
+
from matplotlib.widgets import RadioButtons, Slider
|
|
177
|
+
except ImportError as exc: # pragma: no cover - depends on the installed extras
|
|
178
|
+
raise ImportError("analysis: plotting needs matplotlib: pip install "
|
|
179
|
+
"'MATE-libraries[analysis]'") from exc
|
|
180
|
+
|
|
181
|
+
state = {"run": 0, "objective": names.index(objective) if objective else 0}
|
|
182
|
+
width = 0.64 if len(names) > 1 else 0.86
|
|
183
|
+
with plt.rc_context(dict(_STYLE)):
|
|
184
|
+
fig = plt.figure(figsize=(10, 6))
|
|
185
|
+
ax = fig.add_axes((0.09, 0.2, width, 0.6))
|
|
186
|
+
context = [ax.plot([], [], color=_CONTEXT, linewidth=1, drawstyle="steps-post",
|
|
187
|
+
zorder=1)[0] for _ in runs]
|
|
188
|
+
dots = ax.scatter([], [], s=8, color=_EVALUATION, alpha=0.4, linewidths=0, zorder=2,
|
|
189
|
+
rasterized=True, label="Evaluations")
|
|
190
|
+
(best,) = ax.plot([], [], color=_BEST, linewidth=2, drawstyle="steps-post", zorder=3,
|
|
191
|
+
label="Best so far")
|
|
192
|
+
handles = [dots, best] + ([context[-1]] if len(runs) > 1 else [])
|
|
193
|
+
labels = ["Evaluations", "Best so far"] + (["Other runs, best so far"]
|
|
194
|
+
if len(runs) > 1 else [])
|
|
195
|
+
# On its own line above the plot, clear of the data and of the title.
|
|
196
|
+
ax.legend(handles, labels, loc="lower left", bbox_to_anchor=(0.0, 1.0), ncols=3,
|
|
197
|
+
frameon=False, markerscale=2, labelcolor=_INK, borderaxespad=0.3)
|
|
198
|
+
ax.set_xlabel("Evaluation" if x == "evaluation" else "Generation")
|
|
199
|
+
title = fig.text(0.09, 0.97, "", va="top", ha="left", fontsize=10, color=_INK)
|
|
200
|
+
slider = None
|
|
201
|
+
if len(runs) > 1:
|
|
202
|
+
slider = Slider(fig.add_axes((0.09, 0.07, width, 0.035)), "Run", 0, len(runs) - 1,
|
|
203
|
+
valinit=0, valstep=1, color=_CONTEXT, initcolor="none")
|
|
204
|
+
slider.valtext.set_visible(False)
|
|
205
|
+
buttons = None
|
|
206
|
+
if len(names) > 1:
|
|
207
|
+
height = min(0.6, 0.06 * len(names))
|
|
208
|
+
buttons = RadioButtons(fig.add_axes((0.77, 0.9 - height, 0.21, height),
|
|
209
|
+
frameon=False), names,
|
|
210
|
+
active=state["objective"])
|
|
211
|
+
|
|
212
|
+
def draw_behind() -> None:
|
|
213
|
+
"""The other runs and the axes' limits, for the objective shown."""
|
|
214
|
+
name = names[state["objective"]]
|
|
215
|
+
values: list[np.ndarray] = []
|
|
216
|
+
span: list[np.ndarray] = []
|
|
217
|
+
for run, line in zip(runs, context):
|
|
218
|
+
bx, by = best_so_far(run, name, subpop, x)
|
|
219
|
+
line.set_data(*_steps(bx, by))
|
|
220
|
+
span.append(bx)
|
|
221
|
+
if name in run.objectives:
|
|
222
|
+
v = run.values[:, run.objectives.index(name)]
|
|
223
|
+
values.append(v[np.isfinite(v)])
|
|
224
|
+
every = np.concatenate(values) if values else np.zeros(0)
|
|
225
|
+
reach = np.concatenate(span) if span else np.zeros(0)
|
|
226
|
+
if every.size:
|
|
227
|
+
lo, hi = float(every.min()), float(every.max())
|
|
228
|
+
pad = 0.05 * (hi - lo) if hi > lo else 0.5
|
|
229
|
+
ax.set_ylim(lo - pad, hi + pad)
|
|
230
|
+
if reach.size:
|
|
231
|
+
ax.set_xlim(float(reach.min()) - 0.5, float(reach.max()) + 0.5)
|
|
232
|
+
ax.set_ylabel(name)
|
|
233
|
+
|
|
234
|
+
def draw_front() -> None:
|
|
235
|
+
"""The run in front: its evaluations, its best so far and the title."""
|
|
236
|
+
name = names[state["objective"]]
|
|
237
|
+
front = runs[state["run"]]
|
|
238
|
+
for i, line in enumerate(context):
|
|
239
|
+
line.set_visible(i != state["run"])
|
|
240
|
+
mask = np.ones(len(front.rank), dtype=bool)
|
|
241
|
+
if subpop is not None:
|
|
242
|
+
mask = front.subpop == (front.subpops.index(subpop) if subpop in front.subpops
|
|
243
|
+
else -1)
|
|
244
|
+
k = front.objectives.index(name) if name in front.objectives else None
|
|
245
|
+
shown = front.values[mask, k] if k is not None else np.zeros(0)
|
|
246
|
+
position = (front.rank if x == "evaluation" else front.generation)[mask]
|
|
247
|
+
valid = np.isfinite(shown)
|
|
248
|
+
dots.set_offsets(np.column_stack([position[valid], shown[valid]]))
|
|
249
|
+
bx, by = best_so_far(front, name, subpop, x)
|
|
250
|
+
best.set_data(*_steps(bx, by))
|
|
251
|
+
top = float(np.nanmax(by)) if by.size and np.isfinite(by).any() else None
|
|
252
|
+
invalid = int(np.count_nonzero(np.isnan(shown)))
|
|
253
|
+
infinite = int(np.count_nonzero(np.isinf(shown)))
|
|
254
|
+
hidden = f"{invalid:,} invalid" + (f", {infinite:,} infinite" if infinite else "")
|
|
255
|
+
summary = (f"best {top:.6g}" if top is not None else "no valid evaluation") + \
|
|
256
|
+
f" · {int(valid.sum()):,} evaluations, {hidden} (not shown)"
|
|
257
|
+
title.set_text(f"{_describe(front, state['run'], len(runs))}\n{summary}")
|
|
258
|
+
fig.canvas.draw_idle()
|
|
259
|
+
|
|
260
|
+
def select_run(value: float) -> None:
|
|
261
|
+
state["run"] = int(round(value))
|
|
262
|
+
draw_front()
|
|
263
|
+
|
|
264
|
+
def select_objective(label: str | None) -> None:
|
|
265
|
+
state["objective"] = names.index(label)
|
|
266
|
+
draw_behind()
|
|
267
|
+
draw_front()
|
|
268
|
+
|
|
269
|
+
if slider is not None:
|
|
270
|
+
slider.on_changed(select_run)
|
|
271
|
+
if buttons is not None:
|
|
272
|
+
buttons.on_clicked(select_objective)
|
|
273
|
+
|
|
274
|
+
manager = fig.canvas.manager
|
|
275
|
+
default = getattr(manager, "key_press_handler_id", None)
|
|
276
|
+
if default is not None:
|
|
277
|
+
fig.canvas.mpl_disconnect(default)
|
|
278
|
+
|
|
279
|
+
def on_key(event: Any) -> None:
|
|
280
|
+
if event.key in ("left", "right") and slider is not None:
|
|
281
|
+
step = -1 if event.key == "left" else 1
|
|
282
|
+
slider.set_val(min(max(state["run"] + step, 0), len(runs) - 1))
|
|
283
|
+
elif event.key in ("up", "down") and buttons is not None:
|
|
284
|
+
step = -1 if event.key == "up" else 1
|
|
285
|
+
buttons.set_active((state["objective"] + step) % len(names))
|
|
286
|
+
elif manager is not None:
|
|
287
|
+
key_press_handler(event, fig.canvas, manager.toolbar)
|
|
288
|
+
|
|
289
|
+
fig.canvas.mpl_connect("key_press_event", on_key)
|
|
290
|
+
fig.analysis_widgets = {"run": slider, "objective": buttons}
|
|
291
|
+
draw_behind()
|
|
292
|
+
draw_front()
|
|
293
|
+
if show:
|
|
294
|
+
plt.show()
|
|
295
|
+
return fig
|