Neural Network Models

class relucent.NN(layers: Iterable[Module] | Mapping[str, Module], input_shape: tuple[int, ...] | None = None, device: device | None = None, dtype: dtype | None = None)

Bases: Module

Neural network class that interfaces with the rest of the package

forward(data: Tensor) → Tensor

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_all_layer_outputs(data: Tensor, layers: Container[str] | None = None, verbose: bool = False) → OrderedDict[str, Tensor]

Get outputs from specified layers.

Parameters:

  • data – Input tensor to the network.

  • layers – List of layer names to include. If None, includes all layers. Defaults to None.

  • verbose – If True, prints layer information. Defaults to False.

Returns:

Dictionary mapping layer names to their outputs.

Return type:

OrderedDict

get_grid(bounds: float | None = None, res: int | None = None) → tuple[ndarray, ndarray, ndarray]

Generate a 2D grid of input points.

Creates a regular grid of points in 2D space. Only works for 2D input spaces.

Parameters:

  • bounds – Half-width of the grid (grid spans [-bounds, bounds]). Defaults to config.DEFAULT_GRID_BOUNDS.

  • res – Resolution (number of points per dimension). Defaults to config.DEFAULT_GRID_RES.

Returns:

(x_coords, y_coords, input_points) where input_points is an

array of shape (res*res, 2).

Return type:

tuple

output_grid(bounds: float | None = None, res: int | None = None) → tuple[ndarray, ndarray, OrderedDict[str, Tensor]]

Generate a grid and compute network outputs for all points.

Parameters:

  • bounds – Half-width of the grid. Defaults to config.DEFAULT_GRID_BOUNDS.

  • res – Resolution (number of points per dimension). Defaults to config.DEFAULT_GRID_RES.

Returns:

(x_coords, y_coords, layer_outputs) where layer_outputs is

an OrderedDict mapping layer names to outputs.

Return type:

tuple

save_numpy_weights() → None

Save NumPy weights and biases for all Linear layers.

This method saves the weights and biases of all Linear layers to the weight_cpu and bias_cpu attributes of their respective layer objects.

shi2weights(shi: int, return_idx: bool = False) → Tensor | tuple[str, int]

Get weights corresponding to a neuron index.

Parameters:

  • shi – Index of the neuron (supporting hyperplane index).

  • return_idx – If True, returns (layer_name, neuron_index_in_layer). If False, returns a pointer to the weight tensor. Defaults to False.

Returns:

torch.Tensor weight vector. If return_idx is True: (layer_name, neuron_index) tuple.

Return type:

If return_idx is False

Raises:

ValueError – If the neuron index is invalid.

property device: device
property dtype: dtype
property num_relus: int
relucent.get_mlp_model(widths: Iterable[int], add_last_relu: bool = False) → NN

Create an NN object for a multi-layer perceptron (MLP).

Constructs a fully connected neural network with the specified layer widths. Each layer (except optionally the last) is followed by a ReLU activation.

Parameters:

  • widths – List of integers specifying the number of neurons in each layer, including the input layer. For example, [2, 10, 5, 1] creates a network with input dimension 2, two hidden layers with 10 and 5 neurons, and output dimension 1.

  • add_last_relu – If True, adds a ReLU after the last layer. Defaults to False.

Returns:

A configured neural network object.

Return type:

NN

relucent.convert(input: Module | Iterable[Module] | Mapping[str, Module], input_shape: tuple[int, ...] | None = None) → NN

Convert a PyTorch model to canonical NN format.

Converts various PyTorch layer types (Conv2d, AvgPool2d, etc.) into the canonical format consisting only of Linear and ReLU layers.

Supported layer types:

  • Linear, ReLU: Passed through unchanged

  • Conv2d: Converted to Linear

  • AvgPool2d: Converted to Linear (if kernel_size == stride)

  • Flatten: Handled automatically

  • Dropout: Removed (not needed for inference)

  • LogSoftmax: Stops conversion (output layer)

Parameters:

  • input – An torch.nn.Module, a ModuleList, or a ModuleDict.

  • input_shape – Shape of the input data (excluding batch dimension). If None, infers from the input model. Defaults to None.

Returns:

A new NN object in canonical format.

Return type:

NN

Raises:

  • ValueError – If an unsupported layer type is encountered or the model

  • does not define an input_shape attribute. –