Skip to content

Results

Inspect the result of an optimization. X contains decision variables and F contains their objective values; persistence has its own reference.

Stable public API. The 1.x compatibility policy defines the supported surface; import from the public facade shown below.

from vamos import OptimizationResult, StudyResult

Understand an optimization result · Quickstart · Save and replay a run · Durable study reports

Do not infer the number or source of returned solutions from population size alone. OptimizationResult.front() Pareto-filters the current top-level F; it does not switch result sources. Consult the algorithm/result-mode contract when choosing between a population, non-dominated results, and an external archive.

VAMOS 1.2.0: front(), best(), top_k() and top_k_report() rank feasible solutions first when the selected rows carry constraint values G (the least violated ones when none is feasible), with feasible_only=False for the objective-only selection. top_k() and top_k_report() default to source="auto", and the knee method is a deprecated alias of balanced_sum that emits a FutureWarning. See Understand an optimization result.

OptimizationResult

Container returned by optimize() with Pareto front data and selection helpers.

Use vamos.ux.api for summaries, plotting, and export helpers.

manifest property

Immutable source manifest when this result was loaded from a run.

best(method='balanced_sum', *, feasible_only=True)

One solution of :meth:front, chosen by method.

balanced_sum (default) minimizes the sum of objectives normalized over the front; balanced minimizes their maximum; min_f1 and min_f2 minimize one objective. knee is a deprecated alias of balanced_sum, not a knee point; use :func:vamos.ux.api.knee_point_scores for a geometric knee. feasible_only is passed to :meth:front.

feasibility()

How many rows of the top-level result are feasible, and the smallest constraint violation among them.

The violation of a row is the sum of the positive parts of its constraint values G, so it is 0 exactly when the row is feasible (g(x) <= 0). min_violation is therefore 0 when some row is feasible; a run without feasible solutions has n_feasible == 0 and the violation of its least violated row. A result without G counts every row as feasible, and an empty one has a min_violation of inf.

front(*, return_indices=False, feasible_only=True)

front(*, return_indices: Literal[False] = False, feasible_only: bool = True) -> NDArray[np.float64] | None
front(*, return_indices: Literal[True], feasible_only: bool = True) -> tuple[NDArray[np.float64], NDArray[np.int_]]

Non-dominated rows of the top-level F, feasible solutions first.

When the result carries constraint values G for its rows, only the feasible rows are Pareto-filtered or, when none is feasible, the least violated ones: the rule the algorithms use for their non-dominated results. feasible_only=False filters every row by F alone, as VAMOS 1.1.0 and earlier did. The indices refer to the top-level X/F arrays.

top_k(k=100, *, source='auto', method='balanced_sum', nondominated_only=True, weights=None, feasible_only=True)

Up to k solutions of source, ranked by method.

source="auto" (default) ranks the external archive when the result has one and the top-level result otherwise; "result", "archive" and "population" select one explicitly. When the source carries constraint values G for its rows, only its feasible rows are ranked or, when none is feasible, the least violated ones; feasible_only=False ranks every row. method="knee" is a deprecated alias of "balanced_sum".

top_k_report(k=100, *, source='auto', method='balanced_sum', nondominated_only=True, weights=None, feasible_only=True)

The :meth:top_k selection as one row per solution, with its objectives and variables.

StudyResult

Bases: Sequence[OptimizationResult]

Container returned by optimize(..., seed=[...]).

The object behaves like a read-only sequence of :class:OptimizationResult while also exposing light-weight aggregation helpers for numeric metrics.

runs property

Return the underlying immutable run collection.

best_run(name, maximize=True)

Return the run with the best value for the named metric.

mean(name)

Return the mean of a numeric metric across runs.

metric_values(name)

Return a float array with the named metric extracted from each run.

std(name, ddof=0)

Return the standard deviation of a numeric metric across runs.

ddof=0 (the default) is the population standard deviation; ddof=1 is the sample standard deviation usually reported across seeds.