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.lsr 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_p16 sea-ice code:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp1


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

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

To run Experiment 2:
  cd ../../../verification/lab_sea/input
  ln -sf DATA.10hours data
  ln -sf DATA.SEAICE.adi 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

Both solvers should and do converge to solutions
that are constant at each latitude.  But note that
the two solutions are not exactly the same because
the two solvers represent slightly different
approximations of the viscous/plastic equations.


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.lsr 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 accuracy of the dynamic solvers is increased by
reducing parameter LSR_ERROR for the LSR solver and
by increasing parameter NPSEUDO for the ADI solver.
The computational cost/accuracy trade-off is quite
high for the ADI solver but relatively small for
the LSR solver, which is the default solver.


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.lsr      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

The comparison here is just for fun.
The configuration is too coarse and artificial
to reproduce realistic sea-ice conditions.


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.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.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.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