Specifications and capabilities

FeatureSpec records feature semantics, definition identifiers, input requirements, shared intermediates, symbolic costs, invariance claims, and references. The catalogue renders registered instances of this model.

Backend-specific execution properties belong to FeatureCapability: supported devices, dtypes, and the declared autograd behavior. They are separate from mathematical definitions.

FeatureSpec dataclass

Complete metadata contract for one individually selectable output.

Source code in src/orivex/specs.py

@dataclass(frozen=True, slots=True)
class FeatureSpec:
    """Complete metadata contract for one individually selectable output."""

    name: str
    group: str
    kind: MetricKind
    definition: str
    summary: str
    requirements: frozenset[InputRequirement]
    intermediates: tuple[str, ...]
    cost: CostModel
    deterministic: bool
    invariances: tuple[InvarianceClaim, ...] = ()
    references: tuple[Reference, ...] = ()
    legacy_names: tuple[str, ...] = ()
    minimum_observations: int = 1
    notes: tuple[str, ...] = field(default_factory=tuple)

    def __post_init__(self) -> None:
        if _FEATURE_ID.fullmatch(self.name) is None:
            raise ValueError(f"invalid feature name: {self.name!r}")
        if not self.group or self.name.split(".", 1)[0] != self.group:
            raise ValueError("feature group must equal the first component of the feature name")
        if _DEFINITION_ID.fullmatch(self.definition) is None:
            raise ValueError(f"invalid definition identifier: {self.definition!r}")
        if not self.summary.strip():
            raise ValueError("feature summary must not be empty")
        if self.kind is MetricKind.LANDSCAPE and InputRequirement.Y not in self.requirements:
            raise ValueError("landscape features must explicitly require objective observations y")
        if self.kind is MetricKind.DESIGN and InputRequirement.X not in self.requirements:
            raise ValueError("design descriptors must explicitly require decision observations X")
        if self.minimum_observations < 1:
            raise ValueError("minimum_observations must be positive")
        if len(set(self.intermediates)) != len(self.intermediates):
            raise ValueError("intermediate identifiers must be unique")
        transformations = [claim.transformation for claim in self.invariances]
        if len(set(transformations)) != len(transformations):
            raise ValueError("a feature may declare at most one claim per transformation")
        if len(set(self.legacy_names)) != len(self.legacy_names):
            raise ValueError("legacy feature names must be unique")

name instance-attribute

name: str

group instance-attribute

group: str

kind instance-attribute

kind: MetricKind

definition instance-attribute

definition: str

summary instance-attribute

summary: str

requirements instance-attribute

requirements: frozenset[InputRequirement]

intermediates instance-attribute

intermediates: tuple[str, ...]

cost instance-attribute

cost: CostModel

deterministic instance-attribute

deterministic: bool

invariances class-attribute instance-attribute

invariances: tuple[InvarianceClaim, ...] = ()

references class-attribute instance-attribute

references: tuple[Reference, ...] = ()

legacy_names class-attribute instance-attribute

legacy_names: tuple[str, ...] = ()

minimum_observations class-attribute instance-attribute

minimum_observations: int = 1

notes class-attribute instance-attribute

notes: tuple[str, ...] = field(default_factory=tuple)

CostModel dataclass

Auditable symbolic cost model for a single feature request.

Source code in src/orivex/specs.py

@dataclass(frozen=True, slots=True)
class CostModel:
    """Auditable symbolic cost model for a single feature request."""

    tier: CostTier
    cpu: str
    memory: str
    additional_objective_evaluations: str = "0"

    def __post_init__(self) -> None:
        if not self.cpu.strip() or not self.memory.strip():
            raise ValueError("CPU and memory cost descriptions must not be empty")
        if not self.additional_objective_evaluations.strip():
            raise ValueError("objective-evaluation cost must not be empty")

tier instance-attribute

tier: CostTier

cpu instance-attribute

cpu: str

memory instance-attribute

memory: str

additional_objective_evaluations class-attribute instance-attribute

additional_objective_evaluations: str = '0'

CostTier

Bases: str, Enum

Coarse cost class used for discovery and safe defaults.

Source code in src/orivex/specs.py

class CostTier(str, Enum):
    """Coarse cost class used for discovery and safe defaults."""

    SAMPLE_ONLY = "sample_only"
    ADDITIONAL_EVALUATIONS = "additional_evaluations"
    OPTIMIZATION = "optimization"

SAMPLE_ONLY class-attribute instance-attribute

SAMPLE_ONLY = 'sample_only'

ADDITIONAL_EVALUATIONS class-attribute instance-attribute

ADDITIONAL_EVALUATIONS = 'additional_evaluations'

OPTIMIZATION class-attribute instance-attribute

OPTIMIZATION = 'optimization'

InputRequirement

Bases: str, Enum

Inputs that a feature or its intermediates require.

Source code in src/orivex/specs.py

class InputRequirement(str, Enum):
    """Inputs that a feature or its intermediates require."""

    X = "x"
    Y = "y"
    BOUNDS = "bounds"
    OBJECTIVE = "objective"
    RNG = "rng"

X class-attribute instance-attribute

X = 'x'

Y class-attribute instance-attribute

Y = 'y'

BOUNDS class-attribute instance-attribute

BOUNDS = 'bounds'

OBJECTIVE class-attribute instance-attribute

OBJECTIVE = 'objective'

RNG class-attribute instance-attribute

RNG = 'rng'

MetricKind

Bases: str, Enum

Whether an output describes a landscape or only its sampling design.

Source code in src/orivex/specs.py

class MetricKind(str, Enum):
    """Whether an output describes a landscape or only its sampling design."""

    LANDSCAPE = "landscape"
    DESIGN = "design"

LANDSCAPE class-attribute instance-attribute

LANDSCAPE = 'landscape'

DESIGN class-attribute instance-attribute

DESIGN = 'design'

InvarianceClaim dataclass

A precise, testable transformation claim.

Source code in src/orivex/specs.py

@dataclass(frozen=True, slots=True)
class InvarianceClaim:
    """A precise, testable transformation claim."""

    transformation: Transformation
    behavior: InvarianceBehavior
    conditions: str = ""
    notes: str = ""

transformation instance-attribute

transformation: Transformation

behavior instance-attribute

behavior: InvarianceBehavior

conditions class-attribute instance-attribute

conditions: str = ''

notes class-attribute instance-attribute

notes: str = ''

InvarianceBehavior

Bases: str, Enum

Declared behavior under a transformation.

Source code in src/orivex/specs.py

class InvarianceBehavior(str, Enum):
    """Declared behavior under a transformation."""

    INVARIANT = "invariant"
    EQUIVARIANT = "equivariant"
    NON_INVARIANT = "non_invariant"
    UNKNOWN = "unknown"

INVARIANT class-attribute instance-attribute

INVARIANT = 'invariant'

EQUIVARIANT class-attribute instance-attribute

EQUIVARIANT = 'equivariant'

NON_INVARIANT class-attribute instance-attribute

NON_INVARIANT = 'non_invariant'

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

Transformation

Bases: str, Enum

Transformations considered by metamorphic verification.

Source code in src/orivex/specs.py

class Transformation(str, Enum):
    """Transformations considered by metamorphic verification."""

    ROW_PERMUTATION = "row_permutation"
    VARIABLE_PERMUTATION = "variable_permutation"
    X_TRANSLATION = "x_translation"
    X_POSITIVE_SCALING = "x_positive_scaling"
    X_ORTHOGONAL_ROTATION = "x_orthogonal_rotation"
    Y_TRANSLATION = "y_translation"
    Y_POSITIVE_SCALING = "y_positive_scaling"
    OBJECTIVE_SENSE_REVERSAL = "objective_sense_reversal"

ROW_PERMUTATION class-attribute instance-attribute

ROW_PERMUTATION = 'row_permutation'

VARIABLE_PERMUTATION class-attribute instance-attribute

VARIABLE_PERMUTATION = 'variable_permutation'

X_TRANSLATION class-attribute instance-attribute

X_TRANSLATION = 'x_translation'

X_POSITIVE_SCALING class-attribute instance-attribute

X_POSITIVE_SCALING = 'x_positive_scaling'

X_ORTHOGONAL_ROTATION class-attribute instance-attribute

X_ORTHOGONAL_ROTATION = 'x_orthogonal_rotation'

Y_TRANSLATION class-attribute instance-attribute

Y_TRANSLATION = 'y_translation'

Y_POSITIVE_SCALING class-attribute instance-attribute

Y_POSITIVE_SCALING = 'y_positive_scaling'

OBJECTIVE_SENSE_REVERSAL class-attribute instance-attribute

OBJECTIVE_SENSE_REVERSAL = 'objective_sense_reversal'

Reference dataclass

Literature or software reference supporting a feature definition.

Source code in src/orivex/specs.py

@dataclass(frozen=True, slots=True)
class Reference:
    """Literature or software reference supporting a feature definition."""

    citation: str
    doi: str | None = None
    url: str | None = None

    def __post_init__(self) -> None:
        if not self.citation.strip():
            raise ValueError("reference citation must not be empty")
        if self.doi is None and self.url is None:
            raise ValueError("reference must provide a DOI or URL")

citation instance-attribute

citation: str

doi class-attribute instance-attribute

doi: str | None = None

url class-attribute instance-attribute

url: str | None = None

FeatureCapability dataclass

Execution properties that belong to an implementation, not its mathematics.

Source code in src/orivex/capabilities.py

@dataclass(frozen=True, slots=True)
class FeatureCapability:
    """Execution properties that belong to an implementation, not its mathematics."""

    feature_name: str
    backend: BackendName
    autograd: AutogradSupport
    devices: tuple[DeviceType, ...]
    dtypes: tuple[FloatingDType, ...]
    notes: tuple[str, ...] = ()

    def __post_init__(self) -> None:
        if not self.feature_name:
            raise ValueError("feature name must not be empty")
        if self.backend not in ("numpy", "torch"):
            raise ValueError(f"unsupported backend: {self.backend!r}")
        if self.autograd not in ("smooth", "piecewise", "none"):
            raise ValueError(f"unsupported autograd support: {self.autograd!r}")
        if not self.devices:
            raise ValueError("at least one device type is required")
        if not self.dtypes:
            raise ValueError("at least one floating dtype is required")
        if any(device not in ("cpu", "cuda", "mps") for device in self.devices):
            raise ValueError(f"unsupported device types: {self.devices!r}")
        if any(dtype not in ("float32", "float64") for dtype in self.dtypes):
            raise ValueError(f"unsupported floating dtypes: {self.dtypes!r}")
        if len(set(self.devices)) != len(self.devices):
            raise ValueError("device types must be unique")
        if len(set(self.dtypes)) != len(self.dtypes):
            raise ValueError("floating dtypes must be unique")

feature_name instance-attribute

feature_name: str

backend instance-attribute

backend: BackendName

autograd instance-attribute

autograd: AutogradSupport

devices instance-attribute

devices: tuple[DeviceType, ...]

dtypes instance-attribute

dtypes: tuple[FloatingDType, ...]

notes class-attribute instance-attribute

notes: tuple[str, ...] = ()

AutogradSupport module-attribute

AutogradSupport: TypeAlias = Literal[
    "smooth", "piecewise", "none"
]