
README               May 25, 2021

                     by Hiromasa Yoshimura
                        Meteorological Research Institute, Japan Meteorological Agency


Source code of semi-implicit semi-Lagrangian spectral shallow water models using double Fourier series (DFS) and spherical harmonics (SH), which is used in Yoshimura (2001).


[Paper]

  Yoshimura, H.: Improved double Fourier series on a sphere and its application to a semi-implicit semi-Lagrangian shallow water model, 2021.


[License]

  The source code of the shallow water models is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (See also LICENSE.txt).


[Directries and Files]

  README.txt   : This file

  LiCENSE.txt  : Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License

  shallow_water_DFS/  Shallow weter model using DFS
    Makefile   : For compiling source code
    sw_dfs.F90 : Main program 
    *.F90      : Subroutines

  shallow_water_SH/   Shallow weter model using SH
    Makefile   : For compiling source code
    sw_sh.F90  : Main program 
    *.F90      : Subroutines

  bihar/              Netlib BIHAR library
    Makefile   : For compiling source code
    *.f        : Subroutines


[Use of public libraries]

  The shallow water models utilize the Netlib BIHAR library and the ISPACK library.

  The Netlib BIHAR library in the "bihar" directory has been downloaded from https://www.netlib.org/bihar/.
    This library contains a double precision version of the Netlib FFTPACK library.

  The ISPACK library can be downloaded from https://www.gfd-dennou.org/arch/ispack/ispack-3.0.1.tar.gz.
    This library is under the GNU Lesser General Public License (LGPL-2.1 or later).


[How to compile and run the models]

  Compile the ISPACK library

    Put ispack-3.0.1.tar.gz in the same directory as "shallow_water_DFS", "shallow_water_SH" and "bihar".

    Extract .tar.gz file
      > tar xvzf ispack-3.0.1.tar.gz 

    Compile the ISPACK library to create ispack-3.0.1/libispack3.a.
      > cd ispack-3.0.1
      Edit Mkinclude.  (See ispack-3.0.1/README.)
        Set "DIRS = mxpack lxpack" in Mkinclude.
        If you use optimization for Intel AVX512, set "SSE = avx512" in Mkinclude.
      > make
      > cd ..

  Compile the Netlib BIHAR library

    Compile the Netlib BIHAR library to create bihar/libbihar.a.
      > cd netlib
      Edit Makefile.  (Set FC, OPT and FFLAGS.)
      > make
      > cd ..

  Compile and run the shallow water model using DFS.

    Compile the model to create executable binary "sw_dfs".
      > cd shallow_water_DFS
      Edit Makefile.  (Set FC, OPT, FFLAGS and LFLAGS.)
      Edit sw_dfs.F90.
        (Set JCN_GRID, JCN_INITIAL, JCN_HDIFF, JCN_MONIT, INTHR_MONIT, IMAX, JMAX, NMAX, TIMESTEP, etc.)
      > make

    Run the model.
        > export OMP_NUM_THREADS=xxx  (Set the number of OpenMP threads.)
        > ./sw_dfs
      or
        Edit fcst_sw_dfs.sh.
        Execute fcst_sw_dfs.sh.

  Compile and run the shallow water model using SH.

    Compile the model to create executable binary "sw_sh".
      > cd shallow_water_SH
      Edit Makefile.  (Set FC, OPT, FFLAGS and LFLAGS.)
      Edit sw_sh.F90.
        (Set JCN_INITIAL, JCN_HDIFF, JCN_MONIT, INTHR_MONIT, IMAX, JMAX, NMAX, TIMESTEP, etc.)
      > make

    Run the model.
        > export OMP_NUM_THREADS=xxx  (Set the number of OpenMP threads)
        > ./sw_sh
      or
        Edit fcst_sw_sh.sh.
        Execute fcst_sw_sh.sh.


[Output data from the models]

  *.ctl: Grads contol file (text file).
  *.dr : Real(4) binary data. Unformatted direct access file.

  data.ctl, data.dr: Simulated lon-lat data.
    Variables: h (height), u (zonal wind), v (meridional wind), vor (vorticity), div (divergence).

  norm.ctl, norm.dr: Error of predicted height (for Williamson test case 2).
    Variables: norm_L1 (L1 norm), norm_L2 (L2 norm), norm_Lmax (Lmax norm).

  spectrum.ctl, spectrum.dr: Kinetic Energy spectrum.
    Variables: KE_VOR (Kinetic Energy (Vorticity)), KE_DIV (Kinetic Energy (Divergence)).

  - Files can be read and visualized by using grads.
    http://cola.gmu.edu/grads/

  - Files can be converted to NetCDF by using cdo.
    > cdo -f nc4 import_binary aaa.ctl aaa.nc
    https://code.mpimet.mpg.de/projects/cdo/




