Master

Added possibility of calculating isochrones to SPInS

doc/usage.rst

 Usage
 =====
 
-There are three different ways of using SPInS:
+There are four different ways of using SPInS:
 
   1. generating a binary file with the grid of model parameters
 
      .. note::
-        This step must be carried out before the following two steps
+        This step must be carried out before the following three steps
         as these require the above binary file to function correctly.
 
   2. finding the properties of an observed star thanks to its classic
      and seismic parameters.
   3. carrying out tests to evaluate the accuracy of the interpolation
      for a given grid of models.
+  4. generating an isochrone
 
 The way SPInS is used is decided by the values given in the ``SPInS_configure.py``
 file, which also contains a number of other control parameters.  Extensive
@@ -32,7 +33,7 @@ Generating a binary grid
 
   Relevant parameters in ``SPInS_configure.py``:
 
-    * ``write_grid``: set this to ``True`` so that SPInS will write the binary grid.
+    * ``mode``: set this to ``write_grid`` so that SPInS will write the binary grid.
     * ``replace_age_adim``: allows the user to replace the dimensionless age parameter
       when constructing the binary grid.  This can be useful if the dimensionless
       age parameter is lacking from the grid (in which case SPInS adds zeros for
@@ -58,7 +59,7 @@ Generating a binary grid
   To run SPInS in this configuration, just type the following command in a
   terminal window::
 
-  ./SPInS.py
+    ./SPInS.py
 
 Characterising an observed star
 -------------------------------
@@ -70,7 +71,8 @@ Characterising an observed star
       :py:meth:`SPInS.Likelihood.read_constraints`
 
   Relevant parameters in ``SPInS_configure.py``:
-    * ``write_grid``: set this to ``False``
+    * ``mode``: set this to ``fit_data`` to characterise star(s) using observational
+      data 
     * ``distort_grid``: same as above.  If the user changes the value of
       this parameter compared to when the binary grid was constructed, this
       will override the option previously chosen, and will cause the
@@ -88,13 +90,13 @@ Characterising an observed star
   To run SPInS in this configuration, just type the following command in a
   terminal window::
 
-  ./SPInS.py file_with_constraints
+    ./SPInS.py file_with_constraints
 
   where ``file_with_constraints`` is the file with the observational
   constraints.  If you are characterising multiple stars with common parameters,
   just type the following command in a terminal window::
 
-  ./SPInS.py file1_with_constraints file2_with_constraints [ ... ]
+    ./SPInS.py file1_with_constraints file2_with_constraints [ ... ]
 
   where ``file1_with_constraints``, ``file2_with_constraints`` and any additional
   files are the files with the observational constraints.  
@@ -106,9 +108,7 @@ Testing the accuracy of the interpolation
     * a binary grid of models as produced by SPInS
 
   Relevant parameters in ``SPInS_configure.py``:
-    * ``write_grid``: set this to ``False`` otherwise a binary grid will
-      be produced, and the interpolations tests will not be carried out.
-    * ``test_interpolation``: set this to ``True`` so that SPInS
+    * ``mode``: set this to ``test_interpolation`` so that SPInS
       will carry out the interpolation tests.
     * ``interpolation_file``: specify the name of the file in which to
       write the results from the interpolation tests in binary format.
@@ -117,12 +117,37 @@ Testing the accuracy of the interpolation
   To run SPInS in this configuration, just type the following command in a
   terminal window::
 
-  ./SPInS.py
+    ./SPInS.py
 
   If the grid being tested is two dimensional (excluding age), one can plot
   the results using :py:mod:`plot_interpolation_test` utility::
 
-  ./plot_interpolation_test.py interpolation_test_file
+    ./plot_interpolation_test.py interpolation_test_file
 
   where ``interpolation_test_file`` is the binary file which contains the
   results from the interpolation test.
+
+Generating an isochrone
+-----------------------
+
+  Requirements:
+    * a binary grid of models as produced by SPInS
+
+  Relevant parameters in ``SPInS_configure.py``:
+    * ``mode``: set this to ``write_isochrone`` so that SPInS
+      will generate an isochrone.
+    * ``isochrone_parameters``: a dictionary with the isochrone
+      parameters.  This must contain all of the grid parameters
+      including age, but excluding mass, to generate the isochrone.
+    * ``isochrone_npts``: maximum number of points in the isochrone.
+      In practise, the number of points will be less because typically
+      the target age will lie outside the age range of some of the
+      evolutionary tracks which intervene.
+    * ``isochrone_file``: name of the file in which to same the
+      isochrone in text format.
+
+  To run SPInS in this configuration, just type the following command in a
+  terminal window::
+
+    ./SPInS.py
+