Model

class meme.model.Model[source]

Holds the data for the full machine model, with convenient features for retrieving info.

The Model class represents model data for the full machine. This class fetches the full machine model from a PVA server, and then caches it. All class methods then operate on the cached data. If you would like to refresh the cache, you can call the refresh_rmat_data(), refresh_twiss_data(), or refresh_all() methods, which will re-fetch the information from the model service. Alternatively, you can use the Model’s no_caching attribute to ensure that the model data is refreshed before any method call. Be warned though, this adds a several hundred millisecond delay to every call.

Parameters:

  • model_name (str) – Which acclerator beam path to use. Can be “CU_HXR”, “CU_SXR”,”CU_SPEC”, “SC_DIAG0”, “SC_BSYD”, “SC_HXR”, “SC_SXR”, or “FACET2E”.

  • model_source (str, optional) – Which modelling software to use. The default is “BMAD”, which works for the CU_* and SC_* beam paths. You can also pick “BLEM” for CU_* and SC_*. FACET2E only has “LUCRETIA” as a source.

  • initialize (bool, optional) – Whether to fetch rmat and twiss data immediately upon initialization. Defaults to True. If initialize is False, the data will be fetched the first time it is used.

  • use_design (bool, optional) – Use the design model, rather than the extant model. Defaults to True.

  • no_caching (bool, optional) – If true, model-data will be re-fetched every time it is used. This ensures you stay in-sync with the current model, but makes method calls in this class slower.

Examples:

# On physics@lcls-srv01
from meme.model import Model
m = Model("CU_HXR")
m.get_rmat('BPMS:LI24:801')

# On fphysics@facet-srv01
from meme.model import Model
m = Model("FACET2E",model_source='LUCRETIA')
m.get_rmat('LI16:XCOR:402')
get_rmat(from_device, to_device=[], ignore_bad_names=False, from_device_pos='beg', to_device_pos='end')[source]

Get 6x6 transfer matrices for one or more devices.

This method operates in a few different modes:

1. When a single ‘from’ device and a single ‘to’ device is specified, a single 6x6 transfer matrix will be returned.

m = Model("CU_HXR")
m.get_rmat('BPMS:LI24:801', 'BPMS:LI27:201')
# Will return a single 6x6 matrix

2. When a single ‘from’ device and a list of ‘to’ devices is specified, a list of matrices will be returned, one for each element in the ‘to’ list.

m.get_rmat('BPMS:LI24:801', ['BPMS:LI27:201', 'BPMS:LI27:301', 'BPMS:LI27:401'])
# Will return a list of three 6x6 matrices

3. When a list of ‘from’ devices, and a single ‘to’ device is specified, a list of matrices will be returned, one for each element in the ‘from’ list.

m.get_rmat(['BPMS:LI24:201', 'BPMS:LI24:301', 'BPMS:LI24:401'], 'BPMS:LI27:801')
# Will return a list of three 6x6 matrices

4. When a list is specified for both ‘from’ and ‘to’ devices, a list of matrices will be returned, one for each pair in the two lists. Note that in this mode, both device lists must be the same length.

m.get_rmat(['BPMS:LI24:201', 'BPMS:LI24:301', 'BPMS:LI24:401'], ['BPMS:LI27:201', 'BPMS:LI27:301', 'BPMS:LI27:401'])
# Will return a list of three 6x6 matrices

5. If only one device, or one list of devices is specified, the first element in the machine will be used as the ‘from’ device.

m.get_rmat(['BPMS:LI24:201', 'BPMS:LI24:301', 'BPMS:LI24:401'])
# Will return a list of three 6x6 matrices from the cathode to these three BPMs.

m.get_rmat('BPMS:LI24:201')
# Will return a single 6x6 matrix from the cathode to this BPM.
Parameters:

  • from_device (str or list of str) – The starting device(s) for calculating the transfer matrices. Use device names, element names, or a mix of both.

  • to_device (str or list of str) – The end device(s) for calculating the transfer matrices. Use device names, element names, or a mix of both.

  • ignore_bad_names (bool, optional) – Whether or not to ignore device names which aren’t present in the model. If this option is True, and a device is not found in the model, a 6x6 matrix filled with np.nan will be inserted for that device.

  • from_device_pos (optional) – Either ‘beg’ or ‘mid’, defaults to ‘beg’. For “split” elements (some quads and bends) only. ‘beg’ will calculate the matrix starting from the first half-element, ‘mid’ will calculate the matrix starting from the second half-element. This option is ignored for non-split elements.

  • to_device_pos (optional) – Either ‘mid’ or ‘end’, defaults to ‘end’. For “split” elements (some quads and bends) only. ‘mid’ will calculate the matrix up to the first half-element, ‘end’ will calculate the matrix up to the second half-element. This option is ignored for non-split elements.

Returns:

An array with shape Nx6x6, where N is the length of from_device or to_device

Return type:

np.ndarray

get_s(device_list, ignore_bad_names=False, pos='mid')[source]

Get S position (integrated distance along the beamline) for one or more devices.

Parameters:

  • device_list (str or list of str) – The device(s) to get S positions for. You can use device names, element names, or a mix of both.

  • ignore_bad_names (bool, optional) – Whether or not to ignore device names which aren’t present in the model. If this option is True, and a device is not found in the model, np.nan will be inserted for that device.

  • pos (str, optional) – Either ‘mid’ or ‘end’. ‘mid’ is the default. Only applies to split elements.

Returns:

A 1xN array of S positions, where N=len(device_list)

Return type:

np.ndarray

get_twiss(device_list, ignore_bad_names=False, pos='mid')[source]

Get twiss data for one or more devices.

Parameters:

  • device_list (str or list of str) – The device(s) to get twiss parameters for. You can use device names, element names, or a mix of both.

  • ignore_bad_names (bool, optional) – Whether or not to ignore device names which aren’t present in the model. If this option is True, and a device is not found in the model, np.nan will be inserted for that device.

  • pos (str) – Either ‘mid’ or ‘end’. Defaults to ‘mid’. Only applies to split elements. If ‘mid’, the twiss after the first half-element will be used. If ‘end’, the twiss after the second half-element will be used. Ignored completely for non-split elements.

Returns:

A numpy structured array containing the twiss parameters for the

requested devices. The array has the following fields:

  • length (float): The effective length of the device.

  • p0c (float): The total energy of the beam at the device.

  • alpha_x (float): The horizontal alpha function value at the device.

  • beta_x (float): The horizontal beta function value at the device.

  • eta_x (float): The horizontal dispersion at the device.

  • etap_x (float): The horizontal second-order dispersion at the device.

  • psi_x (float): The horizontal betatron phase advance at the device.

  • alpha_y (float): The vertical alpha function value at the device.

  • beta_y (float): The vertical beta function value at the device.

  • eta_y (float): The vertical dispersion at the device.

  • etap_y (float): The vertical second-order dispersion at the device.

  • psi_y (float): The vertical betatron phase advance at the device.

Return type:

np.ndarray

get_twiss_attribute(device_list, attribute, ignore_bad_names=False, pos='mid')[source]

Get the values for one attribute for one or more devices.

Parameters:

  • device_list (str or list of str) – The device(s) to get the attribute for. You can use device names, element names, or a mix of both.

  • ignore_bad_names (bool, optional) – Whether or not to ignore device names which aren’t present in the model. If this option is True, and a device is not found in the model, np.nan will be inserted for that device.

  • pos (str, optional) – Either ‘mid’ or ‘end’. ‘mid’ is the default. Only applies to split elements.

get_zpos(device_list, ignore_bad_names=False, pos='mid')[source]

Get Z position for one or more devices.

Parameters:

  • device_list (str or list of str) – The device(s) to get Z positions for.

  • ignore_bad_names (bool, optional) – Whether or not to ignore device names which aren’t present in the model. If this option is True, and a device is not found in the model, np.nan will be inserted for that device.

  • pos (str, optional) – Either ‘mid’ or ‘end’. ‘mid’ is the default. Only applies to split elements.

Returns:

A 1xN array of Z positions, where N=len(device_list)

Return type:

np.ndarray

refresh_all()[source]

Refresh the R-Matrix and Twiss data from the MEME optics service.

refresh_rmat_data()[source]

Refresh the R-Matrix data from the MEME optics service.

refresh_twiss_data()[source]

Refresh the Twiss data from the MEME optics service.

meme.model.full_machine_rmats(model_name, use_design=False, model_source='BMAD')[source]

Gets the full machine model from the BMAD Live Model service. It uses the PV “{model_source.upper}:SYS0:1:{model_name.upper}:{LIVE or DESIGN}:RMAT” Most of the time, it is more convenient to use the Model class, rather than this method.

Parameters:

  • model_name (str) – Which accelerator model to use. “CU_HXR”, “CU_SXR”, “SC_HXR”, etc.

  • use_design (bool, optional) – Whether or not to use the design model, rather

  • False. (than the extant model. Defaults to) –

  • model_source (str, optional) – The name of the model source (‘BMAD’, or ‘LUCRETIA’, for example).

Returns:

A numpy structured array containing the model data. The array has the following fields:

  • element (str): The element name for the element.

  • device_name (str): The device name for the element.

  • s (float): The s position for the element. Note that s-position of 0 refers to the start of the entire SLAC linac, NOT the start of LCLS.

  • r_mat (6x6 np.ndarray of floats): The 6x6 transport matrix for this element.

Return type:

numpy.ndarray

meme.model.full_machine_twiss(model_name, use_design=False, model_source='BMAD')[source]

Gets twiss parameters for the full machine from the BMAD Live Model service. It uses the PV “{model_source.upper}:SYS0:1:{model_name.upper}:{LIVE or DESIGN}:RMAT”. Most of the time, it is more convenient to use the Model class, rather than this method.

Parameters:

  • model_name (str) – Which acclerator model to use. Must be “CU_HXR” or “CU_SXR”.

  • use_design (bool, optional) – Whether or not to use the design model, rather

  • False. (than the extant model. Defaults to) – model_source (str, optional): The name of the model source (‘BMAD’, or ‘LUCRETIA’, for example).

Returns:

A numpy structured array containing the model data. The array has the following fields for each element:

  • element (str): The element name for the element.

  • device_name (str): The device name for the element.

  • length (float): The effective length of the element.

  • p0c (float): The total energy of the beam at the element.

  • alpha_x (float): The horizontal alpha function value at the element.

  • beta_x (float): The horizontal beta function value at the element.

  • eta_x (float): The horizontal dispersion at the element.

  • etap_x (float): The horizontal second-order dispersion at the element.

  • psi_x (float): The horizontal betatron phase advance at the element.

  • alpha_y (float): The vertical alpha function value at the element.

  • beta_y (float): The vertical beta function value at the element.

  • eta_y (float): The vertical dispersion at the element.

  • etap_y (float): The vertical second-order dispersion at the element.

  • psi_y (float): The vertical betatron phase advance at the element.

Return type:

numpy.ndarray