Skip to content

gds_analysis.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-analysis/gds_analysis/psuu/space.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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-analysis/gds_analysis/psuu/space.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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-analysis/gds_analysis/psuu/space.py 
57
58
59
60
61
62
63
64
65
66
67
68
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

SchemaViolation dataclass

A single incompatibility between a sweep dimension and declared schema.

Source code in packages/gds-analysis/gds_analysis/psuu/space.py 
74
75
76
77
78
79
80
@dataclass(frozen=True)
class SchemaViolation:
    """A single incompatibility between a sweep dimension and declared schema."""

    param: str
    violation_type: str  # "missing_from_schema", "out_of_bounds", "type_mismatch"
    message: str

Constraint

Bases: BaseModel, ABC

Base class for parameter space constraints.

Source code in packages/gds-analysis/gds_analysis/psuu/space.py 
83
84
85
86
87
88
89
90
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-analysis/gds_analysis/psuu/space.py 
88
89
90
@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-analysis/gds_analysis/psuu/space.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
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-analysis/gds_analysis/psuu/space.py 
112
113
114
115
116
117
118
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-analysis/gds_analysis/psuu/space.py 
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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
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

    @classmethod
    def from_parameter_schema(cls, schema: ParameterSchema) -> ParameterSpace:
        """Create a ParameterSpace from a GDS ParameterSchema.

        Maps ParameterDef entries to Dimensions:

        - ``float`` with bounds -> ``Continuous``
        - ``int`` with bounds -> ``Integer``
        - No bounds -> raises ``ValueError`` (bounds required for sweep)
        - Unsupported type -> raises ``TypeError``

        Requires ``gds-framework`` to be installed.
        """
        from gds.parameters import ParameterSchema as _Schema

        if not isinstance(schema, _Schema):
            raise TypeError(f"Expected ParameterSchema, got {type(schema).__name__}")

        params: dict[str, Dimension] = {}
        for name, pdef in schema.parameters.items():
            if pdef.bounds is None:
                raise ValueError(
                    f"Parameter {name!r} has no bounds declared — "
                    f"cannot create sweep dimension without bounds"
                )
            low, high = pdef.bounds
            py_type = pdef.typedef.python_type
            is_float = py_type is float or (
                isinstance(py_type, type) and issubclass(py_type, float)
            )
            is_int = py_type is int or (
                isinstance(py_type, type) and issubclass(py_type, int)
            )
            if is_float:
                params[name] = Continuous(min_val=float(low), max_val=float(high))
            elif is_int:
                params[name] = Integer(min_val=int(low), max_val=int(high))
            else:
                raise TypeError(
                    f"Parameter {name!r} has type {py_type.__name__} — "
                    f"only float and int are supported for automatic "
                    f"dimension creation"
                )
        return cls(params=params)

    def validate_against_schema(self, schema: ParameterSchema) -> list[SchemaViolation]:
        """Check that this space respects the declared parameter schema.

        Returns a list of violations. Empty list means the space is
        compatible with the schema.

        Requires ``gds-framework`` to be installed.
        """
        from gds.parameters import ParameterSchema as _Schema

        if not isinstance(schema, _Schema):
            raise TypeError(f"Expected ParameterSchema, got {type(schema).__name__}")

        violations: list[SchemaViolation] = []

        for name, dim in self.params.items():
            # Check parameter exists in schema
            pdef = schema.parameters.get(name)
            if pdef is None:
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="missing_from_schema",
                        message=(
                            f"Parameter {name!r} is swept but not "
                            f"declared in the schema"
                        ),
                    )
                )
                continue

            # Check type compatibility
            py_type = pdef.typedef.python_type
            if isinstance(dim, Continuous) and py_type is not float:
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="type_mismatch",
                        message=(
                            f"Parameter {name!r}: Continuous dimension "
                            f"but declared type is {py_type.__name__}"
                        ),
                    )
                )
            elif isinstance(dim, Integer) and py_type is not int:
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="type_mismatch",
                        message=(
                            f"Parameter {name!r}: Integer dimension "
                            f"but declared type is {py_type.__name__}"
                        ),
                    )
                )

            # Check bounds compatibility
            if pdef.bounds is not None and isinstance(dim, (Continuous, Integer)):
                schema_low, schema_high = pdef.bounds
                if dim.min_val < schema_low:
                    violations.append(
                        SchemaViolation(
                            param=name,
                            violation_type="out_of_bounds",
                            message=(
                                f"Parameter {name!r}: sweep min "
                                f"{dim.min_val} < declared lower "
                                f"bound {schema_low}"
                            ),
                        )
                    )
                if dim.max_val > schema_high:
                    violations.append(
                        SchemaViolation(
                            param=name,
                            violation_type="out_of_bounds",
                            message=(
                                f"Parameter {name!r}: sweep max "
                                f"{dim.max_val} > declared upper "
                                f"bound {schema_high}"
                            ),
                        )
                    )

            # Check typedef constraint at sweep boundaries
            if pdef.typedef.constraint is not None and isinstance(
                dim, (Continuous, Integer)
            ):
                if not pdef.typedef.check_value(dim.min_val):
                    violations.append(
                        SchemaViolation(
                            param=name,
                            violation_type="out_of_bounds",
                            message=(
                                f"Parameter {name!r}: sweep min "
                                f"{dim.min_val} fails typedef constraint"
                            ),
                        )
                    )
                if not pdef.typedef.check_value(dim.max_val):
                    violations.append(
                        SchemaViolation(
                            param=name,
                            violation_type="out_of_bounds",
                            message=(
                                f"Parameter {name!r}: sweep max "
                                f"{dim.max_val} fails typedef constraint"
                            ),
                        )
                    )

        return violations

dimension_names property

Ordered list of parameter names.

is_feasible(point)

Check if a parameter point satisfies all constraints.

Source code in packages/gds-analysis/gds_analysis/psuu/space.py 
152
153
154
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-analysis/gds_analysis/psuu/space.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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

from_parameter_schema(schema) classmethod

Create a ParameterSpace from a GDS ParameterSchema.

Maps ParameterDef entries to Dimensions:

  • float with bounds -> Continuous
  • int with bounds -> Integer
  • No bounds -> raises ValueError (bounds required for sweep)
  • Unsupported type -> raises TypeError

Requires gds-framework to be installed.

Source code in packages/gds-analysis/gds_analysis/psuu/space.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
@classmethod
def from_parameter_schema(cls, schema: ParameterSchema) -> ParameterSpace:
    """Create a ParameterSpace from a GDS ParameterSchema.

    Maps ParameterDef entries to Dimensions:

    - ``float`` with bounds -> ``Continuous``
    - ``int`` with bounds -> ``Integer``
    - No bounds -> raises ``ValueError`` (bounds required for sweep)
    - Unsupported type -> raises ``TypeError``

    Requires ``gds-framework`` to be installed.
    """
    from gds.parameters import ParameterSchema as _Schema

    if not isinstance(schema, _Schema):
        raise TypeError(f"Expected ParameterSchema, got {type(schema).__name__}")

    params: dict[str, Dimension] = {}
    for name, pdef in schema.parameters.items():
        if pdef.bounds is None:
            raise ValueError(
                f"Parameter {name!r} has no bounds declared — "
                f"cannot create sweep dimension without bounds"
            )
        low, high = pdef.bounds
        py_type = pdef.typedef.python_type
        is_float = py_type is float or (
            isinstance(py_type, type) and issubclass(py_type, float)
        )
        is_int = py_type is int or (
            isinstance(py_type, type) and issubclass(py_type, int)
        )
        if is_float:
            params[name] = Continuous(min_val=float(low), max_val=float(high))
        elif is_int:
            params[name] = Integer(min_val=int(low), max_val=int(high))
        else:
            raise TypeError(
                f"Parameter {name!r} has type {py_type.__name__} — "
                f"only float and int are supported for automatic "
                f"dimension creation"
            )
    return cls(params=params)

validate_against_schema(schema)

Check that this space respects the declared parameter schema.

Returns a list of violations. Empty list means the space is compatible with the schema.

Requires gds-framework to be installed.

Source code in packages/gds-analysis/gds_analysis/psuu/space.py 
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
def validate_against_schema(self, schema: ParameterSchema) -> list[SchemaViolation]:
    """Check that this space respects the declared parameter schema.

    Returns a list of violations. Empty list means the space is
    compatible with the schema.

    Requires ``gds-framework`` to be installed.
    """
    from gds.parameters import ParameterSchema as _Schema

    if not isinstance(schema, _Schema):
        raise TypeError(f"Expected ParameterSchema, got {type(schema).__name__}")

    violations: list[SchemaViolation] = []

    for name, dim in self.params.items():
        # Check parameter exists in schema
        pdef = schema.parameters.get(name)
        if pdef is None:
            violations.append(
                SchemaViolation(
                    param=name,
                    violation_type="missing_from_schema",
                    message=(
                        f"Parameter {name!r} is swept but not "
                        f"declared in the schema"
                    ),
                )
            )
            continue

        # Check type compatibility
        py_type = pdef.typedef.python_type
        if isinstance(dim, Continuous) and py_type is not float:
            violations.append(
                SchemaViolation(
                    param=name,
                    violation_type="type_mismatch",
                    message=(
                        f"Parameter {name!r}: Continuous dimension "
                        f"but declared type is {py_type.__name__}"
                    ),
                )
            )
        elif isinstance(dim, Integer) and py_type is not int:
            violations.append(
                SchemaViolation(
                    param=name,
                    violation_type="type_mismatch",
                    message=(
                        f"Parameter {name!r}: Integer dimension "
                        f"but declared type is {py_type.__name__}"
                    ),
                )
            )

        # Check bounds compatibility
        if pdef.bounds is not None and isinstance(dim, (Continuous, Integer)):
            schema_low, schema_high = pdef.bounds
            if dim.min_val < schema_low:
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="out_of_bounds",
                        message=(
                            f"Parameter {name!r}: sweep min "
                            f"{dim.min_val} < declared lower "
                            f"bound {schema_low}"
                        ),
                    )
                )
            if dim.max_val > schema_high:
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="out_of_bounds",
                        message=(
                            f"Parameter {name!r}: sweep max "
                            f"{dim.max_val} > declared upper "
                            f"bound {schema_high}"
                        ),
                    )
                )

        # Check typedef constraint at sweep boundaries
        if pdef.typedef.constraint is not None and isinstance(
            dim, (Continuous, Integer)
        ):
            if not pdef.typedef.check_value(dim.min_val):
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="out_of_bounds",
                        message=(
                            f"Parameter {name!r}: sweep min "
                            f"{dim.min_val} fails typedef constraint"
                        ),
                    )
                )
            if not pdef.typedef.check_value(dim.max_val):
                violations.append(
                    SchemaViolation(
                        param=name,
                        violation_type="out_of_bounds",
                        message=(
                            f"Parameter {name!r}: sweep max "
                            f"{dim.max_val} fails typedef constraint"
                        ),
                    )
                )

    return violations