adding plots to documentation

docs/conf.py

@@ -195,3 +195,5 @@
 #     dtype, target = line.split(None, 1)
 #     target = target.strip()
 #     nitpick_ignore.append((dtype, six.u(target)))
+
+numfig = True

docs/helios_k/bins.rst

@@ -0,0 +1,108 @@
+Bins
+====
+
+
+Bins devide the total range of wavenumbers into equal size or not-equal sized 
+ranges. Inside the bins, the values of the opacity function can be compacted 
+into a more lightweight format, in order to same memory space. An example is
+shown in :numref:`figbin`, where the wavenumber range from 0 30000 cm^-1 is 
+divided into fife bins. Inside of each bin, the opacity function is sorted
+from small to large, and mapped to a new parameter y, rangin from 0 to 1. 
+When the opcity function has empty parts inside or is not ranging to the full
+bin width, then the sorted opacity function is zero (or kmin, if used) on the
+lower part.
+| relevant parameters for this example:
+
+ - doResampling = 0
+ - doStoreFullK = 1
+ - doStoreSK = 2
+ - nbins = 5
+
+
+
+.. figure:: ../plots/p001/plot001.png  
+   :name: figbin
+
+   The opacity function is divided into fife bins. Inside each bin, the opacity
+   function is sorted and mapped to a new paramter y, ranging from 0 to 1.
+
+
+
+
+Using a binsfile
+================
+
+When a ``binsFile`` name is given in the ``param.dat`` file, then this
+file is used to generate the boundaries of the bins. The bins do not have
+to be equal sized. 
+| Note that this option does not support the doResampling and
+doTransmission options.
+| The binsfile must contain line by line the boundaries of the bins in cm^-1.
+
+An example of a ``binsFile`` is given below, and the result is shown in :numref:`figbinfile`.
+
+::
+
+   bins.dat
+   --------
+   2000
+   6000
+   12000
+   15000
+   25000
+   30000
+
+| relevant parameters for this example:
+
+ - doResampling = 0
+ - doStoreFullK = 1
+ - doStoreSK = 2
+ - binsFile = bins.dat
+
+.. figure:: ../plots/p002/plot001.png  
+   :name: figbinfile
+
+   The opacity function is divided into fife bins, according to the entries of the binsfile. 
+   Inside each bin, the opacity function is sorted and mapped to a new paramter y, ranging
+   from 0 to 1.
+
+
+
+The output edges option
+=======================
+
+Instead of writing the -per bin sorted- opacity function with the full resolution in
+wavenumbers, it is possible to print only averaged positions within the bins. 
+For doing that, the ``outputedgesFile`` option in the ``param.dat`` file can be used. 
+In that file, the edges of the averaged regions within a bin can be specified. 
+The output possition of the sorted opacity function is then exaclty in between of the
+edges. The edges must have values between 0 and 1. 
+
+
+An example of a ``outputedgesFile`` is given below, and the result is shown in
+:numref:`figbinedges`. Note that the figure is plotted in log scale, therefore
+the averaged points can appear to have too high values. 
+
+::
+   edges.dat
+   ---------
+   0.0
+   0.1
+   0.45
+   0.78
+   1.0
+
+| relevant parameters for this example:
+
+ - doResampling = 0
+ - doStoreFullK = 1
+ - doStoreSK = 2
+ - nbins = 5
+ - OutputEdgesFile = edges.dat
+
+.. figure:: ../plots/p003/plot001.png  
+   :name: figbinedges
+
+   The opacity function is divided into fife bins. Inside each bin, the opacity
+   function is sorted and mapped to a new paramter y, ranging from 0 to 1.
+   The sorted opacity function is averaged within the given edges. 

docs/helios_k/heliosk.rst

@@ -57,8 +57,10 @@ used parameters are listed here, the order can not be changed.
    if cut = 0, then no cutting is performed.
 -  doResampling:
 
-   - 1: all the sorted opacity functions per bin are resampled with a Chebyshev polynomial, and the coefficients are written to the file ``Out_<name>_cbin.dat``.
    - 0: no resampling is done.
+   - 1: all the sorted opacity functions per bin are resampled with a Chebyshev polynomial, and the coefficients from all bins are written to the file ``Out_<name>_cbin.dat``.
+   - 2: all the sorted opacity functions per bin are resampled with a Chebyshev polynomial, and the coefficients from each bin are written to a sepparate file ``Out_<name>_cbin<bin_number>.dat``.
+
 
 -  nC: Number of Chebyshev coefficients use for the resampling.
 -  doTransmission:
@@ -83,7 +85,7 @@ used parameters are listed here, the order can not be changed.
 -  doStoreSK:
    - 0: the resampled opacity function is not written to a file.
    - 1: all bins from the resampled opacity function are written to the same file ``Out_<name>_bin.dat``.
-   - 2: all bins from the resampled opacity function are written to a sepparate file   with names ``Out_<name>_bin< bin number >.dat``.
+   - 2: all bins from the resampled opacity function are written to a sepparate file   with names ``Out_<name>_bin<bin_number>.dat``.
 
 -  nbins: number of bins
 -  binsfile: A '-' ignores this option, otherwise this option specifies

docs/helios_k/options.rst

@@ -0,0 +1,36 @@
+
+
+The P file option
+=================
+
+When a ``PFile`` name is given in the ``param.dat`` file, then this file
+is used to read multiple values for P. This option is useful to speed up
+the performance, because multiple reads from the data files can be
+avoided. Too many entries in the Pfile can lead to a memory shortage.
+
+For example:
+
+::
+
+   1.0
+   10.0
+   100.0
+
+The Species file option
+=======================
+
+This option must be used to calculate opacities for gas mixtures,
+containing multiple species. The File contains in the two columns the
+species name, and the number fraction.
+
+For example:
+
+::
+
+   01_hit16    0.9
+   05_hit16    0.1
+
+This example will produce an opacitiy with 90% H2O and 10% CO.
+
+
+

docs/helios_k/resampling.rst

@@ -0,0 +1,82 @@
+Resampling and k-coefficients
+=============================
+
+With the ``doResampling`` option in the ``param.dat`` file, the 
+per bin sorted opacity function can be resampled with a Chebyshev 
+polynomial. The number of Chebyshev can also be set in the ``param.dat``
+file with the ``nC`` option. By using the resampling method,
+a lot of storage space can be saved. However, the exact location of
+individual transition lines is not contained in the resampled data.
+The Chebyshev coefficients are reported the ``Out<name>_cbin.dat``
+files.
+
+
+An example of a resampled bin is shown in :numref:`figresample`.
+
+
+| relevant parameters for this example:
+
+ - doResampling = 1
+ - nC = 20
+ - doStoreSK = 2
+ - nbins = 1
+
+
+.. figure:: ../plots/p004/plot001.png  
+   :name: figresample
+
+   The per bin sorted opacity function is resampled with a 
+   Chebyshev polynomial, in order so save storage space.
+
+
+Bins with empty parts
+---------------------
+
+Some bins can contain an empty parts, where the opacity function have no transition
+lines. This empty parts causes the sorted opacity parts to have a sharp edge between
+the empty parts and the rest, as shown in :numref:`figresample2`. Using the
+Chebyshev polynomial to resample over these sharp edge would introduce oscillations
+into the resampled opacity functions. In order to avoid these oscillations, we resample
+only the part of the sorted opacity function, which is not 0 or kmin. That leads
+to better results, but when reconstructing the polynomial from the Chebyshev
+coefficients, then the empty parts must be added again. 
+
+
+.. figure:: ../plots/p005/plot001.png  
+   :name: figresample2
+
+   Resampling a bin with an empty part. To avoid oscillations in the resampled
+   Polynoial, only values > kmin are considered.
+
+
+
+Using the Chebyshev coefficients
+--------------------------------
+
+The resampled opacity function can be reconstruced with the following code:
+
+::
+
+	import numpy as np
+	from numpy.polynomial.chebyshev import chebval
+
+	#change here the name of the file
+	data_c = np.loadtxt('Out_name_cbin.dat')
+
+	#change here the bin index and the bin size:
+	binIndex = 0
+	binSize = 300
+
+	#extract Chebyshev coefficients
+	c = data_c[binIndex,2:]
+	#extract starting point in x of opacity function
+	xs = data_c[binIndex,1]
+
+	#rescale x to the standard Chebychev polynomial range [-1:1]
+	x1 = x * 2.0 - 1.0
+	k_res = chebval(x1,c,tensor=False)
+	x2 = x * (1.0 - xs) + xs
+
+	#result is in k_res for x values in x2
+	k_res = np.exp(k_res)
+	 

docs/index.rst

@@ -48,7 +48,9 @@ OPTIONS
 .. toctree::
   :maxdepth: 1
 
-  helios_k/details.rst
+  helios_k/bins.rst
+  helios_k/resampling.rst
+  helios_k/options.rst
 
 
 Output Files