yaq-yeps/312

has-transformed-position

Abstract ¶

This YEP defines the has-transformed-position trait.

Table of Contents ¶

Motivation ¶

Certain motors have use for both an absolute, or "native", position (defined by hardware) and a relative position (defined by the implementation of the motor within a system). For example, a rotational stage may have an hardware position defined as steps from a home position, but an experimenter would care more about the angular position relative to a special angle of the system (e.g. normal incidence).

One of the most basic desires is to offset motor positions so that the position can be set in "relative coordinates":

Scheme 1:

              hw limit 1   |---------*------------|  hw limit 2

native coordinates         0 ... ... x ...   ... max
relative coordinates      -x ... ... 0 ...   ... max-x

A further abstraction is to transform relative positions into positions and units meaningful to the experimenter. Such could be achieved by some function f:

Scheme 2:

              hw limit 1   |---------*------------|  hw limit 2

relative coordinates      -x ... ... 0 ...   ... max-x
transformed coordinates  f(-x) .... f(0) ...... f(max-x)

The functional form of f, which relates relative coordinates to transformed coordinates, is daemon specific. The parameters of the function are implementation specific.

Proposal ¶

We propose a new trait, has-transformed-position.

This trait distinguishes two types of positions: a native_position, which is a position that relates to underlying hardware calls, and position, which is derived from the native position according to some functional form, to_transformed. The functional form is daemon specific; parameters for the functional form should be specified in state or config, whichever the developer sees as appropriate. The inverse of the function, to_native, is also specified.

The trait introduces one explicit functional parameter, the state variable reference_position, which establishes the null position (0 in the Schemes above) in the native coordinate system. As a default, the functional form of to_transformed uses only this reference position to transform coordinates:

to_transformed(x) = x - reference_position
to_native = x + reference_position

Other functional forms must be hard-coded into the daemon. Parameters controlling these functional forms should be implemented as yaq properties with "metadata" record kind (see below).

Transform parameters are subject to change, so native positions are more robust. As such, state is recorded through native units. In contrast, client calls to the position property will report transformed coordinates.

Implement transform parameters as properties ¶

In contrast to position, which is a property with a "data" record kind, native_position has a "metadata" record kind. Consequently, acquisitions hardware are compelled to not track native position across scans, and a varying native_position can only be discerned from inverting the position.

For this reason, it is strongly recommended that all transform parameters are properties with "metadata" record kind. This is already done with the built-in reference_position parameter, but individual daemons will have to implement this for any other parameters. Recording parameters into metadata ensures that acquisitions will have the necessary parameters to invert position into native_position if the need arises.

Specification ¶

This trait requires has-limits (YEP-303). This trait expands the has-limits trait by controlling motor positions using two coordinate systems. One frame (the "transformed" frame) is for common client control. The other frame (the "native" frame) reports position in terms of low-level motor control.

Config ¶

native_limits ¶

type: array

default: [-inf, inf]

Bounds of motion specified in native coordinates. To specify bounds in transformed coordinates, use limits.

State ¶

native_reference_position (float) ¶

The reference position, expressed in native coordinates. Default is 0.0 (i.e. reference position is the same as hardware null).

Messages ¶

to_transformed ¶

request : float

response : float

Convert a native coordinate to transformed.

to_native ¶

request : float

response : float

Convert a transformed coordinate to native. The inverse of to_transformed.

set_native_reference ¶

request : float

Set the reference position in native coordinates. Reference position need not be within hardware limits.

get_native_reference ¶

response : float

Get the reference position in native coordinates.

get_native_position ¶

response : float

Get the current position in native coordinates.

set_native_position ¶

request : float

Set the current position in native coordinates.

get_native_limits ¶

response : {"type": "array", "values" : ["float]}

Returns limits in the relative coordinate system.

get_native_units ¶

response : "string"

Get the units of native coordinates.

Properties ¶

native_reference_position ¶

• getter : "get_native_reference"
• setter : "set_native_reference"
• units_getter : "get_native_units"
• control_kind : "normal"
• record_kind : "metadata"
• type : "double"

native_position ¶

• getter : "get_native_position"
• units_getter : "get_native_units"
• control_kind : "normal"
• record_kind : "metadata"
• type : "double"

native_destination ¶

• getter : "get_native_destination"
• setter : "set_native_position"
• limits_getter : "get_native_limits"
• units_getter : "get_native_units"
• control_kind : "normal"
• record_kind : "metadata"
• type : "double"

Backwards Compatibility ¶

This trait has no effect on has-limits when reference_position = 0.0 and to_transformed(x) == to_native(x) == x.

In state, all values relating to position (position, destination, native_reference_position and hw_limits) are stored in native coordinates. This is so that state values will remain valid even when transforms change.

Rejected Ideas ¶

• An earlier version of this trait, has-reference-position, proposed to use offset and invert state variables to control the transformed position, but did not propose arbitrary functional forms (to_transformed). This was a simpler trait than the accepted form, but we concluded that the functional form would be applicable across a wide range of daemons. This early version of the trait is the default implementation of the new trait.

Copyright ¶

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.

built 2023-10-10 23:52:42                                      CC0: no copyright