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.
Files changed (43) hide show
  1. revfly-2.0.0/PKG-INFO +106 -0
  2. revfly-2.0.0/README.md +157 -0
  3. revfly-2.0.0/packages/sensory-translator-v2/README.md +86 -0
  4. revfly-2.0.0/pyproject.toml +48 -0
  5. revfly-2.0.0/setup.cfg +4 -0
  6. revfly-2.0.0/src/revfly/__init__.py +23 -0
  7. revfly-2.0.0/src/revfly/__main__.py +6 -0
  8. revfly-2.0.0/src/revfly.egg-info/PKG-INFO +106 -0
  9. revfly-2.0.0/src/revfly.egg-info/SOURCES.txt +41 -0
  10. revfly-2.0.0/src/revfly.egg-info/dependency_links.txt +1 -0
  11. revfly-2.0.0/src/revfly.egg-info/entry_points.txt +3 -0
  12. revfly-2.0.0/src/revfly.egg-info/requires.txt +11 -0
  13. revfly-2.0.0/src/revfly.egg-info/top_level.txt +2 -0
  14. revfly-2.0.0/src/sensory_translator_v2/__init__.py +116 -0
  15. revfly-2.0.0/src/sensory_translator_v2/assets.py +924 -0
  16. revfly-2.0.0/src/sensory_translator_v2/backends/__init__.py +19 -0
  17. revfly-2.0.0/src/sensory_translator_v2/backends/base.py +484 -0
  18. revfly-2.0.0/src/sensory_translator_v2/backends/mujoco_worker.py +1213 -0
  19. revfly-2.0.0/src/sensory_translator_v2/backends/persistent_mujoco.py +592 -0
  20. revfly-2.0.0/src/sensory_translator_v2/backends/v1_subprocess.py +364 -0
  21. revfly-2.0.0/src/sensory_translator_v2/backends/worker_protocol.py +108 -0
  22. revfly-2.0.0/src/sensory_translator_v2/bio/__init__.py +39 -0
  23. revfly-2.0.0/src/sensory_translator_v2/bio/lif_interface.py +624 -0
  24. revfly-2.0.0/src/sensory_translator_v2/bio/malecns_pools.py +204 -0
  25. revfly-2.0.0/src/sensory_translator_v2/bio/spiking.py +310 -0
  26. revfly-2.0.0/src/sensory_translator_v2/contracts.py +708 -0
  27. revfly-2.0.0/src/sensory_translator_v2/engine/__init__.py +28 -0
  28. revfly-2.0.0/src/sensory_translator_v2/engine/__main__.py +6 -0
  29. revfly-2.0.0/src/sensory_translator_v2/engine/benchmark.py +346 -0
  30. revfly-2.0.0/src/sensory_translator_v2/engine/cli.py +677 -0
  31. revfly-2.0.0/src/sensory_translator_v2/engine/core.py +1269 -0
  32. revfly-2.0.0/src/sensory_translator_v2/engine/multijoint.py +1003 -0
  33. revfly-2.0.0/src/sensory_translator_v2/engine/openapi.py +385 -0
  34. revfly-2.0.0/src/sensory_translator_v2/engine/server.py +1431 -0
  35. revfly-2.0.0/src/sensory_translator_v2/evidence.py +84 -0
  36. revfly-2.0.0/src/sensory_translator_v2/goals.py +172 -0
  37. revfly-2.0.0/src/sensory_translator_v2/rate/__init__.py +60 -0
  38. revfly-2.0.0/src/sensory_translator_v2/rate/bridge.py +424 -0
  39. revfly-2.0.0/src/sensory_translator_v2/rate/model.py +350 -0
  40. revfly-2.0.0/src/sensory_translator_v2/rate/multijoint.py +805 -0
  41. revfly-2.0.0/src/sensory_translator_v2/rate/optim.py +57 -0
  42. revfly-2.0.0/src/sensory_translator_v2/rate/trainer.py +618 -0
  43. 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
+ ![Top view of the seven-axis left front leg moving with the FlyMimic body fixed](docs/media/top_view_swing.gif)
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
+ ![Tracking error on held-out motion families under matching 30-second budgets](reports/unseen_motion_families_v2/comparison.png)
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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,6 @@
1
+ """Run the REvFLY CLI with python -m revfly."""
2
+
3
+ from sensory_translator_v2.engine.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
@@ -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,3 @@
1
+ [console_scripts]
2
+ revfly = revfly.__main__:main
3
+ sensory-engine-v2 = sensory_translator_v2.engine.cli:main
@@ -0,0 +1,11 @@
1
+ numpy>=2.0
2
+ torch>=2.4
3
+
4
+ [dev]
5
+ pytest>=8.0
6
+
7
+ [physics]
8
+ mujoco<3.4,>=3.3.0
9
+ dm-control>=1.0.28
10
+ imageio>=2.36
11
+ imageio-ffmpeg>=0.5
@@ -0,0 +1,2 @@
1
+ revfly
2
+ sensory_translator_v2