How to Use the Morel-Maritorena python program
==============================================

1. First you must have Python installed, as well as the Python extensions NumPy and Cython.
   If you don't know how to do this, please have your system administrator do it.
   You can use any version of python (e.g., 2.7.13 or 3.6.1), but you must use the same 
   version to both compile and to run the program. 
   This explanation also assumes you're running some version of linux as your operating system.


2. Create a new directory for your project, and put into it only the following files:
   a) Main routine: water2.pyx and water2.pxd (in cython)
   b) Aux routines: clut.pyx and clut.pxd (in cython), and fresnel.c (in C)
   c) Data file: morel_fq.dat
      [note: You can put the data file in separate directory if you wish, e.g., in the below example,
             I put the data file into a subdirectory named "auxdata".]
   d) python routine to compile the program via cython: setup.py
   e) python script file to run an example: run_morel.py


3. Compile the routine: This is an essential step, to convert from cython and C, to be able to use in python.
   a) run: $ python setup.py build_ext --inplace
      [note: if you get a warning about "Using deprecated NumPy API", you may ignore it.]
   b) This should produce in your directory two C files (clut.c, water2.c), 
      and two object files (clut.so, water2.so)


4. Run the routine interactively:
   $ python 
   >>> from numpy import log10  
   >>> from water2 import MorelMaritorena
   >>> wmod = MorelMaritorena('auxdata/')
       [note: Specify the directory where you put the data files. If the data files are in your current directory, 
        use instead "wmod = MorelMaritorena('./')"]
   >>> wav = [412., 443., 490., 510., 565., 670., 865., 1020.]
       [note: You can also run one wavelength at a time, such as "wav = 412."]
   >>> chl = 0.8     # chlorophyll in mg/m3 
   >>> bbs = 0.      # 
   >>> rho_w = wmod.calc(wav, log10(chl), bbs, sza=30., vza=20., raa=90., ws=5.)
       [note: sza is solar zenith, vza is view zenith, raa is relative azimuth, ws is windspeed(m/s), 
              rho_w is water reflectance output]
   >>> print(rho_w)
   [0.009709887206554413, 0.009241287596523762, 0.010147521272301674, 0.008623463101685047, 
    0.006389400456100702, 0.0009943331824615598, 0.00010384673805674538, 0.0]
       [note: you should get similar values of rho_w output for this example, so this is a good test.]
   >>> exit()


5. Run the routine as a python script:
   a) Edit the file "run_morel.py" as needed, e.g., change geometry, wavelengths, chl, etc.
   b) Run the script from the linux command line:
      $ python run_morel.py
      Water Reflectance(wave):
      [0.009709887206554413, 0.009241287596523762, 0.010147521272301674, 0.008623463101685047, 
       0.006389400456100702, 0.0009943331824615598, 0.00010384673805674538, 0.0]


6. Reference:
   a) Morel-Maritorena (2001), "Bio-optical properties of oceanic waters: A reappraisal"