Degree of Freedom (DOF)¶

class blop.dofs.DOF(name=None, description='', type='continuous', search_domain=(-inf, inf), trust_domain=None, domain=None, active=True, read_only=False, transform=None, movable=None, device=None, tags=None, travel_expense=1, units=None)[source]

Bases: object

A degree of freedom (DOF), to be used by an agent.

Parameters:

name: str

The name of the input. This is used as a key to index observed data.

Deprecated since version v0.8.0: This argument is deprecated and will be removed in Blop v1.0.0. The movable.name will be used instead.

description: str, optional

A longer, more descriptive name for the DOF.

Deprecated since version v0.8.0: This argument is deprecated and will be removed in Blop v1.0.0.

type: Literal[“continuous”, “binary”, “ordinal”, “categorical”]

Describes the type of the input to be optimized. An outcome can be - Continuous, meaning any real number. - Binary, meaning that it can take one of two values (e.g. [on, off]) - Ordinal, meaning ordered categories (e.g. [low, medium, high]) - Categorical, meaning non-ordered categories (e.g. [mango, banana, papaya]) Default: “continuous”

search_domain: Optional[Union[tuple[float, float], set[int], set[str]]]

The range of value for the agent to search. Must be supplied for a non read-only DOF. - if continuous, a tuple of the lower and upper limit of the input for the agent to search. - if discrete, a set of the possible values for the input. Default: (-np.inf, np.inf)

trust_domain: Optional[Union[tuple[float, float], set[int], set[str]]]

The agent will reject all data where the DOF value is outside this domain. Must span a equal or larger range than the search domain. Default: (-np.inf, np.inf)

domain: Optional[Union[tuple[float, float], set[int], set[str]]]

The total domain of the input. This is inferred from the transform, unless the input is discrete. Must span a equal or larger range than the trust domain. Default: (-np.inf, np.inf)

active: Optional[bool]

If True, the agent will try to use the DOF in its optimization. If False, the agent will still read the DOF but not include it any model or acquisition function. Default: True

Deprecated since version v0.8.0: This attribute is deprecated and will be removed in Blop v1.0.0. Inactive DOFs are no longer supported.

read_only: Optional[bool]

If True, the agent will not try to set the DOF. Must be set to True if the supplied ophyd device is read-only. The behavior of the DOF on each sample for read only/not read-only are:

‘read’: the agent will read the input on every acquisition (all dofs are always read)
‘move’: the agent will try to set and optimize over these (there must be at least one of these)
‘input’ means that the agent will use the value to make its posterior

Default: False

transform: Optional[Literal[“log”, “logit”, “arctanh”]]

A transform to apply to the objective, to make the process outputs more Gaussian. Default: None

movable: Optional[NamedMovable]

A bluesky.protocols.NamedMovable. If not supplied, a dummy bluesky.protocols.NamedMovable will be generated. Default: None

device: Optional[Signal]

An ophyd.Signal. If not supplied, a dummy ophyd.Signal will be generated. Default: None

Deprecated since version v0.8.0: This attribute is deprecated and will be removed in Blop v1.0.0. Ophyd will no longer be a direct dependency. Use movable which must be a bluesky.protocols.NamedMovable instead.

tags: Optional[list[str]]

A list of tags. These make it easier to subset large groups of DOFs. Default: []

Deprecated since version v0.8.0: This attribute is deprecated and will be removed in Blop v1.0.0.

travel_expense: Optional[float]

The relative cost of moving the DOF from the current position to the new position. Default: 1

Deprecated since version v0.8.0: This attribute is deprecated and will be removed in Blop v1.0.0. It may resurface in a future version.

units: Optional[str]

The units of the DOF (e.g. mm or deg). This is just for plotting and general sanity checking. Default: None

Deprecated since version v0.8.0: This attribute is deprecated and will be removed in Blop v1.0.0.

property search_domain: tuple[float, float] | set[int] | set[str] | set[bool]: A writable DOF always has a search domain, and a read-only DOF will return its current value.

property trust_domain: tuple[float, float] | set[int] | set[str] | set[bool]: If _trust_domain is None, then we trust the entire domain (so we return the domain).

property domain: tuple[float, float] | set[int] | set[str] | set[bool]

The total domain, determined by the DOF type and transform; the user can’t control this. This is what we fall back on as the trust_domain if None is supplied.

If the DOF is continuous:: If there is a transform, return the domain of the transform Else, return (-inf, inf)
If the DOF is discrete:: If there is a trust domain, return the trust domain Else, return the search domain

property readback: Any: The current value of the DOF.

Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. DOFs will not have a readback since Ophyd will no longer be a direct dependency. Instead, use bluesky.plan_stubs.rd on your movable.

property summary: Series: Return a Series summarizing the state of the DOF.

Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. DOFs will not have a summary.

property label_with_units: str: A label for a plot, perhaps.

Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. DOFs will not have a label with units.

property has_model: bool: Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. Models will not be stored in individaul DOFs.

activate()[source]

Activate the DOF

Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. DOFs will always be active.

deactivate()[source]

Deactivate the DOF

Deprecated since version v0.8.0: This method is deprecated and will be removed in Blop v1.0.0. DOFs will always be active.