API References (lattice)

class CaElement(**kws)

Element with Channel Access support.

This class could be used to create an element with data from Channel Finder Service or input keyword parameters.

Parameters:

enable (True or False) – Element is enabled or not, True is controllable, default is True.

Keyword Arguments:

name (str) – Element name.
family (str) – Element type.
index (int) – Element index, default sort key, otherwise, sb is used as sort key.
length (float) – Effective element length.
sb (float) – Longitudinal position at the beginning point, unit: m.
se (float) – Longitudinal position at the end point, unit: m.
virtual (bool) – pass
tags (dict) – Tags for each PV as key name and set of strings as tag names.
fields (dict) – pass
enable (True or False) – Element is enabled or not, True is controllable, default is True.
pv_data (list or dict) – PV record data to build an element, should be of a list of: string of PV name, dict of properties, list of tags, or with dict of keys of: pv_name, pv_props and pv_tags.
auto_monitor (bool) – If set True, initialize all channels auto subscribe, default is False.

Note

If pv_data is defined, element will be initialized with data from pv_data, if pv_data is CFS formatted, simplify_data should be used first to convert data structure.

See also

simplify_data(): Convert CFS formatted data into simple tuple.
phantasy.library.pv.datasource.DataSource: PV data source.

convert(value, from_field, to_field=None)

Interpret the value of from_field of element to the value of to_field, if to_field is not defined, choose the first out of all candidators (sorted).

Parameters:

value (float) – Value of field, no necessary be the current online reading.
from_field (str) – Field name of element, which the paramter value stands for.
to_field (str) – Field name of element.

Returns:

r – Value Interpreted in another unit, from physics engineering or from engineering to physics, depends on the field type.

Return type:

float

Examples

>>> mp = MachinePortal("FRIB", "MEBT")
>>> quad = mp.get_elements(type='QUAD', name='*D1078*')[0]
>>> # convert I = 100 A, to gradient 15.177 T/m
>>> quad.convert(value=100, from_field='I')
15.17734389601
>>> quad.convert(value=15, from_field='B2')
98.7534891752199

current_setting(field)

Return the value of current setting (setpoint) for dynamic field defined by field, if setpoint PV is not available, return None.

Parameters:: field (str) – Name of valid dynamic field.
Returns:: Field current setting or None.
Return type:: r

See also

get_settings: Get field setpoint value from given setpoint pv values.

property design_settings

Physics design setting(s) for all dynamic field(s).

Type:: dict

ensure_put(field, goal, tol=None, timeout=None)

Ensure set the field of element to goal within the discrepancy tolerance of tol, within the max timeout secs. If field is invalid, return None.

Parameters:

field (str) – Dynamic field name of element.
goal (float) – The final value that the field of element would like to reach.
tol (float) – Tolerance for discrepancy between current readback value and the set goal, default is 0.01.
timeout (float) – Maximum wait time, default is 10.0 sec.

Returns:

r – Returns what ensure_put returns, or None.

Return type:

str

See also

ensure_put()

property fields

Valid Channel Access field names.

Warning

fields can only accept dict, with CA field name as key and CaField as value.

Type:: list

get_current_settings(field_of_interest=None, only_physics=True)

Get current setpoint readings of interested dynamic fields.

Parameters:

field_of_interest (list) – Interested physics field names, if not defined, use all valid ones.
only_physics (bool) – If True, only return physics settings otherwise return both physics and engineering field settings.

Returns:

s – Settings of interested physics fields.

Return type:

Settings

get_eng_fields(): Return list of all engineering fields.

get_field(field)

Get element field of CA support.

Parameters:: field (str) – Field name.

Note

All valid field names could be retrieved by fields attribute.

Returns:: CaField or None.
Return type:: ret

get_focusing_polarity(): Only work with QUAD.

get_mapped_field(fname: str)

Get the corresponded field name per the input fname, from engineering to physics, or vice verse.

Returns:: r – The mapped field name, if it is an engineering field.
Return type:: tuple

get_phy_fields(): Return list of all physics fields.

Note

If returned list is empty, but get_eng_fields is not, then physics fields should be the same as engineering fields, but only appeared as ENG field type.

get_settings(field, settings, **kws)

Get the field value from settings, set / read defined by handle keyword argument.

Parameters:

field (str) – Dynamic field name of element.
settings (dict) – Key-value pairs of setpoint PV name and value.

Keyword Arguments:

handle (str) – PV handle, ‘readback’, ‘readset’ or ‘setpoint’ (default).

Returns:

r – Setting value of defined dynamic field, or None.

Return type:

float

See also

current_setting: Get current field setting.

property last_settings

Last setting(s) for all dynamic field(s).

Type:: dict

monitor(field: str, callback, handle: str = 'readback', name: str | None = None)

Monitor a field value change, hook to callback, given a name is useful to remove the callback with ‘’unmonitor’’ method.

The first argument of callback is field object. An example of callback could be like: >>> @pass_arg(‘fld’) >>> def callback(fld, **kws): >>> print(fld.value, kws.get(‘pvname’))

process_pv(pv_name, pv_props, pv_tags=None, u_policy=None, polarity=None, alignment_series=None, **kws)

Process PV record to update element with properties and tags.

Parameters:

pv_name (str) – PV name.
pv_props (dict) – PV properties, key-value pairs.
pv_tags (list) – PV tag list.
u_policy (dict) – Dict of unit conversion policies.
polarity (int) – Device polarity, -1 or 1.
alignment_series (Series) – A series of alignment data, dx,dy,dz,pitch,roll,yaw.

Keyword Arguments:

auto_monitor (bool) – If set True, initialize all channels auto subscribe, default is False.

pv(field=None, handle=None, **kws)

Get PV names with defined field and handle, if none of them is defined, return all PV names.

Parameters:

field (str or list) – Channel access field name, all available fields will be used if not defined, ignore invalid field.
handle (str) – Channel access protocol type, could be one of readback, readset and setpoint.

Note

All Valid field names could be retrieved by fields attribute.
If more than one field is defined with field, i.e. field is a list of string, return PV names binding with these fields, may apply handle as a filter, e.g. if handle is not defined, return all PVs.

Returns:: ret – List of valid PVs as request.
Return type:: list

set_field(field, pv, handle=None, **kws)

Set element field with CA support, i.e. dynamic field.

Parameters:

field (str) – Field name.
pv (str) – Valid PV name.
handle (str) – PV channel type, valid options: readback, readset, setpoint, default is readback.

Keyword Arguments:

pv_policy (dict) – Name of PV read/write policy, keys: ‘read’ and ‘write’, values: scaling law function object.
ftype (str) – Field type, ‘ENG’ (default) or ‘PHY’.
auto_monitor (bool) – If set True, initialize all channels auto subscribe, default is False.

property tags

Tags that element PVs have been assigned.

Type:: dict

unmonitor(field: str, name: str | None = None, handle: str = 'readback'): Unmonitor a field value change, if name is not None, just remove the callbacks under name key, otherwise, remove all.

update_groups(props, **kws)

Update new group with family name.

Parameters:: props (dict) – Element properties.

See also

update_properties

update_properties(props, **kws)

Update element properties.

Parameters:

props (dict) –

Dictionary of properties, two categories:

static properties: without CA features: name, family, index, se, sb (optional), length
dynamic properties: with CA features: handle, field

Keyword Arguments:

pv (str) – Valid PV name.
auto_monitor (bool) – If set True, initialize all channels auto subscribe, default is False.

update_tags(tags, **kws)

Update element tags.

Parameters:: tags (list) – List of tags.
Keyword Arguments:: pv (str) – Valid PV name.

property virtual

Virtual element or not.

Type:: bool

class CaField(name='', **kws)

Channel Access support for element field.

Usually, CaField instance has at most three types of PV names: readback, readset and setpoint, each PV should linked with valid PV connections.

There are two approaches to retrieve the PV values, one is through value attribute, another one is by explicitly calling get();

The same rule applies to set values, i.e. by setting value attribute and by calling put() method.

Parameters:

name (str) – Name of CA field, usually represents the physics attribute linked with CA.

Keyword Arguments:

wait (bool) – Wait or not (True/False) when issuing set command, which is attached to one of ‘caput’ keyword arguments, default: False.
timeout (float) – Time out in second for put operation (see wait), default is 10 seconds.
ensure_put (bool) – Apply ensure set operation or not, default is False, see the notes.
tolerance (float) – Absolute discrepancy tolerance between current readback value and the set goal, default is 0.01.
ename (str) – Name of element which the field attaches to.
readback (str, list(str)) – Readback PV name(s), if a single string is defined, append operation will be issued, if list or tuple of strings is defined, readback attribute will be overwritten with the new list, the same rule applies to readset and setpoint, as well as readback_pv, readset_pv and setpoint_pv.
readset (str, list(str)) – Readset PV name(s).
setpoint (str, list(str)) – Setpoint PV name(s).
pv_policy (dict) – Name of PV read/write policy, keys: ‘read’ and ‘write’, values: scaling law function object.
polarity (int) – Device polarity, -1 or 1.
ftype (str) – Field type, ‘ENG’ (default) or ‘PHY’.
auto_monitor (bool) – If set True, initialize all channels auto subscribe, default is False.

Note

About ensure_put option: If this argument is set True, the set or put action to the field value will be ensured to reach the goal, since CA put wait action sometimes is not that working as the user expected. To make use of this feature, simply set field.ensure_put = True, then do field.value = x, the program will be blocked until field.value reaches x, here assumed field is the instance of CaField class.

property access

(read_access, write_access), access permission of field.

Type:: tuple

add_callback(callback, index=None): Add callback to CaField.

connected(handle='readback'): Check if the handle is connected.

current_setting()

Return current setpoint value.

See also

value: get current readback value.

property ename

Name of element the field attaches to.

Type:: str

property ensure_put

Apply ensure set operation or not, default is False.

Type:: boolean

get(handle='readback', n_sample=1, timeout=10.0, with_timestamp=False, ts_format='raw', keep_raw=False, **kws)

Get value of PV with specified handle, if argument n_sample is larger than 1, statistical result with averaged value and standard deviation will be returned; the sample rate depends on the device scan rate. If timeout is defined, DAQ will be inactivated after timeout second. If PV is attached with a list pvs, the returned values are arrays, e.g. EQUAD usually has two power supply PVs to control one field.

Warning

For the case of devices that generate constant readings, if n_sample is larger than 1, set timeout parameter with a reasonable value is required, or this method will hang up your program.

Parameters:

handle (str) – PV handle, ‘readback’, ‘readset’ or ‘setpoint’.
n_sample (int) – Sample number, total DAQ count.
timeout (float) – Timeout in second for the whole DAQ process, set None to wait forever.
with_timestamp (bool) – If True, return timestamp, default value is False.
ts_format (str) – Format for timestamp, valid options: raw, epoch and human.
keep_raw (bool) – If True, return raw read data as well.

Returns:

r – Valid keys: ‘mean’, ‘std’, ‘timestamp’, ‘data’, the values are the average of all shots, the standard deviation of all shots, the timestamp of the first shot, and all the aquired data array.

Return type:

dict

Examples

Get CA field instance from element:

>>> from phantasy import MachinePortal
>>> mp = MachinePortal(machine='<mach_name>')
>>> lat = mp.work_lattice_conf
>>> elem = lat[0]
>>> print(elem.fields)
>>> fld = elem.get_field('<field_name>')

Get readings from PVs with ‘readback’ handle

>>> print(fld.get('readback'))

Get readings from PVs with ‘setpoint’ handle

>>> print(fld.get('setpoint'))

Get readings from PVs with ‘readset’ handle

>>> print(fld.get('readset'))

Get readings with timestamp

>>> fld.get('readback', with_timestamp=True)

Define the style of timestamp

>>> fld.get('readback', with_timestamp=True, ts_format='human')

Get statistical readings, and keep all the raw data

>>> fld.get('readback', n_sample=1, with_timestamp=True,
            ts_format="epoch", keep_raw=True)

get_auto_monitor(handle='readback'): Get auto_monitor bit for the given PV type.

init_pvs(**kws): PV initialization.

is_engineering_field(): Test if field is engineering field.

is_physics_field(): Test if field is physics field.

property name

Field name, empty string if not given.

Type:: str

property polarity

Device polarity, trend response of the physics field (+/-1) w.r.t. input current (+).

Type:: int

pvs(): Return dict of valid pv type and names.

property read_access

If field readable.

Type:: bool

property read_policy

Defined read policy, i.e. how to read value from field.

The defined policy is a function, with readback_pv attribute as the argument, return a value.

property readback

Readback PV name, usually ends with _RD.

Type:: list[str]

property readback_pv

Readback PV object.

Type:: PV

property readset

Readset PV name, usually ends with _RSET.

Type:: list[str]

property readset_pv

Readset PV object.

Type:: PV

reset_policy(policy=None): Reset policy, by policy name (‘read’ or ‘write’), if not defined, reset both.

set(value, handle='setpoint', **kws)

Set value(s) of PV(s) with specified handle, accept all caput keyword arguments.

Parameters:

value (list or list(val)) – New value(s) to be set.
handle (str) – PV handle, ‘readback’, ‘readset’ or ‘setpoint’.

Examples

Get CA field instance, see get(), set one field of an element which has two ‘setpoint’ PVs, e.g. quad:

>>> fld.set([val1, val2], 'setpoint')
>>> # Check with get:
>>> fld.get('setpoint')
>>> # should return [val1, val2]

Note

get() and set() are a pair of methods that can read/write PV(s) bypass field defined read/write policies.

set_am(): Set am to all pvs.

set_auto_monitor(auto_monitor=True, handle='readback'): Set auto_monitor bit True or False for the given PV type.

property setpoint

Setpoint PV name, usually ends with _CSET.

Type:: list[str]

property setpoint_pv

Setpoint PV object.

Type:: PV

property timeout

10 [sec].

Type:: float
Type:: Time out in second for put operation, default

property tolerance

Absolute discrepancy tolerance between current readback value and the set goal, default is 0.01.

Type:: float

unset_am(): Unset am to all pvs.

update_pv(**kws): Update PV with defined handle.

Keyword Arguments:

readback : str setpoint : str readset : str

property value: Get the current readback value from readback PVs, intepret with read policy as the final field value as a return.

property wait

Wait or not (True/False) when issuing set command, which is attached to one of ‘caput’ keyword arguments, default: False.

Type:: boolean

property write_access

If field writable.

Type:: bool

property write_policy

Defined write policy, i.e. how to set value to field.

The defined policy is a function, with setpoint_pv attribute and new value as arguments.

API References (lattice)

Keyword Arguments: