rlx-opt 0.2.5

RLX optimizer facade — fusion, autodiff, and compile pipelines
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# rlx-opt

Facade crate that re-exports [`rlx-fusion`], [`rlx-autodiff`], and [`rlx-compile`]
with the historical `rlx_opt::` module paths. Most callers use [`rlx`] and
import `rlx::opt::*`; depend on `rlx-opt` directly only when you want the
optimizer stack without the runtime.

## Crate split (0.2)

| Crate | Role |
|-------|------|
| [`rlx-fusion`] | MIR fusion passes, `Pass` trait, `unfuse_fused_for_autodiff` |
| [`rlx-autodiff`] | `grad_with_loss`, `jvp`, `hvp`, `vmap`, `prepare_graph_for_ad` |
| [`rlx-compile`] | `CompilePipeline`, legalization, memory plan, precision / PTQ |

Implementation lives in those crates; `rlx-opt` only wires backward-compatible
`rlx_opt::fusion`, `rlx_opt::autodiff`, `rlx_opt::legalize`, etc.

## Features

| Feature | Enables |
|---------|---------|
| `compile` *(default)* | `rlx-compile` — HIR → MIR → LIR pipeline |
| `training` *(default)* | `rlx-autodiff` — reverse / forward AD, vmap |
| `full` | both |

## Fusion pipeline (via `rlx-compile`)

Fusion is **backend-aware**: `fusion_passes_for_supported` selects passes from a
backend's `OpKind` claim set so the optimizer never emits fused ops the target
cannot lower (e.g. Metal may skip `FuseAttentionBlock`).

Typical order:

1. **Constant folding** — fold compile-time-known subgraphs.
2. **Fusion passes** — gated pattern fusions + elementwise regions.
3. **Legalize** — broadcast materialization, backend-specific rewrites.
4. **Memory plan** — liveness → arena buffer assignment.
5. **DCE** — dead-code elimination (last in the fusion pipeline).

See [`rlx-fusion/README.md`](../rlx-fusion/README.md) and
[`rlx-compile/README.md`](../rlx-compile/README.md) for crate-local detail.

## Install

```toml
[dependencies]
rlx-opt = "0.2"
```

## Build / test

```sh
cargo build -p rlx-opt
cargo test  -p rlx-fusion -p rlx-autodiff -p rlx-compile
```

## Gotchas

- Pass order matters: const-fold before fusion; memory plan after fusion.
- New fused ops need `Op` + infer + verifier + every backend thunk you target.
- `precision` inserts `Cast` nodes; some are eliminated by fusion peepholes.

## License

GPL-3.0-only.

[`rlx`]: https://docs.rs/rlx
[`rlx-fusion`]: ../rlx-fusion/README.md
[`rlx-autodiff`]: ../rlx-autodiff/README.md
[`rlx-compile`]: ../rlx-compile/README.md