| Name | motornet JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | |
| Summary | A PyTorch-powered python toolbox to train deep neural networks to perform motor tasks. |
| upload_time | 2024-01-04 19:43:44 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | |
| keywords |
motornet
pytorch
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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](https://oliviercodol.github.io/MotorNet/build/html/index.html) 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. This will install
version 0.2.0, which relies on PyTorch instead of TensorFlow. Please see the
[changelog](https://oliviercodol.github.io/MotorNet/build/html/documentation/changelog.html) for more details on the
difference between the current development release and the PyPI release.
```
pip install git+https://github.com/OlivierCodol/MotorNet.git@pytorch
```
**Please see the staged changes at the bottom of this file to see the changes currently implemented on this branch.**
### Install with `pip`
NOTE: The current PyPI version of `motornet` is 0.1.5, which relies on TensorFlow
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](https://pytorch.org/docs/stable/torch.html): MotorNet relies on PyTorch to create tensors and build the
graph.
- [NumPy](https://numpy.org/): For array and matrix computations when not using tensors.
- [Gymnasium](https://numpy.org/): `motornet` environments are child classes of `gymnasium` environments.
- [Matplotlib](https://matplotlib.org/): For plotting utilities, mainly in the
[plotor](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/plotor.py) module.
If you are running the current PyPI release (version 0.1.5), which relies on TensorFlow, the requirements are as follows.
- [TensorFlow](https://www.tensorflow.org/): 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](https://pypi.org/project/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](https://numpy.org/): For array and matrix computations when not using tensors.
- [Matplotlib](https://matplotlib.org/): For plotting utilities, mainly in the
[plotor](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/utils/plotor.py) module.
- [IPython](https://ipython.org/): Mainly for
[callbacks](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/nets/callbacks.py) that output training
metrics during model training.
- [joblib](https://joblib.readthedocs.io/en/latest/): For parallelization routines in the
[parallelizer](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/utils/parallelizer.py) script.
## Tutorials
There are several tutorials available to get you started, available in the
[repository](https://github.com/OlivierCodol/MotorNet)'s
[<em>examples</em>](https://github.com/OlivierCodol/MotorNet/tree/master/examples) folder, as well as on the
[documentation website](https://oliviercodol.github.io/MotorNet/build/html/index.html). 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](https://oliviercodol.github.io/MotorNet/build/html/documentation/changelog.html) for a curated log of update
contents [**Note: This will redirect to the main branch's changelog**].
### <font size="4">Version 0.2.0 - Staged changes</font>
First and foremost, this update moves `motornet` from `tensorflow` to `pytorch`. There has been systematic requests for
a `pytorch` implementation of this package, and over time it is becoming clear that this will enable better integration
with existing research efforts from the scientific community that this package is aiming to help. As a consequence,
many API changes and change in the code structure were made, as the logical structure of `pytorch` is fundamentally
different than that of `tensorflow`. These changes are further detailed below.
- Renamed the `motornet.plants` package to `effector` and the `motornet.plants.Plant` class to `Effector`, as 'plant'
is a specific engineering term and may be overly arcanic to a more general audience. Generally, the swap from "plant"
to "effector" has been enacted consistently in the text and code.
- `Task` object essentially perform computations pertaining to `environment` objects in typical simulation software for
machine learning. Therefore, the `motornet.tasks` module has been renamed `motornet.environment` and the `Task` base
class has been renamed to `Environment`. This is also now a subclass of [gymnasium](https://gymnasium.farama.org)'s
[gymnasium.Env](https://gymnasium.farama.org/api/env/#gymnasium-env) class, and it shares its API convention. The
motivation behind these changes is that `gymnasium` is a popular interfacing package for simulation environments
in machine learning, and standardizing `motornet`'s API according to `gymnasium` will enable wider cross-compatibility,
as well as facilitate familiarization efforts from a lot of researchers already accustomed to
`gymnasium`'s API. Users are strongly encouraged to check the updated tutorial notebooks on `motornet`'s GitHub
repository and on the online documentation website for more detailed explanation of the new `Environment` API, if they
are not alredy familiar with `gymnasium`. Generally, the swap from "task" to "environment" has been enacted consistently
in the text and code.
- `Pytorch` does not require the creation of end-to-end `model` objects as `tensorflow` does. Consequently, `motornet`
pipelines only require setting up an `Effector` and wrapping it up in an `Environment` object, without having to create
a `Network` object at all. Feedback delays and Gaussian noise are now handled directly by the `Environment` class.
- Removed all sub-packages in `motornet`. The `pytorch` implementation allows users to create their own loss and network
objects the way they typically would for any project beyond `motornet`, removing the need for a complex sub-packaging
structure differentiating between set of modules falling under the `nets` or `effectors` category. Therefore,
`motornet` now only contains modules. For instance, the `motornet.effector.muscle.Muscle` class is now directly
accessible as `motornet.muscle.Muscle`.
- The `motornet.plotor.plot_pos_over_time()` function now takes cartesian position as argument rather than full
cartesian states that include positions and velocities. In practice, the velocities were always discarded by that
function so we removed this step to allow for a more transparent and intuitive function syntax.
- The `muscle_type` argument of the `motornet.effector.Effector` class has been renamed to `muscle` for conciseness.
- The term `excitation` is now replaced by `action` to better match the terminology in place in continuous control
machine learning. Note that `action` and `activation` are not the same variables.
- Added a `motornet.effector.muscles.MujocoHillMuscle` class to the `muscle` module. This object instantiates MuJoCo's
Hill-type muscle as described in
[the MuJoCo documentation](https://mujoco.readthedocs.io/en/stable/modeling.html#muscle-actuators).
- The `motornet.utils.parallelizer.py` file has been removed, as the means of streamlining model training pipelines
usually boils down to personal preference.
- Users can now seed their `Environment` and `Effector` classes. Seeding is an important aspect of reproducible
programming, and is usually considered a "best practice". Since the `Environment` and `Effector` classes are the only
classes that make use of a random generator, these are the only classes that currently require seeding in `motornet`.
- All `motornet` objects now inherit from the `torch.nn.Module` class. Amongst other things, this allows easy device
assignment for model parameters, using `pytorch`'s usual `.to(device)` method.
- Renamed the `muscles`, `skeletons`, `effectors`, and `environments` modules to `muscle`, `skeleton`, `effector`, and
`environment` for conciseness.
Raw data
{
"_id": null,
"home_page": "",
"name": "motornet",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "motornet,pytorch",
"author": "",
"author_email": "Olivier Codol <codol.olivier@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/62/040c01b208e81175634030bb26af8e4da6103bcb2f18d1cbf4acdb344a95/motornet-0.2.0.tar.gz",
"platform": null,
"description": "# MotorNet\n\nThis repository contains **MotorNet**, a python package that allows training recurrent neural networks to control for\nbiomechanically realistic effectors. This toolbox is designed to meet several goals:\n\n- No hard dependencies beyond typically available python packages. This should make it easier to run this package on remote computing units.\n- Provide users with a variety of muscle types to chose from.\n- Flexibility in creating new, arbitrary muscle wrappings around the skeleton, to enable fast exploration of\ndifferent potential effectors and how to control them. The moment arm are calculated online according to the \ngeometry of the skeleton and the (user-defined) paths of the muscles.\n- User-friendly API, to allow for easier familiarization and intuitive usage. We want to enable a focus on ideas, not implementation.\nThe toolbox focuses on subclassing to allow users to implement their custom task designs, custom plants, and custom controller networks.\n- Open-source, to allow for user contribution and community-driven incremental progress.\n\n## State of the project\n\nThe package is feature complete, and is used by several people to progress in their research.\nWe are currently in beta phase, meaning the toolbox is publicly available but we are still on the lookout for potential\nbugs and fixes to apply. Please feel free to log an issue if you think you found a bug, we appreciate any contribution. \nStay tuned for more!\n\nAn [online documentation](https://oliviercodol.github.io/MotorNet/build/html/index.html) is available. Feel free to \ncheck it out.\n\n## How to Install\n\n### Install from source\n\nTo install the latest development release, you can install directly from GitHub's repository. This will install \nversion 0.2.0, which relies on PyTorch instead of TensorFlow. Please see the \n[changelog](https://oliviercodol.github.io/MotorNet/build/html/documentation/changelog.html) for more details on the\ndifference between the current development release and the PyPI release.\n\n```\npip install git+https://github.com/OlivierCodol/MotorNet.git@pytorch\n```\n\n**Please see the staged changes at the bottom of this file to see the changes currently implemented on this branch.**\n\n### Install with `pip`\n\nNOTE: The current PyPI version of `motornet` is 0.1.5, which relies on TensorFlow\n\nFirst, please make sure that the latest `pip` version is installed in your working environment.\n\n```\npython3 -m pip install -U pip\n```\n\nThen you can install `motornet` using a simple `pip install` command.\n```\npython3 -m pip install motornet\n```\n\n### Install with Anaconda\n\nInstallation via Anaconda is currently not supported.\n\n\n## Requirements\n\nThere is no third-party software required to run MotorNet. However, some freely available python dependencies are \nrequired.\n\nIf you are running the current development release (version 0.2.0), the requirements are as follows.\n\n- [PyTorch](https://pytorch.org/docs/stable/torch.html): MotorNet relies on PyTorch to create tensors and build the \ngraph.\n- [NumPy](https://numpy.org/): For array and matrix computations when not using tensors.\n- [Gymnasium](https://numpy.org/): `motornet` environments are child classes of `gymnasium` environments.\n- [Matplotlib](https://matplotlib.org/): For plotting utilities, mainly in the \n[plotor](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/plotor.py) module.\n\n\nIf you are running the current PyPI release (version 0.1.5), which relies on TensorFlow, the requirements are as follows.\n\n- [TensorFlow](https://www.tensorflow.org/): MotorNet is first and foremost built on TensorFlow. However, the standard\nTensorFlow toolbox is not compatible with recent Apple machines equipped with M1 silicon chips, and users must rely on \nan adapted version called [tensorflow-macos](https://pypi.org/project/tensorflow-macos/). When installing MotorNet, the \n`setup.py` routine will automatically check the machine's OS platform and hardware to assess whether to solve for the \n`tensorflow` or `tensorflow-macos` dependency. \n- [NumPy](https://numpy.org/): For array and matrix computations when not using tensors.\n- [Matplotlib](https://matplotlib.org/): For plotting utilities, mainly in the \n[plotor](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/utils/plotor.py) module.\n- [IPython](https://ipython.org/): Mainly for\n[callbacks](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/nets/callbacks.py) that output training \nmetrics during model training.\n- [joblib](https://joblib.readthedocs.io/en/latest/): For parallelization routines in the \n[parallelizer](https://github.com/OlivierCodol/MotorNet/blob/master/motornet/utils/parallelizer.py) script.\n\n\n## Tutorials\n\nThere are several tutorials available to get you started, available in the\n[repository](https://github.com/OlivierCodol/MotorNet)'s\n[<em>examples</em>](https://github.com/OlivierCodol/MotorNet/tree/master/examples) folder, as well as on the \n[documentation website](https://oliviercodol.github.io/MotorNet/build/html/index.html). Hopefully they will give a sense\nof how the API is supposed to work.\n\nTutorials and API documentation for version 0.1.5 are still available on the website and GitHib repository for those\nwho wish to consult them. They will remain available for the foreseeable future.\n\n## Changelog\n\nSee [here](https://oliviercodol.github.io/MotorNet/build/html/documentation/changelog.html) for a curated log of update \ncontents [**Note: This will redirect to the main branch's changelog**].\n\n\n### <font size=\"4\">Version 0.2.0 - Staged changes</font>\n\nFirst and foremost, this update moves `motornet` from `tensorflow` to `pytorch`. There has been systematic requests for \na `pytorch` implementation of this package, and over time it is becoming clear that this will enable better integration\nwith existing research efforts from the scientific community that this package is aiming to help. As a consequence,\nmany API changes and change in the code structure were made, as the logical structure of `pytorch` is fundamentally\ndifferent than that of `tensorflow`. These changes are further detailed below.\n\n\n- Renamed the `motornet.plants` package to `effector` and the `motornet.plants.Plant` class to `Effector`, as 'plant' \nis a specific engineering term and may be overly arcanic to a more general audience. Generally, the swap from \"plant\" \nto \"effector\" has been enacted consistently in the text and code.\n\n- `Task` object essentially perform computations pertaining to `environment` objects in typical simulation software for\nmachine learning. Therefore, the `motornet.tasks` module has been renamed `motornet.environment` and the `Task` base \nclass has been renamed to `Environment`. This is also now a subclass of [gymnasium](https://gymnasium.farama.org)'s\n[gymnasium.Env](https://gymnasium.farama.org/api/env/#gymnasium-env) class, and it shares its API convention. The \nmotivation behind these changes is that `gymnasium` is a popular interfacing package for simulation environments\nin machine learning, and standardizing `motornet`'s API according to `gymnasium` will enable wider cross-compatibility,\nas well as facilitate familiarization efforts from a lot of researchers already accustomed to \n`gymnasium`'s API. Users are strongly encouraged to check the updated tutorial notebooks on `motornet`'s GitHub\nrepository and on the online documentation website for more detailed explanation of the new `Environment` API, if they\nare not alredy familiar with `gymnasium`. Generally, the swap from \"task\" to \"environment\" has been enacted consistently\nin the text and code.\n\n- `Pytorch` does not require the creation of end-to-end `model` objects as `tensorflow` does. Consequently, `motornet`\npipelines only require setting up an `Effector` and wrapping it up in an `Environment` object, without having to create \na `Network` object at all. Feedback delays and Gaussian noise are now handled directly by the `Environment` class.\n\n- Removed all sub-packages in `motornet`. The `pytorch` implementation allows users to create their own loss and network \nobjects the way they typically would for any project beyond `motornet`, removing the need for a complex sub-packaging \nstructure differentiating between set of modules falling under the `nets` or `effectors` category. Therefore, \n`motornet` now only contains modules. For instance, the `motornet.effector.muscle.Muscle` class is now directly \naccessible as `motornet.muscle.Muscle`.\n\n- The `motornet.plotor.plot_pos_over_time()` function now takes cartesian position as argument rather than full \ncartesian states that include positions and velocities. In practice, the velocities were always discarded by that \nfunction so we removed this step to allow for a more transparent and intuitive function syntax.\n\n- The `muscle_type` argument of the `motornet.effector.Effector` class has been renamed to `muscle` for conciseness.\n\n- The term `excitation` is now replaced by `action` to better match the terminology in place in continuous control \nmachine learning. Note that `action` and `activation` are not the same variables.\n\n- Added a `motornet.effector.muscles.MujocoHillMuscle` class to the `muscle` module. This object instantiates MuJoCo's\nHill-type muscle as described in\n[the MuJoCo documentation](https://mujoco.readthedocs.io/en/stable/modeling.html#muscle-actuators).\n\n- The `motornet.utils.parallelizer.py` file has been removed, as the means of streamlining model training pipelines \nusually boils down to personal preference.\n\n- Users can now seed their `Environment` and `Effector` classes. Seeding is an important aspect of reproducible \nprogramming, and is usually considered a \"best practice\". Since the `Environment` and `Effector` classes are the only\nclasses that make use of a random generator, these are the only classes that currently require seeding in `motornet`.\n\n- All `motornet` objects now inherit from the `torch.nn.Module` class. Amongst other things, this allows easy device \nassignment for model parameters, using `pytorch`'s usual `.to(device)` method.\n\n- Renamed the `muscles`, `skeletons`, `effectors`, and `environments` modules to `muscle`, `skeleton`, `effector`, and\n`environment` for conciseness.\n",
"bugtrack_url": null,
"license": "",
"summary": "A PyTorch-powered python toolbox to train deep neural networks to perform motor tasks.",
"version": "0.2.0",
"project_urls": {
"Github": "https://github.com/OlivierCodol/MotorNet",
"Homepage": "https://oliviercodol.github.io/MotorNet/build/html/index.html"
},
"split_keywords": [
"motornet",
"pytorch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d062040c01b208e81175634030bb26af8e4da6103bcb2f18d1cbf4acdb344a95",
"md5": "a231afd1379ed0c152d937ca97859ed3",
"sha256": "7d972085adab86ea8df838cf03fd4bd25ab0c5f155443a8e2307afbd55ea1c7e"
},
"downloads": -1,
"filename": "motornet-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a231afd1379ed0c152d937ca97859ed3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 52523,
"upload_time": "2024-01-04T19:43:44",
"upload_time_iso_8601": "2024-01-04T19:43:44.967985Z",
"url": "https://files.pythonhosted.org/packages/d0/62/040c01b208e81175634030bb26af8e4da6103bcb2f18d1cbf4acdb344a95/motornet-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-04 19:43:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OlivierCodol",
"github_project": "MotorNet",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "motornet"
}
