virtualmodelcontrol 1.2.2__tar.gz → 1.3.0__tar.gz

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/CHANGELOG.md

@@ -4,6 +4,80 @@ 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.3.0] - 2026-10-30
+
+A minor release. A plan of a robot with fewer motors than coordinates now reads the motors, as the controller that
+runs does (see Changed), and the result of a review of the whole library: the fixes below, most of them for
+cases that gave a wrong or a silent answer, and the tension floor for tendons that only pull. Nothing else changes
+for a robot with a motor on every coordinate.
+
+### Added
+
+- `control.TensionFloor`: an output stage for tendons that only pull. It lifts the torques of each
+  group of tendons (a segment's three) together until the lowest is at a floor, so no tendon is
+  told to push. Equal torques on evenly spaced tendons only squeeze the segment, so the bend
+  that the command makes is the same. Its corner is rounded, and `symbolic` is the same map for
+  a plan (`Problem(output=)`).
+- `Mechanism.motor` and the `MotorAngle` coordinate: entries of the robot's motor angles, as its
+  actuation gives them. A `LimitSpring` on it is a limit on how far a motor may turn.
+- `helyx.tension_stage`, `helyx.unwind_limit` and their numbers `TENSION_FLOOR`,
+  `UNWIND_LIMIT` and `UNWIND_STIFFNESS`: the tension floor, and a limit on how far a motor may
+  unwind (pulling is free). Both are optional, and `helyx.output_stage` is unchanged.
+- `control.underactuated.Frozen(at=)` and `controller(gravity=<motor angles>)`: the rest of the
+  passive joints balanced once at a pose. The frozen torque stays the gradient of a potential,
+  which `gravity=True` (the balance found again at every reading, as before) does not: its torque
+  has a curl of a few percent in the test. `Frozen.rest` can be set as the `q_rest` of the
+  actuation.
+- A `Param` can be shared by several sections or joints (`PCC([0.2, 0.2], radius)`, one axis for two
+  joints): it keeps one value, `ParamSet.by_name()` lists every name it has, and `select` finds
+  it by any of them (under its own name).
+- `MovingHorizon.encoder` of a robot with fewer motors than coordinates measures the motors, as the
+  Kalman filter's does (it pinned the passive joint at its rest angle: an error of 0.37 rad in the
+  test, 0.001 now). `MovingHorizon.P` is defined from `reset` on.
+- A term of a plan can use a site of a `plant` that is another robot.
+
+### Changed
+
+- A plan of a robot with fewer motors than coordinates now reads the motors, as `VMCController`
+  does (the frozen controller of `control.underactuated`). It used to read the whole state, so
+  that `Problem(system)` and the simulation of `VMCController(compile(system))` were different
+  controllers (a gap of 0.36 rad in the test). `Problem(reads="state")` plans the whole-state
+  controller (`StateController`, `"naive"`), and `reads="motors"` asks for the default outright.
+  For a robot with a motor on every coordinate nothing changes.
+- `MPC` applies a plan only if its solve converged (a real-time iteration is applied as it is):
+  a failed solve used to jump the controller's Params. `MPC.applied` says whether the last plan
+  was, and the next solve after a failed one starts from the measured state. `rti=True` is undone
+  by a later `MPC` of the same problem without it, `reset` drops a plan that is being made, and
+  `start` waits until the last plan was polled.
+- `Result.params` and `Result.steps` are held inside the Params' bounds (the solver relaxes a
+  bound by about 1e-8).
+- `fit_params` and `fit_stiffness_damping` refuse an even `smoothing` (it shifted the derivative by
+  half a sample: a damping of 1.5 came out as 1.88), and a run whose `train` mask is off everywhere.
+  `fit_stiffness_damping` returns NaN, with a warning that names it, for a stiffness or damping
+  that the runs do not determine (it returned 0). `fit_params` takes one name as a string, and
+  a run with nothing to train is skipped when another has samples (an error when none has).
+- `VMCController.set` refuses a value whose size is not the Param's (a scalar was broadcast into a
+  matrix), and `live_params()` returns copies. `balance()` and `elements()` use the Params as
+  `set` left them.
+- `register` replaces a class defined again (a script or a notebook cell run twice) and still
+  refuses another object under a taken name. A plugin that fails to import no longer keeps the
+  others from loading: its error is raised by `get` of a name that is missing (and said in the
+  `KeyError`), and is a warning in `names`.
+- `robot.joint` counts from the end (`slice(0, -1)`) and takes numpy integers; an index out of
+  range is a `ValueError` that says how many coordinates there are.
+- `TensionFloor` needs a positive `width` (zero gave NaN).
+- In `ask` and `tell`, a cost that is not finite (an episode that failed) counts as the worst cost
+  so far (`inf` until one is known) and is never the best; `Bayes` used to fail for good after one.
+- `planar.arm(rest=)` takes one angle per passive joint as well as one per joint.
+- The messages that named `Collocation` and `Equilibrium` name `Shooting` too.
+
+### Fixed
+
+- `Tank`, `SwapController` and `ScheduledController` can be copied and pickled.
+- `Gated` forwards what the wrapped component reads.
+- The docstring of `rollout` says that its `z` rows are the state the law used, one step behind
+  `run`'s.
+
 ## [1.2.2] - 2026-10-11
 
 A patch: a fit says when its data do not determine a Param, and gives the same values on every machine; two
@@ -369,7 +443,7 @@ tank, tuning and the calibrations), which was never released on its own.
     geometric terms out and is not provided.
   - `KalmanFilter(system, dt, Q=None, P0=None, gate=40.0, robot=None)` and `Measurement(q, v, Rq,
     Rv, observed, name)`: a Kalman filter of the robot's state (q, v). Its process model is the
-    robot's own dynamics, linearised at the estimate at rest and held over the step (the lab's
+    robot's own dynamics, linearized at the estimate at rest and held over the step (the lab's
     frozen mass matrix, in general form), with the command going through the system's
     transmission. It fuses encoders (`kf.encoder`) and any sensor that sees part of the state,
     gates each measurement on its innovation, and reports the sensors it rejected (`rejected`,
@@ -460,9 +534,9 @@ tank, tuning and the calibrations), which was never released on its own.
   covariance, on a mass, spring and damper. The tutorial "Fit Params to a run" uses it.
 - `KalmanFilter(..., unscented=True, substeps=10)`: the prediction sends sigma points of the
   estimate (the scaled unscented transform, a root of three standard deviations out) through the
-  robot's own integrator, in `substeps` steps, instead of linearising at the estimate; the sensors
+  robot's own integrator, in `substeps` steps, instead of linearizing at the estimate; the sensors
   stay linear, so the update is the same. On a double pendulum it follows the mean of a Monte
-  Carlo to 0.003 where the linearised prediction is off by 2; on a linear robot the two agree.
+  Carlo to 0.003 where the linearized prediction is off by 2; on a linear robot the two agree.
 - `vmc.estimation.MomentumObserver(system, dt, gain, robot=None)`: the external force on a robot
   from its motion, without accelerations. From the momentum and what the model says would change
   it, it gives the generalized force the model does not explain, as a low-pass filter of bandwidth
@@ -854,7 +928,8 @@ First public release.
 - `robots.adapt`: the ADAPT finger (two motors, coupled distal joints), joint-angle coordinate
   and joint-limit spring.
 
-[Unreleased]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.2...HEAD
+[Unreleased]: https://github.com/vigno0405/VirtualModelControl/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/vigno0405/VirtualModelControl/compare/v1.1.0...v1.2.0

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 type: software
-version: 1.2.2
-date-released: "2026-10-11"
+version: 1.3.0
+date-released: "2026-10-30"
 title: "virtualmodelcontrol: Virtual Model Control for robots"
 authors:
   - family-names: Vignoli

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: virtualmodelcontrol
-Version: 1.2.2
+Version: 1.3.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.2.2 → virtualmodelcontrol-1.3.0}/docs/concepts/conventions.md

@@ -94,7 +94,7 @@ tank
 
 output stage
   An optional correction of the motor commands for real hardware: friction compensation,
-  pretension, an offset or a torque limit.
+  pretension, a tension floor, an offset or a torque limit.
 
 template
   A function that builds a ready-made robot, such as `helyx.arm`, with every geometric number

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/concepts/library.md

@@ -39,7 +39,7 @@ a robot middleware such as ROS: signals come in and go out as arrays.
 | describe a new robot | `vmc.models`: `PCC`, `SerialChain`, `JointSpace`, `LinearCoupling`, `Assembly`, `TendonTransmission` |
 | place virtual elements | `vmc.Mechanism`, coordinates and components such as `vmc.LinearSpring` |
 | compile and run a controller | `vmc.VirtualMechanismSystem`, `vmc.compile`, `vmc.VMCController` |
-| correct commands for real hardware | `vmc.control.output`: friction compensation, pretension, limits |
+| correct commands for real hardware | `vmc.control.output`: friction compensation, pretension, a tension floor, limits |
 | get positions, Jacobians, Hessians | `vmc.Kinematics` |
 | get the robot's equations of motion | `vmc.compile_dynamics` (from the components, or from a function with `vmc.models.Equations`) |
 | simulate a closed loop | `vmc.sim`: `ModelPlant`, `run`, `SimClock` |

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/examples/hanging-arm.md

@@ -76,7 +76,8 @@ size, are held out: the fit never sees them.
 `Steps` is this experiment as a controller. It runs on any plant, here the simulated arm, and
 its log goes straight to `identification.fit_stiffness_damping`. The fit knows the arm's
 masses and gravity, and fits its diagonal stiffness and damping by least squares, relative to
-the resting baseline. The masses are never fitted. Here the simulator plays the arm, so the
+the resting baseline. A stiffness or damping that the run does not determine, say of a motor that
+never pulls, comes back as NaN with a warning, not as a zero. The masses are never fitted. Here the simulator plays the arm, so the
 result can be checked against the values it was given.
 
 ```{code-cell} python

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/examples/soft-arm.md

@@ -78,6 +78,15 @@ The nine motors and their bus are in `helyx.hardware("145-145-145")`. On the rea
 `helyx.output_stage()` adds a small pretension to every motor command
 ({glue:text}`pretension:.3f` N·m per radian of motor angle). The simulations below leave it out.
 
+A tendon only pulls, and a motor that is told to push unwinds without end. A virtual spring on
+the tip asks the tendons on the far side of a bend to do just that. `helyx.tension_stage()` is an
+output stage that lifts the three tendons of each segment together until the lowest is at
+`helyx.TENSION_FLOOR`: equal torques on three evenly spaced tendons only squeeze the segment, so
+the bend is the same, and every tendon stays taut. `helyx.unwind_limit(arm)` is a spring on the
+motor angles that pushes back a motor that has unwound more than `helyx.UNWIND_LIMIT` from its
+start angle. Both are optional and tunable, and both have a smooth form, so a plan can include
+them with `Problem(output=helyx.tension_stage())`.
+
 ## Reach past an obstacle
 
 A spring pulls the tip towards a target beyond an obstacle, while two repulsive Gaussian

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/installation.md

@@ -128,10 +128,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.2.2"
+pip install "virtualmodelcontrol==1.3.0"
 ```
 
-In a `requirements.txt` file, write `virtualmodelcontrol==1.2.2`. In a conda `environment.yml`,
+In a `requirements.txt` file, write `virtualmodelcontrol==1.3.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.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/extend.md

@@ -57,7 +57,9 @@ class QuarticSpring(Component):
         return 0.25 * ctx.param(self.stiffness) * ca.sumsqr(y) ** 2
 ```
 
-It acts on any coordinate, and `compile` treats it like the built-in springs:
+Run the cell again, in a notebook or after an edit, and the new class replaces the old one
+under the name. Another class under a taken name is refused. It acts on any coordinate, and
+`compile` treats it like the built-in springs:
 
 ```{code-cell} python
 from virtualmodelcontrol.robots import helyx
@@ -370,7 +372,9 @@ my_project = "my_project.vmc_plugins"
 ```
 
 Importing `my_project.vmc_plugins` must run its `register(...)` decorators. The library loads
-the plugins the first time a name is looked up and not found. So configuration files can use
+the plugins the first time a name is looked up and not found. A plugin that fails to import does
+not keep the others from loading: its error is raised, and a name that is not there says that a
+plugin is broken. So configuration files can use
 the plugins' names ([Experiments in files](configurations.md)). Register a robot template as
 `"robot"`, a simulation's dynamics as `"dynamics"`, an output stage as `"output"`, a controller
 template as `"controller"` and a component as `"component"`. Register a coordinate kind as

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/fit.md

@@ -118,7 +118,7 @@ assert abs(float(tanh_fit.values["damper.damping"]) - 1.5) < 0.1
 
 The true values are 2 kg, 40 N/m and 1.5 N·s/m. The log holds no accelerations, so the fit
 gets them by smoothing the velocity and differentiating it, which is where its error comes from
-(`smoothing` is the number of samples of the smoothing). A run that has an `a` of its own, as a
+(`smoothing` is the number of samples of the smoothing: an odd number, at least 5). A run that has an `a` of its own, as a
 simulation can give, is used as it is. After the fit, {glue:text}`fit_rms:.4f` N is left over
 per sample. The numbers after ± are the standard errors: how far the values may be off if what is
 left over is noise. Here it is not noise, it is the smoothing, so the errors are much larger than

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/mpc.md

@@ -122,8 +122,10 @@ bottom.set_ylabel("stiffness [N/m]");
 
 `MPC` wraps the problem. It builds the program once, and every `step` solves it from the
 measured state, starting from the previous plan moved one interval on. It sets the Params of the
-plan on the controller through `controller.set`, and returns the jump this gave the controller's
-energy, as the [adaptation laws](stiffness.md) do:
+plan on the controller through `controller.set`, if the solve converged (a failed one leaves the
+Params as they are, `mpc.applied` and `mpc.result.converged` say, and the next solve starts from
+the measured state), and returns the jump this gave the
+controller's energy, as the [adaptation laws](stiffness.md) do:
 
 ```{code-cell} python
 mpc = opt.MPC(problem)  # the start and the Params that step become inputs
@@ -211,8 +213,9 @@ while running:
 ```
 
 A solve lets the other threads run, so the loop keeps its rate. `start` does nothing while a
-plan is being made, and an error in the thread is raised by the next `poll`. Create the `MPC`
-after setting the problem's solver and options, since it creates the solver then.
+plan is being made or has not been polled yet, `reset` drops a plan that is being made, and an
+error in the thread is raised by the next `poll`. Create the `MPC` after setting the problem's
+solver and options, since it creates the solver then.
 
 ## A tank pays for the changes
 
@@ -282,7 +285,9 @@ glue("rti", 1e3 * float(abs(fast[-1, 1] - 1.0)), display=False)
 ```
 
 Every plan is one iteration, and the mass ends {glue:text}`rti:.1f` mm from the goal. A plan
-then is not an optimum, only a step towards it; `plan.converged` is false for it by design.
+then is not an optimum, only a step towards it; `plan.converged` is false for it by design, and
+it is applied all the same. `rti=True` sets the problem's solver to `"rti"`, and an `MPC` of the
+same problem without it puts the previous solver back.
 
 ## Solvers
 
@@ -326,7 +331,9 @@ glue("it_exact", int(rows["ipopt-exact"][0]), display=False)
 
 The default `"ipopt"` takes {glue:text}`it_ipopt` iterations against {glue:text}`it_exact` for
 `"ipopt-exact"`, as its Hessian is approximate, and ends at an acceptable level; `"rti"` is one
-step from a cold start, so its plan is not the optimum.
+step from a cold start, so its plan is not the optimum. On a harder shooting the quasi-Newton
+Hessian can use all of its 500 iterations without converging (it does on another problem with
+CasADi 3.8.2): take `"ipopt-exact"` for a shooting, and read `plan.converged`.
 
 Which QP solver the SQP presets use is the `qpsol` option, and not every one of CasADi's
 suits a shooting. Tried on this problem with CasADi 3.7 and 3.8: `qrqp` (the default), `qpoases`

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/optimize.md

@@ -256,8 +256,9 @@ glue("gain", float(100 * (1 - found.result.cost / anchor)), display=False)
 sideways = [c["cost"] for c in found.candidates
             if c["cost"] is not None
             and np.abs(np.array(c["references"][key]) - target)[:2].max() > 1e-6]
-assert len(sideways) >= 2 and min(sideways) > 5 * anchor
-glue("sideways", float(min(sideways) / anchor), display=False)
+assert len(sideways) >= 2 and min(sideways) > anchor  # the target is the better reference
+glue("sideways_min", float(min(sideways) / anchor), display=False)
+glue("sideways_max", float(max(sideways) / anchor), display=False)
 glue("k_search", found.result.params["new.pull.stiffness"].item(), display=False)
 ```
 
@@ -266,8 +267,10 @@ neighbors. The status says how each solve ended: an acceptable level counts as c
 point that did not converge has no cost. The best reference lies {glue:text}`offset:.0f` mm from
 the target along z, and it lowers the cost by {glue:text}`gain:.1f` %, with a stiffness of
 {glue:text}`k_search:.0f` N/m: for this task the target is already a good reference. Moving it
-sideways costs at least {glue:text}`sideways:.0f` times more. `found.result` is the plan, `found.references` the
-point that gave it, and `found.candidates` every point tried.
+sideways costs {glue:text}`sideways_min:.1f` to {glue:text}`sideways_max:.0f` times more (a solve of
+this non-convex plan can end at a different optimum from another point's, and the CasADi version
+changes where: read the statuses). `found.result` is the plan, `found.references` the point that gave it, and
+`found.candidates` every point tried.
 
 ## Where the arm rests
 

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/soft-and-assemblies.md

@@ -37,6 +37,15 @@ soft = vmc.Mechanism(
 soft.actuation.motor_sizes(soft.space)  # motor angles, motor rates
 ```
 
+A number is a `Param`, and one `Param` can stand for several: give the same one to both sections
+and they share its value, so that `Problem.free` and `set` change it once.
+
+```{code-cell} python
+radius = vmc.Param("radius", 0.03, unit="m", scope="design")
+shared = PCC([0.2, 0.2], radius)  # one radius for both sections
+shared.params["seg1.d"] is shared.params["seg2.d"]
+```
+
 The arm's mass is not lumped by itself. `soft.add_mass_along(name, mass, s0, s1, n)` spreads a mass
 evenly between two arc parameters as $n$ point masses at the nodes of Gauss-Legendre quadrature,
 which is exact for any polynomial of degree $2n - 1$ in the arc length. Here the height of the

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/tuning.md

@@ -125,7 +125,8 @@ A searcher is made from the bounds of the Params: `Grid(lower, upper, points)`,
 `Bayes(lower, upper, initial=...)` and `Random(lower, upper, size=...)`. `CMAES(start, step, lower,
 upper, size=...)` also takes a starting point and the size of its first steps, and
 `ExtremumSeeking(start, amplitude, gain, ...)` the size of its test moves and a gain. The CMA-ES
-loop below is the same as `tune`, written out:
+loop below is the same as `tune`, written out. An episode that failed, with a cost that is `inf`
+or NaN, counts as the worst cost so far and is never the best:
 
 ```{code-cell} python
 from virtualmodelcontrol import optimization as opt

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/docs/tutorials/underactuated.md

@@ -108,7 +108,9 @@ builds it, and `base` chooses how its torques are rendered:
 - `"frozen"` evaluates the same law with the passive joint held at its rest angle, whatever it
   does. It needs the motors only, and its torque is the exact gradient of a potential. With
   `gravity=True` it holds the passive joint where its spring balances the arm's own weight
-  instead of at the rest angle.
+  instead of at the rest angle, found again at every reading ([a passive joint under
+  weight](#a-passive-joint-under-weight) says what that costs); with `gravity=` the motor
+  angles of a pose it finds the balance once, there.
 
 ```{code-cell} python
 def reach(robot, compensate=True, stiffness=150.0):
@@ -120,8 +122,9 @@ def reach(robot, compensate=True, stiffness=150.0):
         ctrl.add("gravity", vmc.GravityCompensation(robot))
     return vmc.compile(vmc.VirtualMechanismSystem(robot, ctrl))
 
-def run(compiled, base, correction=None, gravity=False, T=4.0):
-    controller = ua.controller(compiled, base, correction, gravity=gravity)
+def run(compiled, base, correction=None, gravity=False, T=4.0, **stage):
+    controller = ua.controller(compiled, base, correction, gravity=gravity,
+                               **stage)
     plant = vmc.sim.ModelPlant(arm, q0=[0.3, 0.3, 0.3], max_step=1e-4)
     log = vmc.sim.run(plant, controller, vmc.sim.SimClock(5e-4), T=T)
     return log.arrays()
@@ -174,6 +177,58 @@ goal (naive, and frozen with `gravity=True`) and {glue:text}`bare_frozen:.0f` mm
 frozen). Where the passive joint is at rest and carries nothing, naive and frozen send the
 same torques.
 
+## A passive joint under weight
+
+The frozen controller keeps the arm passive because its torque is the gradient of a potential:
+the field of motor angles $\theta \mapsto u(\theta)$ has no curl, so the motors cannot gain
+energy by going around a loop. That holds while the rest of the passive joint is a constant. With
+`gravity=True` the rest is the joint's balance at the current motor angles, and it moves as they
+do, which puts a small curl into the field. We measure the curl as the asymmetry of the Jacobian
+of $u$ with respect to $\theta$, relative to its size, for the plain frozen controller, for
+`gravity=True`, and for `gravity=` the motor angles of a pose, where the balance is solved once:
+
+```{code-cell} python
+def curl(gravity, theta, h=1e-6):
+    controller = ua.controller(compiled, "frozen", gravity=gravity)
+
+    def torque(theta):
+        reading = vmc.Signals(0.0, motor_position=theta, q=[0.0] * 3,
+                              motor_velocity=[0.0, 0.0], v=[0.0] * 3)
+        controller.reset(0.0, reading)
+        return np.asarray(controller.step(0.0, reading)["law_torque"])
+
+    jac = np.column_stack([(torque(theta + h * e) - torque(theta - h * e))
+                           / (2 * h) for e in np.eye(2)])
+    return abs(jac - jac.T).max() / abs(jac).max()
+
+pose = B.T @ runs["naive"]["q"][-1]  # the motor angles where the reach ends
+curls = {"plain": curl(False, pose), "moving": curl(True, pose),
+         "fixed": curl(pose, pose)}
+```
+
+```{code-cell} python
+:tags: [remove-cell]
+assert curls["plain"] < 1e-8 and curls["fixed"] < 1e-8
+assert 1e-3 < curls["moving"] < 0.2
+settled = run(compiled, "frozen", gravity=pose)
+final_fixed = 1000 * float(tip_error(settled)[-1])
+assert final_fixed < 1.0, final_fixed
+glue("curl_plain", float(curls["plain"]), display=False)
+glue("curl_fixed", float(curls["fixed"]), display=False)
+glue("curl_moving", float(curls["moving"]), display=False)
+glue("final_fixed", final_fixed, display=False)
+```
+
+The plain frozen torque has no curl ({glue:text}`curl_plain:.0e`), and neither has the one whose
+balance is solved once ({glue:text}`curl_fixed:.0e`). The torque that follows the balance has a
+curl of {glue:text}`curl_moving:.1%` here: a few percent of the field, but not a gradient, so the
+guarantee does not cover it. Give `gravity=` the motor angles of the pose the arm works around, such as where the
+reach ends. With the balance solved there, the frozen controller ends
+{glue:text}`final_fixed:.1e` mm from the goal, as it does with `gravity=True`, and its torque is
+a gradient again. The rest it found is `ua.Frozen(arm.actuation, dynamics, at=pose).rest`, which
+can be set as the `q_rest` of the actuation, the way [a plan](#planning-with-these-controllers)
+reads it.
+
 ## Keeping the arm passive
 
 The naive torque is not the gradient of anything, so a controller built on it can put energy
@@ -227,8 +282,57 @@ Without a correction the arm gains up to {glue:text}`peak_none:.2f` J from the c
 the passive correction it gains {glue:text}`peak_passive:.3f` J at most, the rounding of the
 control period (the guarantee holds in continuous time and the gain falls with the period). With
 the tank it gains {glue:text}`peak_tank:.2f` J, the budget it started with (the default
-`tank=1.0` J of `ua.controller`). The frozen controller needs no correction for its own
-torque, which is a gradient.
+`tank=1.0` J of `ua.controller`).
+
+The `width` of a correction, in W, smooths the point where it starts. Its default, 1 W, is as
+large as the power of this arm, so the correction also slows the reach when little needs
+correcting: after 4 s the passive correction is still {glue:text}`slow_default:.0f` mm from the
+goal, and with `width=1e-2` it is {glue:text}`slow_narrow:.1f` mm. Take the smallest power that
+matters in your loop.
+
+```{code-cell} python
+:tags: [remove-cell]
+narrow = run(compiled, "naive", "passive", width=1e-2)
+slow_default = 1000 * float(tip_error(corrected["passive"])[-1])
+slow_narrow = 1000 * float(tip_error(narrow)[-1])
+assert slow_default > 10.0 and slow_narrow < 1.0, (slow_default, slow_narrow)
+glue("slow_default", slow_default, display=False)
+glue("slow_narrow", slow_narrow, display=False)
+```
+
+The frozen controller needs no correction to keep the energy of its own virtual spring from
+growing, since its torque is a gradient (with `gravity=True`, only up to the small curl above).
+Do not stack them. A correction compares the power the motors inject with what the arm's own
+dampers dissipate, and a virtual spring that is releasing its energy injects power, so it also
+cuts the torque of the frozen controller:
+
+```{code-cell} python
+def removed(base, T=4.0, dt=5e-4):
+    """The torque [N·m s] that the passive correction takes off the law."""
+    controller = ua.controller(compiled, base, "passive", width=1e-4)
+    plant = vmc.sim.ModelPlant(arm, q0=[0.3, 0.3, 0.3], max_step=1e-4)
+    controller.reset(0.0, plant.read())
+    total = 0.0
+    for _ in range(round(T / dt)):
+        command = controller.step(plant.t, plant.read())
+        total += dt * float(np.abs(command["law_torque"]
+                                   - command["motor_torque"]).sum())
+        plant.write(command)
+        plant.advance(dt)
+    return total
+
+cut = {base: removed(base) for base in ("naive", "frozen")}
+```
+
+```{code-cell} python
+:tags: [remove-cell]
+assert cut["frozen"] > 0.1 and cut["naive"] > 0.1, cut
+glue("cut_frozen", float(cut["frozen"]), display=False)
+glue("cut_naive", float(cut["naive"]), display=False)
+```
+
+Over this reach the correction takes {glue:text}`cut_frozen:.1f` N·m·s off the frozen torque and
+{glue:text}`cut_naive:.1f` N·m·s off the naive one. Use the corrections on the naive controller.
 
 ## A force along a direction
 
@@ -308,6 +412,44 @@ for ax, (name, robot) in zip(axes, robots.items()):
 axes[0].set_ylabel("height [m]");
 ```
 
+## Planning with these controllers
+
+A plan of the [optimization layer](optimize.md) is the closed loop, so it has to read what the
+controller on the robot reads. For a robot with fewer motors than joints, `Problem(system)`
+plans the controller that reads the motors, as `VMCController` does: the frozen one, with the
+passive joints at their rest angles. `Problem(system, reads="state")` plans the whole-state
+controller of `"naive"` instead, and `reads="motors"` asks for the first one outright. Here is
+where each plan puts the arm at rest, started near where the matching simulation of the reach
+ended:
+
+```{code-cell} python
+from virtualmodelcontrol import optimization as opt
+
+def planned_end(reads, base):
+    start = runs[base]["q"][-1] + 0.05  # a guess near where it ends
+    problem = opt.Problem(compiled.system, reads=reads)
+    problem.add(opt.Equilibrium(start))
+    q = problem.solve().q[0]
+    return 1000 * np.linalg.norm(kin.position(q, "tip")[:2] - [0.45, 0.15])
+
+planned = {"naive": planned_end("state", "naive"),
+           "frozen": planned_end("motors", "frozen")}
+```
+
+```{code-cell} python
+:tags: [remove-cell]
+assert abs(planned["naive"] - 1000 * final["naive"]) < 0.1
+assert abs(planned["frozen"] - 1000 * final["frozen"]) < 0.1
+glue("planned_naive", float(planned["naive"]), display=False)
+glue("planned_frozen", float(planned["frozen"]), display=False)
+```
+
+The plans end {glue:text}`planned_naive:.1f` mm and {glue:text}`planned_frozen:.1f` mm from the
+goal, where the simulations above end. The frozen controller's rest is the `q_rest` Param of the
+actuation, so a plan can optimize it (`problem.free("arm.q_rest")`), and set it to a balanced
+rest as in the section above. The corrections have no symbolic form yet: `Problem(output=...)`
+refuses them. Plan the controller and add the correction when you run it.
+
 ## When the passive joint is not measured
 
 The naive controller needs the angle and the rate of every joint, and the encoders give the
@@ -317,7 +459,7 @@ joint moves the other two through the coupling, and the filter reads it from the
 see, $\theta = B^\top q$, as combinations of $q$ (the measurement's `matrix`), not as a reading
 of $q$, so the passive joint is left to the model. Each period the loop updates the filter with
 the encoders, hands the estimate to the controller as the signals `q` and `v`, and predicts
-the next period from the torques it sent.
+the next period from the torques it sent. A `MovingHorizon` estimator takes the same `encoder`.
 
 ```{code-cell} python
 from virtualmodelcontrol.estimation import Encoders, KalmanFilter
@@ -440,21 +582,26 @@ assert torque.shape == (2,) and np.isfinite(torque).all()
 
 ## Choosing
 
-- Start with `"frozen"`, with `gravity=True` if the arm carries weight: it needs only the
-  motors, its torque is a gradient, and it agrees with the naive one where the passive joints
-  rest.
+- Start with `"frozen"`, with `gravity=` the motor angles of the pose it works around if the
+  arm carries weight: it needs only the motors, its torque is a gradient, and it agrees with
+  the naive one where the passive joints rest. `gravity=True` follows the balance at every
+  reading instead, which is closer to the naive controller far from one pose, but its torque
+  is not a gradient.
 - Take `"naive"` when the whole state is measured or estimated well and you want the force the
   spring asks for even away from the passive joints' rest.
-- Add `"passive"` when the arm must never gain energy, and `"tank"` to allow short bursts up
-  to a budget. A correction removes torque, so it can slow the reach; set `tank` to what the
-  task needs.
+- Add `"passive"` to the naive controller when the arm must never gain energy, and `"tank"` to
+  allow short bursts up to a budget. A correction removes torque, so it can slow the reach: set
+  `tank` to what the task needs and `width` to the smallest power that matters. They also cut
+  the frozen torque, which needs no correction.
 - The laws and estimators that read a controller's motors (`ForceTracking`, `StiffnessTracking`,
   `PositionRegulation`, `HoldingGoals`, `ContactForce`, `TaskStiffness`) refuse a
-  `StateController`, which is what `"naive"` and `"frozen"` with `gravity=True` give, with a
+  `StateController`, which is what `"naive"` and `"frozen"` with `gravity` set give, with a
   `ValueError`. Plain `"frozen"` is a `VMCController` and works with them; for a force on
   an underactuated arm use `DirectionalForce`.
-- `gravity=True` holds the passive joints where their springs balance the arm's weight, not at
+- `gravity=` holds the passive joints where their springs balance the arm's weight, not at
   the rest angle: the right reference for an arm that hangs or reaches out. The weight itself
   is compensated by a `GravityCompensation` in the controller, as for any robot.
-- `planar.arm(rest=...)` sets the passive joints' rest angles; the frozen controller and the
-  passive spring read them from the same place.
+- `planar.arm(rest=...)` sets the passive joints' rest angles, one for all, one per passive
+  joint or one per joint. The frozen controller reads them as the `q_rest` of the actuation,
+  and `add_dynamics` copies them into the passive springs' rest: the two do not follow each
+  other after that.

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/src/virtualmodelcontrol/__init__.py

@@ -37,6 +37,7 @@ from .mechanisms import (
     LinearDamper,
     LinearSpring,
     Mechanism,
+    MotorAngle,
     Norm,
     OrientationError,
     PhaseSpring,
@@ -110,6 +111,7 @@ __all__ = [
     "LinearDamper",
     "LinearSpring",
     "Mechanism",
+    "MotorAngle",
     "Norm",
     "OrientationError",
     "Param",

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.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.2.2'
-__version_tuple__ = version_tuple = (1, 2, 2)
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)
 
 __commit_id__ = commit_id = None

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/src/virtualmodelcontrol/adaptation/seeking.py

@@ -74,9 +74,9 @@ class DitherSeeking:
         if len(self._t) > 2 and self._t[-1] - self._t[0] > 0.9 * self.window:
             times, costs = np.array(self._t), np.array(self._cost)
             weights = np.gradient(times)
-            centred = costs - np.sum(costs * weights) / np.sum(weights)
+            centered = costs - np.sum(costs * weights) / np.sum(weights)
             probes = np.sin(np.outer(self.frequency, times))
-            self.slope = 2.0 / self.amplitude * (probes @ (centred * weights)) / np.sum(weights)
+            self.slope = 2.0 / self.amplitude * (probes @ (centered * weights)) / np.sum(weights)
             dt = times[-1] - times[-2]
             rate = np.clip(self.gain * self.slope, -self.max_rate, self.max_rate)
             for i, name in enumerate(self.names):

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/src/virtualmodelcontrol/control/__init__.py

@@ -6,6 +6,7 @@ from .output import (
     FrictionCompensation,
     Pretension,
     StaticFrictionCompensation,
+    TensionFloor,
     TorqueLimit,
     TorqueOffset,
 )
@@ -23,6 +24,7 @@ __all__ = [
     "StaticFrictionCompensation",
     "SwapController",
     "Tank",
+    "TensionFloor",
     "TorqueLimit",
     "TorqueOffset",
     "VMCController",

{virtualmodelcontrol-1.2.2 → virtualmodelcontrol-1.3.0}/src/virtualmodelcontrol/control/blending.py

@@ -78,4 +78,6 @@ class SwapController:
         return Signals(t, **mixed)
 
     def __getattr__(self, name: str) -> Any:
+        if name.startswith("__") or "controller" not in self.__dict__:  # copy and pickle ask early
+            raise AttributeError(name)
         return getattr(self.controller, name)