MATE-runtime 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.
Files changed (97) hide show
  1. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/.gitignore +2 -0
  2. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/PKG-INFO +17 -4
  3. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/README.md +13 -2
  4. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/pyproject.toml +2 -2
  5. mate_runtime-1.1.0/src/MATE/__init__.py +22 -0
  6. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/src/MATE/__main__.py +2 -0
  7. mate_runtime-1.1.0/src/MATE/cli/__init__.py +200 -0
  8. mate_runtime-1.1.0/src/MATE/cli/commands.py +647 -0
  9. mate_runtime-1.1.0/src/MATE/cli/workdir.py +571 -0
  10. mate_runtime-1.1.0/src/MATE/compat/__init__.py +1 -0
  11. mate_runtime-1.1.0/src/MATE/compat/interface.py +248 -0
  12. mate_runtime-1.1.0/src/MATE/compat/sizes.py +144 -0
  13. mate_runtime-1.1.0/src/MATE/config/__init__.py +1 -0
  14. mate_runtime-1.1.0/src/MATE/config/axes.py +310 -0
  15. mate_runtime-1.1.0/src/MATE/config/builders.py +507 -0
  16. mate_runtime-1.1.0/src/MATE/config/calendar.py +371 -0
  17. mate_runtime-1.1.0/src/MATE/config/canonical.py +543 -0
  18. mate_runtime-1.1.0/src/MATE/config/criteria.py +396 -0
  19. mate_runtime-1.1.0/src/MATE/config/events.py +183 -0
  20. mate_runtime-1.1.0/src/MATE/config/invariance.py +227 -0
  21. mate_runtime-1.1.0/src/MATE/config/loader.py +507 -0
  22. mate_runtime-1.1.0/src/MATE/config/model.py +883 -0
  23. mate_runtime-1.1.0/src/MATE/config/resolve.py +943 -0
  24. mate_runtime-1.1.0/src/MATE/config/runtable.py +342 -0
  25. mate_runtime-1.1.0/src/MATE/config/seeds.py +344 -0
  26. mate_runtime-1.1.0/src/MATE/config/stages.py +632 -0
  27. mate_runtime-1.1.0/src/MATE/config/structure.py +635 -0
  28. mate_runtime-1.1.0/src/MATE/config/toml.py +237 -0
  29. mate_runtime-1.1.0/src/MATE/conformance/__init__.py +14 -0
  30. mate_runtime-1.1.0/src/MATE/conformance/baseline.py +250 -0
  31. mate_runtime-1.1.0/src/MATE/conformance/checks.py +1644 -0
  32. mate_runtime-1.1.0/src/MATE/conformance/sampler.py +179 -0
  33. mate_runtime-1.1.0/src/MATE/errors.py +236 -0
  34. mate_runtime-1.1.0/src/MATE/evaluation/__init__.py +1 -0
  35. mate_runtime-1.1.0/src/MATE/evaluation/budget.py +160 -0
  36. mate_runtime-1.1.0/src/MATE/evaluation/invalids.py +181 -0
  37. mate_runtime-1.1.0/src/MATE/evaluation/requests.py +148 -0
  38. mate_runtime-1.1.0/src/MATE/execution/__init__.py +1 -0
  39. mate_runtime-1.1.0/src/MATE/execution/accelerator.py +60 -0
  40. mate_runtime-1.1.0/src/MATE/execution/base.py +643 -0
  41. mate_runtime-1.1.0/src/MATE/execution/choose.py +152 -0
  42. mate_runtime-1.1.0/src/MATE/execution/devices.py +108 -0
  43. mate_runtime-1.1.0/src/MATE/execution/process.py +388 -0
  44. mate_runtime-1.1.0/src/MATE/execution/serial.py +37 -0
  45. mate_runtime-1.1.0/src/MATE/execution/thread.py +106 -0
  46. mate_runtime-1.1.0/src/MATE/execution/vectorised.py +32 -0
  47. mate_runtime-1.1.0/src/MATE/launch.py +349 -0
  48. mate_runtime-1.1.0/src/MATE/loop/__init__.py +6 -0
  49. mate_runtime-1.1.0/src/MATE/loop/continuous.py +172 -0
  50. mate_runtime-1.1.0/src/MATE/loop/driver.py +815 -0
  51. mate_runtime-1.1.0/src/MATE/loop/events.py +266 -0
  52. mate_runtime-1.1.0/src/MATE/loop/generational.py +140 -0
  53. mate_runtime-1.1.0/src/MATE/loop/owns_loop.py +333 -0
  54. mate_runtime-1.1.0/src/MATE/loop/subpops.py +508 -0
  55. mate_runtime-1.1.0/src/MATE/modules/__init__.py +1 -0
  56. mate_runtime-1.1.0/src/MATE/modules/construct.py +198 -0
  57. mate_runtime-1.1.0/src/MATE/modules/discovery.py +238 -0
  58. mate_runtime-1.1.0/src/MATE/modules/registry.py +970 -0
  59. mate_runtime-1.1.0/src/MATE/modules/software.py +593 -0
  60. mate_runtime-1.1.0/src/MATE/modules/versions.py +72 -0
  61. mate_runtime-1.1.0/src/MATE/numerics.py +159 -0
  62. mate_runtime-1.1.0/src/MATE/observation/__init__.py +10 -0
  63. mate_runtime-1.1.0/src/MATE/observation/control.py +199 -0
  64. mate_runtime-1.1.0/src/MATE/observation/display.py +1048 -0
  65. mate_runtime-1.1.0/src/MATE/observation/hub.py +468 -0
  66. mate_runtime-1.1.0/src/MATE/observation/records.py +125 -0
  67. mate_runtime-1.1.0/src/MATE/observation/sinks.py +307 -0
  68. mate_runtime-1.1.0/src/MATE/provenance.py +396 -0
  69. mate_runtime-1.1.0/src/MATE/readout/__init__.py +10 -0
  70. mate_runtime-1.1.0/src/MATE/readout/catalogue.py +282 -0
  71. mate_runtime-1.1.0/src/MATE/readout/front.py +151 -0
  72. mate_runtime-1.1.0/src/MATE/readout/readout.py +953 -0
  73. mate_runtime-1.1.0/src/MATE/readout/series.py +155 -0
  74. mate_runtime-1.1.0/src/MATE/readout/statistics.py +202 -0
  75. mate_runtime-1.1.0/src/MATE/run/__init__.py +1 -0
  76. mate_runtime-1.1.0/src/MATE/run/checkpointing.py +266 -0
  77. mate_runtime-1.1.0/src/MATE/run/contexts.py +553 -0
  78. mate_runtime-1.1.0/src/MATE/run/declarations.py +245 -0
  79. mate_runtime-1.1.0/src/MATE/run/plan.py +467 -0
  80. mate_runtime-1.1.0/src/MATE/run/preconditions.py +165 -0
  81. mate_runtime-1.1.0/src/MATE/run/record.py +554 -0
  82. mate_runtime-1.1.0/src/MATE/run/run.py +1010 -0
  83. mate_runtime-1.1.0/src/MATE/run/specs.py +319 -0
  84. mate_runtime-1.1.0/src/MATE/run/times.py +103 -0
  85. mate_runtime-1.1.0/src/MATE/scheduling/__init__.py +219 -0
  86. mate_runtime-1.1.0/src/MATE/scheduling/local.py +134 -0
  87. mate_runtime-1.1.0/src/MATE/scheduling/slurm.py +384 -0
  88. mate_runtime-1.1.0/src/MATE/storage/__init__.py +1 -0
  89. mate_runtime-1.1.0/src/MATE/storage/checkpoint.py +414 -0
  90. mate_runtime-1.1.0/src/MATE/storage/codec.py +315 -0
  91. mate_runtime-1.1.0/src/MATE/storage/database.py +359 -0
  92. mate_runtime-1.1.0/src/MATE/storage/lease.py +397 -0
  93. mate_runtime-1.1.0/src/MATE/storage/rundir.py +248 -0
  94. mate_runtime-1.0.0.dev0/src/MATE/__init__.py +0 -14
  95. mate_runtime-1.0.0.dev0/src/MATE/cli.py +0 -19
  96. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/COPYING +0 -0
  97. {mate_runtime-1.0.0.dev0 → mate_runtime-1.1.0}/COPYING.LESSER +0 -0
@@ -10,3 +10,5 @@ dist/
10
10
  .coverage
11
11
  htmlcov/
12
12
  .project.settings
13
+ public/
14
+ docs/_build/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: MATE-runtime
3
- Version: 1.0.0.dev0
3
+ Version: 1.1.0
4
4
  Summary: Runtime of MATE, the Modular Algorithmic Toolkit for Evolution: runs, records and replays artificial evolution experiments
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
@@ -15,7 +15,9 @@ 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.0.0.dev0
18
+ Requires-Dist: mate-contract<2,>=1.1
19
+ Requires-Dist: packaging>=24
20
+ Requires-Dist: rich>=13.7
19
21
  Description-Content-Type: text/markdown
20
22
 
21
23
  # MATE-runtime
@@ -25,8 +27,19 @@ Modular Algorithmic Toolkit for Evolution: the run loop, scheduling, storage
25
27
  and the command line `MATE`. Its import name is `MATE`, which also re-exports
26
28
  the contract types.
27
29
 
28
- **Status: under development.** This release only reserves the name; it
29
- contains no functionality yet.
30
+ It loads protocols (TOML files or their Python form), runs them with the
31
+ `serial`, `thread`, `process` or `vectorised` executor, locally or on Slurm,
32
+ records every run in a SQLite database with its provenance, and resumes and
33
+ branches runs from their checkpoints. `MATE replay` replays an individual of a
34
+ run, recorded as the run evaluated it, in the window of the analysis library of
35
+ `MATE-libraries`. `MATE check` runs the conformance suite on a module.
36
+
37
+ ```
38
+ MATE launch protocol.toml
39
+ MATE status Files/protocol
40
+ MATE show Files/protocol/run_000
41
+ MATE replay Files/protocol/run_000
42
+ ```
30
43
 
31
44
  ## Installation
32
45
 
@@ -5,8 +5,19 @@ Modular Algorithmic Toolkit for Evolution: the run loop, scheduling, storage
5
5
  and the command line `MATE`. Its import name is `MATE`, which also re-exports
6
6
  the contract types.
7
7
 
8
- **Status: under development.** This release only reserves the name; it
9
- contains no functionality yet.
8
+ It loads protocols (TOML files or their Python form), runs them with the
9
+ `serial`, `thread`, `process` or `vectorised` executor, locally or on Slurm,
10
+ records every run in a SQLite database with its provenance, and resumes and
11
+ branches runs from their checkpoints. `MATE replay` replays an individual of a
12
+ run, recorded as the run evaluated it, in the window of the analysis library of
13
+ `MATE-libraries`. `MATE check` runs the conformance suite on a module.
14
+
15
+ ```
16
+ MATE launch protocol.toml
17
+ MATE status Files/protocol
18
+ MATE show Files/protocol/run_000
19
+ MATE replay Files/protocol/run_000
20
+ ```
10
21
 
11
22
  ## Installation
12
23
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "MATE-runtime"
7
- version = "1.0.0.dev0"
7
+ version = "1.1.0"
8
8
  description = "Runtime of MATE, the Modular Algorithmic Toolkit for Evolution: runs, records and replays artificial evolution experiments"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.14"
@@ -21,7 +21,7 @@ classifiers = [
21
21
  "Programming Language :: Python :: 3",
22
22
  "Topic :: Scientific/Engineering",
23
23
  ]
24
- dependencies = ["MATE-contract>=1.0.0.dev0,<2"]
24
+ dependencies = ["MATE-contract>=1.1,<2", "packaging>=24", "rich>=13.7"]
25
25
 
26
26
  [project.scripts]
27
27
  MATE = "MATE.cli:main"
@@ -0,0 +1,22 @@
1
+ """MATE runtime: runs, records and replays artificial evolution experiments.
2
+
3
+ ``import MATE`` re-exports the contract types, so that users need not tell ``MATE`` and
4
+ ``MATE_contract`` apart, and adds the Python form of a protocol (design §2.4). Every other
5
+ runtime name is imported from its module (``MATE.conformance``, ``MATE.observation.records``,
6
+ ...).
7
+ """
8
+
9
+ import importlib.metadata
10
+
11
+ from MATE_contract import * # noqa: F403
12
+ from MATE_contract import __all__ as _contract_names
13
+
14
+ from MATE.config.builders import Protocol, loops, method, protocol, replicates, sample, stop, system
15
+ from MATE.errors import ProtocolRefused
16
+ from MATE.run.plan import LaunchResult
17
+ from MATE.run.run import Run
18
+
19
+ __version__ = importlib.metadata.version("MATE-runtime")
20
+
21
+ __all__ = [*_contract_names, "protocol", "method", "system", "loops", "stop", "replicates",
22
+ "sample", "Protocol", "ProtocolRefused", "Run", "LaunchResult"]
@@ -1,3 +1,5 @@
1
+ """``python -m MATE``: the ``MATE`` command line."""
2
+
1
3
  import sys
2
4
 
3
5
  from MATE.cli import main
@@ -0,0 +1,200 @@
1
+ """The ``MATE`` command line ([X] §24, [C] §21, design §3.14).
2
+
3
+ :func:`main` parses the arguments and dispatches to :mod:`MATE.cli.commands`. Exit status:
4
+ 0 success, 1 refusal (software, interface, preconditions, deferred feature), 2 run
5
+ failures, 3 usage error.
6
+ """
7
+
8
+ import argparse
9
+ import sys
10
+ from importlib.metadata import version
11
+ from typing import NoReturn
12
+
13
+ from MATE.cli import commands
14
+
15
+ __all__ = ["main", "build_parser"]
16
+
17
+ _USAGE = 3
18
+ _EXECUTORS = ("serial", "thread", "process", "vectorised", "accelerator")
19
+ _VERBOSITIES = ("quiet", "normal", "verbose", "debug")
20
+
21
+
22
+ class _Usage(Exception):
23
+ """An argument error, reported with exit status 3."""
24
+
25
+
26
+ class _Parser(argparse.ArgumentParser):
27
+ """An argument parser whose errors give exit status 3 instead of exiting with 2."""
28
+
29
+ def error(self, message: str) -> NoReturn:
30
+ self.print_usage(sys.stderr)
31
+ raise _Usage(f"{self.prog}: error: {message}")
32
+
33
+
34
+ def _execution(p: argparse.ArgumentParser, *, retention: bool = False) -> None:
35
+ """The ``[execution]`` overrides ([C] R21.1)."""
36
+ p.add_argument("--workers", type=int, help="number of workers")
37
+ p.add_argument("--executor", choices=_EXECUTORS, help="executor")
38
+ p.add_argument("--scheduler", choices=("slurm",), help="submit to a Slurm cluster")
39
+ p.add_argument("--verbosity", choices=_VERBOSITIES, help="terminal verbosity")
40
+ p.add_argument("--workdir", help="working directory of the runs")
41
+ p.add_argument("--sinks", help="comma-separated sink names, replacing [execution] sinks")
42
+ p.add_argument("--debug", action="store_true", help="debug mode: fail at the first error")
43
+ p.add_argument("--dry-run", action="store_true",
44
+ help="prepare the workdir (and Slurm scripts) and run nothing")
45
+ if retention:
46
+ p.add_argument("--retention", choices=("minimal", "lineage", "full"))
47
+ p.add_argument("--checkpoint-every", type=int, dest="checkpoint_every")
48
+
49
+
50
+ def build_parser() -> argparse.ArgumentParser:
51
+ """Build the argument parser of the ``MATE`` command.
52
+
53
+ Returns
54
+ -------
55
+ argparse.ArgumentParser
56
+ One sub-command per command of [X] §24 and design §3.14; ``exec-run`` is hidden.
57
+ """
58
+ parser = _Parser(
59
+ prog="MATE",
60
+ description="MATE, the Modular Algorithmic Toolkit for Evolution.",
61
+ )
62
+ parser.add_argument(
63
+ "--version",
64
+ action="version",
65
+ version=f"MATE-runtime {version('MATE-runtime')} (MATE-contract {version('MATE-contract')})",
66
+ )
67
+ sub = parser.add_subparsers(dest="command", metavar="<command>", parser_class=_Parser)
68
+
69
+ p = sub.add_parser("launch", help="launch a protocol")
70
+ p.add_argument("protocol", help="the protocol file")
71
+ _execution(p)
72
+ p.add_argument("--sweep", action="append", metavar="PATH=V1,V2",
73
+ help="add an axis (repeatable)")
74
+ p.add_argument("--force", action="store_true",
75
+ help="start every run anew, overwriting the runs already in the workdir")
76
+ p.add_argument("--dashboard", action="store_true", help=argparse.SUPPRESS)
77
+ p.set_defaults(func=commands.cmd_launch)
78
+
79
+ for name, text, func in (("status", "progress and missing runs", commands.cmd_status),
80
+ ("verify", "check the held invariants", commands.cmd_verify),
81
+ ("runs", "blueprints -> runs, for analysis", commands.cmd_runs)):
82
+ p = sub.add_parser(name, help=text)
83
+ p.add_argument("workdir")
84
+ p.add_argument("--protocol", help="the protocol aggregated (several in the workdir)")
85
+ p.set_defaults(func=func)
86
+
87
+ p = sub.add_parser("diff", help="what differs between two blueprints")
88
+ p.add_argument("a", help="a run directory or a workdir")
89
+ p.add_argument("b", help="a run directory or a workdir")
90
+ p.set_defaults(func=commands.cmd_diff)
91
+
92
+ p = sub.add_parser("show", help="summary, series, best individual")
93
+ p.add_argument("path", help="a run directory or a workdir")
94
+ p.add_argument("--objective", help="objective of the best individual (K >= 2)")
95
+ p.add_argument("--subpop", help="subpopulation shown (several subpopulations)")
96
+ p.set_defaults(func=commands.cmd_show)
97
+
98
+ p = sub.add_parser("branch", help="branch from a recorded run")
99
+ p.add_argument("target", metavar="RUN@GENERATION")
100
+ p.add_argument("--count", type=int, required=True, help="number of replicates")
101
+ p.add_argument("--root-seed", required=True, dest="root_seed",
102
+ help="root seed (an integer or 'fresh')")
103
+ _execution(p, retention=True)
104
+ p.set_defaults(func=commands.cmd_branch)
105
+
106
+ p = sub.add_parser("control", help="control a running run")
107
+ p.add_argument("run", help="the run directory")
108
+ p.add_argument("command_name", metavar="command",
109
+ choices=("stop", "suspend", "resume", "checkpoint", "verbosity"))
110
+ p.add_argument("value", nargs="?", help="the verbosity, for 'verbosity'")
111
+ p.set_defaults(func=commands.cmd_control)
112
+
113
+ p = sub.add_parser("list", help="installed modules and their status")
114
+ p.set_defaults(func=commands.cmd_list)
115
+
116
+ p = sub.add_parser("matrix", help="compatibility table of methods x systems")
117
+ p.add_argument("--smoke", action="store_true", help="two real generations per pair")
118
+ p.set_defaults(func=commands.cmd_matrix)
119
+
120
+ p = sub.add_parser("check", help="conformance suite of a module")
121
+ p.add_argument("module")
122
+ p.add_argument("--kind", choices=("method", "system"),
123
+ help="the module's kind, when a method and a system share its name")
124
+ p.add_argument("--system", help="system a method is checked against")
125
+ p.add_argument("--method", help="method a system's resume test runs with")
126
+ p.add_argument("--set", action="append", metavar="KEY=VALUE",
127
+ help="a setting of the module (repeatable)")
128
+ p.add_argument("--tolerance", type=float, default=0.0)
129
+ p.set_defaults(func=commands.cmd_check)
130
+
131
+ p = sub.add_parser("search", help="search the module registry")
132
+ p.add_argument("text")
133
+ p.set_defaults(func=commands.cmd_search)
134
+
135
+ p = sub.add_parser("install", help="install modules from the registry")
136
+ p.add_argument("names", nargs="+", metavar="name",
137
+ help="a registered name, optionally name==version, or a git+ URL")
138
+ p.set_defaults(func=commands.cmd_install)
139
+
140
+ for name, text, func in (
141
+ ("record", "record an individual of a run, for its replay", commands.cmd_record),
142
+ ("replay", "replay an individual of a run in a window", commands.cmd_replay)):
143
+ p = sub.add_parser(name, help=text)
144
+ if name == "record":
145
+ p.add_argument("run", help="the run directory")
146
+ else:
147
+ p.add_argument("run", help="the run directory, or a recording file")
148
+ p.add_argument("--genome", type=int, help="the genome; default the best of the run")
149
+ p.add_argument("--subpop", help="its subpopulation (several subpopulations)")
150
+ p.add_argument("--objective", help="the objective of the best individual (K >= 2)")
151
+ p.add_argument("--force", action="store_true",
152
+ help="record again, replacing the recording kept in the run's replays/")
153
+ p.add_argument("--debug", action="store_true",
154
+ help="print the traceback of a module that fails")
155
+ if name == "replay":
156
+ p.add_argument("--fixed", action="store_true",
157
+ help="a fixed view of the scenes instead of following them")
158
+ p.add_argument("--movie", help="a movie file written while the replay plays")
159
+ p.set_defaults(func=func)
160
+
161
+ p = sub.add_parser("dashboard", help="terminal dashboard (not available in MATE 1.0.0)")
162
+ p.add_argument("args", nargs=argparse.REMAINDER)
163
+ p.set_defaults(func=commands.cmd_dashboard)
164
+
165
+ p = sub.add_parser("exec-run") # hidden: no help, not listed ([X] SC4)
166
+ p.add_argument("directory")
167
+ p.add_argument("--debug", action="store_true")
168
+ p.set_defaults(func=commands.cmd_exec_run)
169
+ return parser
170
+
171
+
172
+ def main(argv: list[str] | None = None) -> int:
173
+ """Run the ``MATE`` command line.
174
+
175
+ Parameters
176
+ ----------
177
+ argv : list of str, optional
178
+ The arguments; default ``sys.argv[1:]``.
179
+
180
+ Returns
181
+ -------
182
+ int
183
+ The exit status: 0 success, 1 refusal, 2 run failures, 3 usage error.
184
+ """
185
+ parser = build_parser()
186
+ try:
187
+ args = parser.parse_args(argv)
188
+ except _Usage as exc:
189
+ print(exc, file=sys.stderr)
190
+ return _USAGE
191
+ except SystemExit as exc: # --version, --help
192
+ return exc.code if isinstance(exc.code, int) else 0
193
+ if args.command is None:
194
+ parser.print_help()
195
+ return 0
196
+ try:
197
+ return args.func(args)
198
+ except commands.UsageError as exc:
199
+ print(f"MATE {args.command}: error: {exc}", file=sys.stderr)
200
+ return _USAGE