Merge pull request #103 from T-Nicholls/cells

Cells

README.rst

@@ -10,7 +10,8 @@
    :target: https://badge.fury.io/py/pytac
 
 
-Python Toolkit for Accelerator Controls (Pytac) is a Python library for working with elements of particle accelerators.
+Python Toolkit for Accelerator Controls (Pytac) is a Python library for working
+with elements of particle accelerators.
 
 Documentation is available at Readthedocs_.
 
@@ -32,6 +33,10 @@ To see a coverage report, check pytest-cov::
 
  $ python -m pytest --cov-report term-missing --cov=pytac
 
+To see style violations, use flake8::
+
+ $ flake8
+
 To build the documentation::
 
  $ cd docs

docs/developers.rst

@@ -1,29 +1,32 @@
 Developers
 ==========
 
-The installation and initialisation steps are slightly different if you want to work on pytac.
-N.B. This guide uses pipenv but a virtualenv will also work.
+The installation and initialisation steps are slightly different if you want to
+work on Pytac. N.B. This guide uses pipenv but a virtualenv will also work.
 
 
 Installation
 ~~~~~~~~~~~~
 
 This is only required on your first use.
 
-- Ensure you have the following requirements: Pip, Pipenv, and a local copy of pytac.
+- Ensure you have the following requirements: Pip, Pipenv, and a local copy of
+  Pytac.
 
-- Install dev-packages and cothread for EPICS support::
+- Install dev-packages and Cothread for EPICS support::
 
     $ pipenv install --dev
-    $ pip install cothread	# cothread is required for EPICS functionality, but pytac can run without it.
+    $ pip install cothread
+    $ # Cothread is required for EPICS functionality, but Pytac can run without it.
 
 
 Initialisation
 ~~~~~~~~~~~~~~
 
-This is required each time you want to start up pytac.
+This is required each time you want to start up Pytac.
 
-- Navigate to your pytac directory and activate a Pipenv shell, and start Python::
+- Navigate to your ``pytac`` directory and activate a Pipenv shell, and start
+  Python::
 
     $ cd <directory-path>
     $ pipenv shell
@@ -34,7 +37,7 @@ This is required each time you want to start up pytac.
     >>>
 
 
-- Import pytac and initialise the lattice from the ``VMX`` directory::
+- Import Pytac and initialise the lattice from the ``VMX`` directory::
 
     >>> import pytac.load_csv
     >>> lattice = pytac.load_csv.load('VMX')

docs/examples.rst

@@ -6,18 +6,19 @@ Installation
 
 This is only required on your first use.
 
-- Ensure you have Pip, then install pytac and cothread::
+- Ensure you have Pip, then install Pytac and Cothread::
 
     $ pip install pytac
-    $ pip install cothread	# cothread is required for EPICS functionality, but pytac can run without it.
+    $ pip install cothread
+    $ # Cothread is required for EPICS functionality, but Pytac can run without it.
 
 
 Initialisation
 ~~~~~~~~~~~~~~
 
-This is required each time you want to start up pytac.
+This is required each time you want to start up Pytac.
 
-- Navigate to your pytac directory and start Python::
+- Navigate to your Pytac directory and start Python::
 
     $ cd <directory-path>
     $ python
@@ -27,7 +28,7 @@ This is required each time you want to start up pytac.
     >>>
 
 
-- Import pytac and initialise the lattice from the ``VMX`` directory::
+- Import Pytac and initialise the lattice from the ``VMX`` directory::
 
     >>> import pytac.load_csv
     >>> lattice = pytac.load_csv.load('VMX')
@@ -85,8 +86,8 @@ Get the value of the 'b1' field of the quad elements
     ...
 
 
-- Print the ``QUAD`` read back values of the 'b1' field using the lattice. This is more efficient
-  since it uses only one request to the control system::
+- Print the ``QUAD`` read back values of the 'b1' field using the lattice. This
+  is more efficient since it uses only one request to the control system::
 
     >>> lattice.get_values('QUAD', 'b1', pytac.RB)
     [71.32496643066406,

docs/index.rst

@@ -1,29 +1,78 @@
 Python Toolkit for Accelerator Controls
 =======================================
 
-Python Toolkit for Accelerator Controls (Pytac) is a Python library for working with elements of particle accelerators, developed at Diamond Light Source.
+Python Toolkit for Accelerator Controls (Pytac) is a Python library for working
+with elements of particle accelerators, developed at Diamond Light Source.
 
-It is hosted on Github at https://github.com/dls-controls/pytac.
+It is hosted on Github at: https://github.com/dls-controls/pytac
 
 Two pieces of software influenced its design:
 
 * Matlab Middlelayer, used widely by accelerator physicists.
-* APHLA, high-level applications written in Python by the NSLS-II accelerator physics group.
+* APHLA, high-level applications written in Python by the NSLS-II accelerator
+  physics group.
 
 
 Overview
 ========
 
-Pytac provides a Python library, ``pytac``, that makes it easier to communicate with machine hardware for online applications. Although it currently works with EPICS, it should be possible to adapt to support other control systems.
-
-The design is based around a ``Lattice`` object that contains a sequence of ``Element`` s. Each element represents a physical component in the accelerator, such as an electromagnet, drift, or BPM. Each element may have zero or more 'fields', each representing a parameter of the component that may change e.g. a BPM element has fields 'x' and 'y' that represent the beam position, and a quadrupole magnet has 'b1' that represents the quadrupolar magnetic field. Each field has one ``Device`` object for monitoring and control purposes, these devices contain the necessary information to get and set parameter data using the control system.
-
-Elements may be grouped into families (an element may be in more than one family), and requested from the lattice object in those families. The current control system integrates with EPICS and uses EPICS PV (process variable) objects to tell EPICS which IOC (input/output controller) to communicate with. The type of the PV specifies which operations can be performed, there are two types of PV: readback, which can only be used to retrieve data; and setpoint, which can be used to set a value as well as for retrieving data. A single component may have both types; and so some methods take 'handle' as an argument, this is to tell the control system which PV to use when interfacing with EPICS, readback ('pytac.RB') or setpoint ('pytac.SP').
-
-Data may be requested or sent in engineering (``ENG``) or physics (``PHYS``) units and will be converted as appropriate. This conversion is a fundamental part of how pytac integrates with the physical accelerator, as physics units are what our description of the accelerator works with (e.g. the magnetic field inside a magnet) and engineering units are what the IOCs on the physical components use (e.g. the current in a magnet). Two types of unit conversion are available: Polynomial (``PolyUnitConv``; often used for linear conversion) and Piecewise Cubic Hermite Interpolating Polynomial (``PchipUnitConv``; often used for magnet data where field may not be linear with current). In the case that measurement data (used to set up the conversion objects) is not in the same units as the physical models, further functions may be given to these objects to complete the conversion correctly.
-
-Models of accelerators, physical or simulated, are defined using a set of ``.csv`` files, located by default in the ``pytac/data`` directory. Each model should be saved in its own directory i.e. different models of the same accelerator should be seperate, just as models of different accelerators would be.
-
+Pytac provides a Python library, ``pytac``, that makes it easier to communicate
+with machine hardware for online applications. Although it currently works with
+EPICS, it should be possible to adapt to support other control systems.
+
+The design is based around a ``Lattice`` object that contains a sequence of
+``Element`` s. Each element represents a physical component in the accelerator,
+such as an electromagnet, drift, or BPM. Each element may have zero or more
+'fields', each representing a parameter of the component that may change e.g. a
+BPM element has fields 'x' and 'y' that represent the beam position, and a
+quadrupole magnet has 'b1' that represents the quadrupolar magnetic field. Each
+field has one ``Device`` object for monitoring and control purposes, these
+devices contain the necessary information to get and set parameter data using
+the control system.
+
+Elements may be grouped into families (an element may be in more than one
+family), and requested from the lattice object in those families. The current
+control system integrates with EPICS and uses EPICS PV (process variable)
+objects to tell EPICS which IOC (input/output controller) to communicate with.
+The type of the PV specifies which operations can be performed, there are two
+types of PV: readback, which can only be used to retrieve data; and setpoint,
+which can be used to set a value as well as for retrieving data. A single
+component may have both types; and so some methods take 'handle' as an
+argument, this is to tell the control system which PV to use when interfacing
+with EPICS, readback (``pytac.RB``) or setpoint (``pytac.SP``).
+
+.. sidebar:: An example control structure.
+
+    .. image:: control_structure.png
+       :width: 400
+
+Data may be set to or retrieved from different data sources, from the live
+machine (``pytac.LIVE``) or from a simulator (``pytac.SIM``). By default the
+'live' data source is implemented using
+`Cothread <https://github.com/dls-controls/cothread>`_ to communicate with
+EPICS, as described above. The 'simulation' data source is left unimplemented,
+as Pytac does not include a simulator. However, ATIP, a module designed to
+integrate the `Accelerator Toolbox <https://github.com/atcollab/at>`_ simulator
+into Pytac can be found `here. <https://github.com/dls-controls/atip>`_
+
+Data may also be requested or sent in engineering (``pytac.ENG``) or physics
+(``pytac.PHYS``) units and will be converted as appropriate. This conversion is
+a fundamental part of how Pytac integrates with the physical accelerator, as
+physics units are what our description of the accelerator works with (e.g. the
+magnetic field inside a magnet) and engineering units are what the IOCs on the
+physical components use (e.g. the current in a magnet). Two types of unit
+conversion are available: Polynomial (``PolyUnitConv``; often used for linear
+conversion) and Piecewise Cubic Hermite Interpolating Polynomial
+(``PchipUnitConv``; often used for magnet data where field may not be linear
+with current). In the case that measurement data (used to set up the conversion
+objects) is not in the same units as the physical models, further functions may
+be given to these objects to complete the conversion correctly.
+
+Models of accelerators, physical or simulated, are defined using a set of
+``.csv`` files, located by default in the ``pytac/data`` directory. Each model
+should be saved in its own directory i.e. different models of the same
+accelerator should be separate, just as models of different accelerators would
+be.
 
 Contents:
 =========
@@ -43,4 +92,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/pytac.rst

@@ -6,7 +6,7 @@ API Documentation
     :undoc-members:
     :show-inheritance:
 
-pytac.cothread_cs module
+pytac.cs module
 ---------------
 
 .. automodule:: pytac.cs
@@ -15,7 +15,7 @@ pytac.cothread_cs module
     :show-inheritance:
 
 pytac.data_source module
--------------------
+------------------------
 
 .. automodule:: pytac.data_source
     :members:
@@ -39,7 +39,7 @@ pytac.element module
     :show-inheritance:
 
 pytac.exceptions module
---------------------
+-----------------------
 
 .. automodule:: pytac.exceptions
     :members:

pytac/cothread_cs.py

@@ -7,11 +7,10 @@
 
 
 class CothreadControlSystem(ControlSystem):
-    """A control system using cothread to communicate with EPICS. N.B. this is
-        the default control system.
+    """A control system using cothread to communicate with EPICS.
 
-    It is used to communicate over channel access with the hardware
-    in the ring.
+    N.B. this is the default control system. It is used to communicate over
+    channel access with the hardware in the ring.
 
     **Methods:**
     """

pytac/cs.py

@@ -5,7 +5,7 @@ class ControlSystem(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.
+    over channel access with the hardware in the ring.
 
     **Methods:**
     """