Merge pull request #8 from T-Nicholls/suggestedChanges

Suggested changes

.gitignore

@@ -19,8 +19,5 @@ htmlcov/
 # temporary files
 *~
 
-# experimental files
-atip/junk/*
-
 # built documentation
 docs/_build

INSTALL.rst

@@ -3,42 +3,44 @@ ATIP Installation
 =================
 
 This guide is for Linux and is based on the current structures of AT and Pytac,
-if you find a mistake please raise an issue on ATIP's GitHub page.
+if you find a mistake anywhere in ATIP please raise an issue on ATIP's GitHub
+page, `here. <https://github.com/dls-controls/atip>`_
 
 Initial Setup and Installation
 ------------------------------
 
-Install AT, Pytac and ATIP from GitHub:
-    1. Download AT, Pytac and ATIP into the same directory [1]_::
+**Install ATIP using pip (not yet supported)**::
 
-        $ cd <source-directory>
-        $ git clone https://github.com/atcollab/at.git
-        $ git clone https://github.com/dls-controls/pytac.git
-        $ git clone https://github.com/T-Nicholls/atip.git
+    $ pip install atip
 
-    2. Create a virtual enviroment and install the dependencies::
+**Install AT, Pytac and ATIP from GitHub**:
 
-        $ cd atip
-        $ virtualenv --no-site-packages venv
-        $ source venv/bin/activate
-        $ pip install -r requirements
+1. Download AT, Pytac and ATIP into the same directory [1]_::
 
-    3. Build AT's .so files::
+    $ cd <source-directory>
+    $ git clone https://github.com/atcollab/at.git
+    $ git clone https://github.com/dls-controls/pytac.git
+    $ git clone https://github.com/T-Nicholls/atip.git
 
-        $ cd ../at/pyat
-        $ python setup.py develop
+2. Create a virtual enviroment and install the dependencies::
 
-    4. Run the tests to ensure all modules are working correctly::
+    $ cd atip
+    $ virtualenv --no-site-packages venv
+    $ source venv/bin/activate
+    $ pip install -r requirements
 
-        $ python -m pytest test
-        $ cd ../../pytac
-        $ python -m pytest
-        $ cd ../atip
-        $ python -m pytest
+3. Build AT's .so files::
 
-Install ATIP using pip (not yet supported)::
+    $ cd ../at/pyat
+    $ python setup.py develop
 
-    $ pip install atip
+4. Run the tests to ensure all modules are working correctly::
+
+    $ python -m pytest test
+    $ cd ../../pytac
+    $ python -m pytest
+    $ cd ../atip
+    $ python -m pytest
 
 Footnotes
 ---------

README.rst

@@ -1,7 +1,7 @@
-.. image:: https://travis-ci.org/T-Nicholls/atip.svg?branch=master
-    :target: https://travis-ci.org/T-Nicholls/atip
-.. image:: https://coveralls.io/repos/github/T-Nicholls/atip/badge.svg?branch=master
-    :target: https://coveralls.io/github/T-Nicholls/atip?branch=master
+.. image:: https://travis-ci.org/dls-controls/atip.svg?branch=master
+    :target: https://travis-ci.org/dls-controls/atip
+.. image:: https://coveralls.io/repos/github/dls-controls/atip/badge.svg?branch=master
+    :target: https://coveralls.io/github/dls-controls/atip?branch=master
 .. image:: https://readthedocs.org/projects/atip/badge/?version=latest
     :target: https://atip.readthedocs.io/en/latest/?badge=latest
 
@@ -41,8 +41,8 @@ element fields that the simulator doesn't.
 Virtual Accelerator:
 --------------------
 
-ATIP can be used as a virtual accelerator, see ``ioc/README.rst`` for further
-information.
+ATIP can also be used as a virtual accelerator, see ``virtac/README.rst`` for
+further information.
 
 Implementation:
 ---------------
@@ -53,53 +53,55 @@ 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 checks
-the length of the queue, whenever a change is queued 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 a very
-recent version of the lattice's physics data is always available.
+``ATSimulator`` object. Inside the ``ATSimulator`` instance a Cothread thread
+checks the length of the queue, whenever a change is queued 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
+a very recent version of the lattice's physics data is always available.
 
 API:
 ----
 
 load_sim:
-    * ``load(lattice, ring)`` - loads the simulator onto the passed Pytac
-      lattice; ring can be an AT ring, or an instance of an AT lattice object,
-      or the path to a .mat file from which a ring can be loaded.
+    * ``load_from_filepath(pytac_lattice, at_lattice_filepath, callback=None)``
+      - loads the AT lattice from the given filepath to the .mat file and then
+      calls ``load``.
+    * ``load(pytac_lattice, at_lattice, callback=None)`` - loads the simulator
+      onto the passed Pytac lattice, callback is a callable that is passed to
+      ATSimulator during creation to be called on completion of each round of
+      physics calculations.
 
 ATElementDataSource:
     * ``get_fields()`` - return the fields on the element.
+    * ``add_field(field)`` - add the given field to this element's data source.
     * ``get_value(field)`` - get the value for a given field on the element.
-    * ``set_value(field, set_value)`` - set the value for a given field on the
+    * ``set_value(field, value)`` - set the value for a given field on the
       element, appends the change to the queue.
-    * ``make_change(field, set_value)`` - change the value of the specifed
-      field on the at element, predominantly used by the queue to make changes,
-      but can also be called directly to avoid putting a change on the queue.
 
 ATLatticeDataSource:
     * ``get_fields()`` - return the fields on the lattice.
     * ``get_value(field)`` - get the value for a given field on the lattice.
     * ``set_value(field, set_value)`` - set the value for a given field on the
-      lattice.
+      lattice, currently not supported so raises HandleException.
 
 ATSimulator:
     * ``toggle_calculations()`` - pause or unpause the recalculation thread.
-    * ``wait_for_calculations(timeout)`` - wait up to 'timeout' seconds for
+    * ``wait_for_calculations(timeout=10)`` - wait up to 'timeout' seconds for
       the current calculations to conclude, if they do it returns True, if not
       False is returned; if 'timeout' is not passed it will wait 10 seconds.
     * ``get_at_element(index)`` - return a shallow copy of the specified AT
       element from the central AT ring, N.B. An 'index' of 1 returns ring[0].
     * ``get_at_lattice()`` - return a shallow copy of the entire centralised AT
       lattice object.
-    * ``get_chrom(cell)`` - return the specified cell of the lattice's
-      'chromaticity'; 0 for 'x', 1 for 'y'.
-    * ``get_emit(cell)`` - return the specified cell of the lattice's
-      'emittance'; 0 for 'x', 1 for 'y'.
-    * ``get_orbit(cell)`` - return the specified cell of the lattice's closed'
-      orbit'; 0 for 'x', 1 for 'phase_x', 2 for 'y', 3 for 'phase_y'.
-    * ``get_tune(cell)`` - return the specified cell of the lattice's 'tune'; 0
-      for 'x', 1 for 'y'.
+    * ``get_chrom(field)`` - return the specified plane of the lattice's
+      'chromaticity'; 'x' or 'y'.
+    * ``get_emit(field)`` - return the specified plane of the lattice's
+      'emittance'; 'x' or 'y'.
+    * ``get_orbit(field)`` - return the specified plane of the lattice's
+      'closed orbit'; 'x', 'phase_x', 'y', or 'phase_y'.
+    * ``get_tune(field)`` - return the specified plane of the lattice's
+      'tune'; 'x' or 'y'.
     * ``get_disp()`` - return the 'dispersion' at every element in the lattice.
     * ``get_s()`` - return the 's position' of every element in the lattice.
     * ``get_energy()`` - return the energy of the lattice.
@@ -110,24 +112,33 @@ ATSimulator:
     * ``get_m44()`` - return the 4x4 transfer matrix for every element in the
       lattice.
     * ``get_mu()`` - return 'mu' at every element in the lattice.
+    * ``get_energy_spread()`` - return the energy spread for the lattice.
+    * ``get_mcf()`` - return the momentum compaction factor for the lattice.
+    * ``get_energy_loss()`` - return the energy loss per turn of the lattice.
+    * ``get_damping_times()`` - return the damping times for the lattice's
+      three normal modes.
+    * ``get_damping_partition_numbers()`` - return the damping partition
+      numbers for the lattice's three normal modes.
+    * ``get_total_bend_angle()`` - return the total bending angle of all the
+      dipoles in the lattice.
+    * ``get_total_absolute_bend_angle()`` - return the total absolute bending
+      angle of all the dipoles in the lattice.
 
 
 Specific Notes:
 ---------------
 
-In order for ATIP to function correctly; ATIP, AT, and Pytac must all be
-located in the same source directory. It also goes without saying that the AT
-and Pytac lattices passed to AT must be directly equivelent 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.
 
-Any function, in ATIP, that takes a ``handle`` argument does so only to conform
-with the ``DataSource`` syntax inherited Pytac. Inside ATIP it is entirely
-arbitrary and can be ignored as it is not used.
+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.
 
-In ``ATElementDataSource``, the set value is used as a get/set flag as well as
-the value to be set; if it is a get request then ``value`` is set to ``None``,
-otherwise the value to be set is passed, the processing methods interpret this
-and behave accordingly.
+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.
 
 Both ``ATElementDataSource`` and ``ATLatticeDataSource`` use a dictionary of
 functions that correspond to fields to interpret which data is to be returned
@@ -136,7 +147,7 @@ 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 superfulous data.
+given an excess of superfluous data.
 
 A number of functions that perform tasks that are frequent or long-winded are
-included in ``ease.py`` to make life easier for the user.
+included in ``utils.py`` to make life easier for the user.

atip/__init__.py

@@ -1,5 +1,5 @@
 """ATIP: Accelerator Toolbox Interface for Pytac.
 See README.rst & INSTALL.rst for more information.
 """
-from . import at_interface, load_sim, sim_data_sources, utils, ease
-__all__ = ["at_interface", "load_sim", "sim_data_sources", "utils", "ease"]
+from . import simulator, load_sim, sim_data_sources, utils
+__all__ = ["simulator", "load_sim", "sim_data_sources", "utils"]