Encoders

Select a frozen encoder by name: FeaturesConfig(encoder="uni2") in Python, features.encoder.name in YAML. An encoder is a leaf of the encoder registry: a name plus its params (output_variant, allow_non_recommended_settings). Precision and batch size are execution settings (slide2vec’s ExecutionOptions); Preprocessing controls image geometry.

Encoding methods

• Single encoder — pick one preset from the model zoo below (the common case).

• Composite (multi-encoder) — concatenate several presets into one richer per-position vector: details.

The run’s features are configured by soma.config.FeaturesConfig, which holds the encoder leaf (soma.config.EncoderLeaf) next to slide2vec’s PreprocessingConfig, ExecutionOptions and DenseOptions.

class soma.config.FeaturesConfig(kind='cached', encoder=None, extraction=<factory>, execution=<factory>, dense=None, cache=<factory>, spacing_policy='strict')

Bases: Editable

features: where a run’s features come from (ADR 0019).

kind: cached extracts once; live re-encodes the (augmented) pixels every step (grid shape). encoder: a slide2vec encoder or composite (None when the run is handed its features). extraction, execution and dense are slide2vec’s PreprocessingConfig, ExecutionOptions and DenseOptions, held as given; an unset tiling comes from dense (grid) or the encoder preset. spacing_policy: native_if_coarser reads a coarser sample at its native spacing.

class soma.config.EncoderLeaf(name, params=<factory>)

Bases: Component

The frozen encoder: a slide2vec encoder, or composite for several concatenated.

params are slide2vec’s Model.from_preset keywords (output_variant, allow_non_recommended_settings), or the composite’s members (soma.models.encoders.CompositeParams); the encoders registry validates them.

Model Zoo

Tile encoders are grouped by output dimension. Spacing is in µm/px; multiple dimensions indicate output variants. soma.components("encoders") lists the presets installed in slide2vec’s registry, each with its level; soma list encoders --level tile prints one level.

Tile-level encoders

Preset	Model	Output dim	Spacing
lunit	Lunit ViT-S/8	384	0.5
prost40m	Prost40M	384	0.5
rudolfv2-s	RudolfV 2-S	384 / 768	0.25, 0.5, 1.0, 2.0
conch	CONCH	512	0.5
phikon	Phikon	768	0.5
conchv15	CONCHv1.5	768	0.5
hibou-b	Hibou-B	768	0.5
h0-mini	H0-mini	768 / 1536	0.5
rudolfv2-b	RudolfV 2-B	768 / 1536	0.25, 0.5, 1.0, 2.0
phikonv2	Phikon-v2	1024	0.5
hibou-l	Hibou-L	1024	0.5
uni	UNI	1024	0.5
musk	MUSK	1024 / 2048	0.25, 0.5, 1.0
gpfm	GPFM	1024	0.5
mstar	mSTAR	1024	0.5
isight	iSight	1024	0.5
phaet	Phaet	1024	0.5
virchow	Virchow	1280 / 2560	0.5
virchow2	Virchow2	1280 / 2560	0.25, 0.5, 1.0, 2.0
uni2	UNI2	1536	0.5
gigapath	GigaPath	1536	0.5
h-optimus-0	H-Optimus-0	1536	0.5
h-optimus-1	H-Optimus-1	1536	0.5
rudolfv2	RudolfV 2	1536 / 3072	0.25, 0.5, 1.0, 2.0
mascaret	Mascaret	1536	0.5
mettle	Mettle	1536 / 3072	0.5
midnight	Midnight	3072	0.25, 0.5, 1.0, 2.0
genbio-pathfm	GenBio-PathFM	4608	0.5

Natural-image controls

Non-pathology baselines that share the tile-encoder interface, for measuring how much pathology pretraining contributes. Both are spacing agnostic, with 0.5 µm/px as the default; see Preprocessing for their tile sizes.

Preset	Model	Output dim	Spacing
dinov2-vitb14	DINOv2 ViT-B/14	768	0.5
dinov3-vitb16	DINOv3 ViT-B/16	768	0.5

DINOv3 uses patch_mean pooling by default; select encoder.output_variant: cls for its class-token output.

Slide-level encoders

Preset	Model	Tile encoder	Output dim
gigapath-slide	GigaPath	gigapath	768
titan	TITAN	conchv15	768
prism	PRISM	virchow (cls_patch_mean)	1280
prism2	PRISM2	virchow2 (cls)	2560 (base) / 3072 (diagnostic)
moozy-slide	MOOZY	lunit	768

Patient-level encoders

Preset	Model	Tile encoder	Output dim
moozy	MOOZY	lunit	768

Set features.extraction.tiling.requested_spacing_um explicitly for encoders with multiple recommended spacings. For a single recommended spacing, soma can fill it in. Configuration and runtime validation check the final combination.

Resolving a fixed benchmark MIL recipe

A slide-level benchmark that accepts both tile- and slide-level encoders can use soma.models.encoders.resolve_aggregator() when it builds each ExperimentConfig. The helper returns the supplied aggregator leaf for a tile encoder and None for a slide encoder, allowing the existing slide representation path to pass the embedding directly to the task head. Patient encoders are rejected because their representations are not slide-level.

soma.models.encoders.resolve_aggregator(encoder_name, tile_recipe)

Resolve a slide benchmark’s aggregation mechanism from encoder metadata.

Return type:

Component | None