Merge pull request #9 from dls-controls/docs-etc

Docs etc

.travis.yml

@@ -10,21 +10,13 @@ install:
   - pip install virtualenv
   - python -m virtualenv venv
   - source venv/bin/activate
-  - |
-    if [[ $TRAVIS_PYTHON_VERSION == 3.7 ]]; then
-        pip install git+https://github.com/dls-controls/cothread.git
-    fi
   - pip install -r requirements.txt
-  - pip install git+https://github.com/dls-controls/pytac.git
-  - pip install -e "git+https://github.com/atcollab/at.git#egg=accelerator-toolbox&subdirectory=pyat"
-  - cd venv/src/accelerator-toolbox/pyat
-  - python setup.py develop
-  - cd ../../../../
 
 script:
   - python -m pytest test --cov-report term-missing --cov=atip
   - flake8 --ignore=E501,W504
   - sphinx-build -b html -ETW docs docs/_build/html
+  - python setup.py bdist_wheel
 
 after_success:
   - coveralls

INSTALL.rst

@@ -9,11 +9,11 @@ page, `here. <https://github.com/dls-controls/atip>`_
 Initial Setup and Installation
 ------------------------------
 
-**Install ATIP using pip (not yet supported)**::
+**Option 1: Install ATIP using pip**::
 
     $ pip install atip
 
-**Install AT, Pytac and ATIP from GitHub**:
+**Option 2: Install AT, Pytac and ATIP from GitHub**:
 
 1. Download AT, Pytac and ATIP into the same directory [1]_::
 
@@ -42,6 +42,17 @@ Initial Setup and Installation
     $ cd ../atip
     $ python -m pytest
 
+Troubleshooting
+---------------
+
+If you encounter problems with your pyAT installation, please refer to 
+``pyat/README.rst`` in the ``at`` source directory. Help for installing
+Pytac is available on `Readthedocs
+<https://pytac.readthedocs.io/en/latest/examples.html#installation>`_.
+
+Please note that for ATIP to function with Python 3.7 or later, you must
+use Cothread>=2.16.
+
 Footnotes
 ---------
 

MANIFEST.in

@@ -0,0 +1,2 @@
+include atip/*.py
+include atip/rings/*.m*

Pipfile

@@ -9,7 +9,7 @@ pytest-cov = "*"
 coveralls = "*"
 mock = "*"
 flake8 = "*"
-Sphinx = "*"
+sphinx = "*"
 sphinx_rtd_theme = "*"
 
 [packages]

README.rst

@@ -9,10 +9,26 @@
 ATIP - Accelerator Toolbox Interface for Pytac
 ==============================================
 
-ATIP is intended to integrate a simulator, using the python implementation of
-`AT <https://github.com/atcollab/at>`_ (pyAT), into
-`Pytac <https://github.com/dls-controls/pytac>`_ so that it can be addressed
-in the same manner as the live machine.
+ATIP is an addition to `Pytac <https://github.com/dls-controls/pytac>`_,
+a framework for controlling particle accelerators.
+ATIP adds a simulator to Pytac, which can be used and addressed in the same way
+as a real accelerator.
+
+ATIP enables the easy offline testing of high level accelerator
+controls applications, by either of two methods:
+
+* By replacing the real accelerator at the point where it is addressed in the
+  software, in the Pytac lattice object;
+
+* In a standalone application as a "virtual accelerator",
+  publishing the same control system interface as the live machine. At
+  Diamond Light Source this has been implemented with EPICS, and run on a
+  different port to the operational control system. So the only change required
+  to test software is to configure this EPICS port.
+
+The python implementation of
+`Accelerator Toolbox <https://github.com/atcollab/at>`_ (pyAT) is used
+for the simulation.
 
 For further information on any of ATIP's functions or classes please read the
 documentation `here <https://atip.readthedocs.io/en/latest/>`_.
@@ -25,39 +41,51 @@ See the ``INSTALL.rst`` document.
 General Use:
 ------------
 
-The integrated ATIP lattice is created by loading the simulated data sources
-onto a Pytac lattice using the ``load()`` function found in ``load_sim.py``.
-Once loaded, the integrated lattice acts like a normal Pytac lattice; the
-simulator is accessed through the ``pytac.SIM`` data sources on the lattice and
-each of the elements. For normal operation, the simulator should be referenced
+ATIP produces an "integrated lattice", which is a Pytac lattice object
+with a simulation data source added.
+The simulated data sources are added using the ``load()`` function
+found in ``load_sim.py``.
+
+This adds ``pytac.SIM`` data sources on to the lattice and
+each of the elements.
+
+The integrated lattice acts like a normal Pytac lattice; the simulator can be
+referenced
 like the live machine but with the data source specified as ``pytac.SIM``
-instead of ``pytac.LIVE``, i.e. a get request to a bpm would be
-``<bpm-element>.get_value('x', data_source=pytac.SIM)``. It is worth noting
-that generally the simulated data sources behave exactly like the live machine,
-but in a few cases they do differ e.g. the simulator has a number of lattice
-fields that the live accelerator doesn't have and the live machine has a few
+instead of ``pytac.LIVE``.
+
+For example, a get request to a BPM would be
+``<bpm-element>.get_value('x', data_source=pytac.SIM)``.
+
+The simulated data sources behave exactly like the live machine,
+except for a few cases. For example, the simulator has a number of lattice
+fields that the live accelerator doesn't have; and the live machine has a few
 element fields that the simulator doesn't.
 
 Virtual Accelerator:
 --------------------
 
-ATIP can also be used as a virtual accelerator, see ``virtac/README.rst`` for
-further information.
+Instructions for using ATIP as a virtual accelerator are found in
+``virtac/README.rst``.
 
 Implementation:
 ---------------
 
-The accelerator data for the simulator is held in the centralised
-``ATSimulator`` class, which the element and lattice data sources reference.
-Each instance of ``ATElementDataSource`` holds the pyAT element equivalent of
-the Pytac element that it is attached to; when a get request is made the
-appropriate data from that AT element is returned, however, when a set request
-is made the class puts those changes onto the queue of the centralised
-``ATSimulator`` object. Inside the ``ATSimulator`` instance a Cothread thread
-checks the length of the queue, whenever a change is queued the thread
+The accelerator data for the simulator is held in one
+``ATSimulator`` object, which is referenced by the data sources of the lattice
+and each element.
+Each Pytac element has an equivalent pyAT element, held in a
+``ATElementDataSource``;
+when a get request is made, the
+appropriate data from that AT element is returned.
+
+The ``ATSimulator`` object has a queue of pending changes. When a set request
+is received by an element, the element puts the changes onto the queue of the
+``ATSimulator``. Inside the ``ATSimulator`` a Cothread thread
+checks the length of the queue. When it sees changes on the queue, the thread
 recalculates the physics data of the lattice to ensure that it is up to date.
-This means that the emittance and linear optics data held by ``ATSimulator``,
-is updated after every batch of changes and that without excessive calculation
+This means that the emittance and linear optics data held by ``ATSimulator``
+is updated after every batch of changes, and that without excessive calculation
 a very recent version of the lattice's physics data is always available.
 
 API:
@@ -128,26 +156,27 @@ ATSimulator:
 Specific Notes:
 ---------------
 
-If local (not pip) installations are used; ATIP, AT, and Pytac must all be
-located in the same source directory In order for ATIP to function correctly.
+In order for ATIP to function correctly, the AT and Pytac lattices used must
+be directly equivalent, i.e. they must have the same length and elements in the
+same positions.
 
-It also goes without saying that the AT and Pytac lattices passed to AT must
-be directly equivalent so that ATIP can function correctly, i.e. same length
-and elements in the same positions.
+If local (not pip) installations are used, ATIP, AT, and Pytac must all be
+located in the same source directory in order for ATIP to function correctly.
 
-The methods on ATIP's data sources, that take ``handle`` and ``throw``
-arguments do so only to conform with the Pytac ``DataSource`` base class which
-they inherit from. Inside ATIP it is entirely arbitrary and can be ignored as
-it is not used.
+The methods on ATIP's data sources that take ``handle`` and ``throw``
+arguments do so only to conform with the Pytac ``DataSource`` base class from
+which they inherit. Inside ATIP they are not used and can be ignored.
 
-Both ``ATElementDataSource`` and ``ATLatticeDataSource`` use a dictionary of
-functions that correspond to fields to interpret which data is to be returned
-or set. In the case where a cell needs to be passed to the data handling
+To interpret which data is to be returned or set,
+both ``ATElementDataSource`` and ``ATLatticeDataSource`` use a dictionary of
+functions corresponding to fields. In the case where a cell needs to be passed
+to the data handling
 functions, for further specification, functools' ``partial()`` is used.
 
-``ATSimulator`` has many methods because the physics data from AT must be split
-into a more manageable format before it is returned, so that the user is not
-given an excess of superfluous data.
+The physics data is received from AT all together; to make it easier to manage,
+it is split by ATIP and accessed by a number of methods of the
+``ATSimulator`` object. This aims to be more convenient for the user
+but does result in the ATSimulator object having a large number of methods.
 
 A number of functions that perform tasks that are frequent or long-winded are
 included in ``utils.py`` to make life easier for the user.

atip/load_sim.py

@@ -36,7 +36,7 @@ def load(pytac_lattice, at_lattice, callback=None):
 
     Args:
         pytac_lattice (pytac.lattice.Lattice): An instance of a Pytac lattice.
-        at_ring (at.lattice_object.Lattice): An instance of an Accelerator
+        at_lattice (at.lattice_object.Lattice): An instance of an Accelerator
                                               Toolbox lattice object.
         callback (callable): To be called after completion of each round of
                               physics calculations.

atip/utils.py

@@ -7,7 +7,7 @@
 def load_at_lattice(mode='DIAD', **kwargs):
     """Load an AT lattice from a .mat file in the 'rings' directory.
 
-    .. Note:: I add custom attributes 'Index' and 'Class' to the each of the
+    .. Note:: I add custom attributes 'Index' and 'Class' to each of the
        elements in the AT lattice as I find them useful for debugging.
 
     Args:
@@ -17,7 +17,7 @@ def load_at_lattice(mode='DIAD', **kwargs):
     Returns:
         at.lattice.Lattice: An AT lattice object.
     """
-    filepath = os.path.join(os.path.split(os.path.dirname(__file__))[0],
+    filepath = os.path.join(os.path.dirname(__file__),
                             ''.join(['rings/', mode.lower(), '.mat']))
     at_lattice = at.load.load_mat(filepath, **kwargs)
     for x in range(len(at_lattice)):

docs/index.rst

@@ -1,11 +1,15 @@
 ATIP - Accelerator Toolbox Interface for Pytac
 ==============================================
 
-ATIP is intended to integrate a simulator, using the python implementation of
-`AT <https://github.com/atcollab/at>`_ (pyAT), into
-`Pytac <https://github.com/dls-controls/pytac>`_ so that it can be addressed
-in the same manner as the live machine. ATIP is hosted on GitHub, found
-`here. <https://github.com/dls-controls/atip>`_
+ATIP is an addition to `Pytac <https://github.com/dls-controls/pytac>`_,
+a framework for controlling particle accelerators.
+ATIP adds a simulator to Pytac, which can be used and addressed in the same way
+as a real accelerator. This enables the easy offline testing of high level
+accelerator controls applications.
+
+The python implementation of
+`Accelerator Toolbox <https://github.com/atcollab/at>`_ (pyAT) is used
+for the simulation.
 
 .. sidebar:: How ATIP fits into the combined control structure.
 
@@ -20,11 +24,13 @@ would.
 ATIP also makes use of `Cothread <https://github.com/dls-controls/cothread>`_
 to recalculate the physics data any time a change is made to the lattice.
 
-ATIP can be run as a virtual accelerator, this functionality is not documented
-here but and explanation of how it works and how to use it may be found in the
-.rst files inside ATIP's virtac directory. To communicate with EPICS the ATIP
-uses `PythonSoftIOC <https://github.com/Araneidae/pythonIoc>`_, this enables it
-to emulate all the PVs of the live machine.
+ATIP can also be run in a standalone application as a "virtual accelerator",
+publishing the same control system interface as the live machine. At
+Diamond Light Source this has been implemented with EPICS, using
+`PythonSoftIOC <https://github.com/Araneidae/pythonIoc>`_.
+This functionality is not documented here but an explanation of how it works
+and how to use it may be found in the ``.rst`` files inside ATIP's ``virtac``
+directory.
 
 Contents:
 =========

requirements.txt

@@ -1,7 +1,9 @@
-numpy>=1.10
-scipy>=0.16
-pytest>=2.9
+accelerator-toolbox>=0.0.2
+pytac>=0.3.0
 cothread
+numpy
+scipy
+pytest
 pytest-cov
 coveralls
 mock

setup.cfg

@@ -17,13 +17,19 @@ classifiers =
     Programming Language :: Python :: 3.7
 keywords = accelerator physics
 
+[files]
+package_data =
+    atip = atip/rings/*.m*
+
 [options]
-packages = atip
+packages =
+    atip
 include_package_data = true
 python_requires = >=2.7.4
 install_requires =
     pytac
     accelerator-toolbox
+    cothread
 
 [coverage:run]
 omit =

start-virtac

@@ -1,8 +1,8 @@
 #!/bin/sh
 
-PYIOC_VERSION=2-11
-EPICS_VERSION=R3.14.12.3
-PYIOC=/dls_sw/prod/$EPICS_VERSION/support/pythonSoftIoc/$PYIOC_VERSION/pythonIoc
+PYIOC_VERSION=2-15
+EPICS_VERSION=R3.14.12.7
+PYIOC=/dls_sw/prod/$EPICS_VERSION/support/pythonIoc/$PYIOC_VERSION/pythonIoc
 
 export EPICS_CA_SERVER_PORT=6064
 export EPICS_CAS_SERVER_PORT=6064

test/conftest.py

@@ -43,7 +43,7 @@ def pytac_lattice():
 @pytest.fixture(scope='session')
 def mat_filepath():
     here = os.path.dirname(__file__)
-    return os.path.realpath(os.path.join(here, '../rings/diad.mat'))
+    return os.path.realpath(os.path.join(here, '../atip/rings/diad.mat'))
 
 
 @pytest.fixture(scope='session')