neuralogic.nn.trainer package

Submodules

neuralogic.nn.trainer.callbacks module

class CheckpointCallback(directory: str | Path, filename: str = 'best.pkl')[source]

Bases: TrainerCallback

Save the model whenever validation loss improves.

Parameters:

  • directory (str or Path) – Directory to save checkpoints into (created if missing).

  • filename (str) – Filename for the checkpoint file (default "best.pkl").

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

property path: Path
class EarlyStoppingCallback(patience: int, min_delta: float = 0.0)[source]

Bases: TrainerCallback

Stop training when validation loss stops improving.

Parameters:

  • patience (int) – Number of epochs with no improvement after which training stops.

  • min_delta (float) – Minimum absolute change to qualify as an improvement.

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

class ProgressCallback(epochs: int)[source]

Bases: TrainerCallback

Show a tqdm progress bar during training.

Parameters:

epochs (int) – Total number of epochs (used for progress bar length).

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

on_train_end(trainer: Trainer) → None[source]

Called once after training finishes (or early-stops).

class TrainerCallback[source]

Bases: object

Base class for training callbacks.

Override any of the hooks. The trainer calls them in the order they were passed to Trainer.fit().

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

on_train_end(trainer: Trainer) → None[source]

Called once after training finishes (or early-stops).

neuralogic.nn.trainer.helpers module

neuralogic.nn.trainer.history module

class TrainerHistory(train_losses: list[float] = <factory>, val_losses: list[float] = <factory>, train_metrics: dict[str, list[float]]=<factory>, val_metrics: dict[str, list[float]]=<factory>, learning_rates: list[float] = <factory>, best_epoch: int = 0, best_val_loss: float = inf, stopped_early: bool = False)[source]

Bases: object

Training history collected during a Trainer.fit() run.

train_losses

Mean training loss per epoch.

Type:

list[float]

val_losses

Mean validation loss per epoch (empty if no validation set).

Type:

list[float]

train_metrics

Per-epoch extra metrics on the training set (each key maps to a list of epoch-level means).

Type:

dict[str, list[float]]

val_metrics

Per-epoch extra metrics on the validation set.

Type:

dict[str, list[float]]

learning_rates

Learning rate at each epoch.

Type:

list[float]

best_epoch

Epoch (0-indexed) that achieved the lowest validation loss.

Type:

int

best_val_loss

Lowest validation loss observed.

Type:

float

stopped_early

True if early stopping fired.

Type:

bool

best_epoch: int = 0
best_val_loss: float = inf
learning_rates: list[float]
stopped_early: bool = False
train_losses: list[float]
train_metrics: dict[str, list[float]]
val_losses: list[float]
val_metrics: dict[str, list[float]]

neuralogic.nn.trainer.metrics module

class Metric(value)[source]

Bases: str, Enum

Enum of available metric names.

Inherits str so members can be used directly where a string is expected:

>>> Metric.ACCURACY == "accuracy"
True
>>> trainer.fit(..., metrics=[Metric.ACCURACY, Metric.F1_MACRO])
ACCURACY = 'accuracy'
F1_MACRO = 'f1_macro'
MAE = 'mae'
MSE = 'mse'
PRECISION_MACRO = 'precision_macro'
R2 = 'r2'
RECALL_MACRO = 'recall_macro'
RMSE = 'rmse'
compute_metrics(targets: list, outputs: list, names: Sequence[str | Metric]) → dict[str, float][source]

Compute named metrics over a batch of (target, output) pairs.

Each metric receives the full batch and returns a single float.

Parameters:

  • targets (list) – Per-sample target values (floats, lists, or 2D lists).

  • outputs (list) – Per-sample output values (same shapes as targets).

  • names (Sequence[str or Metric]) – Metric names to compute, e.g. ["accuracy"] or [Metric.MAE, Metric.R2].

Returns:

Mapping from metric name to its value across the batch.

Return type:

dict[str, float]

neuralogic.nn.trainer.trainer module

class Trainer(module: NeuralModule)[source]

Bases: object

fit(train_dataset: Dataset | GroundedDataset | BuiltDataset, val_dataset: Dataset | GroundedDataset | BuiltDataset | None = None, *, epochs: int = 1, batch_size: int = 1, early_stopping_patience: int | None = None, min_delta: float = 0.0, checkpoint_dir: str | Path | None = None, metrics: Sequence[str | Metric] | None = None, silent: bool = False, callbacks: Sequence[TrainerCallback] | None = None) → TrainerHistory[source]

Run the training loop.

Parameters:

  • train_dataset – Training data. Raw Dataset objects are built automatically; pass a BuiltDataset to skip repeated grounding.

  • val_dataset – Optional validation data. When provided, validation loss (and any requested metrics) are computed after every epoch. Early stopping and checkpointing depend on validation loss.

  • epochs (int) – Number of epochs to train. Default 1.

  • batch_size (int) – Batch size when building raw datasets. Default 1.

  • early_stopping_patience (int or None) – Stop after this many epochs without validation-loss improvement. Requires val_dataset. Default None (no early stopping).

  • min_delta (float) – Minimum absolute change in validation loss to count as improvement. Default 0.0.

  • checkpoint_dir (str, Path, or None) – Directory to save the best model (by validation loss). A file named best.pkl is written on every improvement. Default None (no checkpointing).

  • metrics (Sequence[str or Metric] or None) – Extra metrics to compute, e.g. [Metric.ACCURACY] or ["mae", "r2"]. Loss is always tracked. Default None.

  • silent (bool) – If True, suppress the tqdm progress bar. Default False.

  • callbacks (Sequence[TrainerCallback] or None) – Additional callbacks to invoke. Built-in callbacks (early stopping, checkpoint, progress) are appended automatically based on the other arguments.

Returns:

Losses and metrics for every epoch.

Return type:

TrainerHistory

test(dataset: Dataset | GroundedDataset | BuiltDataset, *, batch_size: int = 1) → list[source]

Evaluate the model on a dataset (no weight updates).

Parameters:

  • dataset – Test data. Raw Dataset objects are built automatically.

  • batch_size (int) – Batch size when building raw datasets. Default 1.

Returns:

Model outputs for every sample.

Return type:

list

Module contents

class CheckpointCallback(directory: str | Path, filename: str = 'best.pkl')[source]

Bases: TrainerCallback

Save the model whenever validation loss improves.

Parameters:

  • directory (str or Path) – Directory to save checkpoints into (created if missing).

  • filename (str) – Filename for the checkpoint file (default "best.pkl").

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

property path: Path
class EarlyStoppingCallback(patience: int, min_delta: float = 0.0)[source]

Bases: TrainerCallback

Stop training when validation loss stops improving.

Parameters:

  • patience (int) – Number of epochs with no improvement after which training stops.

  • min_delta (float) – Minimum absolute change to qualify as an improvement.

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

class Metric(value)[source]

Bases: str, Enum

Enum of available metric names.

Inherits str so members can be used directly where a string is expected:

>>> Metric.ACCURACY == "accuracy"
True
>>> trainer.fit(..., metrics=[Metric.ACCURACY, Metric.F1_MACRO])
ACCURACY = 'accuracy'
F1_MACRO = 'f1_macro'
MAE = 'mae'
MSE = 'mse'
PRECISION_MACRO = 'precision_macro'
R2 = 'r2'
RECALL_MACRO = 'recall_macro'
RMSE = 'rmse'
class ProgressCallback(epochs: int)[source]

Bases: TrainerCallback

Show a tqdm progress bar during training.

Parameters:

epochs (int) – Total number of epochs (used for progress bar length).

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

on_train_end(trainer: Trainer) → None[source]

Called once after training finishes (or early-stops).

class Trainer(module: NeuralModule)[source]

Bases: object

fit(train_dataset: Dataset | GroundedDataset | BuiltDataset, val_dataset: Dataset | GroundedDataset | BuiltDataset | None = None, *, epochs: int = 1, batch_size: int = 1, early_stopping_patience: int | None = None, min_delta: float = 0.0, checkpoint_dir: str | Path | None = None, metrics: Sequence[str | Metric] | None = None, silent: bool = False, callbacks: Sequence[TrainerCallback] | None = None) → TrainerHistory[source]

Run the training loop.

Parameters:

  • train_dataset – Training data. Raw Dataset objects are built automatically; pass a BuiltDataset to skip repeated grounding.

  • val_dataset – Optional validation data. When provided, validation loss (and any requested metrics) are computed after every epoch. Early stopping and checkpointing depend on validation loss.

  • epochs (int) – Number of epochs to train. Default 1.

  • batch_size (int) – Batch size when building raw datasets. Default 1.

  • early_stopping_patience (int or None) – Stop after this many epochs without validation-loss improvement. Requires val_dataset. Default None (no early stopping).

  • min_delta (float) – Minimum absolute change in validation loss to count as improvement. Default 0.0.

  • checkpoint_dir (str, Path, or None) – Directory to save the best model (by validation loss). A file named best.pkl is written on every improvement. Default None (no checkpointing).

  • metrics (Sequence[str or Metric] or None) – Extra metrics to compute, e.g. [Metric.ACCURACY] or ["mae", "r2"]. Loss is always tracked. Default None.

  • silent (bool) – If True, suppress the tqdm progress bar. Default False.

  • callbacks (Sequence[TrainerCallback] or None) – Additional callbacks to invoke. Built-in callbacks (early stopping, checkpoint, progress) are appended automatically based on the other arguments.

Returns:

Losses and metrics for every epoch.

Return type:

TrainerHistory

test(dataset: Dataset | GroundedDataset | BuiltDataset, *, batch_size: int = 1) → list[source]

Evaluate the model on a dataset (no weight updates).

Parameters:

  • dataset – Test data. Raw Dataset objects are built automatically.

  • batch_size (int) – Batch size when building raw datasets. Default 1.

Returns:

Model outputs for every sample.

Return type:

list

class TrainerCallback[source]

Bases: object

Base class for training callbacks.

Override any of the hooks. The trainer calls them in the order they were passed to Trainer.fit().

on_epoch_end(trainer: Trainer, epoch: int, logs: dict[str, Any]) → None[source]

Called after every epoch.

Parameters:

  • trainer (Trainer) – The trainer instance (access trainer.model, etc.).

  • epoch (int) – 0-indexed epoch number that just finished.

  • logs (dict) – Dictionary with keys "train_loss", "val_loss" (if available), "lr", and per-metric keys like "train_accuracy", "val_mae", etc.

on_train_begin(trainer: Trainer) → None[source]

Called once before the first epoch.

on_train_end(trainer: Trainer) → None[source]

Called once after training finishes (or early-stops).

class TrainerHistory(train_losses: list[float] = <factory>, val_losses: list[float] = <factory>, train_metrics: dict[str, list[float]]=<factory>, val_metrics: dict[str, list[float]]=<factory>, learning_rates: list[float] = <factory>, best_epoch: int = 0, best_val_loss: float = inf, stopped_early: bool = False)[source]

Bases: object

Training history collected during a Trainer.fit() run.

train_losses

Mean training loss per epoch.

Type:

list[float]

val_losses

Mean validation loss per epoch (empty if no validation set).

Type:

list[float]

train_metrics

Per-epoch extra metrics on the training set (each key maps to a list of epoch-level means).

Type:

dict[str, list[float]]

val_metrics

Per-epoch extra metrics on the validation set.

Type:

dict[str, list[float]]

learning_rates

Learning rate at each epoch.

Type:

list[float]

best_epoch

Epoch (0-indexed) that achieved the lowest validation loss.

Type:

int

best_val_loss

Lowest validation loss observed.

Type:

float

stopped_early

True if early stopping fired.

Type:

bool

best_epoch: int = 0
best_val_loss: float = inf
learning_rates: list[float]
stopped_early: bool = False
train_losses: list[float]
train_metrics: dict[str, list[float]]
val_losses: list[float]
val_metrics: dict[str, list[float]]
compute_metrics(targets: list, outputs: list, names: Sequence[str | Metric]) → dict[str, float][source]

Compute named metrics over a batch of (target, output) pairs.

Each metric receives the full batch and returns a single float.

Parameters:

  • targets (list) – Per-sample target values (floats, lists, or 2D lists).

  • outputs (list) – Per-sample output values (same shapes as targets).

  • names (Sequence[str or Metric]) – Metric names to compute, e.g. ["accuracy"] or [Metric.MAE, Metric.R2].

Returns:

Mapping from metric name to its value across the batch.

Return type:

dict[str, float]