CADETProcess.parameter_space.ParameterSpace

class CADETProcess.parameter_space.ParameterSpace

Bases: object

Container for parameters, evaluation objects, constraints, and dependencies.

The space is the interface between an optimizer (or sampler) and a set of model objects. It has two responsibilities: defining the feasible domain and writing a parameter vector x into the evaluation objects.

Typical usage:

space = ParameterSpace()
space.add_evaluation_object(process)
space.add_parameter(
    RangedParameter("length", float, lb=0.1, ub=1.0),
    path="column.length",
)
space.set_values({"length": 0.5})

property A: ndarray

Linear inequality constraint matrix, shape (m, n_parameters).

property A_eq: ndarray

Linear equality constraint matrix, shape (m, n_parameters).

property A_eq_independent: ndarray

Equality constraint matrix sliced to independent columns, shape (m, n_variables).

property A_independent: ndarray

Inequality constraint matrix, independent columns only, shape (m, n_variables).

add_dependency(dependent: ParameterBase, independent_parameters: list[ParameterBase], transform: Callable) → None

Declare that dependent is computed from independent_parameters.

The optimizer sees only independent parameters; set_values resolves dependent parameters before writing. Chains are supported; cycles raise at declaration time.

Note: bounds and linear constraints on dependent cannot be enforced before the transform is evaluated. They are checked lazily in set_values via each parameter’s validate method. See the module docstring for the recommended sampling pattern.

Parameters:

dependentParameterBase

The parameter whose value is computed.

independent_parameterslist[ParameterBase]

Parameters whose values are passed to transform, in order.

transformCallable

Called as transform(*values); must return the value for dependent.

Raises:

ValueError

If dependent already has a dependency declared.

ValueError

If any parameter is not registered with this space.

ValueError

If the dependency would introduce a cycle.

add_evaluation_object(obj: Any) → None

Register an evaluation object with the space.

All subsequent add_parameter calls without an explicit evaluation_objects argument will target this object.

Parameters:

objAny

A picklable model object (process, flowsheet, …).

Raises:

ValueError

If obj is already registered.

add_linear_constraint(constraint: LinearConstraint) → None

Register a linear inequality constraint on independent parameters.

add_linear_equality_constraint(constraint: LinearEqualityConstraint) → None

Register a linear equality constraint on independent parameters.

add_parameter(parameter: ParameterBase, *, path: str | None = None, evaluation_objects: list[Any] | None = None, mapper: ParameterMapperBase | None = None) → None

Register a parameter and wire its mapper.

Exactly one of path or mapper may be supplied. Supplying neither registers a parameter with no write target, which is valid for parameters that only participate in dependency transforms and whose value need not be written to any object.

Parameters:

parameterParameterBase

The parameter to register.

pathstr, optional

Dot-separated attribute/key path. A DotPathMapper is created automatically and targets evaluation_objects (or all registered objects if not specified).

evaluation_objectslist, optional

Subset of evaluation objects this parameter maps to. Only valid together with path.

mapperParameterMapperBase, optional

Pre-built mapper. Use this (or add_parameter_with_callable) when a dot-path is insufficient.

Raises:

ValueError

If a parameter with the same name is already registered.

ValueError

If both path and mapper are supplied.

ValueError

If evaluation_objects is given without path.

ValueError

If evaluation_objects contains objects not registered with the space.

add_parameter_with_callable(parameter: ParameterBase, fn: Callable[[Any, Any], None], *, evaluation_objects: list[Any] | None = None) → None

Register a parameter whose write is handled by a callable.

Convenience wrapper around add_parameter with a CallableMapper.

Parameters:

parameterParameterBase

The parameter to register.

fnCallable[[Any, Any], None]

Called as fn(obj, value) for each evaluation object.

evaluation_objectslist, optional

Subset of evaluation objects to target.

property b: ndarray

Linear inequality constraint RHS in physical coordinates, shape (m,).

property b_eq: ndarray

Linear equality constraint RHS in physical coordinates, shape (m,).

property categorical_parameters: list[ChoiceParameter]

Independent categorical (choice) parameters.

check_bounds(x: ArrayLike, tol: float | ArrayLike = 0.0, *, resolve_dependencies: bool = False) → bool

Return True when all parameters satisfy their bounds.

Parameters:

xarray-like

Full parameter vector (length n_parameters) in physical units. Pass resolve_dependencies=True to expand an independent-only vector (length n_variables) first.

tolfloat or array-like

Per-variable (or uniform) tolerance added to each bound.

Raises:

ValueError

If the length of x does not match n_parameters.

property continuous_parameters: list[RangedParameter]

Independent float-typed parameters.

denormalize(x_norm: ArrayLike) → ndarray

Map normalized values back to the original parameter space.

Bounds are not enforced here; out-of-range normalized values are mapped to their corresponding physical values without raising. This allows check_bounds(x, denormalize=True) to correctly return False for values that are outside the normalized unit hypercube.

denormalizes() → Callable

Adapter for methods that operate on physical coordinates.

The decorated method always receives x in physical units. The decorator adds a denormalize=True entry point that converts normalized coordinates to physical before invoking the method, without changing what the implementation sees or its contract.

Apply to methods that are part of the optimizer-facing interface but implemented by ParameterSpace — i.e., methods that TransformedSpace naturally delegates to with denormalize=True.

The denormalize parameter is injected into the wrapped function’s __signature__ so that help() and IDE introspection show it.

property dependent_parameters: list[ParameterBase]

Parameters that are computed from others, in registration order.

evaluate_bounds(x: ArrayLike, *, resolve_dependencies: bool = False) → ndarray

Return [lb - x, x - ub] over all parameters; positive = bound violation.

Parameters:

xarray-like

Full parameter vector (length n_parameters) in physical units. Pass resolve_dependencies=True to expand an independent-only vector first.

evaluate_linear_constraints(x: ArrayLike, *, resolve_dependencies: bool = False) → ndarray

Return A @ x - b; positive entries mean a constraint violation.

Parameters:

xarray-like

Full parameter vector (length n_parameters) in physical units. Pass resolve_dependencies=True to expand an independent-only vector first.

evaluate_linear_equality_constraints(x: ArrayLike, *, resolve_dependencies: bool = False) → ndarray

Return A_eq @ x - b_eq; non-zero entries mean a constraint violation.

Parameters:

xarray-like

Full parameter vector (length n_parameters) in physical units. Pass resolve_dependencies=True to expand an independent-only vector first.

property evaluation_objects: list[Any]

Registered evaluation objects, in insertion order.

get_dependent_values(x_independent: ArrayLike, *, denormalize: bool = False) → ndarray

Expand independent parameter values to the full parameter vector.

Parameters:

x_independentarray-like

Values for the n_variables independent parameters in physical units. Pass denormalize=True to denormalize from normalized coordinates first.

Returns:

np.ndarray

Full parameter vector of length n_parameters, in registration order (independent parameters first, then dependent parameters resolved from them).

get_value(name: str) → Any

Read the current value of parameter name from its evaluation object.

Returns None when no mapper is wired or the mapper does not support read-back.

Raises:

KeyError

If no parameter named name is registered.

property independent_parameters: list[ParameterBase]

Parameters not dependent on others; these form the optimizer input.

property integer_parameters: list[RangedParameter]

Independent integer-typed parameters.

property linear_constraints: list[LinearConstraint]

Registered linear inequality constraints.

property linear_equality_constraints: list[LinearEqualityConstraint]

Registered linear equality constraints.

property lower_bounds: ndarray

Lower bounds for all parameters (independent + dependent); -inf when unbounded.

property lower_bounds_independent: ndarray

Lower bounds for independent variables only; -inf when unbounded.

property n_parameters: int

Total number of registered parameters (independent + dependent).

property n_variables: int

Number of independent (optimizer-facing) variables.

normalize(x: ArrayLike) → ndarray

Map independent values to [0, 1] using per-parameter normalizers.

ChoiceParameter, integer parameters, and parameters with infinite bounds are returned unchanged. Bounds are not enforced here; this is a coordinate transform utility, not a validation gate. Constraints are not automatically transformed; a linear constraint involving a parameter with a non-linear normalizer becomes non-linear in the normalized space. Full constraint transformation is deferred to TransformedSpace (PARAMETERS.md step 3).

property parameters: list[ParameterBase]

All registered parameters, in insertion order.

resolve(assignment: Mapping[str, Any]) → dict[str, Any]

Resolve a named independent assignment to the full parameter assignment.

Dependent parameter values are computed from the independent values in topological order.

Parameters:

assignmentMapping

Values for the independent parameters by name, in physical units. Order-insensitive; the result is ordered by registration.

Returns:

dict

Values for all parameters (independent and dependent), ordered by registration.

Raises:

TypeError

If assignment is not a Mapping.

ValueError

If assignment contains unknown names, misses an independent parameter, or supplies a value for a dependent parameter.

RuntimeError

If dependency declarations leave a parameter unresolvable.

resolves_dependencies() → Callable

Adapter for methods that operate on a fully resolved parameter vector.

The decorated method always receives a full parameter vector of length n_parameters (independent + dependent). The decorator adds a resolve_dependencies=True entry point that expands an independent- only vector via self.get_dependent_values before invoking the method, without changing what the implementation sees or its contract.

Hot paths that have already resolved dependencies pass the full vector directly (resolve_dependencies=False, the default) to avoid redundant resolution.

The resolve_dependencies parameter is injected into the wrapped function’s __signature__ so that help() and IDE introspection show it.

sample(n: int, seed: int | None = None, pool_size: int = 100000, include_dependent: bool = False) → list[dict[str, Any]]

Draw n feasible samples as named assignments.

Delegates to HopsySampler with the given pool_size. See SamplerBase for the full postprocessing contract (significant-digits snap, integer rounding, categorical merge, dependency resolution, validation).

Parameters:

nint

Number of feasible samples to return.

seedint, optional

Random seed. A random 32-bit seed is drawn when not specified.

pool_sizeint

MCMC steps used to build the candidate pool.

include_dependentbool

When True each assignment includes resolved dependent parameters.

Returns:

list[dict]

n named assignments, each ordered by registration.

Raises:

ValueError

If n feasible samples cannot be found within the pool_size budget.

set_value(name: str, value: Any) → None

Write value directly for a single parameter by name.

Validates the value but does not resolve dependencies. Use set_values to write an entire independent-variable vector with full dependency resolution.

Raises:

KeyError

If no parameter named name is registered.

TypeError, ValueError

If value fails the parameter’s validate check.

set_values(assignment: Mapping[str, Any], *, validate_bounds: bool = False, tol: float | ArrayLike = 0.0) → None

Resolve dependent parameters, validate, and write into evaluation objects.

Validates all parameters (including dependent) via their validate method, so out-of-bounds dependent values raise here even though they are not caught by check_bounds.

Parameters:

assignmentMapping

Values for the independent parameters by name, in physical units. Order-insensitive. Numeric vectors are an encoding owned by TransformedSpace; decode first: space.set_values(space.transformed_space.decode(x)).

validate_boundsbool

When True, check that the resolved values satisfy parameter bounds before writing.

tolfloat or array-like

Per-parameter (or uniform) tolerance added to each bound when validate_bounds is True.

Raises:

TypeError

If assignment is not a Mapping, or a parameter’s validate rejects its resolved value.

ValueError

If assignment violates the input contract (unknown names, missing independent parameters, supplied dependent values), if validate_bounds is True and a bound is violated, or if a parameter’s validate rejects its resolved value.

property transformed_space: TransformedSpace

Normalized optimizer view of this space.

Lazily constructed and cached; invalidated whenever parameters, dependencies, or constraints are added.

property upper_bounds: ndarray

Upper bounds for all parameters (independent + dependent); +inf when unbounded.

property upper_bounds_independent: ndarray

Upper bounds for independent variables only; +inf when unbounded.

validate_x(x: ArrayLike, tol: float = 0.0, tol_eq: float = 1e-06, *, resolve_dependencies: bool = False) → bool | ndarray

Return True if x satisfies bounds and all linear constraints.

Parameters:

xarray-like

Full parameter vector, shape (n_parameters,) for a single point or (m, n_parameters) for a population. Pass resolve_dependencies=True to expand an independent-only 1-D vector first (population input always requires the full vector).

tolfloat

Tolerance applied to bounds and inequality constraints (inclusive).

tol_eqfloat

Tolerance applied to equality constraints.

Returns:

bool or np.ndarray of bool

Scalar for a single point; 1-D boolean array for a population.