model

Submodules

• model.boolean
• model.boolean_and
• model.boolean_not
• model.boolean_or
• model.conflicting
• model.continuous
• model.dynamic
• model.generic
• model.interaction_features
• model.pertinent_negative
• model.shattered_gradients
• model.uncertainty_model

Classes

GenericNN	Class for creating custom neural network architectures using specified weights,
ConflictingFeaturesNN	A crafted neural network model that incorporates cancellation features.
ContinuousFeaturesNN	A crafted neural network model that incorporates continuous features with ReLU.
DynamicNN	Class that enables the instantiation of custom neural network architectures using a list
InteractingFeaturesNN	Implements a neural network model designed to explicitly model interactions between specific pairs of features
PertinentNN	Implements a neural network model specifically designed to handle pertinent negatives in input features.
ShatteredGradientsNN	Implements a neural network model using a linear layer followed by an activation function.
UncertaintyNN	Implements a neural network model designed to capture behaviour were an input node impact all or several output nodes equally.
PropFormulaNN	A neural network model representing a propositional formula that is constructed
BooleanAndNN	Implements a neural network model designed to mimic the 'AND' logical operation on input features.
BooleanNotNN	Implements a neural network model designed to apply the logical NOT operation to input features.
BooleanOrNN	Implements a neural network model designed to mimic the 'OR' logical operation on input features.

Functions

generate_layers(→ List[torch.nn.Module])

Creates linear layers and activation function to be used as inputs for nn.Sequential.

Package Contents

class model.GenericNN(weights: torch.Tensor, biases: torch.Tensor | None = None, act_fns: torch.nn.Module | None = None)

Bases: torch.nn.Sequential

Class for creating custom neural network architectures using specified weights, biases, and activation functions.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a GenericNN object.

Parameters:

• weights (torch.Tensor | list[torch.Tensor]) – Weights for each linear layer.

• biases (torch.Tensor | list[torch.Tensor], optional) – Bias for each linear layer. Length of weights and biases must match if list.

• act_fns (nn.module.activation | list, optional) – Activation for each linear layer.

model.generate_layers(weights: torch.Tensor | List[torch.Tensor], biases: torch.Tensor | List[torch.Tensor], act_fns: torch.nn.Module | List[torch.nn.Module]) → List[torch.nn.Module]

Creates linear layers and activation function to be used as inputs for nn.Sequential.

Parameters:

• weights (torch.Tensor | list[torch.Tensor]) – Weights for each linear layer.

• biases (torch.Tensor | list[torch.Tensor] | NoneType) – Bias for each linear layer. Length of weights and biases must match if list.

• act_fns (nn.module.activation | list | NoneType) – Activation for each linear layer. If activation Layer (i.e. not list) act_fns will be repeated for each linear layer. It is recommended to pass in the class rather than instance of activation Layer, as certain FA methods require no duplicate layers in the model.

class model.ConflictingFeaturesNN(continuous_dim: int, weights: torch.Tensor)

Bases: torch.nn.Sequential

A crafted neural network model that incorporates cancellation features.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a ConflictingFeaturesNN object.

Parameters:

• continuous_dim (int) – Dimension length of the continuous features, excluding cancellation features.

• weights (torch.Tensor) – Feature weights of the model. Should have length continuous_dim.

_create_layer_weights(continuous_dim: int, weights: torch.Tensor) → Tuple

Creates the weights for the layers in a ConflictingFeaturesNN model.

Parameters:

• continuous_dim (int) – Number of continuous features.

• weights (torch.Tensor) – Feature weights of the model. Should have length continuous_dim.

Returns:

Tuple containing the weights and activation functions for the neural network model.

Return type:

tuple[list, NoneType, list]

Raises:

AssertionError – If weights are not specified in a valid shape.

class model.ContinuousFeaturesNN(n_features: int, weights: torch.Tensor)

Bases: torch.nn.Sequential

A crafted neural network model that incorporates continuous features with ReLU.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a ContinuousFeaturesNN object.

Parameters:

• n_features (int) – dimensions of the input.

• weights (torch.Tensor) – weights of the model. Should have length n_features.

_create_layer_weights(n_features: int, weights: torch.Tensor) → Tuple

Creates the weights for the layers in a ContinuousFeaturesNN model.

Parameters:

• n_features (int) – Number of features.

• weights (torch.Tensor) – Feature weights of the model. Should have length continuous_dim.

Returns:

Tuple containing the weights and activation functions for the neural network model.

Return type:

tuple[list, NoneType, list]

Raises:

AssertionError – If weights are not specified in a valid shape.

class model.DynamicNN(config: List[Dict], custom_layers: List | None = None)

Bases: torch.nn.Sequential

Class that enables the instantiation of custom neural network architectures using a list of layer configurations.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a DynamicNN object.

Parameters:

• config (list[dict]) – List of layer configurations. Each configuration is a dictionary specifying the layer type and its corresponding parameters.

• custom_layers (list, optional) – List of custom layer classes. Defaults to None.

class model.InteractingFeaturesNN(n_features: int, weights: List[float | Tuple], interacting_features: List[Tuple[int, int]])

Bases: torch.nn.Sequential

Implements a neural network model designed to explicitly model interactions between specific pairs of features within the input data.

This model is capable of emphasizing or de-emphasizing the impact of these interactions on the model’s output through a specialized network architecture and custom weight assignments.

The network consists of linear layers combined with ReLU activation, structured to manipulate the input # features based on the predefined interactions. The interactions are modelled such that the influence of one feature on another can be either enhanced or canceled, according to the specified weights and the interaction mechanism implemented within the network.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes the InteractingFeaturesNN model with specified dimensions, weights, and interactions.

The architecture is designed to create a network that can process feature interactions by rearranging and weighting input features according to the specified interactions.

Parameters:

• n_features (int) – The total number of features in the input data. This includes both interacting and non-interacting features.

• weights (list) – A list of floats or tuples specifying the weights to be applied to the features of the model. This list should have a len that matches the n_features, with each element corresponding to a feature in the input data.

• interacting_features (list[tuple]) – A list where each tuple contains two integers representing the indices of the interacting features. The first element in the tuple is considered the impacting feature, and the second element is the feature being impacted.

_validate_inputs(weights: List[float | Tuple], interacting_features: List[Tuple[int, int]]) → None

Validates the inputs.

Parameters:

• weights (list) – A list of floats or tuples specifying the weights to be applied to the features of the model.

• interacting_features (list[tuple]) – A list where each tuple contains two integers representing the indices of the interacting features.

Raises:

AssertionError – If the inputs are not in the valid datatypes.

_create_layer_weights(n_features: int, weights: List[float | Tuple], interacting_features: List[Tuple[int, int]]) → Tuple

Creates the weights for the layers in a InteractingFeaturesNN model.

Parameters:

• n_features (int) – The total number of features in the input data.

• weights (list) – A list of floats or tuples specifying the weights to be applied to the features of the model.

• interacting_features (list[tuple]) – A list where each tuple contains two integers representing the indices of the interacting features.

Returns:

Tuple containing the weights and activation functions for the neural network model.

Return type:

tuple[list, NoneType, list]

class model.PertinentNN(n_features: int, weights: torch.Tensor, pn_features: torch.Tensor, pn_weight_factor: float)

Bases: torch.nn.Sequential

Implements a neural network model specifically designed to handle pertinent negatives in input features.

This model modifies input features based on their relevance and the presence of pertinent negatives, employing a specialized network architecture with custom weights and biases to emphasize or suppress certain features according to their pertinence.

The network consists of linear layers combined with ReLU activation functions, structured to manipulate the input features dynamically. It uses the provided weights and a ‘pertinence’ tensor to adjust the impact of each feature on the model’s output, effectively highlighting the role of pertinent negatives in the prediction process.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes the PertinentNN model with specified dimensions, weights, pertinent negatives, and a multiplier.

The architecture is designed to first adjust the input features based on their pertinence, then to process these adjusted features through a series of layers that further manipulate and combine them based on the specified weights and the multiplier for pertinent negatives. The final output is a single value obtained through a linear combination of the processed features.

Parameters:

• n_features (int) – The total number of features in the input data.

• weights (torch.Tensor) – A tensor specifying the weights to be applied to the features of the model. This tensor should have a shape that matches the n_features, with each weight corresponding to a feature in the input data.

• pn_features (torch.Tensor) – A tensor indicating the presence (1) or absence (0) of pertinent negatives for each feature. The length of this tensor can be equal to or less than n_features. If it is less, the missing values are assumed to be 0 (no pertinent negative).

• pn_weight_factor (float) – A multiplier used to adjust the weights of the features identified as pertinent negatives.

_reformat_pn_weight(n_features: int, pn_features: torch.Tensor) → torch.Tensor

Reformats pn_features into tensors.

Parameters:

• n_features (int) – The total number of features in the input data.

• pn_features (torch.Tensor) – A torch.Tensor object indicating which feature is a pertinent negative.

Returns:

Reformatted tensor representing the features.

Return type:

torch.Tensor

_create_layer_weights(n_features: int, weights: torch.Tensor, pn_features: torch.Tensor, pn_weight_factor: float) → Tuple

Creates the weights for the layers in a PertinentNN model.

Parameters:

• n_features (int) – The total number of features in the input data.

• weights (torch.Tensor) – A tensor specifying the weights to be applied to the features of the model.

• pn_features (torch.Tensor) – A tensor indicating the presence (1) or absence (0) of pertinent negatives for each feature.

• pn_weight_factor (float) – A multiplier used to adjust the weights of the features identified as pertinent negatives.

Returns:

Tuple containing the weights and activation functions for the neural network model.

Return type:

tuple[list, list, list]

class model.ShatteredGradientsNN(weights: torch.Tensor, act_fun: str = 'Relu')

Bases: torch.nn.Sequential

Implements a neural network model using a linear layer followed by an activation function.

This model is designed to exhibit shattered gradients. To generate a model that exhibits shattered gradients, use shattered_grad.py, located in datagenerator.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a ShatteredGradientsNN object.

Parameters:

• weights (torch.Tensor) – The weights to be applied to the linear layer.

• act_fun (str) – The activation function to be used. Valid options are “Relu”, “Gelu”, or “Sigmoid”. Defaults to ‘Relu’.

_default_activation_function(act_fun: str) → torch.nn.Module

Returns the default activation function based on the provided string.

The _default_activation_function method maps the provided activation function name to the corresponding PyTorch activation function module. Supported activation functions include “Relu” (ReLU), “Gelu” (GELU), and “Sigmoid” (Sigmoid). If the provided name is not in the supported list, a KeyError is raised.

Parameters:

act_fun (str) – The activation function name or class.

Returns:

The corresponding PyTorch activation function module.

Return type:

torch.nn.Module

Raises:

KeyError – If the given activation function is not supported.

class model.UncertaintyNN(n_features: int, weights: torch.Tensor, softmax_layer: bool = True)

Bases: torch.nn.Sequential

Implements a neural network model designed to capture behaviour were an input node impact all or several output nodes equally.

This model uses a linear layer followed by a softmax activation function to compute a distribution over the input features, effectively capturing the uncertainty or confidence level associated with each feature.

For best practice, please create an instance of network using generate_model() method of UncertaintyAwareDataset.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes the UncertaintyNN model with a specified dimension for the input features and custom weights.

The initialized model consists of a single linear layer without bias, followed by a softmax layer to normalize the output of the linear layer into a probability distribution, representing the model’s confidence or uncertainty regarding each input feature.

Parameters:

• n_features (int) – The total number of features in the input data. This parameter determines the dimensionality of the input to the linear layer and subsequently the output dimension of the model before applying the softmax.

• weights (torch.Tensor) – A torch.Tensor object to directly specify the weights for the linear transformation of the input features.

class model.PropFormulaNN(formula_expr: sympy.core.function.FunctionClass, atoms: Tuple)

Bases: torch.nn.Sequential

A neural network model representing a propositional formula that is constructed using only NOT (~), OR (|), AND (&) with syntax from SymPy.

It takes inputs where -1 represents False and +1 represents True.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

parse_tree

The ParseTree representation of the formula.

Type:

ParseTree

atoms

The unique atoms in the formula. The ordering of this tuple matters in determining the ordering of the input to the network.

Type:

tuple[str]

Initializes a PropFormulaNN instance and generates all the torch.nn.Linear layers necessary to construct the neural network.

Parameters:

• formula_expr (sympy.core.function.FunctionClass) – The expression representing the propositional formula. Constructed using only syntax from SymPy with the operators NOT (~), OR (|), AND (&).

• atoms (tuple[str]) – A tuple of unique atoms in the formula.

parse_tree

atoms

_init_layers() → List[torch.nn.Module]

Initializes all the layers of the neural network into a list of nn.Module.

The layers are initialized and created in ascending order of height in the ParseTree representation of the formula.

Returns:

List of neural network layers.

Return type:

list[torch.nn.Module]

_atom_layer() → torch.nn.Module

Initializes the first layer of the neural network that duplicates and reorders the input propositional atoms based on their ordering in the ParseTree.

Returns:

Linear layer that duplicates and reorders the input atoms.

Return type:

torch.nn.Linear

_get_height_layers(height: int) → List[torch.nn.Module]

Retrieves layers corresponding to a specific height in the ParseTree.

Parameters:

height (int) – The specified height within the ParseTree representatation.

Returns:

List of neural network layers for the nodes that are located

at the given height in the ParseTree representation.

Return type:

list[torch.nn.Module]

_init_binary_operator_layers(subtree_ls: List[ParseTree]) → List[torch.nn.Module]

Initializes the all the layers associated with carrying out the operators involved in the given list of subtrees.

It assumes that the given list of subtrees contains at least one that involves a binary operator/connective.

Parameters:

subtree_ls (list[ParseTree]) – List of ParseTree instances with the same height in the full ParseTree that includes binary operators.

Returns:

List of neural network layers for binary operators.

Return type:

list[torch.nn.Module]

_binary_operator_block(arg_num_ls: List[int], subtree_ls: List[ParseTree], first_block: bool = False) → List[torch.nn.Module]

Creates a block of layers that simpliefies the subexpression for the given list of subtrees by applying the binary operator/connective once whenever possible.

The binary operator/connective from the same subtree can be applied simultaneously as long as the number of arguments inputted to it permits (i.e. divisible by two).

Parameters:

• arg_num_ls (list[int]) – List of number of arguments that the operator/node of each subtrees takes.

• subtree_ls (list[ParseTree]) – List of subtrees with the same height in the ParseTree.

• first_block (bool) – Indicates if this is the first block of the layers for this collection of subtrees with the same height.

Returns:

List of neural network layers in a single block.

Return type:

list[torch.nn.Module]

_identity_weights() → Tuple[torch.Tensor, torch.Tensor]

Generates the weights for the two nn.Linear layers in an identity block.

Returns:

Inter and out layer weights for an identity block.

Return type:

tuple[torch.Tensor, torch.Tensor]

_and_or_weights(sub_inter_dim: int, operator: str) → Tuple[torch.Tensor, torch.Tensor]

Generates weights for the two nn.Linear layers in an AND or OR block.

Parameters:

• sub_inter_dim (int) – Dimension of the intermediate layer.

• operator (str) – The operator type (AND or OR).

Returns:

Inter and out layer weights for an AND or OR block.

Return type:

tuple[torch.Tensor, torch.Tensor]

_init_unary_operator_layer(subtree_ls: List[ParseTree]) → List[torch.nn.Module]

Initializes the all the layers associated with carrying out the operators involved in the given list of subtrees.

It assumes that the given list of subtrees contains only unary operators.

Parameters:

subtree_ls (list[ParseTree]) – List of ParseTree instances with the same height in the full ParseTree that only has unary operators.

Returns:

List of neural network layers for unary operators.

Return type:

list[torch.nn.Module]

_count_binary_operators(subtree_ls: List[ParseTree]) → int

Counts the occurrences of binary operators in the given list of ParseTree instances.

Parameters:

subtree_ls (list[ParseTree]) – List of ParseTree instances with the same height in the full ParseTree.

Returns:

Count of binary operators.

Return type:

int

_post_block_arg_num_ls(arg_num_ls: List[int]) → List[int]

Returns the list of number of arguments of each subtree after a binary operator block of layers.

Parameters:

arg_num_ls (list[int]) – List of numbers of arguments for each subtree.

Returns:

Number of arguments for each subtree after a block.

Return type:

list[int]

class model.BooleanAndNN(n_features: int = 2)

Bases: torch.nn.Sequential

Implements a neural network model designed to mimic the ‘AND’ logical operation on input features.

When only -1 or 1 are passed in as part of the input to this model, it is effectively performing the ‘AND’ operation.

This model is structured as a sequence of layers that progressively compute the ‘AND’ operation on the input features, scaling the dimensionality of the input at each step until the final output is obtained. The network employs a specific arrangement of weights and intermediate operations such that it is also equivalent to computing the minimum value among a collection of values given as as the input.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a

sequential manner.

dims

A list that keeps track of the dimensions of each layer in the network.

Type:

list

Initializes an AND model with the specified input features dimension.

Parameters:

n_features (int) – The dimension (number of features) of the input data. Defaults to 2.

n_features = 2

_create_layer_weights() → Tuple

Initializes the layers of the network starting from the input dimension.

Parameters:

in_dim (int) – The dimension of the input to the current layer.

Returns:

A list of initialized layers that make up the network.

Return type:

list

class model.BooleanNotNN(n_features: int)

Bases: torch.nn.Sequential

Implements a neural network model designed to apply the logical NOT operation to input features.

This model consists of a single linear layer without bias, configured to negate each input feature. The weights of the layer are initialized to -1 for each feature, effectively performing the ‘NOT’ operation in a bitwise manner when the inputs are considered to be -1 or 1.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

Initializes a NOT model with a specified dimension for the input features.

The initialized model consists of a single linear layer without bias. The weights of this layer are set to -1 for each input feature, enabling the layer to negate the values of all input features.

Parameters:

n_features (int) – The total number of features in the input data. This parameter determines the dimensionality of the input to the linear layer as well as the output dimension, allowing the model to apply the NOT operation to each feature independently.

class model.BooleanOrNN(n_features: int = 2)

Bases: torch.nn.Sequential

Implements a neural network model designed to mimic the ‘OR’ logical operation on input features.

When only -1 or 1 are passed in as part of the input to this model, it is effectively performing the ‘OR’ operation.

This model is structured as a sequence of layers that progressively compute the ‘OR’ operation on the input features, scaling the dimensionality of the input at each step until the final output is obtained. The network employs a specific arrangement of weights and intermediate operations such that it is also equivalent to computing the maximum value among a collection of values given as as the input.

Inherits from:

torch.nn.Sequential: Parent class for implementing neural networks with modules defined in a sequential manner.

dims

A list that keeps track of the dimensions of each layer in the network.

Type:

list

Initializes an AND model with the specified input features dimension.

Parameters:

n_features (int) – The dimension (number of features) of the input data. Defaults to 2.

n_features = 2

_create_layer_weights() → Tuple

Initializes the layers of the network starting from the input dimension.

Parameters:

in_dim (int) – The dimension of the input to the current layer.

Returns:

A list of initialized layers that make up the network.

Return type:

list