Skip to content

Results and metadata

ComputationResult.values is a read-only mapping from resolved feature names to FeatureValue objects. NumPy computations return floating-point scalars; Torch computations return scalar tensors. A mathematically undefined output has value=None, status=INVALID, and a message.

FeatureValue.definition identifies the mathematical definition. ExecutionMetadata records input and preprocessing fingerprints, options, requested features, evaluated intermediates, runtime, additional objective evaluations, and backend execution details.

Use the preprocessing fingerprint together with feature definitions and execution options for result caching. See results and provenance.

ComputationResult dataclass

Bases: Generic[FeatureScalar]

Source code in src/orivex/result.py 
90
91
92
93
94
95
96
@dataclass(frozen=True, slots=True)
class ComputationResult(Generic[FeatureScalar]):
    values: Mapping[str, FeatureValue[FeatureScalar]]
    metadata: ExecutionMetadata

    def __post_init__(self) -> None:
        object.__setattr__(self, "values", MappingProxyType(dict(self.values)))

values instance-attribute 

values: Mapping[str, FeatureValue[FeatureScalar]]

metadata instance-attribute 

metadata: ExecutionMetadata

FeatureValue dataclass

Bases: Generic[FeatureScalar]

Source code in src/orivex/result.py 
28
29
30
31
32
33
@dataclass(frozen=True, slots=True)
class FeatureValue(Generic[FeatureScalar]):
    value: FeatureScalar | None
    status: FeatureStatus
    definition: str
    message: str | None = None

value instance-attribute 

value: FeatureScalar | None

status instance-attribute 

status: FeatureStatus

definition instance-attribute 

definition: str

message class-attribute instance-attribute 

message: str | None = None

FeatureStatus

Bases: str, Enum

Source code in src/orivex/result.py 
21
22
23
24
25
class FeatureStatus(str, Enum):
    OK = "ok"
    UNAVAILABLE = "unavailable"
    INVALID = "invalid"
    ERROR = "error"

OK class-attribute instance-attribute 

OK = 'ok'

UNAVAILABLE class-attribute instance-attribute 

UNAVAILABLE = 'unavailable'

INVALID class-attribute instance-attribute 

INVALID = 'invalid'

ERROR class-attribute instance-attribute 

ERROR = 'error'

ExecutionMetadata dataclass

Source code in src/orivex/result.py 
36
37
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@dataclass(frozen=True, slots=True)
class ExecutionMetadata:
    sample_fingerprint: str
    requested_features: tuple[str, ...]
    computed_intermediates: tuple[str, ...]
    runtime_seconds: float
    additional_objective_evaluations: int
    warnings: tuple[str, ...] = ()
    workers: int = 1
    backend: BackendName = "numpy"
    device: DeviceType = "cpu"
    device_index: int | None = None
    dtype: FloatingDType = "float64"
    y_normalization: YNormalization = None
    constant_objective: bool = False
    options: FeatureOptions = field(default_factory=resolve_options)

    @property
    def y_normalization_definition(self) -> str:
        return normalization_definition(self.y_normalization)

    @property
    def preprocessing_fingerprint(self) -> str:
        """Cache-key component identifying raw input, backend, dtype, and preprocessing.

        A full result cache must additionally include feature definitions and execution options.
        """
        identity = (
            self.sample_fingerprint,
            self.backend,
            self.dtype,
            self.y_normalization_definition,
        )
        return hashlib.sha256("\0".join(identity).encode("utf-8")).hexdigest()

    def __post_init__(self) -> None:
        normalization_definition(self.y_normalization)
        object.__setattr__(self, "options", resolve_options(self.options))
        if self.runtime_seconds < 0:
            raise ValueError("runtime_seconds must not be negative")
        if self.additional_objective_evaluations < 0:
            raise ValueError("additional objective evaluations must not be negative")
        if self.workers == 0 or self.workers < -1:
            raise ValueError("workers must be -1 or a positive integer")
        if self.backend not in ("numpy", "torch"):
            raise ValueError(f"unsupported backend: {self.backend!r}")
        if self.device not in ("cpu", "cuda", "mps"):
            raise ValueError(f"unsupported device type: {self.device!r}")
        if self.device_index is not None and self.device_index < 0:
            raise ValueError("device index must not be negative")
        if self.dtype not in ("float32", "float64"):
            raise ValueError(f"unsupported floating dtype: {self.dtype!r}")

sample_fingerprint instance-attribute 

sample_fingerprint: str

requested_features instance-attribute 

requested_features: tuple[str, ...]

computed_intermediates instance-attribute 

computed_intermediates: tuple[str, ...]

runtime_seconds instance-attribute 

runtime_seconds: float

additional_objective_evaluations instance-attribute 

additional_objective_evaluations: int

warnings class-attribute instance-attribute 

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

workers class-attribute instance-attribute 

workers: int = 1

backend class-attribute instance-attribute 

backend: BackendName = 'numpy'

device class-attribute instance-attribute 

device: DeviceType = 'cpu'

device_index class-attribute instance-attribute 

device_index: int | None = None

dtype class-attribute instance-attribute 

dtype: FloatingDType = 'float64'

y_normalization class-attribute instance-attribute 

y_normalization: YNormalization = None

constant_objective class-attribute instance-attribute 

constant_objective: bool = False

options class-attribute instance-attribute 

options: FeatureOptions = field(
    default_factory=resolve_options
)

y_normalization_definition property 

y_normalization_definition: str

preprocessing_fingerprint property 

preprocessing_fingerprint: str

Cache-key component identifying raw input, backend, dtype, and preprocessing.

A full result cache must additionally include feature definitions and execution options.

BackendName module-attribute 

BackendName: TypeAlias = Literal['numpy', 'torch']

DeviceType module-attribute 

DeviceType: TypeAlias = Literal['cpu', 'cuda', 'mps']

FloatingDType module-attribute 

FloatingDType: TypeAlias = Literal['float32', 'float64']