aniate 2.0.2__tar.gz → 2.2.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.
- {aniate-2.0.2/aniate.egg-info → aniate-2.2.0}/PKG-INFO +119 -27
- {aniate-2.0.2 → aniate-2.2.0}/README.md +108 -22
- aniate-2.2.0/aniate/__init__.py +27 -0
- aniate-2.2.0/aniate/gym.py +120 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/__init__.py +19 -1
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/check.py +5 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/core.py +8 -1
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/env.py +6 -1
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/solution.py +5 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/validate.py +7 -2
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/__init__.py +12 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/machine.py +5 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/policy.py +5 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/task.py +5 -0
- aniate-2.2.0/aniate/notebook.py +286 -0
- aniate-2.2.0/aniate/route/__init__.py +229 -0
- aniate-2.2.0/aniate/route/core.py +546 -0
- aniate-2.2.0/aniate/route/exact.py +142 -0
- aniate-2.2.0/aniate/route/metaheuristic.py +71 -0
- aniate-2.2.0/aniate/route/network/__init__.py +109 -0
- aniate-2.2.0/aniate/route/network/attention.py +466 -0
- aniate-2.2.0/aniate/route/network/base.py +19 -0
- aniate-2.2.0/aniate/route/network/beam.py +109 -0
- aniate-2.2.0/aniate/route/network/decode.py +141 -0
- aniate-2.2.0/aniate/route/network/decoder.py +226 -0
- aniate-2.2.0/aniate/route/network/encoder.py +71 -0
- aniate-2.2.0/aniate/route/network/instance.py +38 -0
- aniate-2.2.0/aniate/route/network/masking.py +109 -0
- aniate-2.2.0/aniate/route/network/model.py +224 -0
- aniate-2.2.0/aniate/route/network/simulator.py +346 -0
- aniate-2.2.0/aniate/route/network/train.py +152 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/selfcheck.py +3 -2
- {aniate-2.0.2 → aniate-2.2.0/aniate.egg-info}/PKG-INFO +119 -27
- {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/SOURCES.txt +22 -14
- {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/requires.txt +10 -1
- {aniate-2.0.2 → aniate-2.2.0}/pyproject.toml +10 -6
- aniate-2.2.0/tests/test_gym.py +85 -0
- aniate-2.2.0/tests/test_notebook.py +64 -0
- aniate-2.2.0/tests/test_route.py +142 -0
- aniate-2.0.2/MANIFEST.in +0 -2
- aniate-2.0.2/aniate/__init__.py +0 -25
- aniate-2.0.2/conftest.py +0 -8
- aniate-2.0.2/tests/gaussian/plane.py +0 -49
- aniate-2.0.2/tests/gaussian/plot.py +0 -65
- aniate-2.0.2/tests/gaussian/test_gaussian.py +0 -37
- aniate-2.0.2/tests/heavy_tail/plot.py +0 -75
- aniate-2.0.2/tests/heavy_tail/test_heavy_tail.py +0 -42
- aniate-2.0.2/tests/heavy_tail/warehouse.py +0 -67
- aniate-2.0.2/tests/strategies.py +0 -79
- aniate-2.0.2/tests/stsp/plot.py +0 -62
- aniate-2.0.2/tests/stsp/route.py +0 -78
- aniate-2.0.2/tests/stsp/test_stsp.py +0 -28
- aniate-2.0.2/tree.md +0 -183
- {aniate-2.0.2 → aniate-2.2.0}/LICENSE +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/__main__.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/art.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/log.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/builder.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/policies.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/solve.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/space.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/text.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/builders.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/labels.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/product.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/__init__.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/classic.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/gridworld.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/__init__.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/diagrams.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/grid.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/stats.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/style.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/dependency_links.txt +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/entry_points.txt +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/top_level.txt +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/setup.cfg +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_ant.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_art.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_env.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_log.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_model.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_nmdp.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_solve.py +0 -0
- {aniate-2.0.2 → aniate-2.2.0}/tests/test_vis.py +0 -0
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: aniate
|
|
3
|
-
Version: 2.0
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 2.2.0
|
|
4
|
+
Summary: Open source combinatorics solvers: cube and ncube for routing, mdp and nmdp for decisions.
|
|
5
5
|
Author: Kabir Murjani
|
|
6
6
|
License-Expression: MIT
|
|
7
|
-
Project-URL: Homepage, https://
|
|
7
|
+
Project-URL: Homepage, https://aniate.com
|
|
8
8
|
Project-URL: Documentation, https://github.com/Kcbir/aniate/blob/main/tree.md
|
|
9
9
|
Project-URL: Source, https://github.com/Kcbir/aniate
|
|
10
10
|
Project-URL: Issues, https://github.com/Kcbir/aniate/issues
|
|
11
11
|
Project-URL: Releases, https://github.com/Kcbir/aniate/releases
|
|
12
|
-
Keywords: mdp,reinforcement-learning,markov-decision-process,simulation,non-markovian,reward-machine,gym,dynamic-programming,monte-carlo
|
|
12
|
+
Keywords: combinatorial-optimization,routing,tsp,travelling-thief-problem,drone,mdp,reinforcement-learning,markov-decision-process,simulation,non-markovian,reward-machine,gym,gymnasium,jupyter,dynamic-programming,monte-carlo
|
|
13
13
|
Classifier: Development Status :: 3 - Alpha
|
|
14
14
|
Classifier: Intended Audience :: Science/Research
|
|
15
15
|
Classifier: Intended Audience :: Education
|
|
@@ -32,19 +32,26 @@ Requires-Dist: matplotlib>=3.8; extra == "vis"
|
|
|
32
32
|
Provides-Extra: test
|
|
33
33
|
Requires-Dist: pytest>=7; extra == "test"
|
|
34
34
|
Requires-Dist: hypothesis>=6; extra == "test"
|
|
35
|
+
Provides-Extra: gym
|
|
36
|
+
Requires-Dist: gymnasium>=0.29; extra == "gym"
|
|
37
|
+
Provides-Extra: neural
|
|
38
|
+
Requires-Dist: torch>=2.1; extra == "neural"
|
|
39
|
+
Provides-Extra: milp
|
|
40
|
+
Requires-Dist: gurobipy>=11; extra == "milp"
|
|
35
41
|
Provides-Extra: dev
|
|
36
|
-
Requires-Dist: aniate[test,vis]; extra == "dev"
|
|
42
|
+
Requires-Dist: aniate[gym,test,vis]; extra == "dev"
|
|
37
43
|
Dynamic: license-file
|
|
38
44
|
|
|
39
45
|
<div align="center">
|
|
40
46
|
|
|
41
47
|
# aniate
|
|
42
48
|
|
|
43
|
-
*
|
|
49
|
+
*Open source combinatorics solvers*
|
|
44
50
|
|
|
45
51
|
[](https://pypi.org/project/aniate/)
|
|
46
52
|
[](https://www.python.org/)
|
|
47
53
|
[](https://github.com/Kcbir/aniate/actions/workflows/test.yml)
|
|
54
|
+
[](https://aniate.com)
|
|
48
55
|
[](https://github.com/Kcbir/aniate/blob/main/tree.md)
|
|
49
56
|
[](https://github.com/Kcbir/aniate/blob/main/LICENSE)
|
|
50
57
|
|
|
@@ -56,7 +63,61 @@ Dynamic: license-file
|
|
|
56
63
|
|
|
57
64
|
---
|
|
58
65
|
|
|
59
|
-
|
|
66
|
+
```python
|
|
67
|
+
from aniate import cube, ncube, mdp, nmdp
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
| Solver | Solves | Call |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| **NCube** | the TTP-D with a trained network, the neural accelerator | `ncube(nodes, profits, weights, drone=True)` |
|
|
73
|
+
| **Cube** | the TTP-D with the metaheuristic | `cube(nodes, profits, weights, drone=True)` |
|
|
74
|
+
| **cube.milp** | the TTP-D with the exact model | `cube.milp(nodes, profits, weights, drone=True)` |
|
|
75
|
+
| **MDP** | decisions where only the present matters | `mdp(states, actions, transition, reward).solve()` |
|
|
76
|
+
| **NMDP** | decisions where the past matters | `nmdp(world, labels, rule).solve()` |
|
|
77
|
+
|
|
78
|
+
## Cube and NCube
|
|
79
|
+
|
|
80
|
+
Solvers for the Travelling Thief Problem with Drone, from [Drive, Pack, Fly: The Travelling Thief Problem with Drone](https://arxiv.org/abs/2608.16435), by Kabir Murjani and Prof. Abhay Sobhanan. They take the same inputs, and what you leave out decides the problem: with no items it is a TSP-D, with no drone a TTP, and with neither a TSP.
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from aniate import cube, ncube
|
|
84
|
+
|
|
85
|
+
nodes = [(0, 0), (4, 1), (5, 4), (1, 5), (2, 2), (3, 3)] # depot first
|
|
86
|
+
profits, weights = [50, 60, 70, 80, 40], [2, 3, 4, 5, 2]
|
|
87
|
+
|
|
88
|
+
ncube(nodes, profits, weights, drone=True) # the neural accelerator, with our weights
|
|
89
|
+
net = ncube.train(30) # or your own, on 30 customers
|
|
90
|
+
ncube(nodes, profits, weights, drone=True, network=net)
|
|
91
|
+
|
|
92
|
+
print(cube(nodes)) # TSP: a truck
|
|
93
|
+
print(cube(nodes, drone=True)) # TSP-D: a truck and a drone
|
|
94
|
+
print(cube(nodes, profits, weights)) # TTP: a truck and a knapsack
|
|
95
|
+
print(cube(nodes, profits, weights, drone=True)) # TTP-D: all three
|
|
96
|
+
|
|
97
|
+
print(cube.milp(nodes, profits, weights, drone=True)) # the exact model, for small problems
|
|
98
|
+
|
|
99
|
+
env = cube.env(nodes, profits, weights, drone=True) # the simulator, one decision at a time
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
| input | default | meaning |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `nodes` | required | `(x, y)` pairs, depot first |
|
|
105
|
+
| `profits`, `weights` | none | one value per customer, depot left out; give both or neither |
|
|
106
|
+
| `drone` | `False` | fly a drone from the truck |
|
|
107
|
+
| `endurance` | unlimited | longest flight, launch to customer to landing; setting it turns the drone on |
|
|
108
|
+
| `capacity` | half the total weight | what the truck can carry |
|
|
109
|
+
| `rent` | the rate at which a plain tour costs half of all the profit | cost per unit of time |
|
|
110
|
+
| `drone_speed` | twice the empty truck's speed | setting it turns the drone on |
|
|
111
|
+
| `dist` | straight lines | your own distance matrix, depot first |
|
|
112
|
+
| `seconds` | half a second per customer; one hour for `cube.milp` | time limit for `cube` and `cube.milp`; the paper gives `cube` 15 per customer |
|
|
113
|
+
| `seed` | `0` | `cube` only |
|
|
114
|
+
| `network` | `True`, our weights | `ncube` only; a path to your own, or what `ncube.train` returned |
|
|
115
|
+
|
|
116
|
+
The plan comes back with `route`, `flights`, `items`, `time`, `profit`, `objective`, `problem`, `seconds`, `solver` and, for `cube.milp`, `gap`. `ncube` needs `pip install 'aniate[neural]'` and downloads the closest trained size once from Hugging Face. `ncube.train(problems, examples=100, seconds=None, epochs=60, save=None)` solves each problem with the metaheuristic, then teaches the network to imitate those plans; `problems` is a number of customers, or a list of `(nodes, profits, weights)`. `cube.milp` needs `pip install 'aniate[milp]'` and a Gurobi licence for all but small problems.
|
|
117
|
+
|
|
118
|
+
## MDP and NMDP
|
|
119
|
+
|
|
120
|
+
The decision solvers work with finite problems: Markov decision processes in `mdp`, and problems whose reward depends on the history of the episode in `nmdp`.
|
|
60
121
|
|
|
61
122
|
A problem is specified by its states, actions, transition probabilities, rewards and discount factor. The specification is validated at construction, and a model is rejected when a probability row does not sum to one, when a terminal state continues to move or to accrue reward, or when its value is unbounded. The library computes optimal policies together with their exact values, simulates episodes in batches, and compares any external simulator with the model through per-transition chi-square tests and the value martingale `M_t = G_<t + γ^t V(s_t)`. History-dependent objectives are expressed with event labels and a Mealy automaton, and the exact product model is solved. Every operation writes one structured log line, and every figure is saved as a PDF with embedded Computer Modern fonts.
|
|
62
123
|
|
|
@@ -65,6 +126,18 @@ A problem is specified by its states, actions, transition probabilities, rewards
|
|
|
65
126
|
```bash
|
|
66
127
|
pip install aniate # numpy and scipy
|
|
67
128
|
pip install 'aniate[vis]' # adds matplotlib, required for plots
|
|
129
|
+
pip install 'aniate[gym]' # adds gymnasium, required for aniate.gym
|
|
130
|
+
pip install 'aniate[neural]' # adds PyTorch, required for the neural accelerator
|
|
131
|
+
pip install 'aniate[milp]' # adds Gurobi, required for the exact model
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
For Julia, `cube` is one call too:
|
|
135
|
+
|
|
136
|
+
```julia
|
|
137
|
+
using Pkg; Pkg.add(url="https://github.com/Kcbir/aniate", subdir="julia")
|
|
138
|
+
|
|
139
|
+
using Aniate
|
|
140
|
+
cube(nodes, profits, weights; drone=true)
|
|
68
141
|
```
|
|
69
142
|
|
|
70
143
|
## Verifying the installation
|
|
@@ -77,7 +150,7 @@ ant()
|
|
|
77
150
|
`ant()` prints the Fibonacci drawing, the installed version of Python and of each dependency, and the result of a self-test that builds, solves, simulates and checks a small model. It returns `True` when aniate is working. The same report is printed by `python -m aniate`.
|
|
78
151
|
|
|
79
152
|
```
|
|
80
|
-
aniate 2.0
|
|
153
|
+
aniate 2.2.0 Open source combinatorics solvers
|
|
81
154
|
|
|
82
155
|
python 3.12.4 ok required, 3.10 or later
|
|
83
156
|
numpy 2.1.0 ok required, 1.24 or later
|
|
@@ -85,6 +158,7 @@ scipy 1.14.1 ok required, 1.12 or later
|
|
|
85
158
|
matplotlib - not installed optional, for plots in aniate.vis
|
|
86
159
|
pytest - not installed optional, for running the tests
|
|
87
160
|
hypothesis - not installed optional, for property-based tests
|
|
161
|
+
gymnasium - not installed optional, for the Gymnasium adapter in aniate.gym
|
|
88
162
|
|
|
89
163
|
self-test model valid | solved, value 3.20876 | 2,000 episodes simulated | check passed | 13 ms
|
|
90
164
|
plots unavailable; install them with: pip install 'aniate[vis]'
|
|
@@ -95,10 +169,9 @@ aniate is working.
|
|
|
95
169
|
## Quick start
|
|
96
170
|
|
|
97
171
|
```python
|
|
98
|
-
|
|
99
|
-
from aniate import vis
|
|
172
|
+
from aniate import mdp, vis
|
|
100
173
|
|
|
101
|
-
m =
|
|
174
|
+
m = mdp(
|
|
102
175
|
states=range(5), actions=["left", "right"],
|
|
103
176
|
transition=lambda s, a: {max(s - 1, 0): 1.0} if a == "left" else {min(s + 1, 4): 0.8, s: 0.2},
|
|
104
177
|
reward=lambda s, a, s_next: 10.0 if s_next == 4 else -1.0,
|
|
@@ -106,8 +179,8 @@ m = an.from_functions(
|
|
|
106
179
|
)
|
|
107
180
|
|
|
108
181
|
sol = m.solve() # optimal policy, its exact value, an error bound
|
|
109
|
-
runs =
|
|
110
|
-
report =
|
|
182
|
+
runs = mdp.simulate(m, sol, episodes=10_000) # 10,000 episodes, run in parallel
|
|
183
|
+
report = mdp.check(m, policy=sol) # compares simulated behaviour with the model
|
|
111
184
|
vis.save(vis.overview(runs), "overview.pdf") # four standard plots in one PDF
|
|
112
185
|
m.describe() # the model as a JSON-compatible dict
|
|
113
186
|
```
|
|
@@ -133,38 +206,57 @@ Construction fails, and the error names each offending state and action, if any
|
|
|
133
206
|
| `terminal_not_absorbing` | a terminal state moves to another state or pays a reward |
|
|
134
207
|
| `unbounded_value` | the discount factor is 1 and no terminal state is reachable |
|
|
135
208
|
|
|
136
|
-
`
|
|
209
|
+
`mdp.check(model, env=simulator)` runs episodes through an external simulator and reports `impossible_transition`, `transition_frequency`, `reward_mismatch`, `termination_mismatch` and `return_mismatch`. These properties are verified by runtime checks and by the test suite; they are not formally proved.
|
|
137
210
|
|
|
138
211
|
## History-dependent rewards
|
|
139
212
|
|
|
140
213
|
```python
|
|
141
|
-
from aniate import nmdp
|
|
214
|
+
from aniate import nmdp, problems
|
|
142
215
|
|
|
143
|
-
world =
|
|
216
|
+
world = problems.gridworld(rows=5, cols=5, goals=((0, 4),), start=(4, 0))
|
|
144
217
|
labels = nmdp.Labels(world).at("r4c4", "A").at("r0c4", "B")
|
|
145
|
-
task =
|
|
218
|
+
task = nmdp(world, labels, nmdp.Ordering(["A", "B"], violation_penalty=-1))
|
|
146
219
|
policy = task.solve() # a MemoryPolicy: policy.step(state) returns the next action
|
|
147
220
|
```
|
|
148
221
|
|
|
149
222
|
`nmdp.Ordering`, `nmdp.Budget` and `nmdp.Deadline` cover common patterns, and `nmdp.Mealy` expresses any finite-memory rule.
|
|
150
223
|
|
|
224
|
+
## Notebooks
|
|
225
|
+
|
|
226
|
+
In Jupyter, a model, solution, set of episodes, check report, automaton or non-Markovian task that ends a cell is displayed as a table. A long table is shortened, and the number of omitted rows is stated.
|
|
227
|
+
|
|
228
|
+
## Gymnasium
|
|
229
|
+
|
|
230
|
+
```python
|
|
231
|
+
from aniate import gym
|
|
232
|
+
|
|
233
|
+
env = gym.make(m) # a gymnasium.Env with Discrete spaces
|
|
234
|
+
obs, info = env.reset(seed=0)
|
|
235
|
+
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
|
|
236
|
+
|
|
237
|
+
gym.register("aniate/Corridor-v0", lambda: m) # gymnasium.make("aniate/Corridor-v0") then builds it
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Transitions are sampled from the model with the seeded generator of Gymnasium, so equal seeds give equal episodes, and the environment passes the Gymnasium environment checker. The adapter requires `pip install 'aniate[gym]'`.
|
|
241
|
+
|
|
151
242
|
## Interface
|
|
152
243
|
|
|
153
244
|
| call | purpose |
|
|
154
245
|
|---|---|
|
|
155
246
|
| `ant()` | report installed dependencies and run a self-test |
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
247
|
+
| `mdp(states, actions, transition, reward, gamma, terminal=, initial=)` | define a model with Python functions |
|
|
248
|
+
| `mdp.Builder(gamma)` | define a model one transition at a time |
|
|
249
|
+
| `mdp.MDP(P, R, gamma)` | define a model from matrices |
|
|
159
250
|
| `m.solve()` | optimal policy and exact value |
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
251
|
+
| `mdp.evaluate(m, policy)` | exact value of any policy |
|
|
252
|
+
| `mdp.simulate(m, policy, episodes)` | batched episodes, returned as `Episodes` |
|
|
162
253
|
| `m.env()` | a Gym-style environment with `reset` and `step` |
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
254
|
+
| `mdp.check(m, env=simulator, policy=)` | statistical comparison of a simulator with the model |
|
|
255
|
+
| `nmdp(world, labels, automaton)` | a problem whose reward depends on history |
|
|
256
|
+
| `gym.make(m)`, `gym.register(id, model)` | the model as a Gymnasium environment |
|
|
165
257
|
| `vis.overview(runs)`, `vis.graph(m)`, `vis.grid(m, sol)` | plots; `vis.save(fig, "name.pdf")` writes a PDF |
|
|
166
258
|
| `obj.describe()` | a JSON-compatible summary of any model, solution, report or set of episodes |
|
|
167
|
-
| `
|
|
259
|
+
| `aniate.verbosity("quiet")` | set the log level |
|
|
168
260
|
|
|
169
261
|
A decision tree for choosing among these calls, the package layout and the conventions for extending the library are given in [tree.md](https://github.com/Kcbir/aniate/blob/main/tree.md).
|
|
170
262
|
|
|
@@ -189,9 +281,9 @@ Importing aniate prints a Fibonacci rectangle to standard error once per process
|
|
|
189
281
|
```bibtex
|
|
190
282
|
@software{murjani2026aniate,
|
|
191
283
|
author = {Murjani, Kabir},
|
|
192
|
-
title = {aniate:
|
|
284
|
+
title = {aniate: open source combinatorics solvers},
|
|
193
285
|
year = {2026},
|
|
194
|
-
version = {2.0
|
|
286
|
+
version = {2.2.0},
|
|
195
287
|
url = {https://github.com/Kcbir/aniate}
|
|
196
288
|
}
|
|
197
289
|
```
|
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
# aniate
|
|
4
4
|
|
|
5
|
-
*
|
|
5
|
+
*Open source combinatorics solvers*
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/aniate/)
|
|
8
8
|
[](https://www.python.org/)
|
|
9
9
|
[](https://github.com/Kcbir/aniate/actions/workflows/test.yml)
|
|
10
|
+
[](https://aniate.com)
|
|
10
11
|
[](https://github.com/Kcbir/aniate/blob/main/tree.md)
|
|
11
12
|
[](https://github.com/Kcbir/aniate/blob/main/LICENSE)
|
|
12
13
|
|
|
@@ -18,7 +19,61 @@
|
|
|
18
19
|
|
|
19
20
|
---
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
```python
|
|
23
|
+
from aniate import cube, ncube, mdp, nmdp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
| Solver | Solves | Call |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| **NCube** | the TTP-D with a trained network, the neural accelerator | `ncube(nodes, profits, weights, drone=True)` |
|
|
29
|
+
| **Cube** | the TTP-D with the metaheuristic | `cube(nodes, profits, weights, drone=True)` |
|
|
30
|
+
| **cube.milp** | the TTP-D with the exact model | `cube.milp(nodes, profits, weights, drone=True)` |
|
|
31
|
+
| **MDP** | decisions where only the present matters | `mdp(states, actions, transition, reward).solve()` |
|
|
32
|
+
| **NMDP** | decisions where the past matters | `nmdp(world, labels, rule).solve()` |
|
|
33
|
+
|
|
34
|
+
## Cube and NCube
|
|
35
|
+
|
|
36
|
+
Solvers for the Travelling Thief Problem with Drone, from [Drive, Pack, Fly: The Travelling Thief Problem with Drone](https://arxiv.org/abs/2608.16435), by Kabir Murjani and Prof. Abhay Sobhanan. They take the same inputs, and what you leave out decides the problem: with no items it is a TSP-D, with no drone a TTP, and with neither a TSP.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from aniate import cube, ncube
|
|
40
|
+
|
|
41
|
+
nodes = [(0, 0), (4, 1), (5, 4), (1, 5), (2, 2), (3, 3)] # depot first
|
|
42
|
+
profits, weights = [50, 60, 70, 80, 40], [2, 3, 4, 5, 2]
|
|
43
|
+
|
|
44
|
+
ncube(nodes, profits, weights, drone=True) # the neural accelerator, with our weights
|
|
45
|
+
net = ncube.train(30) # or your own, on 30 customers
|
|
46
|
+
ncube(nodes, profits, weights, drone=True, network=net)
|
|
47
|
+
|
|
48
|
+
print(cube(nodes)) # TSP: a truck
|
|
49
|
+
print(cube(nodes, drone=True)) # TSP-D: a truck and a drone
|
|
50
|
+
print(cube(nodes, profits, weights)) # TTP: a truck and a knapsack
|
|
51
|
+
print(cube(nodes, profits, weights, drone=True)) # TTP-D: all three
|
|
52
|
+
|
|
53
|
+
print(cube.milp(nodes, profits, weights, drone=True)) # the exact model, for small problems
|
|
54
|
+
|
|
55
|
+
env = cube.env(nodes, profits, weights, drone=True) # the simulator, one decision at a time
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| input | default | meaning |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `nodes` | required | `(x, y)` pairs, depot first |
|
|
61
|
+
| `profits`, `weights` | none | one value per customer, depot left out; give both or neither |
|
|
62
|
+
| `drone` | `False` | fly a drone from the truck |
|
|
63
|
+
| `endurance` | unlimited | longest flight, launch to customer to landing; setting it turns the drone on |
|
|
64
|
+
| `capacity` | half the total weight | what the truck can carry |
|
|
65
|
+
| `rent` | the rate at which a plain tour costs half of all the profit | cost per unit of time |
|
|
66
|
+
| `drone_speed` | twice the empty truck's speed | setting it turns the drone on |
|
|
67
|
+
| `dist` | straight lines | your own distance matrix, depot first |
|
|
68
|
+
| `seconds` | half a second per customer; one hour for `cube.milp` | time limit for `cube` and `cube.milp`; the paper gives `cube` 15 per customer |
|
|
69
|
+
| `seed` | `0` | `cube` only |
|
|
70
|
+
| `network` | `True`, our weights | `ncube` only; a path to your own, or what `ncube.train` returned |
|
|
71
|
+
|
|
72
|
+
The plan comes back with `route`, `flights`, `items`, `time`, `profit`, `objective`, `problem`, `seconds`, `solver` and, for `cube.milp`, `gap`. `ncube` needs `pip install 'aniate[neural]'` and downloads the closest trained size once from Hugging Face. `ncube.train(problems, examples=100, seconds=None, epochs=60, save=None)` solves each problem with the metaheuristic, then teaches the network to imitate those plans; `problems` is a number of customers, or a list of `(nodes, profits, weights)`. `cube.milp` needs `pip install 'aniate[milp]'` and a Gurobi licence for all but small problems.
|
|
73
|
+
|
|
74
|
+
## MDP and NMDP
|
|
75
|
+
|
|
76
|
+
The decision solvers work with finite problems: Markov decision processes in `mdp`, and problems whose reward depends on the history of the episode in `nmdp`.
|
|
22
77
|
|
|
23
78
|
A problem is specified by its states, actions, transition probabilities, rewards and discount factor. The specification is validated at construction, and a model is rejected when a probability row does not sum to one, when a terminal state continues to move or to accrue reward, or when its value is unbounded. The library computes optimal policies together with their exact values, simulates episodes in batches, and compares any external simulator with the model through per-transition chi-square tests and the value martingale `M_t = G_<t + γ^t V(s_t)`. History-dependent objectives are expressed with event labels and a Mealy automaton, and the exact product model is solved. Every operation writes one structured log line, and every figure is saved as a PDF with embedded Computer Modern fonts.
|
|
24
79
|
|
|
@@ -27,6 +82,18 @@ A problem is specified by its states, actions, transition probabilities, rewards
|
|
|
27
82
|
```bash
|
|
28
83
|
pip install aniate # numpy and scipy
|
|
29
84
|
pip install 'aniate[vis]' # adds matplotlib, required for plots
|
|
85
|
+
pip install 'aniate[gym]' # adds gymnasium, required for aniate.gym
|
|
86
|
+
pip install 'aniate[neural]' # adds PyTorch, required for the neural accelerator
|
|
87
|
+
pip install 'aniate[milp]' # adds Gurobi, required for the exact model
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
For Julia, `cube` is one call too:
|
|
91
|
+
|
|
92
|
+
```julia
|
|
93
|
+
using Pkg; Pkg.add(url="https://github.com/Kcbir/aniate", subdir="julia")
|
|
94
|
+
|
|
95
|
+
using Aniate
|
|
96
|
+
cube(nodes, profits, weights; drone=true)
|
|
30
97
|
```
|
|
31
98
|
|
|
32
99
|
## Verifying the installation
|
|
@@ -39,7 +106,7 @@ ant()
|
|
|
39
106
|
`ant()` prints the Fibonacci drawing, the installed version of Python and of each dependency, and the result of a self-test that builds, solves, simulates and checks a small model. It returns `True` when aniate is working. The same report is printed by `python -m aniate`.
|
|
40
107
|
|
|
41
108
|
```
|
|
42
|
-
aniate 2.0
|
|
109
|
+
aniate 2.2.0 Open source combinatorics solvers
|
|
43
110
|
|
|
44
111
|
python 3.12.4 ok required, 3.10 or later
|
|
45
112
|
numpy 2.1.0 ok required, 1.24 or later
|
|
@@ -47,6 +114,7 @@ scipy 1.14.1 ok required, 1.12 or later
|
|
|
47
114
|
matplotlib - not installed optional, for plots in aniate.vis
|
|
48
115
|
pytest - not installed optional, for running the tests
|
|
49
116
|
hypothesis - not installed optional, for property-based tests
|
|
117
|
+
gymnasium - not installed optional, for the Gymnasium adapter in aniate.gym
|
|
50
118
|
|
|
51
119
|
self-test model valid | solved, value 3.20876 | 2,000 episodes simulated | check passed | 13 ms
|
|
52
120
|
plots unavailable; install them with: pip install 'aniate[vis]'
|
|
@@ -57,10 +125,9 @@ aniate is working.
|
|
|
57
125
|
## Quick start
|
|
58
126
|
|
|
59
127
|
```python
|
|
60
|
-
|
|
61
|
-
from aniate import vis
|
|
128
|
+
from aniate import mdp, vis
|
|
62
129
|
|
|
63
|
-
m =
|
|
130
|
+
m = mdp(
|
|
64
131
|
states=range(5), actions=["left", "right"],
|
|
65
132
|
transition=lambda s, a: {max(s - 1, 0): 1.0} if a == "left" else {min(s + 1, 4): 0.8, s: 0.2},
|
|
66
133
|
reward=lambda s, a, s_next: 10.0 if s_next == 4 else -1.0,
|
|
@@ -68,8 +135,8 @@ m = an.from_functions(
|
|
|
68
135
|
)
|
|
69
136
|
|
|
70
137
|
sol = m.solve() # optimal policy, its exact value, an error bound
|
|
71
|
-
runs =
|
|
72
|
-
report =
|
|
138
|
+
runs = mdp.simulate(m, sol, episodes=10_000) # 10,000 episodes, run in parallel
|
|
139
|
+
report = mdp.check(m, policy=sol) # compares simulated behaviour with the model
|
|
73
140
|
vis.save(vis.overview(runs), "overview.pdf") # four standard plots in one PDF
|
|
74
141
|
m.describe() # the model as a JSON-compatible dict
|
|
75
142
|
```
|
|
@@ -95,38 +162,57 @@ Construction fails, and the error names each offending state and action, if any
|
|
|
95
162
|
| `terminal_not_absorbing` | a terminal state moves to another state or pays a reward |
|
|
96
163
|
| `unbounded_value` | the discount factor is 1 and no terminal state is reachable |
|
|
97
164
|
|
|
98
|
-
`
|
|
165
|
+
`mdp.check(model, env=simulator)` runs episodes through an external simulator and reports `impossible_transition`, `transition_frequency`, `reward_mismatch`, `termination_mismatch` and `return_mismatch`. These properties are verified by runtime checks and by the test suite; they are not formally proved.
|
|
99
166
|
|
|
100
167
|
## History-dependent rewards
|
|
101
168
|
|
|
102
169
|
```python
|
|
103
|
-
from aniate import nmdp
|
|
170
|
+
from aniate import nmdp, problems
|
|
104
171
|
|
|
105
|
-
world =
|
|
172
|
+
world = problems.gridworld(rows=5, cols=5, goals=((0, 4),), start=(4, 0))
|
|
106
173
|
labels = nmdp.Labels(world).at("r4c4", "A").at("r0c4", "B")
|
|
107
|
-
task =
|
|
174
|
+
task = nmdp(world, labels, nmdp.Ordering(["A", "B"], violation_penalty=-1))
|
|
108
175
|
policy = task.solve() # a MemoryPolicy: policy.step(state) returns the next action
|
|
109
176
|
```
|
|
110
177
|
|
|
111
178
|
`nmdp.Ordering`, `nmdp.Budget` and `nmdp.Deadline` cover common patterns, and `nmdp.Mealy` expresses any finite-memory rule.
|
|
112
179
|
|
|
180
|
+
## Notebooks
|
|
181
|
+
|
|
182
|
+
In Jupyter, a model, solution, set of episodes, check report, automaton or non-Markovian task that ends a cell is displayed as a table. A long table is shortened, and the number of omitted rows is stated.
|
|
183
|
+
|
|
184
|
+
## Gymnasium
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
from aniate import gym
|
|
188
|
+
|
|
189
|
+
env = gym.make(m) # a gymnasium.Env with Discrete spaces
|
|
190
|
+
obs, info = env.reset(seed=0)
|
|
191
|
+
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
|
|
192
|
+
|
|
193
|
+
gym.register("aniate/Corridor-v0", lambda: m) # gymnasium.make("aniate/Corridor-v0") then builds it
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Transitions are sampled from the model with the seeded generator of Gymnasium, so equal seeds give equal episodes, and the environment passes the Gymnasium environment checker. The adapter requires `pip install 'aniate[gym]'`.
|
|
197
|
+
|
|
113
198
|
## Interface
|
|
114
199
|
|
|
115
200
|
| call | purpose |
|
|
116
201
|
|---|---|
|
|
117
202
|
| `ant()` | report installed dependencies and run a self-test |
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
203
|
+
| `mdp(states, actions, transition, reward, gamma, terminal=, initial=)` | define a model with Python functions |
|
|
204
|
+
| `mdp.Builder(gamma)` | define a model one transition at a time |
|
|
205
|
+
| `mdp.MDP(P, R, gamma)` | define a model from matrices |
|
|
121
206
|
| `m.solve()` | optimal policy and exact value |
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
207
|
+
| `mdp.evaluate(m, policy)` | exact value of any policy |
|
|
208
|
+
| `mdp.simulate(m, policy, episodes)` | batched episodes, returned as `Episodes` |
|
|
124
209
|
| `m.env()` | a Gym-style environment with `reset` and `step` |
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
210
|
+
| `mdp.check(m, env=simulator, policy=)` | statistical comparison of a simulator with the model |
|
|
211
|
+
| `nmdp(world, labels, automaton)` | a problem whose reward depends on history |
|
|
212
|
+
| `gym.make(m)`, `gym.register(id, model)` | the model as a Gymnasium environment |
|
|
127
213
|
| `vis.overview(runs)`, `vis.graph(m)`, `vis.grid(m, sol)` | plots; `vis.save(fig, "name.pdf")` writes a PDF |
|
|
128
214
|
| `obj.describe()` | a JSON-compatible summary of any model, solution, report or set of episodes |
|
|
129
|
-
| `
|
|
215
|
+
| `aniate.verbosity("quiet")` | set the log level |
|
|
130
216
|
|
|
131
217
|
A decision tree for choosing among these calls, the package layout and the conventions for extending the library are given in [tree.md](https://github.com/Kcbir/aniate/blob/main/tree.md).
|
|
132
218
|
|
|
@@ -151,9 +237,9 @@ Importing aniate prints a Fibonacci rectangle to standard error once per process
|
|
|
151
237
|
```bibtex
|
|
152
238
|
@software{murjani2026aniate,
|
|
153
239
|
author = {Murjani, Kabir},
|
|
154
|
-
title = {aniate:
|
|
240
|
+
title = {aniate: open source combinatorics solvers},
|
|
155
241
|
year = {2026},
|
|
156
|
-
version = {2.0
|
|
242
|
+
version = {2.2.0},
|
|
157
243
|
url = {https://github.com/Kcbir/aniate}
|
|
158
244
|
}
|
|
159
245
|
```
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""aniate: open source combinatorics solvers.
|
|
2
|
+
|
|
3
|
+
from aniate import cube, ncube, mdp, nmdp
|
|
4
|
+
|
|
5
|
+
nodes = [(0, 0), (4, 1), (5, 4), (1, 5), (2, 2), (3, 3)] # depot first
|
|
6
|
+
print(cube(nodes, drone=True))
|
|
7
|
+
|
|
8
|
+
cube plans routes with a metaheuristic, cube.milp with the exact model, and ncube with a neural accelerator.
|
|
9
|
+
mdp solves decisions that depend only on the present, and nmdp those that depend on the past.
|
|
10
|
+
PDF plots live in ``aniate.vis`` (needs matplotlib).
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from aniate import art as _art
|
|
14
|
+
|
|
15
|
+
_art._on_import()
|
|
16
|
+
|
|
17
|
+
from aniate import log, mdp, nmdp, problems # noqa: E402
|
|
18
|
+
from aniate.log import verbosity # noqa: E402
|
|
19
|
+
from aniate.mdp import MDP, Builder, Env, check, evaluate, from_functions, simulate, solve # noqa: E402
|
|
20
|
+
from aniate.nmdp import NMDP # noqa: E402
|
|
21
|
+
from aniate.route import Plan, cube, ncube # noqa: E402
|
|
22
|
+
from aniate.selfcheck import ant # noqa: E402
|
|
23
|
+
|
|
24
|
+
__version__ = "2.2.0"
|
|
25
|
+
|
|
26
|
+
__all__ = ["ant", "cube", "ncube", "Plan", "MDP", "NMDP", "Builder", "from_functions", "Env", "simulate", "check",
|
|
27
|
+
"solve", "evaluate", "verbosity", "log", "mdp", "nmdp", "problems", "__version__"]
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""Gymnasium adapter: any aniate model as a ``gymnasium.Env``.
|
|
2
|
+
|
|
3
|
+
from aniate import gym
|
|
4
|
+
env = gym.make(model) # a gymnasium.Env
|
|
5
|
+
obs, info = env.reset(seed=0)
|
|
6
|
+
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
|
|
7
|
+
|
|
8
|
+
gym.register("aniate/Corridor-v0", build_corridor)
|
|
9
|
+
env = gymnasium.make("aniate/Corridor-v0")
|
|
10
|
+
|
|
11
|
+
Observations and actions are integer positions in ``Discrete`` spaces, which
|
|
12
|
+
is what Gymnasium agents expect; ``observation_label`` and ``action_label``
|
|
13
|
+
translate them back to the model's labels, and ``info`` carries the labels
|
|
14
|
+
as well (the keys of aniate's ``Env``, without its episode counter).
|
|
15
|
+
Transitions are sampled from the model itself with Gymnasium's
|
|
16
|
+
seeded generator, so ``reset(seed=...)`` makes episodes reproducible.
|
|
17
|
+
|
|
18
|
+
Needs gymnasium (``pip install 'aniate[gym]'``).
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
try:
|
|
24
|
+
import gymnasium
|
|
25
|
+
from gymnasium import spaces
|
|
26
|
+
except ImportError as exc: # pragma: no cover
|
|
27
|
+
raise ImportError("aniate.gym needs gymnasium: pip install 'aniate[gym]'") from exc
|
|
28
|
+
|
|
29
|
+
from aniate.mdp.env import Env, _is_product, _unwrap, default_max_steps
|
|
30
|
+
|
|
31
|
+
__all__ = ["AniateEnv", "make", "register"]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class AniateEnv(gymnasium.Env):
|
|
35
|
+
"""A Gymnasium environment that samples from an aniate model.
|
|
36
|
+
|
|
37
|
+
Parameters
|
|
38
|
+
----------
|
|
39
|
+
model : MDP, or an NMDP / non-Markovian model
|
|
40
|
+
max_steps : int, optional
|
|
41
|
+
Truncate episodes after this many steps. Defaults to the horizon, or
|
|
42
|
+
to the step at which ``gamma**t`` falls below 1e-6, as in ``simulate``.
|
|
43
|
+
hide_memory : bool
|
|
44
|
+
Non-Markovian models only: observe the world state (default), and
|
|
45
|
+
report the memory state in ``info["memory"]``.
|
|
46
|
+
render_mode : None or "ansi"
|
|
47
|
+
``"ansi"`` makes ``render()`` return a line describing the last step.
|
|
48
|
+
log : bool
|
|
49
|
+
Write aniate log lines for finished episodes.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
metadata = {"render_modes": ["ansi"], "render_fps": 4}
|
|
53
|
+
|
|
54
|
+
def __init__(self, model, *, max_steps=None, hide_memory=True, render_mode=None, log=False):
|
|
55
|
+
m = _unwrap(model)
|
|
56
|
+
if render_mode is not None and render_mode not in self.metadata["render_modes"]:
|
|
57
|
+
raise ValueError(f"render_mode must be None or 'ansi'; got {render_mode!r}")
|
|
58
|
+
self.model = m
|
|
59
|
+
self.render_mode = render_mode
|
|
60
|
+
self._env = Env(m, max_steps=default_max_steps(m) if max_steps is None else max_steps,
|
|
61
|
+
labels=False, hide_memory=hide_memory and _is_product(m), log=log)
|
|
62
|
+
self.observation_space = spaces.Discrete(len(self._env.states))
|
|
63
|
+
self.action_space = spaces.Discrete(m.A)
|
|
64
|
+
|
|
65
|
+
def observation_label(self, observation):
|
|
66
|
+
"""The state label of an integer observation."""
|
|
67
|
+
return self._env.states[int(observation)]
|
|
68
|
+
|
|
69
|
+
def action_label(self, action):
|
|
70
|
+
"""The action label of an integer action."""
|
|
71
|
+
return self.model.actions[int(action)]
|
|
72
|
+
|
|
73
|
+
def reset(self, *, seed=None, options=None):
|
|
74
|
+
"""Start an episode. ``options={"state": label}`` fixes the start state."""
|
|
75
|
+
super().reset(seed=seed)
|
|
76
|
+
self._env._rng = self.np_random # sample the model with Gymnasium's seeded generator
|
|
77
|
+
obs, info = self._env.reset(state=(options or {}).get("state"))
|
|
78
|
+
return obs, _gym_info(info)
|
|
79
|
+
|
|
80
|
+
def step(self, action):
|
|
81
|
+
if not self.action_space.contains(action):
|
|
82
|
+
raise ValueError(f"action must be an integer in [0, {self.model.A}); got {action!r}")
|
|
83
|
+
env = self._env
|
|
84
|
+
if env._s is None:
|
|
85
|
+
raise RuntimeError("call reset() before step()")
|
|
86
|
+
if env._done:
|
|
87
|
+
raise RuntimeError("this episode is over; call reset()")
|
|
88
|
+
# By position, even when the action labels are themselves integers.
|
|
89
|
+
obs, reward, terminated, truncated, info = env._step(int(action))
|
|
90
|
+
return obs, reward, terminated, truncated, _gym_info(info)
|
|
91
|
+
|
|
92
|
+
def render(self):
|
|
93
|
+
if self.render_mode == "ansi":
|
|
94
|
+
return self._env.render()
|
|
95
|
+
return None
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _gym_info(info):
|
|
99
|
+
"""aniate's ``info`` without the episode counter, so that equal seeds give equal ``info``."""
|
|
100
|
+
info.pop("episode", None)
|
|
101
|
+
return info
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def make(model, **kwargs):
|
|
105
|
+
"""``AniateEnv(model, **kwargs)``: the model as a Gymnasium environment."""
|
|
106
|
+
return AniateEnv(model, **kwargs)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _entry_point(model, **kwargs):
|
|
110
|
+
return AniateEnv(model() if callable(model) else model, **kwargs)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def register(id, model, **kwargs):
|
|
114
|
+
"""Register a model with Gymnasium, so that ``gymnasium.make(id)`` builds it.
|
|
115
|
+
|
|
116
|
+
``model`` is a model, or a function without arguments that returns one;
|
|
117
|
+
the function is called on every ``gymnasium.make``. ``kwargs`` are passed
|
|
118
|
+
to :class:`AniateEnv`.
|
|
119
|
+
"""
|
|
120
|
+
gymnasium.register(id=id, entry_point=_entry_point, kwargs={"model": model, **kwargs})
|
|
@@ -1,4 +1,13 @@
|
|
|
1
|
-
"""Finite Markov decision processes: define, inspect, simulate, check, solve.
|
|
1
|
+
"""Finite Markov decision processes: define, inspect, simulate, check, solve.
|
|
2
|
+
|
|
3
|
+
from aniate import mdp
|
|
4
|
+
|
|
5
|
+
model = mdp(states, actions, transition, reward, gamma=0.9)
|
|
6
|
+
best = model.solve()
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import sys
|
|
10
|
+
from types import ModuleType
|
|
2
11
|
|
|
3
12
|
from aniate.mdp.builder import Builder, from_functions
|
|
4
13
|
from aniate.mdp.check import CheckReport, check
|
|
@@ -21,3 +30,12 @@ __all__ = [
|
|
|
21
30
|
"solve", "evaluate", "values_by_time", "policy_iteration", "value_iteration",
|
|
22
31
|
"backward_induction", "Solution",
|
|
23
32
|
]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class _Callable(ModuleType):
|
|
36
|
+
def __call__(self, *args, **kwargs):
|
|
37
|
+
"""Build a model: the same as `from_functions`."""
|
|
38
|
+
return from_functions(*args, **kwargs)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
sys.modules[__name__].__class__ = _Callable
|
|
@@ -97,6 +97,11 @@ class CheckReport:
|
|
|
97
97
|
return {"kind": "CheckReport", "ok": self.ok, "stats": stats,
|
|
98
98
|
"issues": [i.describe() for i in self.issues]}
|
|
99
99
|
|
|
100
|
+
def _repr_html_(self):
|
|
101
|
+
from aniate.notebook import to_html
|
|
102
|
+
|
|
103
|
+
return to_html(self)
|
|
104
|
+
|
|
100
105
|
def __repr__(self):
|
|
101
106
|
st = self.stats
|
|
102
107
|
head = "PASSED" if self.ok else f"FAILED ({len(self.issues)} issue(s))"
|