CADETProcess.metric_space.MetricSpace

class CADETProcess.metric_space.MetricSpace

Bases: object

Collection of metric declarations with problem-level annotations.

Parallel to ParameterSpace on the output side: owns direction, normalization, and constraint annotations. Purely declarative; it performs no evaluation and holds no reference to an evaluation backend.

Typical usage:

metric_space = MetricSpace()
metric_space.add_objective(Metric("yield", n_metrics=2), minimize=False)
metric_space.add_constraint("purity", bound=0.95, comparison_operator="ge")

add_constraint(metric: Metric | str, bound: float | ArrayLike = 0.0, comparison_operator: Literal['le', 'ge'] = 'le') → Constraint

Annotate a metric with an operator/bound constraint.

Parameters:

metricMetric or str

A new metric (registered on the fly) or the name of a registered one.

boundfloat or array-like

Constraint bound; scalar or one per metric entry.

comparison_operator{“le”, “ge”}

Direction of the comparison.

Returns:

Constraint

The constraint annotation.

add_metric(metric: Metric | str, normalizer: NormalizerBase | None = None) → Metric

Register a metric declaration without annotations.

Parameters:

metricMetric or str

The declaration to register. A string is shorthand for a scalar Metric(name).

normalizerNormalizerBase, optional

Output normalizer for this metric.

Returns:

Metric

The registered metric.

Raises:

ValueError

If a metric with the same name is already registered.

add_objective(metric: Metric | str, minimize: bool = True) → Objective

Annotate a metric with an optimization direction.

Parameters:

metricMetric or str

A new metric (registered on the fly) or the name of a registered one.

minimizebool

Optimization direction; True minimizes, False maximizes.

Returns:

Objective

The direction annotation.

Raises:

ValueError

If the metric already has a direction annotation.

property constraint_labels: list[str]

Flattened labels across all constraints.

property constraint_names: list[str]

Names of all metrics with a constraint annotation.

property constraints: list[Constraint]

All constraint annotations.

property constraints_bounds: ndarray

Flattened bounds across all constraints.

denormalize(results: Mapping[str, Any]) → dict[str, ndarray]

Validate results and map metric values back to physical space.

Metrics without a registered normalizer pass through unchanged.

property labels: list[str]

Flattened labels across all registered metrics.

property metric_names: list[str]

Names of all registered metrics.

property metrics: list[Metric]

All registered metrics.

property metrics_dict: dict[str, Metric]

Registered metrics keyed by name.

property minimize: ndarray

Direction per scalar objective entry; True minimizes.

property n_constraints: int

Total number of scalar constraint entries.

property n_metrics: int

Total number of scalar entries across all registered metrics.

property n_objectives: int

Total number of scalar objective entries.

normalize(results: Mapping[str, Any]) → dict[str, ndarray]

Validate results and map metric values to normalized space.

Metrics without a registered normalizer pass through unchanged.

property objective_labels: list[str]

Flattened labels across all objectives.

property objective_names: list[str]

Names of all metrics with a direction annotation.

property objectives: list[Objective]

All direction annotations.

set_normalizer(metric: Metric | str, normalizer: NormalizerBase) → None

Attach an output normalizer to a registered metric.

validate(results: Mapping[str, Any]) → dict[str, ndarray]

Validate evaluation results against the declared metrics.

Every registered metric must be present with its declared shape. Extra keys (pipeline intermediates) are ignored.

Returns:

dict[str, np.ndarray]

Declared metrics in canonical shape, in registration order.

Raises:

ValueError

If a declared metric is missing or has the wrong shape.