Degree of Freedom (DOF)#

DOF#

class blop.ax.dof.DOF(*, name=None, movable=None)[source]

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. Provide a name if the DOF is not movable.

movableNamedMovable | None

The movable to use for the DOF. Provide a movable if the DOF is movable by Bluesky.

See also

RangeDOF

For continuous parameters with bounds.

ChoiceDOF

For discrete parameters with specific values.

Notes

Either name or movable must be provided, but not both. If movable is provided, 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.

name: str | None = None
movable: NamedMovable | None = None
property parameter_name: str
abstractmethod to_ax_parameter_config()[source]

RangeDOF#

class blop.ax.dof.RangeDOF(*, name=None, movable=None, bounds, parameter_type, step_size=None, scaling=None)[source]

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-movable parameters):

>>> from blop.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 movable devices, see Run a simple experiment with Bluesky.

bounds: tuple[float, float]
parameter_type: Literal['float', 'int']
step_size: float | None = None
scaling: Literal['linear', 'log'] | None = None
to_ax_parameter_config()[source]

Convert the DOF to the Ax parameter configuration equivalent.

Returns:
RangeParameterConfig

The Ax parameter configuration for this DOF.

movable: NamedMovable | None = None
name: str | None = None
property parameter_name: str

ChoiceDOF#

class blop.ax.dof.ChoiceDOF(*, name=None, movable=None, values, parameter_type, is_ordered=None, dependent_parameters=None)[source]

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 blop.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()[source]

Convert the DOF to the Ax parameter configuration equivalent.

Returns:
ChoiceParameterConfig

The Ax parameter configuration for this DOF.

movable: NamedMovable | None = None
name: str | None = None
property parameter_name: str
On this page

This Page