================================================================================
Model Evaluation Tools (MET) TERMS OF USE - IMPORTANT!
================================================================================

Copyright 2022, UCAR/NCAR, NOAA, CSU/CIRA, and CU/CIRES
Licensed under the Apache License, Version 2.0 (the "License");
   You may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

================================================================================
This is the main directory for the Model Evaluation Tools source code release.
================================================================================

For questions, please:
- Refer to the MET User's Guide: https://met.readthedocs.io/en/latest
- Refer to the MET website: http://dtcenter.org/community-code/model-evaluation-tools-met
- Create a post in the METplus GitHub Discussions forum: https://github.com/dtcenter/METplus/discussions

Dependencies
------------

- MET requires the following to be installed on your system prior to building:
   - UniData's NetCDF4 Library
      - http://www.unidata.ucar.edu/software/netcdf
      - Both NetCDF-C and NetCDF-CXX are required
   - GNU Scientific Library (GSL), developer's version
      - http://www.gnu.org/software/gsl
   - Zlib
      - http://www.zlib.net
   - HDF5, to support NetCDF4
     - https://support.hdfgroup.org/ftp/HDF5
   - NCEP's BUFRLIB Library, if wishing to compile PB2NC
      - http://www.nco.ncep.noaa.gov/sib/decoders/BUFRLIB
   - NCEP's GRIB2 Library in C (g2clib), if wishing to compile GRIB2 support
      - jasperlib, libpng, and zlib also required for GRIB2 support
      - http://www.nco.ncep.noaa.gov/pmb/codes/GRIB2
   - Python 3.6, or later, if wishing to compile Python support
   - HDF4 and HDF-EOS2 libraries, if wishing to compile MODIS-Regrid
      - http://www.hdfgroup.org/products/hdf4
      - http://www.hdfgroup.org/hdfeos.html
   - Cairo and FreeType, if wishing to compile MODE-Graphics
      - http://cairographics.org/releases
      - http://www.freetype.org/download.html

- It is suggested that the following tools be used in conjunction with MET:
   - Unified Post-Processor
      - http://dtcenter.org/community-code/unified-post-processor-upp

NOTE: The required libraries should be compiled with the same set of compilers
      to be used in compiling MET.

How to compile and run?
-----------------------

For more detailed instructions on building MET and for a list of supported
platforms and compilers, please refer to the MET User's Guide in the doc/
sub-directory, or the MET Online Tutorial:
  http://dtcenter.org/community-code/model-evaluation-tools-met/online-tutorial

- Set the $CXX and $F77 environment variables to specify the C++ and FORTRAN
  compilers to be used.  If not set, configure will search for compilers and the
  ones if finds may or may not be compatible with those used to compile the
  needed third party libraries.

- If compiling on a big endian machine set the $CXXFLAGS environment variable to
  include '-DBIGENDIAN'.

- Set environment variables to point to the locations of the needed third party
  libraries.  For each library, there are three possible environment variables.
  If the library is installed in one location with an "include" subdirectory
  containing the include files and a "lib" directory containing the library
  files, the $MET_<lib> environment should be set to point to that main
  directory. If the include and library files files are installed in any other
  way, the $MET_<lib>INC and $MET_<lib>INC environment variables should both be
  set, with $MET_<lib>INC pointing to the directory with the include files and
  $MET_<lib>LIB pointing to the directory with the library files.  If
  $MET_<lib>INC and $MET_<lib>LIB are defined, then $MET_<lib> is ignored.

   - Set $MET_NETCDF to point to the main NetCDF directory, or set
     $MET_NETCDFINC to point to the directory with the NetCDF include files
     and set $MET_NETCDFLIB to point to the directory with the NetCDF
     library files.

   - Set $MET_HDF5 to point to the main HDF5 directory.

   - Set $MET_BUFR to point to the main BUFR directory, or set $MET_BUFRLIB
     to point to the directory with the BUFR library files.  Because we don't
     use any BUFR library include files, you don't need to specify
     $MET_BUFRINC.

   - Set $MET_GSL to point to the main GSL directory, or set $MET_GSLINC to
     point to the directory with the GSL include files and set $MET_GSLLIB
     to point to the directory with the GSL library files.

   - If compiling support for GRIB2, set $MET_GRIB2CINC and $MET_GRIB2CLIB
     to point to the main GRIB2C directory which contains both the include
     and library files.  These are used instead of $MET_GRIB2C since the main
     GRIB2C directory does not contain include and lib subdirectories.

   - If compiling support for PYTHON, set $MET_PYTHON_CC and $MET_PYTHON_LD
     to specify the compiler (-I) and linker (-L) flags required for python.
     Set $MET_PYTHON_CC for the directory containing the "Python.h" header file,
     which is the output of running 'python-config --cflags'.
     Set $MET_PYTHON_LD for the directory containing the python library file
     and indicate the library file names, which is the output of running
     'python-config --ldflags'.
     For example:
     MET_PYTHON_CC=`python-config --cflags`
     MET_PYTHON_LD=`python-config --ldflags`
     For more information about Python support in MET, please refer to Appendix
     F of the MET User's Guide.

   - If compiling MODIS-Regrid, set $MET_HDF to point to the main HDF directory,
     or set $MET_HDFINC to point to the directory with the HDF include files
     and set $MET_HDFLIB to point to the directory with the HDF library files.
     Also, set $MET_HDFEOS to point to the main HDF EOS directory, or set
     $MET_HDFEOSINC to point to the directory with the HDF EOS include files
     and set $MET_HDFEOSLIB to point to the directory with the HDF EOS library
     files.

   - If compiling MODE Graphics, set $MET_CAIRO to point to the main Cairo
     directory, or set $MET_CAIROINC to point to the directory with the Cairo
     include files and set $MET_CAIROLIB to point to the directory with the
     Cairo library files. Also, set $MET_FREETYPE to point to the main FreeType
     directory, or set $MET_FREETYPEINC to point to the directory with the
     FreeType include files and set $MET_FREETYPELIB to point to the directory
     with the FreeType library files.

   - When running MODE Graphics, set $MET_FONT_DIR to the directory containing
     font data required at runtime.  A link to the tarball containing this font
     data can be found on the downloads page of the MET website.

- Configure the installation for your system using the configure script.  The
  configure script has command line options to specify where to install MET and
  which MET utilities to install.  Type "./configure --help" for a detailed list
  of options, including the following:

  --prefix=PREFIX
      By default, MET will install all the files in "/usr/local/bin".  You can
      specify an installation prefix other than "/usr/local" using "--prefix",
      for instance "--prefix=$HOME" or "--prefix=`pwd`".

  --enable and --disable options for each of the MET tools.

  By default, compilation of GRIB2 support, Python support, the MODIS-Regrid
  tool, the Lidar2NC tool,and MODE-Graphics are disabled.
  Use the following options to enable them:

  --enable-grib2
      Enable compilation of utilities using GRIB2
      Requires $MET_GRIB2C

  --enable-python
      Enable compilation of python interface
      Requires $MET_PYTHON_CC and $MET_PYTHON_LD

  --enable-modis
      Enable compilation of modis
      Requires $MET_HDF and $MET_HDFEOS

  --enable-mode_graphics
      Enable compilation of mode_graphics
      Requires $MET_CAIRO, $MET_FREETYPE, and $MET_FONT_DIR

  --enable-lidar2nc
      Enable compilation of lidar2nc
      Requires $MET_HDF

  To configure MET to install all of the available tools in the "bin"
  subdirectory of your current directory, you would use the following command:

  ./configure --prefix=`pwd` --enable-grib2 --enable-python \
              --enable-modis --enable-mode_graphics --enable-lidar2nc

- Type 'make install >& make_install.log &'

- Type 'tail -f make_install.log' to view the execution of the make.

- When make is finished, type 'CNTRL-C' to quit the tail.

- If all tools are enabled and the build is successful, the "<prefix>/bin"
  directory (where <prefix> is the prefix you specified on your configure
  command line) will contain the following executables:
   - ascii2nc
   - ensemble_stat
   - gen_ens_prod
   - gen_vx_mask
   - grid_stat
   - gis_dump_dbf
   - gis_dump_shp
   - gis_dump_shx
   - grid_diag
   - gsid2mpr
   - gsidens2orank
   - ioda2nc
   - lidar2nc
   - madis2nc
   - mode
   - mode_analysis
   - modis_regrid
   - mtd
   - pb2nc
   - pcp_combine
   - plot_data_plane
   - plot_mode_field
   - plot_point_obs
   - point2grid
   - point_stat
   - regrid_data_plane
   - rmw_analysis
   - series_analysis
   - shift_data_plane
   - stat_analysis
   - tc_diag
   - tc_dland
   - tc_gen
   - tc_pairs
   - tc_rmw
   - tc_stat
   - wavelet_stat
   - wwmca_plot
   - wwmca_regrid

- Type 'ls <prefix>/bin' to check for the presence of the executables.

- Type 'make test >& make_test.log &' to run all of the test scripts in the
  directory.  These test scripts use test data supplied with the tarball.  For
  instructions on running your own data, please refer to the MET User's Guide.

- Type 'tail -f make_test.log' to view the execution of the test script.

- When the test script is finished, type 'CNTRL-C' to quit the tail.

- Look in "out" to find the output files for these tests.

- In particular, check that the PB2NC tool ran without error.  If there was an
  error, run "make clean" then rerun your configure command adding
  "--disable-block4" to your configure command line and rebuild MET.
