MLP Model

A Multi-Layer Perceptron (MLP) model implementation for sequence prediction tasks. This module provides the core MLP network, the MLPModel wrapper that integrates it with the ALF framework, and the MLPModelConfig and MLPTrainConfig dataclasses for configuration.

class alf_tools.models.mlp.MLP(input_dim, hidden_dims, activation, norm, dropout, model_seed=0)

Bases: Module

Feedforward MLP for scalar regression on pre-computed feature vectors.

Architecture:

input → [Linear → Norm → Activation → Dropout] × depth → Linear → scalar

forward(x)

Run a forward pass and return scalar predictions of shape (batch,).

Return type:

Tensor

Returns:

1-D tensor of scalar predictions, one per input row.

class alf_tools.models.mlp.MLPModel(name='mlp_model', model_config=None, train_config=None, device=None)

Bases: BaseModel

Surrogate model wrapping MLP for pre-computed vector inputs.

Featurisation is a passthrough — inputs must arrive as TABULAR candidates whose data is a numpy array or torch tensor.

cleanup()

Reset the model to its untrained state.

After cleanup(), the next train() call will reinitialise the network, allowing reuse with data of a different feature dimension.

Return type:

None

featurise(inputs)

Convert TABULAR candidates to a float32 tensor.

Parameters:

inputs (LabelledCandidates | list[Candidate]) – Either LabelledCandidates or a list of Candidates. Each candidate’s data must be a numpy array or torch tensor.

Return type:

Tensor

Returns:

Float32 tensor of shape (n_candidates, feature_dim).

Raises:

ValueError – If any candidate has an unsupported modality.

get_epoch_metrics()

Return per-epoch metrics recorded during the most recent train() call.

Return type:

list[SurrogateEpochMetrics]

Returns:

List of SurrogateEpochMetrics, one per epoch; empty before first train().

get_training_summary_metrics()

Return scalar summary metrics from the most recent train() call.

Return type:

dict[str, float | int | number]

Returns:

Dict of metric names to values; empty before first train().

predict(candidate_points)

Return mean predictions, with MC dropout empirical distribution if configured.

Parameters:

candidate_points (list[Candidate]) – Candidates to predict for.

Return type:

Predictions

Returns:

Predictions with means always set. If n_mc_passes > 0, variances and empirical_dist are also populated from stochastic forward passes.

Raises:

RuntimeError – If train() has not been called yet.

sample(condition=None)

Not implemented; raises NotImplementedError.

Return type:

list[Candidate]

train(train_data, val_data=None)

Fit the MLP to train_data, optionally tracking val_data metrics per epoch.

The network is initialised on the first call and re-used on subsequent calls (warm-start). Epoch metrics are reset at the start of each call.

Parameters:

• train_data (LabelledCandidates) – Labelled candidates used for gradient updates.

• val_data (LabelledCandidates | None) – Optional labelled candidates for per-epoch validation loss.

Raises:

• ValueError – If called after a previous train() with data of a different feature dimension without calling cleanup() first.

• RuntimeError – If val_data is provided but avg_val_loss or val_metrics are not set after training. This indicates an internal error in the training loop.

Return type:

None

class alf_tools.models.mlp.MLPModelConfig(hidden_dims=<factory>, activation='relu', norm='none', dropout=0.0, n_mc_passes=0, model_seed=0, dropout_seed=None)

Bases: object

Configuration for MLP model architecture.

Parameters:

• hidden_dims (list[int]) – Sizes of hidden layers; length determines depth.

• activation (Literal['relu', 'gelu', 'silu']) – Activation function applied after each hidden layer’s norm.

• norm (Literal['none', 'batch', 'layer']) – Normalisation applied before activation; “none” skips it.

• dropout (float) – Dropout probability applied after activation in each hidden layer.

• n_mc_passes (int) – Number of stochastic forward passes at inference for MC dropout. 0 disables MC dropout and returns means only.

• model_seed (int) – Global seed for weight initialisation and training data shuffling. Also used as the dropout generator seed when dropout_seed is None. Note: two models with the same seed will have identical initial weights — pass distinct seeds for ensemble members.

• dropout_seed (int | None) – If set, overrides model_seed exclusively for the MC dropout pass generator.

activation: Literal['relu', 'gelu', 'silu'] = 'relu'

dropout: float = 0.0

dropout_seed: int | None = None

hidden_dims: list[int]

model_seed: int = 0

n_mc_passes: int = 0

norm: Literal['none', 'batch', 'layer'] = 'none'

class alf_tools.models.mlp.MLPTrainConfig(learning_rate=0.001, log_frequency=10, normalise_inputs_strategy=None, standardise_outputs=False, label_dtype=None, batch_size=32, num_epochs=50, optimizer='adam', weight_decay=0.0)

Bases: BaseTrainConfig

Configuration for MLP training.

Parameters:

• learning_rate (float) – Learning rate for the optimiser.

• batch_size (int) – Mini-batch size.

• num_epochs (int) – Number of training epochs. Must be >= 1.

• optimizer (Literal['adam', 'adamw']) – Optimiser type; “adam” or “adamw”.

• weight_decay (float) – L2 regularisation coefficient.

• log_frequency (int) – Log a training summary every this many epochs.

batch_size: int = 32

learning_rate: float = 0.001

log_frequency: int = 10

num_epochs: int = 50

optimizer: Literal['adam', 'adamw'] = 'adam'

weight_decay: float = 0.0