ddma 0.12.1__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.
- ddma-0.12.1/LICENSE +22 -0
- ddma-0.12.1/MANIFEST.in +1 -0
- ddma-0.12.1/PKG-INFO +401 -0
- ddma-0.12.1/README.md +345 -0
- ddma-0.12.1/cpp/ddma_abstraction.hpp +349 -0
- ddma-0.12.1/cpp/ddma_core.hpp +211 -0
- ddma-0.12.1/cpp/ddma_growth.hpp +332 -0
- ddma-0.12.1/cpp/ddma_monitor.hpp +635 -0
- ddma-0.12.1/cpp/ddma_parallel.hpp +450 -0
- ddma-0.12.1/cpp/ddma_synthesis.hpp +271 -0
- ddma-0.12.1/cpp/python_binding.cpp +576 -0
- ddma-0.12.1/pyproject.toml +90 -0
- ddma-0.12.1/setup.cfg +4 -0
- ddma-0.12.1/setup.py +103 -0
- ddma-0.12.1/src/ddma/__init__.py +66 -0
- ddma-0.12.1/src/ddma/_bd_components.py +496 -0
- ddma-0.12.1/src/ddma/_box_lp.py +80 -0
- ddma-0.12.1/src/ddma/_monitor_kernels.py +155 -0
- ddma-0.12.1/src/ddma/_signs.py +30 -0
- ddma-0.12.1/src/ddma/abstraction.py +430 -0
- ddma-0.12.1/src/ddma/bounded_derivatives.py +381 -0
- ddma-0.12.1/src/ddma/growth.py +126 -0
- ddma-0.12.1/src/ddma/invariance.py +544 -0
- ddma-0.12.1/src/ddma/monitor.py +998 -0
- ddma-0.12.1/src/ddma/msm.py +143 -0
- ddma-0.12.1/src/ddma/partition.py +207 -0
- ddma-0.12.1/src/ddma/partitioned.py +261 -0
- ddma-0.12.1/src/ddma/plotting.py +175 -0
- ddma-0.12.1/src/ddma/rl.py +193 -0
- ddma-0.12.1/src/ddma/synthesis.py +401 -0
- ddma-0.12.1/src/ddma/threads.py +50 -0
- ddma-0.12.1/src/ddma.egg-info/PKG-INFO +401 -0
- ddma-0.12.1/src/ddma.egg-info/SOURCES.txt +50 -0
- ddma-0.12.1/src/ddma.egg-info/dependency_links.txt +1 -0
- ddma-0.12.1/src/ddma.egg-info/requires.txt +35 -0
- ddma-0.12.1/src/ddma.egg-info/top_level.txt +1 -0
- ddma-0.12.1/tests/test_abstraction_backends.py +262 -0
- ddma-0.12.1/tests/test_bd_methods.py +467 -0
- ddma-0.12.1/tests/test_bounded_derivatives.py +130 -0
- ddma-0.12.1/tests/test_docs.py +42 -0
- ddma-0.12.1/tests/test_growth_cpp.py +113 -0
- ddma-0.12.1/tests/test_growth_map.py +96 -0
- ddma-0.12.1/tests/test_invariance.py +226 -0
- ddma-0.12.1/tests/test_monitor.py +257 -0
- ddma-0.12.1/tests/test_monitor_levels.py +286 -0
- ddma-0.12.1/tests/test_msm.py +112 -0
- ddma-0.12.1/tests/test_partitioned.py +163 -0
- ddma-0.12.1/tests/test_reference_matlab.py +51 -0
- ddma-0.12.1/tests/test_rl.py +109 -0
- ddma-0.12.1/tests/test_synthesis.py +211 -0
- ddma-0.12.1/tests/test_synthesis_backends.py +149 -0
- ddma-0.12.1/tests/test_threads.py +148 -0
ddma-0.12.1/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020–2023 CentraleSupélec
|
|
4
|
+
Copyright (c) 2026 Anas Makdesi
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
ddma-0.12.1/MANIFEST.in
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
include cpp/*.hpp cpp/*.cpp
|
ddma-0.12.1/PKG-INFO
ADDED
|
@@ -0,0 +1,401 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ddma
|
|
3
|
+
Version: 0.12.1
|
|
4
|
+
Summary: Data-driven models and abstractions with guarantees: models of monotone systems and systems with bounded derivatives, symbolic abstractions and correct-by-construction controllers from data.
|
|
5
|
+
Author: Anas Makdesi, Antoine Girard, Laurent Fribourg, Majid Zamani, Saber Jafarpour
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Documentation, https://anas-makdesi.github.io/ddma/
|
|
8
|
+
Project-URL: Source, https://github.com/anas-makdesi/ddma
|
|
9
|
+
Project-URL: Changelog, https://github.com/anas-makdesi/ddma/blob/main/docs/CHANGELOG.md
|
|
10
|
+
Keywords: control,monotone systems,data-driven control,abstraction,formal methods,safety
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
19
|
+
Classifier: Programming Language :: C++
|
|
20
|
+
Classifier: Operating System :: OS Independent
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
22
|
+
Classifier: Intended Audience :: Science/Research
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: numpy>=1.22
|
|
27
|
+
Provides-Extra: examples
|
|
28
|
+
Requires-Dist: matplotlib>=3.5; extra == "examples"
|
|
29
|
+
Requires-Dist: scipy>=1.9; extra == "examples"
|
|
30
|
+
Provides-Extra: lp
|
|
31
|
+
Requires-Dist: scipy>=1.9; extra == "lp"
|
|
32
|
+
Provides-Extra: rl
|
|
33
|
+
Requires-Dist: gymnasium>=0.29; extra == "rl"
|
|
34
|
+
Provides-Extra: rl-demo
|
|
35
|
+
Requires-Dist: gymnasium>=0.29; extra == "rl-demo"
|
|
36
|
+
Requires-Dist: stable-baselines3>=2.0; extra == "rl-demo"
|
|
37
|
+
Requires-Dist: matplotlib>=3.5; extra == "rl-demo"
|
|
38
|
+
Provides-Extra: docs
|
|
39
|
+
Requires-Dist: sphinx>=7; extra == "docs"
|
|
40
|
+
Requires-Dist: furo; extra == "docs"
|
|
41
|
+
Requires-Dist: myst-nb>=1.1; extra == "docs"
|
|
42
|
+
Requires-Dist: sphinx-design; extra == "docs"
|
|
43
|
+
Requires-Dist: sphinx-copybutton; extra == "docs"
|
|
44
|
+
Requires-Dist: jupytext; extra == "docs"
|
|
45
|
+
Requires-Dist: ipykernel; extra == "docs"
|
|
46
|
+
Requires-Dist: matplotlib>=3.5; extra == "docs"
|
|
47
|
+
Requires-Dist: scipy>=1.9; extra == "docs"
|
|
48
|
+
Requires-Dist: gymnasium>=0.29; extra == "docs"
|
|
49
|
+
Provides-Extra: dev
|
|
50
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
51
|
+
Requires-Dist: ruff>=0.4; extra == "dev"
|
|
52
|
+
Requires-Dist: matplotlib>=3.5; extra == "dev"
|
|
53
|
+
Requires-Dist: scipy>=1.9; extra == "dev"
|
|
54
|
+
Requires-Dist: gymnasium>=0.29; extra == "dev"
|
|
55
|
+
Dynamic: license-file
|
|
56
|
+
|
|
57
|
+
# ddma: data-driven models and abstractions
|
|
58
|
+
|
|
59
|
+
**Learn a guaranteed model of an unknown system from data, then synthesize controllers that are provably safe for the real system.**
|
|
60
|
+
|
|
61
|
+
`ddma` implements the minimal simulating maps from
|
|
62
|
+
|
|
63
|
+
> A. Makdesi, A. Girard, L. Fribourg. *Data-Driven Models of Monotone Systems.* IEEE Transactions on Automatic Control, 69, pp. 5294–5309, 2024. [doi:10.1109/TAC.2023.3346793](https://doi.org/10.1109/TAC.2023.3346793)
|
|
64
|
+
|
|
65
|
+
and models of systems that are **not monotone but have bounded derivatives** (TAC 2024, Section III-C, and the five approaches of the PhD thesis, Chapter 3), with the symbolic abstractions and controller synthesis built on top of them (L4DC 2021, ADHS 2021), and **safe envelopes computed straight from data, without a grid** (IFAC World Congress 2026). An **assumption monitor** checks online that new data still agree with the assumptions behind all of these guarantees. More model classes are planned (see the roadmap).
|
|
66
|
+
|
|
67
|
+
**Python and MATLAB.** Both interfaces share one C++ core, they are tested against each other, and the experiments of the three papers and of the thesis chapter are reproduced (see [docs/REPRODUCTION.md](docs/REPRODUCTION.md)). Every feature is in both languages, and the MATLAB results are checked against Python's in CI: see [docs/PARITY.md](docs/PARITY.md) for the name of each function in each language.
|
|
68
|
+
|
|
69
|
+
**Documentation: [anas-makdesi.github.io/ddma](https://anas-makdesi.github.io/ddma/).** The site (Sphinx, sources in `docs/`) has seven tutorials that walk through the toolbox from a scalar map to the assumption monitor, executed on every build so their outputs are those of the current code, with the MATLAB version of each one; and an API reference for both languages, generated from the docstrings and the MATLAB help text. To build it locally: `pip install -e ".[docs]"` and `sphinx-build -b html docs docs/_build/html`, then open `docs/_build/html/index.html`.
|
|
70
|
+
|
|
71
|
+

|
|
72
|
+
|
|
73
|
+
## The idea
|
|
74
|
+
|
|
75
|
+
Suppose part of your system's dynamics is unknown, but you know a little about its shape:
|
|
76
|
+
|
|
77
|
+
- it is **monotone**: larger states and inputs lead to larger next states (true for many thermal, traffic, vehicle and chemical processes); or
|
|
78
|
+
- its **partial derivatives are bounded**: each output changes at most so fast, in each direction, with each state and input (true for most physical systems; the bounds can also be estimated from data, with a probabilistic guarantee);
|
|
79
|
+
- and the disturbance is bounded by known limits.
|
|
80
|
+
|
|
81
|
+
From a set of measured transitions, `ddma` computes a **set-valued model** that is guaranteed to contain the true system. No model class is fitted. For monotone systems the model is:
|
|
82
|
+
|
|
83
|
+
- **sound**: it contains every monotone system that could have produced the data, so it contains the true one;
|
|
84
|
+
- **minimal**: no smaller set-valued model has that guarantee (proved in the TAC paper);
|
|
85
|
+
- **fast to compute**: on a grid with |Q| cells and |K| samples it takes O(|K| log|Q| + |Q|) time, in a compiled C++ kernel: 10 million samples take 0.2 s;
|
|
86
|
+
- **easy to update**: new data refines the model by intersection, without revisiting the old data.
|
|
87
|
+
|
|
88
|
+
For systems with bounded derivatives, five models trade tightness against speed (below); all are sound, can be updated with new data, and the growth-cone models can be updated locally while the system runs.
|
|
89
|
+
|
|
90
|
+
The learned model gives a finite abstraction of the system. Controllers synthesized on it (safety, reach-avoid) carry over to the real system with guarantees.
|
|
91
|
+
|
|
92
|
+
## Example: a safety filter for adaptive cruise control, learned from data
|
|
93
|
+
|
|
94
|
+
A follower car must keep a gap of 10–50 m to a leader whose speed varies anywhere in 13–17 m/s. **The follower's speed dynamics (drag, actuator) are unknown.** We only know they are monotone in speed and acceleration command.
|
|
95
|
+
|
|
96
|
+
From sampled transitions, `ddma` learns the speed dynamics, builds a 6,600-state abstraction and computes the maximal set of states from which safety can be guaranteed against every leader behaviour. The resulting controller is then used as a **safety filter** around a naive cruise controller that ignores the leader.
|
|
97
|
+
|
|
98
|
+

|
|
99
|
+

|
|
100
|
+
|
|
101
|
+
| samples | certified safe region (% of the specification) | learn model | build abstraction | synthesis |
|
|
102
|
+
|---:|---:|---:|---:|---:|
|
|
103
|
+
| 2,000 | 26.7 % | 0.001 s | 0.05 s | 0.003 s |
|
|
104
|
+
| 20,000 | 37.1 % | 0.001 s | 0.04 s | 0.003 s |
|
|
105
|
+
| 200,000 | 38.1 % | 0.007 s | 0.04 s | 0.003 s |
|
|
106
|
+
|
|
107
|
+
Times measured in a cloud container; they vary from run to run.
|
|
108
|
+
|
|
109
|
+
Without the filter, the naive controller drops below the 10 m gap after 9 s and collides at 11.5 s. With the filter, the gap stays above 11 m for the full 200 s.
|
|
110
|
+
|
|
111
|
+
(`python examples/adaptive_cruise_control.py` reproduces the table and figures.)
|
|
112
|
+
|
|
113
|
+
## Systems that are not monotone: bounded derivatives
|
|
114
|
+
|
|
115
|
+
Many dynamics are not monotone: a pendulum's acceleration grows with the angle up to 90° and then falls. What is usually known is how fast each output can change with each variable, i.e. bounds on the partial derivatives. From such bounds and data, `BoundedDerivativeModel` learns a guaranteed model on a grid of cells. It implements the five approaches of the thesis (Chapter 3), chosen with `method=`:
|
|
116
|
+
|
|
117
|
+
| `method=` | idea | when to use it |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `"two_matrix"` (default) | subtract the steepest linear trends so that two monotone functions remain, learn both, intersect | fastest; a cell stays unbounded until some data point lies on the right side of it for both transforms |
|
|
120
|
+
| `"all_matrix"` | the same with every combination of slopes per output (2ⁿ monotone maps, one per orientation) | tighter, bounds every cell |
|
|
121
|
+
| `"growth"` | each sample bounds the function inside a cone set by the derivative bounds; the tightest bound at every grid vertex is computed exactly, in one forward and one backward sweep per axis | as tight as `"all_matrix"`, bounds every cell, can be updated locally online (`update_local`) |
|
|
122
|
+
| `"lin_mono"`, `"lin_growth"` | the same with a small linear program per cell for the final step | tightest; slower on large grids (bounds certified by duality, so solver tolerances cannot make them unsound) |
|
|
123
|
+
|
|
124
|
+

|
|
125
|
+
|
|
126
|
+
With 25 samples and no data near the ends of the interval, both models bound the whole interval; the growth-cone model is tighter, most of all far from the data (mean width 1.24 against 1.51). (`python examples/bounded_derivative_map.py`, or `run examples/bounded_derivative_map` in MATLAB)
|
|
127
|
+
|
|
128
|
+
In two dimensions the model is a pair of staircases, one value per cell, around the unknown function. Here the growth-cone model with the linear-programming step (approach 5) learned from 10⁷ samples of F(z) = cos z₁ + 0.5 cos z₂ + [−0.1, 0.1] on 51 × 51 cells (the example of thesis Section 3.4); the zoom shows the steps:
|
|
129
|
+
|
|
130
|
+

|
|
131
|
+
|
|
132
|
+
**Comparing the five models.** On the two-dimensional example of the thesis, the ranking holds at every amount of data: the growth cones with the linear-programming step are the tightest, and all models get tighter with more data and finer grids. (`python reproductions/thesis_ch3.py`, details in [docs/REPRODUCTION.md](docs/REPRODUCTION.md).)
|
|
133
|
+
|
|
134
|
+

|
|
135
|
+
|
|
136
|
+
**Example: keeping an inverted pendulum upright.** The pendulum's dynamics are learned from 10⁶ transitions on θ ∈ [−2, 2] rad, where they are not monotone, with only the derivative bounds known. On 101 × 101 state cells and 25 input cells, the certified safe region (states from which the pendulum can be kept within the box forever, with torque |u| ≤ 6) covers 16.1 % of the box with the two-matrix model and 17.8 % with the growth cones + LP; every model's controller gives 0 violations in 100 closed-loop runs on the true pendulum.
|
|
137
|
+
|
|
138
|
+

|
|
139
|
+
|
|
140
|
+
| model | learn model | build abstraction | synthesis | safe region |
|
|
141
|
+
|---|---:|---:|---:|---:|
|
|
142
|
+
| `two_matrix` | 0.2 s | 0.1 s | 0.01 s | 16.1 % |
|
|
143
|
+
| `all_matrix` | 1.1 s | 0.1 s | 0.01 s | 17.4 % |
|
|
144
|
+
| `growth` | 0.2 s | 0.1 s | 0.01 s | 17.6 % |
|
|
145
|
+
| `lin_mono` | 23 s | 0.1 s | 0.01 s | 17.6 % |
|
|
146
|
+
| `lin_growth` | 26 s | 0.1 s | 0.01 s | 17.8 % |
|
|
147
|
+
|
|
148
|
+
(`python examples/pendulum_bounded_derivatives.py`; times indicative.)
|
|
149
|
+
|
|
150
|
+
## Reinforcement learning that never violates its constraints
|
|
151
|
+
|
|
152
|
+
`ddma.rl.SafetyFilterWrapper` puts a learned safety controller around any [Gymnasium](https://gymnasium.farama.org) environment: each action of the agent passes unchanged if it is safe and is replaced by the nearest safe action otherwise. From a state in the controller's domain the system stays safe for ever, whatever the agent does, during training as well. In MATLAB, `ddma.safe_step` / `ddma.safe_reset` wrap the step and reset functions of an environment in the form used by the Reinforcement Learning Toolbox (`rlFunctionEnv`).
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
from ddma.rl import SafetyFilterWrapper
|
|
156
|
+
env = SafetyFilterWrapper(gym_env, controller) # controller = ddma.safety(...)
|
|
157
|
+
model = PPO("MlpPolicy", env).learn(100_000) # any agent, any library
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
On the cruise-control task (`ddma.rl.CruiseControlEnv`: drive close to 22 m/s behind a leader that switches between about 13 and 17 m/s; a crash or a lost leader ends the episode), PPO alone crashes or loses the leader 266–319 times while it learns (3 seeds, 100,000 steps each). Inside the filter, built from 200,000 logged transitions without the vehicle model, it has 0 violations in training and evaluation, and ends with a slightly higher return.
|
|
161
|
+
|
|
162
|
+

|
|
163
|
+
|
|
164
|
+
(`python examples/rl_safety_filter.py`, needs `pip install "ddma[rl-demo]"`; MATLAB: `run examples/rl_safety_filter`.)
|
|
165
|
+
|
|
166
|
+
## Safe envelopes without a grid
|
|
167
|
+
|
|
168
|
+
`ddma.invariance` computes a controlled invariant set directly from the transitions, with no partition and no abstraction: every state in the envelope can be kept in it forever, for every disturbance within the bounds, with the inputs the envelope certifies. Two methods:
|
|
169
|
+
|
|
170
|
+
- `monotone_envelope` (monotone systems, lower-closed specifications such as "every temperature at most 26 °C"): the envelope is a union of lower sets, stored as a few corner points, each with the largest input that keeps everything below it there.
|
|
171
|
+
- `embedding_envelope` (any system with bounds on its Jacobian): every pair of data points spans a box; the growth cones of the two points bound where the box can go (an LP, solved here exactly in closed form), and boxes that map into themselves are kept.
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
from ddma import monotone_envelope
|
|
175
|
+
env = monotone_envelope(X, X_next, U, w_lo=0, w_hi=0.15, input_signs=[-1], x_hi=[26, 26, 26])
|
|
176
|
+
env.contains(x) # certified?
|
|
177
|
+
u = env.safe_input(x, u_wanted) # closest certified input (None outside)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Three rooms cooled by one input, unknown heat gains up to 0.15 °C per step, limit 26 °C: from 1,000 transitions the envelope certifies about 98 % of the safe temperature range in under a second; the grid abstraction of `examples/lazy_synthesis.py` certifies about 74 % from 200,000 transitions. For non-monotone systems, 400 transitions of a two-species competition model certify about 84 % of its operating range, and a ring of ten coupled nonlinear units is handled from 1,000 transitions in a fraction of a second.
|
|
181
|
+
|
|
182
|
+

|
|
183
|
+
|
|
184
|
+
(`python examples/envelope_room_cooling.py`, `python examples/envelope_nonlinear.py`; MATLAB: `ddma.monotone_envelope`, `ddma.embedding_envelope`, examples of the same names. Details: [docs/INVARIANCE.md](docs/INVARIANCE.md).)
|
|
185
|
+
|
|
186
|
+
## What if the assumptions are wrong?
|
|
187
|
+
|
|
188
|
+
Every guarantee above holds *if* the system satisfies the assumptions given to the model: a monotonicity pattern, derivative bounds, disturbance bounds. ddma checks data against them before learning (`check_data`: every pair of the learning data) and while the system runs (`AssumptionMonitor`). An alarm is a proof, not a heuristic: no function satisfying the assumptions can produce the data. Each new point is checked against the model's cell bounds, and against every earlier point, in the same step or later, all at once, back at base (`full="later"`, `flush()`). Exact pruning keeps this under a millisecond per step with 2 million stored points. A point that fails is quarantined, so it does not cause follow-up alarms. The monitor computes, for each assumption, the **exact smallest change that alone would explain all the data**, and rules out those that cannot. Then it raises an alarm, widens the assumption (the model is refit, and its guarantee now rests on bounds fitted to the data), switches to a fallback controller, or widens up to a limit and falls back beyond it.
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from ddma import AssumptionMonitor, check_data
|
|
192
|
+
print(check_data(Z, Y, d_lo=d_lo, d_hi=d_hi, signs=signs).report()) # before learning
|
|
193
|
+
mon = AssumptionMonitor.for_model(sigma, Z, Y, on_violation="widen_then_fallback")
|
|
194
|
+
mon.check(z_new, y_new) # every new transition; mon.observe(x, u, x_next) also works
|
|
195
|
+
if mon.fallback_active:
|
|
196
|
+
u = backup(x)
|
|
197
|
+
print(mon.report()) # which level found what, which assumption, by how much
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
In the cruise-control example the assumptions break mid-run, and the monitor catches both problems in the step they happen. When the leader slows to 11 m/s (assumed ≥ 13), the needed change is within the limit: the monitor widens the disturbance bound and recomputes the safe set, 3 steps outside the specification instead of 54. When a trailer is hitched (30 % of the acceleration), the speed noise would have to triple, beyond the limit: the monitor switches to a backup controller, 0 steps outside the specification instead of 6.
|
|
201
|
+
|
|
202
|
+

|
|
203
|
+
|
|
204
|
+
(`python examples/assumption_monitor.py`; MATLAB: `ddma.check_data`, `ddma.monitor`, `ddma.monitor_check`, `run examples/assumption_monitor`. Details and timings: [docs/MONITOR.md](docs/MONITOR.md).)
|
|
205
|
+
|
|
206
|
+
## Install
|
|
207
|
+
|
|
208
|
+
**Python** (3.10 or newer)
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
pip install ddma # pre-built for Linux, macOS and Windows, threads included
|
|
212
|
+
pip install "ddma[examples]" # + matplotlib, scipy (examples and derivative-bound estimation)
|
|
213
|
+
pip install "ddma[rl]" # + gymnasium (the safety filter for reinforcement learning)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The pre-built packages contain the compiled C++ kernels with OpenMP, so there is nothing else to install, also on macOS. On other systems pip builds the kernels from source; without a C++ compiler ddma falls back to NumPy, which gives identical results, only slower. `ddma.compiled_backend_available()` and `ddma.openmp_available()` tell you what you got.
|
|
217
|
+
|
|
218
|
+
The compiled kernels learn models and build abstractions on all cores by default, with results that are bit-identical for any number of threads; `ddma.set_num_threads(n)` limits them. Details: [docs/PERFORMANCE.md](docs/PERFORMANCE.md).
|
|
219
|
+
|
|
220
|
+
From a clone, to run the examples and tests or to change the code:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
git clone https://github.com/anas-makdesi/ddma && cd ddma
|
|
224
|
+
pip install -e ".[dev]" # + pytest and ruff; builds the C++ kernels
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Building from source on macOS needs `brew install libomp` first, otherwise the kernels run on one thread.
|
|
228
|
+
|
|
229
|
+
**MATLAB toolbox** (R2023b or newer)
|
|
230
|
+
|
|
231
|
+
Download `ddma-<version>.mltbx` from the [releases page](https://github.com/anas-makdesi/ddma/releases) and open it in MATLAB, or run `matlab.addons.install("ddma-<version>.mltbx")`. It contains the `+ddma` package, the examples and pre-built MEX files (with threads) for Linux, Windows and macOS on Apple silicon; elsewhere the `.m` code runs, with the same results.
|
|
232
|
+
|
|
233
|
+
**MATLAB / Octave from a clone**
|
|
234
|
+
|
|
235
|
+
```matlab
|
|
236
|
+
cd matlab
|
|
237
|
+
build_mex % optional: compiles the same C++ kernels as MEX files (with threads)
|
|
238
|
+
run examples/acc_safety_filter % the cruise-control example below, in MATLAB
|
|
239
|
+
run examples/pendulum_bounded_derivatives % a non-monotone system: bounded-derivative models
|
|
240
|
+
run examples/online_refinement % learning while running: the safe region grows, 0 violations
|
|
241
|
+
run examples/lazy_synthesis % lazy abstraction: a few percent of the transitions evaluated
|
|
242
|
+
addpath tests; run_tests % checks the MATLAB code against Python reference results
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
The `+ddma` package mirrors the Python API with functions on structs: `ddma.fit`, `ddma.bd_fit` (the five bounded-derivative models; same struct as `ddma.fit`, so it goes straight into `ddma.abstraction`), `ddma.growth_map`, `ddma.estimate_derivative_bounds`, `ddma.bd_update` / `ddma.bd_update_local` / `ddma.abstraction_refresh` / `ddma.safety(..., known_winning)` (online refinement), `ddma.abstraction(..., lazy)`, `ddma.safety`, `ddma.reach_avoid`, `ddma.controller_input` (which includes the safety filter), `ddma.simulate`, and the partition helpers. [docs/PARITY.md](docs/PARITY.md) lists every Python name with its MATLAB counterpart.
|
|
246
|
+
|
|
247
|
+
## Quick start
|
|
248
|
+
|
|
249
|
+
```python
|
|
250
|
+
import numpy as np
|
|
251
|
+
from ddma import MinimalSimulatingMap, PartitionedSimulatingMap, RectangularPartition
|
|
252
|
+
|
|
253
|
+
# data from an unknown monotone map with disturbance in [-0.1, 0.1]
|
|
254
|
+
rng = np.random.default_rng(0)
|
|
255
|
+
Z = rng.uniform(0, 1, size=(1000, 2))
|
|
256
|
+
Y = Z[:, :1] ** 2 + np.tanh(Z[:, 1:]) + rng.uniform(-0.1, 0.1, size=(1000, 1))
|
|
257
|
+
|
|
258
|
+
# exact minimal simulating map, evaluated pointwise
|
|
259
|
+
S = MinimalSimulatingMap(Z, Y, d_lo=-0.1, d_hi=0.1)
|
|
260
|
+
lo, hi = S.bounds([[0.5, 0.5]]) # every consistent system maps (0.5, 0.5) into [lo, hi]
|
|
261
|
+
|
|
262
|
+
# the same on a fixed 50 x 50 grid, computed once for all cells
|
|
263
|
+
grid = RectangularPartition.uniform([0, 0], [1, 1], [50, 50])
|
|
264
|
+
sigma = PartitionedSimulatingMap.from_data(Z, Y, grid, d_lo=-0.1, d_hi=0.1)
|
|
265
|
+
sigma = sigma.update(Z_new, Y_new) # refine later with new data (Z_new, Y_new)
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
From a model to a controller, for x⁺ ∈ f(x, u) + g(x, u) + D with f unknown and monotone, and g known:
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
from ddma import SymbolicAbstraction, affine_bounds, safety, transitions_to_data
|
|
272
|
+
|
|
273
|
+
Zd, Y = transitions_to_data(X, U, X_next, g) # y = x' - g(x, u)
|
|
274
|
+
sigma = PartitionedSimulatingMap.from_data(Zd, Y, RectangularPartition.product(Xgrid, Ugrid),
|
|
275
|
+
d_lo, d_hi)
|
|
276
|
+
abst = SymbolicAbstraction(Xgrid, Ugrid, sigma, g_bounds=affine_bounds(A, B))
|
|
277
|
+
ctrl = safety(abst, abst.cells_inside(safe_lo, safe_hi))
|
|
278
|
+
|
|
279
|
+
u = ctrl.filter(x, u_nominal) # closest certified-safe input to u_nominal
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
When f is not monotone but its partial derivatives are bounded (df_i/dx_j in [A_lo, A_hi], df_i/du_j in [B_lo, B_hi]), the model replaces the simulating map, and g is passed to it:
|
|
283
|
+
|
|
284
|
+
```python
|
|
285
|
+
from ddma import BoundedDerivativeModel, estimate_derivative_bounds
|
|
286
|
+
|
|
287
|
+
# bounds known from physics, or estimated from data (scenario approach):
|
|
288
|
+
# a_lo, a_hi, w = estimate_derivative_bounds(np.hstack([X, U]), X_next - g(X, U))
|
|
289
|
+
grid = RectangularPartition.product(Xgrid, Ugrid)
|
|
290
|
+
model = BoundedDerivativeModel.from_data(X, U, X_next, grid, A_lo, A_hi, B_lo, B_hi,
|
|
291
|
+
d_lo, d_hi, g=g, g_bounds=affine_bounds(A, B),
|
|
292
|
+
method="growth")
|
|
293
|
+
abst = SymbolicAbstraction(Xgrid, Ugrid, model)
|
|
294
|
+
ctrl = safety(abst, abst.cells_inside(safe_lo, safe_hi))
|
|
295
|
+
|
|
296
|
+
# online: refine near new data, update only what changed, keep the old safe set
|
|
297
|
+
model.update_local(x_new, u_new, x_next_new, window=3)
|
|
298
|
+
abst.refresh()
|
|
299
|
+
ctrl = safety(abst, abst.cells_inside(safe_lo, safe_hi), known_winning=ctrl.domain)
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
For one scalar function on its own (e.g. a vehicle's turn rate as a function of speed and steering), `GrowthMap` is the same growth-cone model without the system structure:
|
|
303
|
+
|
|
304
|
+
```python
|
|
305
|
+
from ddma import GrowthMap
|
|
306
|
+
|
|
307
|
+
grid = RectangularPartition.uniform([0.1, -0.79], [2.0, 0.79], [40, 40]) # (speed, steering)
|
|
308
|
+
w = GrowthMap.from_data(Z, y, grid, g_lo=[-10, 1], g_hi=[10, 40], d_lo=-0.05, d_hi=0.05)
|
|
309
|
+
lo, hi = w.bounds(z_query) # guaranteed bounds on f(z) + d at the cells of z_query
|
|
310
|
+
w.update(z_new[None], [y_new]) # one measurement at a time: about 0.1 ms on this grid
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
## What's in the package
|
|
314
|
+
|
|
315
|
+
| module | contents | source |
|
|
316
|
+
|---|---|---|
|
|
317
|
+
| `MinimalSimulatingMap` | exact minimal simulating map, bounds on f, set-membership estimate, merging data sets, consistency check of the monotonicity assumption | TAC paper |
|
|
318
|
+
| `PartitionedSimulatingMap` | tightest interval map on a fixed rectangular partition (O(\|K\| log\|Q\| + \|Q\|) sweep), incremental updates; the data-induced partition recovers the exact minimal map | TAC paper |
|
|
319
|
+
| sign patterns (`signs=`) | known increasing (+1) / decreasing (−1) / no (0) dependence per output and input | ±1: order transformation for unknown linear functions (thesis Ch. 2); 0: extension in this package |
|
|
320
|
+
| `SymbolicAbstraction` | finite abstraction of x⁺ ∈ f(x,u) + g(x,u) + D; successors stored as boxes of cells; `features=` for unknown parts that depend on a subset of (x, u) | L4DC 2021, ADHS 2021, TAC paper |
|
|
321
|
+
| `ddma.rl.SafetyFilterWrapper`, `CruiseControlEnv` | certified safety filter around any Gymnasium environment (actions corrected to the nearest safe one; initial states redrawn into the controller's domain; optional penalty per correction); a cruise-control RL benchmark | |
|
|
322
|
+
| `ddma.invariance`: `monotone_envelope`, `embedding_envelope` | safe envelopes (controlled invariant sets) from data without a grid: maximal corners of lower sets for monotone systems (layered search with dominance pruning + sort-filter skyline, equal to exhaustive enumeration); invariant boxes spanned by pairs of data points for systems with bounded Jacobians (the pair LP solved exactly in closed form); `contains`, `safe_input` | IFAC WC 2026 (Makdesi & Zamani; Makdesi, Zamani & Jafarpour) |
|
|
323
|
+
| `check_data`, `AssumptionMonitor` | check of the learning data (every pair) and online check of new transitions against the model's signs, derivative bounds and disturbance bounds: model cell bounds, random sample, full check (every step or later with `flush()`), exact pruning in the C++ core; quarantine; exact smallest single change of each assumption that explains the data; responses alarm / widen / fallback / widen-then-fallback; plain-words `report()` | this package |
|
|
324
|
+
| `safety`, `reach_avoid` | maximal controlled invariant set; reach-avoid with step counts. Exact fixed points in the C++ core: summed-area tables check a successor box in O(2^n); in `safety` each state keeps a pointer to its first input not yet ruled out, so every state–input pair is examined at most once over the whole fixed point; `reach_avoid` re-examines a state only when its successor hull gained a winning cell | standard fixed points |
|
|
325
|
+
| `SymbolicAbstraction(..., lazy=True)` | no transitions stored: `safety` evaluates a transition only when its scan reaches it (states outside the safe set are never expanded, each state stops at its first good input). Memory O(\|Q\|) instead of O(\|Q\|·\|P\|); the controller computes its allowed inputs on demand. Same winning set | standard fixed point, transitions computed on demand |
|
|
326
|
+
| `Controller` | concrete inputs (`pick=`), **safety filter** (`filter`), closed-loop `simulate` | |
|
|
327
|
+
| `BoundedDerivativeModel` | unknown dynamics that are *not* monotone but have bounded partial derivatives. `method=`: `"two_matrix"` (two monotone maps, intersected; default), `"all_matrix"` (all sign combinations of the derivative bounds), `"growth"` (growth cones evaluated at the grid vertices, exact set-membership values there in one sweep per axis), and `"lin_mono"`, `"lin_growth"` (the same with a linear-programming final step, tightest). `update` adds data exactly; `update_local` (growth cones) updates only a window of cells around each new point, for online use. `local="cell"` / `"slab"` (growth cones) also intersects with the cones of the data points in each cell / in its slabs; `"slab"` is never looser than the min over data of each cone's max over the cell | TAC, Prop. 8; thesis Ch. 3 |
|
|
328
|
+
| `GrowthMap` | the growth-cone model for one scalar function on its own: exact `update` (a per-point path for online use gives the same model as a batch refit), `update_local`, `bounds`, `f_bounds` | thesis Ch. 3 |
|
|
329
|
+
| online refinement | `SymbolicAbstraction.refresh()` recomputes only the transitions of the states changed by `update_local`; `safety(..., known_winning=previous_set)` updates the maximal invariant set exactly, keeping the previous set (which stays controlled invariant when the model is refined) | |
|
|
330
|
+
| `estimate_derivative_bounds`, `scenario_confidence` | derivative and disturbance bounds from data, with the scenario-approach guarantee | TAC, Sec. IV, Prop. 9 |
|
|
331
|
+
| `SymbolicAbstraction(..., assumption=)` | assume-guarantee contracts (e.g. "if the leader's speed stays in [a, b] …") | ADHS, TAC |
|
|
332
|
+
| `cpp/ddma_core.hpp`, `cpp/ddma_synthesis.hpp`, `cpp/ddma_growth.hpp`, `cpp/ddma_abstraction.hpp`, `cpp/ddma_parallel.hpp` | header-only C++ kernels used by both the Python and MATLAB interfaces: map fitting (float64, or float32 with outward rounding), the abstraction's transitions, the synthesis fixed points, and the growth-cone fits (vertex values and the cell/slab maps, the latter in time independent of the slab size); the learning kernels and the abstraction run on several threads (OpenMP, optional), with results that do not depend on the number of threads | |
|
|
333
|
+
| `set_num_threads`, `get_num_threads`, `openmp_available` | number of threads of the learning kernels and the abstraction (default: all cores) | |
|
|
334
|
+
| `ddma.plotting` | paper-style figures: transparent staircase bounds, 3-D and 2-D sets | |
|
|
335
|
+
|
|
336
|
+
## Reproducing the papers
|
|
337
|
+
|
|
338
|
+
`reproductions/` re-runs the numerical experiments of L4DC 2021, ADHS 2021, TAC 2024 and Chapter 3 of the thesis, and [docs/REPRODUCTION.md](docs/REPRODUCTION.md) compares the results with the papers. Highlights:
|
|
339
|
+
|
|
340
|
+
- TAC Figs. 9–10: µ = 2.70 → 2.47 as the data grow from 10⁶ to 10⁷ samples, matching the paper.
|
|
341
|
+
- L4DC: the exact abstraction from 300 transitions (27 million state–input pairs) and its invariant set take 6 s instead of 923 s + 341 s.
|
|
342
|
+
- TAC Lorenz example at the paper's full size (10⁸ samples, 104 million cells) on an 8 GB machine: 223 s instead of 929 s, using per-output inputs, float32 bounds and batched data. Its maximal controlled invariant set (1 million states × 101 inputs) then takes 6 s.
|
|
343
|
+
- Thesis Ch. 3: the five bounded-derivative approaches rank as in the thesis at every data size (Lin + Growth tightest); all contain the true map.
|
|
344
|
+
- Every synthesized controller is checked in closed loop on the true plant: 0 violations.
|
|
345
|
+
- Settings the papers leave implicit (L4DC input range, ADHS experiment settings, LP weighting for the Lorenz example) are documented in the report.
|
|
346
|
+
|
|
347
|
+
## How it's tested
|
|
348
|
+
|
|
349
|
+
The Python tests are in `tests/` and run in under a minute with `pytest`. They check the guarantees rather than the outputs alone:
|
|
350
|
+
|
|
351
|
+
- **Soundness**: the true system lies inside the learned map on thousands of random queries, for random monotone functions and sign patterns.
|
|
352
|
+
- **Minimality**: the bounds are attained by monotone functions consistent with the data.
|
|
353
|
+
- **Fast algorithms against brute force**: the grid sweep equals the theorem's formula exactly, on random non-uniform partitions with data on cell edges and outside the box. Safety and reach-avoid fixed points equal the textbook iterations (sets, step counts and allowed inputs) on random abstractions in dimensions 1–4, with every index type, in both backends.
|
|
354
|
+
- **Bounded-derivative models**: all five approaches are sound for random functions with bounded derivatives, with data outside the box and a known part g. The growth-cone vertex values equal the set-membership bounds computed by brute force over all data, and the cell bounds equal their definition; restricted to two sign matrices, the all-matrix model equals the two-matrix one; `update` equals a refit on all data; the windowed update tightens exactly the window. The linear-programming final steps are certified by weak duality, so solver tolerances cannot make them unsound.
|
|
355
|
+
- **Original implementation**: the grid algorithm reproduces the original MATLAB implementation (`Data2Sigma0` + `ApproximationMonotoneSystemData3`) bit for bit on random problems.
|
|
356
|
+
- **Backends and languages**: the C++ and NumPy backends are bit-identical. The MATLAB code, both pure `.m` and MEX, reproduces the Python results exactly (map, abstraction, safety, reach-avoid; the five bounded-derivative models to within 1e-15, and their online updates), and the MEX fixed points equal the `.m` ones on random 1-D to 3-D abstractions. It has been run in MATLAB (MATLAB Online: tests, examples and figures) and CI runs it under Octave.
|
|
357
|
+
- **Safe envelopes**: the monotone search equals brute-force enumeration; the closed-form pair bound equals an LP solver; every certified corner or box is pushed through the true dynamics with random inputs and worst-case disturbances, and closed loops from thousands of certified states never leave the envelope (Python and MATLAB, MATLAB checked against Python).
|
|
358
|
+
- **Assumption monitor**: correct assumptions never raise an alarm (all model types and methods); a wrong sign, a too-small derivative bound, a missing dependence and a larger disturbance are each detected, and the computed smallest change matches the true value; it is exact (equal to bisection with a full consistency check, and to brute force over all pairs). `check_data` equals brute force and finds corrupted points; each level detects what it should; checking later with `flush()` gives the same result as checking every step; quarantine prevents follow-up alarms; the widening limit switches to fallback. C++ (with and without pruning, any number of threads), NumPy and MATLAB (`.m` and MEX) give the same bits; MATLAB draws the same random samples as Python.
|
|
359
|
+
- **Threads**: every learning kernel gives the same bits with 1, 2 and all threads and with every way of sharing the work among them, in Python and MATLAB, and the same bits as the earlier single-threaded kernels. The compiled abstraction equals the NumPy and `.m` code on every kind of model, `g`, assumption and partition, for any number of threads. CI builds with and without OpenMP (on demand also on macOS and Windows).
|
|
360
|
+
- **Documentation**: the tutorials are executed on every CI run (a failing cell or a Sphinx warning fails the build), their MATLAB snippets run under Octave, and every public Python name must have a docstring.
|
|
361
|
+
- **Closed loop**: simulated trajectories under the synthesized controllers and the safety filter never leave the safe set and always reach the target.
|
|
362
|
+
|
|
363
|
+
## Roadmap
|
|
364
|
+
|
|
365
|
+
Next: pre-built wheels and a MATLAB toolbox file. See [docs/ROADMAP.md](docs/ROADMAP.md).
|
|
366
|
+
|
|
367
|
+
## Authors
|
|
368
|
+
|
|
369
|
+
- **Anas Makdesi**: implementation and maintenance.
|
|
370
|
+
- **Antoine Girard** (Université Paris-Saclay, CNRS, CentraleSupélec, L2S) and **Laurent Fribourg** (Université Paris-Saclay, CNRS, ENS Paris-Saclay, LMF): co-authors of the methods implemented here (L4DC 2021, ADHS 2021, TAC 2024) and supervisors of the PhD thesis.
|
|
371
|
+
- **Majid Zamani** (University of Colorado Boulder; LMU Munich) and **Saber Jafarpour** (University of Colorado Boulder): co-authors of the safe-envelope methods (`ddma.invariance`, IFAC World Congress 2026).
|
|
372
|
+
|
|
373
|
+
The methods come from the papers above. This package was rewritten from the original MATLAB research code with the help of Claude (Anthropic): the Python package, the C++ core, the MATLAB interface, the tests and the reproductions of the papers' experiments.
|
|
374
|
+
|
|
375
|
+
## Citing
|
|
376
|
+
|
|
377
|
+
If you use this software, please cite the TAC paper (see `CITATION.cff`), for the bounded-derivative models also the thesis, and for the safe envelopes the IFAC 2026 papers (Makdesi & Zamani, *Data-driven synthesis of controlled invariant sets for monotone systems*; Makdesi, Zamani & Jafarpour, *Data-driven controlled invariance via monotone embeddings*):
|
|
378
|
+
|
|
379
|
+
```bibtex
|
|
380
|
+
@article{makdesi2024datadriven,
|
|
381
|
+
title = {Data-Driven Models of Monotone Systems},
|
|
382
|
+
author = {Makdesi, Anas and Girard, Antoine and Fribourg, Laurent},
|
|
383
|
+
journal = {IEEE Transactions on Automatic Control},
|
|
384
|
+
volume = {69},
|
|
385
|
+
pages = {5294--5309},
|
|
386
|
+
year = {2024},
|
|
387
|
+
doi = {10.1109/TAC.2023.3346793}
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
@phdthesis{makdesi2023thesis,
|
|
391
|
+
title = {Data-driven abstractions for the safe learning of nonlinear systems},
|
|
392
|
+
author = {Makdesi, Anas},
|
|
393
|
+
school = {Universit{\'e} Paris-Saclay},
|
|
394
|
+
year = {2023},
|
|
395
|
+
note = {NNT 2023UPASG103, HAL tel-04611772}
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## License
|
|
400
|
+
|
|
401
|
+
MIT, see `LICENSE`.
|