********************************************************************************

                             --------------------
                             doptomog version 2.0
                             --------------------

     Copyright (C) 2015  Enrico J. Kotze ejk@saao.ac.za

     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

********************************************************************************

The code was written in Fortran 90/95/2003, IDL, Gnuplot and bash on a Linux
operating system with the following configuration:

	- gfortran	4.8.4
	- IDL		7.1
	- Gnuplot	4.6 patchlevel 4
	- bash		4.3.11(1)

This is the minimum configuration needed for the doptomog package to work as
described below.

********************************************************************************

There are 8 bash scripts in the doptomog/ folder, prefixed 0 to 7 for a logical
stepped process to obtain science grade results.
The scripts may be launched from a file browser (choose "Run in Terminal") or a
terminal command line (use "source ***.sh" where *** signifies the script name).
Prompts for the necessary user input are displayed in the terminal.
See below the sections on the input and output data structures for the input
needed and the output produced by steps 1 to 7.

Step 0:

  0-make.clean.sh

  - remove all previously compiled code and/or compile all code in the code
    folder

Step 1:

  1-exec.pspectra.prepare.sh

  - prepare the input spectra to facilitate the extraction of spectral lines

Step 2:

  2-exec.pspectra.extract.sh

  - extract a specified spectral line

Step 3:

  3-exec.pdoptomog.sh

  - perform Doppler tomography using a fast maximum entropy algorithm on an
    extracted spectral line

  - perform consecutive half-phase Doppler tomography for a specified number of
    half phases
    (see input file doptomog.in in the relevant folder described below)

  - perform flux modulation mapping based on the consecutive half-phase Doppler
    tomography

Step 4:

  4-idl.doptomog.pre.sh

  - perform a visualisation (IDL) of the Doppler tomography results

Step 5:

  5-exec.pbinarymodel.sh

  - calculate a model 2d velocity overlay and a model 3d spatial construct

Step 6:

  6-idl.doptomog.sh

  - perform a visualisation (IDL) of the Doppler tomogram without and with the
    model 2d velocity overlay

Step 7:

  7-gnu.binarymodel.sh

  - perform a visualisation (Gnuplot) of the model 3d spatial construct

NOTE: Each script in the stepped process will compile its code if necessary.

********************************************************************************

The code is organised in the following folders:

  code/
  
  - makefile
  
  - Fortran 90/95/2003 code for

    --	pspectra: program to prepare and extract input spectra
    	mspectra: module holding all declared program variables

    --	pbinarymodel: program to calculate a model 2d velocity overlay and a
    	model 3d spatial construct for the source
    	mbinarymodel: module holding all declared program variables

    --	pdoptomog: program to perform Doppler tomography using a fast maximum
    	entropy algorithm on an extracted spectral line
    	mdoptomog: module holding all declared program variables

  scripts/gnu/

  - scripts for Gnuplot visualisation of the model 3d spatial construct

  scripts/idl/

  - scripts for IDL visualisation of Doppler tomography results

  scripts/shell/

  - scripts for folder and file management
  
********************************************************************************

The input data are organised in the following folder:

  sources/<source name>/in/, e.g., sources/mcv/in/

  - input for Step 1:

    -- specprepare.in, text file containing spectra preparation parameters

  - input for Step 2:

    -- specextract.in, text file containing spectral line extraction parameters

  - input for Step 3:

    -- doptomog.in, text file containing Doppler tomography parameters

  - input for Step 5:

    -- binarymodel.in, text file containing binary parameters

  sources/<source name>/in/spectra/, e.g., sources/mcv/in/spectra/

  - spectra input for Step 1:

    -- <source name>, e.g., cv, file containing list of spectra file names,
       corresponding phase and phase interval (if applicable)

    -- <spectra file name> (multiple), e.g., mcv001.txt, mcv002.txt. etc., files
       containing wavelength and flux

********************************************************************************

The output data are organised in the following folder:

  sources/<source name>/out/spectra/, e.g., sources/mcv/out/spectra/

  - output from Step 1:

    -- specprepare.out, input for Step 2

  - output from Step 2:

    -- specextract.out, input for Step 3

  sources/<source name>/out/doptomog/, e.g., sources/mcv/out/doptomog/

  - output from Step 3:

    -- doptomog.<0=standard/1=inside-out>.log, e.g., doptomog.0.log,
       a log of some of the calculations from the maximum entropy algorithm

    -- doptomog.<0=standard/1=inside-out>.out, e.g., doptomog.0.out,
       main output file containing (amongst other) the reconstructed spectra
       and tomogram, i.e., input for Steps 4 and 6

    -- halfphases/

       - halfphases.<0=standard/1=inside-out>.out, e.g., halfphases.0.out,
         a log of the consecutive half phases processed

       for n consecutive half phases:

       - doptomog.<0=standard/1=inside-out>.<i=0...n-1>.out, e.g.,
         doptomog.0.0.out, main output file containing (amongst other) the
         reconstructed spectra and tomogram for the i'th half phase, i.e.,
         input for Steps 4 and 6

    -- fluxmodmap/

       - fluxmodmap.<0=standard/1=inside-out>.out, e.g., fluxmodmap.0.out,
         main output file containing (amongst other) the n summed reconstructed
         spectra and tomograms, as well as the flux modulation amplitude and
         phase of maximum flux maps, i.e., input for Steps 4 and 6

  - output from Step 4:

    -- avgp.<0=standard/1=inside-out>.ps, e.g., avgp.0.ps,
       averaged line profile

    -- doptomog.<0=standard/1=inside-out>.ps, e.g., doptomog.0.ps,
       quick look results

    -- specin.<0=standard/1=inside-out>.ps, e.g., specin.0.ps,
       trailed input spectra

    -- specre.<0=standard/1=inside-out>.ps, e.g., specre.0.ps,
       trailed reconstructed spectra

    -- halfphases/

       for n consecutive half phases:

       - avgp.<0=standard/1=inside-out>.<i=0...n-1>.ps, e.g., avgp.0.0.ps,
         averaged line profile for the i'th half phase

       - doptomog.<0=standard/1=inside-out>.<i=0...n-1>.ps, e.g.,
         doptomog.0.0.ps, quick look results for the i'th half phase

       - specin.<0=standard/1=inside-out>.<i=0...n-1>.ps, e.g., specin.0.0.ps,
         trailed input spectra for the i'th half phase

       - specre.<0=standard/1=inside-out>.<i=0...n-1>.ps, e.g., specre.0.0.ps,
         trailed reconstructed spectra for the i'th half phase

    -- fluxmodmap/

       - avgp.<0=standard/1=inside-out>.ps, e.g., avgp.0.ps,
         averaged line profile for the n summed half phases

       - doptomog.<0=standard/1=inside-out>.ps, e.g., doptomog.0.ps,
          quick look results for the n summed half phases

       - specin.<0=standard/1=inside-out>.ps, e.g., specin.0.ps,
         trailed input spectra for the n summed half phases

       - specre.<0=standard/1=inside-out>.ps, e.g., specre.0.ps,
         trailed reconstructed spectra for the n summed half phases

  - output from Step 6:

    -- dopmap.<0=standard/1=inside-out>.ps, e.g., dopmap.0.ps,
       tomogram without model velocity profile overlay

    -- dopmap.<0=standard/1=inside-out>.vmod.ps, e.g., dopmap.0.vmod.ps,
       tomogram with model velocity profile overlay

    -- halfphases/

       for n consecutive half phases:

       - dopmap.<0=standard/1=inside-out>.<i=0...n-1>.ps, e.g., dopmap.0.0.ps,
         tomogram without model velocity profile overlay for the i'th half phase

       - dopmap.<0=standard/1=inside-out>.<i=0...n-1>.vmod.ps, e.g.,
         dopmap.0.0.vmod.ps, tomogram with model velocity profile overlay for
         the i'th half phase

    -- fluxmodmap/

       - dopmap.<0=standard/1=inside-out>.ps, e.g., dopmap.0.ps,
         tomogram without model velocity profile overlay for the n summed half
         phases

       - dopmap.<0=standard/1=inside-out>.vmod.ps, e.g., dopmap.0.vmod.ps,
         tomogram with model velocity profile overlay for the n summed half
         phases

       - moduamp.<0=standard/1=inside-out>.ps, e.g., moduamp.0.ps,
         flux modulation amplitude map without model velocity profile overlay

       - moduamp.<0=standard/1=inside-out>.vmod.ps, e.g., moduamp.0.vmod.ps,
         flux modulation amplitude map without model velocity profile overlay

       - modupha.<0=standard/1=inside-out>.ps, e.g., modupha.0.ps,
         flux modulation phase-offset map without model velocity profile overlay

       - modupha.<0=standard/1=inside-out>.vmod.ps, e.g., modupha.0.vmod.ps,
         flux modulation phase-offset map with model velocity profile overlay

       - modupham.<0=standard/1=inside-out>.ps, e.g., modupham.0.ps,
         phase of maximum flux map without model velocity profile overlay

       - modupham.<0=standard/1=inside-out>.vmod.ps, e.g., modupham.0.vmod.ps,
         phase of maximum flux map with model velocity profile overlay

       - moduphap.<0=standard/1=inside-out>.ps, e.g., moduphap.0.ps,
         filtered phase of maximum flux map without model velocity profile
         overlay

       - moduphap.<0=standard/1=inside-out>.vmod.ps, e.g., moduphap.0.vmod.ps,
         filtered phase of maximum flux map with model velocity profile overlay

  sources/<source name>/out/binarymodel/gnu/, e.g.,
   sources/mcv/out/binarymodel/gnu/

  - output from Step 5:

    -- various files, input for Step 7

  - output from Step 7:

    -- various subfolders and/or files depending on selected terminal

  sources/<source name>/out/binarymodel/idl/, e.g.,
   sources/mcv/out/binarymodel/idl/

  - output from Step 5:

    -- various files, input for Step 6

********************************************************************************