vollo_trees_compiler

Bindings for the Vollo tree compiler.

This module provides functions to compile models to vollo-trees programs, and to evaluate these programs.

class vollo_trees_compiler.Config

Hardware configuration for compiling a forest to a program

static from_json(json_path: str) → Config: Load a configuration from a JSON file

max_input_features: Maximum number of input features

max_tree_depth: Maximum depth of a tree

num_partitions: Number of partitions the tree units are split into, one per SLR on boards that have them. The program’s result does not depend on it and a bitstream accepts a program compiled for any count; it refines the cycle estimate. Absent from older configurations, which have one.

num_tree_units: Number of tree units

unit_ram_depth: Maximum number of nodes in each tree unit

class vollo_trees_compiler.Forest

An internal representation of a forest of decision trees

static forests_to_program_f32(forests: list[Forest], config: Config) → ProgramF32

Compile a list of forests into a single multi-model program where nodes have f32 comparators and the inputs are f32. Every forest must state its leaves in the same precision (see output_precision()), which is the format the outputs are delivered in.

Emits a UserWarning when the program compiles but a model’s outputs resolve to less than their format’s precision.

static from_onnx(path: str) → Forest: Convert an ONNX model with a TreeEnsembleRegressor (https://onnx.ai/onnx/operators/onnx_aionnxml_TreeEnsembleRegressor.html) node to a vollo-trees Forest representation

max_depth() → int: Get the maximum depth of the trees in the forest

num_input_features() → int: Get the number of input features expected by the forest

num_trees() → int: Get the number of trees in the forest

output_precision() → str: The format a program compiled from this forest delivers its outputs in (“f32” or “f64”), which follows the precision the ONNX model stated its leaves in.

to_program_f32(config: Config) → ProgramF32

Compile the forest to a program where nodes have f32 comparators and the inputs are f32. The output format follows the precision the model stated its leaves in (see output_precision()).

Emits a UserWarning when the program compiles but its outputs resolve to less than their format’s precision.

class vollo_trees_compiler.ProgramF32

A compiled program where comparators and leaves are float32 values

config() → Config

eval(input: List[float], model_ix: int = 0) → float: Evaluate the program on a given input.

eval_with_cycle_estimate(&self, input: Vec<f32>, model_ix: int = 0) -> (f64, int): Evaluate a program on a given input, and return the result along with the estimated number of cycles For a worst-case cycle count estimate see pessimistic_cycle_estimate().

static load(input_path: str) → ProgramF32: Load the program from the specified file path

static load_bytes(data: bytes) → Program

pessimistic_cycle_estimate(model_ix: int = 0) → int: Return a pessimistic estimate of the number of cycles required to calculate the result of an inference. This is calculated based on the maximum length branch in each tree. For an input-based cycle count see eval_with_cycle_estimate().

save(output_path: str): Save the program to the specified file path

save_bytes() → bytes

exception vollo_trees_compiler.FromOnnxError: Error occuring while converting an ONNX model to a vollo-trees Forest

exception vollo_trees_compiler.ForestCompileError: Error occuring while compiling a Forest to a Program