Contents of /MITgcm/verification/lab_sea/README

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)
  gairxFile      = 'u10m.labsea79'    # 10-m zonal wind
  gairyFile      = 'v10m.labsea79'    # 10-m meridional wind
  tairFile       = 'tair.labsea1979'  # 2-m air temperature
  qaFile         = 'qa.labsea1979'    # 2-m specific humidity
  floFile        = 'flo.labsea1979'   # longwave radiation
  fshFile        = 'fsh.labsea1979'   # shortwave radiation
  rainFile       = 'prate.labsea1979' # precipitation
  evapFile       = 'evap.labsea1979'  # evaporation


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

Running the testscript experiment:
  cd verification
  ./testscript -force lab_sea

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  5  5  7  7  7  8 10  9  6  6  6  6  7  5  7  5  7 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_OPTIONS.h .
  ln -sf ../code/CPP_EEOPTIONS.h .
  ../../../tools/genmake -makefile
    ==> on alhena use:
    ../../../tools/genmake -platform=o2k_noopt -makefile
  make clean
  make depend
  make
  mv mitgcmuv mitgcmuv_1
  
Generating 2-CPU executable:
  cd ../../../verification/lab_sea/input
  ln -sf ../code/SIZE_2x1.h SIZE.h
  ln -sf ../code/CPP_OPTIONS.h .
  ln -sf ../code/CPP_EEOPTIONS_MPI.h CPP_EEOPTIONS.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 model compiles and integrates.  It
is the default experiment of "verification/testscript lab_sea".

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_patch5 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 compare
the output of exp2 to that of exp1:
  cd ../../../verification/lab_sea/matlab
  matlab
  lookat_exp3

If the dynamic ice solvers are correct, they should converge to a
constant solution.  The tests above show that both the ADI and the LSR
solver are unable to handle periodic domains and therefore that they
cannot be "correctly" parallelized.


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.  Work is underway to fix this problem.


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
1	Example: Labrador Sea Region with Sea-Ice
2	=========================================
3
4	This example sets up a small (20x16x23) Labrador Sea experiment
5	coupled to a dynamic thermodynamic sea-ice model.
6	A brief description of the sea-ice model is in "seaice.ps".
7
8	The domain of integration spans 280E to 320E and 46N to 78N.
9	Horizontal grid spacing is 2 degrees.
10	The 23 vertical levels and the bathymetry file
11	bathyFile = 'bathy.labsea'
12	are obtained from the the 2-degree ECCO configuration.
13
14	Integration is initialized from annual-mean Levitus climatology
15	hydrogThetaFile = 'LevCli_temp.labsea'
16	hydrogSaltFile = 'LevCli_salt.labsea'
17
18	Surface salinity relaxation is to the monthly mean Levitus climatology
19	saltClimFile = 'SSS.labsea'
20
21	Forcing files are a 1979-1999 monthly climatology computed from the
22	NCEP reanalysis (see pkg/seaice/SEAICE_FFIELDS.h for units and signs)
23	gairxFile = 'u10m.labsea79' # 10-m zonal wind
24	gairyFile = 'v10m.labsea79' # 10-m meridional wind
25	tairFile = 'tair.labsea1979' # 2-m air temperature
26	qaFile = 'qa.labsea1979' # 2-m specific humidity
27	floFile = 'flo.labsea1979' # longwave radiation
28	fshFile = 'fsh.labsea1979' # shortwave radiation
29	rainFile = 'prate.labsea1979' # precipitation
30	evapFile = 'evap.labsea1979' # evaporation
31
32
33	Using testscript to test sea-ice code
34	=====================================
35
36	Running the testscript experiment:
37	cd verification
38	./testscript -force lab_sea
39
40	Note that fairly large differences in accuracy occur across different
41	platforms. For example, testscript comparisons between g77 (Linux)
42	and f77 (SGI) generated output gives:
43
44	T S U V
45	C D M c m s m s m s m s
46	n p a R g m m e . m m e . m m e . m m e .
47	f n k u 2 i a a d i a a d i a a d i a a d
48	g d e n d n x n . n x n . n x n . n x n .
49
50	Y Y Y Y 5 5 7 7 7 8 10 9 6 6 6 6 7 5 7 5 7 FAIL lab_sea
51
52
53	Instructions for generating 1-CPU and 2-CPU executables
54	=======================================================
55
56	Generating 1-CPU executable:
57	cd ../verification/lab_sea/input
58	ln -sf ../code/SIZE.h .
59	ln -sf ../code/CPP_OPTIONS.h .
60	ln -sf ../code/CPP_EEOPTIONS.h .
61	../../../tools/genmake -makefile
62	==> on alhena use:
63	../../../tools/genmake -platform=o2k_noopt -makefile
64	make clean
65	make depend
66	make
67	mv mitgcmuv mitgcmuv_1
68
69	Generating 2-CPU executable:
70	cd ../../../verification/lab_sea/input
71	ln -sf ../code/SIZE_2x1.h SIZE.h
72	ln -sf ../code/CPP_OPTIONS.h .
73	ln -sf ../code/CPP_EEOPTIONS_MPI.h CPP_EEOPTIONS.h
74	../../../tools/genmake -mpi -makefile
75	==> on alhena for comparison purposes use:
76	../../../tools/genmake -mpi -platform=o2k_noopt -makefile
77	==> on alhena for fast execution use:
78	../../../tools/genmake -mpi -platform=o2k -makefile
79	make clean
80	make depend
81	make
82	mv mitgcmuv mitgcmuv_2x1
83
84
85	Instructions for running Experiment 1
86	=====================================
87
88	This is a 1-cpu, 10-hour integration used to make sure that all the
89	files are available and that the model compiles and integrates. It
90	is the default experiment of "verification/testscript lab_sea".
91
92	To run Experiment 1:
93	cd ../../../verification/lab_sea/input
94	ln -sf data.10hours data
95	ln -sf data.seaice.adi data.seaice
96	mitgcmuv_1 >&! output.txt
97	mkdir exp1
98	mv *tave.0000000010.data exp1
99
100	Use matlab script lookat_exp1.m to compare the output
101	of exp1 with that from release1_patch5 sea-ice code:
102	cd ../../../verification/lab_sea/matlab
103	matlab
104	lookat_exp1
105
106
107	Instructions for running Experiment 2
108	=====================================
109
110	This is a 1-cpu test of the LSR solver. The solution is
111	compared to that of experiment 1, which used the ADI solver.
112
113	To run Experiment 2:
114	cd ../../../verification/lab_sea/input
115	ln -sf data.10hours data
116	ln -sf data.seaice.lsr data.seaice
117	mitgcmuv_1 >&! output.txt
118	mkdir exp2
119	mv *tave.0000000010.data exp2
120
121	Use matlab script lookat_exp2.m to compare
122	the output of exp2 to that of exp1:
123	cd ../../../verification/lab_sea/matlab
124	matlab
125	lookat_exp2
126
127
128	Instructions for running Experiment 3
129	=====================================
130
131	This is a test of periodic boundary conditions for LSR
132	and ADI solvers. The domain has a flat bottom and
133	is periodic both in the x and the y directions.
134	All forcing files are null or constant (u10m = v10m = 5 m/s).
135
136	To run Experiment 3:
137	cd ../../../verification/lab_sea/input
138	ln -sf data.1hour data
139	ln -sf data.seaice.testadi data.seaice
140	mitgcmuv_1 >&! output.txt
141	mkdir exp3a
142	mv *tave.0000000001.data exp3a
143	ln -sf data.seaice.testlsr data.seaice
144	mitgcmuv_1 >&! output.txt
145	mkdir exp3b
146	mv *tave.0000000001.data exp3b
147
148	Use matlab script lookat_exp3.m to compare
149	the output of exp2 to that of exp1:
150	cd ../../../verification/lab_sea/matlab
151	matlab
152	lookat_exp3
153
154	If the dynamic ice solvers are correct, they should converge to a
155	constant solution. The tests above show that both the ADI and the LSR
156	solver are unable to handle periodic domains and therefore that they
157	cannot be "correctly" parallelized.
158
159
160	Instructions for running Experiment 4
161	=====================================
162
163	This is a 2-cpu, 10-hour integration used to test
164	tile edges for sea-ice dynamic solvers.
165
166	To run Experiment 4:
167	cd ../../../verification/lab_sea/input
168	ln -sf data.10hours data
169	ln -sf data.seaice.adi data.seaice
170	mpirun -np 2 mitgcmuv_2x1
171	mkdir exp4
172	mv *tave.0000000010.data exp4
173
174	Use the matlab script lookat_exp4.m to compare
175	the 2-cpu output to that of exp1:
176	cd ../../../verification/lab_sea/matlab
177	matlab
178	lookat_exp4
179
180	The inaccuracy at the tile boundary can be decreased by increasing
181	NPSEUDO in data.seaice at the expense of computation time.
182	Also as sea-ice ages (thickens) the difference at the tiles becomes
183	increasingly small. For solver pkg/seaice/adi.F a value of NPSEUDO=10
184	appears adequate for forward integrations but cannot be used for sea-ice
185	adjoint model. Work is underway to fix this problem.
186
187
188	Instructions for running Experiment 5
189	=====================================
190
191	This is a 2-cpu, 2-year, test integration. It illustrates
192	convention used by seaice_get_forcing.F for multi-year forcing.
193
194	To run Experiment 5:
195	cd ../../../verification/lab_sea/input
196	ln -sf data.2years data
197	ln -sf data.seaice.adi data.seaice
198	ln -sf evap.labsea1979 evap.labsea1980
199	ln -sf flo.labsea1979 flo.labsea1980
200	ln -sf fsh.labsea1979 fsh.labsea1980
201	ln -sf prate.labsea1979 prate.labsea1980
202	ln -sf qa.labsea1979 qa.labsea1980
203	ln -sf tair.labsea1979 tair.labsea1980
204	ln -sf u10m.labsea79 u10m.labsea80
205	ln -sf v10m.labsea79 v10m.labsea80
206	mpirun -np 2 mitgcmuv_2x1
207
208	Use the matlab script lookat_exp5.m to compare
209	the 2-cpu output to SMMR-SSM/I data:
210	cd ../../../verification/lab_sea/matlab
211	matlab
212	lookat_exp5
213
214	Disclaimer:
215	The comparison here is just for fun, not really supposed
216	to look anything like the data.
217	Otherwise it would put a lot of people out of business :-)
218
219	Instructions for running Experiment 6
220	=====================================
221
222	This is a 1-cpu test of sea-ice thermodynamics (no dynamics).
223	The solution is compared to that of experiment 1.
224
225	To run Experiment 6:
226	cd ../../../verification/lab_sea/input
227	ln -sf data.10hours data
228	ln -sf data.seaice.nodynamics data.seaice
229	mitgcmuv_1 >&! output.txt
230	mkdir exp6
231	mv *tave.0000000010.data exp6
232
233	Use the matlab script lookat_exp6.m to compare
234	the output of exp6 to that of exp1:
235	cd ../verification/lab_sea/matlab
236	matlab
237	lookat_exp6
238
239	Instructions for running Experiment 7
240	=====================================
241
242	This is a 2-cpu, 10-hour integration used to test
243	tile edges for sea-ice thermodynamics (no dynamics).
244	2-CPU executable from experiment 4 is required.
245
246	To run Experiment 7:
247	cd ../../../verification/lab_sea/input
248	ln -sf data.10hours data
249	ln -sf data.seaice.nodynamics data.seaice
250	mpirun -np 2 mitgcmuv_2x1
251	mkdir exp7
252	mv *tave.0000000010.data exp7
253
254	Use the matlab script lookat_exp7.m to compare
255	the output of exp7 to that of exp6:
256	cd ../verification/lab_sea/matlab
257	matlab
258	lookat_exp7