Skip to content

gds_psuu.space

Parameter space definitions for search.

Parameter space definitions for search.

Continuous

Bases: BaseModel

A continuous parameter dimension with min/max bounds.

Source code in packages/gds-psuu/gds_psuu/space.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class Continuous(BaseModel):
    """A continuous parameter dimension with min/max bounds."""

    model_config = ConfigDict(frozen=True)

    min_val: float
    max_val: float

    @model_validator(mode="after")
    def _validate_bounds(self) -> Self:
        if self.min_val >= self.max_val:
            raise PsuuValidationError(
                f"min_val ({self.min_val}) must be less than max_val ({self.max_val})"
            )
        if not math.isfinite(self.min_val) or not math.isfinite(self.max_val):
            raise PsuuValidationError("Bounds must be finite")
        return self

Integer

Bases: BaseModel

An integer parameter dimension with min/max bounds (inclusive).

Source code in packages/gds-psuu/gds_psuu/space.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
class Integer(BaseModel):
    """An integer parameter dimension with min/max bounds (inclusive)."""

    model_config = ConfigDict(frozen=True)

    min_val: int
    max_val: int

    @model_validator(mode="after")
    def _validate_bounds(self) -> Self:
        if self.min_val >= self.max_val:
            raise PsuuValidationError(
                f"min_val ({self.min_val}) must be less than max_val ({self.max_val})"
            )
        return self

Discrete

Bases: BaseModel

A discrete parameter dimension with explicit allowed values.

Source code in packages/gds-psuu/gds_psuu/space.py 
53
54
55
56
57
58
59
60
61
62
63
64
class Discrete(BaseModel):
    """A discrete parameter dimension with explicit allowed values."""

    model_config = ConfigDict(frozen=True)

    values: tuple[Any, ...]

    @model_validator(mode="after")
    def _validate_values(self) -> Self:
        if len(self.values) < 1:
            raise PsuuValidationError("Discrete dimension must have at least 1 value")
        return self

Constraint

Bases: BaseModel, ABC

Base class for parameter space constraints.

Source code in packages/gds-psuu/gds_psuu/space.py 
70
71
72
73
74
75
76
77
class Constraint(BaseModel, ABC):
    """Base class for parameter space constraints."""

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

    @abstractmethod
    def is_feasible(self, point: ParamPoint) -> bool:
        """Return True if the point satisfies this constraint."""

is_feasible(point) abstractmethod

Return True if the point satisfies this constraint.

Source code in packages/gds-psuu/gds_psuu/space.py 
75
76
77
@abstractmethod
def is_feasible(self, point: ParamPoint) -> bool:
    """Return True if the point satisfies this constraint."""

LinearConstraint

Bases: Constraint

Linear inequality constraint: sum(coeff_i * x_i) <= bound.

Source code in packages/gds-psuu/gds_psuu/space.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class LinearConstraint(Constraint):
    """Linear inequality constraint: sum(coeff_i * x_i) <= bound."""

    coefficients: dict[str, float]
    bound: float

    @model_validator(mode="after")
    def _validate_nonempty(self) -> Self:
        if not self.coefficients:
            raise PsuuValidationError(
                "LinearConstraint must have at least 1 coefficient"
            )
        return self

    def is_feasible(self, point: ParamPoint) -> bool:
        total = sum(coeff * point[name] for name, coeff in self.coefficients.items())
        return total <= self.bound

FunctionalConstraint

Bases: Constraint

Arbitrary feasibility predicate over a parameter point.

Source code in packages/gds-psuu/gds_psuu/space.py 
 99
100
101
102
103
104
105
class FunctionalConstraint(Constraint):
    """Arbitrary feasibility predicate over a parameter point."""

    fn: Callable[[ParamPoint], bool]

    def is_feasible(self, point: ParamPoint) -> bool:
        return self.fn(point)

ParameterSpace

Bases: BaseModel

Defines the searchable parameter space as a mapping of named dimensions.

Source code in packages/gds-psuu/gds_psuu/space.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
class ParameterSpace(BaseModel):
    """Defines the searchable parameter space as a mapping of named dimensions."""

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

    params: dict[str, Dimension]
    constraints: tuple[Constraint, ...] = ()

    @model_validator(mode="after")
    def _validate_nonempty(self) -> Self:
        if not self.params:
            raise PsuuValidationError("ParameterSpace must have at least 1 parameter")
        return self

    @model_validator(mode="after")
    def _validate_constraint_params(self) -> Self:
        param_names = set(self.params.keys())
        for constraint in self.constraints:
            if isinstance(constraint, LinearConstraint):
                unknown = set(constraint.coefficients.keys()) - param_names
                if unknown:
                    raise PsuuValidationError(
                        f"LinearConstraint references unknown params: {unknown}"
                    )
        return self

    @property
    def dimension_names(self) -> list[str]:
        """Ordered list of parameter names."""
        return list(self.params.keys())

    def is_feasible(self, point: ParamPoint) -> bool:
        """Check if a parameter point satisfies all constraints."""
        return all(c.is_feasible(point) for c in self.constraints)

    def grid_points(self, n_steps: int) -> list[ParamPoint]:
        """Generate a grid of parameter points.

        For Continuous: ``n_steps`` evenly spaced values between min and max.
        For Integer: all integers in [min_val, max_val] (ignores n_steps).
        For Discrete: all values.

        Points that violate constraints are excluded.
        """
        axes: list[list[Any]] = []
        for dim in self.params.values():
            if isinstance(dim, Continuous):
                if n_steps < 2:
                    raise PsuuValidationError(
                        "n_steps must be >= 2 for Continuous dimensions"
                    )
                step = (dim.max_val - dim.min_val) / (n_steps - 1)
                axes.append([dim.min_val + i * step for i in range(n_steps)])
            elif isinstance(dim, Integer):
                axes.append(list(range(dim.min_val, dim.max_val + 1)))
            elif isinstance(dim, Discrete):
                axes.append(list(dim.values))
        names = self.dimension_names
        all_points = [
            dict(zip(names, combo, strict=True)) for combo in itertools.product(*axes)
        ]
        if self.constraints:
            return [p for p in all_points if self.is_feasible(p)]
        return all_points

dimension_names property

Ordered list of parameter names.

is_feasible(point)

Check if a parameter point satisfies all constraints.

Source code in packages/gds-psuu/gds_psuu/space.py 
139
140
141
def is_feasible(self, point: ParamPoint) -> bool:
    """Check if a parameter point satisfies all constraints."""
    return all(c.is_feasible(point) for c in self.constraints)

grid_points(n_steps)

Generate a grid of parameter points.

For Continuous: n_steps evenly spaced values between min and max. For Integer: all integers in [min_val, max_val] (ignores n_steps). For Discrete: all values.

Points that violate constraints are excluded.

Source code in packages/gds-psuu/gds_psuu/space.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def grid_points(self, n_steps: int) -> list[ParamPoint]:
    """Generate a grid of parameter points.

    For Continuous: ``n_steps`` evenly spaced values between min and max.
    For Integer: all integers in [min_val, max_val] (ignores n_steps).
    For Discrete: all values.

    Points that violate constraints are excluded.
    """
    axes: list[list[Any]] = []
    for dim in self.params.values():
        if isinstance(dim, Continuous):
            if n_steps < 2:
                raise PsuuValidationError(
                    "n_steps must be >= 2 for Continuous dimensions"
                )
            step = (dim.max_val - dim.min_val) / (n_steps - 1)
            axes.append([dim.min_val + i * step for i in range(n_steps)])
        elif isinstance(dim, Integer):
            axes.append(list(range(dim.min_val, dim.max_val + 1)))
        elif isinstance(dim, Discrete):
            axes.append(list(dim.values))
    names = self.dimension_names
    all_points = [
        dict(zip(names, combo, strict=True)) for combo in itertools.product(*axes)
    ]
    if self.constraints:
        return [p for p in all_points if self.is_feasible(p)]
    return all_points