mcode-neural 0.5.0__py3-none-any.whl

mcode_neural/model.py

@@ -0,0 +1,2092 @@
+# region  F I L E
+# <copyright file="mcode-neural/src/mcode_neural/model.py" company="MicroCODE Incorporated">Copyright © 2026 MicroCODE, Inc. Troy, MI</copyright><author>Timothy J. McGuire</author>
+# region  M O D U L E
+# region  D O C U M E N T A T I O N
+"""
+Project:  MicroCODE Python Packages
+Customer: Internal + MIT xPRO Course
+@module   'mcode_neural.model'
+@memberof mcode_neural
+@created  October 2026
+@author   Timothy McGuire, MicroCODE, Inc.
+@description >
+MicroCODE Shared Self-Describing Model Library
+
+LICENSE:
+--------
+MIT License: MicroCODE.mcode-neural
+
+Copyright (c) 2026 Timothy McGuire, MicroCODE, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+DESCRIPTION:
+------------
+This module implements every MicroCODE model: the 'Model' base class, with
+its 'kind', the arguments it was built with, its 'Data', its training history,
+and its 'network' list, each a 'Network' of 'Layer's; the 'MODEL_KINDS' each
+'kind' selects; our single neuron models, 'NeuronModel' and its regressor and
+classifiers, in NumPy; our multi-layer models, 'FeedforwardModel' and its
+classification, binary classification, and regression models, and
+'AutoencoderModel', in PyTorch; a network built elsewhere, e.g. VGG11,
+wrapped as one of them; saving and loading a model with all of it;
+the device a model trains on, its GPU memory capped; and freezing, unfreezing,
+and replacing the output layer of any network, for transfer learning.
+
+
+REFERENCES:
+-----------
+1. MIT xPRO Course: AI and Deep Learning: Neural Network Applications
+
+2. PyTorch -- Serialization semantics (torch.save, torch.load with weights_only)
+   https://pytorch.org/docs/stable/notes/serialization.html
+
+3. PyTorch -- torch.nn (Module, Sequential)
+   https://pytorch.org/docs/stable/nn.html
+
+4. PyTorch -- torch.cuda.set_per_process_memory_fraction (the GPU memory cap)
+   https://pytorch.org/docs/stable/generated/torch.cuda.set_per_process_memory_fraction.html
+"""
+
+# endregion
+
+# region  I M P O R T S
+
+import inspect
+import operator
+
+import re
+
+import math
+
+import numbers
+from contextlib import contextmanager
+from datetime import datetime
+from importlib.metadata import version
+
+from typing import ClassVar
+
+import numpy as np
+import torch
+
+from torch import nn
+
+from .data import DATA_KINDS, Data
+
+from .layer import (
+    _check_conv,
+    _check_dropout,
+    _check_sizes,
+    _check_width,
+    _conv_arguments,
+    _conv_stack,
+    _deconv_stack,
+    _sample_shape,
+    _scored,
+    _shaped,
+    _stack,
+    _stage_shapes,
+)
+
+from .network import NETWORK_KINDS
+from .neuron import NEURON_KINDS, NON_ZERO
+
+from .neuron import NeuronOptimizer
+
+# endregion
+
+# region  C O N S T A N T S
+
+# what every model of one kind shares, keyed by the model's 'kind':
+#   metrics: the curves its trainer keeps per phase; "acc" is the share of answers it gets right
+#   best / is_better: the val metric that picks the best epoch, and its strict comparison
+#   has_classes: the answers allowed to "does its data name its classes, {label: (color, name)}?"
+# a kind whose 'is_better' always holds keeps its last epoch; a metric name holds no '_', since
+# 'show_training_curves()' splits each curve's key at its last '_', e.g. "dloss" and "gloss"
+MODEL_KINDS = {
+    'classification': {
+        'metrics': ('loss', 'acc'),
+        'best': 'acc',
+        'is_better': operator.gt,
+        'has_classes': (True,),
+    },
+    'regression': {
+        'metrics': ('loss',),
+        'best': 'loss',
+        'is_better': operator.lt,
+        'has_classes': (False,),
+    },
+    'autoencoder': {
+        'metrics': ('loss',),
+        'best': 'loss',
+        'is_better': operator.lt,
+        'has_classes': (True, False),
+    },
+}
+
+# the attributes 'Model' sets on every model, apart from each family's learned state
+MODEL_ATTRIBUTES = ('_data', 'history', '_network')
+
+# the versions every "create" event records, read once, as plain strings a saved model can keep
+MODEL_VERSIONS = {
+    'mcode_neural': version('mcode-neural'),
+    'torch': str(torch.__version__),
+}
+
+SEED_LIMIT = 2**32 - 1
+
+# the key under which a step's hyperparams keep the settings it was not given; 'show_model_history()' marks them
+HISTORY_DEFAULTS = 'defaults'
+
+# the neuron kinds an autoencoder's decoder output may take, its 'output_activation':
+#   linear: standardized rows, or images from Normalize()
+#   sigmoid: images from ToTensor() alone, or min-max scaled rows
+#   tanh: images from Normalize([0.5], [0.5]), as the course loads MNIST
+AUTOENCODER_OUTPUTS = ('linear', 'sigmoid', 'tanh')
+
+# the share of a GPU's memory 'model_device()' lets this process use, the rest left to the desktop
+DEVICE_FRACTION = 0.75
+
+# the samples a model scores at once before it has trained; after, its latest training's 'batch_size'
+SCORE_BATCH_SIZE = 64
+
+# the history events that change a Model's network, replayed in order by 'model_load()' before its weights load
+MODEL_CHANGES = {
+    'replace_output': lambda model, hyperparams: _replace_output(
+        model, hyperparams['out_features']
+    ),
+    'freeze': lambda model, hyperparams: _set_trainable(
+        model, hyperparams['parts'], False
+    ),
+    'unfreeze': lambda model, hyperparams: _set_trainable(
+        model, hyperparams['parts'], True
+    ),
+}
+
+# endregion
+
+# region  C L A S S E S
+
+
+class Model:
+    """
+    A self-describing model, the parent of our single neuron and multi-layer models: its kind,
+    the arguments it was built with, the data it reads, and how it was trained.
+
+    Subclasses set 'kind' ("classification", "regression", or "autoencoder", a key of
+    'MODEL_KINDS') and 'hidden_size' (the width of each hidden layer, or a conv stage's
+    (channels, height, width); () for none), declare their networks in 'sources' and
+    'network_kind', build 'model.network' from that 'NETWORK_KINDS' row, and
+    implement 'weights()', 'load_weights()', 'train_step()', 'score_step()', and 'classify()',
+    'regress()', or an autoencoder's 'encode()', 'decode()', and 'reconstruct()'. A class that sets no 'kind',
+    e.g. 'NeuronModel' or 'FeedforwardModel', is abstract: building one raises a TypeError.
+
+    Args:
+        arguments:  the subclass constructor's arguments by name, with its 'seed' when it builds
+                    its own weights, e.g. {"in_features": 5, "seed": None}, so 'model_load()'
+                    can build the model again;
+                    in the order 'show_model_history()' lists them. The "create" event keeps
+                    those equal to the default the constructor's signature names under
+                    'HISTORY_DEFAULTS', e.g. {"in_features": 5, "defaults": {"seed": None}}.
+
+    Note:
+        The attribute is named 'kind', not 'type', because 'type' would shadow 'nn.Module.type()', which casts a
+        network's parameters.
+        'history' is the one record of how the model was made: a list of events, oldest first,
+        each {"event", "time", "hyperparams", "results"}. "create" is recorded here, "data" when
+        'model.data' is set, "train" by 'train_model()', and "load" by
+        'model_load()'; 'model_test()' keeps its metrics in the latest "train" event. 'arguments',
+        'curves', and 'best_epoch' are read-only views of it: 'curves' is {} and 'best_epoch' is
+        None until the model is trained.
+    """
+
+    # every model class by name, so 'model_load()' can build a saved model again
+    CLASSES: ClassVar[dict] = {}
+    # whether its networks are given to it rather than built from its arguments
+    is_external = False
+    # the keys of the optimizer dict its 'train_step()' takes; () when it takes one optimizer
+    optimizer_keys = ()
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        Model.CLASSES[cls.__name__] = cls
+
+    def __init__(self, arguments):
+        if not hasattr(type(self), 'kind'):
+            subclasses = [cls.__name__ for cls in type(self).__subclasses__()]
+            raise TypeError(
+                f"'{type(self).__name__}' is abstract; build one of its subclasses, e.g. {subclasses}"
+            )
+        # a network's nn.Module.__init__ must run before its first attribute is set
+        super().__init__()
+        if 'seed' in arguments:
+            seed = arguments['seed']
+            if seed is not None and (
+                isinstance(seed, bool)
+                or not isinstance(seed, numbers.Integral)
+                or not 0 <= seed <= SEED_LIMIT
+            ):
+                raise ValueError(
+                    f"'seed' must be a whole number from 0 to {SEED_LIMIT}, or None, got {seed!r}"
+                )
+        self.history = []
+        # the arguments given, then those left at the default the subclass's signature names
+        signature = inspect.signature(type(self)).parameters
+        given = {
+            key: value
+            for key, value in arguments.items()
+            if value != signature[key].default
+        }
+        hyperparams = {
+            **given,
+            HISTORY_DEFAULTS: {
+                key: value for key, value in arguments.items() if key not in given
+            },
+        }
+        self._record('create', hyperparams, MODEL_VERSIONS)
+        self._data = None
+
+    @property
+    def arguments(self):
+        """The arguments the model was built with, given and default, by name, from its "create" event; read-only."""
+        return _arguments(self.history[0]['hyperparams'])
+
+    @property
+    def curves(self):
+        """The latest training's {f"{phase}_{metric}": [one value per epoch]}; {} before any training."""
+        train = _latest_train(self)
+        return {} if train is None else train['results']['curves']
+
+    @property
+    def best_epoch(self):
+        """The epoch whose weights the latest training kept; None before any training."""
+        train = _latest_train(self)
+        return None if train is None else train['results']['best_epoch']
+
+    @property
+    def in_features(self):
+        """The number of values in one sample, its 'in_features' argument; read-only."""
+        return self.arguments['in_features']
+
+    @property
+    def data(self):
+        """The model's 'Data', set once, e.g. 'model.data = data_frame_split(...)'."""
+        # a ValueError, as an AttributeError here would be replaced by nn.Module.__getattr__'s own
+        if self._data is None:
+            raise ValueError(
+                "'model' has no data; load it first, e.g. 'model.data = data_frame_split(...)'"
+            )
+        return self._data
+
+    @data.setter
+    def data(self, data):
+        if not isinstance(data, Data):
+            raise TypeError(
+                f"'model.data' must be a Data, e.g. from 'data_frame_split()', got {type(data).__name__}"
+            )
+        # a classifier's views name its classes; a regressor has none to name; an autoencoder may
+        has_classes = data.classes is not None
+        if has_classes not in MODEL_KINDS[self.kind]['has_classes']:
+            needs = "takes no 'classes' (None)" if has_classes else "needs 'classes'"
+            raise ValueError(
+                f"'model' is {_article(self.kind)} model, so its data {needs}"
+            )
+        in_features = self.in_features
+        if DATA_KINDS[data.kind]['has_features'] and len(data.feature) != in_features:
+            raise ValueError(
+                f"'model.data' names {len(data.feature)} features; 'model' reads {in_features}"
+            )
+        self._data = data
+        if self.history[-1]['event'] == 'data':
+            self.history.pop()
+        samples = {phase: len(dataset) for phase, dataset in data.datasets.items()}
+        self._record('data', data.split, samples)
+
+    def _record(self, event, hyperparams, results):
+        """
+        Appends one event to 'history', stamped with the local time, its values plain for 'model_save()'.
+
+        Args:
+            event:          the step, "create", "data", "train", or "load".
+            hyperparams:    what the step was given, {name: value}; None when not recorded.
+            results:        what the step produced, {name: value}; None when not recorded.
+        """
+        time = datetime.now().astimezone().isoformat(sep=' ', timespec='seconds')
+        self.history.append(
+            _event(
+                event,
+                time,
+                _plain(hyperparams, 'hyperparams'),
+                _plain(results, 'results'),
+            )
+        )
+
+    @property
+    def network(self):
+        """The model's Networks, in the order its 'sources' lists them, e.g. 'model.network[1].layer[0]'; read-only."""
+        return self._network
+
+    @property
+    def layer(self):
+        """
+        The Layers of a model of one network, e.g. 'model.layer[2].neuron[5]'; read-only.
+
+        Raises a ValueError on a model of several networks, whose Layers are read from
+        'model.network[k].layer'; a ValueError, as nn.Module hides an AttributeError raised here.
+        """
+        if len(self._network) != 1:
+            raise ValueError(
+                f"'model.layer' reads a Model of one network; {type(self).__name__} has {len(self._network)}:"
+                " read 'model.network[k].layer[i]'"
+            )
+        return self._network[0].layer
+
+    def weights(self):
+        """Returns a copy of the model's learned parameters, as 'load_weights()' takes them."""
+        raise NotImplementedError('weights method should be implemented by subclass')
+
+    def load_weights(self, weights):
+        """Sets the model's learned parameters from 'weights()'."""
+        raise NotImplementedError(
+            'load_weights method should be implemented by subclass'
+        )
+
+    def classify(self, X):
+        """Returns a classifier's (columns, probabilities) for every row of X."""
+        raise NotImplementedError('classify method should be implemented by subclass')
+
+    def regress(self, X):
+        """Returns a regressor's predicted values for every row of X."""
+        raise NotImplementedError('regress method should be implemented by subclass')
+
+    def train_step(self, inputs, labels, optimizer, name):
+        """
+        Trains on one batch: computes its losses, steps its optimizer(s), and returns its metrics.
+
+        Args:
+            inputs:     the batch's samples, as 'data_loaders()' serves them, on the CPU.
+            labels:     the batch's labels, as 'data_loaders()' serves them, on the CPU.
+            optimizer:  what 'train_model()' was given: one optimizer, or a dict keyed by
+                        'optimizer_keys'.
+            name:       the phase as a message names it, e.g. "'model.data' phase 'train'".
+
+        Returns:
+            {metric: total over the batch's samples}, one per metric of its 'MODEL_KINDS'
+            entry, in order: a loss is its batch mean times the batch's size, "acc" a count, so
+            the trainer's average over the phase weighs every sample alike.
+        """
+        raise NotImplementedError('train_step method should be implemented by subclass')
+
+    def score_step(self, inputs, labels, name):
+        """
+        Scores one batch without training, returning its metrics as 'train_step()' does.
+
+        Args:
+            inputs: the batch's samples, as 'train_step()' takes them.
+            labels: the batch's labels, as 'train_step()' takes them.
+            name:   the phase as a message names it, e.g. "'model.data' phase 'val'".
+        """
+        raise NotImplementedError('score_step method should be implemented by subclass')
+
+
+class NeuronModel(Model):
+    """
+    Abstract single neuron, the parent of our regression and classification models.
+
+    Subclasses set 'activation_name' (a key of 'NEURON_KINDS', which applies it and its slope),
+    'kind', and 'label_value', and implement 'loss()' and 'loss_gradient()'; a classifier also
+    implements 'probability()'.
+
+    Args:
+        in_features:    the number of input features, the length of the weight vector 'w'.
+        seed:           seeds the starting weights, a whole number from 0 to 2**32 - 1, so every build with
+                        it starts the same, without changing NumPy's global random stream; None for
+                        unseeded weights, e.g. after the Notebook's own 'np.random.seed()'.
+    """
+
+    # a single neuron is one layer, with no hidden layer before it
+    hidden_size = ()
+    # how its networks are found and read, a key of 'NETWORK_KINDS'
+    network_kind = 'numpy'
+    # each network's name, in the order they run, and what it reads: 'data' or an earlier network
+    sources: ClassVar[dict] = {'neuron': ('data',)}
+
+    def __init__(self, in_features, seed=None):
+        super().__init__({'in_features': in_features, 'seed': seed})
+        # self.w = np.zeros(in_features)
+        # self.w_0 = 0.
+        # Better, we set initial weights to small normally distributed values.
+        with _seeded(seed):
+            self.w = 0.01 * np.random.randn(in_features)
+            self.w_0 = 0.01 * np.random.randn()
+        # add this to divisions to ensure we don't divide by 0
+        self.non_zero_tolerance = NON_ZERO
+        self._network = NETWORK_KINDS[self.network_kind]['networks'](self)
+
+    def forward(self, x):
+        """Returns the activation a for one sample x, caching its 'z' and 'a' for 'gradient()'."""
+        # Calculate and save the pre-activation z
+        self.z = x @ self.w.T + self.w_0
+
+        # Apply the activation function, and return
+        self.a = self.activation(self.z)
+        return self.a
+
+    def activation(self, z):
+        """Returns the activation a of the pre-activation z, as its 'activation_name' row of 'NEURON_KINDS' applies it."""
+        return NEURON_KINDS[self.activation_name]['activation'](z)
+
+    # calculate and save gradient of our output with respect to weights
+    def gradient(self, x):
+        """
+        Caches 'grad_w' and 'grad_w_0', da/dw = slope(a) x and da/dw_0 = slope(a), from 'forward()'s cached 'a'.
+
+        Args:
+            x:  the sample 'forward()' scored, (in_features,), or its batch, (N, in_features),
+                whose 'grad_w' is one row per sample.
+        """
+        slope = NEURON_KINDS[self.activation_name]['slope'](self.a)
+        self.grad_w = np.asarray(slope)[..., None] * x
+        self.grad_w_0 = slope
+
+    # update weights based on gradients and learning rate
+    def update(self, grad_loss, learning_rate):
+        """
+        Steps 'w' and 'w_0' against dL/da times the cached 'grad_w' and 'grad_w_0', scaled by learning_rate.
+
+        Args:
+            grad_loss:      dL/da of the sample 'gradient()' cached, or of each sample of its batch, (N,).
+            learning_rate:  the step size.
+
+        Note:
+            A batch steps by the mean of its samples' updates; the mean of one sample is that
+            sample's update exactly, so a batch of one is the course's per-sample loop.
+        """
+        grad_loss = np.reshape(grad_loss, (-1, 1))
+        grad_w = np.reshape(self.grad_w, (len(grad_loss), -1))
+        self.w -= np.mean(grad_loss * grad_w, axis=0) * learning_rate
+        self.w_0 -= np.mean(grad_loss[:, 0] * self.grad_w_0) * learning_rate
+
+    def train_step(self, inputs, labels, optimizer, name):
+        """
+        Trains on one batch, as 'Model.train_step()': forward, gradient, then 'optimizer.step()'.
+
+        Args:
+            inputs:     the batch's samples, (N, in_features), as 'data_loaders()' serves them.
+            labels:     the batch's labels, (N,), each one of its 'label_value'.
+            optimizer:  a NeuronOptimizer, which holds the learning rate.
+            name:       the phase as a message names it, e.g. "'model.data' phase 'train'".
+
+        Returns:
+            {"loss": total} and, for a classifier, "acc": the count it gets right, each scored
+            before the batch's update, as the course's loop scores each sample.
+        """
+        if not isinstance(optimizer, NeuronOptimizer):
+            raise TypeError(
+                f"'optimizer' must be a NeuronOptimizer for a {type(self).__name__},"
+                f" e.g. 'NeuronOptimizer(lr=0.01)', got {type(optimizer).__name__}"
+            )
+        X, Y = self._batch(inputs, labels, name)
+        a = self.forward(X)
+        totals = self._totals(a, Y)
+        self.gradient(X)
+        optimizer.step(self, self.loss_gradient(a, Y))
+        return totals
+
+    def score_step(self, inputs, labels, name):
+        """Scores one batch without training, as 'Model.score_step()', leaving the cached 'z' and 'a' as they were."""
+        X, Y = self._batch(inputs, labels, name)
+        return self._totals(self.outputs(X), Y)
+
+    def _batch(self, inputs, labels, name):
+        """
+        Returns a batch as NumPy (X, Y), raising a ValueError naming the phase unless each sample has one known label.
+
+        Args:
+            inputs: the batch's samples, a tensor.
+            labels: the batch's labels, a tensor.
+            name:   the phase as a message names it.
+        """
+        X, Y = inputs.numpy(), labels.numpy()
+        # a single neuron has one output, so one label per sample
+        if Y.ndim != 1:
+            raise ValueError(
+                f'{name} has labels of shape {Y.shape}; a single neuron needs one label per sample'
+            )
+        if self.label_value is not None:
+            unknown = sorted(set(np.unique(Y).tolist()) - set(self.label_value))
+            if unknown:
+                raise ValueError(
+                    f'{name} holds labels {unknown};'
+                    f' a {type(self).__name__} takes {list(self.label_value)}'
+                )
+        return X, Y
+
+    def _totals(self, a, Y):
+        """Returns the batch's {"loss": total} and, for a classifier, its "acc" count, from its activations a."""
+        totals = {'loss': float(self.loss(a, Y).sum())}
+        if 'acc' in MODEL_KINDS[self.kind]['metrics']:
+            # the prediction's column is the position of its label in 'label_value'
+            predicted = np.asarray(self.label_value)[(a > self.threshold).astype(int)]
+            totals['acc'] = float((predicted == Y).sum())
+        return totals
+
+    @property
+    def threshold(self):
+        """The activation at the decision boundary z = 0; a classifier predicts its higher class above it."""
+        return self.activation(0.0)
+
+    def outputs(self, X):
+        """
+        Returns the activation a for every row of X, leaving 'z', 'a', 'grad_w', and 'grad_w_0' as they were.
+
+        Args:
+            X:  the input samples, a NumPy array of shape (N, in_features).
+        """
+        return self.activation(X @ self.w + self.w_0)
+
+    def classify(self, X):
+        """
+        Returns a classifier's predicted column and class probabilities for every row of X.
+
+        Args:
+            X:  the input samples, a NumPy array of shape (N, in_features).
+
+        Returns:
+            (columns, probabilities): (N,) int64 columns, 1 where a is above 'threshold', else 0;
+            (N, 2) probabilities, the lower class first, as 'predict_classes()' returns them.
+        """
+        a = self.outputs(X)
+        p = self.probability(a)
+        columns = (a > self.threshold).astype(np.int64)
+        return columns, np.column_stack([1 - p, p])
+
+    def regress(self, X):
+        """Returns a regressor's (N,) predicted values for every row of X, its activation a."""
+        return self.outputs(X)
+
+    def weights(self):
+        """Returns a copy of 'w' and 'w_0', 'w' as a tensor, as 'model_save()' stores it."""
+        return {'w': torch.tensor(self.w), 'w_0': float(self.w_0)}
+
+    def load_weights(self, weights):
+        """Sets 'w' and 'w_0' from 'weights()'."""
+        self.w = weights['w'].numpy().copy()
+        self.w_0 = weights['w_0']
+
+
+class RegressorNeuronModel(NeuronModel):
+    """Single neuron regressor, a linear activation, for any real target."""
+
+    activation_name = 'linear'
+    kind = 'regression'
+    # any real target
+    label_value = None
+
+    def loss(self, a, y):
+        """Squared error, as nn.MSELoss, so a neuron and a network report one loss."""
+        return (a - y) ** 2
+
+    def loss_gradient(self, a, y):
+        """dL/da of the squared error."""
+        return 2 * (a - y)
+
+
+class LogisticClassifierNeuronModel(NeuronModel):
+    """Single neuron logistic classifier, a sigmoid activation, for 0 / 1 labels."""
+
+    activation_name = 'sigmoid'
+    kind = 'classification'
+    label_value = (0, 1)
+
+    def probability(self, a):
+        """The probability of label 1: the sigmoid's a itself."""
+        return a
+
+    def loss(self, a, y):
+        """Binary cross entropy, the negative log likelihood of the 0 / 1 label y."""
+        tolerance = self.non_zero_tolerance
+        return -(y * np.log(a + tolerance) + (1 - y) * np.log(1 - a + tolerance))
+
+    def loss_gradient(self, a, y):
+        """dL/da of the binary cross entropy."""
+        return (a - y) / (a * (1 - a) + self.non_zero_tolerance)
+
+
+class BipolarClassifierNeuronModel(NeuronModel):
+    """
+    Single neuron bipolar classifier, a tanh activation.
+
+    Outputs are in (-1, 1), so it predicts class 1 when a > 0 and expects -1 / +1 labels.
+    """
+
+    activation_name = 'tanh'
+    kind = 'classification'
+    label_value = (-1, 1)
+
+    def probability(self, a):
+        """The probability of label +1: a rescaled from (-1, 1) to (0, 1)."""
+        return (a + 1) / 2
+
+    def loss(self, a, y):
+        """Binary cross entropy of the probability (a + 1) / 2 against the -1 / +1 label y as 0 / 1."""
+        p, t = (a + 1) / 2, (y + 1) / 2
+        tolerance = self.non_zero_tolerance
+        return -(t * np.log(p + tolerance) + (1 - t) * np.log(1 - p + tolerance))
+
+    def loss_gradient(self, a, y):
+        """dL/da of that cross entropy, (a - y) / (1 - a^2); times 'grad_w' it is (a - y) x."""
+        return (a - y) / (1 - a**2 + self.non_zero_tolerance)
+
+
+class _CriterionModel(Model, nn.Module):
+    """
+    What every PyTorch Model trained on one 'criterion' and one optimizer shares: its step.
+
+    Note:
+        A subclass sets 'criterion', the loss class, and overrides '_targets()' when its loss
+        reads other targets than its labels, and '_fitted()' when its outputs must be shaped
+        to them.
+    """
+
+    def train_step(self, inputs, labels, optimizer, name):
+        """
+        Trains on one batch, as 'Model.train_step()': forward, loss, backward, and 'optimizer.step()'.
+
+        Args:
+            inputs:     the batch's samples, as 'data_loaders()' serves them.
+            labels:     the batch's labels, as 'data_loaders()' serves them.
+            optimizer:  a PyTorch optimizer of the model's parameters, e.g. torch.optim.Adam.
+            name:       the phase as a message names it, e.g. "'model.data' phase 'train'".
+
+        Returns:
+            {"loss": the batch mean times its size} and, for a classifier, "acc": the share of
+            each sample's answers it gets right, summed over the batch.
+        """
+        if not isinstance(optimizer, torch.optim.Optimizer):
+            raise TypeError(
+                f"'optimizer' must be a PyTorch optimizer for a {type(self).__name__},"
+                f" e.g. 'torch.optim.Adam(model.parameters())', got {type(optimizer).__name__}"
+            )
+        self.train()
+        optimizer.zero_grad()
+        outputs, targets, loss = self._step(inputs, labels, name)
+        loss.backward()
+        optimizer.step()
+        return self._totals(outputs, targets, loss)
+
+    def score_step(self, inputs, labels, name):
+        """Scores one batch in eval() without gradients, as 'Model.score_step()'."""
+        self.eval()
+        with torch.no_grad():
+            outputs, targets, loss = self._step(inputs, labels, name)
+        return self._totals(outputs, targets, loss)
+
+    def _step(self, inputs, labels, name):
+        """
+        Returns one batch's (outputs, targets, loss), the batch moved to the model's device.
+
+        Args:
+            inputs: the batch's samples.
+            labels: the batch's labels.
+            name:   the phase as a message names it.
+        """
+        device = next(self.parameters()).device
+        # every batch shaped as the network reads it: rows for a Linear network, images for conv stages
+        inputs = _shaped(inputs, self.in_shape, name).to(device)
+        targets = self._targets(inputs, labels.to(device), name)
+        outputs = self._fitted(self(inputs), targets)
+        return outputs, targets, self.criterion()(outputs, targets)
+
+    def _targets(self, inputs, labels, name):
+        """Returns what its loss compares its outputs to: its labels."""
+        return labels
+
+    def _fitted(self, outputs, targets):
+        """Returns its outputs shaped as its loss takes them: as they are."""
+        return outputs
+
+    def _totals(self, outputs, targets, loss):
+        """Returns the batch's {"loss": total} and, for a classifier, its "acc" total."""
+        # each batch's mean times its size, so the phase average weighs every sample alike
+        totals = {'loss': loss.item() * len(targets)}
+        if 'acc' in MODEL_KINDS[self.kind]['metrics']:
+            matches = self.predicted(outputs) == targets
+            totals['acc'] = matches.sum().item() / targets[0].numel()
+        return totals
+
+
+class FeedforwardModel(_CriterionModel):
+    """
+    Multi-layer feedforward network, the parent of our classification and regression networks.
+
+    Hidden 'Linear' layers, each followed by a ReLU (and a Dropout when 'dropout' > 0),
+    then a 'Linear' output layer, all in one 'nn.Sequential', its one Network, named for its
+    purpose in the subclass's 'sources', e.g. 'model.classifier' or 'model.regressor'.
+
+    Args:
+        in_features:    the number of input features, the width of the first layer's input.
+        hidden_size:    the width of each hidden layer, in order, e.g. (64, 32); its length is
+                        the number of hidden layers. () builds a single 'Linear' layer.
+        out_features:   the width of the output layer.
+        dropout:        the probability of zeroing each hidden activation while training, at least 0
+                        and below 1; 0 adds no Dropout layers.
+        seed:           seeds the starting weights, a whole number from 0 to 2**32 - 1, so every build with
+                        it starts the same, without changing torch's global random stream; None for
+                        unseeded weights, e.g. after the Notebook's own 'torch.manual_seed()'.
+        in_shape:       one image's (channels, height, width), e.g. (1, 28, 28), whose product is
+                        'in_features'; given with 'convolution' and only with it.
+        convolution:    the convolution stages before the 'Linear' layers, in order, each a dict of
+                        'CONV_STAGE_KEYS', e.g. ({"channels": 8, "kernel": 3, "pool": 2},): a
+                        Conv2d that keeps the height and width, a ReLU, then a MaxPool2d (none for a
+                        pool of 1). The last stage's maps are flattened into the first 'Linear'
+                        layer. () builds 'Linear' layers only.
+
+    Note:
+        The course's 'SimpleClassifier2Layer' is hidden_size=(h1, h2): two hidden layers,
+        three 'Linear' layers. Every layer is in the course's order, so a course model's
+        'state_dict()' loads into the matching model here by order, its 'layers.N' keys read
+        as 'classifier.N'. Dropout acts only in 'model.train()' mode; 'model.eval()' turns it off,
+        and it follows only the hidden 'Linear' layers. The course's Module 4.1
+        'CNNClassifier' is (784, (64,), 10, in_shape=(1, 28, 28),
+        convolution=({"channels": 8, "kernel": 3, "pool": 2},)).
+
+    Example:
+        >>> model = ClassificationModel(input_size, (64, 64, 64), num_classes, dropout=0.25).to(device)
+        >>> model = ClassificationModel(28 * 28, (64,), 10, in_shape=(1, 28, 28),
+        ...     convolution=({"channels": 8, "kernel": 3, "pool": 2},)).to(device)
+    """
+
+    activation_name = 'relu'
+    # how its networks are found and read, a key of 'NETWORK_KINDS'
+    network_kind = 'torch'
+    # each network's name, in the order they run, and what it reads: 'data' or an earlier network
+    sources: ClassVar[dict]
+
+    def __init__(
+        self,
+        in_features,
+        hidden_size,
+        out_features,
+        dropout=0.0,
+        seed=None,
+        in_shape=None,
+        convolution=(),
+    ):
+        # V A L I D A T E: every width and the dropout rate fail by name before any layer is built
+        _check_width('in_features', in_features)
+        _check_sizes('hidden_size', hidden_size)
+        _check_width('out_features', out_features)
+        _check_dropout(dropout)
+        _check_conv(in_features, in_shape, convolution, is_mirrored=False)
+
+        # A R G U M E N T S: kept as plain numbers, so model_load() reads them back with weights_only
+        conv = _conv_arguments(in_shape, convolution)
+        super().__init__(
+            {
+                'in_features': int(in_features),
+                **conv,
+                'hidden_size': tuple(int(width) for width in hidden_size),
+                'out_features': int(out_features),
+                'dropout': float(dropout),
+                'seed': seed,
+            }
+        )
+
+        # S H A P E S: kept as built, since a file saved by a pre-release build records neither conv argument
+        self._in_shape = _sample_shape(in_features, conv['in_shape'])
+        self._stage_shapes = _stage_shapes(conv['in_shape'], conv['convolution'])
+        flat = math.prod([self._in_shape, *self._stage_shapes][-1])
+
+        # L A Y E R S: the conv stages, then Linear, ReLU, and (when asked) Dropout per hidden layer, then the output
+        (name,) = self.sources
+        with _seeded(seed):
+            setattr(
+                self,
+                name,
+                nn.Sequential(
+                    *_conv_stack(conv['in_shape'], conv['convolution']),
+                    *_stack((flat, *hidden_size, out_features), dropout),
+                ),
+            )
+        self._network = NETWORK_KINDS[self.network_kind]['networks'](self)
+
+    def forward(self, x):
+        """Returns the network's raw outputs for the batch x, as nn.Module calls it."""
+        (name,) = self.sources
+        return getattr(self, name)(x)
+
+    @property
+    def hidden_size(self):
+        """
+        The output of each hidden layer, in order, as the network was built: each conv stage's
+        (channels, height, width), then each hidden 'Linear' layer's width, e.g. ((8, 14, 14), 64).
+        """
+        return (*self._stage_shapes, *self.arguments['hidden_size'])
+
+    @property
+    def in_shape(self):
+        """One sample's shape as the network reads it: (channels, height, width), or (in_features,) with no conv stages."""
+        return self._in_shape
+
+    def outputs(self, X):
+        """
+        Returns the network's outputs for every sample, scored in eval() without gradients, its mode left as it was.
+
+        Args:
+            X:  the input samples, one per row: a tensor or NumPy array of shape (N, ...), each
+                sample 'in_features' values; each is shaped to 'in_shape', as 'train_model()'
+                feeds the network, so images and flattened rows score the same.
+
+        Returns:
+            the (N, out_features) outputs tensor, on the CPU.
+
+        Note:
+            X is scored in batches of the latest training's 'batch_size' (64 before any training),
+            each moved to the model's device alone, so a phase of any size fits the GPU.
+        """
+        return _scored(self, self, X, 'X', self.in_shape)
+
+    def classify(self, X):
+        """
+        Returns a classifier's predicted column(s) and probabilities for every sample.
+
+        Args:
+            X:  the input samples, as 'outputs()' takes them.
+
+        Returns:
+            (columns, probabilities) as NumPy arrays, columns int64 and probabilities float64:
+            (N,) columns and (N, k) probabilities for one label per sample; (N, k) of each for
+            a binary network's k independent labels.
+        """
+        logits = self.outputs(X)
+        columns = self.predicted(logits)
+        # a one-output model is one two-class label, as the views read it, not one label of many
+        if columns.ndim == 2 and columns.shape[1] == 1:
+            columns = columns[:, 0]
+        probabilities = self.probabilities(logits)
+        return columns.long().cpu().numpy(), probabilities.cpu().double().numpy()
+
+    def regress(self, X):
+        """
+        Returns a regressor's predicted value(s) for every sample.
+
+        Args:
+            X:  the input samples, as 'outputs()' takes them.
+
+        Returns:
+            a float64 NumPy array: (N,) for one target, as the targets are, or (N, k) for k targets.
+        """
+        return self.outputs(X).squeeze(1).cpu().double().numpy()
+
+    def weights(self):
+        """Returns a copy of 'state_dict()' in system RAM, so later training cannot change it and it takes no GPU memory."""
+        return {
+            key: value.detach().to('cpu', copy=True)
+            for key, value in self.state_dict().items()
+        }
+
+    def load_weights(self, weights):
+        """Loads 'weights()' into the network."""
+        self.load_state_dict(weights)
+
+
+class ClassificationModel(FeedforwardModel):
+    """
+    Multi-layer classification network; 'out_features' is the number of classes.
+
+    Note:
+        Each output is a logit, one raw score per class: train with 'nn.CrossEntropyLoss',
+        which applies the softmax, and predict with 'outputs.argmax(1)'.
+
+    Example:
+        >>> model = ClassificationModel(input_size, (128, 64), num_classes).to(device)
+    """
+
+    output_activation_name = 'softmax'
+    kind = 'classification'
+    # the loss class, built with PyTorch's default "mean" reduction the epoch loss assumes
+    criterion = nn.CrossEntropyLoss
+    sources: ClassVar[dict] = {'classifier': ('data',)}
+
+    def predicted(self, outputs):
+        """Each sample's predicted column, the highest logit's."""
+        return outputs.argmax(1)
+
+    def probabilities(self, logits):
+        """(N, k) class probabilities, each row summing to 1."""
+        return torch.softmax(logits, dim=1)
+
+
+class RegressionModel(FeedforwardModel):
+    """
+    Multi-layer regression network; 'out_features' is the number of targets.
+
+    Note:
+        The output is (N, out_features), e.g. (N, 1) for one target; flatten it to match
+        (N,) targets before 'nn.MSELoss', as the course's training loop does.
+
+    Example:
+        >>> model = RegressionModel(input_size, (64, 64, 64), 1, dropout=0.25).to(device)
+    """
+
+    output_activation_name = 'linear'
+    kind = 'regression'
+    criterion = nn.MSELoss
+    sources: ClassVar[dict] = {'regressor': ('data',)}
+
+    def _fitted(self, outputs, targets):
+        """Returns (N, 1) outputs reshaped to (N,) targets, or nn.MSELoss broadcasts to (N, N)."""
+        return _flattened(outputs, targets)
+
+
+class BinaryClassificationModel(FeedforwardModel):
+    """
+    Multi-layer binary classification network; 'out_features' is the number of yes / no labels.
+
+    Note:
+        Each output is a logit, one raw score per label: train with 'nn.BCEWithLogitsLoss',
+        which applies the sigmoid, and predict with 'outputs > 0'. out_features=1 is one
+        two-class label; out_features=k is k independent labels (multi-label), each its own
+        yes / no, where a softmax classifier's outputs would compete.
+
+    Example:
+        >>> model = BinaryClassificationModel(input_size, (64, 32), 1).to(device)
+    """
+
+    output_activation_name = 'sigmoid'
+    kind = 'classification'
+    criterion = nn.BCEWithLogitsLoss
+    sources: ClassVar[dict] = {'classifier': ('data',)}
+
+    def _targets(self, inputs, labels, name):
+        """Returns the 0 / 1 labels cast to the model's float dtype for BCE, raising a ValueError naming the phase for any other."""
+        if not ((labels == 0) | (labels == 1)).all():
+            raise ValueError(
+                f'{name} holds labels other than 0 and 1;'
+                ' each output of the model is one yes / no'
+            )
+        return labels.to(next(self.parameters()).dtype)
+
+    def _fitted(self, outputs, targets):
+        """Returns the outputs reshaped to the labels' shape, (N,) for one output."""
+        return _flattened(outputs, targets)
+
+    def predicted(self, outputs):
+        """Each output's predicted yes / no, read from the logit, where a rounded probability could tie."""
+        return outputs > 0
+
+    def probabilities(self, logits):
+        """
+        Each output's probability of yes; for one output, the two class probabilities, the lower
+        class first, where sigmoid(-z) is 1 - sigmoid(z) without cancellation.
+        """
+        if logits.shape[1] == 1:
+            return torch.cat([torch.sigmoid(-logits), torch.sigmoid(logits)], dim=1)
+        return torch.sigmoid(logits)
+
+
+class AutoencoderModel(_CriterionModel):
+    """
+    Multi-layer autoencoder: an encoder that compresses each sample to a small latent code, and a
+    decoder that rebuilds the sample from it.
+
+    The encoder is hidden 'Linear' layers, each followed by a ReLU (and a Dropout when 'dropout'
+    > 0), down to a 'Linear' latent layer with no activation; the decoder mirrors it back to
+    'in_features', then applies its output style.
+
+    Args:
+        in_features:        the number of input features, e.g. 784 for a 28 x 28 image.
+        encoder_size:       the width of each hidden encoder layer, in order, e.g. (128, 64); the
+                            decoder's hidden layers are the same widths reversed. () builds a single
+                            'Linear' layer each way.
+        latent_size:        the width of the latent code, e.g. 2 to plot it as it is.
+        output_activation:  the decoder's output style, one of 'AUTOENCODER_OUTPUTS': "linear"
+                            (the course's) for standardized rows or Normalize()d images, "sigmoid"
+                            for inputs in [0, 1], "tanh" for inputs in [-1, 1].
+        dropout:            the probability of zeroing each hidden activation while training, at least 0
+                            and below 1; 0 adds no Dropout layers.
+        seed:               seeds the starting weights, a whole number from 0 to 2**32 - 1, so every build with
+                            it starts the same, without changing torch's global random stream; None for
+                            unseeded weights, e.g. after the Notebook's own 'torch.manual_seed()'.
+        in_shape:           one image's (channels, height, width), as 'FeedforwardModel' takes it.
+        convolution:        the encoder's convolution stages, as 'FeedforwardModel' takes them; each pool must
+                            divide the height and width it pools, so the decoder can rebuild them. The
+                            decoder mirrors them with one ConvTranspose2d per stage, its kernel and
+                            stride the stage's pool, a ReLU between each, back to 'in_shape'.
+
+    Note:
+        Train with 'train_model()', on nn.MSELoss of each sample against itself; the labels of
+        its data are never trained on, and 'classes', when given, color 'show_latent_space()'.
+        The course's 'SimpleAutoEncoder' is (784, (128, 64), 2) and its 'AutoEncoder' is
+        (784, (256,), 32): every layer is in the course's order under the names 'encoder' and
+        'decoder', and no output style holds weights, so a course model's 'state_dict()' loads
+        into the matching model here. The course's Module 4.1 'CNNAutoEncoder' is (784, (), 32,
+        in_shape=(1, 28, 28), convolution=({"channels": 8, "kernel": 3, "pool": 2},)), less its
+        two ReLUs that follow a ReLU and change nothing; its weights load in their order. The
+        trainer and views read only 'encode()', 'decode()', 'reconstruct()', and the class
+        attributes.
+
+    Example:
+        >>> model = AutoencoderModel(28 * 28, (128, 64), 2).to(device)
+        >>> model.data = data_dataset_split(mnist_train, mnist_test, 0.25, digit_classes, seed=0)
+        >>> model = AutoencoderModel(28 * 28, (), 32, in_shape=(1, 28, 28),
+        ...     convolution=({"channels": 8, "kernel": 3, "pool": 2},)).to(device)
+    """
+
+    activation_name = 'relu'
+    kind = 'autoencoder'
+    criterion = nn.MSELoss
+    # how its networks are found and read, a key of 'NETWORK_KINDS'
+    network_kind = 'torch'
+    # each network's name, in the order they run, and what it reads: 'data' or an earlier network
+    sources: ClassVar[dict] = {'encoder': ('data',), 'decoder': ('encoder',)}
+
+    def __init__(
+        self,
+        in_features,
+        encoder_size,
+        latent_size,
+        output_activation='linear',
+        dropout=0.0,
+        seed=None,
+        in_shape=None,
+        convolution=(),
+    ):
+        # V A L I D A T E: every width, the output style, and the dropout rate fail by name first
+        _check_width('in_features', in_features)
+        _check_sizes('encoder_size', encoder_size)
+        _check_width('latent_size', latent_size)
+        _check_output_activation(output_activation)
+        _check_dropout(dropout)
+        _check_conv(in_features, in_shape, convolution, is_mirrored=True)
+
+        # A R G U M E N T S: kept as plain values, so model_load() reads them back with weights_only
+        conv = _conv_arguments(in_shape, convolution)
+        super().__init__(
+            {
+                'in_features': int(in_features),
+                **conv,
+                'encoder_size': tuple(int(width) for width in encoder_size),
+                'latent_size': int(latent_size),
+                'output_activation': output_activation,
+                'dropout': float(dropout),
+                'seed': seed,
+            }
+        )
+        self.output_activation_name = output_activation
+
+        # S H A P E S: kept as built, since a file saved by a pre-release build records neither conv argument
+        self._in_shape = _sample_shape(in_features, conv['in_shape'])
+        self._stage_shapes = _stage_shapes(conv['in_shape'], conv['convolution'])
+        flat = math.prod([self._in_shape, *self._stage_shapes][-1])
+
+        # L A Y E R S: the encoder down to the latent code, then the decoder mirrored back up
+        widths = (flat, *encoder_size, latent_size)
+        with _seeded(seed):
+            self.encoder = nn.Sequential(
+                *_conv_stack(conv['in_shape'], conv['convolution']),
+                *_stack(widths, dropout),
+            )
+            output = NEURON_KINDS[output_activation]['module']()
+            self.decoder = nn.Sequential(
+                *_stack(widths[::-1], dropout),
+                *_deconv_stack(conv['in_shape'], conv['convolution']),
+                output,
+            )
+        self._network = NETWORK_KINDS[self.network_kind]['networks'](self)
+
+    def forward(self, x):
+        """Returns the reconstruction of the batch x: encoded to its latent code, then decoded."""
+        return self.decoder(self.encoder(x))
+
+    @property
+    def hidden_size(self):
+        """
+        The output of every layer between input and output: each encoder conv stage's (channels,
+        height, width), the encoder widths, the latent size, then the decoder's mirror of both,
+        e.g. (128, 64, 2, 64, 128), or ((8, 14, 14), 32, (8, 14, 14)).
+        """
+        shapes = self._stage_shapes
+        sizes = self.arguments['encoder_size']
+        return (
+            *shapes,
+            *sizes,
+            self.arguments['latent_size'],
+            *sizes[::-1],
+            *shapes[::-1],
+        )
+
+    @property
+    def in_shape(self):
+        """One sample's shape as the network reads it: (channels, height, width), or (in_features,) with no conv stages."""
+        return self._in_shape
+
+    @property
+    def output_range(self):
+        """The (low, high) its output style can reach, e.g. (-1.0, 1.0) for "tanh"."""
+        return NEURON_KINDS[self.output_activation_name]['range']
+
+    def _targets(self, inputs, labels, name):
+        """Returns the inputs, shaped as the network reads them, raising a ValueError naming the phase for any past 'output_range'."""
+        low, high = self.output_range
+        if inputs.min() < low or inputs.max() > high:
+            raise ValueError(
+                f'{name} holds inputs from {inputs.min().item():.4g} to'
+                f' {inputs.max().item():.4g}; a {self.output_activation_name!r} output reconstructs'
+                f' only [{low}, {high}]'
+            )
+        return inputs
+
+    def encode(self, X):
+        """
+        Returns every sample's latent code, scored in eval() without gradients, its mode left as it was.
+
+        Args:
+            X:  the input samples, one per row: a tensor or NumPy array of shape (N, ...), each
+                sample 'in_features' values; each is shaped to 'in_shape', as 'train_model()'
+                feeds the network, so images and flattened rows score the same.
+
+        Returns:
+            a float64 NumPy array of shape (N, latent_size).
+        """
+        return self.network[0].outputs(X)
+
+    def decode(self, Z):
+        """
+        Returns the sample the decoder rebuilds from every latent code, scored as 'encode()' scores.
+
+        Args:
+            Z:  the latent codes, a tensor or NumPy array of shape (N, latent_size).
+
+        Returns:
+            a float64 NumPy array of shape (N, in_features), each image flattened to one row.
+        """
+        outputs = self.network[1]._outputs(Z, 'Z')
+        return outputs.reshape(len(outputs), -1)
+
+    def reconstruct(self, X):
+        """
+        Returns every sample encoded and decoded again, scored as 'encode()' scores.
+
+        Args:
+            X:  the input samples, as 'encode()' takes them.
+
+        Returns:
+            a float64 NumPy array of shape (N, in_features), each row one sample's reconstruction.
+        """
+        return (
+            _scored(self, self, X, 'X', self.in_shape).flatten(1).cpu().double().numpy()
+        )
+
+    def weights(self):
+        """Returns a copy of 'state_dict()' in system RAM, so later training cannot change it and it takes no GPU memory."""
+        return {
+            key: value.detach().to('cpu', copy=True)
+            for key, value in self.state_dict().items()
+        }
+
+    def load_weights(self, weights):
+        """Loads 'weights()' into the network."""
+        self.load_state_dict(weights)
+
+
+class _ExternalModel:
+    """
+    What every wrapped network shares: its networks given, not built, and its shapes read from its Layers.
+
+    Note:
+        A wrapper lists it before its house class, e.g. 'ClassificationModel', so 'in_features',
+        'hidden_size', and 'activation_name' are read from 'in_shape' and the probed Layers, not
+        from the arguments the house class builds its networks from.
+    """
+
+    is_external = True
+
+    def _wrap(self, networks, in_shape, arguments):
+        """
+        Checks the networks and 'in_shape', records the "create" event, and finds the Model's Networks.
+
+        Args:
+            networks:   each network by its name in 'sources', e.g. {"classifier": vgg11}.
+            in_shape:   one sample's shape as the networks read it, e.g. (3, 224, 224).
+            arguments:  its plain arguments after 'in_shape', e.g. {"output_activation": "tanh"}.
+        """
+        if (
+            not isinstance(in_shape, tuple)
+            or not in_shape
+            or any(
+                isinstance(size, bool)
+                or not isinstance(size, numbers.Integral)
+                or size < 1
+                for size in in_shape
+            )
+        ):
+            raise ValueError(
+                f"'in_shape' must be a tuple of whole numbers of at least 1, e.g. (3, 224, 224), got {in_shape!r}"
+            )
+        for name, network in networks.items():
+            if not isinstance(network, nn.Module):
+                raise TypeError(
+                    f"'{name}' must be a PyTorch network, e.g. torchvision's VGG11, got {type(network).__name__}"
+                )
+        in_shape = tuple(int(size) for size in in_shape)
+        # the house class's own __init__ builds networks; a wrapper is given them
+        Model.__init__(self, {'in_shape': in_shape, **arguments})
+        for name, network in networks.items():
+            setattr(self, name, network)
+        self._in_shape = in_shape
+        self._network = NETWORK_KINDS[self.network_kind]['networks'](self)
+
+    @property
+    def in_features(self):
+        """The number of values in one sample, the product of 'in_shape'; read-only."""
+        return math.prod(self.in_shape)
+
+    @property
+    def hidden_size(self):
+        """The output of every Layer but the last, in order: a width, or a conv Layer's (channels, height, width)."""
+        layers = [layer for network in self.network for layer in network.layer]
+        return tuple(
+            layer.out_shape[0] if len(layer.out_shape) == 1 else layer.out_shape
+            for layer in layers[:-1]
+        )
+
+    @property
+    def activation_name(self):
+        """The first Layer's activation, e.g. "relu", the one the views label as the hidden activation."""
+        return self.network[0].layer[0].activation
+
+
+class ExternalClassificationModel(_ExternalModel, ClassificationModel):
+    """
+    A classification network built outside mcode-neural, e.g. torchvision's VGG11, as a Model.
+
+    Args:
+        classifier: the network, an nn.Module whose outputs are one logit per class; its loss,
+                    nn.CrossEntropyLoss, applies the softmax.
+        in_shape:   one sample's shape as the network reads it, e.g. (3, 224, 224); given, since a
+                    network with an adaptive pool reads many sizes.
+
+    Note:
+        It trains, tests, predicts, shows, and saves as a 'ClassificationModel' does. Its Layers
+        are found by one hooked pass, as every Model's are, so a network that runs a module twice
+        in one pass, e.g. ResNet's shared ReLU, fails by name. 'hidden_size' and
+        'activation_name' are read from its Layers. 'model_load()' takes the same network built
+        again: 'model_load(path, classifier=...)'.
+
+    Example:
+        >>> vgg = ExternalClassificationModel(models.vgg11(weights=None), (3, 32, 32)).to(device)
+        >>> model_replace_output(vgg, 10)
+    """
+
+    def __init__(self, classifier, in_shape):
+        self._wrap({'classifier': classifier}, in_shape, {})
+
+
+class ExternalRegressionModel(_ExternalModel, RegressionModel):
+    """
+    A regression network built outside mcode-neural as a Model.
+
+    Args:
+        regressor:  the network, an nn.Module whose outputs are the predicted values, one per target.
+        in_shape:   one sample's shape as the network reads it, e.g. (13,) or (3, 64, 64).
+
+    Note:
+        It trains, tests, predicts, shows, and saves as a 'RegressionModel' does, its Layers read
+        as 'ExternalClassificationModel' reads them. 'model_load()' takes the same network built
+        again: 'model_load(path, regressor=...)'.
+
+    Example:
+        >>> model = ExternalRegressionModel(my_regressor, (13,)).to(device)
+    """
+
+    def __init__(self, regressor, in_shape):
+        self._wrap({'regressor': regressor}, in_shape, {})
+
+
+class ExternalAutoencoderModel(_ExternalModel, AutoencoderModel):
+    """
+    An autoencoder built outside mcode-neural, its encoder and decoder, as a Model.
+
+    Args:
+        encoder:            the network that compresses each sample to its latent code, an nn.Module.
+        decoder:            the network that rebuilds each sample from its code, an nn.Module whose output
+                            is the sample's shape, through its 'output_activation'.
+        in_shape:           one sample's shape as the encoder reads it, e.g. (1, 28, 28).
+        output_activation:  the decoder's output style, one of 'AUTOENCODER_OUTPUTS', as
+                            'AutoencoderModel' takes it: "sigmoid" for a decoder ending in
+                            nn.Sigmoid, "tanh" for nn.Tanh, "linear" for none.
+
+    Note:
+        It trains, tests, encodes, decodes, shows, and saves as an 'AutoencoderModel' does, its
+        Layers read as 'ExternalClassificationModel' reads them. 'model_load()' takes both
+        networks built again: 'model_load(path, encoder=..., decoder=...)'.
+
+    Example:
+        >>> model = ExternalAutoencoderModel(my_encoder, my_decoder, (1, 28, 28), "sigmoid").to(device)
+    """
+
+    def __init__(self, encoder, decoder, in_shape, output_activation):
+        _check_output_activation(output_activation)
+        self._wrap(
+            {'encoder': encoder, 'decoder': decoder},
+            in_shape,
+            {'output_activation': output_activation},
+        )
+
+    @property
+    def output_activation_name(self):
+        """The decoder's output style, its 'output_activation' argument; read-only."""
+        return self.arguments['output_activation']
+
+
+# endregion
+
+# region  P R I V A T E   F U N C T I O N S
+
+
+def _check_output_activation(output_activation):
+    """Raises a ValueError unless 'output_activation' is one of 'AUTOENCODER_OUTPUTS'."""
+    if output_activation not in AUTOENCODER_OUTPUTS:
+        raise ValueError(
+            f"'output_activation' must be one of {list(AUTOENCODER_OUTPUTS)}, got {output_activation!r}"
+        )
+
+
+def _check_model(model):
+    """
+    Raises a TypeError unless 'model' is a mcode-neural Model, for every function that takes one.
+
+    Args:
+        model:  the caller's model.
+    """
+    if not isinstance(model, Model):
+        raise TypeError(
+            f"'model' must be a mcode-neural Model, got {type(model).__name__}"
+        )
+
+
+def _flattened(outputs, targets):
+    """
+    Returns 'outputs' reshaped to the targets' shape, raising a ValueError when their sizes differ.
+
+    Args:
+        outputs:    a batch's outputs, e.g. (N, 1).
+        targets:    what its loss compares them to, e.g. (N,).
+    """
+    # (N, 2) outputs for (N,) targets would reshape to nothing sensible
+    if outputs.numel() != targets.numel():
+        raise ValueError(
+            f"'model' outputs {tuple(outputs.shape)} for targets {tuple(targets.shape)};"
+            " its 'out_features' must match the number of targets"
+        )
+    return outputs.reshape(targets.shape)
+
+
+def _article(word):
+    """
+    Returns 'word' after its English article, e.g. "a regression" or "an autoencoder".
+
+    Args:
+        word:   the word the article leads, e.g. a model's 'kind'.
+    """
+    return f'{"an" if word[0] in "aeiou" else "a"} {word}'
+
+
+def _arguments(hyperparams):
+    """
+    Returns a "create" event's arguments as the constructor takes them: those given, then those left at their defaults.
+
+    Args:
+        hyperparams:    the "create" event's hyperparams, {name: value, ..., "defaults": {name: value}}.
+    """
+    given = {
+        key: value for key, value in hyperparams.items() if key != HISTORY_DEFAULTS
+    }
+    return given | hyperparams[HISTORY_DEFAULTS]
+
+
+def _event(event, time, hyperparams, results):
+    """
+    Returns one history event, {"event", "time", "hyperparams", "results"}.
+
+    Args:
+        event:          the step, "create", "data", "train", or "load".
+        time:           its local time, e.g. "2026-10-29 14:03:12-04:00"; None when not recorded.
+        hyperparams:    what the step was given, plain values; None when not recorded.
+        results:        what the step produced, plain values; None when not recorded.
+    """
+    return {
+        'event': event,
+        'time': time,
+        'hyperparams': hyperparams,
+        'results': results,
+    }
+
+
+def _plain(value, name):
+    """
+    Returns 'value' as plain values a saved model can keep: None, bool, str, int, float, and lists, tuples, and dicts of them.
+
+    Args:
+        value:  the value to record, e.g. an optimizer's settings; a NumPy or torch number, array,
+                or tensor becomes the plain number or list it holds.
+        name:   its dotted name, e.g. "hyperparams.optimizer", named when it cannot be kept.
+    """
+    if value is None:
+        return value
+    if isinstance(value, (bool, np.bool_)):
+        return bool(value)
+    # a str subclass, e.g. torch's TorchVersion, would be saved as its own class
+    if isinstance(value, str):
+        return str(value)
+    if isinstance(value, numbers.Integral):
+        return int(value)
+    if isinstance(value, numbers.Real):
+        return float(value)
+    if isinstance(value, (torch.Tensor, np.ndarray)):
+        return _plain(value.tolist(), name)
+    if isinstance(value, (list, tuple)):
+        items = [_plain(item, f'{name}[{i}]') for i, item in enumerate(value)]
+        return tuple(items) if isinstance(value, tuple) else items
+    if isinstance(value, dict):
+        return {key: _plain(item, f'{name}.{key}') for key, item in value.items()}
+    raise TypeError(
+        f'{name!r} holds a {type(value).__name__}, which a saved model cannot keep'
+    )
+
+
+@contextmanager
+def _seeded(seed):
+    """
+    Seeds the model weights built inside it, leaving the Notebook's own random streams as they were.
+
+    Args:
+        seed:   a whole number that seeds NumPy's global RNG and torch's CPU generator inside the
+                block, both restored after it; None leaves both as they are, unseeded.
+    """
+    if seed is None:
+        yield
+        return
+    state = np.random.get_state()
+    np.random.seed(seed)
+    try:
+        # the CPU generator only: torch.manual_seed() would also reseed CUDA, outside the fork
+        with torch.random.fork_rng(devices=[]):
+            torch.default_generator.manual_seed(seed)
+            yield
+    finally:
+        np.random.set_state(state)
+
+
+def _latest_train(model):
+    """
+    Returns the model's latest "train" event, or None before any training.
+
+    Args:
+        model:  a Model.
+    """
+    trains = [event for event in model.history if event['event'] == 'train']
+    return trains[-1] if trains else None
+
+
+def _score_batch_size(model):
+    """
+    Returns how many samples a model scores at once: its latest training's 'batch_size', else 'SCORE_BATCH_SIZE'.
+
+    Args:
+        model:  a Model.
+
+    Note:
+        Scoring keeps no gradients, so a batch that trained fits. A model not yet trained, or
+        saved by a version whose neuron trainer took no batch size, scores 'SCORE_BATCH_SIZE'.
+    """
+    train = _latest_train(model)
+    hyperparams = None if train is None else train['hyperparams']
+    if hyperparams is None or 'batch_size' not in hyperparams:
+        return SCORE_BATCH_SIZE
+    return hyperparams['batch_size']
+
+
+def _upgraded(saved):
+    """
+    Returns a file saved by a pre-release build, which kept no history, in the shape 'model_save()' writes now.
+
+    Args:
+        saved:  what 'torch.load()' read: 'class', 'arguments', 'weights', 'data', 'curves', and
+                'best_epoch'.
+
+    Note:
+        The one approved fallback. The history is built from what the file held: "create" from
+        its arguments, "data" when it held data, and "train" when it held curves. A fact it never
+        held, e.g. a time, a split, or a trainer's settings, is None, "not recorded".
+    """
+    history = [_event('create', None, saved['arguments'], None)]
+    data = saved['data']
+    if data is not None:
+        data = data | {'split': None}
+        history.append(_event('data', None, None, None))
+    if saved['curves']:
+        results = {
+            'curves': saved['curves'],
+            'best_epoch': saved['best_epoch'],
+            'tests': {},
+        }
+        history.append(_event('train', None, None, results))
+    return {
+        'class': saved['class'],
+        'weights': saved['weights'],
+        'data': data,
+        'history': history,
+    }
+
+
+def _check_networks(path, cls, networks):
+    """
+    Raises a ValueError unless 'networks' are the ones the saved class takes: a wrapped Model's, by name, or none.
+
+    Args:
+        path:       the file being loaded, for the messages.
+        cls:        the saved Model class.
+        networks:   the networks 'model_load()' was given, by name.
+    """
+    if not cls.is_external:
+        if networks:
+            raise ValueError(
+                f'{path!r} holds a {cls.__name__!r}, which builds its own networks; give none, got {list(networks)}'
+            )
+        return
+    names = list(cls.sources)
+    if sorted(networks) != sorted(names):
+        raise ValueError(
+            f'{path!r} holds a {cls.__name__!r}; give its networks built again, by name, {names},'
+            f' e.g. model_load(path, {names[0]}=...), got {list(networks)}'
+        )
+
+
+def _check_fit(path, model, weights):
+    """
+    Raises a ValueError naming the first weight the file and the model's networks do not hold in one shape.
+
+    Args:
+        path:       the file being loaded, for the messages.
+        model:      a wrapped Model, built from the networks given, its saved changes replayed.
+        weights:    the file's weights, {key: tensor}, as 'model.weights()' saved them.
+    """
+    shapes = {key: tuple(value.shape) for key, value in model.state_dict().items()}
+    for key, value in weights.items():
+        shape = tuple(value.shape)
+        if key not in shapes:
+            raise ValueError(
+                f'{path!r} holds {_path_text(key)} {shape}; the networks given have no {_path_text(key)}'
+            )
+        if shapes[key] != shape:
+            raise ValueError(
+                f'{path!r} holds {_path_text(key)} {shape}; the networks given have {shapes[key]}'
+            )
+    for key, shape in shapes.items():
+        if key not in weights:
+            raise ValueError(
+                f'the networks given have {_path_text(key)} {shape}, which {path!r} does not hold'
+            )
+
+
+def _path_text(path):
+    """
+    Returns a module path as the code that reaches it reads, e.g. "classifier.6" as "classifier[6]".
+
+    Args:
+        path:   a path as 'named_modules()' names it, or already in that form, e.g. "features".
+    """
+    return re.sub(r'\.(\d+)', r'[\1]', path)
+
+
+def _module_path(text):
+    """
+    Returns a module path as 'named_modules()' names it, e.g. "classifier[6]" as "classifier.6".
+
+    Args:
+        text:   a path either way, e.g. "classifier[6]" or "classifier.6".
+    """
+    return re.sub(r'\[(\d+)\]', r'.\1', text)
+
+
+def _parts(model, parts):
+    """
+    Returns the submodules 'parts' names, e.g. ("features",), or the whole model when none, failing by name.
+
+    Args:
+        model:  a 'torch.nn.Module', a network Model or an external network.
+        parts:  submodule paths, e.g. "features" or "classifier[6]" ("classifier.6" reads the same).
+    """
+    if not isinstance(model, nn.Module):
+        raise TypeError(
+            f"'model' must be a PyTorch network, e.g. ClassificationModel or VGG11, got {type(model).__name__};"
+            ' a single NumPy neuron has no layers to freeze or replace'
+        )
+    for path in parts:
+        try:
+            model.get_submodule(_module_path(path))
+        except AttributeError:
+            top = [name for name, _ in model.named_children()]
+            raise ValueError(
+                f"'model' has no part {path!r}; its top-level parts are {top}"
+            ) from None
+    return [model.get_submodule(_module_path(path)) for path in parts] or [model]
+
+
+def _trainable(model):
+    """Returns (trainable, total) parameter counts of a network."""
+    parameters = list(model.parameters())
+    trainable = sum(p.numel() for p in parameters if p.requires_grad)
+    return trainable, sum(p.numel() for p in parameters)
+
+
+def _set_trainable(model, parts, trains):
+    """
+    Sets whether every parameter of each part trains, and returns the network's (trainable, total) counts.
+
+    Args:
+        model:  a network.
+        parts:  submodule paths; empty for the whole network.
+        trains: True to unfreeze, False to freeze.
+    """
+    for module in _parts(model, parts):
+        for parameter in module.parameters():
+            parameter.requires_grad_(trains)
+    return _trainable(model)
+
+
+def _output_layer(model):
+    """Returns (path, module) of a network's output layer, its last nn.Linear in module order, failing by name."""
+    linears = [
+        (path, module)
+        for path, module in model.named_modules()
+        if isinstance(module, nn.Linear)
+    ]
+    if not linears:
+        raise ValueError(
+            f"'model' {type(model).__name__} has no nn.Linear output layer to replace"
+        )
+    return linears[-1]
+
+
+def _replace_output(model, out_features):
+    """
+    Replaces a network's output layer with a new nn.Linear of 'out_features', and returns (path, old layer, new layer).
+
+    Args:
+        model:          a network.
+        out_features:   the new layer's outputs, already checked.
+
+    Note:
+        The new layer keeps the old one's 'in_features', bias, device, and dtype; its weights are
+        new. A Model's Network views are built again, so they read the new layer.
+    """
+    path, old = _output_layer(model)
+    new = nn.Linear(old.in_features, out_features, bias=old.bias is not None).to(
+        device=old.weight.device, dtype=old.weight.dtype
+    )
+    parent, _, name = path.rpartition('.')
+    setattr(model.get_submodule(parent), name, new)
+    if isinstance(model, Model):
+        model._network = NETWORK_KINDS[model.network_kind]['networks'](model)
+    return path, old, new
+
+
+def _gpu_memory(device):
+    """
+    Returns a CUDA device's (total, cap) in GiB; the cap is the share 'model_device()' set, None when none was.
+
+    Args:
+        device: a CUDA device.
+
+    Note:
+        The cap is read back from PyTorch, which keeps the fraction; the library keeps no copy.
+    """
+    total = torch.cuda.get_device_properties(device).total_memory / 2**30
+    fraction = torch.cuda.get_per_process_memory_fraction(device)
+    return total, (fraction * total if fraction < 1 else None)
+
+
+def _peaks(device):
+    """
+    Returns the peak GPU memory since its last reset, {"peak_allocated_gib", "peak_reserved_gib"}, in GiB to 3 places.
+
+    Args:
+        device: a CUDA device.
+
+    Note:
+        Reserved is what PyTorch holds from the driver, and what the cap of 'model_device()' bounds;
+        allocated is the part of it tensors use.
+    """
+    return {
+        'peak_allocated_gib': round(torch.cuda.max_memory_allocated(device) / 2**30, 3),
+        'peak_reserved_gib': round(torch.cuda.max_memory_reserved(device) / 2**30, 3),
+    }
+
+
+def _out_of_memory(phase, batch_size, device):
+    """
+    Returns a torch.OutOfMemoryError naming the phase and batch size that ran past the GPU memory this process may use.
+
+    Args:
+        phase:      the phase whose batch failed, e.g. "train".
+        batch_size: the batch size that failed.
+        device:     the CUDA device the batch ran on.
+
+    Note:
+        The cap is read back from PyTorch, which keeps the fraction 'model_device()' set; with no
+        cap the limit is the GPU's whole memory.
+    """
+    total, cap = _gpu_memory(device)
+    limit = (
+        f'the {cap:.2f} GiB cap' if cap is not None else f"the GPU's {total:.2f} GiB"
+    )
+    return torch.OutOfMemoryError(
+        f'phase {phase!r} at batch_size={batch_size} needs more than {limit}; try a smaller batch_size'
+    )
+
+
+# endregion
+
+# region  P U B L I C   F U N C T I O N S
+
+
+def model_test(model, phase):
+    """
+    Scores a trained model on one labeled phase of its data, and keeps the metrics in its history.
+
+    Args:
+        model:  a Model trained by 'train_model()'.
+        phase:  the labeled phase to score, e.g. "test", a phase of 'model.data'.
+
+    Returns:
+        'predict_metrics(model, phase)': a classifier's {"accuracy", "auc"}, a regressor's
+        {"mae", "rmse", "r2"}, or an autoencoder's {"mse", "rmse"}.
+
+    Note:
+        The metrics describe the weights the latest training kept, so they are kept in that
+        "train" event's results as "tests": {phase: metrics}. Testing the same phase again
+        replaces its metrics, so a re-run cell adds nothing; training again starts a new event.
+        The phase is scored in batches of the training's 'batch_size'; on a GPU, the kept
+        metrics also hold the scoring's peak memory, "peak_allocated_gib" and
+        "peak_reserved_gib", as the trainer's results do.
+
+    Example:
+        >>> model = train_model(model, optimizer, scheduler, num_epochs=50, batch_size=10)
+        >>> model_test(model, "test")
+        {'accuracy': 0.9615, 'auc': 0.9912}
+    """
+    # predict.py imports this module, so its scorer is imported only when first called
+    from .predict import predict_metrics
+
+    _check_model(model)
+    train = _latest_train(model)
+    if train is None:
+        raise ValueError(
+            "'model' has no training to test; train it with 'train_model()' first"
+        )
+    device = next(model.parameters()).device if isinstance(model, nn.Module) else None
+    is_cuda = device is not None and device.type == 'cuda'
+    if is_cuda:
+        torch.cuda.reset_peak_memory_stats(device)
+    metrics = predict_metrics(model, phase)
+    kept = metrics | _peaks(device) if is_cuda else metrics
+    train['results']['tests'][phase] = _plain(kept, f'tests.{phase}')
+    return metrics
+
+
+def model_save(model, path):
+    """
+    Saves a model with what it knows about itself: its class, weights, data contract, and
+    history as a PyTorch .pt file.
+
+    Args:
+        model:  a Model, e.g. trained by 'train_model()'.
+        path:   the file to write, e.g. "wine_neuron.pt".
+
+    Note:
+        The datasets are not saved, only their contract: the feature names, the classes, the
+        DataFrame contract, and how they were split; a loaded model scores new rows added by
+        'data_frame_phase()'. The history holds the arguments the model is built again from, and
+        every training's curves. Every value saved is a tensor, number, string, list, tuple, or
+        dict, so 'model_load()' reads the file with 'weights_only=True', which runs no pickled code.
+
+    Example:
+        >>> model_save(model, "wine_neuron.pt")
+    """
+    _check_model(model)
+    data = None
+    if model._data is not None:
+        frame = model._data.frame
+        # a torch dtype is stored by its name, e.g. "int64", a plain string
+        if frame is not None:
+            frame = frame | {'label_dtype': str(frame['label_dtype']).split('.')[-1]}
+        data = {
+            'kind': model._data.kind,
+            'feature': model._data.feature,
+            'classes': model._data.classes,
+            'frame': frame,
+            'split': model._data.split,
+        }
+    torch.save(
+        {
+            'class': type(model).__name__,
+            'weights': model.weights(),
+            'data': data,
+            'history': model.history,
+        },
+        path,
+    )
+
+
+def model_load(path, **networks):
+    """
+    Loads a model saved by 'model_save()' from a PyTorch .pt file: the same class, weights, data contract, and history.
+
+    Args:
+        path:       the file 'model_save()' wrote.
+        networks:   a wrapped Model's networks, built again by the caller, each by its name in its
+                    class's 'sources', e.g. classifier=models.vgg11(weights=None); none for every
+                    other Model, which builds its own.
+
+    Returns:
+        the model, on the CPU, or on a wrapped Model's networks' device; 'model.data' holds the
+        saved contract and no datasets, so add new rows with 'data_frame_phase()' or set new
+        datasets before scoring them. Its history is the saved one, then a "load" event naming
+        'path'.
+
+    Note:
+        The model's class must be defined, i.e. its module imported, before it is loaded. A file
+        saved by a pre-release build that kept no history loads with one built from what it held:
+        its arguments, data, and curves; a time or setting it never held reads "not recorded".
+        A pre-release file that kept every argument as given has none reading "(default)".
+        The history's "replace_output", "freeze", and "unfreeze" events are replayed in order
+        before the weights load, so a swapped output layer fits and frozen parts stay frozen.
+        A wrapped Model's networks need only be built as the original was before those changes,
+        e.g. VGG11 with its 1,000 outputs; a saved weight they do not hold, or hold in another
+        shape, fails by name before any weight loads.
+
+    Example:
+        >>> model = model_load("wine_neuron.pt")
+        >>> data_frame_phase(model, "new", new_wines)
+        >>> labels, probabilities = predict_classes(model, "new")
+        >>> vgg = model_load("vgg11_fashion.pt", classifier=models.vgg11(weights=None))
+    """
+    saved = torch.load(path, map_location='cpu', weights_only=True)
+    if 'history' not in saved:
+        saved = _upgraded(saved)
+    name = saved['class']
+    if name not in Model.CLASSES:
+        raise ValueError(
+            f'{path!r} holds a {name!r}, which is not a defined Model class; import its module first'
+        )
+    create = saved['history'][0]
+    if HISTORY_DEFAULTS not in create['hyperparams']:
+        create['hyperparams'] = create['hyperparams'] | {HISTORY_DEFAULTS: {}}
+    cls = Model.CLASSES[name]
+    _check_networks(path, cls, networks)
+    model = cls(**networks, **_arguments(create['hyperparams']))
+    for event in saved['history']:
+        if event['event'] in MODEL_CHANGES:
+            MODEL_CHANGES[event['event']](model, event['hyperparams'])
+    if model.is_external:
+        _check_fit(path, model, saved['weights'])
+    model.load_weights(saved['weights'])
+    data = saved['data']
+    if data is not None:
+        if 'kind' not in data:
+            raise ValueError(
+                f"{path!r} was saved by a pre-release build of mcode-neural, so its data has no 'kind'; re-save it from its Notebook"
+            )
+        frame = data['frame']
+        if frame is not None:
+            frame = frame | {'label_dtype': getattr(torch, frame['label_dtype'])}
+        model.data = Data(
+            data['kind'],
+            {},
+            data['feature'],
+            data['classes'],
+            frame,
+            data['split'],
+        )
+    model.history = saved['history']
+    model._record('load', {'path': str(path)}, {})
+    return model
+
+
+def model_device(fraction=DEVICE_FRACTION):
+    """
+    Returns the device to train on, CUDA when available, else the CPU, and caps this process's GPU memory.
+
+    Args:
+        fraction:   the share of the GPU's memory this process may use, a number above 0 and at
+                    most 1; 'DEVICE_FRACTION', 0.75, leaves the rest to the desktop and other processes.
+
+    Returns:
+        torch.device('cuda', n), the current GPU, or torch.device('cpu') when CUDA is not available.
+
+    Note:
+        On CUDA, PyTorch's memory allocator is capped at 'fraction' of the GPU's memory, so a
+        batch too big raises torch.OutOfMemoryError at once, which 'train_model()' re-raises
+        naming the phase and batch size, instead of spilling into shared system RAM and running
+        many times slower. The cap bounds PyTorch's tensors; the CUDA context, a few hundred MB,
+        sits outside it. PyTorch's cached free blocks are returned to the driver as the cap is
+        set, since a block cached before it could be reused past it. On a CPU no cap is set. It
+        prints the device, and on CUDA the GPU's name,
+        its memory, and the cap, so the Notebook's output records what the run had. Calling it
+        again sets the cap again; a new 'fraction' replaces the old one.
+
+    Example:
+        >>> device = model_device()
+        Device: cuda:0
+           GPU: NVIDIA RTX 2000 Ada Generation Laptop GPU
+        Memory: 8.00 GiB
+           Cap: 6.00 GiB (75%)
+        >>> model = ClassificationModel(in_features=4, hidden_size=(64, 32), out_features=2).to(device)
+    """
+    if (
+        isinstance(fraction, bool)
+        or not isinstance(fraction, numbers.Real)
+        or not 0 < fraction <= 1
+    ):
+        raise ValueError(
+            f"'fraction' must be a number above 0 and at most 1, got {fraction!r}"
+        )
+    if not torch.cuda.is_available():
+        print('Device: cpu')
+        print('   GPU: none; CUDA is not available')
+        return torch.device('cpu')
+
+    device = torch.device('cuda', torch.cuda.current_device())
+    torch.cuda.set_per_process_memory_fraction(fraction, device)
+    torch.cuda.empty_cache()
+    gpu = torch.cuda.get_device_properties(device)
+    total = gpu.total_memory / 2**30
+    print(f'Device: {device}')
+    print(f'   GPU: {gpu.name}')
+    print(f'Memory: {total:.2f} GiB')
+    print(f'   Cap: {fraction * total:.2f} GiB ({fraction:.0%})')
+    return device
+
+
+def model_freeze(model, *parts):
+    """
+    Freezes a network, or named parts of it, so their weights do not train; prints what trains after.
+
+    Args:
+        model:  a PyTorch network: a mcode-neural network Model, e.g. ClassificationModel, or an
+                external network, e.g. torchvision's VGG11.
+        parts:  submodule paths as the code reaches them, e.g. "features" or "classifier[6]"
+                ("classifier.6" reads the same); none freezes the whole network.
+
+    Note:
+        Every parameter of each part is set not to train ('requires_grad' False); an optimizer
+        built over all of 'model.parameters()' then steps only the ones that train. A Model
+        records a "freeze" event, {"parts"} and {"trainable", "total"}, which 'model_load()'
+        replays. 'show_model_trace()' and 'show_model_internals()' mark what trains.
+
+    Example:
+        >>> model_freeze(vgg11)
+        Froze the whole network: 0 of 132,863,336 parameters train
+    """
+    trainable, total = _set_trainable(model, parts, False)
+    named = [_path_text(path) for path in parts]
+    what = ', '.join(named) if named else 'the whole network'
+    print(f'Froze {what}: {trainable:,} of {total:,} parameters train')
+    if isinstance(model, Model):
+        model._record(
+            'freeze', {'parts': named}, {'trainable': trainable, 'total': total}
+        )
+
+
+def model_unfreeze(model, *parts):
+    """
+    Unfreezes a network, or named parts of it, so their weights train again; prints what trains after.
+
+    Args:
+        model:  a PyTorch network, a mcode-neural network Model or an external network.
+        parts:  submodule paths, e.g. "classifier"; none unfreezes the whole network.
+
+    Note:
+        A Model records an "unfreeze" event, as 'model_freeze()' records "freeze".
+
+    Example:
+        >>> model_unfreeze(vgg11)
+        Unfroze the whole network: 128,942,507 of 128,942,507 parameters train
+    """
+    trainable, total = _set_trainable(model, parts, True)
+    named = [_path_text(path) for path in parts]
+    what = ', '.join(named) if named else 'the whole network'
+    print(f'Unfroze {what}: {trainable:,} of {total:,} parameters train')
+    if isinstance(model, Model):
+        model._record(
+            'unfreeze', {'parts': named}, {'trainable': trainable, 'total': total}
+        )
+
+
+def model_replace_output(model, out_features):
+    """
+    Replaces a network's output layer, its last nn.Linear, with a new one of 'out_features' outputs.
+
+    Args:
+        model:          a PyTorch network, a mcode-neural network Model or an external network.
+        out_features:   the new output layer's outputs, e.g. 43 classes; a whole number of at least 1.
+
+    Note:
+        The output layer is the network's last nn.Linear in module order, e.g. VGG's
+        "classifier[6]" or ResNet's "fc"; its path is printed. The new layer keeps its
+        'in_features', bias, device, and dtype, and trains; its weights are new. A Model's Network
+        and Layer views read the new layer, and it records a "replace_output" event,
+        {"out_features"} and {"path", "in_features"}, which 'model_load()' replays before
+        loading the saved weights, so a saved swapped Model loads again.
+
+    Example:
+        >>> model_replace_output(vgg11, 43)
+        Replaced classifier[6]: Linear(4096 -> 1000) with Linear(4096 -> 43)
+    """
+    _parts(model, ())
+    if (
+        isinstance(out_features, bool)
+        or not isinstance(out_features, numbers.Integral)
+        or out_features < 1
+    ):
+        raise ValueError(
+            f"'out_features' must be a whole number of at least 1, got {out_features!r}"
+        )
+    path, old, new = _replace_output(model, out_features)
+    path = _path_text(path)
+    print(
+        f'Replaced {path}: Linear({old.in_features} -> {old.out_features})'
+        f' with Linear({new.in_features} -> {new.out_features})'
+    )
+    if isinstance(model, Model):
+        model._record(
+            'replace_output',
+            {'out_features': int(out_features)},
+            {'path': path, 'in_features': new.in_features},
+        )
+
+
+# endregion
+# endregion
+# endregion