Skip to content

How-to Guides

[[toc]]

These recipes cover day-to-day tasks: compiling programs, exporting artifacts, caching, and configuring runtime policies.

Compile across backends

from pathlib import Path

from fuse import Program

source = Path("examples/04_mlp.fuse").read_text()
program = Program(source)

# Default is backend="auto"; pass backend explicitly to force an engine.
auto_runner = program.compile()  # chooses based on hardware/workload
auto_runner()

from pathlib import Path

from fuse import Program
from fuse import torch as fuse_torch

program = Program(Path("examples/04_mlp.fuse").read_text())
torch_runner = fuse_torch.compile(program, device="auto")
torch_runner()

python -m fuse run examples/04_mlp.fuse --backend numpy --cache .cache

Tip

Switching between backends is a compile-time choice. The DSL stays identical across engines, so you can validate behaviour under NumPy before deploying with Torch or JAX.

Auto backend selection

Program.compile() now defaults to backend="auto". The chooser considers the execution mode, projection strategy, streaming usage, and hardware to pick an engine:

  • NumPy for demand mode, Monte Carlo projection, or streaming workloads.
  • Torch on CUDA/MPS for deep-learning–like programs (e.g., attention/MLP) when available.
  • JAX for heavier batched workloads when JAX is installed and can amortize JIT.
  • Falls back to NumPy on small programs or when accelerators aren’t available.

Force a specific backend with program.compile(backend="numpy"|"torch"|"jax").

Export to TorchScript / ONNX

from pathlib import Path

from fuse import Program, to_torchscript, to_onnx

program = Program(Path("examples/04_mlp.fuse").read_text())
script_module = to_torchscript(program)
onxx_model = to_onnx(program)

Note

TorchScript export returns a torch.jit.ScriptModule. The ONNX helper writes to disk and returns the file path.

Enable caching

from pathlib import Path

from fuse import Program

program = Program(Path("examples/05_transformer_block.fuse").read_text())
runner = program.compile(backend="numpy", cache_dir=".cache")
runner()

Cache directories persist compiled IR and backend artifacts. Reuse the same path across runs to skip recompilation.

Configure runtime policies

Policies drive weight loading, quantisation, sharding, and LoRA adapters. Mix and match to match your deployment constraints.

from pathlib import Path

from fuse import Program, RuntimePolicies, ManifestWeightStore

program = Program(Path("examples/05_transformer_block.fuse").read_text())
policies = RuntimePolicies(
    weight_store=ManifestWeightStore("examples/ckpt/manifest.json"),
    strict_weights=True,
)
runner = program.compile(backend="numpy", policies=policies)

Policy debugging

Call policies.describe() to inspect active rules. During execution, Program.explain() captures policy-driven caching events alongside tensor traces.