Merge branch 'develop' into pr/600

.github/workflows/test.yaml

@@ -9,5 +9,5 @@ jobs:
       - uses: actions/checkout@v3
       - uses: software-mansion/setup-scarb@v1
         with:
-          scarb-version: "2.5.3"
+          scarb-version: "2.6.4"
       - run: scarb test --workspace && scarb fmt --workspace

.tool-versions

@@ -1 +1 @@
-scarb 2.5.3
+scarb 2.6.4

Scarb.toml

@@ -1,6 +1,6 @@
 [package]
 name = "orion"
-version = "0.2.4"
+version = "0.2.5"
 cairo-version = "2.5.3"
 edition = "2023_10"
 description = "ONNX Runtime in Cairo for verifiable ML inference using STARK"

docgen/src/main.rs

@@ -59,6 +59,14 @@ fn main() {
     doc_trait(trait_path, doc_path, label);
     doc_functions(trait_path, doc_path, trait_name, label);
 
+    // TREE ENSEMBLE DOC
+    let trait_path = "src/operators/ml/tree_ensemble/tree_ensemble.cairo";
+    let doc_path = "docs/framework/operators/machine-learning/tree-ensemble";
+    let label = "tree_ensemble";
+    let trait_name: &str = "TreeEnsembleTrait";
+    doc_trait(trait_path, doc_path, label);
+    doc_functions(trait_path, doc_path, trait_name, label);
+
     // LINEAR REGRESSOR DOC
     let trait_path = "src/operators/ml/linear/linear_regressor.cairo";
     let doc_path = "docs/framework/operators/machine-learning/linear-regressor";

docs/SUMMARY.md

@@ -113,6 +113,7 @@
     * [tensor.qlinear\_matmul](framework/operators/tensor/tensor.qlinear\_matmul.md)
     * [tensor.qlinear\_concat](framework/operators/tensor/tensor.qlinear\_concat.md)
     * [tensor.qlinear\_leakyrelu](framework/operators/tensor/tensor.qlinear\_leakyrelu.md)
+    * [tensor.qlinear\_conv](framework/operators/tensor/tensor.qlinear\_conv.md)
     * [tensor.nonzero](framework/operators/tensor/tensor.nonzero.md)
     * [tensor.squeeze](framework/operators/tensor/tensor.squeeze.md)
     * [tensor.unsqueeze](framework/operators/tensor/tensor.unsqueeze.md)
@@ -174,10 +175,13 @@
     * [nn.gemm](framework/operators/neural-network/nn.gemm.md)
     * [nn.grid\_sample](framework/operators/neural-network/nn.grid\_sample.md)
     * [nn.col2im](framework/operators/neural-network/nn.col2im.md)
-    * [nn.conv_transpose](framework/operators/neural-network/nn.conv\_transpose.md)
+    * [nn.conv\_transpose](framework/operators/neural-network/nn.conv\_transpose.md)
     * [nn.conv](framework/operators/neural-network/nn.conv.md)
+    * [nn.conv_integer](framework/operators/neural-network/nn.conv\_integer.md)
     * [nn.depth_to_space](framework/operators/neural-network/nn.depth_to_space.md)
     * [nn.space_to_depth](framework/operators/neural-network/nn.space_to_depth.md)
+    * [nn.max\_pool](framework/operators/neural-network/nn.max\_pool.md)
+    * [nn.deform\_conv](framework/operators/neural-network/nn.deform\_conv_.md)
   * [Machine Learning](framework/operators/machine-learning/README.md)
     * [Tree Ensemble Classifier](framework/operators/machine-learning/tree-ensemble-classifier/README.md)
       * [tree\_ensemble\_classifier.predict](framework/operators/machine-learning/tree-ensemble-classifier/tree\_ensemble\_classifier.predict.md)

docs/framework/compatibility.md

@@ -47,6 +47,9 @@ You can see below the list of current supported ONNX Operators:
 |            [Col2im](operators/neural-network/nn.col2im\_sigmoid.md)           | :white\_check\_mark: |
 |       [ConvTranspose](operators/neural-network/nn.conv\_transpose_.md)        | :white\_check\_mark: |
 |                  [Conv](operators/neural-network/nn.conv.md)                  | :white\_check\_mark: |
+|         [ConvInteger](operators/neural-network/nn.conv\_integer_.md)          | :white\_check\_mark: |
+|              [MaxPool](operators/neural-network/nn.max\_pool.md)              | :white\_check\_mark: |
+|        [DeformConv](operators/neural-network/nn.deform\_conv_.md)             | :white\_check\_mark: |
 |                    [Sinh](operators/tensor/tensor.sinh.md)                    | :white\_check\_mark: |
 |                   [Asinh](operators/tensor/tensor.asinh.md)                   | :white\_check\_mark: |
 |                   [Atanh](operators/tensor/tensor.atanh.md)                   | :white\_check\_mark: |
@@ -66,6 +69,7 @@ You can see below the list of current supported ONNX Operators:
 |             [QlinearAdd](operators/tensor/tensor.qlinear\_add.md)             | :white\_check\_mark: |
 |             [QlinearMul](operators/tensor/tensor.qlinear\_mul.md)             | :white\_check\_mark: |
 |       [QLinearLeakyRelu](operators/tensor/tensor.qlinear\_leakyrelu.md)       | :white\_check\_mark: |
+|            [QLinearConv](operators/tensor/tensor.qlinear\_conv_.md)           | :white\_check\_mark: |
 |                 [Nonzero](operators/tensor/tensor.nonzero.md)                 | :white\_check\_mark: |
 |                 [Squeeze](operators/tensor/tensor.squeeze.md)                 | :white\_check\_mark: |
 |               [Unsqueeze](operators/tensor/tensor.unsqueeze.md)               | :white\_check\_mark: |

docs/framework/operators/machine-learning/tree-ensemble/README.md

@@ -0,0 +1,22 @@
+# Tree Ensemble 
+
+`TreeEnsembleTrait` provides a trait definition for tree ensemble problem.
+
+```rust
+use orion::operators::ml::TreeEnsembleTrait;
+```
+
+### Data types
+
+Orion supports currently only fixed point data types for `TreeEnsembleTrait`.
+
+| Data type            | dtype                                                         |
+| -------------------- | ------------------------------------------------------------- |
+| Fixed point (signed) | `TreeEnsembleTrait<FP8x23 \| FP16x16 \| FP64x64 \| FP32x32>` |
+
+
+***
+
+| function | description |
+| --- | --- |
+| [`tree_ensemble.predict`](tree_ensemble.predict.md) | Returns the regressed values for each input in a batch. |

docs/framework/operators/machine-learning/tree-ensemble/tree_ensemble.predict.md

@@ -0,0 +1,139 @@
+# TreeEnsemble::predict
+
+```rust 
+   fn predict(X: @Tensor<T>,
+                  nodes_splits: Tensor<T>,
+                  nodes_featureids: Span<usize>,
+                  nodes_modes: Span<MODE>,
+                  nodes_truenodeids: Span<usize>,
+                  nodes_falsenodeids: Span<usize>,
+                  nodes_trueleafs: Span<usize>,
+                  nodes_falseleafs: Span<usize>,
+                  leaf_targetids: Span<usize>,
+                  leaf_weights: Tensor<T>,
+                  tree_roots: Span<usize>,
+                  post_transform: POST_TRANSFORM,
+                  aggregate_function: AGGREGATE_FUNCTION,
+                  nodes_hitrates: Option<Tensor<T>>,
+                  nodes_missing_value_tracks_true: Option<Span<usize>>,
+                  membership_values: Option<Tensor<T>>,
+                  n_targets: usize
+              ) -> MutMatrix::<T>;
+```
+
+Tree Ensemble operator. Returns the regressed values for each input in a batch. Inputs have dimensions [N, F] where N is the input batch size and F is the number of input features. Outputs have dimensions [N, num_targets] where N is the batch size and num_targets is the number of targets, which is a configurable attribute.
+
+## Args
+
+* `X`:  Input 2D tensor.
+* `nodes_splits`: Thresholds to do the splitting on for each node with mode that is not 'BRANCH_MEMBER'.
+* `nodes_featureids`: Feature id for each node.
+* `nodes_modes`: The comparison operation performed by the node. This is encoded as an enumeration of 'NODE_MODE::LEQ', 'NODE_MODE::LT', 'NODE_MODE::GTE', 'NODE_MODE::GT', 'NODE_MODE::EQ', 'NODE_MODE::NEQ', and 'NODE_MODE::MEMBER'
+* `nodes_truenodeids`: If `nodes_trueleafs` is 0 (false) at an entry, this represents the position of the true branch node. 
+* `nodes_falsenodeids`: If `nodes_falseleafs` is 0 (false) at an entry, this represents the position of the false branch node.
+* `nodes_trueleafs`: 1 if true branch is leaf for each node and 0 an interior node.
+* `nodes_falseleafs`: 1 if true branch is leaf for each node and 0 an interior node.
+* `leaf_targetids`: The index of the target that this leaf contributes to (this must be in range `[0, n_targets)`).
+* `leaf_weights`: The weight for each leaf.
+* `tree_roots`: Index into `nodes_*` for the root of each tree. The tree structure is derived from the branching of each node.
+* `post_transform`: Indicates the transform to apply to the score.One of 'POST_TRANSFORM::NONE', 'POST_TRANSFORM::SOFTMAX', 'POST_TRANSFORM::LOGISTIC', 'POST_TRANSFORM::SOFTMAX_ZERO'  or 'POST_TRANSFORM::PROBIT' ,
+* `aggregate_function`: Defines how to aggregate leaf values within a target. One of 'AGGREGATE_FUNCTION::AVERAGE', 'AGGREGATE_FUNCTION::SUM', 'AGGREGATE_FUNCTION::MIN', 'AGGREGATE_FUNCTION::MAX` defaults to 'AGGREGATE_FUNCTION::SUM' 
+* `nodes_hitrates`: Popularity of each node, used for performance and may be omitted.
+* `nodes_missing_value_tracks_true`: For each node, define whether to follow the true branch (if attribute value is 1) or false branch (if attribute value is 0) in the presence of a NaN input feature. This attribute may be left undefined and the default value is false (0) for all nodes.
+* `membership_values`: Members to test membership of for each set membership node. List all of the members to test again in the order that the 'BRANCH_MEMBER' mode appears in `node_modes`, delimited by `NaN`s. Will have the same number of sets of values as nodes with mode 'BRANCH_MEMBER'. This may be omitted if the node doesn't contain any 'BRANCH_MEMBER' nodes.
+* `n_targets`: The total number of targets.
+
+
+## Returns
+
+* Output of shape [Batch Size, Number of targets]
+
+## Type Constraints
+
+`TreeEnsembleClassifier` and `X` must be fixed points
+
+## Examples
+
+```rust
+use orion::numbers::FP16x16;
+use orion::operators::tensor::{Tensor, TensorTrait, FP16x16Tensor, U32Tensor};
+use orion::operators::ml::{TreeEnsembleTrait,POST_TRANSFORM, AGGREGATE_FUNCTION, NODE_MODE};
+use orion::operators::matrix::{MutMatrix, MutMatrixImpl};
+use orion::numbers::NumberTrait;
+
+fn example_tree_ensemble_one_tree() ->  MutMatrix::<FP16x16> {
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(3);
+    shape.append(2);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 78643, sign: false });
+    data.append(FP16x16 { mag: 222822, sign: false });
+    data.append(FP16x16 { mag: 7864, sign: true });
+    data.append(FP16x16 { mag: 108789, sign: false });
+    data.append(FP16x16 { mag: 271319, sign: false });
+    data.append(FP16x16 { mag: 115998, sign: false });
+    let mut X = TensorTrait::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(4);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 342753, sign: false });
+    data.append(FP16x16 { mag: 794296, sign: false });
+    data.append(FP16x16 { mag: 801505, sign: true });
+    data.append(FP16x16 { mag: 472514, sign: false });
+    let leaf_weights = TensorTrait::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(3);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 205783, sign: false });
+    data.append(FP16x16 { mag: 78643, sign: false });
+    data.append(FP16x16 { mag: 275251, sign: false });
+    let nodes_splits = TensorTrait::new(shape.span(), data.span());
+
+    let membership_values = Option::None;
+
+    let n_targets = 2;
+    let aggregate_function = AGGREGATE_FUNCTION::SUM;
+    let nodes_missing_value_tracks_true = Option::None;
+    let nodes_hitrates = Option::None;
+    let post_transform = POST_TRANSFORM::NONE;
+
+    let tree_roots: Span<usize> = array![0].span();
+    let nodes_modes: Span<MODE> = array![MODE::LEQ, MODE::LEQ, MODE::LEQ].span();
+
+    let nodes_featureids: Span<usize> = array![0, 0, 0].span();
+    let nodes_truenodeids: Span<usize> = array![1, 0, 1].span();
+    let nodes_trueleafs: Span<usize> = array![0, 1, 1].span();
+    let nodes_falsenodeids: Span<usize> = array![2, 2, 3].span();
+    let nodes_falseleafs: Span<usize> = array![0, 1, 1].span();
+    let leaf_targetids: Span<usize> = array![0, 1, 0, 1].span();
+
+    return TreeEnsembleTrait::predict(
+        @X,
+        nodes_splits,
+        nodes_featureids,
+        nodes_modes,
+        nodes_truenodeids,
+        nodes_falsenodeids,
+        nodes_trueleafs,
+        nodes_falseleafs,
+        leaf_targetids,
+        leaf_weights,
+        tree_roots,
+        post_transform,
+        aggregate_function,
+        nodes_hitrates,
+        nodes_missing_value_tracks_true,
+        membership_values,
+        n_targets
+    );
+}
+
+>>> [[ 5.23  0.  ]
+     [ 5.23  0.  ]
+     [ 0.   12.12]]    
+```

docs/framework/operators/neural-network/README.md

@@ -40,4 +40,5 @@ Orion supports currently these `NN` types.
 | [`nn.conv_transpose`](nn.conv\_transpose.md) | Performs the convolution transpose of the input data tensor and weight tensor. |
 | [`nn.conv`](nn.conv.md) | Performs the convolution of the input data tensor and weight tensor. |
 | [`nn.global_average_pool`](nn.global\_average\_pool.md) | GlobalAveragePool consumes an input tensor X and applies average pooling across the values in the same channel. |
+| [`nn.conv_integer`](nn.conv\_integer.md) | Performs integer convolution  |
 

docs/framework/operators/neural-network/nn.conv_integer.md

@@ -0,0 +1,122 @@
+# tensor.conv_integer
+
+```rust
+
+fn conv_integer(
+    X: @Tensor<T>,
+    W: @Tensor<T>,
+    X_zero_point: Option<@Tensor<T>>,
+    W_zero_point: Option<@Tensor<T>>,
+    auto_pad: Option<AUTO_PAD>,
+    dilations: Option<Span<usize>>,
+    group: Option<usize>,
+    kernel_shape: Option<Span<usize>>,
+    pads: Option<Span<usize>>,
+    strides: Option<Span<usize>>,
+) -> Tensor<T>;
+```
+
+Performs integer convolution 
+
+The integer convolution operator consumes an input tensor, its zero-point, a filter, and its zero-point, and computes the output.
+
+## Args
+
+* `X`(`@Tensor<i8>`) - Input data tensor, has size (N x C x H x W), where N is the batch size, C is the number of channels, and H and W are the height and width. Note that this is for the 2D image. Otherwise the size is (N x C x D1 x D2 ... x Dn)..
+* `W`(`@Tensor<i8>`) - Weight tensor that will be used in the convolutions; has size (M x C/group x kH x kW), where C is the number of channels, and kH and kW are the height and width of the kernel, and M is the number of feature maps. For more than 2 dimensions, the kernel shape will be (M x C/group x k1 x k2 x ... x kn), where (k1 x k2 x ... kn) is the dimension of the kernel. 
+* `X_zero_point`(`@Tensor<T>`) - Zero point for input `X`
+* `W_zero_point`(`@Tensor<T>`) - Zero point for input `W`. 
+* `auto_pad`(`Option<AUTO_PAD>`) - Default is NOTSET, auto_pad must be either NOTSET, SAME_UPPER, SAME_LOWER or VALID. NOTSET means explicit padding is used. SAME_UPPER or SAME_LOWER mean pad the input so that `output_shape[i] = ceil(input_shape[i] / strides[i])` for each axis `i`.
+* `dilations`(`Option<Span<usize>>`) - Dilation value along each spatial axis of the filter. If not present, the dilation defaults to 1 along each spatial axis.
+* `group`(`Option<usize>`) - Default is 1, number of groups input channels and output channels are divided into.
+* `kernel_shape`(`Option<Span<usize>>`) - The shape of the convolution kernel. If not present, should be inferred from input W.
+* `pads`(`Option<Span<usize>>`) - Padding for the beginning and ending along each spatial axis, it can take any value greater than or equal to 0. The value represent the number of pixels added to the beginning and end part of the corresponding axis. `pads` format should be as follow [x1_begin, x2_begin...x1_end, x2_end,...], where xi_begin the number of pixels added at the beginning of axis `i` and xi_end, the number of pixels added at the end of axis `i`. This attribute cannot be used simultaneously with auto_pad attribute. If not present, the padding defaults to 0 along start and end of each spatial axis.
+* `strides`(`Option<Span<usize>>`) - Stride along each spatial axis. If not present, the stride defaults to 1 along each spatial axis. 
+
+## Returns
+
+A new `Tensor<usize>`, containing the result of the convolution of the inputs.
+
+
+## Example
+
+```rust
+use core::array::{ArrayTrait, SpanTrait};
+
+use orion::operators::tensor::{TensorTrait, Tensor, I8Tensor, U32Tensor};
+use orion::operators::nn::NNTrait;
+use orion::operators::nn::U32NN;
+
+fn example_conv_integer() -> Tensor<usize> {
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(1);
+    shape.append(1);
+    shape.append(3);
+    shape.append(3);
+
+    let mut data = ArrayTrait::new();
+    data.append(2);
+    data.append(3);
+    data.append(4);
+    data.append(5);
+    data.append(6);
+    data.append(7);
+    data.append(8);
+    data.append(9);
+    data.append(10);
+    let mut X = TensorTrait::<i8>::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(1);
+    shape.append(1);
+    shape.append(2);
+    shape.append(2);
+
+    let mut data = ArrayTrait::new();
+    data.append(1);
+    data.append(1);
+    data.append(1);
+    data.append(1);
+    let mut W = TensorTrait::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(1);
+    shape.append(1);
+    shape.append(1);
+    shape.append(1);
+
+    let mut data = ArrayTrait::new();
+    data.append(1);
+    let X_zero_point = TensorTrait::<i8>::new(shape.span(), data.span());
+
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(1);
+    shape.append(1);
+    shape.append(2);
+    shape.append(2);
+
+    let mut data = ArrayTrait::new();
+    data.append(12);
+    data.append(16);
+    data.append(24);
+    data.append(28);
+    let expected_output = TensorTrait::new(shape.span(), data.span());
+
+    'data ok'.print();
+
+    return NNTrait::conv_integer(
+        @X,
+        @W,
+        Option::Some(@X_zero_point),
+        Option::None,
+        Option::None,
+        Option::None,
+        Option::None,
+        Option::None,
+        Option::None,
+        Option::None,
+    );
+}
+>>> [[12, 16], [24, 28]]
+```