API References (operation)

class MachinePortal(machine=None, segment=None, **kws)

The very first step to control the machine (accelerator system) on physics high-level view, create high-level lattice object from segment of machine, upon which various operations could be proceeded.

Parameters:

  • machine (str) – Name of the accelerator machine, typically, is the name of the data directory, within which all the related configuration files are hosted, could be the path of the configuration folder. The default value is FRIB.

  • segment (str) – All machine segments are defined in segments field in the configuration file “phantasy.ini”, separated by space, e.g. segments: LINAC LS1 defines two segments LINAC and LS1, the default_segment field in that file is used to define the default segment to use. If segment parameter is not defined, use the one defined by default_segment.

Keyword Arguments:

  • prefix (str) – String prefix to all channels, this parameter is crucial to the virtual accelerator (VA) modeling, when ‘–pv-prefix’ argument is used when starting up the VA rather than the one defined in the configuration file (e.g. phantasy.cfg). If this parameter is not defined, will use the one defined by ‘machine’ in ‘DEFAULT’ section of configuration file.

  • verbose (int) – If set nonzero, print out verbose message.

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

Note

  1. Lattice is created from segment of machine.

  2. Directory searching rule for the machine configuration files: (searching priority from high to low)

    • Path of user-defined directory;

    • Path of current working directory;

    • Path defined by env: PHANTASY_CONFIG_DIR;

    • Current user’s home folder: ~/.phantasy;

    • Path of phantasy-machines if installed via pip.

    If the found directory is MPATH, then the naming rule of machine: MPATH + machine name, e.g. MPATH=/home/user/develop, machine name is FRIB, then machine could be defined as: /home/user/develop/FRIB, all configuration files of FRIB should be in that directory.

Examples

>>> # Use default configuration
>>> mp = MachinePortal()
>>> mp.last_machine_path # where I put FRIB machine
/home/tong1/work/FRIB/projects/machines/FRIB
>>> # with machine name, just the same as above
>>> mp = MachinePortal(machine="FRIB")
>>> # another machine name
>>> mp = MachinePortal(machine="FRIB1")
# FRIB1 is in the current working directory
>>> os.path.relpath(mp.last_machine_path)
'FRIB1'
combined_lattice()

Combine all loaded lattice(s) into one Lattice to return.

get_all_names(latname=None, virtual=False, **kws)

Get names of all elements from given lattice.

Parameters:

  • latname (str) – Name of lattice to be investigated.

  • virtual (True or False) – Return virtual elements or not, False by default.

Returns:

ret – List of element names.

Return type:

List(str)

See also

lattice_names

Names of all loaded lattices.

get_all_types

Get all element types from given lattice.

get_all_segment_names()

Return all available segment names.

get_all_types(latname=None, virtual=False, **kws)

Get names of element types (groups/families) from given lattice.

Parameters:

  • latname (str) – Name of lattice to be investigated.

  • virtual (True or False) – Return virtual group or not, False by default.

Returns:

ret – List of type names.

Return type:

List(str)

See also

lattice_names

Names of all loaded lattices.

get_all_names

Get all element names from given lattice.

get_elements(latname=None, name=None, type=None, srange=None, search_all=False, **kws)

Get element(s) from working lattice.

Parameters:

  • latname (str) – Use the (valid) defined lattice name instead of current working lattice name, maybe useful to inspect non-working lattices.

  • name (str or list[str]) – (List of) Element names or Unix shell style patterns.

  • type (str or list[str]) – (List of) Element type/group/family, or Unix shell style patterns.

  • srange (tuple) – Start and end points (tuple of float) of elements’ longitudinal position.

  • search_all (bool) – If True, search from all the loaded segments.

Keyword Arguments:

sort_key (str) – Ascendingly sort key of the returned list, name or pos, pos by default, or other attributes valid for CaElement.

Returns:

ret – List of elements (CaElement), excluding virtual elements.

Return type:

List

Note

  1. The pattern here used is Unix shell style, slightly different from regex, e.g. pattern ‘BP’ matches ‘BPM’ in regex, but matches nothing in Unix shell style, ‘BP*’ works;

  2. If more than one positional parameters (name, type, srange) are defined, return elements that meet all definitions;

  3. By default, the returned elements are ascendingly sorted according to element position values.

Examples

Create MachinePortal instance, e.g. mp 1. Define name with an invalid name:

>>> mp.get_elements(name='NOEXISTS')
[]

  1. Define name with name or name patterns:

>>> mp.get_elements(name='FS1_BMS:DCV_D2662')
[FS1_BMS:DCV_D2662 [VCOR] @ sb=153.794690]
>>> mp.get_elements(name=['FS1_B?*D266?', 'LS1_B*DCV*'], latname='LINAC')
[LS1_BTS:DCV_D1937 [VCOR] @ sb=81.365954,
 LS1_BTS:DCV_D1964 [VCOR] @ sb=84.013954,
 LS1_BTS:DCV_D1997 [VCOR] @ sb=87.348954,
 LS1_BTS:DCV_D2024 [VCOR] @ sb=90.055166,
 LS1_BTS:DCV_D2061 [VCOR] @ sb=93.710487,
 LS1_BTS:DCV_D2114 [VCOR] @ sb=98.985556,
 FS1_BMS:DCV_D2662 [VCOR] @ sb=153.794690,
 FS1_BMS:DCH_D2662 [HCOR] @ sb=153.794690,
 FS1_BMS:BPM_D2664 [BPM] @ sb=153.963690,
 FS1_BMS:QH_D2666 [QUAD] @ sb=154.144690]

  1. Filter BPMs from the above result:

>>> mp.get_elements(name=['FS1_B?*D266?', 'LS1_B*DCV*'], type='BPM',
>>>                 latname='LINAC')
[FS1_BMS:BPM_D2664 [BPM] @ sb=153.963690]
>>> # type='BPM' also could be be pattern

  1. Filter hybrid types:

>>> mp.get_elements(name=['FS1_B?*D266?', 'LS1_B*DCV*'],
>>>                 type=['BPM', 'QUAD'], latname='LINAC')
[FS1_BMS:BPM_D2664 [BPM] @ sb=153.963690,
 FS1_BMS:QH_D2666 [QUAD] @ sb=154.144690]

  1. Get subsection from lattice according to s-position range:

>>> mp.get_elements(srange=(10, 11))
[LS1_CB01:CAV1_D1229 [CAV] @ sb=10.366596,
 LS1_CB01:BPM_D1231 [BPM] @ sb=10.762191,
 LS1_CB01:SOL1_D1235 [SOL] @ sb=10.894207]

  1. Continue filter with srange parameter

>>> mp.get_elements(name=['FS1_B?*D266?', 'LS1_B*DCV*'],
>>>                 type=['BPM', 'QUAD'], srange=(154, 155),
>>>                 latname='LINAC')
[FS1_BMS:QH_D2666 [QUAD] @ sb=154.144690]

Note

Select subsection by srange parameter is realized by new approach, other than ~phantasy.library.Lattice.getLine(), e.g. the result of getLine((10,11)) contains element before the start range: i.e. LS1_WA03:PM_D1223:PM @ sb=9.929284, which is beyond the range.

See also

get_virtual_elements()

Get virtual elements.

next_elements()

Get neighborhood of reference element.

CaElement

Element class.

static get_pv_names(elem, field=None, **kws)

Get PV names by given fields for defined elements.

Parameters:

  • elem – (List of) CaElement objects.

  • field (str or List(str)) – (List of) Field name of PV, if list of names is defined, only names shared by all elements are valid; if not defined, all shared fields will be used.

Keyword Arguments:

handle (str) – Handle of pv, ‘readback’ (default), ‘setpoint’ or ‘readset’.

Returns:

ret – dict of PV names, with keys of field names.

Return type:

dict

Examples

  1. Get all BPM and PM elements:

>>> elem = mp.get_elements(type='*PM')

  1. Get all pv names with same field:

>>> pv1 = mp.get_pv_names(elem) # {'X':[...], 'Y':[...]}

  1. Get define field(s):

>>> pv2 = mp.get_pv_names(elem, 'X')
>>> pv2 = mp.get_pv_names(elem, ['X'])

  1. Get all PV names from one elements:

>>> pv3 = mp.get_pv_names(elem[0])
>>> # return value example:
{u'ENG': [u'V_1:LS1_CA01:BPM_D1129:ENG_RD'],
 u'PHA': [u'V_1:LS1_CA01:BPM_D1129:PHA_RD'],
 u'X': [u'V_1:LS1_CA01:BPM_D1129:X_RD'],
 u'Y': [u'V_1:LS1_CA01:BPM_D1129:Y_RD']}

See also

get_pv_values()

Get PV values.

get_readback()

Get PV readbacks.

CaElement

Element class.

static get_pv_values(elem, field=None, **kws)

Get PV readback values by given fields for defined elements.

Parameters:

  • elem – (List of) CaElement objects.

  • field (str or List(str)) – (List of) Field name of PV, if list of names is defined, only names shared by all elements are valid; if not defined, all shared fields will be used.

Returns:

ret – dict of PV readback values, with keys of field names.

Return type:

dict

Examples

>>> # get all BPM and PM elements
>>> elem = mp.get_elements(type='*PM')
>>> # get 'X' and 'Y' pv readback values
>>> data = mp.get_pv_values(elem, ['X','Y'])
>>> data.keys()
['Y', 'X']

See also

get_pv_names()

Get PV names.

get_readback()

Get PV readbacks.

get_virtual_elements(**kws)

Get all virtual elements from given lattice.

Keyword Arguments:

latname (str) – Name of lattice to be investigated.

Returns:

ret – List of virtual CaElement objects.

Return type:

List

inspect_mconf(mconf=None, out=None)

Inspect given machine configuration.

Parameters:

  • mconf – Machine configuration object, if not given, inspect the last loaded machine.

  • out – Output stream, if not given, only return results, or besides returning results, also print into defined stream, could be stdout, file``(valid file object), or``StringIO.

Returns:

ret – Inspection results, retur a dict when out is None, or StringIO object when out is sio, or None; keys of dict:

  • path : (str), phantasy.ini fullpath

  • lattices : (list), all defined lattices

  • machine : (str), defined machine name

  • config : (dict), all configurations

Return type:

dict or StringIO or None

Examples

>>> mconf = mp.inspect_mconf()
>>> # write inspection results into file
>>> with open('fileout.dat', 'w') as f:
>>>     mconf = mp.inspect_mconf(out=f)
>>> # out could be StringIO or sys.stdout or 'stdout'.

See also

Configuration

static is_virtual(elem)

Test if input element is virtual element.

Parameters:

elem – CaElement object.

Returns:

ret – True for virtual element, else False.

Return type:

True or False

property last_lattice_conf

Configuration of last loaded lattice, composed of caElements.

See also

CaElement

Type:

list

property last_lattice_name

Name of last loaded lattice.

Type:

str

property last_load_success

Return True if lattice loaded without error, or False.

property last_machine_conf

Last loaded configuration object.

See also

Configuration

Type:

Configuration

property last_machine_name

Name of last loaded machine.

Type:

str

property last_machine_path

Full path of the last loaded phantasys.ini file

Type:

str

property lattice_names

Names of all loaded lattices.

Type:

list

property lattices

All loaded lattices.

Type:

dict

load_lattice(segment=None, machine=None, **kws)

Load machine segment from phantasy.ini file.

Parameters:

  • segment (str) – Segment name.

  • machine (str) – Machine name, or path of configuration files.

Keyword Arguments:

  • verbose (int) – If set nonzero, print out verbose message.

  • re_load (True or False) – If set True, reload segment, False by default.

Returns:

ret – Configuration of loaded segment of machine, with the keys of lat_name, lat_conf, mach_name, mach_path and mach_conf.

Return type:

dict

Examples

>>> mp.load_lattice('LS1')
>>> mp.work_lattice_name # 'LS1'
>>> mp.load_lattice('LINAC') # does not actually load, use cached
>>> mp.work_lattice_name # 'LINAC'
# Note working lattice is changed from 'LS1' to 'LINAC', although
# not actually loaded the lattice, see use_lattice().

The cached tricky could improve performance, e.g. in ipython:

>>> %%timeit
>>> mp.load_lattice('LS1', re_load=True)
10 loops, best of 3: 180 ms per loop
>>> %%timeit
>>> mp.load_lattice('LS1')
10000 loops, best of 3: 190 µs per loop

Note

  1. If segment of machine has already been loaded, will not load again, just switch working lattice to be the segment; keyword parameter re_load could be set to force reload;

  2. re_load could be used if necessary, e.g. the configuration file for some segment is changed, etc.

See also

use_lattice

Choose working lattice from loaded lattices.

reload_lattice

Reload machine/lattice.

property machine_names

Names of all loaded machines or facilities.

Type:

list

property machines

All loaded machines.

Type:

dict

next_elements(ref_elem, count=1, **kws)

Get elements w.r.t reference element, according to the defined confinement, from given lattice name, if not given latname, use the current working lattice.

Parameters:

  • ref_elem – CaElement object, reference element.

  • count (int) – Skip element number after ref_elem, negative input means before, e.g. count=1 will locate the next one of ref_elem in the investigated lattice, if keyword parameter type is given, will locate the next one element of the defined type; count=-1 will locate in the opposite direction.

Keyword Arguments:

  • type (str or list(str)) – (List of) Element type/group/family, if type is a list of more than one element types, the next parameter will apply on each type.

  • range (str) – String of format start:stop:step, to slicing the output list, e.g. return 50 BPMs after ref_elem (count=50), but only get every two elements, simply by setting range=0::2.

  • latname (str) – Name of lattice to be investigated.

  • ref_include (True or False) – Include ref_elem in the returned list or not, False by default.

Returns:

ret – List of next located elements, ascendingly sorted by position, by default, only return one element (for eath type) that meets the confinement, return more by assgining range keyword parameter.

Return type:

List

Examples

Create MachinePortal instance, e.g. mp

  1. Select an element as reference element:

>>> print(all_e)
[LS1_CA01:CAV1_D1127 [CAV] @ sb=0.207064,
 LS1_CA01:BPM_D1129 [BPM] @ sb=0.511327,
 LS1_CA01:SOL1_D1131 [SOL] @ sb=0.643330,
 LS1_CA01:DCV_D1131 [VCOR] @ sb=0.743330,
 LS1_CA01:DCH_D1131 [HCOR] @ sb=0.743330,
 LS1_CA01:CAV2_D1135 [CAV] @ sb=0.986724,
 LS1_CA01:CAV3_D1143 [CAV] @ sb=1.766370,
 LS1_CA01:BPM_D1144 [BPM] @ sb=2.070634,
 LS1_CA01:SOL2_D1147 [SOL] @ sb=2.202637,
 LS1_CA01:DCV_D1147 [VCOR] @ sb=2.302637,
 LS1_CA01:DCH_D1147 [HCOR] @ sb=2.302637,
 LS1_CA01:CAV4_D1150 [CAV] @ sb=2.546031,
 LS1_WA01:BPM_D1155 [BPM] @ sb=3.109095,
 LS1_CA02:CAV1_D1161 [CAV] @ sb=3.580158,
 LS1_CA02:BPM_D1163 [BPM] @ sb=3.884422,
 LS1_CA02:SOL1_D1165 [SOL] @ sb=4.016425,
 LS1_CA02:DCV_D1165 [VCOR] @ sb=4.116425,
 LS1_CA02:DCH_D1165 [HCOR] @ sb=4.116425,
 LS1_CA02:CAV2_D1169 [CAV] @ sb=4.359819,
 LS1_CA02:CAV3_D1176 [CAV] @ sb=5.139465,
 LS1_CA02:BPM_D1178 [BPM] @ sb=5.443728]
>>> ref_elem = all_e[5]

  1. Get next element of ref_elem:

>>> mp.next_elements(ref_elem)
[LS1_CA01:CAV3_D1143 [CAV] @ sb=1.766370]

  1. Get last of the next two element:

>>> mp.next_elements(ref_elem, count=2)
[LS1_CA01:BPM_D1144 [BPM] @ sb=2.070634]

  1. Get all of the next two elements:

>>> mp.next_elements(ref_elem, count=2, range='0::1')
[LS1_CA01:CAV3_D1143 [CAV] @ sb=1.766370,
 LS1_CA01:BPM_D1144 [BPM] @ sb=2.070634]

  1. Get all of the two elements before ref_elem:

>>> mp.next_elements(ref_elem, count=-2, range='0::1')
[LS1_CA01:DCV_D1131 [VCOR] @ sb=0.743330,
 LS1_CA01:DCH_D1131 [HCOR] @ sb=0.743330]

  1. Get next two BPM elements after ref_elem, including itself:

>>> mp.next_elements(ref_elem, count=2, type=['BPM'],
>>>                  ref_include=True, range='0::1')
[LS1_CA01:CAV2_D1135 [CAV] @ sb=0.986724,
 LS1_CA01:BPM_D1144 [BPM] @ sb=2.070634,
 LS1_WA01:BPM_D1155 [BPM] @ sb=3.109095]

  1. Get with hybrid types:

>>> mp.next_elements(ref_elem, count=2, type=['BPM', 'CAV'],
>>>                  range='0::1')
[LS1_CA01:CAV3_D1143 [CAV] @ sb=1.766370,
 LS1_CA01:BPM_D1144 [BPM] @ sb=2.070634,
 LS1_CA01:CAV4_D1150 [CAV] @ sb=2.546031,
 LS1_WA01:BPM_D1155 [BPM] @ sb=3.109095]
print_all_properties()

Print all properties, for debug only.

reload_lattice(segment=None, machine=None, **kws)

Reload machine lattice, if parameters machine and segment are not defined, reload last loaded one.

Parameters:

  • segment (str) – Name of segment of machine.

  • machine (str) – Name of machine, or path of configuration files.

See also

load_lattice

Load machine/lattice from configuration files.

use_lattice(lattice_name=None)

Choose name of one of the loaded lattices as the working lattice, if this method is not evoked, the working lattice is the last loaded lattice.

Parameters:

lattice_name (str) – Lattice name.

Returns:

ret – Selected working lattice name.

Return type:

str

Note

If load_lattice() or reload_lattice() is called, the working lattice name would be changed to the just loaded one, since, usually as the user loading a lattice, most likely he/she would like to switch onto that lattice, or explicitly invoking use_lattice() again to switch to another one.

See also

load_lattice

Load machine/lattice from configuration files.

property work_lattice_conf

Configuration of working lattice, composed of CaElements.

See also

CaElement

Element object for channel access.

use_lattice()

Choose working lattice from loaded lattices.

Type:

list

property work_lattice_name

Name of working lattice.

Type:

str