canvas_engineering.compiler

Program compilation: lower a CanvasProgram to a deploy-ready execution plan. ProgramCompiler.compile() accepts an optional runtime torch.nn.Module and actually materializes the compile modes — freezing parameters, replacing them with same-valued buffers for constant regions, and serializing state_dict to disk for export regions.

canvas_engineering.compiler.CompiledProgram dataclass

Deploy-ready execution plan produced by ProgramCompiler.

Attributes:

Name	Type	Description
schema	CanvasSchema	Potentially reduced CanvasSchema (inactive regions removed).
active_regions	Set[str]	Set of region names still alive at deploy.
frozen_regions	Set[str]	Set of region names with frozen parameters.
constant_regions	Set[str]	Set of regions materialized as buffers.
exported_memories	Set[str]	Dict of region names exported to disk.
active_connections	List[Connection]	Connections between active regions only.
constant_buffers	Dict[str, Tensor]	For each constant region, the materialized tensor stored alongside the compiled plan (populated when compile() is given a runtime module).
exported_paths	Dict[str, str]	For each exported region, the file path the region's state was written to.

n_eliminated property

Number of regions eliminated from the training graph.

canvas_engineering.compiler.ProgramCompiler

Lowers a CanvasProgram to a deploy-ready CompiledProgram.

Compile passes applied in order: 1. freeze: mark compile_mode="freeze" regions (no gradient) 2. constant: mark compile_mode="constant" regions (materialize as buffer, remove from active) 3. export: mark compile_mode="export" regions (save to disk, remove from active) 4. dead elimination: remove connections involving inactive regions

Usage

compiler = ProgramCompiler(program) compiled = compiler.compile()

compile(module=None, export_dir=None)

Run all compile passes and return a CompiledProgram.

Parameters:

Name	Type	Description	Default
module	Optional[Module]	Optional runtime nn.Module whose parameters are organized by region (the module must expose a regions attribute mapping region names to submodules). When supplied: - frozen regions have .requires_grad_(False) applied - constant regions have their parameters detached and re-registered as buffers (no further training) - exported regions are saved to disk via torch.save(submodule.state_dict(), path) and then detached (.requires_grad_(False)) on the running module so they no longer participate in training. When None the modes are still recorded on the returned CompiledProgram for later application.	None
export_dir	Optional[str]	Directory used for compile_mode='export' regions. Defaults to ./canvas_exports if any region is exported and module is supplied.	None

Returns:

Type	Description
CompiledProgram	CompiledProgram with active/frozen/constant/exported region
CompiledProgram	sets and (if module was given) constant_buffers and
CompiledProgram	exported_paths populated.