orivex 0.1.0__py3-none-any.whl

orivex/__init__.py

@@ -0,0 +1,49 @@
+"""Better FLACCO: selective and verified exploratory landscape analysis."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from orivex.api import compute, list_features
+from orivex.capabilities import AutogradSupport, FeatureCapability
+from orivex.normalization import YNormalization
+from orivex.result import BackendName, DeviceType, FloatingDType
+from orivex.sample import LandscapeSample, ObjectiveSense, ObjectiveSenseName
+from orivex.specs import (
+    CostModel,
+    CostTier,
+    FeatureSpec,
+    InputRequirement,
+    InvarianceBehavior,
+    InvarianceClaim,
+    MetricKind,
+    Reference,
+    Transformation,
+)
+
+try:
+    __version__ = version("orivex")
+except PackageNotFoundError:  # Running directly from a source checkout.
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AutogradSupport",
+    "BackendName",
+    "CostModel",
+    "CostTier",
+    "DeviceType",
+    "FeatureCapability",
+    "FeatureSpec",
+    "FloatingDType",
+    "InputRequirement",
+    "InvarianceBehavior",
+    "InvarianceClaim",
+    "LandscapeSample",
+    "MetricKind",
+    "ObjectiveSense",
+    "ObjectiveSenseName",
+    "Reference",
+    "Transformation",
+    "YNormalization",
+    "__version__",
+    "compute",
+    "list_features",
+]

orivex/api.py

@@ -0,0 +1,75 @@
+"""Public convenience API backed by the built-in feature engine."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from orivex.engine import Engine
+from orivex.features.distribution import FEATURES as DISTRIBUTION_FEATURES
+from orivex.features.distribution import INTERMEDIATES as DISTRIBUTION_INTERMEDIATES
+from orivex.features.fitness_distance import FEATURES as FITNESS_DISTANCE_FEATURES
+from orivex.features.fitness_distance import INTERMEDIATES as FITNESS_DISTANCE_INTERMEDIATES
+from orivex.features.information_content import FEATURES as INFORMATION_CONTENT_FEATURES
+from orivex.features.information_content import INTERMEDIATES as INFORMATION_CONTENT_INTERMEDIATES
+from orivex.features.meta_model import FEATURES as META_MODEL_FEATURES
+from orivex.features.meta_model import INTERMEDIATES as META_MODEL_INTERMEDIATES
+from orivex.features.nearest_better import FEATURES as NEAREST_BETTER_FEATURES
+from orivex.features.nearest_better import INTERMEDIATES as NEAREST_BETTER_INTERMEDIATES
+from orivex.normalization import YNormalization
+from orivex.options import FeatureOptions
+from orivex.result import ComputationResult
+from orivex.sample import LandscapeSample
+from orivex.specs import FeatureSpec
+
+DEFAULT_ENGINE = Engine(
+    DISTRIBUTION_FEATURES
+    + META_MODEL_FEATURES
+    + INFORMATION_CONTENT_FEATURES
+    + NEAREST_BETTER_FEATURES
+    + FITNESS_DISTANCE_FEATURES,
+    DISTRIBUTION_INTERMEDIATES
+    + META_MODEL_INTERMEDIATES
+    + INFORMATION_CONTENT_INTERMEDIATES
+    + NEAREST_BETTER_INTERMEDIATES
+    + FITNESS_DISTANCE_INTERMEDIATES,
+)
+
+
+def compute(
+    sample: LandscapeSample,
+    features: str | tuple[str, ...] | list[str],
+    *,
+    rng: np.random.Generator | None = None,
+    workers: int = 1,
+    y_normalization: YNormalization = "minmax",
+    options: FeatureOptions | None = None,
+) -> ComputationResult:
+    """Compute features from canonical objectives, min-max normalized by default.
+
+    ``y_normalization`` is ``"minmax"`` (observed range) or ``None`` (raw canonical
+    objectives). Normalized constant objectives map to zero. The original sample is
+    preserved; preprocessing is recorded
+    separately from mathematical feature definitions in result metadata.
+
+    ``options`` is a nested mapping keyed by feature group, for example
+    ``{"fitness_distance": {"proportion_of_best": 0.25}}``. Omit it to use defaults.
+    Unknown groups and option names are rejected. Fitness-distance features always use
+    Euclidean distances to the best selected observation. Effective options are recorded
+    in ``result.metadata.options`` as an immutable snapshot.
+
+    ``workers=1`` is the predictable default. Pass ``-1`` to let supporting kernels use all
+    available CPUs, or a positive integer to set an upper worker count. Kernels that do not
+    support parallel execution ignore this setting.
+    """
+    return DEFAULT_ENGINE.compute(
+        sample,
+        features,
+        rng=rng,
+        workers=workers,
+        y_normalization=y_normalization,
+        options=options,
+    )
+
+
+def list_features() -> tuple[FeatureSpec, ...]:
+    return tuple(DEFAULT_ENGINE.registry.get(name) for name in DEFAULT_ENGINE.registry.names())

orivex/capabilities.py

@@ -0,0 +1,42 @@
+"""Backend-specific feature implementation capabilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from orivex.result import BackendName, DeviceType, FloatingDType
+
+AutogradSupport: TypeAlias = Literal["smooth", "piecewise", "none"]
+
+
+@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")

orivex/engine.py

@@ -0,0 +1,192 @@
+"""Execution of planned feature definitions with shared intermediate caching."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+import numpy as np
+
+from orivex.normalization import YNormalization, normalize_objectives
+from orivex.options import FeatureOptions, resolve_options
+from orivex.planner import IntermediateSpec, Planner
+from orivex.registry import FeatureRegistry
+from orivex.result import ComputationResult, ExecutionMetadata, FeatureStatus, FeatureValue
+from orivex.sample import LandscapeSample
+from orivex.specs import FeatureSpec, InputRequirement
+
+IntermediateValue = object
+
+
+class FeatureUnavailable(ValueError):
+    """A feature is mathematically undefined for an otherwise valid sample."""
+
+
+# Numerical failures that are expected for otherwise valid samples (overflow, underflow, division
+# by an underflowed quantity, singular designs). These are isolated per feature as INVALID results.
+# Programming errors -- TypeError, KeyError, IndexError, AttributeError, and the like -- are not
+# listed and therefore still propagate so that bugs remain distinguishable from numerical failures.
+EXPECTED_NUMERICAL_ERRORS: tuple[type[Exception], ...] = (
+    FeatureUnavailable,
+    ArithmeticError,
+    np.linalg.LinAlgError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _IntermediateFailure:
+    """Marks an intermediate that raised an expected numerical failure.
+
+    Stored in place of a value so that features depending on it (directly or transitively) surface
+    the same failure as an INVALID status instead of terminating the whole request.
+    """
+
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class ComputationContext:
+    sample: LandscapeSample
+    intermediates: Mapping[str, IntermediateValue]
+    rng: np.random.Generator | None
+    workers: int = 1
+    objective_y: np.ndarray | None = None
+    options: FeatureOptions = field(default_factory=resolve_options)
+
+    @property
+    def y(self) -> np.ndarray:
+        """Canonical objectives after the computation's declared preprocessing."""
+        return self.sample.minimization_y if self.objective_y is None else self.objective_y
+
+    def intermediate(self, name: str) -> IntermediateValue:
+        try:
+            value = self.intermediates[name]
+        except KeyError as error:
+            raise RuntimeError(f"intermediate was not planned: {name}") from error
+        if isinstance(value, _IntermediateFailure):
+            raise FeatureUnavailable(value.message)
+        return value
+
+
+FeatureCalculator = Callable[[ComputationContext], float | int]
+IntermediateCalculator = Callable[[ComputationContext], IntermediateValue]
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureDefinition:
+    spec: FeatureSpec
+    calculate: FeatureCalculator
+
+
+@dataclass(frozen=True, slots=True)
+class IntermediateDefinition:
+    spec: IntermediateSpec
+    calculate: IntermediateCalculator
+
+
+class Engine:
+    def __init__(
+        self,
+        features: tuple[FeatureDefinition, ...],
+        intermediates: tuple[IntermediateDefinition, ...],
+    ) -> None:
+        self._feature_definitions: dict[str, FeatureDefinition] = {}
+        for definition in features:
+            if definition.spec.name in self._feature_definitions:
+                raise ValueError(f"feature definition already registered: {definition.spec.name}")
+            self._feature_definitions[definition.spec.name] = definition
+
+        self._intermediate_definitions: dict[str, IntermediateDefinition] = {}
+        for definition in intermediates:
+            if definition.spec.name in self._intermediate_definitions:
+                raise ValueError(
+                    f"intermediate definition already registered: {definition.spec.name}"
+                )
+            self._intermediate_definitions[definition.spec.name] = definition
+
+        self.registry = FeatureRegistry(tuple(item.spec for item in features))
+        self.planner = Planner(
+            self.registry,
+            tuple(item.spec for item in intermediates),
+        )
+
+    def compute(
+        self,
+        sample: LandscapeSample,
+        features: str | tuple[str, ...] | list[str],
+        *,
+        rng: np.random.Generator | None = None,
+        workers: int = 1,
+        y_normalization: YNormalization = "minmax",
+        options: FeatureOptions | None = None,
+    ) -> ComputationResult:
+        options = resolve_options(options)
+        if workers == 0 or workers < -1:
+            raise ValueError("workers must be -1 or a positive integer")
+        sample.validate_unchanged()
+        started = time.perf_counter()
+        plan = self.planner.plan(features)
+        if InputRequirement.RNG in plan.requirements and rng is None:
+            raise ValueError("the requested feature plan requires an explicit numpy Generator")
+
+        objective_y, constant = normalize_objectives(sample.minimization_y, y_normalization)
+
+        cache: dict[str, IntermediateValue] = {}
+        for intermediate in plan.intermediates:
+            context = ComputationContext(
+                sample,
+                MappingProxyType(cache),
+                rng,
+                workers,
+                objective_y,
+                options,
+            )
+            try:
+                cache[intermediate.name] = self._intermediate_definitions[
+                    intermediate.name
+                ].calculate(context)
+            except EXPECTED_NUMERICAL_ERRORS as error:
+                cache[intermediate.name] = _IntermediateFailure(str(error))
+
+        context = ComputationContext(
+            sample,
+            MappingProxyType(cache),
+            rng,
+            workers,
+            objective_y,
+            options,
+        )
+        values: dict[str, FeatureValue] = {}
+        for spec in plan.features:
+            definition = self._feature_definitions[spec.name]
+            try:
+                value = definition.calculate(context)
+                if not np.isfinite(value):
+                    raise FeatureUnavailable("definition produced a non-finite value")
+                values[spec.name] = FeatureValue(
+                    value=value,
+                    status=FeatureStatus.OK,
+                    definition=spec.definition,
+                )
+            except EXPECTED_NUMERICAL_ERRORS as error:
+                values[spec.name] = FeatureValue(
+                    value=None,
+                    status=FeatureStatus.INVALID,
+                    definition=spec.definition,
+                    message=str(error),
+                )
+
+        metadata = ExecutionMetadata(
+            sample_fingerprint=sample.fingerprint,
+            requested_features=plan.feature_names,
+            computed_intermediates=plan.intermediate_names,
+            runtime_seconds=time.perf_counter() - started,
+            additional_objective_evaluations=0,
+            workers=workers,
+            y_normalization=y_normalization,
+            constant_objective=constant,
+            options=options,
+        )
+        return ComputationResult(values, metadata)

orivex/features/__init__.py

@@ -0,0 +1 @@
+"""Built-in feature definitions."""

orivex/features/distribution.py

@@ -0,0 +1,212 @@
+"""Objective-value distribution features compatible with flacco type-3 estimators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from orivex.engine import (
+    ComputationContext,
+    FeatureDefinition,
+    FeatureUnavailable,
+    IntermediateDefinition,
+)
+from orivex.planner import IntermediateSpec
+from orivex.specs import (
+    CostModel,
+    CostTier,
+    FeatureSpec,
+    InputRequirement,
+    InvarianceBehavior,
+    InvarianceClaim,
+    MetricKind,
+    Reference,
+    Transformation,
+)
+
+REFERENCE = Reference(
+    citation="Mersmann et al. (2011), Exploratory Landscape Analysis",
+    doi="10.1145/2001576.2001690",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CenteredObjectives:
+    observations: int
+    values: np.ndarray
+    scale: float
+
+
+def centered_objectives(context: ComputationContext) -> CenteredObjectives:
+    """Mean-centered objectives rescaled to unit maximum magnitude.
+
+    The type-3 skewness and kurtosis are invariant to a positive scaling of the deviations, so the
+    shared moments are accumulated from ``(y - mean) / max|y - mean|`` instead of the raw
+    deviations. The scale cancels analytically in every dependent feature, which keeps the moment
+    sums bounded by the observation count and therefore representable at any finite objective scale.
+    ``scale`` is ``0.0`` exactly for a constant objective.
+    """
+    y = context.y
+    deviations = y - np.mean(y)
+    # Constancy is decided on the objectives directly: a genuinely constant objective can still
+    # acquire tiny nonzero deviations through mean rounding, and rescaling would otherwise amplify
+    # that noise into apparently valid moments.
+    constant = y.size == 0 or bool(np.min(y) == np.max(y))
+    scale = 0.0 if constant else float(np.max(np.abs(deviations)))
+    values = deviations / scale if scale > 0.0 else np.zeros_like(deviations)
+    values.flags.writeable = False
+    return CenteredObjectives(observations=y.size, values=values, scale=scale)
+
+
+CENTERED = IntermediateDefinition(
+    spec=IntermediateSpec(
+        name="y.centered",
+        dependencies=(),
+        requirements=frozenset({InputRequirement.Y}),
+    ),
+    calculate=centered_objectives,
+)
+
+
+def _centered(context: ComputationContext) -> CenteredObjectives:
+    value = context.intermediate("y.centered")
+    if not isinstance(value, CenteredObjectives):
+        raise TypeError("y.centered has an invalid runtime type")
+    return value
+
+
+def sum2(context: ComputationContext) -> float:
+    centered = _centered(context).values
+    return float(centered @ centered)
+
+
+def sum3(context: ComputationContext) -> float:
+    return float(np.sum(_centered(context).values ** 3))
+
+
+def sum4(context: ComputationContext) -> float:
+    return float(np.sum(_centered(context).values ** 4))
+
+
+SUM2 = IntermediateDefinition(
+    IntermediateSpec("y.sum2", ("y.centered",), frozenset()),
+    sum2,
+)
+SUM3 = IntermediateDefinition(
+    IntermediateSpec("y.sum3", ("y.centered",), frozenset()),
+    sum3,
+)
+SUM4 = IntermediateDefinition(
+    IntermediateSpec("y.sum4", ("y.centered",), frozenset()),
+    sum4,
+)
+
+
+def _sum(context: ComputationContext, name: str) -> float:
+    value = context.intermediate(name)
+    if not isinstance(value, float):
+        raise TypeError(f"{name} has an invalid runtime type")
+    return value
+
+
+def skewness_type3(context: ComputationContext) -> float:
+    centered = _centered(context)
+    second = _sum(context, "y.sum2")
+    third = _sum(context, "y.sum3")
+    if centered.observations < 3:
+        raise FeatureUnavailable("type-3 skewness requires at least 3 observations")
+    if centered.scale == 0.0:
+        raise FeatureUnavailable("skewness is undefined for constant objective values")
+    n = centered.observations
+    type1 = np.sqrt(n) * third / second**1.5
+    return float(type1 * ((n - 1) / n) ** 1.5)
+
+
+def kurtosis_type3(context: ComputationContext) -> float:
+    centered = _centered(context)
+    second = _sum(context, "y.sum2")
+    fourth = _sum(context, "y.sum4")
+    if centered.observations < 4:
+        raise FeatureUnavailable("type-3 kurtosis requires at least 4 observations")
+    if centered.scale == 0.0:
+        raise FeatureUnavailable("kurtosis is undefined for constant objective values")
+    n = centered.observations
+    ratio = n * fourth / second**2
+    return float(ratio * (1.0 - 1.0 / n) ** 2 - 3.0)
+
+
+COMMON_INVARIANCES = (
+    InvarianceClaim(
+        Transformation.ROW_PERMUTATION,
+        InvarianceBehavior.INVARIANT,
+        conditions="paired finite observations",
+    ),
+    InvarianceClaim(
+        Transformation.Y_TRANSLATION,
+        InvarianceBehavior.INVARIANT,
+        conditions="finite y with non-zero variance",
+    ),
+    InvarianceClaim(
+        Transformation.Y_POSITIVE_SCALING,
+        InvarianceBehavior.INVARIANT,
+        conditions="finite positive scale and non-zero y variance",
+    ),
+)
+
+
+SKEWNESS = FeatureDefinition(
+    spec=FeatureSpec(
+        name="ela_distr.skewness",
+        group="ela_distr",
+        kind=MetricKind.LANDSCAPE,
+        definition="flacco-type3-v1",
+        summary="Type-3 sample skewness of objective observations under minimization convention.",
+        requirements=frozenset({InputRequirement.Y}),
+        intermediates=("y.sum2", "y.sum3"),
+        cost=CostModel(CostTier.SAMPLE_ONLY, cpu="O(n)", memory="O(n) shared"),
+        deterministic=True,
+        invariances=(
+            *COMMON_INVARIANCES,
+            InvarianceClaim(
+                Transformation.OBJECTIVE_SENSE_REVERSAL,
+                InvarianceBehavior.INVARIANT,
+                conditions="negate y and reverse the declared objective sense together",
+            ),
+        ),
+        references=(REFERENCE,),
+        legacy_names=("ela_distr.skewness",),
+        minimum_observations=3,
+    ),
+    calculate=skewness_type3,
+)
+
+
+KURTOSIS = FeatureDefinition(
+    spec=FeatureSpec(
+        name="ela_distr.kurtosis",
+        group="ela_distr",
+        kind=MetricKind.LANDSCAPE,
+        definition="flacco-type3-v1",
+        summary="Type-3 excess sample kurtosis of objective observations.",
+        requirements=frozenset({InputRequirement.Y}),
+        intermediates=("y.sum2", "y.sum4"),
+        cost=CostModel(CostTier.SAMPLE_ONLY, cpu="O(n)", memory="O(n) shared"),
+        deterministic=True,
+        invariances=(
+            *COMMON_INVARIANCES,
+            InvarianceClaim(
+                Transformation.OBJECTIVE_SENSE_REVERSAL,
+                InvarianceBehavior.INVARIANT,
+                conditions="negate y and reverse the declared objective sense together",
+            ),
+        ),
+        references=(REFERENCE,),
+        legacy_names=("ela_distr.kurtosis",),
+        minimum_observations=4,
+    ),
+    calculate=kurtosis_type3,
+)
+
+FEATURES = (SKEWNESS, KURTOSIS)
+INTERMEDIATES = (CENTERED, SUM2, SUM3, SUM4)