tensor-ee 0.1.0__py3-none-any.whl

tensor_ee/__init__.py

@@ -0,0 +1,28 @@
+"""Experimental PyTorch-compatible building blocks for native Earth Engine."""
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _distribution_version
+
+try:
+    __version__ = _distribution_version("tensor-ee")
+except _PackageNotFoundError:
+    __version__ = "0.1.0"  # Source checkouts need no installed distribution metadata.
+
+from .comparison import PixelTensor, compare_segmentation
+from .compatibility import CompatibilityReport, check_compatibility
+from .compiler import CompiledModel, Grid, Raster, UnsupportedOperation, WeightProvider, compile_model
+from .primitives import (concatenate, conv2d, eval_dropout, from_image, gelu, leaky_relu, nearest_upsample,
+                         pool2d, relu, residual_add, sigmoid, silu, softmax, tanh)
+from .outputs import SegmentationOutputs, binary_threshold, segmentation_outputs
+from .weight_assets import FeatureCollectionWeightProvider, effective_convolutions, export_weights
+from .weight_mapping import MatchedWeightProvider
+
+__all__ = [
+    "PixelTensor", "compare_segmentation",
+    "CompatibilityReport", "check_compatibility",
+    "CompiledModel", "Grid", "Raster", "UnsupportedOperation", "WeightProvider",
+    "compile_model", "from_image", "conv2d", "pool2d", "nearest_upsample",
+    "concatenate", "residual_add", "relu", "sigmoid", "leaky_relu", "silu", "gelu", "tanh", "eval_dropout", "softmax",
+    "SegmentationOutputs", "segmentation_outputs", "binary_threshold",
+    "FeatureCollectionWeightProvider", "MatchedWeightProvider",
+    "effective_convolutions", "export_weights",
+]

tensor_ee/_swin_parameters.py

@@ -0,0 +1,304 @@
+"""Local accounting and exact asset record mapping for the Swin-UPerNet composites.
+
+The fixed Swin-T224 adapter (``tensor_ee.swin``) and workflow (``tensor_ee.swin_workflow``)
+use ``SwinTParameters`` and the loaders here, at Swin-T224's settings. The schema, the
+checkpoint mapping, the parameter checks and the weight records also take a
+``SwinUPerNetConfig`` (``tensor_ee.models.swin_t224.configuration``; default ``SWIN_T224``):
+``parameter_records`` yields the ``ConvolutionWeights`` records of any configuration, under
+the timm and SMP names the composites' loader (``with_manifest``) reads, in the v2 manifest
+format (``native_ee_featurecollection_weights_v2``) that ``export_weights`` writes.
+Swin-T224's 189 records are unchanged."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import io
+import json
+from pathlib import Path
+import re
+from typing import Any, Literal, Mapping
+
+import numpy as np
+import torch
+
+from .core.errors import UnsupportedOperation
+from .models.swin_t224.configuration import DEPTHS, SWIN_T224, SwinUPerNetConfig, block_shifts
+from .weights.assets import ConvolutionWeights, FeatureCollectionWeightProvider
+from .weights.constants import ServerArray
+
+ENC_PREFIX = "encoder.model."
+PE_PREFIX = ENC_PREFIX + "patch_embed."
+ENCODER_NAME = "tu-swin_tiny_patch4_window7_224"
+
+
+def parameter_shapes(config: SwinUPerNetConfig = SWIN_T224):
+    """Complete inference schema in the historical three-map layouts (encoder groups, patch
+    embedding, decoder, BatchNorm counters): ``config.parameter_shapes()``; Swin-T224's by
+    default."""
+    return config.parameter_shapes()
+
+
+def encoder_prefix(group):
+    if group.startswith("pm"):
+        return f"layers.{int(group[2:])}.downsample."
+    s, b = group[1:].split("b")
+    return f"layers.{int(s)-1}.blocks.{b}."
+
+
+def checkpoint_shapes(config: SwinUPerNetConfig = SWIN_T224):
+    """The SMP UPerNet checkpoint's tensor shapes (``encoder.model.layers_{s}...``,
+    ``encoder.model.patch_embed.*`` with the Conv2d weight [embed_dim, bands, patch, patch],
+    the decoder and head, and the BatchNorm counters)."""
+    enc, pe, dec, counters = parameter_shapes(config)
+    out = {ENC_PREFIX + encoder_prefix(g).replace("layers.", "layers_", 1) + n: shape
+           for g, params in enc.items() for n, shape in params.items()}
+    conv = (config.embed_dim, config.in_chans, config.patch, config.patch)
+    out.update({PE_PREFIX+n: (conv if n == "proj.weight" else shape) for n, shape in pe.items()})
+    out.update(dec)
+    out.update(counters)
+    return out
+
+
+def _sha(value, name):
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None:
+        raise UnsupportedOperation(f"{name} must be a lowercase SHA-256 digest")
+
+
+def _model(config: SwinUPerNetConfig) -> str:
+    """The model's name in messages: "fixed Swin-T" (Swin-T224, the historical messages) or
+    "configured Swin-UPerNet"."""
+    return "fixed Swin-T" if config == SWIN_T224 else "configured Swin-UPerNet"
+
+
+def validate_state(state, config: SwinUPerNetConfig = SWIN_T224):
+    shapes = checkpoint_shapes(config)
+    if not isinstance(state, Mapping) or set(state) != set(shapes):
+        got = set(state) if isinstance(state, Mapping) else set()
+        raise UnsupportedOperation(f"{_model(config)} checkpoint keys differ: missing={sorted(set(shapes)-got)}, extra={sorted(got-set(shapes))}")
+    for k, shape in shapes.items():
+        v = state[k]
+        if not isinstance(v, torch.Tensor) or tuple(v.shape) != shape:
+            raise UnsupportedOperation(f"{k}: expected tensor shape {shape}")
+        if k.endswith("num_batches_tracked"):
+            if v.dtype != torch.int64 or v.item() < 0:
+                raise UnsupportedOperation(f"{k}: expected a nonnegative int64 BatchNorm counter")
+        elif v.dtype != torch.float32 or not torch.isfinite(v).all():
+            raise UnsupportedOperation(f"{k}: expected finite float32 coefficients")
+
+
+def read_state(checkpoint: Path, expected_checkpoint_sha256: str):
+    _sha(expected_checkpoint_sha256, "expected_checkpoint_sha256")
+    # An open file can still be changed in place. Hash and deserialize one
+    # immutable snapshot so the verified digest binds the returned coefficients.
+    source_data = Path(checkpoint).read_bytes()
+    if hashlib.sha256(source_data).hexdigest() != expected_checkpoint_sha256:
+        raise UnsupportedOperation("checkpoint SHA-256 differs from expected_checkpoint_sha256")
+    checkpoint_data = torch.load(io.BytesIO(source_data), map_location="cpu", weights_only=True)
+    if not isinstance(checkpoint_data, Mapping) or "model_state_dict" not in checkpoint_data:
+        raise UnsupportedOperation("expected checkpoint with model_state_dict")
+    state = checkpoint_data["model_state_dict"]
+    validate_state(state)
+    return state
+
+
+def parameters_from_state(state, config: SwinUPerNetConfig = SWIN_T224):
+    """Re-key only, preserving all coefficient values and original flatten order. The
+    patch embedding's Conv2d weight becomes [embed_dim, bands x patch^2], flattened
+    (c, ky, kx)."""
+    validate_state(state, config)
+    enc_shapes, _, _, _ = parameter_shapes(config)
+    enc, pe, dec = {g: {} for g in enc_shapes}, {}, {}
+    for k, tensor in state.items():
+        if k.endswith("num_batches_tracked"):
+            continue
+        v = tensor.detach().cpu().numpy().copy()
+        if k.startswith(PE_PREFIX):
+            n = k[len(PE_PREFIX):]
+            pe[n] = v.reshape(config.embed_dim, config.patch_columns) if n == "proj.weight" else v
+        elif k.startswith(ENC_PREFIX):
+            stage, rest = k[len(ENC_PREFIX+"layers_"):].split(".", 1)
+            if rest.startswith("blocks."):
+                b, n = rest[len("blocks."):].split(".", 1)
+                enc[f"s{int(stage)+1}b{b}"][n] = v
+            else:
+                enc[f"pm{int(stage)}"][rest[len("downsample."):]] = v
+        else:
+            dec[k] = v
+    return enc, pe, dec
+
+
+def _validate_map(values, shapes, name, model="fixed Swin-T"):
+    if not isinstance(values, Mapping) or set(values) != set(shapes):
+        raise UnsupportedOperation(f"{name}: {model} parameter names differ")
+    for k, shape in shapes.items():
+        value = values[k]
+        if isinstance(value, ServerArray):
+            # Decoder asset convolutions use the historical flattened [Cout,Cin*k*k] record.
+            accepted = ((shape[0], int(np.prod(shape[1:]))),) if len(shape) == 4 else (shape,)
+            if tuple(value.shape) not in accepted:
+                raise UnsupportedOperation(f"{name}.{k}: expected shape {shape}")
+        elif not isinstance(value, np.ndarray) or value.shape != shape or value.dtype != np.float32 or not np.isfinite(value).all():
+            raise UnsupportedOperation(f"{name}.{k}: expected finite float32 array of shape {shape}")
+
+
+def validate_parameters(encoder, patch, decoder, config: SwinUPerNetConfig = SWIN_T224) -> None:
+    """The parameter checks: the three maps hold exactly the configuration's names (the
+    encoder groups without a final norm), each a finite float32 NumPy array of its schema
+    shape or a ``ServerArray`` of that shape (a convolution as [Cout, Cin k k])."""
+    enc, pe, dec, _ = parameter_shapes(config)
+    model = _model(config)
+    if not isinstance(encoder, Mapping) or set(encoder) != set(enc):
+        raise UnsupportedOperation(f"encoder: {model} groups differ (raw C4 has no final norm)")
+    for g in enc:
+        _validate_map(encoder[g], enc[g], g, model)
+    _validate_map(patch, pe, "patch_embed", model)
+    _validate_map(decoder, dec, "decoder", model)
+
+
+@dataclass(frozen=True)
+class SwinTParameters:
+    """Validated Swin-T224 parameters: the fixed adapter's and workflow's input."""
+
+    encoder: Mapping[str, Mapping[str, np.ndarray | ServerArray]]
+    patch_embed: Mapping[str, np.ndarray | ServerArray]
+    decoder: Mapping[str, np.ndarray | ServerArray]
+    checkpoint_sha256: str
+    manifest_sha256: str | None = None
+
+    def __post_init__(self):
+        self.validate()
+
+    def validate(self):
+        _sha(self.checkpoint_sha256, "checkpoint_sha256")
+        if self.manifest_sha256 is not None:
+            _sha(self.manifest_sha256, "manifest_sha256")
+        validate_parameters(self.encoder, self.patch_embed, self.decoder, SWIN_T224)
+
+
+def records_and_locations(encoder, patch, decoder):
+    """The existing row/chunk/record format, with each source tensor's read location."""
+    records, locations = {}, {}
+    groups = [(g, p, encoder_prefix(g)) for g, p in encoder.items()]
+    groups += [("patch_embed", patch, "patch_embed."), ("decoder", decoder, "")]
+    for group, params, prefix in groups:
+        for n, value in params.items():
+            base = n.removesuffix(".bias")
+            weight_name = base + ".weight"
+            if n.endswith(".bias") and weight_name in params and params[weight_name].ndim >= 2:
+                key, part = prefix+base, "bias"
+            elif value.ndim == 1:
+                key, part = prefix+n, "vector"
+            elif n.endswith(".weight"):
+                key, part = prefix+n.removesuffix(".weight"), "weight"
+            else:
+                key, part = prefix+n, "matrix"
+            locations[(group,n)] = (key, part, value.shape)
+            if part == "bias":
+                continue
+            matrix = value.reshape(1,-1) if part == "vector" else value.reshape(value.shape[0],-1)
+            bias = params.get(n.removesuffix(".weight")+".bias") if part == "weight" else None
+            if key in records:
+                raise UnsupportedOperation(f"duplicate parameter record {key}")
+            records[key] = ConvolutionWeights(key, matrix.copy(), None if bias is None else bias.copy(), "float32", prefix+n)
+    return records, locations
+
+
+def parameter_records(encoder, patch, decoder, config: SwinUPerNetConfig = SWIN_T224) -> list[ConvolutionWeights]:
+    """The ``ConvolutionWeights`` records of a configuration's local parameters, for
+    ``export_weights`` (a v2 manifest) and ``with_manifest`` (the composites' loader).
+
+    The three maps are the historical layouts (``parameters_from_state``): encoder groups
+    ``s{s}b{b}`` / ``pm{n}`` with timm names, the patch embedding, and the decoder and head
+    with SMP names. They must pass ``validate_parameters`` for ``config`` and be NumPy arrays
+    (server arrays cannot be re-exported). The records are ``records_and_locations``'s, in
+    the maps' order: for Swin-T224 exactly ``swin_workflow.weight_records``'s 189. No
+    requests occur."""
+    validate_parameters(encoder, patch, decoder, config)
+    maps = [*encoder.values(), patch, decoder]
+    if any(not isinstance(value, np.ndarray) for values in maps for value in values.values()):
+        raise UnsupportedOperation("parameter_records requires local NumPy parameters, without a manifest")
+    records, _ = records_and_locations(encoder, patch, decoder)
+    return list(records.values())
+
+
+def with_manifest(encoder, patch, decoder, manifest, checkpoint_sha256):
+    if not isinstance(manifest, Mapping) or manifest.get("source_checkpoint_sha256") != checkpoint_sha256:
+        raise UnsupportedOperation("manifest source_checkpoint_sha256 differs from the checkpoint")
+    if manifest.get("format") != "native_ee_featurecollection_weights_v2" or manifest.get("status") != "ready":
+        raise UnsupportedOperation("a completed native_ee_featurecollection_weights_v2 manifest is required")
+    records, locations = records_and_locations(encoder, patch, decoder)
+    layers = manifest.get("layers")
+    if not isinstance(layers, Mapping) or set(layers) != set(records):
+        raise UnsupportedOperation("manifest must account for every fixed Swin-T record exactly once")
+    for key, record in records.items():
+        meta = layers[key]
+        if not isinstance(meta, Mapping) or (meta.get("shape") != list(record.shape) or meta.get("dtype") != "float32"
+            or meta.get("bias") is not (record.bias is not None) or meta.get("sha256") != record.sha256):
+            raise UnsupportedOperation(f"manifest record {key}: shape/dtype/bias/fingerprint differs from checkpoint")
+        assets = meta.get("assets")
+        if not isinstance(assets, list) or not assets or any(not isinstance(v,str) or not v for v in assets) or len(set(assets)) != len(assets):
+            raise UnsupportedOperation(f"manifest record {key}: explicit unique asset IDs are required")
+    listing = json.dumps(sorted((key, r.sha256) for key,r in records.items()), separators=(",",":"))
+    if manifest.get("manifest_hash") != hashlib.sha256(listing.encode()).hexdigest():
+        raise UnsupportedOperation("manifest_hash differs from the exact parameter record listing")
+    provider = FeatureCollectionWeightProvider(manifest)
+    arrays = {k: provider.arrays(k) for k in records}
+    output = {g:{} for g in encoder}
+    output.update(patch_embed={},decoder={})
+    for (g,n),(key,part,shape) in locations.items():
+        weight, bias = arrays[key]
+        if part == "bias":
+            array = bias.reshape(list(shape))
+        elif part == "vector":
+            array = weight.reshape(list(shape))
+        else:
+            array = weight
+            shape = tuple(records[key].shape)
+        output[g][n] = ServerArray(array,shape)
+    sha = hashlib.sha256(json.dumps(manifest,sort_keys=True,separators=(",",":"),allow_nan=False).encode()).hexdigest()
+    return {g:output[g] for g in encoder},output['patch_embed'],output['decoder'],sha
+
+
+def load_swin_t224_parameters(checkpoint: Path, *, expected_checkpoint_sha256: str,
+                             manifest: Mapping[str, Any] | None = None) -> SwinTParameters:
+    state = read_state(checkpoint, expected_checkpoint_sha256)
+    enc, pe, dec = parameters_from_state(state)
+    manifest_sha = None
+    if manifest is not None:
+        enc, pe, dec, manifest_sha = with_manifest(enc, pe, dec, manifest, expected_checkpoint_sha256)
+    return SwinTParameters(enc, pe, dec, expected_checkpoint_sha256, manifest_sha)
+
+
+def build_model(state, attention="default"):
+    """Strict local reference model; no download, EE initialization, or forward pass."""
+    if attention not in ("default","explicit"):
+        raise UnsupportedOperation("attention must be 'default' or 'explicit'")
+    validate_state(state)
+    import segmentation_models_pytorch as smp
+    # Construction must not round the checkpoint through an ambient half dtype
+    # or place the reference on an ambient accelerator default device.
+    with torch.device("cpu"):
+        model = smp.UPerNet(encoder_name=ENCODER_NAME, encoder_weights=None, in_channels=2, classes=2).float()
+    model.load_state_dict(state, strict=True)
+    model = model.eval()
+    shifts = block_shifts(8,8)
+    for s in range(4):
+        stage = getattr(model.encoder.model,f"layers_{s}")
+        if len(stage.blocks) != DEPTHS[s]:
+            raise UnsupportedOperation("installed model does not implement the fixed Swin-T depths")
+        for block, shift in zip(stage.blocks,shifts[s]):
+            if block.shift_size != (shift,shift) or block.window_size != (7,7):
+                raise UnsupportedOperation("installed model window/shift differs from fixed Swin-T224")
+            if (not isinstance(block.mlp.act,torch.nn.GELU) or block.mlp.act.approximate != 'none'
+                or block.norm1.eps != 1e-5 or block.norm2.eps != 1e-5):
+                raise UnsupportedOperation("installed model GELU/LayerNorm differs from fixed Swin-T224")
+            if attention == "explicit":
+                block.attn.fused_attn = False
+    return model
+
+
+def load_swin_t224_model(checkpoint: Path, *, expected_checkpoint_sha256: str,
+                        attention: Literal["default", "explicit"] = "default") -> torch.nn.Module:
+    if attention not in ("default", "explicit"):
+        raise UnsupportedOperation("attention must be 'default' or 'explicit'")
+    return build_model(read_state(checkpoint,expected_checkpoint_sha256),attention)

tensor_ee/blocks/raster/__init__.py

@@ -0,0 +1,36 @@
+"""Raster-layout (R) blocks of the native EE library: the CNN path's compute blocks.
+
+- ``conv``: ``conv2d``;
+- ``pooling``: ``pool2d``;
+- ``resample``: ``nearest_upsample``;
+- ``merge``: ``concatenate``, ``residual_add``;
+- ``activations``: ``relu``, ``sigmoid``, ``leaky_relu``, ``silu``, ``gelu``, ``tanh``,
+  ``eval_dropout``, ``common_score_mask``, ``softmax``;
+- ``outputs``: ``segmentation_outputs``, ``binary_threshold``.
+
+Each module declares ``METADATA`` (locality, policy, cost and status per block,
+docs/library-contract.md section 9). Every block takes a keyword-only
+``policy=`` that defaults to, and only accepts, ``float32_operands`` (section 7).
+
+These are the blocks themselves. ``compile_model`` materializes each node with
+``.toFloat()``, and the public ``tensor_ee`` primitives wrap the same blocks
+with that materialization; neither cast is inside a block.
+
+Modules here import only the standard library, ``ee``, NumPy, torch (the blocks
+take PyTorch modules and options), ``tensor_ee.core``, ``tensor_ee.layouts``
+and ``tensor_ee.weights``. Nothing here imports a research folder, the
+converter (``compiler``, ``semantics``, ...) or the models.
+"""
+
+from .conv import conv2d
+from .pooling import pool2d
+from .resample import nearest_upsample
+from .merge import concatenate, residual_add
+from .activations import (common_score_mask, eval_dropout, gelu, leaky_relu, relu, sigmoid, silu,
+                          softmax, tanh)
+from .outputs import SegmentationOutputs, binary_threshold, segmentation_outputs
+
+__all__ = ["conv2d", "pool2d", "nearest_upsample", "concatenate", "residual_add",
+           "relu", "sigmoid", "leaky_relu", "silu", "gelu", "tanh", "eval_dropout",
+           "common_score_mask", "softmax",
+           "SegmentationOutputs", "segmentation_outputs", "binary_threshold"]

tensor_ee/blocks/raster/activations.py

@@ -0,0 +1,183 @@
+"""R pointwise activations, the common score mask and channel softmax.
+
+Moved whole from ``tensor_ee.compiler``, where they were private:
+``_relu``, ``_sigmoid``, ``_leaky_relu``, ``_silu``, ``_gelu``, ``_tanh``,
+``_eval_dropout``, ``_common_score_mask`` and ``_softmax`` are here ``relu``,
+``sigmoid``, ``leaky_relu``, ``silu``, ``gelu``, ``tanh``, ``eval_dropout``,
+``common_score_mask`` and ``softmax``. Their helpers moved with them:
+``_sigmoid_image``, ``_real_option``, ``_FLOAT32_MAX``, ``_exact_gelu`` and
+``_dropout_probability``. The old names are re-exports of these objects.
+
+Precision policy ``float32_operands`` (contract section 7): scalars are exact
+binary64 (``_ee_scalar``); softmax keeps its ``toDouble()`` score widening; the
+node output is materialized with ``.toFloat()`` by the caller
+(``compile_model`` or the ``tensor_ee.primitives`` facade), not here.
+
+``_finish`` and ``_ee_scalar`` are module-level bindings that these functions
+look up (tests/test_pointwise_operators.py patches them here).
+"""
+
+from __future__ import annotations
+
+import math
+from numbers import Real
+from typing import Any
+
+import ee
+import torch
+
+from ...core.errors import UnsupportedOperation
+from ...core.grid import Grid
+from ...core.metadata import ANY_SETTINGS, BlockMetadata, Locality, Validated, validate_metadata
+from ...core.precision import FLOAT32_OPERANDS, validate_policy
+from ...core.precision import exact_scalar as _ee_scalar
+from ...core.tensor import Raster
+from ...layouts.raster import finish as _finish
+from .conv import _no_coefficients
+
+
+def relu(raster: Raster, *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    return _finish(raster.image.max(0), raster.bands, raster.grid, clip_footprints)
+
+
+def _sigmoid_image(image: ee.Image) -> ee.Image:
+    # Stable algebraic form avoids exp overflow for very negative logits.
+    magnitude = image.abs().multiply(-1).exp()
+    positive = magnitude.add(1).pow(-1)
+    negative = magnitude.divide(magnitude.add(1))
+    return positive.where(image.lt(0), negative)
+
+
+def sigmoid(raster: Raster, *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    return _finish(_sigmoid_image(raster.image), raster.bands, raster.grid, clip_footprints)
+
+
+_FLOAT32_MAX = float(torch.finfo(torch.float32).max)
+
+
+def _real_option(value: Any, name: str, *, float32: bool = False) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise UnsupportedOperation(f"{name} must be a static finite real scalar; received {value!r}")
+    try:
+        number = float(value)
+    except (OverflowError, ValueError) as error:
+        raise UnsupportedOperation(f"{name} must be finite; received {value!r}") from error
+    if not math.isfinite(number):
+        raise UnsupportedOperation(f"{name} must be finite; received {value!r}")
+    if float32:
+        if abs(value) > _FLOAT32_MAX:
+            raise UnsupportedOperation(f"{name} must be representable in float32; received {value!r}")
+        rounded = torch.tensor(number, dtype=torch.float32).item()
+        if value != 0 and rounded == 0:
+            raise UnsupportedOperation(f"{name} must be representable in float32; received {value!r}")
+        number = rounded
+    return number
+
+
+def _exact_gelu(approximate: Any) -> None:
+    if not isinstance(approximate, str) or approximate != "none":
+        raise UnsupportedOperation(f"approximate must be 'none'; received {approximate!r}")
+
+
+def _dropout_probability(p: Any) -> float:
+    probability = _real_option(p, "p")
+    if not 0 <= p <= 1:
+        raise UnsupportedOperation(f"p must satisfy 0 <= p <= 1; received {p!r}")
+    return probability
+
+
+def leaky_relu(raster: Raster, negative_slope: float = 0.01,
+               *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    slope = _real_option(negative_slope, "negative_slope", float32=True)
+    image = raster.image.where(raster.image.lt(0), raster.image.multiply(_ee_scalar(slope)))
+    return _finish(image, raster.bands, raster.grid, clip_footprints)
+
+
+def silu(raster: Raster, *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    # Both sigmoid branches use exp(-abs(x)); no positive exponent can overflow.
+    sigmoid = _sigmoid_image(raster.image)
+    return _finish(raster.image.multiply(sigmoid), raster.bands, raster.grid, clip_footprints)
+
+
+def gelu(raster: Raster, *, approximate: str = "none",
+         clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    _exact_gelu(approximate)
+    # Established Swin expression: double work, one float32 materialization at
+    # the public/compiler boundary. No intermediate x*x or positive exponent.
+    image = raster.image.multiply(0.5).multiply(
+        raster.image.multiply(math.sqrt(0.5)).erf().add(1))
+    return _finish(image, raster.bands, raster.grid, clip_footprints)
+
+
+def tanh(raster: Raster, *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    return _finish(raster.image.tanh(), raster.bands, raster.grid, clip_footprints)
+
+
+def eval_dropout(raster: Raster, *, p: float = 0.5,
+                 clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    _dropout_probability(p)
+    return _finish(raster.image, raster.bands, raster.grid, clip_footprints)
+
+
+def common_score_mask(image: ee.Image, grid: Grid, *, policy: str = FLOAT32_OPERANDS) -> ee.Image:
+    """Intersect every score mask and finite float32 predicate before reduction.
+
+    This is the existing _valid_logits predicate in a recipe-free core path.
+    Parsing FLOAT32_MAX avoids EE's integral-valued literal clipping.
+    """
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    masks = image.mask().reduce(ee.Reducer.min()).gt(0)
+    finite = image.eq(image).And(image.abs().lte(_ee_scalar(_FLOAT32_MAX))).reduce(ee.Reducer.min())
+    return masks.And(finite).unmask(0, sameFootprint=False).And(grid.mask())
+
+
+def softmax(raster: Raster, *, clip_footprints: bool = False, policy: str = FLOAT32_OPERANDS) -> Raster:
+    validate_policy(policy, allowed=FLOAT32_OPERANDS)
+    if (not raster.bands or any(not isinstance(name, str) or not name for name in raster.bands)
+            or len(set(raster.bands)) != len(raster.bands)):
+        raise UnsupportedOperation("softmax requires nonempty unique channel names")
+    image = raster.image.select(list(raster.bands))
+    image = image.updateMask(common_score_mask(image, raster.grid)).toDouble()
+    maximum = image.reduce(ee.Reducer.max())
+    exponential = image.subtract(maximum).exp()
+    normalized = exponential.divide(exponential.reduce(ee.Reducer.sum()))
+    return _finish(normalized, raster.bands, raster.grid, clip_footprints)
+
+
+# ---------------------------------------------------------------------------
+# Locality and cost metadata (contract section 9)
+# ---------------------------------------------------------------------------
+_SWEEPS = ("docs/evidence/t02-operators.json", "docs/evidence/t05-primary.json")
+
+_UNCLIPPED = Validated(({"clip_footprints": (False,)},))
+"""The blocks only the CNN operator validation, segmentation output validation and trained-model preservation sweeps cover: their slopes, probabilities and inputs
+varied, but ``clip_footprints`` never left False. The ResNet18 runs, which the other R blocks
+cite, used True (resnet18_full64_float32_policy.json)."""
+
+
+def _pointwise(name: str, evidence: tuple[str, ...], validated: Validated = ANY_SETTINGS) -> BlockMetadata:
+    return BlockMetadata(name=name, layout_in="R", layout_out="R", locality=Locality.POINTWISE,
+                         policy=FLOAT32_OPERANDS, embedded_constants=_no_coefficients,
+                         asset_arrays=_no_coefficients, status="Ready", evidence=evidence, validated=validated)
+
+
+METADATA = validate_metadata({
+    "relu": _pointwise("relu", ("docs/history/cnn/results/parity.json", "docs/history/cnn/results/resnet18_full64_float32_policy.json",
+                                "docs/history/cnn/results/segwater_js_parity_1x1.json")),
+    "sigmoid": _pointwise("sigmoid", ("docs/history/cnn/results/parity.json", "docs/history/cnn/results/resnet18_full64_float32_policy.json")),
+    "leaky_relu": _pointwise("leaky_relu", _SWEEPS, _UNCLIPPED),
+    "silu": _pointwise("silu", _SWEEPS, _UNCLIPPED),
+    "gelu": _pointwise("gelu", _SWEEPS, _UNCLIPPED),
+    "tanh": _pointwise("tanh", _SWEEPS, _UNCLIPPED),
+    "eval_dropout": _pointwise("eval_dropout", _SWEEPS, _UNCLIPPED),
+    # A single-band 0/1 validity mask on the raster's grid.
+    "common_score_mask": _pointwise("common_score_mask", ("docs/evidence/t03-outputs.json",)),
+    "softmax": _pointwise("softmax", ("docs/evidence/t03-outputs.json", "docs/evidence/t05-primary.json"), _UNCLIPPED),
+})