nnbma.networks package

Submodules

nnbma.networks.neural_network module

class nnbma.networks.neural_network.NeuralNetwork(input_features: int, output_features: int, inputs_names: List[str] | None = None, outputs_names: List[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None)

Bases: Module, ABC

Neural network abstract class.

Parameters:

• input_features (int) – Dimension of input vector.

• output_features (int) – Dimension of output vector.

• inputs_names (Optional[List[str]], optional) – List of inputs names. None if the names have not been specified.

• outputs_names (Optional[List[str]], optional) – List of outputs names. None if the names have not been specified.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

Raises:

• ValueError – The length of inputs_names should equal input_features.

• ValueError – The length of outputs_names should equal output_features.

• ValueError – The list inputs_names must not have duplicates.

• ValueError – The list outputs_names must not have duplicates.

copy() → NeuralNetwork

Returns a copy of the network. The copy is detached from the original network so any modification of one doesn’t modify the other.

Returns:

copy of self.

Return type:

NeuralNetwork

count_bytes(learnable_only: bool = True, display: bool = False) → Tuple[int, Literal['B', 'kB', 'MB', 'GB', 'TB']] | str

Returns the number of parameters of the module. If learnable_only=True, this function returns the number of parameters for which requires_grad=True. If learnable_only=False, it returns the number of parameters, independently to their requires_grad property.

Parameters:

• (bool (learnable_only) – Indicates the the type of parameter to count. Defaults to True.

• optional) – Indicates the the type of parameter to count. Defaults to True.

Returns:

• int – Number of parameters.

• str – Unit (‘B’, ‘kB’, ‘MB’, ‘GB’, ‘TB’)

count_parameters(learnable_only: bool = True) → int

Returns the number of parameters of the module. If learnable_only=True, this function returns the number of parameters for which requires_grad=True. If learnable_only=False, it returns the number of parameters, independently to their requires_grad property.

Parameters:

learnable_only (bool, optional) – Indicates the the type of parameter to count. Defaults to True.

Returns:

Number of parameters.

Return type:

int

evaluate(x: ndarray, transform_inputs: bool = False, transform_outputs: bool = False) → ndarray

Evaluate the network on a batch of NumPy inputs.

Parameters:

• x (ndarray) – batch of inputs of shape (?, input_features).

• transform_inputs (bool, optional) – whether the input x are to be pre-processed.

• transform_outputs (bool, optional) – whether the predictions y are to be post-processed.

Returns:

batch of outputs of shape (?, output_features).

Return type:

ndarray

Raises:

• ValueError – The transform_inputs argument cannot be True when the inputs_transformer attribute is None.

• ValueError – The transform_outputs argument cannot be True when the outputs_transformer attribute is None.

abstract forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

classmethod load(module_name: str, module_path: str | None = None) → NeuralNetwork

Load a network from a local save made using the save() method.

Parameters:

• module_name (str) – Name of the directory in which the model has been saved.

• module_path (str | None) – Path to the previous directory.

Returns:

loaded neural network instance.

Return type:

NeuralNetwork

Raises:

FileNotFoundError – The specified directory does not exist, or is not a directory.

restrict_to_output_subset(output_subset: List[str] | List[int] | None = None) → None

Restricts network outputs to those contained in output_subset.

Parameters:

output_subset (List[str] | List[int] | None, optional) – Network outputs required. If None, no restriction is applied. Default: None.

Raises:

• PermissionError – The outputs cannot be restricted when Module is in train mode.

• TypeError – The output_subset argument must be a list or None.

• TypeError – The output_subset argument must be a list of int or a list of str.

save(module_name: str, module_path: str | None = None, overwrite: bool = True) → None

Saves the network for future use.

Parameters:

• module_name (str) – Name of the directory in which the model will be saved.

• module_path (str | None) – Path to the previous directory.

• overwrite (bool) – If True, the save can overwrite a previous backup of the same name. If False, an error will be raised if such a backup exists.

set_device(device: str) → None

Set the device to use.

Parameters:

device (str) – Device to use (“cpu” or “cuda”).

time(n: int, repeat: int) → Tuple[float, float, float]

Estimates the evaluation time of the model for a batch of n inputs. Returns the average, min and max durations (in seconds) over repeat iterations.

Parameters:

• n (int) – batch size.

• repeat (int) – number of evaluations.

Returns:

average, min and max durations (in seconds)

Return type:

Tuple[float, float, float]

Raises:

• TypeError – The n argument must be an integer.

• TypeError – The repeat argument must be an integer.

train(mode: bool = True) → NeuralNetwork

Set the current mode of the network (train or eval).

Parameters:

mode (bool, optional) – If True, activate the training mode. If False, activate the evaluation mode. Default: True.

Returns:

Instance of network.

Return type:

NeuralNetwork

training: bool

nnbma.networks.fully_connected module

class nnbma.networks.fully_connected.FullyConnected(layers_sizes: Iterable[int], activation: Module, batch_norm: bool = False, inputs_names: Sequence[str] | None = None, outputs_names: Sequence[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None, last_restrictable: bool = True)

Bases: NeuralNetwork

Standard fully connected neural network.

Parameters:

• layers_sizes (Iterable[int]) – list of number of neurons per layer. The first value corresponds to the dimension of the input layer, and the last value to the dimension of the output layer.

• activation (nn.Module) – activation function.

• batch_norm (bool, optional) – whether to use batch normalization during training, by default False.

• inputs_names (Optional[Sequence[str]], optional) – List of inputs names. None if the names have not been specified. By default None.

• outputs_names (Optional[Sequence[str]], optional) – List of outputs names. None if the names have not been specified. By default None.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing, by default None.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing, by default None.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

• last_restrictable (bool, optional) – whether the last layer is to be a RestrictableLinear layer, by default True.

forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

restrict_to_output_subset(output_subset: Sequence[str] | Sequence[int] | None = None) → None

Restricts network outputs to those contained in output_subset.

Parameters:

output_subset (List[str] | List[int] | None, optional) – Network outputs required. If None, no restriction is applied. Default: None.

Raises:

• PermissionError – The outputs cannot be restricted when Module is in train mode.

• TypeError – The output_subset argument must be a list or None.

• TypeError – The output_subset argument must be a list of int or a list of str.

training: bool

nnbma.networks.densely_connected module

class nnbma.networks.densely_connected.DenselyConnected(input_features: int, output_features: int, n_layers: int, growing_factor: float, activation: Module, batch_norm: bool = False, inputs_names: Sequence[str] | None = None, outputs_names: Sequence[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None, last_restrictable: bool = True)

Bases: NeuralNetwork

Densely connected neural network. In such a network, the input of an hidden layer is the concatenation of the input and output of the previous layer. This skip operation permits to reduce the number of parameters to learn, to reuse intermediate computation results and to avoid gradient vanishing effects.

Parameters:

• input_features (int) – dimension of input vector.

• output_features (int) – dimension of output vector.

• n_layers (int) – number of layers in the network.

• growing_factor (float) – growing factor considered in the full network. The growing factor corresponds to the ratio of the output and input dimensions for one layer. For instance, growing_factor=1.0 implies that the input of a hidden layer is twice that of the previous layer.

• activation (nn.Module) – activation function.

• batch_norm (bool, optional) – whether to use batch normalization during training, by default False.

• inputs_names (Optional[Sequence[str]], optional) – List of inputs names. None if the names have not been specified. By default None.

• outputs_names (Optional[Sequence[str]], optional) – List of outputs names. None if the names have not been specified. By default None.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing, by default None.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing, by default None.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

• last_restrictable (bool, optional) – whether the last layer is to be a RestrictableLinear layer, by default True.

forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

restrict_to_output_subset(output_subset: Sequence[str] | Sequence[int] | None) → None

Restricts network outputs to those contained in output_subset.

Parameters:

output_subset (List[str] | List[int] | None, optional) – Network outputs required. If None, no restriction is applied. Default: None.

Raises:

• PermissionError – The outputs cannot be restricted when Module is in train mode.

• TypeError – The output_subset argument must be a list or None.

• TypeError – The output_subset argument must be a list of int or a list of str.

training: bool

nnbma.networks.polynomial_network module

class nnbma.networks.polynomial_network.PolynomialNetwork(input_features: int, order: int, subnetwork: NeuralNetwork, inputs_names: Sequence[str] | None = None, outputs_names: Sequence[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None)

Bases: NeuralNetwork

Neural network with a polynomial expansion as a first layer.

Parameters:

• input_features (int) – Dimension of input vector.

• order (int) – order of the polynomial expansion.

• subnetwork (NeuralNetwork) – network to be placed after the polynomial expansion.

• inputs_names (Optional[Sequence[str]], optional) – List of inputs names. None if the names have not been specified. By default None.

• outputs_names (Optional[Sequence[str]], optional) – List of outputs names. None if the names have not been specified. By default None.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing, by default None.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing, by default None.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

Raises:

ValueError – The number of polynomial features does not match the input layer of the subnetwork.

forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

restrict_to_output_subset(output_subset: Sequence[str] | Sequence[int] | None) → None

Restricts network outputs to those contained in output_subset.

Parameters:

output_subset (List[str] | List[int] | None, optional) – Network outputs required. If None, no restriction is applied. Default: None.

Raises:

• PermissionError – The outputs cannot be restricted when Module is in train mode.

• TypeError – The output_subset argument must be a list or None.

• TypeError – The output_subset argument must be a list of int or a list of str.

training: bool

update_standardization(x: Tensor | ndarray) → None

Applies the update_standardization method of the PolynomialExpansion first layer, i.e., updates the standardization parameters for the outputs of the polynomial expansion.

Parameters:

x (Union[Tensor, ndarray]) – input tensor.

nnbma.networks.embedding_network module

class nnbma.networks.embedding_network.EmbeddingNetwork(subnetwork: NeuralNetwork, preprocessing: None | AdditionalModule | List[AdditionalModule] = None, postprocessing: None | AdditionalModule | List[AdditionalModule] = None, inputs_names: Sequence[str] | None = None, outputs_names: Sequence[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None)

Bases: NeuralNetwork

Embedding neural network.

Parameters:

• subnetwork (NeuralNetwork) – Base network.

• preprocessing (Union[None, AdditionalModule, List[AdditionalModule]], optional) – PyTorch operation to apply before subnetwork, by default None.

• postprocessing (Union[None, AdditionalModule, List[AdditionalModule]], optional) – PyTorch operation to apply after subnetwork, by default None.

• inputs_names (Optional[Sequence[str]], optional) – List of inputs names. None if the names have not been specified. By default None.

• outputs_names (Optional[Sequence[str]], optional) – List of outputs names. None if the names have not been specified. By default None.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing, by default None.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing, by default None.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

Raises:

• TypeError – All elements of preprocessing must be instances of AdditionalModule.

• TypeError – All elements of postprocessing must be instances of AdditionalModule.

forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

training: bool

nnbma.networks.merging_network module

class nnbma.networks.merging_network.MergingNetwork(subnetworks: Sequence[NeuralNetwork], inputs_names: Sequence[str] | None = None, outputs_names: Sequence[str] | None = None, inputs_transformer: Operator | None = None, outputs_transformer: Operator | None = None, device: str | None = None)

Bases: NeuralNetwork

Utility class to run a set of neural networks in parallel to predict distinct sets of outputs.

Parameters:

• subnetworks (Sequence[NeuralNetwork]) – Set of neural networks to be run in parallel to predict distinct sets of outputs.

• inputs_names (Optional[Sequence[str]], optional) – List of inputs names. None if the names have not been specified. By default None.

• outputs_names (Optional[Sequence[str]], optional) – List of outputs names. None if the names have not been specified. Must be coherent with subnetworks names. If not None, all subnetworks must have a non-None outputs_names attribute. By default None.

• inputs_transformer (Optional[Operator], optional) – Transformation applied to the inputs before processing, by default None.

• outputs_transformer (Optional[Operator], optional) – Transformation applied to the outputs after processing, by default None.

• device (Optional[str], optional) – Device used (“cpu” or “cuda”), by default None (corresponds to “cpu”).

Raises:

• TypeError – The subnetworks argument must be a sequence of NeuralNetwork instances.

• ValueError – All the elements of subnetworks must have the same number of inputs.

• ValueError – Incompatible inputs_names among subnetworks.

• ValueError – No element of subnetworks can be None when outputs_names is not None.

• ValueError – Some elements of subnetworks have the same outputs.

• ValueError – Some elements of outputs_names cannot be found in the outputs of any element of subnetworks.

forward(x: Tensor) → Tensor

Evaluates the neural network on an input x.

Parameters:

x (torch.Tensor) – input tensor of shape (?, input_features)

Returns:

output tensor of shape (?, output_features)

Return type:

torch.Tensor

restrict_to_output_subset(output_subset: Sequence[str] | Sequence[int] | None = None) → None

Restricts network outputs to those contained in output_subset.

Parameters:

output_subset (List[str] | List[int] | None, optional) – Network outputs required. If None, no restriction is applied. Default: None.

Raises:

• PermissionError – The outputs cannot be restricted when Module is in train mode.

• TypeError – The output_subset argument must be a list or None.

• TypeError – The output_subset argument must be a list of int or a list of str.

training: bool

Module contents