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.
Files changed (85) hide show
  1. {aniate-2.0.2/aniate.egg-info → aniate-2.2.0}/PKG-INFO +119 -27
  2. {aniate-2.0.2 → aniate-2.2.0}/README.md +108 -22
  3. aniate-2.2.0/aniate/__init__.py +27 -0
  4. aniate-2.2.0/aniate/gym.py +120 -0
  5. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/__init__.py +19 -1
  6. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/check.py +5 -0
  7. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/core.py +8 -1
  8. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/env.py +6 -1
  9. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/solution.py +5 -0
  10. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/validate.py +7 -2
  11. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/__init__.py +12 -0
  12. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/machine.py +5 -0
  13. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/policy.py +5 -0
  14. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/task.py +5 -0
  15. aniate-2.2.0/aniate/notebook.py +286 -0
  16. aniate-2.2.0/aniate/route/__init__.py +229 -0
  17. aniate-2.2.0/aniate/route/core.py +546 -0
  18. aniate-2.2.0/aniate/route/exact.py +142 -0
  19. aniate-2.2.0/aniate/route/metaheuristic.py +71 -0
  20. aniate-2.2.0/aniate/route/network/__init__.py +109 -0
  21. aniate-2.2.0/aniate/route/network/attention.py +466 -0
  22. aniate-2.2.0/aniate/route/network/base.py +19 -0
  23. aniate-2.2.0/aniate/route/network/beam.py +109 -0
  24. aniate-2.2.0/aniate/route/network/decode.py +141 -0
  25. aniate-2.2.0/aniate/route/network/decoder.py +226 -0
  26. aniate-2.2.0/aniate/route/network/encoder.py +71 -0
  27. aniate-2.2.0/aniate/route/network/instance.py +38 -0
  28. aniate-2.2.0/aniate/route/network/masking.py +109 -0
  29. aniate-2.2.0/aniate/route/network/model.py +224 -0
  30. aniate-2.2.0/aniate/route/network/simulator.py +346 -0
  31. aniate-2.2.0/aniate/route/network/train.py +152 -0
  32. {aniate-2.0.2 → aniate-2.2.0}/aniate/selfcheck.py +3 -2
  33. {aniate-2.0.2 → aniate-2.2.0/aniate.egg-info}/PKG-INFO +119 -27
  34. {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/SOURCES.txt +22 -14
  35. {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/requires.txt +10 -1
  36. {aniate-2.0.2 → aniate-2.2.0}/pyproject.toml +10 -6
  37. aniate-2.2.0/tests/test_gym.py +85 -0
  38. aniate-2.2.0/tests/test_notebook.py +64 -0
  39. aniate-2.2.0/tests/test_route.py +142 -0
  40. aniate-2.0.2/MANIFEST.in +0 -2
  41. aniate-2.0.2/aniate/__init__.py +0 -25
  42. aniate-2.0.2/conftest.py +0 -8
  43. aniate-2.0.2/tests/gaussian/plane.py +0 -49
  44. aniate-2.0.2/tests/gaussian/plot.py +0 -65
  45. aniate-2.0.2/tests/gaussian/test_gaussian.py +0 -37
  46. aniate-2.0.2/tests/heavy_tail/plot.py +0 -75
  47. aniate-2.0.2/tests/heavy_tail/test_heavy_tail.py +0 -42
  48. aniate-2.0.2/tests/heavy_tail/warehouse.py +0 -67
  49. aniate-2.0.2/tests/strategies.py +0 -79
  50. aniate-2.0.2/tests/stsp/plot.py +0 -62
  51. aniate-2.0.2/tests/stsp/route.py +0 -78
  52. aniate-2.0.2/tests/stsp/test_stsp.py +0 -28
  53. aniate-2.0.2/tree.md +0 -183
  54. {aniate-2.0.2 → aniate-2.2.0}/LICENSE +0 -0
  55. {aniate-2.0.2 → aniate-2.2.0}/aniate/__main__.py +0 -0
  56. {aniate-2.0.2 → aniate-2.2.0}/aniate/art.py +0 -0
  57. {aniate-2.0.2 → aniate-2.2.0}/aniate/log.py +0 -0
  58. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/builder.py +0 -0
  59. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/policies.py +0 -0
  60. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/solve.py +0 -0
  61. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/space.py +0 -0
  62. {aniate-2.0.2 → aniate-2.2.0}/aniate/mdp/text.py +0 -0
  63. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/builders.py +0 -0
  64. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/labels.py +0 -0
  65. {aniate-2.0.2 → aniate-2.2.0}/aniate/nmdp/product.py +0 -0
  66. {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/__init__.py +0 -0
  67. {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/classic.py +0 -0
  68. {aniate-2.0.2 → aniate-2.2.0}/aniate/problems/gridworld.py +0 -0
  69. {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/__init__.py +0 -0
  70. {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/diagrams.py +0 -0
  71. {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/grid.py +0 -0
  72. {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/stats.py +0 -0
  73. {aniate-2.0.2 → aniate-2.2.0}/aniate/vis/style.py +0 -0
  74. {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/dependency_links.txt +0 -0
  75. {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/entry_points.txt +0 -0
  76. {aniate-2.0.2 → aniate-2.2.0}/aniate.egg-info/top_level.txt +0 -0
  77. {aniate-2.0.2 → aniate-2.2.0}/setup.cfg +0 -0
  78. {aniate-2.0.2 → aniate-2.2.0}/tests/test_ant.py +0 -0
  79. {aniate-2.0.2 → aniate-2.2.0}/tests/test_art.py +0 -0
  80. {aniate-2.0.2 → aniate-2.2.0}/tests/test_env.py +0 -0
  81. {aniate-2.0.2 → aniate-2.2.0}/tests/test_log.py +0 -0
  82. {aniate-2.0.2 → aniate-2.2.0}/tests/test_model.py +0 -0
  83. {aniate-2.0.2 → aniate-2.2.0}/tests/test_nmdp.py +0 -0
  84. {aniate-2.0.2 → aniate-2.2.0}/tests/test_solve.py +0 -0
  85. {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.2
4
- Summary: Approximate Numerics in Applied Transition Environments: define, simulate, check, solve and plot MDPs and non-Markovian decision problems.
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://github.com/Kcbir/aniate
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
- *Approximate Numerics in Applied Transition Environments*
49
+ *Open source combinatorics solvers*
44
50
 
45
51
  [![pypi](https://img.shields.io/pypi/v/aniate?label=pypi&logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/aniate/)
46
52
  [![python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
47
53
  [![tests](https://img.shields.io/github/actions/workflow/status/Kcbir/aniate/test.yml?branch=main&label=tests&logo=github)](https://github.com/Kcbir/aniate/actions/workflows/test.yml)
54
+ [![website](https://img.shields.io/badge/website-aniate.com-5A7B55)](https://aniate.com)
48
55
  [![guide](https://img.shields.io/badge/guide-tree.md-B03A2E)](https://github.com/Kcbir/aniate/blob/main/tree.md)
49
56
  [![licence](https://img.shields.io/badge/licence-MIT-555555)](https://github.com/Kcbir/aniate/blob/main/LICENSE)
50
57
 
@@ -56,7 +63,61 @@ Dynamic: license-file
56
63
 
57
64
  ---
58
65
 
59
- Reference implementation of aniate, a Python library for finite decision problems: Markov decision processes and problems whose reward depends on the history of the episode.
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.2 Approximate Numerics in Applied Transition Environments
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
- import aniate as an
99
- from aniate import vis
172
+ from aniate import mdp, vis
100
173
 
101
- m = an.from_functions(
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 = an.simulate(m, sol, episodes=10_000) # 10,000 episodes, run in parallel
110
- report = an.check(m, policy=sol) # compares simulated behaviour with the model
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
- `an.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.
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 = an.problems.gridworld(rows=5, cols=5, goals=((0, 4),), start=(4, 0))
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 = an.NMDP(world, labels, nmdp.Ordering(["A", "B"], violation_penalty=-1))
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
- | `an.from_functions(states, actions, transition, reward, gamma, terminal=, initial=)` | define a model with Python functions |
157
- | `an.Builder(gamma)` | define a model one transition at a time |
158
- | `an.MDP(P, R, gamma)` | define a model from matrices |
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
- | `an.evaluate(m, policy)` | exact value of any policy |
161
- | `an.simulate(m, policy, episodes)` | batched episodes, returned as `Episodes` |
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
- | `an.check(m, env=simulator, policy=)` | statistical comparison of a simulator with the model |
164
- | `an.NMDP(world, labels, automaton)` | a problem whose reward depends on history |
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
- | `an.verbosity("quiet")` | set the log level |
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: Approximate Numerics in Applied Transition Environments},
284
+ title = {aniate: open source combinatorics solvers},
193
285
  year = {2026},
194
- version = {2.0.2},
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
- *Approximate Numerics in Applied Transition Environments*
5
+ *Open source combinatorics solvers*
6
6
 
7
7
  [![pypi](https://img.shields.io/pypi/v/aniate?label=pypi&logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/aniate/)
8
8
  [![python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
9
9
  [![tests](https://img.shields.io/github/actions/workflow/status/Kcbir/aniate/test.yml?branch=main&label=tests&logo=github)](https://github.com/Kcbir/aniate/actions/workflows/test.yml)
10
+ [![website](https://img.shields.io/badge/website-aniate.com-5A7B55)](https://aniate.com)
10
11
  [![guide](https://img.shields.io/badge/guide-tree.md-B03A2E)](https://github.com/Kcbir/aniate/blob/main/tree.md)
11
12
  [![licence](https://img.shields.io/badge/licence-MIT-555555)](https://github.com/Kcbir/aniate/blob/main/LICENSE)
12
13
 
@@ -18,7 +19,61 @@
18
19
 
19
20
  ---
20
21
 
21
- Reference implementation of aniate, a Python library for finite decision problems: Markov decision processes and problems whose reward depends on the history of the episode.
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.2 Approximate Numerics in Applied Transition Environments
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
- import aniate as an
61
- from aniate import vis
128
+ from aniate import mdp, vis
62
129
 
63
- m = an.from_functions(
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 = an.simulate(m, sol, episodes=10_000) # 10,000 episodes, run in parallel
72
- report = an.check(m, policy=sol) # compares simulated behaviour with the model
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
- `an.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.
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 = an.problems.gridworld(rows=5, cols=5, goals=((0, 4),), start=(4, 0))
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 = an.NMDP(world, labels, nmdp.Ordering(["A", "B"], violation_penalty=-1))
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
- | `an.from_functions(states, actions, transition, reward, gamma, terminal=, initial=)` | define a model with Python functions |
119
- | `an.Builder(gamma)` | define a model one transition at a time |
120
- | `an.MDP(P, R, gamma)` | define a model from matrices |
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
- | `an.evaluate(m, policy)` | exact value of any policy |
123
- | `an.simulate(m, policy, episodes)` | batched episodes, returned as `Episodes` |
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
- | `an.check(m, env=simulator, policy=)` | statistical comparison of a simulator with the model |
126
- | `an.NMDP(world, labels, automaton)` | a problem whose reward depends on history |
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
- | `an.verbosity("quiet")` | set the log level |
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: Approximate Numerics in Applied Transition Environments},
240
+ title = {aniate: open source combinatorics solvers},
155
241
  year = {2026},
156
- version = {2.0.2},
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))"