Utility Functions

Optional helpers for scripts and applications that use ropt. Nothing in ropt calls these. See Plugin Discovery for the plugin queries, Variable scaling for the bounds converter, and Keyboard Interrupts for when the escape hatch is worth reaching for.

ropt.utils also re-exports get_plugin_name, documented with the Plugin Manager.

ropt.utils

Optional helpers for scripts and applications that use ropt.

Nothing in ropt calls anything here. Three kinds of helper live here: queries about the installed plugins, 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, offered because the fix is easy to get wrong and hard to find.

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

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.