Skip to content

Commit aa89d2d

Browse files
dbellicoso-bdaiexploy-bot
authored andcommitted
Update docs (#90)
### What change is being made Update exporter tutorial. Fix link. ### Why this change is being made N/A ### Tested N/A GitOrigin-RevId: 2d1bd16fb21e4b9a31256c27ad0d1ecf2cb57d52
1 parent e90bb43 commit aa89d2d

10 files changed

Lines changed: 48 additions & 26 deletions

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ We use [Pixi](https://pixi.sh) to build this repository. See the
101101
target_link_libraries(my_controller PRIVATE exploy)
102102
```
103103

104-
See [`examples/controller/`](examples/controller/) for a complete working example.
104+
See [`examples/controller/`](https://github.com/bdaiinstitute/exploy/blob/main/examples/controller) for a complete working example.
105105

106106
#### Initialize the environment and install dependencies
107107

docs/tutorial/exporter/exporter_tutorial.md

Lines changed: 44 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -396,55 +396,74 @@ This traces all registered torch operations — observation computation, the act
396396
processing — and writes them into a single ONNX graph. The resulting file contains the full
397397
computation pipeline from raw inputs to commanded outputs, along with the metadata you registered.
398398

399-
---
399+
### Inspecting and understanding the generated ONNX files
400+
When exporting an environment and its actor, Exploy produces `policy.onnx` (or whatever filename
401+
is passed to `export_environment_as_onnx()`). That exported file can then be used for evaluation
402+
(see [Putting It All Together](#putting-it-all-together)) or for deployment in a controller
403+
(see [Controller Tutorial](../controller/controller_tutorial.md)).
404+
405+
The export contains two execution paths by design: **Default** and **ProcessActions**. The
406+
**Default** path runs at the policy rate and includes observation computation plus actor inference,
407+
while the **ProcessActions** path runs at the simulation rate and captures the computational graph
408+
for action post-processing and command application that occurs at every simulation sub-step. This
409+
separation preserves the original control timing (policy step vs. simulation sub-step) in the
410+
exported model.
411+
412+
Additionally, Exploy will produce debug computational graphs. These are only to be used for
413+
debugging and visual inspection.
414+
415+
- `debug/policy_default.onnx`: The `Default` path of the computational graph.
416+
- `debug/policy_process_actions.onnx`: The `ProcessActions` path of the computational graph.
417+
- `debug/policy_optimized.onnx`: The optimized version of the exported ONNX model.
418+
419+
420+
> **Note:** `debug/policy_optimized.onnx` is generated when `optimize=True` is passed to
421+
> {py:class}`SessionWrapper <exploy.exporter.core.session_wrapper.SessionWrapper>`. While fully
422+
> functional, it requires the same ONNX Runtime version to be used in both the exporter and the
423+
> controller. This constraint depends on the user's setup.
424+
> For deployment in a controller, only the `policy.onnx` file should be used.
400425
401-
## Visualizing the Exported ONNX Graph
426+
427+
### Visualizing the Exported ONNX Graph
402428

403429
You can inspect the exported ONNX file using [Netron](https://github.com/lutzroeder/netron), an
404430
open-source viewer for neural network models. The screenshots below show the computational graphs
405-
produced by the export steps in this tutorial.
406-
407-
### Overview
431+
produced by the export steps in this tutorial. The [unit test](https://github.com/bdaiinstitute/exploy/blob/main/python/exploy/exporter/core/tests/test_export_environment.py) runs on three different environments:
432+
- an environment that computes observations and uses an MLP actor
433+
- an environment that uses a torch module to compute parts of its observations and uses an MLP actor
434+
- an environment that uses a torch module to compute parts of its observations and uses an RNN-based actor
408435

409-
The exported ONNX file contains two subgraphs: a **Default** graph that computes observations and
436+
Each exported ONNX file contains two subgraphs: a **Default** graph that computes observations and
410437
actions at the policy rate, and a **ProcessActions** graph that maps raw actions to commanded
411438
outputs at the simulation rate.
412439

413-
![Overview of the exported ONNX graph](exporter_tutorial_netron_overview.png)
414440

415-
### Default graph (basic environment)
441+
#### Environment and MLP Actor
416442

417443
This is the full default graph for the basic `Environment` from Step 1. You can see the named
418-
inputs (`foo`, `bar`, `baz`, `memory.actions.in`) flowing through the observation computation
419-
and into the actor network, which produces actions and the named outputs (`out`,
420-
`memory.actions.out`).
421-
422-
![Default graph for the basic environment](exporter_tutorial_netron_default.png)
444+
inputs (`foo`), the group inputs (`bar`, `baz`), and the memory inputs (`memory.actions.in`) flowing
445+
through the observation computation and into the actor network, which produces actions and the named
446+
outputs (`out`, `memory.actions.out`). The ProcessActions subgraph traces only `process_actions()`
447+
and `apply_actions()`. It runs at the simulation time-step rate (i.e., once per decimation sub-step)
448+
and maps actions to commanded outputs.
423449

424-
### ProcessActions subgraph
450+
![Overview of the exported ONNX graph](exporter_tutorial_netron_env.svg)
425451

426-
The ProcessActions subgraph traces only `process_actions()` and `apply_actions()`. It runs at the
427-
simulation time-step rate (i.e., once per decimation sub-step) and maps actions to commanded
428-
outputs.
429-
430-
![ProcessActions subgraph](exporter_tutorial_netron_process_actions.png)
431-
432-
### Default graph with a torch module
452+
#### Environment with a torch module and MLP Actor
433453

434454
When the environment includes a learnable `torch.nn.Module` (see the
435455
[Advanced: Using Torch Modules in Observations](#advanced-using-torch-modules-in-observations)
436456
section), the module's parameters and operations appear in the graph:
437457

438-
![Default graph for environment with torch module](exporter_tutorial_netron_envwithmodule_default.png)
458+
![Default graph for environment with torch module](exporter_tutorial_netron_env_with_module.svg)
439459

440-
### Default graph with a torch module and an RNN actor
460+
#### Environment with a torch module and an RNN Actor
441461

442462
When using an RNN-based actor (see
443463
[Advanced: RNN-Based Actors](#advanced-rnn-based-actors)), the graph includes the LSTM hidden
444464
states as additional memory inputs and outputs:
445465

446-
![Default graph for environment with torch module and RNN actor](exporter_tutorial_netron_envwithmodule_rnnactor_default.png)
447-
466+
![Default graph for environment with torch module and RNN actor](exporter_tutorial_netron_env_with_module_rnn_actor.svg)
448467
---
449468

450469
## Step 6 — Load and Run the Exported Model
-27.3 KB
Binary file not shown.

docs/tutorial/exporter/exporter_tutorial_netron_env.svg

Lines changed: 1 addition & 0 deletions
Loading

docs/tutorial/exporter/exporter_tutorial_netron_env_with_module.svg

Lines changed: 1 addition & 0 deletions
Loading

docs/tutorial/exporter/exporter_tutorial_netron_env_with_module_rnn_actor.svg

Lines changed: 1 addition & 0 deletions
Loading
Binary file not shown.
Binary file not shown.
-19.6 KB
Binary file not shown.
Binary file not shown.

0 commit comments

Comments
 (0)