Source code for dendritic_modeling.models.builders

"""Model builders that plugins provide.

:func:`~dendritic_modeling.scripts.script_utils.setup_utils.initialize_model`
builds the encoder, core and decoder named in ``model`` and wraps them for the
task. A plugin can take over building the three components for configurations
it recognises, for example a pretrained backbone whose layers are replaced by
dendritic cores. It registers a model builder:

* ``applies(model_config)`` returns whether the builder handles the
  configuration, usually because a plugin section of it is enabled;
* ``build(model_config)`` returns ``(encoder, core, decoder, encoder_network)``,
  where ``encoder_network`` is the module whose parameters the encoder optimizer
  group trains (often ``encoder`` itself).

``initialize_model`` then wraps the components exactly as for built-in models.
At most one registered builder may apply to a configuration.
"""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass
from typing import Any

from torch import nn

from dendritic_modeling.plugins import load_plugins

ModelComponents = tuple[nn.Module, nn.Module, nn.Module, nn.Module]


@dataclass(frozen=True)
class ModelBuilder:
    """One registered model builder."""

    name: str
    applies: Callable[[Any], bool]
    build: Callable[[Any], ModelComponents]


_BUILDERS: dict[str, ModelBuilder] = {}


[docs] def register_model_builder( name: str, *, applies: Callable[[Any], bool], build: Callable[[Any], ModelComponents], allow_override: bool = False, ) -> None: """Register a builder of the encoder, core and decoder of some models.""" key = str(name).strip().lower() if not key: raise ValueError("model builder name must be non-empty") if not callable(applies) or not callable(build): raise TypeError("applies and build must be callable") if key in _BUILDERS and not allow_override: raise ValueError( f"Model builder {key!r} is already registered; pass allow_override=True " "to replace it" ) _BUILDERS[key] = ModelBuilder(name=key, applies=applies, build=build)
def unregister_model_builder(name: str) -> None: """Remove a registered model builder if present.""" _BUILDERS.pop(str(name).strip().lower(), None) def registered_model_builders() -> list[str]: """Names of the registered model builders, including those of plugins.""" load_plugins() return sorted(_BUILDERS) def resolve_model_builder(model_config: Any) -> ModelBuilder | None: """The registered builder that applies to ``model_config``, or None.""" load_plugins() applicable = [ builder for builder in _BUILDERS.values() if builder.applies(model_config) ] if len(applicable) > 1: names = ", ".join(sorted(builder.name for builder in applicable)) raise ValueError(f"Several model builders apply to this configuration: {names}") return applicable[0] if applicable else None __all__ = [ "ModelBuilder", "ModelComponents", "register_model_builder", "registered_model_builders", "resolve_model_builder", "unregister_model_builder", ]