filtered-transformations
Use Equinox filtered JAX transformations over mixed PyTree models.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- filtered-transformations
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Use Equinox filtered JAX transformations over mixed PyTree models.
- disable-model-invocation
- true
02 资源文件 2
- 参考文档references/filtered-transformations.md5.5 KB
- 参考文档references/troubleshooting.md4.7 KB
03 SKILL.md 正文
Filtered Transformations
Use this sub-skill when applying JAX transforms to Equinox modules or other mixed PyTrees whose leaves are not all arrays.
Use when
- A raw
jax.jit,jax.grad,jax.vmap, orjax.pmaprejects an Equinox model or callable PyTree. - The task names
filter_jit,filter_grad,filter_value_and_grad,filter_vmap,filter_pmap,filter_eval_shape,filter_make_jaxpr,filter_shard,filter_checkpoint, orfilter_pure_callback. - The user needs custom filtered derivatives with
filter_custom_jvporfilter_custom_vjp. - A training step must combine filtered gradients, Optax updates, and JIT.
- The task involves pmap/sharding behavior for PyTrees with static leaves.
Route elsewhere
- Use
../module-and-trees/when the main task is defining fields, partitioning a model manually, or performing tree surgery. - Use
../nn-and-state/when the main task is layer construction,BatchNorm,Sequential,State, or inference-mode toggles. - Use
../diagnostics-and-serialization/for runtime error/debug behavior, serialization, or pretty printing. - Use
../internal-advanced/forequinox.internal.noinline, internal loops, primitive authoring helpers, or other semi-public utilities.
Read first
references/filtered-transformations.mdfor API groups, patterns, and examples.references/troubleshooting.mdfor transform-specific failure modes.../../references/api-reference.mdfor signature summaries.
Core workflow
- Determine which leaves should be traced as arrays. Equinox defaults usually treat JAX/NumPy arrays as dynamic and everything else as static.
- Replace raw JAX transforms with the corresponding
eqx.filter_*transform when a whole mixed PyTree crosses the transform boundary. - Use
eqx.partition/eqx.combineonly when you need explicit control or a raw JAX transform API. - For training steps, put loss, gradient computation, optimizer update, and
eqx.apply_updatesinside one compiled function when possible. - For batched models, remember that most
equinox.nnlayers act on one example; usejax.vmaporeqx.filter_vmaparound the call. - For
filter_pmaporfilter_shard, check the device/sharding assumptions before declaring backend coverage.
Minimal validation
From the generated skill root (set EQUINOX_SKILL_ROOT to its absolute path),
run the bundled smoke helper after installing Equinox:
cd "$EQUINOX_SKILL_ROOT" && python scripts/smoke.py --mode transformations
For CPU multi-device filter_pmap smoke coverage:
cd "$EQUINOX_SKILL_ROOT" && python scripts/smoke.py --mode transformations --two-cpu-devices
The helper configures two logical CPU devices before importing JAX when that flag is supplied.
Scope note
This sub-skill distills Equinox's filtered transform behavior into the bundled references and smoke helper. The source repository and its test/docs checkout were construction evidence only, not runtime dependencies.
Key cautions
- A CPU
filter_pmapsmoke validates API structure, not accelerator semantics. filter_graddifferentiates floating-point/complex array leaves in the first argument and returns a PyTree matching that input; nondifferentiable/static leaves appear asNonegradients.- Donation options are explicit:
filter_jitsupportsdonate="all","all-except-first", warning variants, and"none";filter_pmapsupports"all","warn", and"none". - If a problem is actually about layer state or batch normalization axes, route
to
nn-and-stateafter confirming the transform boundary.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).