Skip to main content

​
Module

Base class for all neural network modules in Deepbox. All models should subclass this class. Modules can contain other modules, allowing you to nest them in a tree structure. You can register submodules, parameters (trainable tensors), and buffers (non-trainable tensors).

​
Constructor

abstract class Module
The Module class is abstract and should be extended by custom layers and models.

​
Properties

  • training: boolean - Whether the module is in training mode (affects Dropout, BatchNorm, etc.)

​
Methods

​
forward

abstract forward(...inputs: AnyTensor[]): AnyTensor
Forward pass of the module. Must be implemented by all subclasses. Parameters:
  • inputs - Input tensors (Tensor or GradTensor)
Returns: Output tensor

​
call

call(...inputs: AnyTensor[]): AnyTensor
Makes the module callable. Allows using module(x) instead of module.forward(x). Executes forward pre-hooks, then forward pass, then forward hooks.

​
train

train(mode: boolean = true): this
Sets the module in training mode. Parameters:
  • mode - Training mode (true) or evaluation mode (false)
Returns: this (for method chaining)

​
eval

eval(): this
Sets the module in evaluation mode. Equivalent to train(false). Returns: this (for method chaining)

​
parameters

*parameters(recurse: boolean = true): Generator<GradTensor>
Generator that yields all trainable parameters of this module and its children. Parameters:
  • recurse - Whether to include parameters of child modules (default: true)
Returns: Generator of GradTensor parameters

​
namedParameters

*namedParameters(prefix: string = "", recurse: boolean = true): Generator<[string, GradTensor]>
Generator that yields all named parameters with their hierarchical names. Parameters:
  • prefix - Prefix for parameter names
  • recurse - Whether to include parameters of child modules
Returns: Generator of [name, parameter] pairs

​
modules

*modules(recurse: boolean = true): Generator<Module>
Generator that yields all child modules. Parameters:
  • recurse - Whether to include nested child modules
Returns: Generator of modules

​
namedModules

*namedModules(prefix: string = "", recurse: boolean = true): Generator<[string, Module]>
Generator that yields all named child modules.

​
zeroGrad

zeroGrad(): void
Zeros out the gradients of all parameters. Call this before each training iteration.

​
freezeParameters

freezeParameters(names?: string[], recurse: boolean = true): void
Freezes specific parameters by setting requiresGrad=false. Parameters:
  • names - Array of parameter names to freeze. If undefined, freezes all parameters.
  • recurse - Whether to include parameters from child modules
Warning: Creates new GradTensor instances. Recreate optimizers after calling this.

​
unfreezeParameters

unfreezeParameters(names?: string[], recurse: boolean = true): void
Unfreezes specific parameters by setting requiresGrad=true. Parameters:
  • names - Array of parameter names to unfreeze
  • recurse - Whether to include parameters from child modules

​
to

to(device: Device): this
Moves module to a specific device. Currently updates device metadata only. Parameters:
  • device - Target device (‘cpu’, ‘webgpu’, ‘wasm’)
Returns: this (for method chaining) Warning: Metadata-only operation. Does not actually transfer data between devices.

​
stateDict

stateDict(): {
  parameters: Record<string, StateEntry>;
  buffers: Record<string, StateEntry>;
}
Gets the state dictionary containing all parameters and buffers. Returns: Object with parameters and buffers

​
loadStateDict

loadStateDict(stateDict: {
  parameters?: Record<string, StateEntry>;
  buffers?: Record<string, StateEntry>;
}): void
Loads state dictionary into the module. Parameters:
  • stateDict - State dictionary to load

​
Protected Methods

​
registerModule

protected registerModule(name: string, module: Module): void
Registers a child module.

​
registerParameter

protected registerParameter(name: string, param: GradTensor): void
Registers a trainable parameter.

​
registerBuffer

protected registerBuffer(name: string, buffer: Tensor): void
Registers a non-trainable buffer (e.g., running statistics).

​
Example

import { Module, Linear, ReLU } from 'deepbox/nn';
import type { Tensor } from 'deepbox/ndarray';

class MyModel extends Module {
  private fc1: Linear;
  private relu: ReLU;
  private fc2: Linear;

  constructor() {
    super();
    this.fc1 = new Linear(10, 5);
    this.relu = new ReLU();
    this.fc2 = new Linear(5, 2);
    this.registerModule('fc1', this.fc1);
    this.registerModule('relu', this.relu);
    this.registerModule('fc2', this.fc2);
  }

  forward(x: Tensor): Tensor {
    let out = this.fc1.forward(x);
    out = this.relu.forward(out);
    out = this.fc2.forward(out);
    return out;
  }
}

const model = new MyModel();
model.train(); // Set to training mode

// Get all parameters for optimizer
const params = Array.from(model.parameters());

​
Sequential

Sequential container for stacking layers in a linear pipeline. Simplifies model construction by automatically chaining layers.

​
Constructor

class Sequential extends Module

constructor(...layers: Module[])
Parameters:
  • layers - Variable number of Module instances to stack sequentially
Throws:
  • InvalidParameterError - If no layers are provided
  • DeepboxError - If a layer is undefined

​
Properties

  • length: number - Number of layers in the container

​
Methods

​
forward

forward(...inputs: AnyTensor[]): AnyTensor
Sequentially applies all layers. Output of each layer becomes input to the next. Parameters:
  • inputs - Single input tensor
Returns: Output tensor after passing through all layers Throws:
  • InvalidParameterError - If input count is invalid or a layer returns multiple outputs

​
getLayer

getLayer(index: number): Module
Gets a layer by index. Parameters:
  • index - Zero-based index of the layer
Returns: The layer at the specified index Throws:
  • IndexError - If index is out of bounds

​
Iteration

Sequential is iterable and supports the iterator protocol: 
for (const layer of sequential) {
  console.log(layer);
}

​
Example

import { Sequential, Linear, ReLU, Dropout } from 'deepbox/nn';
import { tensor } from 'deepbox/ndarray';

// Create a feedforward network
const model = new Sequential(
  new Linear(784, 256),
  new ReLU(),
  new Dropout(0.5),
  new Linear(256, 128),
  new ReLU(),
  new Dropout(0.5),
  new Linear(128, 10)
);

const input = tensor(new Array(784).fill(0));
const output = model.forward(input);

// Access individual layers
const firstLayer = model.getLayer(0); // Linear(784, 256)
const layerCount = model.length; // 7

// Iterate over layers
for (const layer of model) {
  console.log(layer.toString());
}

​
Building Complex Networks

import { Sequential, Linear, ReLU, BatchNorm1d } from 'deepbox/nn';

// MLP with batch normalization
const mlp = new Sequential(
  new Linear(512, 256),
  new BatchNorm1d(256),
  new ReLU(),
  new Linear(256, 128),
  new BatchNorm1d(128),
  new ReLU(),
  new Linear(128, 10)
);

// CNN feature extractor
const cnn = new Sequential(
  new Conv2d(3, 64, 3, { padding: 1 }),
  new ReLU(),
  new MaxPool2d(2),
  new Conv2d(64, 128, 3, { padding: 1 }),
  new ReLU(),
  new MaxPool2d(2)
);

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us