-
Notifications
You must be signed in to change notification settings - Fork 9
/
code.tex
2062 lines (2010 loc) · 89.5 KB
/
code.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{Details of the Code}
\label{Code}
\subsection{Directory structure}
The directory structure is as shown in Fig.\ \ref{fdirs}, with the
ability to run the ocean alone or coupled to atmospheric and/or
wave models. If running just the ocean, the model can be run forward
in time (the nonlinear model) or as an adjoint, tangent linear, or
representer model for data assimilation purposes. This document
describes the uncoupled forward model only, specifically the version
used for our domains containing sea ice and other
changes from the main trunk code. Details are subject to change
without notice---check your own source code for specific details as
they apply to you.
The directories shown here are:
\begin{klist}
\kitem{Apps} This directory contains a subdirectory for each of
my personal applications and is not in the trunk code. In fact,
it is now a git submodule, i.e., a separate repository. Its
subdirectories contain files used by each application: the ROMS
header file for setting cpp definitions, the analytic formulations
for fields computed in the model rather than read from files
(bottom heat flux of zero, for instance), and ASCII input files
read by ROMS on startup to set things such as forcing file names
and model time-step. Some of these applications are:
\begin{klist}
\kitem{Arctic} This is the curvilinear grid covering the whole
Arctic ocean, with 5--6 km resolution off Alaska, coarser to the
far side.
\kitem{Beaufort} This is shared code for two different Beaufort Sea
domains, one curvilinear at 3 km, the other rectangular at 0.5 km.
\kitem{Bering} This is a 10 km grid of the Bering Sea, generated for
coupling to WRF in the COAWST branch, but also tested with CICE.
\kitem{Circle} This is a circular domain wave propagation problem
with an analytic solution used as a test problem \citep{Lamb32}.
\kitem{NEP} This is the Northeast Pacific domain covering the
waters off the west coast of the US, from California to the
Bering Sea. It is a rectangular domain at about 11 km resolution
when viewed in a conformal conic projection with standard
latitudes of 40 and 60 N.
\kitem{NWGOA} This is a 1.5 km grid of the Northwest Gulf of Alaska. It
gets boundary conditions from the Northeast Pacific grid, but
is not aligned with it.
\end{klist}
Other unsupported applications are also here. The application-specific
files included in the main trunk ROMS are elsewhere.
\kitem{Atmosphere} This directory is under development, not
currently distributed. If you want to run with a coupled atmosphere
or wave model, contact John Warner for access to the COAWST
branch or wait for the NUOPC coupling code to become public.
\kitem{Compilers} This contains \code{makefile} fragments as described in
\S\ref{Mult_dir_make}.
\kitem{Data} Directories under here contain example forcing, grid,
and initial condition NetCDF files. There is also a directory
containing the headers of these files in the format produced
by \code{ncdump} (CDL).
\kitem{Lib} The ARPACK and MCT libraries are needed by the data
assimilation codes and by the coupled models, respectively.
\kitem{makefile} This is the standard ROMS makefile as described
in \S\ref{Gmake}.
\kitem{Master} The ROMS main program is here, in various forms for
the forward model, coupled models and others. See \S\ref{Master}.
\kitem{README} A few words about the code, recommended for all github
projects.
\kitem{README.CICE} A few words about the ``fake'' (direct) coupling
to the Los Alamos CICE model.
\begin{figure}[t]
\thinlines
\begin{center}
\setlength{\unitlength}{3947sp}%
%
\begin{picture}(5505,5286)(1486,-7276)
\put(6976,-5461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Sediment/}%
}}}}
\put(3376,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}NEP/}%
}}}}
\put(3376,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Circle/}%
}}}}
\put(3376,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Bering/}%
}}}}
\put(3376,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Arctic/}%
}}}}
\put(4876,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Adjoint/}%
}}}}
\put(4876,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Bin/}%
}}}}
\put(4876,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Drivers/}%
}}}}
\put(4876,-3661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}External/}%
}}}}
\put(4876,-3961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Functionals/}%
}}}}
\put(4876,-4261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Include/}%
}}}}
\put(4876,-4561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}License\_ROMS.txt}%
}}}}
\put(4876,-4861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Modules/}%
}}}}
\put(4876,-5161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Nonlinear/}%
}}}}
\put(4876,-5461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Obsolete/}%
}}}}
\put(4876,-5761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Programs/}%
}}}}
\put(4876,-6061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Representer/}%
}}}}
\put(4876,-6361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}SeaIce/}%
}}}}
\put(4876,-6661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Tangent/}%
}}}}
\put(4876,-6961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Utility/}%
}}}}
\put(4876,-7261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Version}%
}}}}
\thinlines
{\color[rgb]{0,0,0}\put(2251,-5086){\line( 1, 0){2550}}
}%
{\color[rgb]{0,0,0}\put(2101,-2386){\line( 1, 0){900}}
}%
{\color[rgb]{0,0,0}\put(4501,-4561){\line( 0, 1){1875}}
\put(4501,-2686){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-2986){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-3286){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-3586){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-4486){\line( 0,-1){2700}}
\put(4501,-7186){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-3886){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-4186){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4801,-4486){\line( 0, 1){ 0}}
}%
{\color[rgb]{0,0,0}\put(4501,-4786){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-5086){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-5386){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-5686){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-5986){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-6286){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-6586){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(4501,-6886){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(3001,-2386){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(3001,-2686){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(3001,-2086){\line( 0,-1){1200}}
\put(3001,-3286){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(3001,-2986){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(3001,-2086){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(5926,-5086){\line( 1, 0){975}}
\put(6901,-5086){\line(-1, 0){300}}
\put(6601,-5086){\line( 0,-1){300}}
\put(6601,-5386){\line( 1, 0){300}}
}%
\put(1501,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Atmosphere/}%
}}}}
\put(1501,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Compilers/}%
}}}}
\put(1501,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Data/}%
}}}}
\put(1501,-3661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Lib/}%
}}}}
\put(1501,-3961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}makefile}%
}}}}
\put(1501,-4261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Master/}%
}}}}
\put(1501,-4561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}README}%
}}}}
\put(1501,-4861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}README.CICE}%
}}}}
\put(1501,-5161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}ROMS/}%
}}}}
\put(1501,-5461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}SeaIce/}%
}}}}
\put(1501,-5761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}User/}%
}}}}
\put(1501,-6061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Waves/}%
}}}}
\put(1501,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Apps/}%
}}}}
\put(6976,-5161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}Biology/}%
}}}}
\put(3376,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}.../}%
}}}}
\end{picture}%
\end{center}
\caption{ROMS directory structure.}
\label{fdirs}
\end{figure}
\kitem{ROMS}
These files are for the ocean model, as opposed to other components of
the coupled system.
\begin{klist}
\kitem{Adjoint} This is the adjoint of the forward model, for data
assimilation.
\kitem{Bin} Various shell and Perl scripts for use with the model.
Note that the \code{.sh} files are actually \code{csh} scripts, not
\code{sh} scripts.
\kitem{Drivers} The main program includes one of these files,
depending on how you are running the model. The forward model is in
\code{nl\_ocean.h}.
\kitem{External} ROMS reads an ASCII file on startup. Here are
examples for various applications, also examples of the optional
files for extra components such as a sediment model or a stations
file.
\kitem{Functionals} The file \code{analytical.F} can include one
or more code bits for the analytic specification of for instance the
initial conditions. Here are examples for the supported model test
problems.
\kitem{Include} Each application has a header file with C
preprocessor options for that application. For instance, the
\code{UPWELLING} case has the include file \code{upwelling.h}
containing C preprocessor options for its periodic channel domain.
The full list of available options is in \code{cppdefs.h}.
Another important include file is \code{globaldefs.h}, which can
define some helper C preprocessor tags.
\kitem{License\_ROMS.txt} The open source license under which ROMS
is copyrighted.
\kitem{Modules} The ROMS data structures are now in Fortran 90
module files, located here.
\kitem{Nonlinear} The routines used by the nonlinear forward model
are here, implementing the physics described in \S\ref{Num}.
\begin{klist}
\kitem{Biology} The files for the ecosystem parts of the forward
model are here.
\kitem{Sediment} The files for the sediment parts of the forward
model are here.
\end{klist}
\kitem{Obsolete} Long unused versions of the boundary conditions
are stored here.
\kitem{Programs} Not all computer architectures or compilers are the same.
The \code{types.F} program checks your compiler for the sizes of the
Fortran floating point types.
\kitem{Representer} This is the representer of the forward model, for
data assimilation.
\kitem{SeaIce} The sea ice model described in \S\ref{Iphys} is here.
\kitem{Tangent} This is the tangent linear of the forward model, for data
assimilation.
\kitem{Utility} Here are utility functions used by the various
ROMS routines, many dealing with I/O.
\kitem{Version} A file containing the time and date of this
\code{svn} revision, also the \code{svn} URL---if and only if you
check out with svn. At least the date in the file is kept current
by Hernan. ``git log'' can show you the svn history, in commits such as:
\begin{verbatim}
commit b4e77b3a45208ee8059ca7b83e038371a60bc0d0
Author: arango <arango@f091316a-d328-0410-a40a-876eff57d070>
Date: Fri Jun 23 23:22:54 2017 +0000
src:ticket:733
git-svn-id: https://www.myroms.org/svn/src/trunk@851
f091316a-d328-0410-a40a-876eff57d070
\end{verbatim}
where the commit is associated with trac ticket 733 and svn revision 851.
\end{klist}
\kitem{SeaIce} This is code for coupling to the Los Alamos CICE model
with some tips in README.CICE. It works, although the coupling is
inefficient. The Norwegians have also been working on this problem
and they have released the \code{metroms} coupling using MCT on github.
\kitem{User} Some might choose to use this directory rather than
the Apps directory. It serves the same purpose but is arranged
by file type rather than by application.
\kitem{Waves} The SWAN wave model is here.
\end{klist}
\subsection{Main subroutines}
\label{Master}
\subsubsection{master.F}
The main program is in \code{master.F}. It is simply a shell, including
one of \code{mct\_coupler.h}, \code{esmf\_coupler.h} or \code{ocean.h}. In
our case, \code{ocean.h} contains the actual main program, which
initializes MPI (if needed), calls \code{ROMS\_initialize},
calls \code{ROMS\_run} with an argument for how long to run for,
then \code{ROMS\_finalize}, and finally wraps up the MPI.
See Fig.\ \ref{focean_h}.
\begin{figure}[t]
\thinlines
\begin{center}
\setlength{\unitlength}{3947sp}%
%
\begin{picture}(5998,1749)(1501,-2548)
{\color[rgb]{0,0,0}\put(2851,-1186){\line( 1, 0){750}}
\put(3601,-1186){\line( 0, 1){375}}
\put(3601,-811){\line( 1, 0){225}}
}%
{\color[rgb]{0,0,0}\put(3601,-1186){\line( 0,-1){900}}
\put(3601,-2086){\line( 1, 0){225}}
}%
{\color[rgb]{0,0,0}\put(2476,-1486){\line( 1, 0){825}}
\put(3301,-1486){\line( 0,-1){825}}
\put(3301,-2311){\line( 1, 0){2100}}
\put(5401,-2311){\line( 0, 1){1125}}
\put(5401,-1186){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(2701,-1786){\line( 1, 0){300}}
\put(3001,-1786){\line( 0,-1){750}}
\put(3001,-2536){\line( 1, 0){2700}}
\put(5701,-2536){\line( 0, 1){750}}
\put(5701,-1786){\line( 1, 0){300}}
}%
{\color[rgb]{0,0,0}\put(5701,-2386){\line( 1, 0){300}}
}%
\put(1201,-961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{mpi\_init}}%
}}}}
\put(1201,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ROMS\_initialize}}%
}}}}
\put(1201,-1561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ROMS\_run}}%
}}}}
\put(1201,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ROMS\_finalize}}%
}}}}
\put(1201,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{mpi\_finalize}}%
}}}}
\put(3901,-961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{initialize\_parallel}}%
}}}}
\put(3901,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{inp\_par}}%
}}}}
\put(3901,-1561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{wclock\_on}}%
}}}}
\put(3901,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{mod\_arrays}}%
}}}}
\put(3901,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{initial}}%
}}}}
\put(5851,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{main3d} or
\code{main2d}}%
}}}}
\put(6151,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{wclock\_off}}%
}}}}
\put(6151,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{close\_out}}%
}}}}
\put(6151,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0.82,.0}if (trouble)}%
}}}}
\put(7046,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{wrt\_rst}}%
}}}}
\end{picture}%
%
\end{center}
\caption{ROMS main structure.}
\label{focean_h}
\end{figure}
\subsubsection{ocean\_control.F}
This is again a shell which includes one of many other files to do
the actual work. In this case, the worker files all contain
\code{ROMS\_initialize}, \code{ROMS\_run} and \code{ROMS\_finalize}
and live in the \code{ROMS/Drivers} directory. The driver file we
will be looking at is \code{nl\_ocean.h}.
\subsubsection{ROMS\_initialize}
This is called at the beginning of the run and therefore starts off
by finding out how many parallel processes are running and which one
this is, then calls the following ROMS routines:
\begin{klist}
\kitem{initialize\_parallel} In the \code{mod\_parallel} module,
set up a few variables, including some for the built-in profiling.
\kitem{inp\_par} Call \code{read\_phypar} to read in the ASCII input
file(s) used by ROMS, set up the parallel tiles, then call
routines to read in the rest of the ASCII input for biology, ice,
etc.
\kitem{wclock\_on} In \code{timers.F}, initialize a timer for
the built-in profiling.
\kitem{mod\_arrays} Allocate and initialize the dynamically sized
arrays in ROMS based on the grid sizes read in by \code{inp\_par}.
\kitem{initial} Read in the initial conditions from one or more NetCDF
files (one per grid) or compute them analytically. Likewise
for the grid, plus set up the vertical grid spacing to be
used and many other details.
\end{klist}
\subsubsection{ROMS\_run}
Call one of these two routines with the RunInterval argument:
\begin{klist}
\kitem{main3d} or \code{main2d} Solve the full
equations described in \S\ref{Num} (\code{main3d}) or the depth-integrated
version only (\code{main2d}).
\end{klist}
\subsubsection{ROMS\_finalize}
This is called at the end of the run, whether it was otherwise
successful or not. The routines called are:
\begin{klist}
\kitem{wrt\_rst} If the run had an error code set, write out a
restart record of the current model fields in case they are useful in
diagnosing the trouble.
\kitem{wclock\_off} End the built-in timers and cause them to print
out a report.
\kitem{close\_io} Close all open files so as to flush the buffers
and put NetCDF files into a finished state.
\end{klist}
\subsection{Initialization}
\label{Ini}
\begin{klist}
\kitem{checkdefs}Report on which C preprocessor variables
have been \code{\#define}d and check their consistency (called from
\code{inp\_par}).
\kitem{ana\_grid} Compute the grid(s) internally.
\kitem{ana\_mask} Compute the land mask internally.
\kitem{get\_grid} Read in the curvilinear coordinate arrays as
well as $f$ and $h$ from one NetCDF file per grid.
\kitem{set\_scoord} Set and initialize relevant variables
associated with the vertical transformation to nondimensional
$\sigma$-coordinate described in Appendix~\ref{Scoord}.
\kitem{set\_weights} Set the barotropic time-step average
weighting function.
\kitem{metrics} Compute the metric term combinations which do
not depend on the surface elevation and therefore remain constant in
time.
\kitem{ini\_strengthcoef} Compute a field for the nonlinear ice
strength option \citep{Overland_1988}.
\kitem{ana\_wtype} Compute the Jerlov water type field internally.
\kitem{ana\_nudgcoef} Compute the nudging time scales.
\kitem{get\_nudgcoef} Read the nudging time scales from a file.
\kitem{ini\_hmixcoef} Initialize the horizontal mixing coefficients.
\kitem{ana\_sponge} Compute the horizontal mixing coefficients
internally.
\kitem{ana\_initial} Analytic initial conditions for momentum and
active tracers.
\kitem{ana\_passive} Analytic initial conditions for passive tracers.
\kitem{ana\_biology} Analytic initial conditions for ecosystem tracers.
\kitem{ana\_sediment} Analytic initial conditions for sediment tracers.
\kitem{ana\_ice} Analytic initial conditions for ice variables.
\kitem{get\_state} Read initial fields from disk---either
restart or from some other source which has been converted to the
appropriate NetCDF format.
\kitem{get\_wetdry} or \code{wetdry} Initialize wet/dry masks.
\kitem{set\_depth} Compute time-evolving depths.
\kitem{set\_massflux} Compute initial horizontal mass fluxes.
\kitem{omega} Compute initial vertical velocities.
\kitem{rho\_eos} Compute initial density fields.
\kitem{ana\_psource} Set up analytic point sources.
\kitem{check\_multifile} Read input files in which one or more file
is specified to find out time-ranges, etc.
\kitem{get\_idata} Read in time-invariant forcing data.
\kitem{get\_data} Read in the first record of time-varying forcing
fields, boundary conditions, etc.
\kitem{set\_masks} Compute I/O masks.
\kitem{ana\_drag} Compute bottom drag coefficients internally.
\kitem{stiffness} Compute grid stiffness.
\kitem{grid\_coords} Convert initial float and station locations to
fractional grid coordinates.
\kitem{nesting} Perform inter-grid communications.
\end{klist}
\subsubsection{main3d}
This solves the full three-dimensional equations described in \S\ref{Num}.
It has siblings \code{main2d} for solving the depth-integrated equations
and \code{main3d\_offline} for reading files from a prior simulation
and using them to advect the biological tracers or the Lagrangian floats.
The full version is shown in Fig.\ \ref{flow}, where the outer loop is
over both timesteps and grids. Note that many subroutines are
optional and only get called if the appropriate C preprocessor
switches have been set. The subroutines are described as follows:
\begin{figure}
\thinlines
\begin{center}
\setlength{\unitlength}{3947sp}%
%
\begin{picture}(5642,5697)(1189,-6123)
\thinlines
{\color[rgb]{0,0,0}\put(5651,-586){\line( 0,-1){4425}}
}%
{\color[rgb]{0,0,0}\put(1201,-736){\line( 0,-1){5475}}
\put(1201,-6211){\line( 1, 0){1800}}
\put(3001,-6211){\line( 0, 1){5625}}
\put(3001,-586){\vector( 1, 0){450}}
}%
{\color[rgb]{0,0,0}\put(3451,-586){\line( 0,-1){5625}}
\put(3451,-6211){\line( 1, 0){1750}}
\put(5201,-6211){\line( 0, 1){5625}}
\put(5201,-586){\vector( 1, 0){450}}
}%
\put(5801,-661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{rhs3d}}%
}}}}
\put(5801,-961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{my25\_prestep}}%
}}}}
\put(5801,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{gls\_prestep}}%
}}}}
\put(6101,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{step2d}}%
}}}}
\put(6101,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{step2d}}%
}}}}
\put(5801,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_depth}}%
}}}}
\put(5801,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{step3d\_uv}}%
}}}}
\put(5801,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{omega}}%
}}}}
\put(5801,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{my25\_corstep}}%
}}}}
\put(5801,-3661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{gls\_corstep}}%
}}}}
\put(5801,-3961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{biology}}%
}}}}
\put(5801,-4261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{sediment}}%
}}}}
\put(5801,-4561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{step3d\_t}}%
}}}}
\put(5801,-4861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{step\_floats}}%
}}}}
\put(5801,-1561){\makebox(0,0)[lb]{{{{\color[rgb]{0,.82,0}<loop>}%
}}}}
\put(1201,-661){\makebox(0,0)[lb]{{{{\color[rgb]{0,.82,0}<loop>}%
}}}}
\put(3601,-661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_vbc}}%
}}}}
\put(1401,-961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ntimesteps}}%
}}}}
\put(1401,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{get\_data}}%
}}}}
\put(1401,-1561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_data}}%
}}}}
\put(1401,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{.8,0,0}First step only:}%
}}}}
\put(1701,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ini\_zeta}}%
}}}}
\put(1701,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_depth}}%
}}}}
\put(1701,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ini\_fields}}%
}}}}
\put(1401,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_massflux}}%
}}}}
\put(1401,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{rho\_eos}}%
}}}}
\put(1401,-3661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{diag}}%
}}}}
\put(1401,-3961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{radiation\_stress}}%
}}}}
\put(1401,-4261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{cawdir\_eval}}%
}}}}
\put(1401,-4561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ana\_albedo}}%
}}}}
\put(1401,-4861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{albedo\_eval}}%
}}}}
\put(1401,-5161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ccsm\_flux}}%
}}}}
\put(1401,-5761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ncep\_flux}}%
}}}}
\put(1401,-6061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{bblm}}%
}}}}
\put(1401,-5461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{bulk\_flux}}%
}}}}
\put(3601,-961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_tides}}%
}}}}
\put(3601,-1261){\makebox(0,0)[lb]{{{{\color[rgb]{.8,0,0}First rst step only:}%
}}}}
\put(3901,-1561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ice\_flux\_rst}}%
}}}}
\put(3601,-1861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{seaice}}%
}}}}
\put(3601,-2161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{ana\_vmix}}%
}}}}
\put(3601,-2461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{lmd\_vmix}}%
}}}}
\put(3601,-2761){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{bvf\_mix}}%
}}}}
\put(3601,-3061){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{hmixing}}%
}}}}
\put(3601,-3361){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{omega}}%
}}}}
\put(3601,-3661){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{wvelocity}}%
}}}}
\put(3601,-3961){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_zeta}}%
}}}}
\put(3601,-4261){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_diags}}%
}}}}
\put(3601,-4561){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_filter}}%
}}}}
\put(3601,-4861){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_avg}}%
}}}}
\put(3601,-5161){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{set\_avg2}}%
}}}}
\put(3601,-5461){\makebox(0,0)[lb]{{{{\color[rgb]{0,0,0}\code{output}}%
}}}}
\put(3601,-5761){\makebox(0,0)[lb]{{{{\color[rgb]{0,.82,0}Exit if time}%
}}}}
\put(3601,-5956){\makebox(0,0)[lb]{{{{\color[rgb]{0,.82,0} is reached}%
}}}}
\end{picture}%
\end{center}
\caption{Flow chart of the model main program in forward mode. Calls to
\code{nesting} for nested grid applications have been left out.}
\label{flow}
\end{figure}
\begin{klist}
\kitem{ntimesteps} Find out how many timesteps to take on each grid.
\kitem{get\_data} Read in the second and subsequent records of
time-varying forcing fields, boundary conditions, etc.
\kitem{set\_data} Time interpolate between the records read in by
\code{get\_data}.
\kitem{ini\_zeta} Check for wet/dry cells if needed and initialize
all the time levels of zeta.
\kitem{ini\_fields} Initialize the 2-D velocities to match the
vertical integral of the 3-D velocities, making all the time levels
match.
\kitem{set\_massflux} Compute horizontal mass fluxes, $\frac{H_z
u}{n}$ and $\frac{H_z v}{m}$.
\kitem{rho\_eos} Compute the nonlinear equation of state.
\kitem{diag} Compute some global sums, print them, and check them to
see if they are sensible. If not, stop the model run.
\kitem{radiation\_stress} Compute the radiation stresses due to
wave-current interactions \citep{Mellor_2003,Mellor_2005}.
\kitem{cawdir\_eval}, \code{ana\_albedo} or \code{albedo\_eval} Compute
the albedo at the ice and ocean surface.
\kitem{ccsm\_flux} Compute the surface fluxes from the atmosphere
based on a marine boundary layer. This version comes from CCSM
\citep{Large_08} and is reputed to do better outside of the tropics
than the default bulk flux computation.
\kitem{bulk\_flux} Compute the surface fluxes from the atmosphere
based on a marine boundary layer. This version comes from COARE
version 3.0 \citep{Fairall_2003,Taylor_2001,Oost_2002}.
\kitem{ncep\_flux} Compute the surface fluxes from the NCEP
atmospheric model.
\kitem{bblm} Compute the bottom stresses from one of three bottom
boundary layer models.
\kitem{set\_vbc} Compute the surface and bottom fluxes and stresses
that aren't computed elsewhere---set vertical boundary conditions.
\kitem{set\_tides} Compute the tidal boundary conditions from the
tidal constituents.
\kitem{seaice} Run the sea ice model described in \S\ref{Iphys}. It
changes the surface boundary conditions for the ocean and therefore
gets called before the call to \code{output} or anything else that
would be needing the surface boundary conditions. In the case of a
perfect restart, \code{ice\_flux\_rst} is called instead on the
first timestep---this restores surface fluxes from the restart file.
\kitem{ana\_vmix} Called if there's an analytic profile for the
vertical mixing coefficient.
\kitem{lmd\_vmix} Called when using the K-profile parameterization
of vertical mixing \citep{Large94,Large98}.
\kitem{bvf\_mix} Compute the vertical mixing as a function of the
Brunt-V\"ais\"al\"a frequency.
\kitem{hmixing} Compute time-dependent horizontal mixing coefficients
\citep{S63, Holland_98, Webb_98,Griffies_2000}.
\kitem{omega} Compute the $\Omega$ vertical velocity from the horizontal
divergences.
\kitem{wvelocity} Compute the physical vertical velocity for the
model output.
\kitem{set\_zeta} Set the surface elevation to the time-mean over the
last baroclinic time-step.
\kitem{set\_diags} Accumulate the time-average of the diagnostics
fields.
\kitem{set\_filter} Accumulate a weighted sum using a Lanczos filter
for detiding the most important of the output fields. Not in the trunk
code.
\kitem{set\_avg} Accumulate time-averaged fields for the averages
output.
\kitem{set\_avg2} Accumulate the time-averaged surface fields for the
second averages output. Not in the trunk code.
\kitem{output} Write to various output NetCDF files.
\kitem{rhs3d} Call \code{pre\_step3d} to compute a predictor
step on the three-dimensional variables, then compute
right-hand-sides of the three-dimensional velocity fields for the
corrector step, including pressure gradients.
\kitem{my25\_prestep} Compute the predictor step for turbulent
kinetic energy prognostic variables, \code{tke} and \code{gls}.
\kitem{gls\_prestep} Compute the predictor step for turbulent
kinetic energy prognostic variables, \code{tke} and \code{gls}.
\kitem{step2d} Compute the depth-integrated time-step. It is called in
a loop over all the short time-steps, first as a predictor step, then
as a corrector step.
\kitem{step3d\_uv} Complete the time-step for the three-dimensional
velocities.
\kitem{omega} Compute the $\Omega$ vertical velocity.
\kitem{my25\_corstep} Perform the corrector step for turbulent kinetic
energy and length scale prognostic variables, \code{tke} and \code{gls}
\citep{Mellor82, Galperin88}.
\kitem{gls\_corstep} Perform the corrector step for turbulent kinetic
energy and length scale prognostic variables, \code{tke} and \code{gls}
\citep{Umlauf2003, Warner_2005}.
\kitem{biology} Compute the changes to the biological tracers due to
biological activity using one of several options for the ecosystem
model.
\kitem{sediment} Compute changes to the sediment tracers
\citep{Warner_2008}.
\kitem{step3d\_t} Complete the tracer time-step.
\kitem{ice\_frazil} Compute the frazil ice growth, if any. Now called
from inside \code{step3d\_t}.
\kitem{step\_floats} Time-step the Lagrangian floats.
\end{klist}
\subsection{Modules}
\label{Mod_f90}
Now that we are using Fortran 90, the method of choice for managing
data structures is modules. The \code{ROMS/Modules} directory
contains all of the ROMS modules that contain globally used
variables. The complete list is:
\begin{klist}
\kitem{mod\_arrays.F} This actually has no data structures, but has the
routine that calls the allocate and initialize routines for all the
others.
\kitem{mod\_average.F} If \code{AVERAGES} is defined, this will
provide the storage for the running means of the fields you are averaging.
\kitem{mod\_average2.F} If \code{AVERAGES2} is defined, this will
provide the storage for the surface running means of the fields you are
averaging.
\kitem{mod\_bbl.F} If \code{BBL\_MODEL} is defined, this will
provide the storage for the bottom boundary fields.
\kitem{mod\_behavior.F} If \code{FLOAT\_BIOLOGY} is defined, this will
include a file for adding behavior to floats, such as oysters
sinking to the bottom.
\kitem{mod\_biology.F} If \code{BIOLOGY} is defined, this will
provide the storage for the biology interaction parameters.
\kitem{mod\_boundary.F} This contains the storage for the open boundary
conditions. If they aren't provided analytically, this will also provide
the storage for fields read from a file that need to be time-interpolated.
\kitem{mod\_clima.F} If one of \code{LsshCLM}
or several other options is set to \code{.true.}, this will
provide the storage for the climatology fields.
\kitem{mod\_coupler.F} If either \code{MODEL\_COUPLING} or
\code{ESMF\_LIB} is defined, this will set up the requisite fields and
data structures for the coupling.
\kitem{mod\_coupling.F} If \code{SOLVE3D} is defined, this will
provide the storage for the fields used in coupling the 2-D
and 3-D components of the simulation.
\kitem{mod\_diags.F} If \code{DIAGNOSTICS} is defined, this will
provide the storage for the various tendency terms.
\kitem{mod\_eclight.F} If both \code{BIOLOGY} and \code{ECOSIM}
are defined, this will set up the spectral irradiance
variables.
\kitem{mod\_eoscoef.F} If \code{NONLIN\_EOS} is defined, this will
provide the polynomial expansion coefficients for the nonlinear equation
of state for sea water.
\kitem{mod\_filter.F} If \code{FILTERED} is defined, this will provide
the storage for the weighted means used in detiding the averages.
Not in the trunk code.
\kitem{mod\_floats.F} If \code{FLOATS} is defined, this will
provide the storage for the float tracking variables.
\kitem{mod\_forces.F} This
provides the storage for the surface and bottom forcing fields.
\kitem{mod\_fourdvar.F} If either \code{FOUR\_DVAR} or \code{VERIFICATION}
is defined, this will set up the variational data assimilation
variables.
\kitem{mod\_grid.F} This provides the storage for the model grid fields.
\kitem{mod\_ice.F} If \code{ICE\_MODEL} or \code{CICE\_MODEL} is
defined, this will provide storage for the ice fields.
\kitem{mod\_iounits.F} This contains a number of variables used by the
I/O, including file names and file IDs.
\kitem{mod\_kinds.F} This contains the integers associated with the
various integer and real Fortran types. If you find more systems
supporting 128-bit reals, let us know.
\kitem{mod\_mixing.F} This contains the arrays for the various
optional horizontal and vertical mixing parameterizations.
\kitem{mod\_ncparam.F} This contains all sorts of parameters relating to
the NetCDF I/O files, including those read from the \code{varinfo.dat}
file. The parameters \code{MV} and \code{NV} are set here, giving
the maximum number of variables that can be read [this is a change
from the trunk code].
\kitem{mod\_nesting.F} If \code{NESTING} is defined, this module defines
generic structures used for nesting, composed, and mosaic grids.
Still in development, but some cases do now work.
\kitem{mod\_netcdf.F} This brings in \code{netcdf.mod} and defines
wrapper functions for many of the netcdf functions.
\kitem{mod\_ocean.F} This contains the 2-D and 3-D fields of the primitive
ocean variables and optionally the sediment variables.
\kitem{mod\_parallel.F} This sets up some global variables such as
\code{Master}, which is true for the master thread or
process. It also initializes the internal ROMS profiling arrays.
\kitem{mod\_param.F} This contains the sizes of each grid used, plus
things like how many tidal constituents are being used. Many of these are
read from the input files during initialization, not known at compile
time.
\kitem{mod\_scalars.F} This contains a large number of scalars, i.e. values
which don't have spatial dependence. Some are fixed constants such
as \code{itemp} referring to the temperature tracer. Others could
have a different value on each grid.
\kitem{mod\_sedbed.F} If either \code{SEDIMENT} or \code{BBL\_MODEL}
is defined, this contains parameters for the sediment bed layers.
\kitem{mod\_sediment.F} If either \code{SEDIMENT} or \code{BBL\_MODEL}
is defined, this contains parameters for the respective model.
\kitem{mod\_sources.F} This contains the variables used for point
sources, only allocated if one of \code{LuvSrc}, \code{LwSrc}
or \code{LtracerSrc} is set to \code{.true}.
\kitem{mod\_stepping.F} This contains the time-stepping variables used to
point to the relevant time level.
\kitem{mod\_storage.F} If \code{PROPAGATOR} is
defined, this module defines the work space for the Generalized
Stability Theory (GST) Analysis package (ARPACK).
\kitem{mod\_strings.F} This contains strings such as a title for the run,
the list of \code{cpp} options defined, and the names of the sections of
code being profiled.
\kitem{mod\_tides.F} If \code{SSH\_TIDES} and/or \code{UV\_TIDES} is
defined, this will provide the storage for the tidal constituents.
\kitem{mod\_trc\_sources.F} If \code{TRC\_PSOURCE}
is defined, this contains the variables used
for tracer point sources. Not in the trunk code.
\end{klist}
\subsection{Functionals}
\label{Functionals}
The Functionals directory contains \code{analytical.F} which
conditionally includes code bits for computing analytic values for a
wide variety of fields. Many are alternates for reading from NetCDF
files, especially for idealized problems.
\begin{klist}
\kitem{ana\_aiobc} Provide analytic open boundary conditions for the ice
concentration.
\kitem{ana\_albedo} Compute analytic surface albedo.
\kitem{ana\_biology} Provide analytic initial conditions for the
biology tracers.
\kitem{ana\_btflux} Compute analytic kinematic bottom flux of
tracer type variables (default of zero).
\kitem{ana\_cloud} Provide analytic cloud fraction.
\kitem{ana\_diag} Compute customized diagnostics.
\kitem{ana\_dqdsst} Provide analytic variation of surface heat
flux as a function of SST.
\kitem{ana\_drag} Compute customized bottom drag coefficients.
\kitem{ana\_fsobc} Provide analytic open boundary conditions for
the free surface.
\kitem{ana\_grid} Set up an analytic grid.
\kitem{ana\_hiobc} Provide analytic open boundary conditions for the ice
thickness.
\kitem{ana\_hsnobc} Provide analytic open boundary conditions for the snow
thickness.
\kitem{ana\_hsnobc} Provide analytic open boundary conditions for the snow
thickness.
\kitem{ana\_humid} Provide analytic atmospheric humidity.
\kitem{ana\_ice} Provide analytic initial conditions for the sea ice.
\kitem{ana\_initial} Set up analytic initial conditions for the ocean.
\kitem{ana\_lrflux} Provide analytic kinematic surface
downward longwave radiation.
\kitem{ana\_m2clima} Set up an analytic climatology for the
two-dimensional momentum.
\kitem{ana\_m2obc} Provide analytic open boundary conditions for the
two-dimensional momentum.
\kitem{ana\_m3clima} Set up an analytic climatology for the
three-dimensional momentum.
\kitem{ana\_m3obc} Provide open boundary conditions for the
three-dimensional momentum.
\kitem{ana\_mask} Set up an analytic mask.
\kitem{ana\_ncep} Set up analytic fields as if they came from NCEP.
\kitem{ana\_nudgcoef} Set up spatially dependent nudging
coefficients for nudging to a climatology.
\kitem{ana\_pair} Provide analytic sea-level air pressure.
\kitem{ana\_passive} Provide analytic initial conditions for
passive tracers.
\kitem{ana\_perturb} Provide analytic perturbations to the
initial conditions.
\kitem{ana\_psource} Provide analytic point source fluxes.
\kitem{ana\_rain} Provide analytic rainfall.
\kitem{ana\_scope} Set adjoint sensitivity spatial scope masking
arrays.
\kitem{ana\_sediment} Provide analytic initial conditions for the
sediment tracers.
\kitem{ana\_smflux} Provide analytic kinematic surface
momentum flux (wind stress).
\kitem{ana\_snow} Provide analytic snowfall.
\kitem{ana\_specir} Set surface solar downwelling spectral
irradiance at just beneath the sea surface.
\kitem{ana\_spinning} Set time-variable rotation force as the
sum of Coriolis and Centripetal accelerations. This is used in polar
coordinate applications (annulus grid).
\kitem{ana\_sponge} Provide spatially variable horizontal mixing
coefficients.
\kitem{ana\_srflux} Provide analytic kinematic surface
shortwave radiation.
\kitem{ana\_ssh} Provide analytic sea surface height.
\kitem{ana\_sss} Provide analytic sea surface salinity.
\kitem{ana\_sst} Provide analytic sea surface temperature.
\kitem{ana\_stflux} Provide analytic kinematic surface
flux of tracer type variables.
\kitem{ana\_tair} Provide analytic air temperature.
\kitem{ana\_tclima} Provide analytic tracer climatology fields.
\kitem{ana\_tobc} Provide analytic open boundary conditions for
all tracers (active, passive, biology, and sediment).
\kitem{ana\_vmix} Provide analytic vertical mixing coefficients.
\kitem{ana\_winds} Provide analytic winds.
\kitem{ana\_wwave} Provide analytic wind-induced wave amplitude,
direction and period.
\end{klist}
\subsection{Other subroutines and functions}
\label{Minor}
The ROMS/Utility directory contains an assortment of useful
routines, many of which deal with I/O:
\begin{klist}
\kitem{NetCDF I/O} The I/O has been cleaned up so that {\em all}
processes check for the return code on reads and writes and exit on
failure. In many cases, the master process is the only one actually
doing the I/O, but it then broadcasts its status to the rest.
\begin{klist}
\kitem{def\_*} Create the ROMS NetCDF file of the appropriate
type, including dimensions, attributes, and variables.
\kitem{def\_info} Add some standard scalar variables to any NetCDF file.
\kitem{get\_*fld} Read a field from a netcdf file, perhaps
using one of \code{nf\_fread2d} and its kin. \code{nf\_fread2d}
is special in that it can read uniformly gridded forcing files
and call \code{regrid} to regrid them onto the ROMS grid.
\kitem{wrt\_*} Write to the ROMS NetCDF file of the appropriate type.
\end{klist}
\kitem{Text input} ROMS can parse text files in a specific format.
These files replace what many other models use namelists for.
\begin{klist}
\kitem{read\_*} The ocean\_xx.in file is read by \code{read\_phypar}
while others read the stations, floats, and other text files.
\end{klist}
\end{klist}
\subsection{C preprocessor variables}
\label{Cpp1}
Before it can be compiled, the model must be run through the C
preprocessor \code{cpp}, as described in Appendix \ref{Cpp}. The C
preprocessor has its own variables, which may be defined either with an
explicit \code{\#define} command or with a command line option to
\code{cpp}. We have chosen to define these variables in an
application-specific include file, except for some
machine-dependent ones, which are defined in the \code{makefile}.
These variables allow you to conditionally compile sections of the
code. For instance, if \code{MASKING} is not defined, the masking
code will not be seen by the compiler, and the masking variables will
not be declared.
The top of each Fortran file contains \code{\#include ``cppdefs.h''}.
This file will include the user-provided file of \code{cpp} options
and then include \code{globaldefs.h}. This latter will set some
internal ROMS \code{cpp} variables for you, depending on choices you
have made. For instance, if you don't provide analytic surface
forcing fields by one means or another, \code{globaldefs.h} will set
\code{FRC\_FILE} and ROMS will attempt to read a
forcing file. Some combinations of options don't make sense, so
\code{checkdefs} will complain and cause the run to end if it finds
any incompatibilities in your setup.
The exact list of user-selectable \code{cpp} variables will depend
on which ROMS branch you have. Those listed below are in the sea-ice
branch on github. They can be grouped into several categories:
\begin{klist}
\kitem{Momentum terms} \mbox{}
The default horizontal advection is 3rd-order upstream bias for
3D momentum and 4th-order centered for 2D momentum. The default
vertical advection is 4th-order centered for 3D momentum. If this
is what you want, no flags for momentum advection need to be
activated except for \code{UV\_ADV}.
The 3rd-order upstream split advection (\code{UV\_U3ADV\_SPLIT}) can be used
to correct for the spurious mixing of the advection operator in
terrain-following coordinates. If this is chosen, the advection
operator is split into advective and viscosity components and several
internal flags are activated in \code{globaldefs.h}. Notice that
horizontal and vertical advection of momentum is 4th-order centered
plus biharmonic viscosity to correct for spurious mixing.
\begin{klist}
\kitem{UV\_ADV} Define to compute the momentum advection terms.
\kitem{CURVGRID} Define to compute the extra
non-linear advection terms which arise when using curvilinear coordinates.
\kitem{UV\_COR} Define to compute the Coriolis term.
\kitem{UV\_U3ADV\_SPLIT} Define for 3rd-order upstream split
momentum advection.
\kitem{UV\_C2ADVECTION} Define for 2nd-order centered advection.
\kitem{UV\_C4ADVECTION} Define for 4rd-order centered advection.
\kitem{UV\_SADVECTION} Define for splines vertical advection
(for shallow, vertically well-resolved domains).
\kitem{UV\_VIS2} Define to compute the
horizontal Laplacian viscosity.
\kitem{UV\_VIS4} Define to compute the
horizontal biharmonic viscosity.
\kitem{UV\_SMAGORINSKY} Define for Smagorinsky-like viscosity.
\kitem{UV\_LOGDRAG} Define for logarithmic bottom friction.
\kitem{UV\_LDRAG} Define for linear bottom friction.
\kitem{UV\_QDRAG} Define for quadratic bottom friction.
\kitem{UV\_WAVEDRAG} Define for extra linear bottom wave drag.
\kitem{UV\_DRAG\_GRID} Define for spatially variable bottom drag.
\kitem{SPLINES\_VVISC} Define for splines reconstruction of
vertical viscosity.
\kitem{LIMIT\_BSTRESS} Define for bottom drag limiter.
\end{klist}
\kitem{Tracers} \mbox{}
The default horizontal and vertical advection is 4th-order centered.
The 3rd-order upstream split advection (\code{TS\_U3ADV\_SPLIT}) can be used
to correct for the spurious diapycnal diffusion of the advection
operator in terrain-following coordinates. If this is chosen, the
advection operator is split in advective and diffusive components
and several internal flags are activated in \code{globaldefs.h}. Notice
that horizontal and vertical advection of tracer is 4th-order centered
plus biharmonic diffusion to correct for spurious diapycnal mixing.
The total time-dependent horizontal mixing coefficient are computed
in \code{hmixing.F}. It is also recommended to use the rotated mixing
tensor along geopotentials (\code{MIX\_GEO\_TS}) for the biharmonic
operator.