concrete.ml.sklearn.qnn.md

module concrete.ml.sklearn.qnn

Scikit-learn interface for concrete quantized neural networks.

Global Variables

• MAX_BITWIDTH_BACKWARD_COMPATIBLE

---

class SparseQuantNeuralNetImpl

Sparse Quantized Neural Network classifier.

This class implements an MLP that is compatible with FHE constraints. The weights and activations are quantized to low bitwidth and pruning is used to ensure accumulators do not surpass an user-provided accumulator bit-width. The number of classes and number of layers are specified by the user, as well as the breadth of the network

method __init__

__init__(
    input_dim,
    n_layers,
    n_outputs,
    n_hidden_neurons_multiplier=4,
    n_w_bits=3,
    n_a_bits=3,
    n_accum_bits=8,
    activation_function=<class 'torch.nn.modules.activation.ReLU'>,
    quant_narrow=False,
    quant_signed=True
)

Sparse Quantized Neural Network constructor.

Args:

• input_dim: Number of dimensions of the input data

• n_layers: Number of linear layers for this network

• n_outputs: Number of output classes or regression targets

• n_w_bits: Number of weight bits

• n_a_bits: Number of activation and input bits

• n_accum_bits: Maximal allowed bitwidth of intermediate accumulators

• n_hidden_neurons_multiplier: A factor that is multiplied by the maximal number of active (non-zero weight) neurons for every layer. The maximal number of neurons in the worst case scenario is: 2^n_max-1 max_active_neurons(n_max, n_w, n_a) = floor(---------------------) (2^n_w-1)*(2^n_a-1) ) The worst case scenario for the bitwidth of the accumulator is when all weights and activations are maximum simultaneously. We set, for each layer, the total number of neurons to be: n_hidden_neurons_multiplier * max_active_neurons(n_accum_bits, n_w_bits, n_a_bits) Through experiments, for typical distributions of weights and activations, the default value for n_hidden_neurons_multiplier, 4, is safe to avoid overflow.

• activation_function: a torch class that is used to construct activation functions in the network (e.g. torch.ReLU, torch.SELU, torch.Sigmoid, etc)

• quant_narrow : whether this network should use narrow range quantized integer values

• quant_signed : whether to use signed quantized integer values

Raises:

• ValueError: if the parameters have invalid values or the computed accumulator bitwidth is zero

---

method enable_pruning

enable_pruning()

Enable pruning in the network. Pruning must be made permanent to recover pruned weights.

Raises:

• ValueError: if the quantization parameters are invalid

---

method forward

forward(x)

Forward pass.

Args:

• x (torch.Tensor): network input

Returns:

• x (torch.Tensor): network prediction

---

method make_pruning_permanent

make_pruning_permanent()

Make the learned pruning permanent in the network.

---

method max_active_neurons

max_active_neurons()

Compute the maximum number of active (non-zero weight) neurons.

The computation is done using the quantization parameters passed to the constructor. Warning: With the current quantization algorithm (asymmetric) the value returned by this function is not guaranteed to ensure FHE compatibility. For some weight distributions, weights that are 0 (which are pruned weights) will not be quantized to 0. Therefore the total number of active quantized neurons will not be equal to max_active_neurons.

Returns:

• n (int): maximum number of active neurons

---

method on_train_end

on_train_end()

Call back when training is finished, can be useful to remove training hooks.

---

class QuantizedSkorchEstimatorMixin

Mixin class that adds quantization features to Skorch NN estimators.

---

property base_estimator_type

Get the sklearn estimator that should be trained by the child class.

---

property base_module_to_compile

Get the module that should be compiled to FHE. In our case this is a torch nn.Module.

Returns:

• module (nn.Module): the instantiated torch module

---

property fhe_circuit

Get the FHE circuit.

Returns:

• Circuit: the FHE circuit

---

property input_quantizers

Get the input quantizers.

Returns:

• List[Quantizer]: the input quantizers

---

property n_bits_quant

Return the number of quantization bits.

This is stored by the torch.nn.module instance and thus cannot be retrieved until this instance is created.

Returns:

• n_bits (int): the number of bits to quantize the network

Raises:

• ValueError: with skorch estimators, the module_ is not instantiated until .fit() is called. Thus this estimator needs to be .fit() before we get the quantization number of bits. If it is not trained we raise an exception

---

property onnx_model

Get the ONNX model.

.. # noqa: DAR201

Returns:

• _onnx_model_ (onnx.ModelProto): the ONNX model

---

property output_quantizers

Get the input quantizers.

Returns:

• List[QuantizedArray]: the input quantizers

---

property quantize_input

Get the input quantization function.

Returns:

• Callable : function that quantizes the input

---

method get_params_for_benchmark

get_params_for_benchmark()

Get parameters for benchmark when cloning a skorch wrapped NN.

We must remove all parameters related to the module. Skorch takes either a class or a class instance for the module parameter. We want to pass our trained model, a class instance. But for this to work, we need to remove all module related constructor params. If not, skorch will instantiate a new class instance of the same type as the passed module see skorch net.py NeuralNet::initialize_instance

Returns:

• params (dict): parameters to create an equivalent fp32 sklearn estimator for benchmark

---

method infer

infer(x, **fit_params)

Perform a single inference step on a batch of data.

This method is specific to Skorch estimators.

Args:

• x (torch.Tensor): A batch of the input data, produced by a Dataset

• **fit_params (dict) : Additional parameters passed to the forward method of the module and to the self.train_split call.

Returns: A torch tensor with the inference results for each item in the input

---

method on_train_end

on_train_end(net, X=None, y=None, **kwargs)

Call back when training is finished by the skorch wrapper.

Check if the underlying neural net has a callback for this event and, if so, call it.

Args:

• net: estimator for which training has ended (equal to self)

• X: data

• y: targets

• kwargs: other arguments

---

class FixedTypeSkorchNeuralNet

A mixin with a helpful modification to a skorch estimator that fixes the module type.

---

method get_params

get_params(deep=True, **kwargs)

Get parameters for this estimator.

Args:

• deep (bool): If True, will return the parameters for this estimator and contained subobjects that are estimators.

• **kwargs: any additional parameters to pass to the sklearn BaseEstimator class

Returns:

• params : dict, Parameter names mapped to their values.

---

class NeuralNetClassifier

Scikit-learn interface for quantized FHE compatible neural networks.

This class wraps a quantized NN implemented using our Torch tools as a scikit-learn Estimator. It uses the skorch package to handle training and scikit-learn compatibility, and adds quantization and compilation functionality. The neural network implemented by this class is a multi layer fully connected network trained with Quantization Aware Training (QAT).

The datatypes that are allowed for prediction by this wrapper are more restricted than standard scikit-learn estimators as this class needs to predict in FHE and network inference executor is the NumpyModule.

method __init__

__init__(
    *args,
    criterion=<class 'torch.nn.modules.loss.CrossEntropyLoss'>,
    classes=None,
    optimizer=<class 'torch.optim.adam.Adam'>,
    **kwargs
)

---

property base_estimator_type

---

property base_module_to_compile

Get the module that should be compiled to FHE. In our case this is a torch nn.Module.

Returns:

• module (nn.Module): the instantiated torch module

---

property classes_

---

property fhe_circuit

Get the FHE circuit.

Returns:

• Circuit: the FHE circuit

---

property history

---

property input_quantizers

Get the input quantizers.

Returns:

• List[Quantizer]: the input quantizers

---

property n_bits_quant

Return the number of quantization bits.

This is stored by the torch.nn.module instance and thus cannot be retrieved until this instance is created.

Returns:

• n_bits (int): the number of bits to quantize the network

Raises:

• ValueError: with skorch estimators, the module_ is not instantiated until .fit() is called. Thus this estimator needs to be .fit() before we get the quantization number of bits. If it is not trained we raise an exception

---

property onnx_model

Get the ONNX model.

.. # noqa: DAR201

Returns:

• _onnx_model_ (onnx.ModelProto): the ONNX model

---

property output_quantizers

Get the input quantizers.

Returns:

• List[QuantizedArray]: the input quantizers

---

property quantize_input

Get the input quantization function.

Returns:

• Callable : function that quantizes the input

---

method fit

fit(X, y, **fit_params)

---

method get_params

get_params(deep=True, **kwargs)

Get parameters for this estimator.

Args:

• deep (bool): If True, will return the parameters for this estimator and contained subobjects that are estimators.

• **kwargs: any additional parameters to pass to the sklearn BaseEstimator class

Returns:

• params : dict, Parameter names mapped to their values.

---

method get_params_for_benchmark

get_params_for_benchmark()

Get parameters for benchmark when cloning a skorch wrapped NN.

We must remove all parameters related to the module. Skorch takes either a class or a class instance for the module parameter. We want to pass our trained model, a class instance. But for this to work, we need to remove all module related constructor params. If not, skorch will instantiate a new class instance of the same type as the passed module see skorch net.py NeuralNet::initialize_instance

Returns:

• params (dict): parameters to create an equivalent fp32 sklearn estimator for benchmark

---

method infer

infer(x, **fit_params)

Perform a single inference step on a batch of data.

This method is specific to Skorch estimators.

Args:

• x (torch.Tensor): A batch of the input data, produced by a Dataset

• **fit_params (dict) : Additional parameters passed to the forward method of the module and to the self.train_split call.

Returns: A torch tensor with the inference results for each item in the input

---

method on_train_end

on_train_end(net, X=None, y=None, **kwargs)

Call back when training is finished by the skorch wrapper.

Check if the underlying neural net has a callback for this event and, if so, call it.

Args:

• net: estimator for which training has ended (equal to self)

• X: data

• y: targets

• kwargs: other arguments

---

method predict

predict(X, execute_in_fhe=False)

Predict on user provided data.

Predicts using the quantized clear or FHE classifier

Args:

• X : input data, a numpy array of raw values (non quantized)

• execute_in_fhe : whether to execute the inference in FHE or in the clear

Returns:

• y_pred : numpy ndarray with predictions

---

class NeuralNetRegressor

Scikit-learn interface for quantized FHE compatible neural networks.

This class wraps a quantized NN implemented using our Torch tools as a scikit-learn Estimator. It uses the skorch package to handle training and scikit-learn compatibility, and adds quantization and compilation functionality. The neural network implemented by this class is a multi layer fully connected network trained with Quantization Aware Training (QAT).

The datatypes that are allowed for prediction by this wrapper are more restricted than standard scikit-learn estimators as this class needs to predict in FHE and network inference executor is the NumpyModule.

method __init__

__init__(*args, optimizer=<class 'torch.optim.adam.Adam'>, **kwargs)

---

property base_estimator_type

---

property base_module_to_compile

Get the module that should be compiled to FHE. In our case this is a torch nn.Module.

Returns:

• module (nn.Module): the instantiated torch module

---

property fhe_circuit

Get the FHE circuit.

Returns:

• Circuit: the FHE circuit

---

property history

---

property input_quantizers

Get the input quantizers.

Returns:

• List[Quantizer]: the input quantizers

---

property n_bits_quant

Return the number of quantization bits.

This is stored by the torch.nn.module instance and thus cannot be retrieved until this instance is created.

Returns:

• n_bits (int): the number of bits to quantize the network

Raises:

• ValueError: with skorch estimators, the module_ is not instantiated until .fit() is called. Thus this estimator needs to be .fit() before we get the quantization number of bits. If it is not trained we raise an exception

---

property onnx_model

Get the ONNX model.

.. # noqa: DAR201

Returns:

• _onnx_model_ (onnx.ModelProto): the ONNX model

---

property output_quantizers

Get the input quantizers.

Returns:

• List[QuantizedArray]: the input quantizers

---

property quantize_input

Get the input quantization function.

Returns:

• Callable : function that quantizes the input

---

method fit

fit(X, y, **fit_params)

---

method get_params

get_params(deep=True, **kwargs)

Get parameters for this estimator.

Args:

• deep (bool): If True, will return the parameters for this estimator and contained subobjects that are estimators.

• **kwargs: any additional parameters to pass to the sklearn BaseEstimator class

Returns:

• params : dict, Parameter names mapped to their values.

---

method get_params_for_benchmark

get_params_for_benchmark()

Get parameters for benchmark when cloning a skorch wrapped NN.

We must remove all parameters related to the module. Skorch takes either a class or a class instance for the module parameter. We want to pass our trained model, a class instance. But for this to work, we need to remove all module related constructor params. If not, skorch will instantiate a new class instance of the same type as the passed module see skorch net.py NeuralNet::initialize_instance

Returns:

• params (dict): parameters to create an equivalent fp32 sklearn estimator for benchmark

---

method infer

infer(x, **fit_params)

Perform a single inference step on a batch of data.

This method is specific to Skorch estimators.

Args:

• x (torch.Tensor): A batch of the input data, produced by a Dataset

• **fit_params (dict) : Additional parameters passed to the forward method of the module and to the self.train_split call.

Returns: A torch tensor with the inference results for each item in the input

---

method on_train_end

on_train_end(net, X=None, y=None, **kwargs)

Call back when training is finished by the skorch wrapper.

Check if the underlying neural net has a callback for this event and, if so, call it.

Args:

• net: estimator for which training has ended (equal to self)

• X: data

• y: targets

• kwargs: other arguments