realtime-smm 0.1.2

No project description provided

realtime-smm

This project is the official codebase for the T-RO paper A Learning-Based Method for Computing Self-Motion Manifolds of Redundant Robots for Real-Time Fault-Tolerant Motion Planning.

realtime-smm is a learning-based toolkit for computing self-motion manifolds (SMMs) of redundant robots fast enough for realtime global motion planning.

Overview

• Cache-focused data pipeline that stores raw and post-processed SMM samples during grid construction.
• Per-cluster neural regressors trained on Fourier-series targets with optional low-pass filtering and XY half-plane canonicalisation.
• Bundled inference model (SMMNetworkBundle) that selects the correct regressor with a classifier, reconstructs joint trajectories, and can upsample output resolutions.
• Optional basin-hopping pretraining (via pytorch-minimize) before standard PyTorch optimisers to help escape poor initialisations.
• Example notebook-style script (examples/smms_3r.py) that trains, loads, and visualises overlays against analytical solutions.

Features

• Caching: Uses platformdirs to create per-run cache folders that persist raw grids, post-processed clusters, and trained models.
• Cluster-centric training: Each connected workspace cluster yields its own neural network while a classifier predicts the correct cluster at inference time.
• Fourier targets: SMMs are transformed to Fourier space, optionally truncated with fft_cutoff, and reconstructed via analytic IFFT for smooth representation.
• XY half-plane canonicalisation: Input transforms are rotated into a canonical frame, with the orientation offset reapplied after prediction.
• Upsampling: SMMNetworkBundle.__call__ supports samples= to evaluate the learned Fourier representation at arbitrary resolutions.
• Progress feedback: Training loops use tqdm progress bars when available and log final losses per cluster.

Installation

pip install realtime-smm

Optional basin-hopping pretraining relies on pytorch-minimize, which is not published on PyPI. Install it manually if you plan to use that feature:

pip install git+https://github.com/gngdb/pytorch-minimize.git

Using Poetry:

poetry install
pip install git+https://github.com/gngdb/pytorch-minimize.git

Quickstart

realtime-smm exposes a narrow public surface in realtime_smm.main:

from realtime_smm import (
    Robot,
    GridParams,
    SMMSolverParams,
    TrainingConfig,
    training_pipeline,
    load_trained_bundle,
)

robot = Robot([...])  # Define DH links
grid_params = GridParams(pos_resolution=0.01, use_xy_halfplane=True)
smm_params = SMMSolverParams(samples=64)
config = TrainingConfig(epochs=1000, fft_cutoff=20)

bundle = training_pipeline(
    robot,
    grid_params=grid_params,
    smm_params=smm_params,
    training_config=config,
    name="my_robot_run",
)

bundle = load_trained_bundle(name="my_robot_run")
T = np.eye(4)
ws_smms = bundle(T, samples=256)  # Predict upsampled SMMs

Only call the top-level helpers from main.py and adjust behaviour through the configuration dataclasses re-exported in __init__.py.

Cache Management

You can clear cached runs when experimenting:

from realtime_smm import clear_cache

clear_cache(name="my_robot_run")  # Remove a single run
clear_cache()  # Prompt before clearing every cache directory

Examples

examples/smms_3r.py demonstrates the full workflow, including plotting predicted vs. analytical SMM projections. Run it after installation to sanity-check dependencies and visualise results.

License

MIT. See LICENSE for details.