JCSDA CRTM v2.1.3 Build Instructions ==================================== $Revision: 29405 $ CRTM SUPPORT EMAIL: ncep.list.emc.jcsda_crtm.support@noaa.gov 0) PREAMBLE ----------- The CRTM tarball directory structure looks like: ./ |-configure .............. compiler environment shell source files |-fix .............. CRTM coefficient datafiles |-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 | |-Example3_Zeeman | |-Example5_ClearSky | |-Example6_ChannelSubset | |-Example7_AOD | |-Example9_Aircraft | |-Example10_ScatteringSwitch | `-Example11_SOI `-k_matrix ............. k-matrix model tests/examples |-Example1_Simple | |-coefficients ...... contains the coefficient data for the program | `-results ...... contains the results of the program |-Example2_SSU |-Example3_Zeeman |-Example5_ClearSky |-Example6_ChannelSubset |-Example7_AOD |-Example10_ScatteringSwitch `-Example11_SOI NOTE: The Aircaft capability only applies to the Forward model, so there is no equivalent Example9_Aircraft for the K-matrix model. 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 build system for the CRTM is relatively unsophisticated and is constructed for the Unix "sh" shell (or its derivative bsh, bash, or ksh shells). Currently csh (or any of its variants) is not supported. 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 -fimplicit-none -fconvert=big-endian -ffree-form -fno-second-underscore -frecord-marker=4 -funroll-loops -ggdb -Wall -std=f2003 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: 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 ---------------- Once the compilation environment has been set up, the CRTM library build is performed by simply typing, make in the main directory. At this point you should see the source file compilation output. Depending on the compiler used you may see various warning messages, for example warning: 'cchar[1]{lb: 1 sz: 1}' may be used uninitialized in this function} or PGF90-I-0035-Predefined intrinsic scale loses intrinsic property} etc. The actual format of the warning message depends on the compiler. We are working on eliminating these warning messages where appropriate or necessary. NOTE: The current build process is set up to generate a static library not a shared one. 3) TEST CASE BUILDS AND RUNS ---------------------------- Several test/example programs exercising the forward and K-matrix functions have been supplied with the CRTM. To build and run all these tests, type, make test This process does generate a lot of output to screen so be prepared to scroll through it. Currently there are nine forward model test, or example, programs: test/forward/Example1_Simple test/forward/Example2_SSU test/forward/Example3_Zeeman test/forward/Example5_ClearSky test/forward/Example6_ChannelSubset test/forward/Example7_AOD test/forward/Example9_Aircraft test/forward/Example10_ScatteringSwitch test/forward/Example11_SOI And there are eight cases for the K-matrix model: test/k_matrix/Example1_Simple test/k_matrix/Example2_SSU test/k_matrix/Example3_Zeeman test/k_matrix/Example5_ClearSky test/k_matrix/Example6_ChannelSubset test/k_matrix/Example7_AOD test/k_matrix/Example10_ScatteringSwitch test/k_matrix/Example11_SOI Both the forward and K-matrix tests *should* end with output that looks like: ====================== SUMMARY OF ALL RESULTS ====================== Passed 34 of 34 tests. Failed 0 of 34 tests. If you encounter failures you might see something like: ====================== SUMMARY OF ALL RESULTS ====================== Passed 24 of 34 tests. Failed 10 of 34 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. For example, to view the K-matrix Example1_Simple test case differences for the amsua_metop-a sensor 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 where the amsua_metop-a.output file is generated during the test run, and the results/amsua_metop-a.output file is supplied with the CRTM tarball. - Any differences that typically result are quite small (of the order of microKelvin or less when there is a noticable difference in the computed brightness temperatures), although not always at the numerical precision limit. - A graphical differencing tool such as tkdiff (http://tkdiff.sourceforge.net/), meld (http://meldmerge.org/), or FileMerge/opendiff (on Mac OSX) is recommended for viewing the file differences. 4) LIBRARY INSTALLATION ----------------------- A very simple install target is specified in the supplied makefile to put all the necessary include files (the generated *.mod files containing all the procedure interface information) in an ./include subdirectory and the library itself (the generated libCRTM.a file) in a ./lib subdirectory. The make command is make install The ./include and ./lib subdirectories can then be copied/moved/linked to a more suitable location on your system, for example: $HOME/local/CRTM. NOTE: Currently, running the tests also invokes this install target. That will change in future releases so do not rely on the 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) LINKING TO THE LIBRARY ------------------------- Let's assume you've built the CRTM library and placed the /include and /lib subdirectories in your own local area, $HOME/local/CRTM. In the makefile for your application that uses the CRTM, you will need to add -I$HOME/local/CRTM/include to your list of compilation switches, and the following to your list of link switches, -L$HOME/local/CRTM/lib -lCRTM NOTE: The "-I", "-L", and "-l" switches are ubiquitous and should work with most compilers. Consult your compiler documentation for more information. 7) 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