revfly 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- revfly-2.0.0/PKG-INFO +106 -0
- revfly-2.0.0/README.md +157 -0
- revfly-2.0.0/packages/sensory-translator-v2/README.md +86 -0
- revfly-2.0.0/pyproject.toml +48 -0
- revfly-2.0.0/setup.cfg +4 -0
- revfly-2.0.0/src/revfly/__init__.py +23 -0
- revfly-2.0.0/src/revfly/__main__.py +6 -0
- revfly-2.0.0/src/revfly.egg-info/PKG-INFO +106 -0
- revfly-2.0.0/src/revfly.egg-info/SOURCES.txt +41 -0
- revfly-2.0.0/src/revfly.egg-info/dependency_links.txt +1 -0
- revfly-2.0.0/src/revfly.egg-info/entry_points.txt +3 -0
- revfly-2.0.0/src/revfly.egg-info/requires.txt +11 -0
- revfly-2.0.0/src/revfly.egg-info/top_level.txt +2 -0
- revfly-2.0.0/src/sensory_translator_v2/__init__.py +116 -0
- revfly-2.0.0/src/sensory_translator_v2/assets.py +924 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/__init__.py +19 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/base.py +484 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/mujoco_worker.py +1213 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/persistent_mujoco.py +592 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/v1_subprocess.py +364 -0
- revfly-2.0.0/src/sensory_translator_v2/backends/worker_protocol.py +108 -0
- revfly-2.0.0/src/sensory_translator_v2/bio/__init__.py +39 -0
- revfly-2.0.0/src/sensory_translator_v2/bio/lif_interface.py +624 -0
- revfly-2.0.0/src/sensory_translator_v2/bio/malecns_pools.py +204 -0
- revfly-2.0.0/src/sensory_translator_v2/bio/spiking.py +310 -0
- revfly-2.0.0/src/sensory_translator_v2/contracts.py +708 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/__init__.py +28 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/__main__.py +6 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/benchmark.py +346 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/cli.py +677 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/core.py +1269 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/multijoint.py +1003 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/openapi.py +385 -0
- revfly-2.0.0/src/sensory_translator_v2/engine/server.py +1431 -0
- revfly-2.0.0/src/sensory_translator_v2/evidence.py +84 -0
- revfly-2.0.0/src/sensory_translator_v2/goals.py +172 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/__init__.py +60 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/bridge.py +424 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/model.py +350 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/multijoint.py +805 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/optim.py +57 -0
- revfly-2.0.0/src/sensory_translator_v2/rate/trainer.py +618 -0
- revfly-2.0.0/src/sensory_translator_v2/runtime_install.py +370 -0
revfly-2.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: revfly
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: REvFLY engine for inverse motor-rate control in FlyMimic MuJoCo
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/IlleJiViN/REvFLY
|
|
7
|
+
Project-URL: Issues, https://github.com/IlleJiViN/REvFLY/issues
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
Requires-Dist: numpy>=2.0
|
|
12
|
+
Requires-Dist: torch>=2.4
|
|
13
|
+
Provides-Extra: physics
|
|
14
|
+
Requires-Dist: mujoco<3.4,>=3.3.0; extra == "physics"
|
|
15
|
+
Requires-Dist: dm-control>=1.0.28; extra == "physics"
|
|
16
|
+
Requires-Dist: imageio>=2.36; extra == "physics"
|
|
17
|
+
Requires-Dist: imageio-ffmpeg>=0.5; extra == "physics"
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
20
|
+
|
|
21
|
+
# REvFLY Python SDK and CLI
|
|
22
|
+
|
|
23
|
+
Python SDK and CLI for translating joint trajectories into continuous motor rates and replaying them with FlyMimic MuJoCo. The wheel installs the engine and its APIs. The release ZIP supplies the checkpoints, physics assets, and optional local Control Studio.
|
|
24
|
+
|
|
25
|
+
## Install from PyPI
|
|
26
|
+
|
|
27
|
+
Once the `revfly` distribution is listed on PyPI, install it for the SDK and CLI.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
python -m pip install revfly
|
|
31
|
+
revfly --version
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
For simulations, add the `physics` extra and download the runtime ZIP for the model checkpoints, physics assets, and local Control Studio. The physics workflow was tested on Linux x86-64 with Python 3.11. On Linux, you can install CPU Torch first to avoid downloading CUDA dependencies. Rendering uses the host's OpenGL/EGL libraries. [Runtime ZIP](https://github.com/IlleJiViN/REvFLY/releases/download/v2.0.0/revfly-2.0.0-local-beta.zip)
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
python3.11 -m venv .venv
|
|
38
|
+
source .venv/bin/activate
|
|
39
|
+
python -m pip install 'torch>=2.4' --index-url https://download.pytorch.org/whl/cpu
|
|
40
|
+
python -m pip install 'revfly[physics]'
|
|
41
|
+
revfly install-assets ./revfly-2.0.0-local-beta.zip
|
|
42
|
+
revfly verify-assets
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
To switch an existing environment, run `python -m pip uninstall sensory-translator-v2` before installing `revfly`. Both distributions share files and commands.
|
|
46
|
+
|
|
47
|
+
Assets are stored in `~/.local/share/sensory-translator-v2/bundle` or under `XDG_DATA_HOME`. An explicit `--asset-root` or `SENSORY_TRANSLATOR_V2_ASSET_ROOT` selects a different bundle. Source checkouts with the legacy physics assets keep their checkout defaults. Add `--replace` to install a different verified bundle in place. An extracted `bundle/` directory is also a valid input.
|
|
48
|
+
|
|
49
|
+
## Install from a GitHub wheel
|
|
50
|
+
|
|
51
|
+
Download the wheel alongside the runtime ZIP or extract it from the ZIP. Use the same virtual environment as above and replace the PyPI installation command with the wheel command. [GitHub release](https://github.com/IlleJiViN/REvFLY/releases/tag/v2.0.0)
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
python -m pip install './revfly-2.0.0-py3-none-any.whl[physics]'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Run a simulation
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
revfly run-multijoint --goal-family swing_scaled --scale 0.92 \
|
|
61
|
+
--mode fast --output ./swing-result --render
|
|
62
|
+
|
|
63
|
+
revfly serve --host 127.0.0.1 --port 8505 --ui \
|
|
64
|
+
--model-id 20261115_v2_fastbridge_lowenergy
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The first command writes the manifest, physics traces, and top-view video. The second serves the local [Control Studio](http://127.0.0.1:8505/) and the [OpenAPI specification](http://127.0.0.1:8505/openapi.json). For an environment without OpenGL, omit `--render` and set `MUJOCO_GL=disable` for headless inference.
|
|
68
|
+
|
|
69
|
+
## Use the Python API
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from contextlib import closing
|
|
73
|
+
|
|
74
|
+
from revfly import MultiJointEngine
|
|
75
|
+
|
|
76
|
+
with closing(MultiJointEngine()) as engine:
|
|
77
|
+
goal = engine.goal_from_family(family="swing_scaled", scale=0.92)
|
|
78
|
+
result = engine.run(goal["target_rad"], mode="fast", output="./swing-result")
|
|
79
|
+
print(result["best_rmse_deg"], result["independent_replay_verified"])
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Use `EngineV2` for single-axis simulation and `MultiJointEngine` for seven-axis left-front-leg simulation. `EngineV2Config` and `MultiJointEngineConfig` accept an explicit `asset_root` and optional separate `physics_python`. The default multi-joint checkpoint is `20261116_v2_multijoint15_resnorm`. Use `serve --multijoint-checkpoint PATH` or `run-multijoint --checkpoint PATH` to load a different model.
|
|
83
|
+
|
|
84
|
+
The multi-joint controller commands all 15 muscles. The bundle supports deterministic-interval, refractory Poisson, and direct LIF replay with separately reported simulation RMSE. Premotor connectome replay requires local MaleCNS data plus `pandas` and a Parquet reader such as `pyarrow`.
|
|
85
|
+
|
|
86
|
+
## Install from a Git tag
|
|
87
|
+
|
|
88
|
+
Run this in the target virtual environment. Download and install the runtime ZIP separately using `install-assets`.
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
python -m pip install 'revfly[physics] @ git+https://github.com/IlleJiViN/REvFLY.git@v2.0.0'
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Build and publish a team release
|
|
95
|
+
|
|
96
|
+
Build the wheel and source distribution from the repository root. Export the runtime files from a checkout that contains the trained checkpoints and FlyMimic assets.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
python -m pip install build
|
|
100
|
+
python -m build
|
|
101
|
+
revfly export-assets --asset-root . --dest dist/bundle --include-v2-models --include-ui
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
After editing UI sources, build `apps/control_ui` before exporting. The beta ZIP contains the wheel, `bundle/`, this README, third-party notices, the upstream FlyMimic license, and `SHA256SUMS`.
|
|
105
|
+
|
|
106
|
+
After pushing the matching Git tag, attach the wheel and ZIP to that tag's pre-release.
|
revfly-2.0.0/README.md
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# REvFLY
|
|
2
|
+
|
|
3
|
+
REvFLY is a Python engine that **estimates the continuous motor firing rates needed to produce a target joint trajectory in a fruit fly simulation**. It controls seven joint axes and 15 muscles in the left front leg of FlyMimic's MuJoCo model. It provides a Python API, CLI, local HTTP API, and a control interface with top-view playback.
|
|
4
|
+
|
|
5
|
+
On nine synthetic targets from three motion families held out from training and model selection, starting the search from model predictions lowered mean joint-angle RMSE from **10.412° to 6.056°** under the same 30-second forward search. The number of targets above the 5.7296° threshold fell from **9/9 to 3/9**. [Benchmark protocol and full results](reports/unseen_motion_families_v2/README.md)
|
|
6
|
+
|
|
7
|
+
[Installation](#installation) · [Python and HTTP APIs](#python-and-http-apis) · [Benchmark](#held-out-motion-benchmark) · [Presentation and demonstration guide](docs/PRESENTATION.md)
|
|
8
|
+
|
|
9
|
+
## How it works
|
|
10
|
+
|
|
11
|
+
FlyMimic's musculoskeletal simulator takes muscle drives and computes joint motion. REvFLY uses that simulator to solve the inverse problem of finding muscle drives for a desired trajectory. Multiple firing-rate patterns can produce similar motion, so the engine evaluates candidates by replaying them in the same physics model and measuring joint-angle error. [FlyMimic paper](https://proceedings.iclr.cc/paper_files/paper/2026/hash/222843b731e2c7813291586e2b39fe89-Abstract-Conference.html) · [FlyMimic source](https://github.com/gizemozd/FlyMimic)
|
|
12
|
+
|
|
13
|
+
```mermaid
|
|
14
|
+
flowchart LR
|
|
15
|
+
A["Target joint angles 211 × 7<br/>Initial pose"] --> B["Trained ResidualNorm MLP"]
|
|
16
|
+
B --> C["Continuous firing-rate knots<br/>15 channels × 105 time points"]
|
|
17
|
+
C --> D["Firing rates to muscle drives"]
|
|
18
|
+
D --> E["FlyMimic / MuJoCo<br/>Forward simulation"]
|
|
19
|
+
E --> F["Joint angles, errors, and top-view video"]
|
|
20
|
+
E -. "Optional refinement" .-> C
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| Stage | Interface |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| Input | A `211 × 7` target joint-angle matrix in radians spanning 420 ms, with optional initial offsets for the seven axes. |
|
|
26
|
+
| Control scope | Left front leg coxa yaw, pitch, and roll, trochanter yaw, pitch, and roll, and tibia pitch. The body stays fixed. |
|
|
27
|
+
| Model | `ResidualNormRateMLP` estimates channel firing rates from the target and initial pose. The default checkpoint is `20261116_v2_multijoint15_resnorm`. |
|
|
28
|
+
| Output | 105 firing-rate knots per motor channel, constrained to 0–200 Hz and converted to muscle drives at 2 ms intervals. The engine drives all 15 muscles with the estimated rates. |
|
|
29
|
+
| Verification | Records the target and simulated joint angles, per-axis errors, and firing rates. Replays the selected muscle inputs in an independent run. |
|
|
30
|
+
|
|
31
|
+
The firing rate is a continuous control signal in spikes per second for each motor channel. The benchmark below uses continuous-rate replay. With optional explicit-spike or LIF replay, the engine reports the joint-angle errors for that path. Validation of electrical stimulation parameters and electrode waveforms is outside the experimental scope. [Firing-rate bridge](src/sensory_translator_v2/rate/bridge.py)
|
|
32
|
+
|
|
33
|
+
### Run modes
|
|
34
|
+
|
|
35
|
+
| Mode | Behavior |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `fast` | Simulates the firing rates predicted by the trained model. |
|
|
38
|
+
| `auto` | Attempts refinement up to the configured iteration limit when the initial candidate exceeds the error threshold. |
|
|
39
|
+
| `refine` | Refines the candidate firing rates up to the configured iteration limit. |
|
|
40
|
+
| `closed_loop` | Adjusts muscle drives during replay with PD feedback from simulated joint angles and velocities. |
|
|
41
|
+
|
|
42
|
+
Training used firing rates fitted to muscle inputs and joint-angle errors measured in simulation. The model weights are fixed at inference. Refinement adjusts the firing rates for the current target. The engine replays candidates that pass the gradient check and keeps a candidate when replay confirms a lower error. A persistent physics worker reuses the compiled MuJoCo model and initializes each replay independently. [Training code](src/sensory_translator_v2/rate/multijoint.py) · [Multi-joint engine](src/sensory_translator_v2/engine/multijoint.py)
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
Install the Python SDK and CLI from PyPI once the `revfly` distribution is listed.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install revfly
|
|
50
|
+
revfly --version
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
You can also download and install the release wheel with `python -m pip install ./revfly-2.0.0-py3-none-any.whl`. [Release wheel](https://github.com/IlleJiViN/REvFLY/releases/download/v2.0.0/revfly-2.0.0-py3-none-any.whl)
|
|
54
|
+
|
|
55
|
+
To run simulations, install the `physics` extra in a Python 3.11 environment and install the runtime bundle. The bundle supplies the model checkpoints, FlyMimic assets, and local UI. This workflow was tested on Linux x86-64. [Runtime ZIP](https://github.com/IlleJiViN/REvFLY/releases/download/v2.0.0/revfly-2.0.0-local-beta.zip)
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
python3.11 -m venv .venv
|
|
59
|
+
source .venv/bin/activate
|
|
60
|
+
python -m pip install 'torch>=2.4' --index-url https://download.pytorch.org/whl/cpu
|
|
61
|
+
python -m pip install 'revfly[physics]'
|
|
62
|
+
revfly install-assets ./revfly-2.0.0-local-beta.zip
|
|
63
|
+
revfly verify-assets
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
For a direct wheel install with simulation support, use `python -m pip install './revfly-2.0.0-py3-none-any.whl[physics]'` in the same environment. If you installed the previous `sensory-translator-v2` distribution, run `python -m pip uninstall sensory-translator-v2` before installing `revfly` because the distributions share files and commands.
|
|
67
|
+
|
|
68
|
+
### Top-view demo
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
revfly run-multijoint --goal-family swing_scaled --scale 0.92 \
|
|
72
|
+
--mode fast --output ./swing-result --render
|
|
73
|
+
|
|
74
|
+
revfly serve --host 127.0.0.1 --port 8505 --ui \
|
|
75
|
+
--model-id 20261115_v2_fastbridge_lowenergy
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The first command saves the target, firing rates, simulated trajectories, top-view video, and run metadata. The second starts the local interface to select a preset and compare the target to replay on each axis. For headless execution, omit `--render` and set `MUJOCO_GL=disable` if needed. Rendering requires the host's OpenGL/EGL runtime. [Local Control Studio](http://127.0.0.1:8505/) · [Installation and build details](packages/sensory-translator-v2/README.md)
|
|
79
|
+
|
|
80
|
+

|
|
81
|
+
|
|
82
|
+
The swing preset in fast mode reached a joint-angle RMSE of 1.578° in this installation and rendering demo.
|
|
83
|
+
|
|
84
|
+
## Python and HTTP APIs
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from contextlib import closing
|
|
88
|
+
|
|
89
|
+
from revfly import MultiJointEngine
|
|
90
|
+
|
|
91
|
+
with closing(MultiJointEngine()) as engine:
|
|
92
|
+
goal = engine.goal_from_family(family="swing_scaled", scale=0.92)
|
|
93
|
+
result = engine.run(goal["target_rad"], mode="fast", output="./swing-result")
|
|
94
|
+
print(result["best_rmse_deg"])
|
|
95
|
+
print(result["independent_replay_verified"])
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
For a custom target, pass a `211 × 7` matrix in radians in the expected joint-axis order to `engine.run(target_rad)`. `best_rmse_deg` is the simulated tracking error, `independent_replay_verified` confirms independent replay of the selected command, and `accuracy_threshold_met` reports whether the run met the accuracy threshold. Use `EngineV2` for the single-joint API.
|
|
99
|
+
|
|
100
|
+
The HTTP server supports goal generation, asynchronous runs, and result downloads.
|
|
101
|
+
|
|
102
|
+
| Request | Action |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `GET /v2/capabilities` | Inspect available motions, control scope, and run modes. |
|
|
105
|
+
| `GET /v2/multijoint/goal?family=swing_scaled&scale=0.92` | Generate a seven-axis target trajectory. |
|
|
106
|
+
| `POST /v2/multijoint/jobs` | Submit a target trajectory and options. |
|
|
107
|
+
| `GET /v2/jobs/{job_id}` | Check progress and retrieve the result. |
|
|
108
|
+
| `GET /v2/jobs/{job_id}/download` | Download the result bundle. |
|
|
109
|
+
|
|
110
|
+
The running server exposes the request and response schemas through OpenAPI. [Local OpenAPI schema](http://127.0.0.1:8505/openapi.json) · [Schema source](src/sensory_translator_v2/engine/openapi.py)
|
|
111
|
+
|
|
112
|
+
## Held-out motion benchmark
|
|
113
|
+
|
|
114
|
+
With the checkpoint fixed, we generated three targets each from **sequential muscle-group pulses, variable-frequency antagonist drive, and coactivation followed by release**. These families were held out from training and model selection. Each target came from replaying in-range firing rates in the same MuJoCo model. Optimization received only the target joint angles and initial pose. Each target's nearest training trajectory was 10.72–22.86° away in joint-angle RMSE.
|
|
115
|
+
|
|
116
|
+
The direct search starts from a target-independent baseline waveform. MLP initialization starts from rates predicted for the target. Both methods used the same 57 low-frequency search directions and a 30-second budget, ranking candidates by simulated tracking error. The budget included MLP inference. Setup and final independent replay were timed separately.
|
|
117
|
+
|
|
118
|
+
| Nine targets, 30 seconds of forward search each | Direct search | MLP initialization + same search |
|
|
119
|
+
| --- | ---: | ---: |
|
|
120
|
+
| Initial mean RMSE | 23.347° | 12.541° |
|
|
121
|
+
| Final mean RMSE | 10.412° | **6.056°** |
|
|
122
|
+
| Worst target RMSE | 13.634° | **9.530°** |
|
|
123
|
+
| Targets above the threshold | 9/9 | **3/9** |
|
|
124
|
+
|
|
125
|
+
The target RMSE takes the square root of the mean squared error over 211 time points and seven axes. Mean RMSE averages these per-target values across nine targets. A target fails when its RMSE exceeds 0.1 rad (5.7296°). MLP initialization produced lower final error on all nine targets. Trochanter yaw had the highest remaining error with MLP initialization, with a worst-target RMSE of 13.440° and peak absolute error of 31.534°. All 18 selected commands reproduced identical trajectories on independent replay.
|
|
126
|
+
|
|
127
|
+
In a separate L-BFGS experiment using gradients from the physics model with the same targets and time budget, 15 of 18 runs stopped at the gradient check. The final mean error was 23.347° with direct initialization and 9.353° with MLP initialization. All targets exceeded the threshold (9/9) under both methods.
|
|
128
|
+
|
|
129
|
+

|
|
130
|
+
|
|
131
|
+
[Methods and results by joint axis](reports/unseen_motion_families_v2/README.md) · [Trial CSV](reports/unseen_motion_families_v2/trials.csv) · [Worst joint errors CSV](reports/unseen_motion_families_v2/per_joint_worst.csv)
|
|
132
|
+
|
|
133
|
+
### Reproduction
|
|
134
|
+
|
|
135
|
+
Install the wheel and runtime assets, then clone the matching source tag. The scripts run the gradient-based comparison and the forward search. Set `--asset-root` to the default installation path or to your runtime bundle.
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
git clone --branch v2.0.0 https://github.com/IlleJiViN/REvFLY.git
|
|
139
|
+
cd REvFLY
|
|
140
|
+
assets="${XDG_DATA_HOME:-$HOME/.local/share}/sensory-translator-v2/bundle"
|
|
141
|
+
PYTHONPATH=src python scripts/benchmark_v2_unseen_families.py \
|
|
142
|
+
--asset-root "$assets" --output results/unseen_lbfgs --budget-s 30
|
|
143
|
+
PYTHONPATH=src python scripts/benchmark_v2_unseen_forward.py \
|
|
144
|
+
--asset-root "$assets" --source results/unseen_lbfgs --output results/unseen_forward
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The original runs were parallelized across three Linux logical CPUs. Hardware and system load affect how many physics rollouts fit within 30 seconds. Compare the methods in pairs on the same system and use the generated targets and run records to check the results. [Test configuration](reports/unseen_motion_families_v2/methods.json) · [Generated targets](reports/unseen_motion_families_v2/targets.npz)
|
|
148
|
+
|
|
149
|
+
## Research scope and history
|
|
150
|
+
|
|
151
|
+
- **REvFLY** turns target trajectories into firing-rate commands and compares the resulting motion in a single simulator. The nine targets are synthetic fixed-body tasks, each lasting 420 ms. Live fruit fly control, natural-language commands, whole-body walking, and electrode stimulation require separate validation.
|
|
152
|
+
- **Earlier audio experiments** aligned response patterns between a human auditory model and a simulated fruit fly auditory system using synthetic audio. The music pilot reached the audio preparation stage.
|
|
153
|
+
- **Earlier sensory-to-motor GNN experiments** predicted motor neuron membrane potential from visual and olfactory stimuli. The GNN fell below the mean predictor and ridge regression on the primary metric. REvFLY's seven-axis inverse controller uses an MLP conditioned on target angles and a musculoskeletal simulator.
|
|
154
|
+
|
|
155
|
+
## Credits
|
|
156
|
+
|
|
157
|
+
The musculoskeletal model is from Özdil et al., *Musculoskeletal simulation of limb movement biomechanics in Drosophila melanogaster* (ICLR 2026). The REvFLY runtime ZIP contains FlyMimic's physics XML and meshes, a subset of the reference joint angles from demo `0002`, and teacher rollouts generated in simulation. [Paper](https://proceedings.iclr.cc/paper_files/paper/2026/hash/222843b731e2c7813291586e2b39fe89-Abstract-Conference.html) · [FlyMimic revision](https://github.com/gizemozd/FlyMimic/tree/9ea11316) · [FlyMimic license](FlyMimic-LICENSE.txt) · [UI third-party notices](THIRD_PARTY_NOTICES.txt)
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# REvFLY Python SDK and CLI
|
|
2
|
+
|
|
3
|
+
Python SDK and CLI for translating joint trajectories into continuous motor rates and replaying them with FlyMimic MuJoCo. The wheel installs the engine and its APIs. The release ZIP supplies the checkpoints, physics assets, and optional local Control Studio.
|
|
4
|
+
|
|
5
|
+
## Install from PyPI
|
|
6
|
+
|
|
7
|
+
Once the `revfly` distribution is listed on PyPI, install it for the SDK and CLI.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
python -m pip install revfly
|
|
11
|
+
revfly --version
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
For simulations, add the `physics` extra and download the runtime ZIP for the model checkpoints, physics assets, and local Control Studio. The physics workflow was tested on Linux x86-64 with Python 3.11. On Linux, you can install CPU Torch first to avoid downloading CUDA dependencies. Rendering uses the host's OpenGL/EGL libraries. [Runtime ZIP](https://github.com/IlleJiViN/REvFLY/releases/download/v2.0.0/revfly-2.0.0-local-beta.zip)
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
python3.11 -m venv .venv
|
|
18
|
+
source .venv/bin/activate
|
|
19
|
+
python -m pip install 'torch>=2.4' --index-url https://download.pytorch.org/whl/cpu
|
|
20
|
+
python -m pip install 'revfly[physics]'
|
|
21
|
+
revfly install-assets ./revfly-2.0.0-local-beta.zip
|
|
22
|
+
revfly verify-assets
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
To switch an existing environment, run `python -m pip uninstall sensory-translator-v2` before installing `revfly`. Both distributions share files and commands.
|
|
26
|
+
|
|
27
|
+
Assets are stored in `~/.local/share/sensory-translator-v2/bundle` or under `XDG_DATA_HOME`. An explicit `--asset-root` or `SENSORY_TRANSLATOR_V2_ASSET_ROOT` selects a different bundle. Source checkouts with the legacy physics assets keep their checkout defaults. Add `--replace` to install a different verified bundle in place. An extracted `bundle/` directory is also a valid input.
|
|
28
|
+
|
|
29
|
+
## Install from a GitHub wheel
|
|
30
|
+
|
|
31
|
+
Download the wheel alongside the runtime ZIP or extract it from the ZIP. Use the same virtual environment as above and replace the PyPI installation command with the wheel command. [GitHub release](https://github.com/IlleJiViN/REvFLY/releases/tag/v2.0.0)
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
python -m pip install './revfly-2.0.0-py3-none-any.whl[physics]'
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Run a simulation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
revfly run-multijoint --goal-family swing_scaled --scale 0.92 \
|
|
41
|
+
--mode fast --output ./swing-result --render
|
|
42
|
+
|
|
43
|
+
revfly serve --host 127.0.0.1 --port 8505 --ui \
|
|
44
|
+
--model-id 20261115_v2_fastbridge_lowenergy
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The first command writes the manifest, physics traces, and top-view video. The second serves the local [Control Studio](http://127.0.0.1:8505/) and the [OpenAPI specification](http://127.0.0.1:8505/openapi.json). For an environment without OpenGL, omit `--render` and set `MUJOCO_GL=disable` for headless inference.
|
|
48
|
+
|
|
49
|
+
## Use the Python API
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from contextlib import closing
|
|
53
|
+
|
|
54
|
+
from revfly import MultiJointEngine
|
|
55
|
+
|
|
56
|
+
with closing(MultiJointEngine()) as engine:
|
|
57
|
+
goal = engine.goal_from_family(family="swing_scaled", scale=0.92)
|
|
58
|
+
result = engine.run(goal["target_rad"], mode="fast", output="./swing-result")
|
|
59
|
+
print(result["best_rmse_deg"], result["independent_replay_verified"])
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Use `EngineV2` for single-axis simulation and `MultiJointEngine` for seven-axis left-front-leg simulation. `EngineV2Config` and `MultiJointEngineConfig` accept an explicit `asset_root` and optional separate `physics_python`. The default multi-joint checkpoint is `20261116_v2_multijoint15_resnorm`. Use `serve --multijoint-checkpoint PATH` or `run-multijoint --checkpoint PATH` to load a different model.
|
|
63
|
+
|
|
64
|
+
The multi-joint controller commands all 15 muscles. The bundle supports deterministic-interval, refractory Poisson, and direct LIF replay with separately reported simulation RMSE. Premotor connectome replay requires local MaleCNS data plus `pandas` and a Parquet reader such as `pyarrow`.
|
|
65
|
+
|
|
66
|
+
## Install from a Git tag
|
|
67
|
+
|
|
68
|
+
Run this in the target virtual environment. Download and install the runtime ZIP separately using `install-assets`.
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
python -m pip install 'revfly[physics] @ git+https://github.com/IlleJiViN/REvFLY.git@v2.0.0'
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Build and publish a team release
|
|
75
|
+
|
|
76
|
+
Build the wheel and source distribution from the repository root. Export the runtime files from a checkout that contains the trained checkpoints and FlyMimic assets.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
python -m pip install build
|
|
80
|
+
python -m build
|
|
81
|
+
revfly export-assets --asset-root . --dest dist/bundle --include-v2-models --include-ui
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
After editing UI sources, build `apps/control_ui` before exporting. The beta ZIP contains the wheel, `bundle/`, this README, third-party notices, the upstream FlyMimic license, and `SHA256SUMS`.
|
|
85
|
+
|
|
86
|
+
After pushing the matching Git tag, attach the wheel and ZIP to that tag's pre-release.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "revfly"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "REvFLY engine for inverse motor-rate control in FlyMimic MuJoCo"
|
|
9
|
+
readme = "packages/sensory-translator-v2/README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
classifiers = ["Development Status :: 4 - Beta"]
|
|
13
|
+
dependencies = [
|
|
14
|
+
"numpy>=2.0",
|
|
15
|
+
"torch>=2.4",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
physics = [
|
|
20
|
+
"mujoco>=3.3.0,<3.4",
|
|
21
|
+
"dm-control>=1.0.28",
|
|
22
|
+
"imageio>=2.36",
|
|
23
|
+
"imageio-ffmpeg>=0.5",
|
|
24
|
+
]
|
|
25
|
+
dev = [
|
|
26
|
+
"pytest>=8.0",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.scripts]
|
|
30
|
+
revfly = "revfly.__main__:main"
|
|
31
|
+
sensory-engine-v2 = "sensory_translator_v2.engine.cli:main"
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Repository = "https://github.com/IlleJiViN/REvFLY"
|
|
35
|
+
Issues = "https://github.com/IlleJiViN/REvFLY/issues"
|
|
36
|
+
|
|
37
|
+
[tool.setuptools]
|
|
38
|
+
include-package-data = false
|
|
39
|
+
|
|
40
|
+
[tool.setuptools.dynamic]
|
|
41
|
+
version = {attr = "sensory_translator_v2.__version__"}
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.package-dir]
|
|
44
|
+
"" = "src"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools.packages.find]
|
|
47
|
+
where = ["src"]
|
|
48
|
+
include = ["revfly", "sensory_translator_v2*"]
|
revfly-2.0.0/setup.cfg
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""Public REvFLY Python API."""
|
|
2
|
+
|
|
3
|
+
from sensory_translator_v2 import __version__
|
|
4
|
+
from sensory_translator_v2.engine import (
|
|
5
|
+
EngineV2,
|
|
6
|
+
EngineV2Config,
|
|
7
|
+
MultiJointEngine,
|
|
8
|
+
MultiJointEngineConfig,
|
|
9
|
+
RateControlV2App,
|
|
10
|
+
RateControlV2HTTPServer,
|
|
11
|
+
evaluate_bio_realization,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"EngineV2",
|
|
16
|
+
"EngineV2Config",
|
|
17
|
+
"MultiJointEngine",
|
|
18
|
+
"MultiJointEngineConfig",
|
|
19
|
+
"RateControlV2App",
|
|
20
|
+
"RateControlV2HTTPServer",
|
|
21
|
+
"__version__",
|
|
22
|
+
"evaluate_bio_realization",
|
|
23
|
+
]
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: revfly
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: REvFLY engine for inverse motor-rate control in FlyMimic MuJoCo
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/IlleJiViN/REvFLY
|
|
7
|
+
Project-URL: Issues, https://github.com/IlleJiViN/REvFLY/issues
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
Requires-Dist: numpy>=2.0
|
|
12
|
+
Requires-Dist: torch>=2.4
|
|
13
|
+
Provides-Extra: physics
|
|
14
|
+
Requires-Dist: mujoco<3.4,>=3.3.0; extra == "physics"
|
|
15
|
+
Requires-Dist: dm-control>=1.0.28; extra == "physics"
|
|
16
|
+
Requires-Dist: imageio>=2.36; extra == "physics"
|
|
17
|
+
Requires-Dist: imageio-ffmpeg>=0.5; extra == "physics"
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
20
|
+
|
|
21
|
+
# REvFLY Python SDK and CLI
|
|
22
|
+
|
|
23
|
+
Python SDK and CLI for translating joint trajectories into continuous motor rates and replaying them with FlyMimic MuJoCo. The wheel installs the engine and its APIs. The release ZIP supplies the checkpoints, physics assets, and optional local Control Studio.
|
|
24
|
+
|
|
25
|
+
## Install from PyPI
|
|
26
|
+
|
|
27
|
+
Once the `revfly` distribution is listed on PyPI, install it for the SDK and CLI.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
python -m pip install revfly
|
|
31
|
+
revfly --version
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
For simulations, add the `physics` extra and download the runtime ZIP for the model checkpoints, physics assets, and local Control Studio. The physics workflow was tested on Linux x86-64 with Python 3.11. On Linux, you can install CPU Torch first to avoid downloading CUDA dependencies. Rendering uses the host's OpenGL/EGL libraries. [Runtime ZIP](https://github.com/IlleJiViN/REvFLY/releases/download/v2.0.0/revfly-2.0.0-local-beta.zip)
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
python3.11 -m venv .venv
|
|
38
|
+
source .venv/bin/activate
|
|
39
|
+
python -m pip install 'torch>=2.4' --index-url https://download.pytorch.org/whl/cpu
|
|
40
|
+
python -m pip install 'revfly[physics]'
|
|
41
|
+
revfly install-assets ./revfly-2.0.0-local-beta.zip
|
|
42
|
+
revfly verify-assets
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
To switch an existing environment, run `python -m pip uninstall sensory-translator-v2` before installing `revfly`. Both distributions share files and commands.
|
|
46
|
+
|
|
47
|
+
Assets are stored in `~/.local/share/sensory-translator-v2/bundle` or under `XDG_DATA_HOME`. An explicit `--asset-root` or `SENSORY_TRANSLATOR_V2_ASSET_ROOT` selects a different bundle. Source checkouts with the legacy physics assets keep their checkout defaults. Add `--replace` to install a different verified bundle in place. An extracted `bundle/` directory is also a valid input.
|
|
48
|
+
|
|
49
|
+
## Install from a GitHub wheel
|
|
50
|
+
|
|
51
|
+
Download the wheel alongside the runtime ZIP or extract it from the ZIP. Use the same virtual environment as above and replace the PyPI installation command with the wheel command. [GitHub release](https://github.com/IlleJiViN/REvFLY/releases/tag/v2.0.0)
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
python -m pip install './revfly-2.0.0-py3-none-any.whl[physics]'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Run a simulation
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
revfly run-multijoint --goal-family swing_scaled --scale 0.92 \
|
|
61
|
+
--mode fast --output ./swing-result --render
|
|
62
|
+
|
|
63
|
+
revfly serve --host 127.0.0.1 --port 8505 --ui \
|
|
64
|
+
--model-id 20261115_v2_fastbridge_lowenergy
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The first command writes the manifest, physics traces, and top-view video. The second serves the local [Control Studio](http://127.0.0.1:8505/) and the [OpenAPI specification](http://127.0.0.1:8505/openapi.json). For an environment without OpenGL, omit `--render` and set `MUJOCO_GL=disable` for headless inference.
|
|
68
|
+
|
|
69
|
+
## Use the Python API
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from contextlib import closing
|
|
73
|
+
|
|
74
|
+
from revfly import MultiJointEngine
|
|
75
|
+
|
|
76
|
+
with closing(MultiJointEngine()) as engine:
|
|
77
|
+
goal = engine.goal_from_family(family="swing_scaled", scale=0.92)
|
|
78
|
+
result = engine.run(goal["target_rad"], mode="fast", output="./swing-result")
|
|
79
|
+
print(result["best_rmse_deg"], result["independent_replay_verified"])
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Use `EngineV2` for single-axis simulation and `MultiJointEngine` for seven-axis left-front-leg simulation. `EngineV2Config` and `MultiJointEngineConfig` accept an explicit `asset_root` and optional separate `physics_python`. The default multi-joint checkpoint is `20261116_v2_multijoint15_resnorm`. Use `serve --multijoint-checkpoint PATH` or `run-multijoint --checkpoint PATH` to load a different model.
|
|
83
|
+
|
|
84
|
+
The multi-joint controller commands all 15 muscles. The bundle supports deterministic-interval, refractory Poisson, and direct LIF replay with separately reported simulation RMSE. Premotor connectome replay requires local MaleCNS data plus `pandas` and a Parquet reader such as `pyarrow`.
|
|
85
|
+
|
|
86
|
+
## Install from a Git tag
|
|
87
|
+
|
|
88
|
+
Run this in the target virtual environment. Download and install the runtime ZIP separately using `install-assets`.
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
python -m pip install 'revfly[physics] @ git+https://github.com/IlleJiViN/REvFLY.git@v2.0.0'
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Build and publish a team release
|
|
95
|
+
|
|
96
|
+
Build the wheel and source distribution from the repository root. Export the runtime files from a checkout that contains the trained checkpoints and FlyMimic assets.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
python -m pip install build
|
|
100
|
+
python -m build
|
|
101
|
+
revfly export-assets --asset-root . --dest dist/bundle --include-v2-models --include-ui
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
After editing UI sources, build `apps/control_ui` before exporting. The beta ZIP contains the wheel, `bundle/`, this README, third-party notices, the upstream FlyMimic license, and `SHA256SUMS`.
|
|
105
|
+
|
|
106
|
+
After pushing the matching Git tag, attach the wheel and ZIP to that tag's pre-release.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
packages/sensory-translator-v2/README.md
|
|
4
|
+
src/revfly/__init__.py
|
|
5
|
+
src/revfly/__main__.py
|
|
6
|
+
src/revfly.egg-info/PKG-INFO
|
|
7
|
+
src/revfly.egg-info/SOURCES.txt
|
|
8
|
+
src/revfly.egg-info/dependency_links.txt
|
|
9
|
+
src/revfly.egg-info/entry_points.txt
|
|
10
|
+
src/revfly.egg-info/requires.txt
|
|
11
|
+
src/revfly.egg-info/top_level.txt
|
|
12
|
+
src/sensory_translator_v2/__init__.py
|
|
13
|
+
src/sensory_translator_v2/assets.py
|
|
14
|
+
src/sensory_translator_v2/contracts.py
|
|
15
|
+
src/sensory_translator_v2/evidence.py
|
|
16
|
+
src/sensory_translator_v2/goals.py
|
|
17
|
+
src/sensory_translator_v2/runtime_install.py
|
|
18
|
+
src/sensory_translator_v2/backends/__init__.py
|
|
19
|
+
src/sensory_translator_v2/backends/base.py
|
|
20
|
+
src/sensory_translator_v2/backends/mujoco_worker.py
|
|
21
|
+
src/sensory_translator_v2/backends/persistent_mujoco.py
|
|
22
|
+
src/sensory_translator_v2/backends/v1_subprocess.py
|
|
23
|
+
src/sensory_translator_v2/backends/worker_protocol.py
|
|
24
|
+
src/sensory_translator_v2/bio/__init__.py
|
|
25
|
+
src/sensory_translator_v2/bio/lif_interface.py
|
|
26
|
+
src/sensory_translator_v2/bio/malecns_pools.py
|
|
27
|
+
src/sensory_translator_v2/bio/spiking.py
|
|
28
|
+
src/sensory_translator_v2/engine/__init__.py
|
|
29
|
+
src/sensory_translator_v2/engine/__main__.py
|
|
30
|
+
src/sensory_translator_v2/engine/benchmark.py
|
|
31
|
+
src/sensory_translator_v2/engine/cli.py
|
|
32
|
+
src/sensory_translator_v2/engine/core.py
|
|
33
|
+
src/sensory_translator_v2/engine/multijoint.py
|
|
34
|
+
src/sensory_translator_v2/engine/openapi.py
|
|
35
|
+
src/sensory_translator_v2/engine/server.py
|
|
36
|
+
src/sensory_translator_v2/rate/__init__.py
|
|
37
|
+
src/sensory_translator_v2/rate/bridge.py
|
|
38
|
+
src/sensory_translator_v2/rate/model.py
|
|
39
|
+
src/sensory_translator_v2/rate/multijoint.py
|
|
40
|
+
src/sensory_translator_v2/rate/optim.py
|
|
41
|
+
src/sensory_translator_v2/rate/trainer.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|