concrete.ml.sklearn.qnn.md
Last updated
Last updated
concrete.ml.sklearn.qnn
Scikit-learn interface for concrete quantized neural networks.
MAX_BITWIDTH_BACKWARD_COMPATIBLE
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
__init__
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
enable_pruning
Enable pruning in the network. Pruning must be made permanent to recover pruned weights.
Raises:
ValueError
: if the quantization parameters are invalid
forward
Forward pass.
Args:
x
(torch.Tensor): network input
Returns:
x
(torch.Tensor): network prediction
make_pruning_permanent
Make the learned pruning permanent in the network.
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
on_train_end
Call back when training is finished, can be useful to remove training hooks.
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
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
infer
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
on_train_end
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
FixedTypeSkorchNeuralNet
A mixin with a helpful modification to a skorch estimator that fixes the module type.
get_params
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.
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.
__init__
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
fit
get_params
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.
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
infer
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
on_train_end
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
predict
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
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.
__init__
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
fit
get_params
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.
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
infer
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
on_train_end
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