Example: Labrador Sea Region with Sea-Ice
=========================================

This example sets up a small (20x16x23) Labrador Sea experiment
coupled to a dynamic thermodynamic sea-ice model.
A brief description of the sea-ice model is in "seaice.ps".

The domain of integration spans 280E to 320E and 46N to 78N.
Horizontal grid spacing is 2 degrees.
The 23 vertical levels and the bathymetry file
  bathyFile      = 'bathy.labsea'
are obtained from the the 2-degree ECCO configuration.

Integration is initialized from annual-mean Levitus climatology
 hydrogThetaFile = 'LevCli_temp.labsea'
 hydrogSaltFile  = 'LevCli_salt.labsea'

Surface salinity relaxation is to the monthly mean Levitus climatology
 saltClimFile    = 'SSS.labsea'

Forcing files are a 1979-1999 monthly climatology computed from the
NCEP reanalysis (see pkg/seaice/SEAICE_FFIELDS.h for units and signs)
  uwindFile      = 'u10m.labsea79'    # 10-m zonal wind
  vwindFile      = 'v10m.labsea79'    # 10-m meridional wind
  atempFile      = 'tair.labsea1979'  # 2-m air temperature
  aqhFile        = 'qa.labsea1979'    # 2-m specific humidity
  lwdownFile     = 'flo.labsea1979'   # downward longwave radiation
  swdownFile     = 'fsh.labsea1979'   # downward shortwave radiation
  precipFile     = 'prate.labsea1979' # precipitation
  evapFile       = 'evap.labsea1979'  # evaporation


Using testscript to test sea-ice code
=====================================

Running the testscript experiment:
  cd verification
  ./testscript -force lab_sea
The default experiment is Experiment 8, below.
It uses pkg/gmredi, pkg/kpp, pkg/seaice, and pkg/exf.

Note that fairly large differences in accuracy occur across different
platforms.  For example, testscript comparisons between g77 (Linux)
and f77 (SGI) generated output gives:

                T           S           U           V
C D M    c        m  s        m  s        m  s        m  s
n p a R  g  m  m  e  .  m  m  e  .  m  m  e  .  m  m  e  .
f n k u  2  i  a  a  d  i  a  a  d  i  a  a  d  i  a  a  d
g d e n  d  n  x  n  .  n  x  n  .  n  x  n  .  n  x  n  .

Y Y Y Y  8 10  9 11 10  9 11 13 10  9  8  8  9  8  9  8  9 FAIL  lab_sea


Instructions for generating 1-CPU and 2-CPU executables
=======================================================

Generating 1-CPU executable:
  cd verification/lab_sea/input
  ln -sf ../code/SIZE.h .
  ln -sf ../code/CPP_EEOPTIONS.h .
  ln -sf ../code/CPP_OPTIONS.NOEXF.h CPP_OPTIONS.h
  rm -f SEAICE_OPTIONS.h
  ../../../tools/genmake -makefile
    ==> on alhena use:
    ../../../tools/genmake -platform=o2k_noopt -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_1

Generating 1-CPU executable with SEAICE_EXTERNAL_FORCING:
  cd ../../../verification/lab_sea/input
  ln -sf ../code/SIZE.h .
  ln -sf ../code/CPP_EEOPTIONS.h .
  ln -sf ../code/CPP_OPTIONS.h .
  ln -sf ../code/ECCO_CPPOPTIONS.h .
  ln -sf ../code/SEAICE_OPTIONS.h .
  ../../../tools/genmake -makefile
    ==> on alhena use:
    ../../../tools/genmake -platform=o2k_noopt -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_exf_forcing

1-CPU executable with SEAICE_EXTERNAL_FORCING, without READ_EVAP
  cd ../../../verification/lab_sea/input
  ln -sf ../code/SIZE.h .
  ln -sf ../code/CPP_EEOPTIONS.h .
  ln -sf ../code/CPP_OPTIONS.h .
  ln -sf ../code/ECCO_CPPOPTIONS.BULK.h ECCO_CPPOPTIONS.h
  ln -sf ../code/SEAICE_OPTIONS.h .
  ../../../tools/genmake -makefile
    ==> on alhena use:
    ../../../tools/genmake -platform=o2k_noopt -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_compute_evap

Generating 1-CPU executable with SEAICE_EXTERNAL_FLUXES:
  cd ../../../verification/lab_sea/input
  ln -sf ../code/SIZE.h .
  ln -sf ../code/CPP_EEOPTIONS.h .
  ln -sf ../code/CPP_OPTIONS.h .
  ln -sf ../code/ECCO_CPPOPTIONS.BULK.h ECCO_CPPOPTIONS.h
  ln -sf ../code/SEAICE_OPTIONS.EXF_FLUXES.h SEAICE_OPTIONS.h
  ../../../tools/genmake -makefile
    ==> on alhena use:
    ../../../tools/genmake -platform=o2k_noopt -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_exf_fluxes
  
Generating 2-CPU executable:
  cd ../../../verification/lab_sea/input
  ln -sf ../code/SIZE.2x1.h SIZE.h
  ln -sf ../code/CPP_EEOPTIONS.MPI.h CPP_EEOPTIONS.h
  ln -sf ../code/CPP_OPTIONS.NOEXF.h CPP_OPTIONS.h
  rm -f SEAICE_OPTIONS.h
  ../../../tools/genmake -mpi -makefile
    ==> on alhena for comparison purposes use:
      ../../../tools/genmake -mpi -platform=o2k_noopt -makefile
    ==> on alhena for fast execution use:
      ../../../tools/genmake -mpi -platform=o2k -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_2x1


Instructions for running Experiment 1
=====================================

This is a 1-cpu, 10-hour integration used to make sure that all
the files are available and that the sea-ice model compiles and
runs.  The reading of atmospheric forcing files and the computation
of open-water bulk fluxes are carried out within pkg/seaice.

To run Experiment 1:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.adi data.seaice
  mitgcmuv_1 >&! output.txt
  mkdir exp1
  mv *tave.0000000010.data exp1

Use matlab script lookat_exp1.m to compare the output
of exp1 with that from release1_p10 sea-ice code:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp1


Instructions for running Experiment 2
=====================================

This is a 1-cpu test of the LSR solver.  The solution is
compared to that of experiment 1, which used the ADI solver.

To run Experiment 2:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.lsr data.seaice
  mitgcmuv_1 >&! output.txt
  mkdir exp2
  mv *tave.0000000010.data exp2

Use matlab script lookat_exp2.m to compare
the output of exp2 to that of exp1:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp2


Instructions for running Experiment 3
=====================================

This is a test of periodic boundary conditions for LSR
and ADI solvers.  The domain has a flat bottom and
is periodic both in the x and the y directions.
All forcing files are null or constant (u10m = v10m = 5 m/s).

To run Experiment 3:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.1hour data
  ln -sf DATA.SEAICE.testadi data.seaice
  mitgcmuv_1 >&! output.txt
  mkdir exp3a
  mv *tave.0000000001.data exp3a
  ln -sf DATA.SEAICE.testlsr data.seaice
  mitgcmuv_1 >&! output.txt
  mkdir exp3b
  mv *tave.0000000001.data exp3b

Use matlab script lookat_exp3.m to look at
results from exp3a and exp3b:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp3

If the dynamic ice solvers are correct, they should converge to a
solution that is constant at each latitude.


Instructions for running Experiment 4
=====================================

This is a 2-cpu, 10-hour integration used to test
tile edges for sea-ice dynamic solvers.

To run Experiment 4:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.adi data.seaice
  mpirun -np 2 mitgcmuv_2x1
  mkdir exp4
  mv *tave.0000000010.data exp4

Use the matlab script lookat_exp4.m to compare
the 2-cpu output to that of exp1:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp4

The inaccuracy at the tile boundary can be decreased by increasing
NPSEUDO in data.seaice at the expense of computation time.
Also as sea-ice ages (thickens) the difference at the tiles becomes
increasingly small.  For solver pkg/seaice/adi.F a value of NPSEUDO=10
appears adequate for forward integrations but cannot be used for sea-ice
adjoint model.  With NPSEUDO=300 or greater, the tile disappears, but the
computational cost is very large (11 times that of teh forward model).


Instructions for running Experiment 5
=====================================

This is a 2-cpu, 2-year, test integration.  It illustrates
convention used by seaice_get_forcing.F for multi-year forcing.

To run Experiment 5:
  cd ../../../verification/lab_sea/input
  ln -sf      DATA.2years             data
  ln -sf  DATA.SEAICE.adi      data.seaice
  ln -sf  evap.labsea1979  evap.labsea1980  
  ln -sf   flo.labsea1979   flo.labsea1980   
  ln -sf   fsh.labsea1979   fsh.labsea1980   
  ln -sf prate.labsea1979 prate.labsea1980 
  ln -sf    qa.labsea1979    qa.labsea1980    
  ln -sf  tair.labsea1979  tair.labsea1980  
  ln -sf    u10m.labsea79    u10m.labsea80    
  ln -sf    v10m.labsea79    v10m.labsea80    
  mpirun -np 2 mitgcmuv_2x1

Use the matlab script lookat_exp5.m to compare
the 2-cpu output to SMMR-SSM/I data:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp5

Disclaimer:
The comparison here is just for fun, not really supposed
to look anything like the data.
Otherwise it would put a lot of people out of business :-)

Instructions for running Experiment 6
=====================================

This is a 1-cpu test of sea-ice thermodynamics (no dynamics).
The solution is compared to that of experiment 1.

To run Experiment 6:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.nodynamics data.seaice
  mitgcmuv_1 >&! output.txt
  mkdir exp6
  mv *tave.0000000010.data exp6

Use the matlab script lookat_exp6.m to compare
the output of exp6 to that of exp1:
  cd ../verification/lab_sea/matlab
  matlab
  lookat_exp6

Instructions for running Experiment 7
=====================================

This is a 2-cpu, 10-hour integration used to test
tile edges for sea-ice thermodynamics (no dynamics).
2-CPU executable from experiment 4 is required.

To run Experiment 7:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.nodynamics data.seaice
  mpirun -np 2 mitgcmuv_2x1
  mkdir exp7
  mv *tave.0000000010.data exp7

Use the matlab script lookat_exp7.m to compare
the output of exp7 to that of exp6:
  cd ../verification/lab_sea/matlab
  matlab
  lookat_exp7


Instructions for running Experiment 8
=====================================

This is the default experiment which is executed by
verification/testscript.  It is a 1-cpu, 10-hour integration
used to test CPP option SEAICE_EXTERNAL_FORCING.  Atmospheric
state is read-in using pkg/exf, rather than pkg/seaice routines.
This experiment uses pkg/gmredi, pkg/kpp, pkg/seaice, and pkg/exf.

To run Experiment 8:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours_exf data
  ln -sf DATA.SEAICE.adi_exf data.seaice
  mitgcmuv_exf_forcing >&! output.txt
  mkdir exp8
  mv *tave.0000000010.data exp8

Use matlab script lookat_exp8.m to compare
the output of exp8 to that of exp1:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp8


Instructions for running Experiment 9
=====================================

This is a 1-cpu, 10-hour integration used to test CPP option
SEAICE_EXTERNAL_FLUXES.  Both the atmospheric state and the
open-water surface fluxes are provided by pkg/exf.

To run Experiment 9:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours_exf data
  ln -sf DATA.SEAICE.adi_exf data.seaice
  mitgcmuv_exf_fluxes >&! output.txt
  mkdir exp9
  mv *tave.0000000010.data exp9

Use matlab script lookat_exp9.m to compare
the output of exp9 to that of exp8:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp9


Instructions for running Experiment 10
======================================

This is a 1-cpu, 10-hour integration similar to exp8, but
with bulk formula computation of evaporation fields.

To run Experiment 10:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours_exf data
  ln -sf DATA.SEAICE.adi_exf data.seaice
  mitgcmuv_compute_evap >&! output.txt
  mkdir exp10
  mv *tave.0000000010.data exp10

Use matlab script lookat_exp10.m to compare
the output of exp10 to that of exp8:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp10