Skip to content

Computation

Input and output contract

compute(sample, features, ...) returns a ComputationResult with one entry per resolved feature and separate execution metadata. Features use canonical minimization objectives, min-max normalized by default.

Argument Meaning
sample A validated LandscapeSample
features An exact name, fnmatch glob, or list/tuple of selectors; every selector must match
rng Optional NumPy generator for features that declare an RNG requirement
workers 1 by default; a positive integer or -1 for supporting parallel kernels
y_normalization "minmax" (default) or None to disable normalization
options Optional mapping of feature groups to settings; see fitness-distance options

An unknown selector raises UnknownFeatureSelection. Invalid inputs or options raise errors. A mathematically undefined feature on a valid sample instead produces an invalid value with an explanation. See results.

compute 

compute(
    sample: LandscapeSample,
    features: str | tuple[str, ...] | list[str],
    *,
    rng: 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.

Source code in src/orivex/api.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
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,
    )

list_features() returns the full FeatureSpec tuple for the registered NumPy profile, ordered by feature name. For a readable listing, see the catalogue.

list_features 

list_features() -> tuple[FeatureSpec, ...]
Source code in src/orivex/api.py 
74
75
def list_features() -> tuple[FeatureSpec, ...]:
    return tuple(DEFAULT_ENGINE.registry.get(name) for name in DEFAULT_ENGINE.registry.names())

UnknownFeatureSelection

Bases: RegistryError

Source code in src/orivex/registry.py 
18
19
class UnknownFeatureSelection(RegistryError):
    pass

RegistryError

Bases: ValueError

Base class for feature-registry errors.

Source code in src/orivex/registry.py 
10
11
class RegistryError(ValueError):
    """Base class for feature-registry errors."""

YNormalization module-attribute 

YNormalization: TypeAlias = Literal['minmax'] | None

FeatureOptions module-attribute 

FeatureOptions: TypeAlias = Mapping[
    str, Mapping[str, float]
]