virtualmodelcontrol 1.1.0__tar.gz → 1.2.0__tar.gz

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/) (0.x: the API may change between minor versions).
 
+## [1.2.0] - 2026-10-09
+
+A robot that runs for hours: the log of a real-time run can keep only its last seconds. Nothing that
+worked before changes.
+
+### Added
+
+- `sim.run(..., window=)`: on real time, a run that goes on for hours keeps only the last `window`
+  seconds of its log (up to a quarter more, until the next trim) instead of every step in memory;
+  `info["steps"]` still counts them all, and a Ctrl-C keeps only whole steps.
+- `RunLog.crop(t_min, t_max)`: the steps of a time window as a new log, with the same `info` and
+  `meta`; an end left out is open.
+
 ## [1.1.0] - 2026-10-09
 
 Static friction of the motors: a model of it, a compensation for it, its identification and a

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: virtualmodelcontrol
-Version: 1.1.0
+Version: 1.2.0
 Summary: Virtual Model Control: robots and controllers as mechanisms of springs, dampers and inertances, compiled with CasADi.
 Project-URL: Repository, https://github.com/vigno0405/VirtualModelControl
 Project-URL: Documentation, https://vigno0405.github.io/VirtualModelControl/

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/docs/installation.md

@@ -120,10 +120,10 @@ pip install -e .
 An experiment should always run the same code. Pin the version, and move the pin on purpose:
 
 ```bash
-pip install "virtualmodelcontrol==1.1.0"
+pip install "virtualmodelcontrol==1.2.0"
 ```
 
-In a `requirements.txt` file, write `virtualmodelcontrol==1.1.0`. In a conda `environment.yml`,
+In a `requirements.txt` file, write `virtualmodelcontrol==1.2.0`. In a conda `environment.yml`,
 list it under `pip:`. `pip show virtualmodelcontrol` tells you which version you have, and the
 [changelog](development/changelog.md) what changed between versions.
 

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/docs/troubleshooting.md

@@ -32,7 +32,7 @@ sudo apt install python3-venv
 pip installs CasADi from a prebuilt wheel. If pip starts building CasADi from source, or
 `import casadi` fails, there is no wheel for your Python version or platform. Create the
 environment with a Python version listed among the files on CasADi's
-[PyPI page](https://pypi.org/project/casadi/#files).
+[PyPI page](https://pypi.org/project/casadi/).
 
 ## Compiling takes long
 

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/docs/tutorials/real-time.md

@@ -132,6 +132,29 @@ length of each step. `log.info` counts the `overruns` (steps longer than the per
 `stale` readings the loop refused as too old and the `guard_trips` (readings missing or not
 numbers). A refused reading means zero torque for that step.
 
+A run that goes on for hours would keep every step in memory. With `window` [s], `run` keeps
+only the last seconds of the log (up to a quarter more, until it trims), and `log.info["steps"]`
+still counts every step. `log.crop(t_min, t_max)` takes a part of any log:
+
+```{code-cell} python
+driver = Driver()
+clock = vmc.sim.WallClock(1 / 330, 0.05, now=driver.time,
+                          sleep=driver.sim.advance)
+long = vmc.sim.run(Plant(driver), controller, clock, T=3.0, window=1.0)
+kept = long.arrays()["t"].ravel()
+last = long.crop(t_min=kept[-1] - 0.5)  # the last half second
+len(kept), len(last.arrays()["t"])
+```
+
+```{code-cell} python
+:tags: [remove-cell]
+assert long.info["steps"] == 990 and 330 <= len(kept) <= 413
+assert abs(kept[-1] - 989 / 330) < 1e-9 and 160 <= len(last.arrays()["t"]) <= 167
+glue("kept", len(kept), display=False)
+```
+
+The log holds {glue:text}`kept` of the 990 steps, the last second or so, and nothing older.
+
 `run` does not close the plant: do it yourself, with `try` and `finally`:
 
 ```python

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/src/virtualmodelcontrol/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
 
 __commit_id__ = commit_id = None

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/src/virtualmodelcontrol/sim/run.py

@@ -62,6 +62,7 @@ def run(
     guard: Guard | None = None,
     z0: Any = None,
     record: Iterable[str] | str = (),
+    window: float | None = None,
 ) -> RunLog:
     """Run ``controller`` on ``plant`` for ``T`` [s]; returns the recorded run.
 
@@ -73,7 +74,9 @@ def run(
     step, the measurements, the command (and the law's torque before any output stage), the
     virtual state ``z`` when the controller has one, and what ``record`` asks for (see
     ``RECORDS``); a value the step did not compute is NaN. Its ``meta`` holds the Params at the
-    start and the plant's hardware profile.
+    start and the plant's hardware profile. On real time, ``window`` [s] keeps only the last
+    seconds of a run that goes on for hours (up to a quarter more, until the next trim);
+    ``info["steps"]`` still counts them all.
     """
     guard = Guard() if guard is None else guard
     extras = _extras(record)
@@ -83,8 +86,10 @@ def run(
         raise ValueError(
             "record='robot' needs a simulated plant: a real robot does not report forces"
         )
+    if window is not None and not isinstance(clock, WallClock):
+        raise ValueError("window is for a real-time run: a simulated one has its duration")
     if isinstance(clock, WallClock):
-        return _run_wall(plant, controller, clock, T, guard, z0, extras)
+        return _run_wall(plant, controller, clock, T, guard, z0, extras, window)
     if T is None:
         raise ValueError("a simulated run needs its duration T")
     log = RunLog()
@@ -189,6 +194,7 @@ def _run_wall(
     guard: Guard,
     z0: Any,
     extras: Callable[[Any, Any], dict[str, Any]],
+    window: float | None,
 ) -> RunLog:
     """The run loop on real time: measured steps, stale readings refused, rate statistics."""
     log, limit = RunLog(), None if T is None else round(T / clock.dt)
@@ -197,7 +203,7 @@ def _run_wall(
     t0 = previous = tick = clock.now()
     _reset(controller, 0.0, meas, z0)
     _describe(log, plant, controller)
-    steps = overruns = stale = 0
+    steps = overruns = stale = dropped = 0
     try:
         while limit is None or steps < limit:
             now = clock.now()
@@ -214,6 +220,12 @@ def _run_wall(
             values = _values(t, cmd, meas, controller, plant, extras if good else None)
             log.step(dt=now - previous, **values)
             steps += 1
+            if window is not None and len(log.rows["t"]) > 1.25 * window / clock.dt:
+                # a fifth at a time: trimming a list costs its length
+                drop = len(log.rows["t"]) // 5
+                dropped += drop
+                for rows in log.rows.values():
+                    del rows[:drop]
             previous, tick = now, tick + clock.dt
             wait = tick - clock.now()
             if wait > 0:
@@ -221,7 +233,7 @@ def _run_wall(
             else:  # late: start again from now rather than catching up in a burst
                 overruns, tick = overruns + 1, clock.now()
     except KeyboardInterrupt:  # Ctrl-C ends a real-time run with the log so far
-        log.rows = {name: rows[:steps] for name, rows in log.rows.items()}
+        log.rows = {name: rows[: steps - dropped] for name, rows in log.rows.items()}
     dt = np.diff(log.arrays()["t"].ravel()) if steps > 1 else np.array([clock.dt])
     log.info = {
         "steps": steps,

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/src/virtualmodelcontrol/sim/runlog.py

@@ -50,6 +50,17 @@ class RunLog:
         """Each signal as an (n_steps, ...) array."""
         return {name: np.array(rows) for name, rows in self.rows.items()}
 
+    def crop(self, t_min: float | None = None, t_max: float | None = None) -> RunLog:
+        """The steps with ``t_min`` ≤ t ≤ ``t_max`` [s] (an end left out is open), as a new log with
+        the same ``info`` and ``meta``."""
+        t = np.array([row[0] for row in self.rows["t"]])
+        keep = np.flatnonzero(
+            (t >= (-np.inf if t_min is None else t_min))
+            & (t <= (np.inf if t_max is None else t_max))
+        )
+        rows = {name: [values[i] for i in keep] for name, values in self.rows.items()}
+        return RunLog(rows, dict(self.info), dict(self.meta))
+
     def save(self, path: str | os.PathLike[str], *, overwrite: bool = False) -> Path:
         """Write the log as a compressed ``.npz`` and return its path. The file is written whole or
         not at all (through a temporary file), and an existing one is kept unless ``overwrite``."""

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/tests/sim/test_runlog.py

@@ -167,3 +167,31 @@ def test_the_library_reads_runs_of_its_own_simulator(tmp_path):
     assert back.meta == log.meta and back.meta["library"] == vmc.__version__
     for name, values in log.arrays().items():
         np.testing.assert_array_equal(back.arrays()[name], values, err_msg=name)
+
+
+def test_crop_keeps_the_steps_of_a_time_window_and_leaves_the_log_as_it_was():
+    log = example_log()
+    part = log.crop(0.25, 1.0)
+    rows = part.arrays()
+    np.testing.assert_array_equal(rows["t"].ravel(), [0.5, 1.0])
+    np.testing.assert_array_equal(rows["q"], [[3.0, 4.0], [5.0, 6.0]])
+    assert rows["tag"].shape == (2, 1) and np.isnan(rows["tag"]).all()  # the names stay, aligned
+    assert part.info == log.info and part.meta == log.meta
+    part.info["steps"] = 0  # a copy: the original is not touched
+    assert log.info["steps"] == 3 and len(log.arrays()["t"]) == 3
+    np.testing.assert_array_equal(
+        log.crop(t_max=0.5).arrays()["t"].ravel(), [0.0, 0.5]
+    )  # open ends
+    np.testing.assert_array_equal(log.crop(t_min=0.6).arrays()["t"].ravel(), [1.0])
+    assert len(log.crop().arrays()["t"]) == 3 and len(log.crop(2.0, 3.0).rows["t"]) == 0
+    np.testing.assert_array_equal(
+        log.crop(0.5, 0.5).arrays()["t"].ravel(), [0.5]
+    )  # both ends count
+
+
+def test_crop_with_an_open_end_takes_every_time_on_that_side():
+    log = RunLog()
+    for t in (-1.0, 0.0, 5.0):
+        log.step(t=t, q=[t])
+    np.testing.assert_array_equal(log.crop(t_max=0.0).arrays()["t"].ravel(), [-1.0, 0.0])
+    np.testing.assert_array_equal(log.crop(t_min=0.0).arrays()["t"].ravel(), [0.0, 5.0])

{virtualmodelcontrol-1.1.0 → virtualmodelcontrol-1.2.0}/tests/sim/test_wallclock.py

@@ -123,3 +123,49 @@ def test_ctrl_c_ends_a_real_time_run_with_the_log_so_far():
 def test_a_simulated_run_needs_its_duration():
     with pytest.raises(ValueError, match="duration"):
         vmc.sim.run(None, None, vmc.sim.SimClock(0.01), T=None)
+
+
+def test_a_window_keeps_the_last_seconds_of_a_run_that_goes_on():
+    for steps in range(300, 313):  # the run ends at every point of the trimming cycle
+        time = FakeTime()
+        clock = vmc.sim.WallClock(dt=0.01, now=time.now, sleep=time.sleep)
+        log = vmc.sim.run(Plant(time), Controller(time), clock, T=steps * 0.01, window=0.5)
+        rows = log.arrays()
+        t = rows["t"].ravel()
+        assert log.info["steps"] == steps  # every step ran
+        assert 50 <= len(t) <= 62  # the last 0.5 s, and at most a quarter more
+        assert t[-1] == pytest.approx((steps - 1) * 0.01)  # the newest steps are the kept ones
+        np.testing.assert_allclose(np.diff(t), 0.01, atol=1e-9)  # no gap: the oldest rows went
+        assert all(len(v) == len(t) for v in rows.values())  # every signal was trimmed together
+    time = FakeTime()
+    clock = vmc.sim.WallClock(dt=0.01, now=time.now, sleep=time.sleep)
+    full = vmc.sim.run(Plant(time), Controller(time), clock, T=3.0)
+    assert len(full.arrays()["t"]) == 300  # without a window nothing is dropped
+
+
+def test_ctrl_c_in_the_middle_of_a_step_of_a_windowed_run_keeps_only_whole_steps(monkeypatch):
+    original = vmc.sim.runlog.RunLog.step
+    calls = []
+
+    def interrupted(self, **values):
+        calls.append(1)
+        if len(calls) == 121:  # the signal comes after the first signal of the step is logged
+            first, *_ = values
+            self.rows.setdefault(first, []).append(np.array([0.0]))
+            raise KeyboardInterrupt
+        original(self, **values)
+
+    monkeypatch.setattr(vmc.sim.runlog.RunLog, "step", interrupted)
+    time = FakeTime()
+    clock = vmc.sim.WallClock(dt=0.01, now=time.now, sleep=time.sleep)
+    log = vmc.sim.run(Plant(time), Controller(time), clock, T=None, window=0.5)
+    rows = log.arrays()
+    assert log.info["steps"] == 120 and 50 <= len(rows["t"]) <= 62
+    assert len({len(v) for v in rows.values()}) == 1 and rows["t"].ravel()[-1] == pytest.approx(
+        1.19
+    )
+
+
+def test_a_window_is_for_a_run_on_real_time():
+    with pytest.raises(ValueError, match="real-time"):
+        vmc.sim.run(None, None, vmc.sim.SimClock(0.01), T=1.0, window=0.5)