API Documentation¶

Pytac: Python Toolkit for Accelerator Controls.

pytac.cs module¶

Class representing an abstract control system.

class pytac.cs.ControlSystem[source]¶

Bases: object

Abstract base class representing a control system.

A specialised implementation of this class would be used to communicate over channel access with the hardware in the ring.

Methods:

get_multiple(pvs, throw)[source]¶

Get the value for given PVs.

Parameters:	pvs (sequence) – PVs to get values of. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	the current values of the PVs.
Return type:	list(object)
Raises:	`ControlSystemException` – if it cannot connect to the specified PV.

get_single(pv, throw)[source]¶

Get the value of a given PV.

Parameters:	pv (string) – PV to get the value of. readback or a setpoint PV. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	the current value of the given PV.
Return type:	object
Raises:	`ControlSystemException` – if it cannot connect to the specified PVs.

set_multiple(pvs, values, throw)[source]¶

Set the values for given PVs.

Parameters:	pvs (sequence) – PVs to set the values of. values (sequence) – values to set no the PVs. throw (bool) – On failure, if True raise ControlSystemException, if False return a list of True and False values corresponding to successes and failures and log a warning.
Raises:	`ValueError` – if the PVs or values are not passed in as sequences or if they have different lengths `ControlSystemException` – if it cannot connect to one or more PVs.

set_single(pv, value, throw)[source]¶

Set the value of a given PV.

Parameters:	pv (string) – The PV to set the value of. value (object) – The value to set the PV to. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`ControlSystemException` – if it cannot connect to the specified PV.

pytac.data_source module¶

Module containing pytac data source classes.

class pytac.data_source.DataSource[source]¶

Bases: object

Abstract base class for element or lattice data sources.

Typically an instance would represent hardware via a control system, or a simulation.

Attributes:

units¶

pytac.PHYS or pytac.ENG.

Type:	str

Methods:

get_fields()[source]¶

Get all the fields represented by this data source.

Returns:	all fields.
Return type:	iterable

get_value(field, handle, throw)[source]¶

Get a value for a field.

Parameters:	field (str) – field of the requested value. handle (str) – pytac.RB or pytac.SP throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	value for specified field and handle.
Return type:	float

set_value(field, value, throw)[source]¶

Set a value for a field.

This is always set to pytac.SP, never pytac.RB.

Parameters:	field (str) – field to set. value (float) – value to set. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.

class pytac.data_source.DataSourceManager[source]¶

Bases: object

Class that manages all the data sources and UnitConv objects associated with a lattice or element.

It receives requests from a lattice or element object and directs them to the correct data source. The unit conversion objects for all fields are also held here.

default_units¶

Holds the current default unit type, pytac.PHYS or pytac.ENG, for an element or lattice.

Type:	str

default_data_source¶

Holds the current default data source, pytac.LIVE or pytac.SIM, for an element or lattice.

Type:	str

Methods:

add_device(field, device, uc)[source]¶

Add device and unit conversion objects to a given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The key to store the unit conversion and device objects. device (Device) – The device object used for this field. uc (UnitConv) – The unit conversion object used for this field.
Raises:	`DataSourceException` – if no DeviceDataSource is set.

get_device(field)[source]¶

Get the device for the given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The lookup key to find the device on the manager.
Returns:	The device on the given field.
Return type:	Device
Raises:	`DataSourceException` – if no DeviceDataSource is set.

get_fields()[source]¶

Get all the fields defined on the manager.

Includes all fields defined by all data sources.

Returns:	A dictionary of all the fields defined on the manager, separated by data source(key).
Return type:	dict

get_unitconv(field)[source]¶

Get the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion.
Returns:	The object associated with the specified field.
Return type:	UnitConv
Raises:	`FieldException` – if no unit conversion object is present.

get_value(field, handle='readback', units='default', data_source='default', throw=True)[source]¶

Get the value for a field.

Returns the value of a field on the manager. This value is uniquely identified by a field and a handle. The returned value is either in engineering or physics units. The data_source flag returns either real or simulated values. If handle, units or data_source are not given then the lattice default values are used.

Parameters:	field (str) – The requested field. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS returned. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	The value of the requested field
Return type:	float
Raises:	`DataSourceException` – if there is no data source on the given field. `FieldException` – if the manager does not have the specified field.

set_data_source(data_source, data_source_type)[source]¶

Add a data source to the manager.

Parameters:	data_source (DataSource) – the data source to be set. data_source_type (str) – the type of the data source being set pytac.LIVE or pytac.SIM.

set_unitconv(field, uc)[source]¶

set the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion. uc (UnitConv) – The unit conversion object to be set.

set_value(field, value, handle='setpoint', units='default', data_source='default', throw=True)[source]¶

Set the value for a field.

This sets a value on the machine or the simulation. If handle,units or data_source are not given then the lattice default values are used.

Parameters:	field (str) – The requested field. value (float) – The value to set. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`HandleException` – if the specified handle is not pytac.SP. `DataSourceException` – if arguments are incorrect. `FieldException` – if the manager does not have the specified field.

class pytac.data_source.DeviceDataSource[source]¶

Bases: pytac.data_source.DataSource

Data source containing control system devices.

Attributes:

units¶

pytac.ENG or pytac.PHYS, pytac.ENG by default.

Type:	str

Methods:

add_device(field, device)[source]¶

Add device to this data_source.

Parameters:	field (str) – field this device represents. device (Device) – device object.

get_device(field)[source]¶

Get device from the data_source.

Parameters:	field (str) – field of the requested device.
Returns:	The device of the specified field.
Return type:	Device
Raises:	`FieldException` – if the specified field doesn’t exist on this data source.

get_fields()[source]¶

Get all the fields from the data_source.

Returns:	list of strings of all the fields of the data_source.
Return type:	list

get_value(field, handle, throw=True)[source]¶

Get the value of a readback or setpoint PV for a field from the data_source.

Parameters:	field (str) – field of the requested value. handle (str) – pytac.RB or pytac.SP. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	The value of the PV.
Return type:	float
Raises:	`FieldException` – if the device does not have the specified field.

set_value(field, value, throw=True)[source]¶

Set the value of a readback or setpoint PV for a field from the data_source.

Parameters:	field (str) – field for the requested value. value (float) – The value to set on the PV. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`FieldException` – if the device does not have the specified field.

pytac.device module¶

The device class used to represent a particular function of an accelerator element.

A physical element in an accelerator may have multiple devices: an example at DLS is a sextupole magnet that contains also horizontal and vertical corrector magnets and a skew quadrupole.

class pytac.device.BasicDevice(value, enabled=True)[source]¶

Bases: pytac.device.Device

A basic implementation of the device class.

This device does not have a PV associated with it, nor does it interact with a simulator. In short this device acts as simple storage for data that rarely changes, as it is not affected by changes to other aspects of the accelerator.

Parameters:	value (numeric) – can be a number or a list of numbers. enabled (bool-like) – Whether the device is enabled. May be a PvEnabler object.

get_value(handle=None, throw=None)[source]¶

Read the value from the device.

Parameters:	handle (str) – Irrelevant in this case as a control system is not used, only supported to conform with the base class. throw (bool) – Irrelevant in this case as a control system is not used, only supported to conform with the base class.
Returns:	the value of the device.
Return type:	numeric

is_enabled()[source]¶

Whether the device is enabled.

Returns:	whether the device is enabled.
Return type:	bool

set_value(value, throw=None)[source]¶

Set the value on the device.

Parameters:	value (numeric) – the value to set. throw (bool) – Irrelevant in this case as a control system is not used, only supported to conform with the base class.

class pytac.device.Device[source]¶

Bases: object

A representation of a property of an element associated with a field.

Typically a control system will be used to set and get values on a device.

Methods:

get_value(handle, throw)[source]¶

Read the value from the device.

Parameters:	handle (str) – pytac.SP or pytac.RB. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	the value of the PV.
Return type:	float

is_enabled()[source]¶

Whether the device is enabled.

Returns:	whether the device is enabled.
Return type:	bool

set_value(value, throw)[source]¶

Set the value on the device.

Parameters:	value (float) – the value to set. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.

class pytac.device.EpicsDevice(name, cs, enabled=True, rb_pv=None, sp_pv=None)[source]¶

Bases: pytac.device.Device

An EPICS-aware device.

Contains a control system, readback and setpoint PVs. A readback or setpoint PV is required when creating an epics device otherwise a DataSourceException is raised. The device is enabled by default.

Attributes:

name¶

The prefix of EPICS PVs for this device.

Type:	str

rb_pv¶

The EPICS readback PV.

Type:	str

sp_pv¶

The EPICS setpoint PV.

Type:	str

Parameters:	name (str) – The prefix of EPICS PV for this device. cs (ControlSystem) – The control system object used to get and set the value of a PV. enabled (bool-like) – Whether the device is enabled. May be a PvEnabler object. rb_pv (str) – The EPICS readback PV. sp_pv (str) – The EPICS setpoint PV.
Raises:	`DataSourceException` – if no PVs are provided.

Methods:

get_pv_name(handle)[source]¶

Get the PV name for the specified handle.

Parameters:	handle (str) – The readback or setpoint handle to be returned.
Returns:	A readback or setpoint PV.
Return type:	str
Raises:	`HandleException` – if the PV doesn’t exist.

get_value(handle, throw=True)[source]¶

Read the value of a readback or setpoint PV.

Parameters:	handle (str) – pytac.SP or pytac.RB. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	The value of the PV.
Return type:	float
Raises:	`HandleException` – if the requested PV doesn’t exist.

is_enabled()[source]¶

Whether the device is enabled.

Returns:	whether the device is enabled.
Return type:	bool

set_value(value, throw=True)[source]¶

Set the device value.

Parameters:	value (float) – The value to set. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`HandleException` – if no setpoint PV exists.

class pytac.device.PvEnabler(pv, enabled_value, cs)[source]¶

Bases: object

A PvEnabler class to check whether a device is enabled.

The class will behave like True if the PV value equals enabled_value, and False otherwise.

Parameters:	pv (str) – The PV name. enabled_value (str) – The value for PV for which the device should be considered enabled. cs (ControlSystem) – The control system object.

Methods:

pytac.element module¶

Module containing the element class.

class pytac.element.Element(length, element_type, name=None, lattice=None)[source]¶

Bases: object

Class representing one physical element in an accelerator lattice.

An element has zero or more devices (e.g. quadrupole magnet) associated with each of its fields (e.g. ‘b1’ for a quadrupole).

Attributes:

name¶

The name identifying the element.

Type:	str

type_¶

The type of the element.

Type:	str

length¶

The length of the element in metres.

Type:	float

families¶

The families this element is a member of.

Type:	set

Parameters:	length (float) – The length of the element. element_type (str) – The type of the element. name (str) – The unique identifier for the element in the ring. lattice (Lattice) – The lattice to which the element belongs.

Methods:

add_device(field, device, uc)[source]¶

Add device and unit conversion objects to a given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The key to store the unit conversion and device objects. device (Device) – The device object used for this field. uc (UnitConv) – The unit conversion object used for this field.
Raises:	`DataSourceException` – if no DeviceDataSource is set.

add_to_family(family)[source]¶

Add the element to the specified family.

Parameters:	family (str) – Represents the name of the family.

cell¶

The lattice cell this element is within.

N.B. If the element spans multiple cells then the cell it begins in is returned (lowest cell number).

Type:	int

get_device(field)[source]¶

Get the device for the given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The lookup key to find the device on an element.
Returns:	The device on the given field.
Return type:	Device
Raises:	`DataSourceException` – if no DeviceDataSource is set.

get_fields()[source]¶

Get the all fields defined on an element.

Includes all fields defined by all data sources.

Returns:	A dictionary of all the fields defined on an element, separated by data source(key).
Return type:	dict

get_unitconv(field)[source]¶

Get the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion.
Returns:	The object associated with the specified field.
Return type:	UnitConv
Raises:	`FieldException` – if no unit conversion object is present.

get_value(field, handle='readback', units='default', data_source='default', throw=True)[source]¶

Get the value for a field.

Returns the value of a field on the element. This value is uniquely identified by a field and a handle. The returned value is either in engineering or physics units. The data_source flag returns either real or simulated values.

Parameters:	field (str) – The requested field. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS returned. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	The value of the requested field
Return type:	float
Raises:	`DataSourceException` – if there is no data source on the given field. `FieldException` – if the element does not have the specified field.

index¶

The element’s index within the ring, starting at 1.

Type:	int

s¶

The element’s start position within the lattice in metres.

Type:	float

set_data_source(data_source, data_source_type)[source]¶

Add a data source to the element.

Parameters:	data_source (DataSource) – the data source to be set. data_source_type (str) – the type of the data source being set pytac.LIVE or pytac.SIM.

set_lattice(lattice)[source]¶

Set the stored lattice reference for this element to the passed lattice object.

Parameters:	lattice (Lattice) – lattice object to store a reference to.

set_unitconv(field, uc)[source]¶

Set the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion. uc (UnitConv) – The unit conversion object to be set.

set_value(field, value, handle='setpoint', units='default', data_source='default', throw=True)[source]¶

Set the value for a field.

This value can be set on the machine or the simulation.

Parameters:	field (str) – The requested field. value (float) – The value to set. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`DataSourceException` – if arguments are incorrect. `FieldException` – if the element does not have the specified field.

class pytac.element.EpicsElement(length, element_type, name=None, lattice=None)[source]¶

Bases: pytac.element.Element

EPICS-aware element.

Adds get_pv_name() method.

Methods:

Parameters:	length (float) – The length of the element. element_type (str) – The type of the element. name (str) – The unique identifier for the element in the ring. lattice (Lattice) – The lattice to which the element belongs.

Methods:

get_pv_name(field, handle)[source]¶

Get PV name for the specified field and handle.

Parameters:	field (str) – The requested field. handle (str) – pytac.RB or pytac.SP.
Returns:	The readback or setpoint PV for the specified field.
Return type:	str
Raises:	`DataSourceException` – if there is no data source for this field. `FieldException` – if the specified field doesn’t exist.

pytac.exceptions module¶

Module containing all the exceptions used in pytac.

exception pytac.exceptions.ControlSystemException[source]¶

Bases: exceptions.Exception

Exception associated with control system misconfiguration.

exception pytac.exceptions.DataSourceException[source]¶

Bases: exceptions.Exception

Exception associated with Device misconfiguration or invalid requests to a data source.

exception pytac.exceptions.FieldException[source]¶

Bases: exceptions.Exception

Exception associated with invalid field requests.

exception pytac.exceptions.HandleException[source]¶

Bases: exceptions.Exception

Exception associated with requests with invalid handles.

exception pytac.exceptions.UnitsException[source]¶

Bases: exceptions.Exception

Conversion not understood.

pytac.lattice module¶

Representation of a lattice object which contains all the elements of the machine.

class pytac.lattice.EpicsLattice(name, epics_cs, symmetry=None)[source]¶

Bases: pytac.lattice.Lattice

EPICS-aware lattice class.

Allows efficient get_values() and set_values() methods, and adds get_pv_names() method.

Attributes:

name¶

The name of the lattice.

Type:	str

symmetry¶

The symmetry of the lattice (the number of cells).

Type:	int

Parameters:	name (str) – The name of the epics lattice. epics_cs (ControlSystem) – The control system used to store the values on a PV. symmetry (int) – The symmetry of the lattice (the number of cells).

Methods:

get_element_pv_names(family, field, handle)[source]¶

Get the PV names for the given field, and handle, on all elements in the given family in the lattice.

Assume that the elements are EpicsElements that have the get_pv_name() method.

Parameters:	family (str) – The requested family. field (str) – The requested field. handle (str) – pytac.RB or pytac.SP.
Returns:	A list of PV names, strings.
Return type:	list

get_element_values(family, field, handle='readback', units='default', data_source='default', dtype=None)[source]¶

Get the value of the given field for all elements in the given family in the lattice.

Parameters:	family (str) – family of elements to request the values of. field (str) – field to request values for. handle (str) – pytac.RB or pytac.SP. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM. dtype (numpy.dtype) – if None, return a list. If not None, return a numpy array of the specified type.
Returns:	The requested values.
Return type:	list or numpy.array

get_pv_name(field, handle)[source]¶

Get the PV name for a specific field, and handle on this lattice.

Parameters:	field (str) – The requested field. handle (str) – pytac.RB or pytac.SP.
Returns:	The readback or setpoint PV for the specified field.
Return type:	str

set_element_values(family, field, values, handle='setpoint', units='default', data_source='default')[source]¶

Set the value of the given field for all elements in the given family in the lattice to the given values.

Parameters:	family (str) – family of elements on which to set values. field (str) – field to set values for. values (sequence) – A list of values to assign. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM.
Raises:	`IndexError` – if the given list of values doesn’t match the number of elements in the family.

class pytac.lattice.Lattice(name, symmetry=None)[source]¶

Bases: object

Representation of a lattice.

Represents a lattice object that contains all elements of the ring. It has a name and a control system to be used for unit conversion.

Attributes:

name¶

The name of the lattice.

Type:	str

symmetry¶

The symmetry of the lattice (the number of cells).

Type:	int

Parameters:	name (str) – The name of the lattice. symmetry (int) – The symmetry of the lattice (the number of cells).

Methods:

add_device(field, device, uc)[source]¶

Add device and unit conversion objects to a given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The key to store the unit conversion and device objects. device (Device) – The device object used for this field. uc (UnitConv) – The unit conversion object used for this field.
Raises:	`DataSourceException` – if no DeviceDataSource is set.

add_element(element)[source]¶

Append an element to the lattice and update its lattice reference.

Parameters:	element (Element) – element to append.

cell_bounds¶

The indexes of elements in which a cell boundary occurs.

Examples

A lattice of 5 equal length elements with 2 fold symmetry would return [1, 4, 5] 1 - because it is the start of the first cell. 4 - because it is the first element in the second cell as the boundary between the first and second cells occurs halfway into the length of element 3. 5 - (len(lattice)) because it is the end of the second (last) cell.

Type:	list (str)

cell_length¶

The average length of a cell in the lattice.

Type:	float

convert_family_values(family, field, values, origin, target)[source]¶

Convert the given values according to the given origin and target units, using the unit conversion objects for the given field on the elements in the given family.

Parameters:	family (str) – the family of elements which the values belong to. field (str) – the field on the elements which the values are from. values (sequence) – values to be converted. origin (str) – pytac.ENG or pytac.PHYS. target (str) – pytac.ENG or pytac.PHYS.

get_all_families()[source]¶

Get all families of elements in the lattice.

Returns:	all defined families.
Return type:	set

get_default_data_source()[source]¶

Get the default data source, pytac.LIVE or pytac.SIM.

Returns:	the default data source for the entire lattice.
Return type:	str

get_default_units()[source]¶

Get the default unit type, pytac.ENG or pytac.PHYS.

Returns:	the default unit type for the entire lattice.
Return type:	str

get_device(field)[source]¶

Get the device for the given field.

A DeviceDataSource must be set before calling this method, this defaults to pytac.LIVE as that is the only data source that currently uses devices.

Parameters:	field (str) – The lookup key to find the device on the lattice.
Returns:	The device on the given field.
Return type:	Device
Raises:	`DataSourceException` – if no DeviceDataSource is set.

get_element_device_names(family, field)[source]¶

Get the names for devices attached to a specific field for elements in the specfied family.

Typically all elements of a family will have devices associated with the same fields - for example, BPMs each have a device for fields ‘x’ and ‘y’.

Parameters:	family (str) – family of elements. field (str) – field specifying the devices.
Returns:	device names for specified family and field.
Return type:	list

get_element_devices(family, field)[source]¶

Get devices for a specific field for elements in the specfied family.

Typically all elements of a family will have devices associated with the same fields - for example, BPMs each have a device for fields ‘x’ and ‘y’.

Parameters:	family (str) – family of elements. field (str) – field specifying the devices.
Returns:	devices for specified family and field.
Return type:	list

get_element_values(family, field, handle='readback', units='default', data_source='default', dtype=None)[source]¶

Get the value of the given field for all elements in the given family in the lattice.

Parameters:	family (str) – family of elements to request the values of. field (str) – field to request values for. handle (str) – pytac.RB or pytac.SP. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM. dtype (numpy.dtype) – if None, return a list. If not None, return a numpy array of the specified type.
Returns:	The requested values.
Return type:	list or numpy.array

get_elements(family=None, cell=None)[source]¶

Get the elements of a family from the lattice.

If no family is specified it returns all elements. Elements are returned in the order they exist in the ring.

Parameters:	family (str) – requested family. cell (int) – restrict elements to those in the specified cell.
Returns:	list containing all elements of the specified family.
Return type:	list
Raises:	`ValueError` – if there are no elements in the specified cell or family.

get_family_s(family)[source]¶

Get s positions for all elements from the same family.

Parameters:	family (str) – requested family.
Returns:	list of s positions for each element.
Return type:	list

get_fields()[source]¶

Get the fields defined on the lattice.

Includes all fields defined by all data sources.

Returns:	A dictionary of all the fields defined on the lattice, separated by data source(key).
Return type:	dict

get_length()[source]¶

Returns the length of the lattice, in meters.

Returns:	The length of the lattice (m).
Return type:	float

get_unitconv(field)[source]¶

Get the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion.
Returns:	The object associated with the specified field.
Return type:	UnitConv
Raises:	`FieldException` – if no unit conversion object is present.

get_value(field, handle='readback', units='default', data_source='default', throw=True)[source]¶

Get the value for a field on the lattice.

Returns the value of a field on the lattice. This value is uniquely identified by a field and a handle. The returned value is either in engineering or physics units. The data_source flag returns either real or simulated values.

Parameters:	field (str) – The requested field. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS returned. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False None will be returned for any PV that fails and log a warning.
Returns:	The value of the requested field
Return type:	float
Raises:	`DataSourceException` – if there is no data source on the given field. `FieldException` – if the lattice does not have the specified field.

set_data_source(data_source, data_source_type)[source]¶

Add a data source to the lattice.

Parameters:	data_source (DataSource) – the data source to be set. data_source_type (str) – the type of the data source being set pytac.LIVE or pytac.SIM.

set_default_data_source(default_ds)[source]¶

Sets the default data source for the lattice and all its elements.

Parameters:	default_ds (str) – The default data source to be set across the entire lattice, pytac.LIVE or pytac.SIM.
Raises:	`DataSourceException` – if specified default data source is not a valid data source.

set_default_units(default_units)[source]¶

Sets the default unit type for the lattice and all its elements.

Parameters:	default_units (str) – The default unit type to be set across the entire lattice, pytac.ENG or pytac.PHYS.
Raises:	`UnitsException` – if specified default unit type is not a valid unit type.

set_element_values(family, field, values, handle='setpoint', units='default', data_source='default')[source]¶

Set the value of the given field for all elements in the given family in the lattice to the given values.

Parameters:	family (str) – family of elements on which to set values. field (str) – field to set values for. values (sequence) – A list of values to assign. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM.
Raises:	`IndexError` – if the given list of values doesn’t match the number of elements in the family.

set_unitconv(field, uc)[source]¶

Set the unit conversion option for the specified field.

Parameters:	field (str) – The field associated with this conversion. uc (UnitConv) – The unit conversion object to be set.

set_value(field, value, handle='setpoint', units='default', data_source='default', throw=True)[source]¶

Set the value for a field.

This value can be set on the machine or the simulation.

Parameters:	field (str) – The requested field. value (float) – The value to set. handle (str) – pytac.SP or pytac.RB. units (str) – pytac.ENG or pytac.PHYS. data_source (str) – pytac.LIVE or pytac.SIM. throw (bool) – On failure, if True raise ControlSystemException, if False log a warning.
Raises:	`DataSourceException` – if arguments are incorrect. `FieldException` – if the lattice does not have the specified field.

pytac.load_csv module¶

Module to load the elements of the machine from csv files.

The csv files are stored in one directory with specified names:

elements.csv

devices.csv

families.csv

unitconv.csv

uc_poly_data.csv

uc_pchip_data.csv

pytac.load_csv.load(mode, control_system=None, directory=None, symmetry=None)[source]¶

Load the elements of a lattice from a directory.

Parameters:	mode (str) – The name of the mode to be loaded. control_system (ControlSystem) – The control system to be used. If none is provided an EpicsControlSystem will be created. directory (str) – Directory where to load the files from. If no directory is given the data directory at the root of the repository is used. symmetry (int) – The symmetry of the lattice (the number of cells).
Returns:	The lattice containing all elements.
Return type:	Lattice
Raises:	`ControlSystemException` – if the default control system, cothread, is not installed.

pytac.load_csv.load_pchip_unitconv(filename)[source]¶

Load pchip unit conversions from a csv file.

Parameters:	filename (path-like object) – The pathname of the file from which to load the pchip unit conversions.
Returns:	A dictionary of the unit conversions.
Return type:	dict

pytac.load_csv.load_poly_unitconv(filename)[source]¶

Load polynomial unit conversions from a csv file.

Parameters:	filename (path-like object) – The pathname of the file from which to load the polynomial unit conversions.
Returns:	A dictionary of the unit conversions.
Return type:	dict

pytac.load_csv.load_unitconv(directory, mode, lattice)[source]¶

Load the unit conversion objects from a file.

Parameters:	directory (str) – The directory where the data is stored. mode (str) – The name of the mode that is used. lattice (Lattice) – The lattice object that will be used.

pytac.units module¶

Classes for use in unit conversion.

class pytac.units.NullUnitConv(engineering_units='', physics_units='')[source]¶

Bases: pytac.units.UnitConv

Returns input value without performing any conversions.

Attributes:

eng_units¶

The unit type of the post conversion engineering value.

Type:	str

phys_units¶

The unit type of the post conversion physics value.

Type:	str

Parameters:	engineering_units (str) – The unit type of the post conversion engineering value. physics_units (str) – The unit type of the post conversion physics value.

class pytac.units.PchipUnitConv(x, y, post_eng_to_phys=<function unit_function>, pre_phys_to_eng=<function unit_function>, engineering_units='', physics_units='', name=None)[source]¶

Bases: pytac.units.UnitConv

Piecewise Cubic Hermite Interpolating Polynomial unit conversion.

Attributes:

x¶

A list of points on the x axis. These must be in increasing order for the interpolation to work. Otherwise, a ValueError is raised.

Type:	list

y¶

A list of points on the y axis. These must be in increasing or decreasing order. Otherwise, a ValueError is raised.

Type:	list

pp¶

A pchip one-dimensional monotonic cubic interpolation of points on both x and y axes.

Type:	PchipInterpolator

name¶

An identifier for the unit conversion object.

Type:	str

eng_units¶

The unit type of the post conversion engineering value.

Type:	str

phys_units¶

The unit type of the post conversion physics value.

Type:	str

Parameters:

x (list) – A list of points on the x axis. These must be in increasing order for the interpolation to work. Otherwise, a ValueError is raised.
y (list) – A list of points on the y axis. These must be in increasing or decreasing order. Otherwise, a ValueError is raised.
engineering_units (str) – The unit type of the post conversion engineering value.
physics_units (str) – The unit type of the post conversion physics value.
name (str) – An identifier for the unit conversion object.

Raises:

ValueError – if coefficients are not appropriately monotonic.

class pytac.units.PolyUnitConv(coef, post_eng_to_phys=<function unit_function>, pre_phys_to_eng=<function unit_function>, engineering_units='', physics_units='', name=None)[source]¶

Bases: pytac.units.UnitConv

Linear interpolation for converting between physics and engineering units.

Attributes:

p¶

A one-dimensional polynomial of coefficients.

Type:	poly1d

name¶

An identifier for the unit conversion object.

Type:	str

eng_units¶

The unit type of the post conversion engineering value.

Type:	str

phys_units¶

The unit type of the post conversion physics value.

Type:	str

Parameters:

coef (array-like) – The polynomial’s coefficients, in decreasing powers.
post_eng_to_phys (float) – The value after conversion between ENG and PHYS.
pre_eng_to_phys (float) – The value before conversion.
engineering_units (str) – The unit type of the post conversion engineering value.
physics_units (str) – The unit type of the post conversion physics value.
name (str) – An identifier for the unit conversion object.

class pytac.units.UnitConv(post_eng_to_phys=<function unit_function>, pre_phys_to_eng=<function unit_function>, engineering_units='', physics_units='', name=None)[source]¶

Bases: object

Class to convert between physics and engineering units.

This class does not do conversion but does return values if the target units are the same as the provided units. Subclasses should implement _raw_eng_to_phys() and _raw_phys_to_eng() in order to provide complete unit conversion.

The two arguments to this function represent functions that are applied to the result of the initial conversion. One happens after the conversion, the other happens before the conversion back.

Attributes:

name¶

An identifier for the unit conversion object.

Type:	str

eng_units¶

The unit type of the post conversion engineering value.

Type:	str

phys_units¶

The unit type of the post conversion physics value.

Type:	str

Parameters:

post_eng_to_phys (function) – Function to be applied after the initial conversion.
pre_phys_to_eng (function) – Function to be applied before the initial conversion.
engineering_units (str) – The unit type of the post conversion engineering value.
physics_units (str) – The unit type of the post conversion physics value.
name (str) – An identifier for the unit conversion object.

Methods:

convert(value, origin, target)[source]¶

Convert between two different unit types and chek the validity of the result.

Parameters:	value (float) – the value to be converted origin (str) – pytac.ENG or pytac.PHYS target (str) – pytac.ENG or pytac.PHYS
Returns:	The resulting value.
Return type:	float
Raises:	`UnitsException` – If the conversion is invalid; i.e. if there are no solutions, or multiple, within conversion limits.

eng_to_phys(value)[source]¶

Function that does the unit conversion.

Conversion from engineering to physics units. An additional function may be cast on the initial conversion.

Parameters:	value (float) – Value to be converted from engineering to physics units.
Returns:	The result value.
Return type:	float
Raises:	`UnitsException` – If the conversion is invalid; i.e. if there are no solutions, or multiple, within conversion limits.

phys_to_eng(value)[source]¶

Function that does the unit conversion.

Conversion from physics to engineering units. An additional function may be cast on the initial conversion.

Parameters:	value (float) – Value to be converted from physics to engineering units.
Returns:	The result value.
Return type:	float
Raises:	`UnitsException` – If the conversion is invalid; i.e. if there are no solutions, or multiple, within conversion limits.

set_conversion_limits(lower_limit, upper_limit)[source]¶

Conversion limits to be applied before or after a conversion take place. Limits should be set in in engineering units.

Parameters:	lower_limit (float) – the lower conversion limit upper_limit (float) – the upper conversion limit

set_post_eng_to_phys(post_eng_to_phys)[source]¶

Set the function to be applied after the initial conversion. :param post_eng_to_phys: Function to be applied after the

initial conversion.

set_pre_phys_to_eng(pre_phys_to_eng)[source]¶

Set the function to be applied before the initial conversion. :param pre_phys_to_eng: Function to be applied before the

initial conversion.

pytac.units.unit_function(value)[source]¶

Default value for the pre and post functions used in unit conversion.

Parameters:	value (float) – The value to be converted.
Returns:	The result of the conversion.
Return type:	float

pytac.utils module¶

Utility functions.

pytac.utils.get_div_rigidity(energy)[source]¶

Parameters:	energy (int) – the energy of the lattice.
Returns:	div rigidity.
Return type:	function

pytac.utils.get_mult_rigidity(energy)[source]¶

Parameters:	energy (int) – the energy of the lattice.
Returns:	mult rigidity.
Return type:	function

pytac.utils.get_rigidity(energy_mev)[source]¶

Parameters:	energy_mev (int) – the energy of the lattice.
Returns:	p devided by the elementary charge.
Return type:	float