Skip to content

Models API

Use load_model to load a local backbone, pretraining, or classifier checkpoint in Python. For complete analysis workflows and automatic model downloads, use the analysis guides.

from porefm.models import load_model

model = load_model("backbone.pt", model_type="backbone", device="cpu")
print(model.preprocessing)

By default the model is in evaluation mode with gradients disabled. For training, pass for_training=True when loading; calling model.train() alone does not re-enable gradients. Datasets can use model.preprocessing to match the checkpoint's signal processing; see preprocessing.

Single-file zero-shot and prototype bundles are loaded through their respective CLI commands. See model selection.

porefm.models.load_model(checkpoint_path, *, model_type='auto', add_signal_cross_attn=None, include_ema=None, classifier_signal_source=None, for_training=False, device='cpu')

Construct a PoreFM model directly from one trusted checkpoint path.

Parameters

checkpoint_path : str or pathlib.Path Pretraining, classifier, or backbone checkpoint. Checkpoints are loaded with pickle enabled and must therefore come from a trusted source. model_type : {"auto", "backbone", "pretraining", "classifier"}, default="auto" Model to construct. "auto" restores the complete declared model; "backbone" extracts only the shared backbone from any supported PoreFM checkpoint. add_signal_cross_attn : bool or None, default=None Preserve the checkpoint topology when None. False omits the signal-query-to-base cross-attention tower and contextual_ts while retaining base-query-to-signal attention and contextual base outputs. A tower absent from the checkpoint cannot be enabled. include_ema : bool or None, default=None For a pretraining model, None preserves the checkpoint's EMA setting and False omits the EMA encoder and latent head. Classifier inference omits auxiliary pretraining/EMA modules by default; passing True restores them when compatible weights are present. Backbones never construct EMA modules. classifier_signal_source : {"auto", "contextual_ts", "fixed_sa_ts"} or None Optional classifier-only signal source override. A classifier that requires contextual_ts cannot disable signal-to-base attention. for_training : bool, default=False If false, return an evaluation-mode model with gradients disabled. If true, return training mode with constructor-defined gradient settings, including a frozen EMA target. device : str or torch.device, default="cpu" Device receiving the constructed model after CPU checkpoint loading.

Returns

torch.nn.Module An :class:ONTBackbone, :class:ONTModelForPreTraining, or :class:ONTModelForClassification according to model_type. model.preprocessing holds the resolved signal contract for use with datasets/readers, or None for checkpoints without identifying metadata. Signal workflows require an identified contract.

Raises

ValueError If a requested component was not trained in the checkpoint or an option combination is incompatible with the requested model. RuntimeError If required checkpoint parameters are missing or unrelated unexpected parameters remain after applying an intentional topology reduction.