Degree of Freedom (DOF)#
DOF#
- class blop.ax.dof.DOF(*, name=None, actuator=None)[source]#
Bases:
ABCBase 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
RangeDOFfor continuous parameters orChoiceDOFfor discrete parameters.- Attributes:
- namestr | None
The name of the DOF. Provide a name if the DOF is not an actuator.
- 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
blop.protocols.ActuatorThe protocol for actuators.
RangeDOFFor continuous parameters with bounds.
ChoiceDOFFor discrete parameters with specific values.
Notes
Either
nameoractuatormust be provided, but not both. Ifactuatoris provided, the DOF will be associated with a Bluesky-controllable device and will automatically move during acquisition. If onlynameis provided, the DOF represents a parameter that is controlled externally.
RangeDOF#
- class blop.ax.dof.RangeDOF(*, name=None, actuator=None, bounds, parameter_type, step_size=None, scaling=None)[source]#
Bases:
DOFA 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 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 actuators, see Your first Bayesian optimization with Blop.
ChoiceDOF#
- class blop.ax.dof.ChoiceDOF(*, name=None, actuator=None, values, parameter_type, is_ordered=None, dependent_parameters=None)[source]#
Bases:
DOFA 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)