sungkyunner/forceflow-bspline-knot-analysis

ForceFlow Adaptive B-spline Knot Analysis

Training-free adaptive cubic B-spline fitting results on episode 0 of `JokerESC/ForceFlow`. No policy, SmolVLA model, or GPU was used.

Question

When action changes little but force/torque changes substantially, does fitting one vector-valued B-spline to [action, force, torque] allocate knots near the force event that are absent from an action-only fit?

Both fits use one common knot vector per multichannel trajectory. For the joint fit, the control-point columns split into action, force, and torque channels. The group-balanced adaptive insertion criterion is:

action MSE + lambda_F^2 * force MSE + lambda_tau^2 * torque MSE

Each modality is normalized before fitting. The fitting loop follows the B-spline Policy idea: fit, insert a knot at the largest reconstruction-error sample, and repeat until the normalized tolerance or knot budget is reached.

Published run

• —Source episode: 0 (1,885 samples)
• —Selected stationary-action/high-wrench steps: 682, 856, 1078, 1388
• —Local window: +/-40 samples
• —Cubic B-spline normalized RMSE tolerance: 1.0
• —Maximum local interior knots: 30
• —Wrench weight sweep: 0.25, 0.5, 1.0, 2.0

At weight 1.0, step 1078 and step 1388 gained a joint-fit knot within three samples of the event while the action-only fit had none. At weight 2.0, the four windows used 59 action-only versus 74 joint-fit interior knots in total; 6 action-only versus 9 joint-fit knots lay within three samples of the selected events. Step 856 saturated the 30-knot budget in both fits and is retained as a useful negative/limitation case.

These results demonstrate that wrench channels can alter adaptive knot allocation. They are not evidence of policy-level task improvement.

The repository also includes a third, force-guided action fit. It produces only action control points and an action spline. Wrench is not fitted; normalized force/torque change is used only as external knot-insertion salience alongside action reconstruction error.

At the default weight 1.0, force-guided fitting placed 2 knots within three steps of event 1078 and 1 knot near event 1388, while action-only fitting placed none in either window. It used 13 versus 11 total knots at event 1078 and 5 versus 4 at event 1388. Event 856 remained saturated at the 30-knot cap.

Files

• —results/episode_0000/study_summary.png: main purpose-built visualization
• —results/episode_0000/weight_sweep.csv: all event/weight measurements
• —results/episode_0000/event_*/: knot CSV, channel-separated control points, metrics, fit arrays, and local figures for the default weight 1.0
• —results/episode_0000/event_*/trajectory_geometry.png: the 12-D trajectory, spline, control polygon, control points, and knot-evaluated points in one PCA plane, plus physical-unit action/force/torque channel curves
• —results/episode_0000/event_*/action_only_channels.png: all six action channels from the action-only fit
• —results/episode_0000/event_*/action_wrench_action_channels.png: all six action components from the joint action+wrench fit, shown separately
• —results/episode_0000/event_*/force_guided_action_channels.png: action-only control points with knot insertion guided by action error and wrench change
• —results/episode_0000/event_*/force_guided_overall_action.png: action-only, FT-guided, and joint action+FT splines, action control points, and knots overlaid on the same raw channel selected by trajectory_geometry.png (action_3 for event 1388)
• —results/episode_0000/event_*/ft_threshold_sweep/: detailed plots for each selected event (682, 856, 1078, 1388) and FT difference threshold quantiles 0.50, 0.75, 0.90, 0.95, 0.99, with a stacked comparison with all three fits' knots, and CSV/JSON metadata. The step-index behavior ribbon uses the same four broad low/high regimes as the other figures but prints concrete hold/maintain-pose or wipe-vase motion and steady/changing FT-load interpretations rather than LL/LH/HL/HH codes. Exact ranges are in step_task_actions.csv.
• —results/episode_0000/event_*/reconstruction_error_threshold_sweep/: normalized global reconstruction-RMSE tolerance sweep (0.25 through 1.25) for each selected event with all three fits' knots, exact objective errors, CSV, and JSON metadata; FT guidance stays fixed at q=0.95.
• —results/episode_0000/event_1388/clean_vase_event_1388_steps_1348_1428.mp4: original fixed- and wrist-camera frames for the analyzed 81-step window, with step/task/contact overlays; see the adjacent JSON for provenance and the nominal-playback timing caveat.
• —results/episode_0000/clean_vase_episode_0000_full_steps_0000_1884.mp4: complete 1,885-frame fixed/wrist-camera task video with mid-scale behavior overlays; playback is nominal 10 FPS because source frame timestamps are absent.
• —results/episode_0000/broad_task_segments.csv: complete episode behavior segments used by the full video and all regenerated image labels.
• —results/episode_0000/full_episode_reconstruction_error_threshold_sweep/: full step 0–1884 reconstruction-RMSE tolerance sweep with q fixed at 0.95, maximum 300 interior knots, and CSV/JSON metadata.
• —results/episode_0000/event_1388/labeled_reconstruction_error_threshold_sweep/: comparison of action-error, source-labeled action/force/torque, and action+FT joint knot assignment. Source-labeled errors are never summed: the largest local group error supplies the knot and its recorded source label, while all three group-global RMSE values must independently meet the stopping tolerance.
• —results/episode_0000/four_regime_overview.png: exhaustive four-quadrant action-change/FT-change scatter and full-episode regime timeline

All time-axis figures use the same translucent mid-scale regime background: gray is low action/low FT, green is low action/high FT, blue is high action/low FT, and red is high action/high FT. Classification uses 21-step centered-mean changes, episode-global median thresholds, and a 15-step minimum binary-state duration, recorded exactly in study.json; these are signal-derived interpretations, not dataset ground-truth behavior or physical-contact labels.

• —code/: exact fitting, reporting, tests, and environment lockfile

Reproduce on CPU

uv sync --extra test
uv run pytest -q
uv run study-forceflow-bspline --episode 0 --output study_outputs

The code downloads only ForceFlow tabular data through Hugging Face streaming. It does not construct or execute a neural-network policy.

Method references

• —B-spline Policy
• —ForceFlow