-
Notifications
You must be signed in to change notification settings - Fork 9
/
wave.tex
2339 lines (2116 loc) · 100 KB
/
wave.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\section{Configuring ROMS for a Specific Application}
\label{Wave}
This chapter describes the parts of ROMS for which the user is
responsible when configuring it for a given application. Section
\ref{User} describes the process in a generic fashion while
\S\ref{UpDown}, \S\ref{ARCTIC}, \S\ref{NWGOA} and \S\ref{BEAUFORT}
step through the application of ROMS to idealized upwelling/downwelling
and several realistic wind-driven domains respectively. As
distributed, ROMS is ready to run quite a few examples, where the
C preprocessor flags determine which is to be executed. Some of
these examples are described in \citet{Haidvogel99}, some are listed
here:
\begin{klist}
\kitem{BASIN} This is a rectangular, flat-bottomed basin with
double-gyre wind forcing. When run, it produces a western boundary
current flowing into a central ``Gulf Stream''
which goes unstable and generates eddies. The goal is to run
adiabatically to study the homogenization of potential vorticity.
It earned its nickname of Big Bad Basin by taking a long time to
run and by causing difficulties for the spectral versions of SPEM.
% \kitem{CANYON\_A} The canyon is a periodic channel with a steep shelf
% along one wall, where the shelf contains a steep canyon. There is a
% periodic forcing which causes the water to oscillate along the
% channel. The rotation and the shelf lead to non-zero mean flows,
% especially near the canyon. Version A is homogeneous and can be
% executed with a 2-D model. See \citet{HB97} for
% a description of the canyon problems and the gravitational adjustment
% problem.
% \kitem{CANYON\_B} This is like Canyon A, except that it is
% stratified.
% \kitem{DAMEE\_4} DAMEE stands for Data Assimilation and Model
% Evaluation Experiment and is a comparison of different models of
% the North Atlantic. Version 4 is a big domain
% extending from 30$^\circ$ S to 65$^\circ$ N. Additional input files
% are required to run the DAMEE configurations.
\kitem{GRAV\_ADJ} The gravitational adjustment problem takes place
in a long narrow domain which is initialized with dense water at one
end and light water at the other. At time zero, the water is released
and it generates two propagating fronts as the light water rushes to
fill the top and the dense water rushes to fill the bottom. This
configuration can be used to test various advection schemes.
\kitem{OVERFLOW} This configuration is similar to the
GRAV\_ADJ problem, but is initialized with dense water in the shallow
part of a domain with a sloping bottom.
\kitem{SEAMOUNT} The seamount test has been used to test the pressure
gradient errors. It has an idealized seamount in a periodic channel.
See \citet{BH93} and \citet{McCalpin94} for more information.
\kitem{UPWELLING} The upwelling/downwelling example was
contributed by \citet{Macks93}
and consists of a periodic channel with shelves on each side.
There is along-channel wind forcing and the Coriolis term leads
to upwelling on one side and downwelling on the other side. If
you run it for several days without vertical mixing, you end up with
dense water over light water.
\end{klist}
Some NetCDF input files for the ROMS examples can be found under
\code{Data/ROMS} in the ROMS distribution while many others can be
downloaded as part of the \href{http://www.myroms.org/svn/src/test}{ROMS
test package}. The ASCII input files are under \code{ROMS/External}.
\subsection{Configuring ROMS}
\label{User}
The four main sections you need to change in ROMS are the \code{makefile}
or \code{build.bash}, an include file with \code{cpp} options, any
analytic functions, and the ASCII input file. If more realistic fields
are desired, you will have to provide other NetCDF input files as well, for
instance for the grid and the wind forcing.
\subsubsection{Case Name}
First, you need to decide on a name for your particular application or
configuration. This name is provided via the \code{ROMS\_APPLICATION} in
either the makefile or the build script. This name should be reasonably
short, all uppercase, with spaces converted to underscores. For example,
let's say we pick the name \code{WIKI\_TEST}. This name gets defined
during the build, so you can add code protected by \code{\#ifdef
WIKI\_TEST} as needed. This would be a good time to either copy the
makefile or the build Script to create one specific to this case prior
to editing it.
\subsubsection{ Case-specific Include File}
Each application has its own include file, included by
\code{cppdefs.h}. The name of this file is the name of your
application (\code{WIKI\_TEST} here) turned into lower case, with '.h'
appended (\code{wiki\_test.h}). The location of this file is set by
\code{MY\_HEADER\_DIR}, pointing to \code{User/Include} or some other
location of your choosing.
The complete list of options to be set prior to compilation are listed in
\S\ref{Cpp1}. Place those you need in the \code{wiki\_test.h} file. These
include algorithm choices (e.g. advection and turbulence closure schemes),
output options (averages, diagnostics, stations, floats), and
application modules (biology, sediments). Each line should be of the
form:
\begin{verbatim}
#define SOME_VAR
\end{verbatim}
Note that any undefined variable need not be mentioned.
Also note that if you copy a predefined application from
\code{ROMS/Include} as a template for your application, you must
rename it. If you don't change the name, ROMS will use the one in
\code{ROMS/Include} and your file will be ignored during the build
procedure.
\subsubsection{Functionals}
Some of the cpp options have names beginning with \code{ANA\_}. For each one of
these, you will be expected to provide an analytic expression for the field
in question in the corresponding include file. These files
are listed in \S\ref{Functionals} and their location is determined
by \code{MY\_ANALYTICAL\_DIR}. You may chose to copy those from
\code{User/Functionals} to some new directory and place your version of
the assignments within
\begin{verbatim}
#ifdef WIKI_TEST
! Set weird and wonderful winds
:
#endif
\end{verbatim}
This makes
it easy to search for later, if nothing else.
\subsubsection{\code{checkdefs.F}}
If you add new \code{cpp} variables to the code (other than your
application name), it is recommended that you also add the appropriate
code to \code{checkdefs.F}, such as:
\begin{verbatim}
#ifdef SLEET
IF (Master) WRITE(stdout,20) 'SLEET', &
& 'Sleet falling on the ice option.'
is=lenstr(Coptions)+1
Coptions(is:is+7)=' SLEET,'
#endif /* SLEET */
\end{verbatim}
Note that the number ``7'' on the \code{Coptions} line must be set
according to the length of the string you are adding. In this case 7
is for `` SLEET,'', including the comma and the space. You do not
need to do this for your application name (\code{WIKI\_TEST} here),
since \code{checkdefs} will print whatever is in \code{MyAppCPP}.
\subsubsection{Model domain}
\label{Muddy}
It is assumed in this manual that \code{Ngrids} will be set to 1.
Having multiple grids talk to each other is brand new in ROMS 3.7,
with documentation appearing on the ROMS wiki.
One of the first things the user must decide is how many grid points
to use, and can be afforded. There are three parameters in
\code{ocean.in} which specify the grid size and one parameter for the
number of active tracers:
\begin{tabbing}
Gnu \= Allolo \= \kill
\> \code{Lm} \> Number of finite-difference points in $\xi$. \\
\> \code{Mm} \> Number of finite-difference points in $\eta$. \\
\> \code{N} \> Number of finite-difference points in the vertical. \\
\> \code{NAT} \> Number of active tracers. \\
\end{tabbing}
The number of biological tracers is set in the \code{biology.in} file.
There are no constraints on these except $\code{Lm} \geq 2$, $\code{Mm}
\geq 2$, $\code{N} \geq 1$ and $\code{NAT} \geq 1$. \code{Lm} and
\code{Mm} should be at least 3 if the domain is periodic in that
direction. If $\code{N} == 1$, don't define SOLVE\_3D.
\subsubsection{$x,y$ grid}
The subroutine \code{get\_grid} or \code{ana\_grid} is called by
\code{initial} to set the grid arrays, the bathymetry, and the
Coriolis parameter. Most of the simple test problems have their grid
information specified in \code{ana\_grid.h} in the directory
\code{ROMS/Functionals}. More realistic problems require a NetCDF grid
file, produced by the grid generation programs described in
\citet{GRIDS}, by the Matlab \code{SeaGrid}, or by some
other method. The variables which are read by \code{get\_grid} are:
\begin{tabbing}
Gnu \= \kill
\> \code{xl, el, spherical, f, h, pm, pn, x\_rho, y\_rho,
lon\_rho, lat\_rho, angle}.
\end{tabbing}
If the grid is curved, \code{get\_grid} will also read:
\begin{tabbing}
Gnu \= \kill
\> \code{dndx, dmde}.
\end{tabbing}
Likewise, if \code{MASKING} is defined, it will read:
\begin{tabbing}
Gnu \= \kill
\> \code{mask\_rho, mask\_u, mask\_v, mask\_psi}.
\end{tabbing}
\subsubsection {$\xi,\eta$ grid}
Before providing initial conditions and boundary conditions, the
user must understand the model grid. The fields are laid out on an
Arakawa C grid as in Fig.\ \ref{fcgr}. The overall grid is shown in
Fig.\ \ref{fwgr}. The thick outer line shows the position of the
model boundary. The points inside this boundary are those which are
advanced in time using the model physics. The points on the boundary
and those on the outside must be supplied by the boundary
conditions.
The three-dimensional model fields are carried in four-dimensional
arrays, where the fourth array index refers to one of two or three
time levels. The tracers have a fifth array index telling which
tracer is being referred to.
For instance, $\code{itemp}=1$ refers to
potential temperature while $\code{isalt}=2$ refers to salinity. The
integers $i$, $j$, and $k$ are used throughout the model to index
the three spatial dimensions:
\begin{tabbing}
Gnus \= Gnus \= \kill
\>$i$ \>Index variable for the $\xi$-direction. \\
\>$j$ \>Index variable for the $\eta$-direction. \\
\>$k$ \>Index variable for the $\sigma$-direction. $k = 1$
refers to the bottom \\
biggnu \= \kill
\>while $k = \code{N}$ refers to the surface.
\end{tabbing}
In terms of grid extent, the model is expecting values for rho-point indices
from $i = 0$ through $i = $Lm$ + 1$, even though the computational
domain extends from $i = 1$ through $i = $Lm.
\subsubsection{Initial conditions}
The initial values for the model fields are provided by either
\code{ana\_initial} or \code{get\_state}. \code{get\_state} is
also used to read a restart file if the model is being restarted from a
previous run.
Also in \code{initial}, \code{rho\_eos} is called to initialize
the density field. \code{rho\_eos} also computes \code{rhoA},
the vertically averaged density, and \code{rhoS}, the density
perturbation. Both \code{rhoA} and \code{rhoS} are used in the barotropic
pressure gradient.
%The tracer climatology fields also require appropriate values if they
%are to be used, and are provided by \code{ana\_tclima} or
%\code{get\_tclima}. Likewise, the surface height climatology is read by
%\code{get\_ssh} or provided by \code{ana\_ssh}.
\subsubsection{Equation of state}
The equation of state is defined in the subroutine \code{rho\_eos}. Two
versions are provided in ROMS: a nonlinear $\rho =
\rho(T,S,z)$ from \citet{Jackett} and a linear
$\rho(T,S)$. The linear form is
$$
\rho = \code{R0} - \code{Tcoef} \cdot (T-T0) +
\code{Scoef} \cdot (S-S0)
$$
or
$$
\rho = \code{R0} + \code{Tcoef} \cdot (T-T0),
$$
depending on whether or not
\code{SALINITY} is defined. Specify which equation of state you
would like to use with the \code{NONLIN\_EOS} C preprocessor flag in your
application include file. The linear coefficients \code{R0}, \code{T0},
\code{Tcoef}, \code{S0}, and \code{Scoef} are set in \code{ocean.in}. Note
that we are computing {\em in situ} density from potential temperature and
salinity. Some of the vertical mixing schemes require potential density
and some other fields, which are computed by \code{rho\_eos} as well.
\subsubsection{Boundary conditions}
\label{Bcs}
The horizontal boundary conditions are provided by the subroutines
in \code{u3dbc\_im}, \code{v3dbc\_im}, \code{u2dbc\_im}, \code{v2dbc\_im},
\code{t3dbc\_im}, and \code{zetabc}. They are called every time-step
and provide the boundary values for the fields $u, v, \overline{u},
\overline{v}$, all tracers, and $\zeta$, respectively. They are currently
configured for a closed basin, a periodic channel, a doubly periodic
domain or a domain with various open boundary conditions. Each side is
controlled independently with ``West'' being the \code{i=1} boundary,
``East'' being the \code{i=L} boundary, ``South'' being the \code{j=1}
boundary, and ``North'' being the \code{j=M} boundary. These choices are
set in \code{ocean.in} via the \code{LBC} array.
Many of the choices for open boundaries require that the model have
some boundary values for the field in question. These can be specified in
the appropriate \code{ana\_xxx.h} file for say \code{ANA\_TOBC} or
they can be read from a boundary NetCDF file. There is logic in
\code{globaldefs.h} by which ROMS decides whether or not it needs to
read a boundary file.
\subsubsection{Model forcing}
\label{Mforce}
\noindent {\bf(a) Winds and thermal fluxes}
There are two different ways to apply a wind forcing: as a surface
momentum flux in the vertical viscosity term, or as a body force over
the upper water column.
Usually, we set the vertical $\sigma$-coordinate
parameters to retain some resolution near the surface and apply the
fluxes as boundary conditions to the vertical viscosity/diffusivity.
In either case, the surface and bottom fluxes are either defined
analytically, read from a forcing file, or computed inside ROMS
using a bulk flux formula from the appropriate atmospheric fields
(air temperature and winds, for instance). You must either edit the
appropriate \code{ana\_xxx.h} or create a NetCDF forcing
file in the format expected by ROMS. Note that it is quite common
to put the surface variables in the forcing file while having an analytic
bottom heat flux. ROMS now has the capability of reading in a list
of forcing fields---it can be convenient to have one file per field
rather than stuffing tides, winds, river inputs all into one file.
In the past, our vertical resolution was relatively coarse and the
vertical viscosity would have to have been unreasonably large for
us to resolve the surface Ekman layer. If that is your situation,
define \code{BODYFORCE} in \code{cppdefs.h} and provide a value for
\code{levsfrc} in \code{ocean.in}. The forcing is applied over the
levels from \code{levsfrc} to \code{N}. The above caution about
vertical resolution also applies to the surface fluxes of $T$ and
$S$, although \code{BODYFORCE} only refers to wind stress, not the
surface tracer fluxes.
\smallskip
\noindent {\bf(b) Climatology}
One way to force the model is via a nudging to the tracer and/or
momentum climatologies. Nudging to values from a global model
near the boundaries can be useful when the boundary conditions alone
are not entirely well-behaved.
Set the climatologies in \code{ana\_tclima.h} or in a
file read by \code{get\_data}, set \code{LtracerCLM} in
\code{ocean\_wiki\_test.in} and also set the array \code{Tnudgcof} in
either \code{ana\_nudgcoef.h} or in a file (with name in \code{NUDNAME}
variable in the ocean.in).
\smallskip
\noindent {\bf(c) Tides}
There is also more than one way to force with tides. One way is to
provide boundary conditions with enough temporal resolution to
resolve the tides. Another is to provide ROMS with the tidal
constituents at all grid points and to have ROMS reconstruct the
tidal currents (\code{UV\_TIDES}) and/or elevations (\code{SSH\_TIDES})
for any given time. An example of such a tidal forcing file is in
\code{Data/ROMS/Forcing/test\_head\_frc.nc}.
The non-trunk code with ice, etc. includes the \code{TIDES\_ASTRO} option to
add on the long-period tides from
\citet{Foreman_96a} and \citet{Foreman_96b}.
There is also an option to include the tidal potential
forcing term (\code{POT\_TIDES}), requiring the tidal potential to
be included in the tides forcing file.
\smallskip
\noindent {\bf(d) Rivers}
Point sources can be used to provide river inflow to the model.
These have their own input file (\code{SSFNAME}) if not provided via
\code{ana\_psource}.
\subsubsection{\code{ocean.in}}
\label{ASCII_in}
ROMS expects to read a number of variables from an ASCII file as described
in \S\ref{Running}.
Example input files are in \code{ROMS/External} with names like
\code{ocean\_grav\_adj.in}, where ``grav\_adj'' refers to the name of
the application. Lines beginning with ``!'' are comments and will be
ignored by ROMS on reading them.
The input is organized as key/value pairs, separated by one or two
equals signs. It is possible for ROMS to run on more than one grid
simultaneously, with the number of grids being read from the input
file. If there is one equals sign (\code{=}), ROMS will use the
corresponding value for all grids. If there are two (\code{==}), ROMS
will read a value for each grid. Thus far, most domains have used just
one grid, though I did run a two-grid Palau domain---check in
\code{Apps/Palau} for a two-grid ocean.in
file (which I generated using a Python script).
ROMS will ignore the parameters not needed by the current simulation,
e.g., the GLS parameters will not be read if you are not using that
mixing scheme. Most of the example files contain all possible
parameters, with \code{User/External/ocean.in} being for sure updated
with each addition. The parameters are described in comments at the
bottom of the \code{ocean.in} files. Skipping those having to do
with data assimilation, the input parameters are as follows:
\begin{klist}
\kitem{Header} \mbox{}
\begin{klist}
\kitem{TITLE} A text string to put in the output files.
\kitem{MyAppCPP} The shorthand name for this application.
\kitem{VARNAME} The location of the \code{varinfo.dat} file
containing information about fields to read/write from/to NetCDF
files.
\kitem{Ngrids} The number of grids to compute on.
\kitem{NestLayers} The number of levels of nested grids.
\kitem{GridsInLayer} The number of grids in each nesting level.
\end{klist}
\kitem{Grid-dimension parameters} \mbox{}
\begin{klist}
\kitem{Lm} Number of $i$-direction INTERIOR RHO-points.
\kitem{Mm} Number of $j$-direction INTERIOR RHO-points.
\kitem{N} Number of vertical levels.
\kitem{Nbed} Number of sediment bed layers.
\kitem{NAT} Number of active tracers (usually 2).
\kitem{NPT} Number of passive tracers.
\kitem{NCS} Number of cohesive (mud) sediment tracers.
\kitem{NNS} Number of non-cohesive (sand) sediment tracers.
\end{klist}
\kitem{Domain-decomposition parameters} \mbox{}
\begin{klist}
\kitem{NtileI} Number of $i$-direction partitions.
\kitem{NtileJ} Number of $j$-direction partitions.
\end{klist}
\kitem{Boundary conditions} \mbox{}
\begin{klist}
\kitem{LBC} A line is given for each field, each line
containing four values, one for each side in the order
``West'', ``South'', ``East'', ``North''. Each value is a
string, with the possible values being:
\begin{klist}
\kitem{Cha} Chapman implicit.
\kitem{Che} Chapman explicit.
\kitem{Cla} Clamped.
\kitem{Clo} Closed.
\kitem{Fla} Flather.
\kitem{Gra} Gradient.
\kitem{Mix} Ice only---mixed clamped and radiation.
\kitem{Nes} Nested.
\kitem{Per} Periodic---should match the opposing
boundary.
\kitem{Rad} Radiation.
\kitem{RadNud}Radiation and nudging.
\kitem{Red} Reduced Physics---note that this also
requires the \code{FSOBC\_REDUCED} cpp flag.
\kitem{Shc} Schepetkin.
\end{klist}
\kitem{VolCons} Four values for the volume conservation, one
for each edge.
\end{klist}
\kitem{Time-stepping parameters} \mbox{}
\begin{klist}
\kitem{NTIMES} Number of time-steps to evolve the 3-D
equations in the current run. This is actually the total
number, including any previous segments of the same run. For
instance, if you already did a three-month run and wish to
continue for another three months, set \code{NTIMES} to the
number of steps needed for six months.
\kitem{DT} Time-step in seconds for the 3-D equations.
\kitem{NDTFAST} Number of time-steps for the 2-D equations
to be executed each \code{dt}. This is the number shown as $M$
in Figure \ref{ftspl}---the model will compute $M^\ast$ at run
time.
\end{klist}
% \kitem{Model iteration loops parameters} \mbox{}
% \begin{klist}
% \kitem{ERstr} Starting ensemble run number.
% \kitem{ERend} Ending ensemble run number.
% \kitem{Nouter} Maximum number of 4DVAR outer loop iterations.
% \kitem{Ninner} Maximum number of 4DVAR inner loop iterations.
% \kitem{Nintervals} Number of time interval divisions for
% stochastic optimals computations.
% \end{klist}
% \kitem{Generalized Stability Theory (GST) parameters} \mbox{}
% \begin{klist}
% \kitem{NEV} Number of eigenvalues.
% \kitem{NCV} Number of eigenvectors.
% \end{klist}
\kitem{Input/Output parameters} \mbox{}
ROMS has several possible output files. The output files can
include a restart file, a history file, an averages file, and a
station file, for instance. The restart file often contains
only two records with the older record being overwritten during
the next write. The history file can contain a subset of the
restart fields, for instance just the surface elevation and the
surface temperature. The averages file contains time-averages
of the model fields, for instance daily or monthly means,
depending on \code{NAVG}. The station file contains timeseries
for specified points, possibly quite frequently since each record
is small. For some, machinery is in place to write multiple
files, numbering them \_0001, \_0002, etc.
\begin{klist}
\kitem{NRREC} Record number of the restart file to read
as the initial conditions. Set to 0 at the beginning of the
run, -1 to read the latest record.
\kitem{LcycleRST} Logical, true to cycle between two records
of the restart file.
\kitem{NRST} Number of time-steps between writing of
restart fields.
\kitem{NSTA} Number of time-steps between writing fields
into the stations file.
\kitem{NFLT} Number of time-steps between writing fields
into the floats file.
\kitem{NINFO} Number of time-steps between calling
\code{diag} to write some global information and to check for
NaN values.
\end{klist}
\kitem{History, average, diagnostic output parameters} \mbox{}
\begin{klist}
\kitem{LDEFOUT} True for creating new output files for
stations, history, floats, etc. If false, output is appended
to these files.
\kitem{NHIS} Number of time-steps between writing history
records.
\kitem{NDEFHIS} Number of time-steps between starting new history
files.
\kitem{NQCK} Number of time-steps between writing secondary
history records.
\kitem{NDEFQCK} Number of time-steps between starting new
secondary history files.
\kitem{NTSAVG} Starting time-step for the accumulation of
output time-averaged data. For instance, you might want to average
over the last day of a thirty-day run.
\kitem{NAVG} Number of time-steps between writing
time-averaged data into the averages file.
\kitem{NDEFAVG} Number of time-steps between starting
new averages files.
\kitem{NTSAVG2} Starting time-step for the accumulation of
output secondary time-averaged data. For instance, you might
want to average over the last day of a thirty-day run.
\kitem{NAVG2} Number of time-steps between writing
time-averaged data into the secondary averages file.
\kitem{NDEFAVG2} Number of time-steps between starting
new secondary averages files.
\kitem{NTSDIA} Starting time-step for the accumulation of
output diagnostics data. For instance, you might want to write
diagnostics for the last day of a thirty-day run.
\kitem{NDIA} Number of time-steps between writing
diagnostics data into the diagnostics file.
\kitem{NDEFDIA} Number of time-steps between starting
new diagnostics files.
\end{klist}
% \kitem{Tangent linear and adjoint output parameters} \mbox{}
% \begin{klist}
% \kitem{LcycleTLM} Logical, true to cycle between two records
% \kitem{NTLM} Number of time-steps between writing
% tangent linear data.
% \kitem{NDEFTLM} Number of time-steps between starting
% new tangent linear files.
% \kitem{LcycleADJ} Logical, true to cycle between two records
% of the restart file.
% \kitem{NADJ} Number of time-steps between writing
% adjoint data.
% \kitem{NDEFADJ} Number of time-steps between starting
% new adjoint files.
% \kitem{NSFF} Number of time-steps between 4DVAR adjustment of
% surface forcing fluxes.
% \kitem{NOBC} Number of time-steps between 4DVAR adjustment of
% open boundary fields.
% \end{klist}
% \kitem{Check-pointing GST restart parameters} \mbox{}
% \begin{klist}
% \kitem{LrstGST} GST restart switch.
% \kitem{MaxIterGST} Maximum number of iterations.
% \kitem{NGST} Check-pointing interval.
% \end{klist}
% \kitem{Ritz GST parameter} \mbox{}
% \begin{klist}
% \kitem{Ritz\_tol} Relative accuracy of the Ritz values
% computed in the GST analysis.
% \end{klist}
\kitem{Horizontal mixing of tracers} \mbox{}
\begin{klist}
\kitem{TNU2} Constant mixing
coefficient for the horizontal Laplacian diffusion of each tracer.
A value is expected for each of the \code{NAT+NPT} tracers.
\kitem{TNU4} Constant mixing
coefficient for the horizontal biharmonic diffusion of each tracer.
A value is expected for each of the \code{NAT+NPT} tracers.
\end{klist}
\kitem{Horizontal viscosity coefficients} \mbox{}
\begin{klist}
\kitem{VISC2} Constant mixing coefficient for the horizontal
Laplacian viscosity.
\kitem{VISC4} Constant mixing coefficient for the horizontal
biharmonic viscosity.
\end{klist}
\kitem{Horizontal sponge} \mbox{}
\begin{klist}
\kitem{LuvSponge} Logical for applying a sponge (increased
horizontal viscosity) to momentum fields.
\kitem{LtracerSponge} Logical for applying a sponge
(increased horizontal diffusivity) to tracer fields.
\end{klist}
\kitem{Vertical mixing coefficients for tracers} \mbox{}
\begin{klist}
\kitem{AKT\_BAK} Background vertical mixing coefficient
for the tracers (\code{NAT+NPT} values).
\end{klist}
\kitem{Vertical mixing coefficient for momentum} \mbox{}
\begin{klist}
\kitem{AKV\_BAK} Background vertical mixing coefficient
for momentum.
\end{klist}
\kitem{Turbulent closure parameters} \mbox{}
\begin{klist}
\kitem{AKK\_BAK} Background vertical mixing coefficient
for turbulent kinetic energy.
\kitem{AKP\_BAK} Background vertical mixing coefficient
for turbulent generic statistical field.
\kitem{TKENU2} Constant mixing coefficient for the horizontal
Laplacian diffusion of turbulent kinetic energy.
\kitem{TKENU4} Constant mixing coefficient for the horizontal
biharmonic diffusion of turbulent kinetic energy.
\end{klist}
\kitem{Generic length-scale turbulence closure parameters}
\mbox{}
\begin{klist}
\kitem{GLS\_P} Stability exponent.
\kitem{GLS\_M} Turbulent kinetic energy exponent.
\kitem{GLS\_N} Turbulent length scale exponent.
\kitem{GLS\_Kmin} Minimum value of specific turbulent kinetic
energy.
\kitem{GLS\_Pmin} Minimum value of dissipation.
\kitem{GLS\_CMU0} Stability coefficient.
\kitem{GLS\_C1} Shear production coefficient.
\kitem{GLS\_C2} Dissipation coefficient.
\kitem{GLS\_C3M} Buoyancy production coefficient (minus).
\kitem{GLS\_C3P} Buoyancy production coefficient (plus).
\kitem{GLS\_SIGK} Constant Schmidt number (non-dimensional) for
turbulent kinetic energy diffusivity.
\kitem{GLS\_SIGP} Constant Schmidt number (non-dimensional) for
turbulent generic statistical field, ``psi''.
\end{klist}
\kitem{Constants used in surface TKE flux computation} \mbox{}
\begin{klist}
\kitem{CHARNOK\_ALPHA} Charnok surface roughness.
\kitem{ZOS\_HSIG\_ALPHA} Roughness from wave amplitude.
\kitem{SZ\_ALPHA} Roughness from wave dissipation.
\kitem{CRGBAN\_CW} Craig and Banner wave breaking.
\end{klist}
\kitem{Bottom drag coefficients} \mbox{}
\begin{klist}
\kitem{RDRG} Linear bottom drag coefficient.
\kitem{RDRG2} Quadratic bottom drag coefficient.
\kitem{Zob} Bottom roughness.
\kitem{Zos} Surface roughness (under ice shelves).
\end{klist}
\kitem{Height of atmospheric measurements for bulk flux
parameterizations} \mbox{}
\begin{klist}
\kitem{BLK\_ZQ} Height of air humidity values.
\kitem{BLK\_ZT} Height of air temperature values.
\kitem{BLK\_ZW} Height of wind values.
\end{klist}
\kitem{Wetting and drying parameter} \mbox{}
\begin{klist}
\kitem{DCRIT} Minimum depth for dry cells.
\end{klist}
\kitem{Various parameters} \mbox{}
\begin{klist}
\kitem{WTYPE} Jerlov water type.
\kitem{LEVSFRC} Deepest level to apply surface momentum
stresses as a body force.
Used when the C-preprocessor option BODYFORCE is defined.
\kitem{LEVBFRC} Shallowest level to apply bottom momentum
stresses as a body force.
Used when the C-preprocessor option BODYFORCE is defined.
\end{klist}
\kitem{Vertical coordinate parameters} \mbox{}
\begin{klist}
\kitem{Vtransform} Transformation equation, 1 for old style,
2 now recommended.
\kitem{Vstretching} Stretching function, 1 for old style, 4
now recommended.
\end{klist}
\kitem{Vertical $\sigma$-coordinates parameters} \mbox{}
\begin{klist}
\kitem{THETA\_S} $\sigma$-coordinate surface control parameter,
[$0 < \code{theta\_s} < 20$ for old style].
\kitem{THETA\_B} $\sigma$-coordinate bottom control parameter,
[$0 < \code{theta\_b} < 1$ for old style].
\kitem{TCLINE} Width of the surface or bottom boundary layer
in which higher vertical resolution is required during stretching.
\end{klist}
\kitem{Mean Density and Brunt-V\"ais\"al\"a frequency} \mbox{}
\begin{klist}
\kitem{RHO0} Mean density used in the Boussinesq
approximation.
\kitem{BVF\_BAK} Background Brunt-V\"ais\"al\"a frequency squared.
\end{klist}
\kitem{Time parameters} \mbox{}
\begin{klist}
\kitem{DSTART} Time stamp assigned to model initialization
(days).
\kitem{TIDE\_START} Time of tidal origin relative to model
origin.
\kitem{TIME\_REF} Reference time in the format yyyymmdd.dd or
else a special value for specific calendars as documented in the
\code{ocean.in} files.
\end{klist}
\kitem{Nudging time scales} \mbox{}
\begin{klist}
\kitem{TNUDG} Time scale (days) of nudging towards
tracer climatology at the interior and at the boundaries.
A value is expected for each active tracer.
\kitem{ZNUDG} Time scale (days) of nudging towards
free surface climatology at the interior and at the boundaries.
\kitem{M2NUDG} Time scale (days) of nudging towards
2-D momentum climatology at the interior and at the boundaries.
\kitem{M3NUDG} Time scale (days) of nudging towards
3-D momentum climatology at the interior and at the boundaries.
\kitem{TNUDG\_SSS} Time scale (days) of nudging towards
surface salinity climatology.
\kitem{SSS\_MISMATCH\_THRESHOLD} Parameter when both
\code{SCORRECTION} and \code{SSSC\_THRESHOLD} are used.
\end{klist}
\kitem{Open boundary factor} \mbox{}
\begin{klist}
\kitem{OBCFAC} Ratio of inflow and outflow nudging time scales.
\end{klist}
\kitem{Linear equation of state parameters} \mbox{}
\begin{klist}
\kitem{R0} Background density value used in
the linear equation of state.
\kitem{T0} Background potential temperature constant.
\kitem{S0} Background salinity constant.
\kitem{TCOEF} Thermal expansion coefficient in the linear
equation of state.
\kitem{SCOEF} Saline contraction coefficient in the linear
equation of state.
\end{klist}
\kitem{Slipperiness parameter} \mbox{}
\begin{klist}
\kitem{GAMMA2} Slipperiness variable, either 1.0 (free
slip) or $-1.0$ (no slip).
\end{klist}
\kitem{Point sources} \mbox{}
\begin{klist}
\kitem{LuvSrc} Logical for lateral flux point sources.
\kitem{LwSrc} Logical for vertical flux point sources.
\kitem{LtracerSrc} Logical, one value per tracer,
whether or not point sources have tracer values.
\end{klist}
\kitem{Climatology nudging} \mbox{}
\begin{klist}
\kitem{LsshCLM} Logical for SSH climatology.
\kitem{Lm2CLM} Logical for 2D momentum climatologies.
\kitem{Lm3CLM} Logical for 3D momentum climatologies.
\kitem{LtracerCLM} Logical, one value per tracer,
whether or not to have tracer climatologies.
\kitem{LnudgeM2CLM} Logical for nudging to 2D momentum climatologies.
\kitem{LnudgeM3CLM} Logical for nudging to 3D momentum climatologies.
\kitem{LnudgeTCLM} Logical, one value per tracer,
whether or not to nudge to tracer climatologies.
\end{klist}
% \kitem{Adjoint sensitivity time parameters} \mbox{}
% \begin{klist}
% \kitem{DstrS} Starting day.
% \kitem{DendS} Ending day.
% \end{klist}
% \kitem{Adjoint sensitivity vertical level parameters} \mbox{}
% \begin{klist}
% \kitem{KstrS} Starting level.
% \kitem{KendS} Ending level.
% \end{klist}
% \kitem{Adjoint sensitivity logical parameters} \mbox{}
% \begin{klist}
% \kitem{Lstate(isFsur)} Free surface.
% \kitem{Lstate(isUbar)} 2D $u$-momentum.
% \kitem{Lstate(isVbar)} 2D $v$-momentum.
% \kitem{Lstate(isUvel)} 3D $u$-momentum.
% \kitem{Lstate(isVvel)} 3D $v$-momentum.
% \kitem{Lstate(isTvar)} Tracers (NT values expected).
% \end{klist}
% \kitem{Stochastic optimals time scale} \mbox{}
% \begin{klist}
% \kitem{SO\_decay} Stochastic optimals time decorrelation
% scale (days) assumed for red noise processes.
% \end{klist}
% \kitem{Logicals for stochastic optimals} \mbox{}
% \begin{klist}
% \kitem{SOstate(isUstr)} Surface $u$-stress.
% \kitem{SOstate(isVstr)} Surface $v$-stress.
% \kitem{Lstate(isTsur)} Surface tracer flux (NT values expected).
% \end{klist}
% \kitem{Stochastic optimals surface standard deviations} \mbox{}
% \begin{klist}
% \kitem{SO\_sdev(isUstr)} Surface $u$-stress.
% \kitem{SO\_sdev(isVstr)} Surface $v$-stress.
% \kitem{SO\_sdev(isTsur)} Surface tracer flux (NT values
% expected).
% \end{klist}
\kitem{Logical switches to activate the writing of
history/averages fields}
Values for all of these for the ice model are now set in \code{ice.in}.
\begin{klist}
\kitem{Hout} History output switches, one line per variable.
Check the \code{ocean.in} file for the names of the fields involved.
\kitem{Qout} Secondary history output switches, one line
per variable.
Check the \code{ocean.in} file for the names of the fields involved.
\kitem{Aout} Averages output switches, one line per variable.
Check the \code{ocean.in} file for the names of the fields involved.
\kitem{Aout2} Averages2 output switches, one line per variable.
Check the \code{ocean.in} file for the names of the fields involved.
\kitem{Dout} Diagnostics output switches, one line per term.
Check the \code{ocean.in} file for the names of the fields involved.
\end{klist}
\kitem{User parameters} \mbox{}
\begin{klist}
\kitem{NUSER} Number of user parameters
\kitem{USER} Values of user parameters (NUSER values).
\end{klist}
\kitem{NetCDF-4/HDF5 parameters} \mbox{}
\begin{klist}
\kitem{NC\_SHUFFLE} If non-zero, turn on shuffle filter.
\kitem{NC\_DEFLATE} If non-zero, turn on deflate filter.
\kitem{NC\_DLEVEL} Deflate level (0--9).
\end{klist}
\kitem{Input NetCDF file names} \mbox{}
\begin{klist}
\kitem{GRDNAME} Grid file.
\kitem{ININAME} Initial conditions file.
\kitem{ITLNAME} Initial tangent linear file.
\kitem{IRPNAME} Initial representer file.
\kitem{IADNAME} Initial adjoint file.
\kitem{FWDNAME} Forward model file.
\kitem{ADSNAME} Adjoint sensitivity functional file.
\kitem{NGCNAME} Nesting connectivity file.
\kitem{NUDNAME} Nudging coefficients file.
\kitem{SSFNAME} Sources/sinks forcing file.
\end{klist}
\kitem{Boundary, Climatology and Forcing NetCDF files} These can
each have an array of files, with one set of files per variable,
each file in a set for a different range of times. See \code{ocean.in}
for syntax. Note that the trunk code only does this for forcing
files, while if you use the code described here, you {\em must}
specify the number of files of the appropriate type before providing
the filenames. For instance, not setting \code{NBCFILES} before setting
\code{BRYNAME} will lead to a segmentation fault.
\begin{klist}
\kitem{NCLMFILES} Number of climatology files.
\kitem{CLMNAME} Climatology file.
\kitem{NBCFILES} Number of boundary files.
\kitem{BRYNAME} Boundary condition file.
\kitem{NFFILES} Number of forcing files.
\kitem{FRCNAME} Forcing files.
\end{klist}
\kitem{Output NetCDF file names} \mbox{}
\begin{klist}
\kitem{DAINAME} Data assimilation next cycle initial conditions
file.
\kitem{GSTNAME} GST analysis restart file.
\kitem{RSTNAME} Restart file.
\kitem{HISNAME} History file.
\kitem{QCKNAME} Secondary history file.
\kitem{TLMNAME} Tangent linear file.
\kitem{TLFNAME} Impulse forcing file (for tangent linear model).
\kitem{ADJNAME} Adjoint file.
\kitem{AVGNAME} Averages file.
\kitem{AVG2NAME} Secondary averages file.
\kitem{DIANAME} Diagnostics file.
\kitem{STANAME} Stations file.
\kitem{FLTNAME} Lagrangian floats file.
\end{klist}
\kitem{ASCII input file names} \mbox{}
\begin{klist}
\kitem{APARNAM} Assimilation parameters.
\kitem{SPOSNAM} Stations positions.
\kitem{FPOSNAM} Initial drifter positions.
\kitem{IPARNAM} Ice parameters.
\kitem{BPARNAM} Biology parameters.
\kitem{SPARNAM} Sediment parameters.
\kitem{USRNAME} User's generic input.
\end{klist}
\end{klist}
The bottom of the sample files contain comments describing some of these in
greater detail, including the data assimilation parameters.
\subsubsection{User variables and subroutines}
\label{Store}
It is possible for the user to add new variables and functionality,
though it is discouraged. The design goal is to isolate the most common
features a user would change to the \code{cpp} switches
(\S\ref{Cpp1}), the \code{ana\_xx.h} files (\S\ref{Functionals}) and
the ASCII input file (\S\ref{ASCII_in}). A query on the ROMS forum
might be in order if you have something specific in mind.
If you do choose to add bits, know that the \code{makefile}
fragments called \code{Module.mk} will attempt to compile and
link into a library anything
with a \code{.F} extension in the directories already generating a
library from such files.
\subsection{Upwelling/Downwelling Example}
\label{UpDown}
The application which ROMS is configured to run as distributed
is a wind-driven
upwelling and downwelling example, described in
\citet{Macks93}. There is a shelf on each wall of a periodic channel
and an along-channel wind forcing, which drives upwelling at one wall
and downwelling at the other. This problem depends on the Ekman layer,
therefore a surface stress is used with vertical viscosity. The Ekman
depth is estimated to be 9 $m$ if $A_v = 0.01 m^2 / s$, so the vertical
grid spacing must resolve this. The maximum depth is 150 $m$ and our
choice of the vertical grid parameters leads to a surface $\Delta z$
of 1.6 $m$. A possible update to this example would be to increase
\code{N} and decrease \code{Lm}, the latter because the solution
does not vary in the along-channel direction.
\subsubsection{\code{cppdefs.h}}
The C preprocessor variable \code{UPWELLING} is used for the
upwelling configuration of the model. The \code{makefile} will
direct \code{cppdefs.h} to include the file \code{upwelling.h}:
\begin{verbatim}
#define UV_ADV
#define UV_COR
#define UV_LDRAG
#define UV_VIS2
#undef MIX_GEO_UV
#define MIX_S_UV
#define SPLINES_VDIFF
#define SPLINES_VVISC
#define TS_U3HADVECTION
#define TS_C4VADVECTION
#undef TS_MPDATA
#define DJ_GRADPS
#define TS_DIF2
#undef TS_DIF4
#undef MIX_GEO_TS
#define MIX_S_TS
#define SALINITY
#define SOLVE3D
#define AVERAGES
#define DIAGNOSTICS_TS
#define DIAGNOSTICS_UV
#define ANA_GRID
#define ANA_INITIAL
#define ANA_SMFLUX
#define ANA_STFLUX
#define ANA_SSFLUX
#define ANA_BTFLUX
#define ANA_BSFLUX
#if defined GLS_MIXING || defined MY25_MIXING
# define KANTHA_CLAYSON
# define N2S2_HORAVG
# define RI_SPLINES
#else
# define ANA_VMIX
#endif
#if defined BIO_FENNEL || defined ECOSIM || \
defined NPZD_POWELL || defined NEMURO || \
defined BIO_UMAINE
# define ANA_BIOLOGY
# define ANA_SPFLUX
# define ANA_BPFLUX
# define ANA_SRFLUX
#endif
#if defined NEMURO
# define HOLLING_GRAZING
# undef IVLEV_EXPLICIT
#endif
#ifdef BIO_FENNEL
# define CARBON
# define DENITRIFICATION
# define BIO_SEDIMENT
# define DIAGNOSTICS_BIO
#endif
#ifdef BIO_UMAINE
# define OXYGEN
# undef CARBON
#endif
#ifdef PERFECT_RESTART
# undef AVERAGES
# undef DIAGNOSTICS_BIO
# undef DIAGNOSTICS_TS
# undef DIAGNOSTICS_UV
# define OUT_DOUBLE
#endif
\end{verbatim}
Here we have declared that we want a three-dimensional solution, but
no masking. There is salinity but we're using a linear equation of state.
The momentum equations have advection, Coriolis force and pressure
gradients. There is both horizontal viscosity and diffusion, but they
are along constant $\sigma$-surfaces and if you check the input file,
you find that the horizontal diffusion is set to zero.
There are ifdefs for various biology cases, none of which
have been defined. Likewise, we are using the default of
\code{ANA\_VMIX} as distributed. We are asking for many other
analytic functions too, including the grid. We are asking
for diagnostic output with the \code{DIAGNOSTICS\_TS} and
\code{DIAGNOSTICS\_UV}.
\subsubsection{Model domain}
The flow does not vary in $x$, so \code{Lm} can be almost anything.
Set the values for \code{Lm}, \code{Mm}, \code{N} and \code{NAT} in
the input file:
\begin{verbatim}
Lm == 41 ! Number of I-direction INTERIOR RHO-points
Mm == 80 ! Number of J-direction INTERIOR RHO-points
N == 16 ! Number of vertical levels
NAT = 2 ! Number of active tracers (usually, 2)
\end{verbatim}
A historical note: \code{Lm} here really is 41 for 41 boxes in the
$x$-direction. It was originally set to 41 for 40 boxes, but the