Skip to content

gds_psuu.results

Sweep results and summary types.

Sweep results and summary types.

EvaluationSummary

Bases: BaseModel

Summary of a single evaluation (without raw simulation data).

Source code in packages/gds-psuu/gds_psuu/results.py 
16
17
18
19
20
21
22
class EvaluationSummary(BaseModel):
    """Summary of a single evaluation (without raw simulation data)."""

    model_config = ConfigDict(frozen=True)

    params: ParamPoint
    scores: KPIScores

SweepResults

Bases: BaseModel

Container for all evaluation results from a sweep.

Source code in packages/gds-psuu/gds_psuu/results.py 
25
26
27
28
29
30
31
32
33
34
35
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
88
89
90
class SweepResults(BaseModel):
    """Container for all evaluation results from a sweep."""

    model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)

    evaluations: list[EvaluationResult]
    kpi_names: list[str]
    optimizer_name: str

    @property
    def summaries(self) -> list[EvaluationSummary]:
        """Summaries without raw simulation data."""
        return [
            EvaluationSummary(params=e.params, scores=e.scores)
            for e in self.evaluations
        ]

    def best(self, kpi: str, *, maximize: bool = True) -> EvaluationSummary:
        """Return the evaluation with the best score for the given KPI.

        Args:
            kpi: Name of the KPI to optimize.
            maximize: If True, return the evaluation with the highest score.
        """
        if not self.evaluations:
            raise ValueError("No evaluations to search")
        if kpi not in self.kpi_names:
            raise ValueError(f"KPI '{kpi}' not found in {self.kpi_names}")

        best_eval = max(
            self.evaluations,
            key=lambda e: e.scores[kpi] if maximize else -e.scores[kpi],
        )
        return EvaluationSummary(params=best_eval.params, scores=best_eval.scores)

    def best_by_objective(self, objective: Objective) -> EvaluationSummary:
        """Return the evaluation with the best objective score.

        The objective reduces multiple KPI scores to a single scalar.
        Higher is better.
        """
        if not self.evaluations:
            raise ValueError("No evaluations to search")

        best_eval = max(
            self.evaluations,
            key=lambda e: objective.score(e.scores),
        )
        return EvaluationSummary(params=best_eval.params, scores=best_eval.scores)

    def to_dataframe(self) -> Any:
        """Convert to pandas DataFrame. Requires ``pandas`` installed."""
        try:
            import pandas as pd  # type: ignore[import-untyped]
        except ImportError as exc:  # pragma: no cover
            raise ImportError(
                "pandas is required for to_dataframe(). "
                "Install with: pip install gds-psuu[pandas]"
            ) from exc

        rows: list[dict[str, Any]] = []
        for ev in self.evaluations:
            row: dict[str, Any] = dict(ev.params)
            row.update(ev.scores)
            rows.append(row)
        return pd.DataFrame(rows)

summaries property

Summaries without raw simulation data.

best(kpi, *, maximize=True)

Return the evaluation with the best score for the given KPI.

Parameters:

Name Type Description Default
kpi str

Name of the KPI to optimize.

 required
maximize bool

If True, return the evaluation with the highest score.

 True
Source code in packages/gds-psuu/gds_psuu/results.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def best(self, kpi: str, *, maximize: bool = True) -> EvaluationSummary:
    """Return the evaluation with the best score for the given KPI.

    Args:
        kpi: Name of the KPI to optimize.
        maximize: If True, return the evaluation with the highest score.
    """
    if not self.evaluations:
        raise ValueError("No evaluations to search")
    if kpi not in self.kpi_names:
        raise ValueError(f"KPI '{kpi}' not found in {self.kpi_names}")

    best_eval = max(
        self.evaluations,
        key=lambda e: e.scores[kpi] if maximize else -e.scores[kpi],
    )
    return EvaluationSummary(params=best_eval.params, scores=best_eval.scores)

best_by_objective(objective)

Return the evaluation with the best objective score.

The objective reduces multiple KPI scores to a single scalar. Higher is better.

Source code in packages/gds-psuu/gds_psuu/results.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def best_by_objective(self, objective: Objective) -> EvaluationSummary:
    """Return the evaluation with the best objective score.

    The objective reduces multiple KPI scores to a single scalar.
    Higher is better.
    """
    if not self.evaluations:
        raise ValueError("No evaluations to search")

    best_eval = max(
        self.evaluations,
        key=lambda e: objective.score(e.scores),
    )
    return EvaluationSummary(params=best_eval.params, scores=best_eval.scores)

to_dataframe()

Convert to pandas DataFrame. Requires pandas installed.

Source code in packages/gds-psuu/gds_psuu/results.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def to_dataframe(self) -> Any:
    """Convert to pandas DataFrame. Requires ``pandas`` installed."""
    try:
        import pandas as pd  # type: ignore[import-untyped]
    except ImportError as exc:  # pragma: no cover
        raise ImportError(
            "pandas is required for to_dataframe(). "
            "Install with: pip install gds-psuu[pandas]"
        ) from exc

    rows: list[dict[str, Any]] = []
    for ev in self.evaluations:
        row: dict[str, Any] = dict(ev.params)
        row.update(ev.scores)
        rows.append(row)
    return pd.DataFrame(rows)