Utility Functions

ropt.utils

Optional helpers for scripts and applications that use ropt.

Nothing in ropt calls anything here. Three kinds of helper live here: a check on the options a backend accepts, for code that builds configurations dynamically or checks them before starting a long run; a converter from variable bounds to the scales and offsets that a configuration expects; and escape hatches for problems that come from outside the library.

validate_backend_options

validate_backend_options(
    method: str, options: dict[str, Any] | list[str]
) -> None

Validate the optimizer-specific options for a given method.

method is either "plugin-name/method-name" or just "method-name"; see Plugin Discovery for both forms.

Parameters:

Name	Type	Description	Default
`method`	`str`	The specific optimization method name.	required
`options`	`dict[str, Any] \| list[str]`	The dictionary or a list of strings of options.	required

Raises:

Type	Description
`ValueError`	If the options are not valid for the method.

scales_and_offsets_from_bounds

scales_and_offsets_from_bounds(
    lower_bounds: ArrayLike,
    upper_bounds: ArrayLike,
    target_range: tuple[float, float] = (0.0, 1.0),
) -> tuple[NDArray[np.float64], NDArray[np.float64]]

Derive variable scales and offsets that map bounds onto a target range.

The scales and offsets returned here can be passed straight to the scales and offsets fields of a VariablesConfig object. They define the map \(y = (x - o)/s\) that sends lower_bounds to the start of target_range and upper_bounds to its end, which puts variables of wildly different magnitudes on a common footing for the optimizer.

The bounds must be finite and the ranges must not be empty, since a variable that cannot vary has no scale.

Parameters:

Name	Type	Description	Default
`lower_bounds`	`ArrayLike`	The lower bounds of the variables.	required
`upper_bounds`	`ArrayLike`	The upper bounds of the variables.	required
`target_range`	`tuple[float, float]`	The range to map the bounds onto (default: 0 to 1).	`(0.0, 1.0)`

Returns:

Type	Description
`tuple[NDArray[float64], NDArray[float64]]`	The scales and the offsets.

Raises:

Type	Description
`ValueError`	If the bounds are not finite, or if either range is empty.

restore_keyboard_interrupt

restore_keyboard_interrupt() -> None

Make Ctrl-C interrupt a waiting program again.

Some third-party extension modules set the process-wide SA_RESTART flag on SIGINT when they are imported, after which Ctrl-C no longer breaks into a program that is waiting. This clears the flag, and is a no-op on platforms that do not have one.

Entirely optional: call it at the top of a script, after the imports, only if Ctrl-C stops working. See Keyboard Interrupts.