Ax Degree of Freedom (DOF)

DOF

class bluesky_adaptive.ax.dof.DOF(*, name=None, actuator=None)

Bases: ABC

Base class for a degree of freedom (DOF) to optimize.

A DOF represents a controllable input parameter in the optimization problem. DOFs define the search space that the optimizer explores to find optimal solutions. Use RangeDOF for continuous parameters or ChoiceDOF for discrete parameters.

Attributes:

namestr | None

The name of the DOF.

actuatorActuator | str | None

The actuator or its name to use for the DOF. Provide an actuator if the DOF is controllable by Bluesky.

See also

bluesky_adaptive.protocols.Actuator

The protocol for actuators.

RangeDOF

For continuous parameters with bounds.

ChoiceDOF

For discrete parameters with specific values.

Notes

If actuator is an Actuator device instance, the DOF will be associated with a Bluesky-controllable device and will automatically move during acquisition. If only name is provided, the DOF represents a parameter that is controlled externally. Both name and actuator can be provided, but only if both are strings. This is necessary when using bluesky-queueserver which requires actuator to be the Python variable name for the device instance and name is the device.name. When both actuator and name are specified, the Ax parameter name will be name.

name: str | None = None

actuator: MovableHasName | Flyable | str | None = None

property parameter_name: str

The parameter name used internally by Ax.

abstractmethod to_ax_parameter_config()

Convert the data class to Ax configuration.

RangeDOF

class bluesky_adaptive.ax.dof.RangeDOF(*, name=None, actuator=None, bounds, parameter_type, step_size=None, scaling=None)

Bases: DOF

A degree of freedom that is a continuous range.

Use this class for continuous parameters that can take any value within specified bounds, such as motor positions, voltages, or temperatures.

Attributes:

boundstuple[float, float]

The search domain of the DOF as (lower_bound, upper_bound).

parameter_typeLiteral[“float”, “int”]

The data type of the DOF. Use “float” for continuous values or “int” for integer values.

step_sizefloat | None, optional

The step size of the DOF. If provided, the optimizer will only suggest values at multiples of this step size.

scalingLiteral[“linear”, “log”] | None, optional

The scaling of the DOF. Use “log” for parameters that span orders of magnitude.

Examples

Define a continuous DOF with a name (for non-actuator parameters):

>>> from bluesky_adaptive.ax.dof import RangeDOF
>>> dof = RangeDOF(name="voltage", bounds=(-10.0, 10.0), parameter_type="float")

Define an integer DOF with a step size:

>>> dof = RangeDOF(name="num_exposures", bounds=(1, 100), parameter_type="int", step_size=1)

For examples with actuators, see Your first Bayesian optimization with Bluesky Adaptive.

bounds: tuple[float, float]

parameter_type: Literal['float', 'int']

step_size: float | None = None

scaling: Literal['linear', 'log'] | None = None

to_ax_parameter_config()

Convert the DOF to the Ax parameter configuration equivalent.

Returns:

RangeParameterConfig

The Ax parameter configuration for this DOF.

actuator: MovableHasName | Flyable | str | None = None

name: str | None = None

property parameter_name: str

The parameter name used internally by Ax.

ChoiceDOF

class bluesky_adaptive.ax.dof.ChoiceDOF(*, name=None, actuator=None, values, parameter_type, is_ordered=None, dependent_parameters=None)

Bases: DOF

A degree of freedom that is a discrete choice.

Use this class for categorical or ordinal parameters that can only take on specific discrete values, such as filter selections, detector modes, or beam energies from a fixed set.

Attributes:

valueslist[float] | list[int] | list[str] | list[bool]

The possible discrete values of the DOF.

parameter_typeLiteral[“float”, “int”, “str”, “bool”]

The data type of the DOF.

is_orderedbool | None, optional

Whether the values are ordered. If not provided, it will be inferred from the values. Set to True for ordinal parameters (e.g., [“low”, “medium”, “high”]).

dependent_parametersMapping[TParameterValue, Sequence[str]] | None, optional

Specify which other DOFs are active dependent on specific values of this DOF.

Examples

Define a choice DOF for selecting a filter:

>>> from bluesky_adaptive.ax.dof import ChoiceDOF
>>> dof = ChoiceDOF(name="filter", values=["none", "Al", "Si"], parameter_type="str")

Define an ordered choice DOF:

>>> dof = ChoiceDOF(name="power", values=[1, 2, 5, 10], parameter_type="int", is_ordered=True)

values: list[float] | list[int] | list[str] | list[bool]

parameter_type: Literal['float', 'int', 'str', 'bool']

is_ordered: bool | None = None

dependent_parameters: Mapping[int | float | str | bool, Sequence[str]] | None = None

to_ax_parameter_config()

Convert the DOF to the Ax parameter configuration equivalent.

Returns:

ChoiceParameterConfig

The Ax parameter configuration for this DOF.

actuator: MovableHasName | Flyable | str | None = None

name: str | None = None

property parameter_name: str

The parameter name used internally by Ax.