MotorNet

This repository contains MotorNet, a python package that allows training recurrent neural networks to control for biomechanically realistic effectors. This toolbox is designed to meet several goals:

No hard dependencies beyond typically available python packages. This should make it easier to run this package on remote computing units.
Provide users with a variety of muscle types to chose from.
Flexibility in creating new, arbitrary muscle wrappings around the skeleton, to enable fast exploration of different potential effectors and how to control them. The moment arm are calculated online according to the geometry of the skeleton and the (user-defined) paths of the muscles.
User-friendly API, to allow for easier familiarization and intuitive usage. We want to enable a focus on ideas, not implementation. The toolbox focuses on subclassing to allow users to implement their custom task designs, custom plants, and custom controller networks.
Open-source, to allow for user contribution and community-driven incremental progress.

State of the project

The package is feature complete, and is used by several people to progress in their research. We are currently in beta phase, meaning the toolbox is publicly available but we are still on the lookout for potential bugs and fixes to apply. Please feel free to log an issue if you think you found a bug, we appreciate any contribution. Stay tuned for more!

An online documentation is available. Feel free to check it out.

How to Install

Install from source

To install the latest development release, you can install directly from GitHub's repository.

pip install git+https://github.com/OlivierCodol/MotorNet.git

Install with `pip`

First, please make sure that the latest pip version is installed in your working environment.

python3 -m pip install -U pip

Then you can install motornet using a simple pip install command.

python3 -m pip install motornet

Install with Anaconda

Installation via Anaconda is currently not supported.

Requirements

There is no third-party software required to run MotorNet. However, some freely available python dependencies are required.

If you are running the current development release (version 0.2.0), the requirements are as follows.

PyTorch: MotorNet relies on PyTorch to create tensors and build the graph.
NumPy: For array and matrix computations when not using tensors.
Gymnasium: motornet environments are child classes of gymnasium environments.
Matplotlib: For plotting utilities, mainly in the plotor module.

If you are running a release version < 0.2.0, which relies on TensorFlow, the requirements are as follows.

TensorFlow: MotorNet is first and foremost built on TensorFlow. However, the standard TensorFlow toolbox is not compatible with recent Apple machines equipped with M1 silicon chips, and users must rely on an adapted version called tensorflow-macos. When installing MotorNet, the setup.py routine will automatically check the machine's OS platform and hardware to assess whether to solve for the tensorflow or tensorflow-macos dependency.
NumPy: For array and matrix computations when not using tensors.
Matplotlib: For plotting utilities, mainly in the plotor module.
IPython: Mainly for callbacks that output training metrics during model training.
joblib: For parallelization routines in the parallelizer script.

Tutorials

There are several tutorials available to get you started, available in the repository's examples folder, as well as on the documentation website. Hopefully they will give a sense of how the API is supposed to work.

Tutorials and API documentation for version 0.1.5 are still available on the website and GitHib repository for those who wish to consult them. They will remain available for the foreseeable future.

Changelog

See here for a curated log of update contents.

OlivierCodol/MotorNet