Source code for pyaicad.learning

"""Training the networks that guide the search.

A training set is a list of problems: one problem per training example. :class:`Dataset` splits a
list into training and validation sets; :func:`fit` trains a network on it with a named
recipe. The problems you evaluate on are kept apart by you and never given to :func:`fit`; the trained network is a :class:`Checkpoint` that the neural searches (:class:`pyaicad.NeuralPriorSearch`,
:class:`pyaicad.NeuralPriorBPSearch`) solve with.

Each network has its own restrictions on the problems it can be trained on and used with; they are
documented with the network in the Rust crate (``neural::consformer`` for ConsFormer), not here.

>>> import pyaicad as ac
>>> from pyaicad import learning
>>> ckpt = learning.fit(train_problems, "consformer-mdd", checkpoint_dir="ckpt", epochs=50)  # doctest: +SKIP
>>> results = ac.local_search(test_problems, ac.NeuralPriorBPSearch(ckpt))  # doctest: +SKIP
"""

from __future__ import annotations

import dataclasses
import json
import math
import os
import random
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union

from . import _core
from ._runtime import require_learning, set_seed
from .errors import CheckpointError
from .mdd import _merge_heuristic, _ordering
from .model import Model

__all__ = [
    "Dataset",
    "Network",
    "Adam",
    "AdamW",
    "SGD",
    "Optimiser",
    "Training",
    "Recipe",
    "RECIPES",
    "fit",
    "load",
    "Checkpoint",
]

PathLike = Union[str, "os.PathLike[str]"]


# --------------------------------------------------------------------------------------------
# Datasets
# --------------------------------------------------------------------------------------------


[docs] @dataclass(frozen=True) class Dataset: """The problems a network is trained on: training and validation problems. The validation set is used during training to keep the best network. There is no test set on purpose: evaluating on problems that training could have seen proves nothing, so the problems you evaluate on are yours to keep apart and never pass to :func:`fit`. """ train: Tuple[Model, ...] validation: Tuple[Model, ...] def __post_init__(self) -> None: for name in ("train", "validation"): object.__setattr__(self, name, tuple(getattr(self, name))) if not self.train: raise ValueError("a dataset needs at least one training problem") if not self.validation: raise ValueError("a dataset needs at least one validation problem")
[docs] @classmethod def split( cls, problems: Iterable[Model], validation_fraction: float = 0.2, *, seed: Optional[int] = None, ) -> "Dataset": """Splits ``problems`` at random into training and validation sets. ``validation_fraction`` is the share of the problems kept for validation, strictly between 0 and 1; both sets get at least one problem. The same ``seed`` gives the same split. """ items = list(problems) if not 0.0 < validation_fraction < 1.0: raise ValueError(f"validation_fraction must be strictly between 0 and 1, got {validation_fraction}") if len(items) < 2: raise ValueError("splitting needs at least two problems, one to train on and one to validate on") random.Random(seed).shuffle(items) n_val = min(len(items) - 1, max(1, round(len(items) * validation_fraction))) return cls(train=tuple(items[n_val:]), validation=tuple(items[:n_val]))
def __iter__(self): # pragma: no cover - convenience yield from (*self.train, *self.validation) def __len__(self) -> int: return len(self.train) + len(self.validation)
# -------------------------------------------------------------------------------------------- # Recipes # -------------------------------------------------------------------------------------------- _DESTROY = { "random": _core.PyDestroyKind.Random, "worst": _core.PyDestroyKind.Worst, "related": _core.PyDestroyKind.Related, }
[docs] @dataclass(frozen=True) class Network: """The architecture of a ConsFormer network. ``domain_size`` is the number of values the network can predict: values ``0`` to ``domain_size - 1``. ``"auto"`` takes the smallest size covering the problems it is trained on, which requires non-negative values. """ domain_size: Union[int, str] = "auto" embedding_size: int = 128 hidden_size: int = 128 num_heads: int = 1 expand_size: int = 128 num_layers: int = 1 dropout: float = 0.0 bias: bool = True positional_encoding_dimensions: int = 0 mask_fraction: float = 0.5 tau: float = 0.1 learned_attention_mask: bool = False
def _check_optimiser( lr: float, grad_clip_norm: Optional[float], grad_clip_value: Optional[float] ) -> None: if not lr > 0: raise ValueError(f"lr must be positive, got {lr!r}") if grad_clip_norm is not None and grad_clip_value is not None: raise ValueError("set grad_clip_norm or grad_clip_value, not both") for name, value in (("grad_clip_norm", grad_clip_norm), ("grad_clip_value", grad_clip_value)): if value is not None and not value > 0: raise ValueError(f"{name} must be positive, got {value!r}") def _check_betas(beta_1: float, beta_2: float, epsilon: float) -> None: if not (0 <= beta_1 < 1 and 0 <= beta_2 < 1): raise ValueError(f"beta_1 and beta_2 must be in [0, 1), got {beta_1!r} and {beta_2!r}") if not epsilon > 0: raise ValueError(f"epsilon must be positive, got {epsilon!r}")
[docs] @dataclass(frozen=True) class Adam: """The Adam optimiser. ``weight_decay`` is an L2 penalty (``None`` for none). ``grad_clip_norm`` clips the L2 norm of each gradient tensor and ``grad_clip_value`` clips each element of the gradient; set at most one. """ lr: float = 3e-4 beta_1: float = 0.9 beta_2: float = 0.999 epsilon: float = 1e-5 amsgrad: bool = False weight_decay: Optional[float] = None grad_clip_norm: Optional[float] = None grad_clip_value: Optional[float] = None def __post_init__(self) -> None: _check_optimiser(self.lr, self.grad_clip_norm, self.grad_clip_value) _check_betas(self.beta_1, self.beta_2, self.epsilon) if self.weight_decay is not None and self.weight_decay < 0: raise ValueError(f"weight_decay must not be negative, got {self.weight_decay!r}")
[docs] @dataclass(frozen=True) class AdamW: """Adam with a decoupled weight decay, which is always applied (``0`` for none). ``grad_clip_norm`` clips the L2 norm of each gradient tensor and ``grad_clip_value`` clips each element of the gradient; set at most one. """ lr: float = 3e-4 beta_1: float = 0.9 beta_2: float = 0.999 epsilon: float = 1e-5 amsgrad: bool = False weight_decay: float = 1e-4 grad_clip_norm: Optional[float] = None grad_clip_value: Optional[float] = None def __post_init__(self) -> None: _check_optimiser(self.lr, self.grad_clip_norm, self.grad_clip_value) _check_betas(self.beta_1, self.beta_2, self.epsilon) if self.weight_decay < 0: raise ValueError(f"weight_decay must not be negative, got {self.weight_decay!r}")
[docs] @dataclass(frozen=True) class SGD: """Stochastic gradient descent, with momentum if ``momentum`` is set. ``dampening`` and ``nesterov`` only apply with a momentum. ``weight_decay`` is an L2 penalty (``None`` for none). ``grad_clip_norm`` clips the L2 norm of each gradient tensor and ``grad_clip_value`` clips each element of the gradient; set at most one. """ lr: float = 1e-2 momentum: Optional[float] = None dampening: float = 0.0 nesterov: bool = False weight_decay: Optional[float] = None grad_clip_norm: Optional[float] = None grad_clip_value: Optional[float] = None def __post_init__(self) -> None: _check_optimiser(self.lr, self.grad_clip_norm, self.grad_clip_value) if self.momentum is None and (self.nesterov or self.dampening != 0): raise ValueError("dampening and nesterov need a momentum") if self.momentum is not None and not 0 <= self.momentum < 1: raise ValueError(f"momentum must be in [0, 1), got {self.momentum!r}") if self.weight_decay is not None and self.weight_decay < 0: raise ValueError(f"weight_decay must not be negative, got {self.weight_decay!r}")
Optimiser = Union[Adam, AdamW, SGD] """An optimiser with its settings: one of :class:`Adam`, :class:`AdamW` and :class:`SGD`."""
[docs] @dataclass(frozen=True) class Training: """How the network is optimised. ``optimiser`` is the optimiser with its learning rate and settings (Adam by default). The network is evaluated on the validation set every ``validation_interval`` epochs, and the best one so far is kept; so ``validation_interval`` must not exceed ``epochs``. ``initial_weights`` is the checkpoint directory of an earlier run: its weights initialise the network before the first epoch, to continue or fine-tune that run. The network settings must be the ones the weights were trained with. By default the network starts from scratch. """ optimiser: Optimiser = field(default_factory=Adam) epochs: int = 10 batch_size: int = 32 validation_interval: int = 10 early_stopping_patience: Optional[int] = None early_stopping_min_delta: float = 1e-4 initial_weights: Optional[PathLike] = None destroy: str = "random" # which variables are re-predicted in a training step; "consformer" only def __post_init__(self) -> None: if not isinstance(self.optimiser, (Adam, AdamW, SGD)): raise TypeError(f"optimiser must be Adam, AdamW or SGD, got {self.optimiser!r}") if self.destroy not in _DESTROY: raise ValueError(f"destroy must be one of {sorted(_DESTROY)}, got {self.destroy!r}")
[docs] @dataclass(frozen=True) class Recipe: """A way of training a network: the loss, the architecture and the optimiser settings. Use one of the named recipes in :data:`RECIPES`, optionally with changes: >>> Recipe.named("consformer-mdd").replace(epochs=50, lr=1e-3).training.epochs 50 >>> Recipe.named("consformer").replace(optimiser=SGD(momentum=0.9)).training.optimiser.lr 0.01 ``replace`` takes the name of any setting of the network, the training, or the recipe itself, and refuses names it does not know. With the ``"mdd"`` loss, ``bp_rounds`` is the number of rounds of belief propagation (the one of :class:`pyaicad.NeuralPriorBPSearch`) that label the diagram of each constraint before its weighted model count is taken: the network's probabilities are the prior of each variable, and the diagram of a constraint is labelled with that prior tilted by what the *other* constraints say about the variable. The loss then sees the other constraints, and scores the weights that the search labels its diagrams with. ``0``, the default, labels the diagrams with the network's probabilities as they are; the gradient is taken with respect to them, the messages of belief propagation being constants. The setting has no effect on the ``"classical"`` loss. ``gumbel_scale`` multiplies the Gumbel noise that is added to the network's logits before their softmax turns them into the probabilities the ``"mdd"`` loss scores. ``1.0``, the default, is the Gumbel-softmax relaxation of ConsFormer; ``0.0`` adds no noise, so the loss is the exact expectation under the plain softmax of the logits, and is deterministic (so is the validation loss that selects the best network). It applies to the whole loss, belief propagation included, and has no effect on the ``"classical"`` loss. >>> Recipe.named("consformer-mdd").bp_rounds 0 >>> Recipe.named("consformer-mdd").replace(bp_rounds=1).bp_rounds 1 >>> Recipe.named("consformer-mdd").replace(bp_rounds=5).bp_rounds 5 >>> Recipe.named("consformer-mdd").gumbel_scale 1.0 >>> Recipe.named("consformer-mdd").replace(gumbel_scale=0.0).gumbel_scale 0.0 """ name: str loss: str # "classical": hand-written penalty per constraint type; "mdd": exact MDD model count network: Network = field(default_factory=Network) training: Training = field(default_factory=Training) order: Union[str, Tuple[int, ...]] = "auto" # how constraint MDDs are ordered ("mdd" loss) merge: str = "state_similarity" # and merged ("mdd" loss); has no effect on an exact compile bp_rounds: int = 0 # "mdd" loss: rounds of belief propagation that label the diagrams gumbel_scale: float = 1.0 # "mdd" loss: scale of the Gumbel noise added to the logits (0: none) def __post_init__(self) -> None: if self.loss not in ("classical", "mdd"): raise ValueError(f"loss must be 'classical' or 'mdd', got {self.loss!r}") if isinstance(self.bp_rounds, bool) or not isinstance(self.bp_rounds, int) or self.bp_rounds < 0: raise ValueError(f"bp_rounds must be a non-negative integer, got {self.bp_rounds!r}") if ( isinstance(self.gumbel_scale, bool) or not isinstance(self.gumbel_scale, (int, float)) or not math.isfinite(self.gumbel_scale) or self.gumbel_scale < 0 ): raise ValueError(f"gumbel_scale must be a non-negative number, got {self.gumbel_scale!r}")
[docs] @staticmethod def named(name: str) -> "Recipe": """One of the recipes of :data:`RECIPES`.""" try: return RECIPES[name] except KeyError: raise ValueError(f"unknown recipe {name!r}; choose from {sorted(RECIPES)}") from None
[docs] def replace(self, **changes: Any) -> "Recipe": """A copy with some settings changed, by name. A setting of the optimiser (``lr``, ``momentum``, ...) changes the optimiser the recipe has once ``optimiser=`` is applied, if given. """ own = {f.name for f in dataclasses.fields(self)} - {"network", "training"} net = {f.name for f in dataclasses.fields(Network)} train = {f.name for f in dataclasses.fields(Training)} top: Dict[str, Any] = {} n: Dict[str, Any] = {} t: Dict[str, Any] = {} o: Dict[str, Any] = {} optimiser = changes.get("optimiser", self.training.optimiser) opt = ( {f.name for f in dataclasses.fields(optimiser)} if dataclasses.is_dataclass(optimiser) else set() ) for key, value in changes.items(): if key in own: top[key] = value elif key in net: n[key] = value elif key in train: t[key] = value elif key in opt: o[key] = value else: known = sorted(own | net | train | opt) raise TypeError(f"unknown setting {key!r}; the settings are {known}") training = dataclasses.replace(self.training, **t) if o: training = dataclasses.replace( training, optimiser=dataclasses.replace(training.optimiser, **o) ) return dataclasses.replace( self, network=dataclasses.replace(self.network, **n), training=training, **top, )
RECIPES: Dict[str, Recipe] = { "consformer": Recipe("consformer", loss="classical"), "consformer-mdd": Recipe("consformer-mdd", loss="mdd"), } """The named recipes. ``"consformer"`` trains with a hand-written penalty per constraint type; ``"consformer-mdd"`` trains against the exact weighted model count of each constraint's MDD.""" # -------------------------------------------------------------------------------------------- # Checkpoints # --------------------------------------------------------------------------------------------
[docs] @dataclass(frozen=True) class Checkpoint: """A trained network on disk: a directory holding ``config.json`` and ``weights.mpk``.""" path: Path config: Dict[str, Any] @property def domain_size(self) -> int: """The number of values the network predicts.""" return int(self.config["domain_size"])
[docs] @classmethod def load(cls, path: PathLike) -> "Checkpoint": """Opens the checkpoint in directory ``path``, checking that it is complete.""" directory = Path(path) config_file, weights_file = directory / "config.json", directory / "weights.mpk" if not config_file.is_file() or not weights_file.is_file(): raise CheckpointError( f"{directory} is not a checkpoint: it needs config.json and weights.mpk" ) try: config = json.loads(config_file.read_text()) except ValueError as e: raise CheckpointError(f"{config_file} is not valid JSON: {e}") from None if "domain_size" not in config: raise CheckpointError(f"{config_file} has no domain_size") return cls(directory, config)
def __fspath__(self) -> str: return str(self.path)
[docs] def load(path: PathLike) -> Checkpoint: """Opens a checkpoint written by :func:`fit`. See :meth:`Checkpoint.load`.""" return Checkpoint.load(path)
# -------------------------------------------------------------------------------------------- # Training # -------------------------------------------------------------------------------------------- def _domain_size(models: Iterable[Model]) -> int: largest = 0 for model in models: for var in model.variables: for value in model.domain(var): if value < 0: raise ValueError( "domain_size='auto' needs non-negative values; " "shift the values or give domain_size" ) largest = max(largest, value) return largest + 1 def _native_network(net: Network, domain_size: int) -> Any: return _core.PyConsFormerConfig( domain_size=domain_size, embedding_size=net.embedding_size, hidden_size=net.hidden_size, num_heads=net.num_heads, expand_size=net.expand_size, mask_fraction=net.mask_fraction, tau=net.tau, num_layers=net.num_layers, drop_out=net.dropout, bias=net.bias, positional_encoding_dimensions=net.positional_encoding_dimensions, learn_attention_mask=net.learned_attention_mask, ) def _native_optimiser(o: Optimiser) -> Any: if isinstance(o, Adam): return _core.PyOptimiser.Adam( lr=o.lr, beta_1=o.beta_1, beta_2=o.beta_2, epsilon=o.epsilon, amsgrad=o.amsgrad, weight_decay=o.weight_decay, grad_clip_norm=o.grad_clip_norm, grad_clip_value=o.grad_clip_value, ) if isinstance(o, AdamW): return _core.PyOptimiser.AdamW( lr=o.lr, beta_1=o.beta_1, beta_2=o.beta_2, epsilon=o.epsilon, amsgrad=o.amsgrad, weight_decay=o.weight_decay, grad_clip_norm=o.grad_clip_norm, grad_clip_value=o.grad_clip_value, ) if isinstance(o, SGD): return _core.PyOptimiser.Sgd( lr=o.lr, momentum=o.momentum, dampening=o.dampening, nesterov=o.nesterov, weight_decay=o.weight_decay, grad_clip_norm=o.grad_clip_norm, grad_clip_value=o.grad_clip_value, ) raise TypeError(f"optimiser must be Adam, AdamW or SGD, got {o!r}") def _native_training(t: Training) -> Any: return _core.PyTrainingConfig( optimiser=_native_optimiser(t.optimiser), num_epochs=t.epochs, batch_size=t.batch_size, validation_interval=t.validation_interval, early_stopping_patience=t.early_stopping_patience, early_stopping_min_delta=t.early_stopping_min_delta, destroy_kind=_DESTROY[t.destroy], initial_weights=None if t.initial_weights is None else str(Path(t.initial_weights)), )
[docs] def fit( data: Union[Dataset, Sequence[Model]], recipe: Union[str, Recipe] = "consformer-mdd", *, checkpoint_dir: PathLike, seed: Optional[int] = None, **settings: Any, ) -> Checkpoint: """Trains a network and keeps the best one found in ``checkpoint_dir``. The network with the lowest loss on the validation set is written to ``checkpoint_dir`` during training, so an interrupted run still leaves a usable one. Args: data: A :class:`Dataset`, or a list of problems, which is split 80/20 into training and validation sets (use :meth:`Dataset.split` for another share). Never include the problems you evaluate on. recipe: The name of a recipe in :data:`RECIPES`, or a :class:`Recipe`. checkpoint_dir: Where the network is written. Created if missing. seed: Seeds the library's randomness (see :func:`pyaicad.set_seed`) before training, and the split of a plain list. **settings: Changes to the recipe, by name, as in :meth:`Recipe.replace`: ``fit(data, "consformer", checkpoint_dir="ckpt", epochs=50, embedding_size=64)``. Returns: The :class:`Checkpoint` holding the best network. """ require_learning("training a network") recipe = Recipe.named(recipe) if isinstance(recipe, str) else recipe if settings: recipe = recipe.replace(**settings) if not isinstance(data, Dataset): data = Dataset.split(data, seed=seed) t = recipe.training if t.validation_interval < 1 or t.epochs < 1: raise ValueError("epochs and validation_interval must be at least 1") if t.validation_interval > t.epochs: raise ValueError( f"validation_interval ({t.validation_interval}) is larger than epochs ({t.epochs}): " "the network would never be validated, so none would be kept" ) domain_size = recipe.network.domain_size if domain_size == "auto": domain_size = _domain_size(data) elif not isinstance(domain_size, int) or domain_size < 1: raise ValueError(f"domain_size must be 'auto' or a positive integer, got {domain_size!r}") if seed is not None: set_seed(seed) directory = Path(checkpoint_dir) network = _native_network(recipe.network, domain_size) training = _native_training(recipe.training) train = [m._native_problem() for m in data.train] validation = [m._native_problem() for m in data.validation] if recipe.loss == "classical": _core.train_consformer(train, network, training, str(directory), validation=validation) else: _core.train_consformer_mdd( train, network, training, str(directory), pyordering=_ordering(recipe.order, data.train[0]), pymerge=_merge_heuristic(recipe.merge), validation=validation, bp_rounds=recipe.bp_rounds, gumbel_scale=float(recipe.gumbel_scale), ) return Checkpoint.load(directory)