JCSDA CRTM beta v2.0.2 Build Instructions
=========================================

$Revision: 8146 $


  CRTM SUPPORT EMAIL: ncep.list.emc.jcsda_crtm.support@noaa.gov
     

  *****************
  *** IMPORTANT ***
  *****************
  To (hopefully) make it easier for people to compile the CRTM library and
  associated test/example programs, we've changed the structure of the build
  process. As such, please read this carefully.
  *****************
  *****************

  
0) PREAMBLE
-----------
   The CRTM tarball directory structure looks like:
     ./
     |-configure   .............. compiler environment shell source files
     |-libsrc      .............. CRTM Fortran95/2003 source files
     `-test        .............. test/example programs and results
        |-forward  .............. forward model tests/examples
        |  |-Example1_Simple
        |  |  |-coefficients .... contains the coefficient data for the program
        |  |  `-results      .... contains the results of the program
        |  |-Example2_SSU
        |  |  |-coefficients
        |  |  `-results
        |  |-Example3_Zeeman
        |  |  |-coefficients
        |  |  `-results
        |  |-Example4_ODPS
        |  |  |-coefficients
        |  |  `-results
        |  `-Example5_ClearSky
        |     |-coefficients
        |     `-results
        `-k_matrix  ............. k-matrix model tests/examples
           |-Example1_Simple
           |  |-coefficients
           |  `-results
           |-Example2_SSU
           |  |-coefficients
           |  `-results
           |-Example3_Zeeman
           |  |-coefficients
           |  `-results
           `-Example4_ODPS
              |-coefficients
              `-results
   
   The build makefiles now assumes that environment variables (envars) will
   be defined that describe the compilation and link environment. The envars
   that must be defined are:
     FC:       the Fortran95/2003 compiler executable,
     FC_FLAGS: the flags/switches provided to the Fortran compiler,
     FL:       the linker used to create the executable test/example programs,
     FL_FLAGS: the flags/switches provided to the linker.
     
   Several shell source files are provided for the compilers to which we have
   access and have tested here at the JCSDA. These shell source files are in
   the "configure/" subdirectory of the tarball.
   
   The current list of test compiler environments in the configure/ directory
   are:
   
     $ ls configure/
     g95.setup             ifort.setup        xlf.setup
     g95_debug.setup       ifort_debug.setup  xlf_debug.setup
     gfortran.setup        pgi.setup
     gfortran_debug.setup  pgi_debug.setup



1) COMPILATION ENVIRONMENT SETUP
--------------------------------
   To set the compilation envars for your CRTM build, you need to source the
   required "setup" file. For example, to use gfortran to build the CRTM you
   would type
   
     . configure/gfortran.setup
   
   in the main directory. Note the "." and space preceding the filename.
   This should print out something like the following:
   
     =========================================
      CRTM compilation environment variables:
        FC:       gfortran
        FC_FLAGS:  -c  -O3  -fconvert=big-endian  -ffast-math  -ffree-form
                   -fno-second-underscore  -frecord-marker=4  -funroll-loops
                   -ggdb  -static  -Wall  
        FL:       gfortran
        FL_FLAGS:  
     =========================================
   
   indicating the values to which the envars have been set.
   
   Change the current setups to suit your needs. If you use a different compiler
   please consider submitting your compilation setup to be included in future
   releases.

   Note that as of CRTM v2.0, the Fortran compiler needs to be compatible with
   the ISO TR-15581 Allocatable Enhancements update to Fortran95. Most current
   Fortran95 compilers do support TR-15581.
   
   
   
2) LIBRARY BUILD
----------------
   In the main directory type

     make
     
   to start building the CRTM library.
   
   If you're using the DEBUG compiler flags you may, unfortunately, see many
   warnings similar to:

     Warning (137): Variable 'cosaz' at (1) is never used and never set
     Warning (112): Variable 'rlongitude' at (1) is set but never used
     Warning (140): Implicit conversion at (1) may cause precision loss
     Warning: Unused dummy argument 'group_index' at (1)   
     PGF90-I-0035-Predefined intrinsic scale loses intrinsic property
     etc..
     
   The actual format depends on the compiler. We are working on eliminating
   these warning messages.



3) TEST CASE BUILDS AND RUNS
----------------------------
   Once the CRTM library is built, type

     make test
     
   to build and run both the forward and k_matrix test/example programs. This process
   does generate a lot of output to screen so be prepared to scroll through it.
   
   Currently there are four forward model test, or example, programs:
     test/forward/Example1_Simple
     test/forward/Example2_SSU
     test/forward/Example3_Zeeman
     test/forward/Example4_ODPS
   And there are the same four cases for the k_matrix model:
     test/k_matrix/Example1_Simple
     test/k_matrix/Example2_SSU
     test/k_matrix/Example3_Zeeman
     test/k_matrix/Example4_ODPS
   
   Both the forward and k_matrix tests should end with output that looks like:
   
   
     ======================
     SUMMARY OF ALL RESULTS
     ======================

     Passed 14 of 14 tests.
     Failed 0 of 14 tests.
   
   
   Currently they both have the same number of tests. If you encounter failures you
   might see something like:
   
   
     ======================
     SUMMARY OF ALL RESULTS
     ======================

     Passed 10 of 14 tests.
     Failed 4 of 14 tests.  <----<<<  **WARNING**
   
   
   Some important things to note about the tests:
     - The supplied results were generated using the gfortran DEBUG build.
     - Comparisons between DEBUG and PRODUCTION builds can be different due
       to various compiler switches that modify floating point arithmetic
       (e.g. optimisation levels), or different hardware.
     - For test failures, you can view the differences between the generated
       and supplied ASCII output files. E.g. to view the k_matrix Example1_Simple
       test case differences for amsua_metop-a you would do something like:
       
         $ cd test/k_matrix/Example1_Simple
         $ diff -u amsua_metop-a.output results/amsua_metop-a.output | more
                   \__________________/ \__________________________/
                             |                        |
                       This file is         This file is supplied
                     generated during       with the CRTM tarball
                       the test run
   


4) LIBRARY INSTALLATION
-----------------------
   To install the CRTM library in the ./lib and ./include directories, type

     make install
   
   You can then copy/move/link these directories to the preferred location
   on your system.
   
   Note: Currently, running the tests also does this. That will change in
         future tarball releases so don;t rely on that behaviour.



5) CLEANUP
----------
   Two cleanup targets are provided in the makefile:
   
     make clean
     
   Removes all the compilation and link products from the libsrc/ directory.
   
     make distclean  
     
   This does the same as the "clean" target but also deletes the library
   and include directories created by the "install" target.
   
   
   
6) FEEDBACK AND CONTACT INFO
----------------------------
   That's really it. Any questions or bug reports can be sent to CRTM Support at

     ncep.list.emc.jcsda_crtm.support@noaa.gov
     
   Constructive suggestions for improving the build procedure(s) are welcome too.
