-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathACCESS-OM2-1-025-010deg.tex
3102 lines (2541 loc) · 233 KB
/
ACCESS-OM2-1-025-010deg.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
\documentclass[11pt, a4paper]{article}
% BUG: occasional page overruns (look for "Overfull \vbox" error in .log)
% perhaps related to longtable? upgrading to TeXLive2019 didn't help...
% https://tex.stackexchange.com/questions/203629/longtable-and-floats-wrong-table-breaks-on-pages-with-floats-part-2/207748#207748
\usepackage{ifthen}
\newboolean{overleaf}\setboolean{overleaf}{false} % set to true for compatibility with overleaf
\newboolean{draft}\setboolean{draft}{true} % whether to display notes (e.g. TODO, FIXME, etc)
\newboolean{gitinfo}\setboolean{gitinfo}{true} % whether use gitinfo2 to provide git detail (doesn't work in Overleaf; you may also need to run setup.sh the first time)
\ifthenelse{\boolean{overleaf}}{\setboolean{gitinfo}{false}}{}
\usepackage[T1]{fontenc}
\usepackage{fourier}
%\reversemarginpar % doesn't work...
\newcommand{\WARNING}{\marginpar{\textcolor{red}{\danger}}\index{Warnings \textcolor{red}{\danger}}}
\usepackage[a4paper, top=1cm,bottom=1cm,left=2cm,right=2cm, includeheadfoot]{geometry}
%\geometry{a4paper}
%\usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent
\ifthenelse{\boolean{overleaf}}{\usepackage[demo]{graphicx}}{\usepackage{graphicx}}
\usepackage{amssymb}
%\usepackage{epstopdf}
%\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}
\usepackage[table,dvipsnames]{xcolor} % loads also colortbl
\definecolor{lightblue}{rgb}{0.93,0.95,1.0}
%%\rowcolors{2}{blue!4}{white}
%\rowcolors{1}{lightblue}{white}
\definecolor{link}{rgb}{0,0,1}
\usepackage[colorlinks,
linkcolor={link},citecolor={link},urlcolor={link},
breaklinks, bookmarks, bookmarksopen, bookmarksnumbered %, backref=section
]{hyperref}
\usepackage{url}\urlstyle{sf} % rm, sf, tt or same
\usepackage{breakurl}
%% Define a new style for the urls that will use a smaller font.
\makeatletter
\def\url@smallurlstyle{%
\@ifundefined{selectfont}{\def\UrlFont{\sf}}{\def\UrlFont{\footnotesize\sffamily}}}
\makeatother
%% Now actually use the newly defined style.
\urlstyle{smallurl}
\usepackage{PTSansNarrow} % narrow sans serif font for urls
\usepackage[scaled=.9]{inconsolata} % for texttt
\usepackage{mathpazo}
\usepackage{tikz}
\tikzset{
state/.style={
rectangle,
rounded corners,
draw=black, ultra thick,
minimum height=2em,
inner sep=2pt,
text centered,
text width=40ex
},
}
\usepackage{datetime2}\DTMsetdatestyle{iso}
\ifthenelse{\boolean{gitinfo}}{\usepackage[grumpy]{gitinfo2}}{}
\usepackage{qrcode}
\usepackage{natbib}
\usepackage{ltablex}\keepXColumns
\usepackage{sistyle} % TODO: replace with siunitx?
%\usepackage{siunitx} % would need to update nmltab to replace \num* with the siunitx equivalent
\usepackage{array}
\usepackage[strings]{underscore} % allows hyphenation at underscores
\usepackage[nooneline,small,hypcap=true]{caption} % correct hypcap needs v 3.1 or higher
\renewcommand{\captionlabelfont}{\bfseries}
\setlength{\captionmargin}{0.5cm} \setlength{\abovecaptionskip}{3pt}
\usepackage{placeins}
\usepackage{makeidx}
\makeindex
\ifthenelse{\boolean{draft}}
{\newcommand{\note}[1]{#1}} % show all notes
{\newcommand{\note}[1]{\quad}} % hide all notes
\ifthenelse{\boolean{gitinfo}}
{
\usepackage{fancyhdr}
\pagestyle{fancy}
\renewcommand{\headrulewidth}{0pt}
\lfoot{\textbf{\emph{\textsf{typeset \today\ \DTMcurrenttime\ \DTMcurrentzone}}}}
\rfoot{{\tiny
Last commit%
\ifthenelse{\equal{\gitDirty}{}}{:}{ (\emph{incomplete}):}
%git hash:
\href{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/commit/\gitAbbrevHash}{\gitAbbrevHash},
%\gitCommitterIsoDate, %committed to branch ``\gitBranch ''
\gitAuthorIsoDate, %committed to branch ``\gitBranch ''
%by \gitCommitterName
by \gitAuthorName
%\ifthenelse{\equal{\gitRoff}{}}{}{\hfill \gitRoff\ commit(s) since release \gitRel \\}
}}
%\gitDirty\
%committed by \gitCommitterName , \gitCommitterIsoDate\ \\
%\hfill\textbf{NB: git hash does not reflect any uncommitted changes to this document.}\\
\rhead{}
}
{}
\newcommand{\TODO}[1]{\note{\textcolor{orange}{\textsf{\textbf{TODO:} #1}}}\index{TODO}}
\newcommand{\FIXME}[1]{\note{\textcolor{red}{\textsf{\textbf{FIXME: }#1}}}\index{FIXME}}
\newcommand{\CONTRIBUTORS}[1]{\note{\textcolor{BurntOrange}{\textsf{\textsl{CONTRIBUTORS: #1}}}}}
\newcommand{\ISSUE}[1]{\note{\colorbox{yellow}{\textsf{\textbf{\href{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/issues/#1}{ISSUE #1}}}}}\index{ISSUE}}
\newcommand{\CISSUE}[1]{\note{\colorbox{gray}{\textsf{\textbf{\href{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/issues/#1}{ISSUE #1}}}}}\index{ISSUE (closed)}}
\setlength{\fboxsep}{0pt}
% link directly to github source
%\newcommand{\momlink}[2]{\href{https://github.com/mom-ocean/MOM5/search?q=#2}{#1}}
%\newcommand{\cicelink}[2]{\href{https://github.com/COSIMA/cice5/search?q=#2}{#1}}
%\newcommand{\yatmlink}[2]{\href{https://github.com/COSIMA/libaccessom2/search?q=#2}{#1}}
% link to appendix tables
% need work around to handle names that include _ (which is many of them!) - possibly due to use of underscore package?
% derived from https://tex.stackexchange.com/questions/129739/label-and-non-plain-text-arguments
\makeatletter
\newcommand*{\make@hex@label}[1]{%
\def\hex@label{#1}%
\@onelevel@sanitize\hex@label
\EdefEscapeHex\hex@label{\hex@label}%
}
\newcommand*{\hexhypertarget}[2]{%
\@bsphack
\make@hex@label{#1}%
\hypertarget{\hex@label}{#2}%
\@esphack
}
\newcommand*{\hexhyperlink}[2]{%
\make@hex@label{#1}%
\hyperlink{\hex@label}{#2}%
}
\makeatother
\newcommand{\momlink}[2]{\hexhyperlink{mom:#2}{#1}}
\newcommand{\cicelink}[2]{\hexhyperlink{cice:#2}{#1}}
\newcommand{\yatmlink}[2]{\hexhyperlink{yatm:#2}{#1}}
\newcommand{\accessomlink}[2]{\hexhyperlink{accessom2:#2}{#1}}
% can \StrSubstitute in xstring be used to remove _? - can't get this to work
%\usepackage{xstring}
%\newcommand{\momlink}[2]{\hyperlink{mom:#2}{#1 mom:\StrSubstitute{#2}{_}{}}}
%\newcommand{\momlink}[2]{\hyperlink{mom:\StrSubstitute{#2}{_}{_}}{#1 mom:\StrSubstitute{#2}{_}{}}}
\newcommand{\paramsty}[1]{\textsf{#1}}
\newcommand{\param}[1]{\paramsty{#1}\index{\paramsty{#1}}}
%\newcommand{\param}[1]{\paramsty{#1}}
\newcommand{\mom}[1]{\paramsty{\momlink{#1}{#1}}\index{\paramsty{#1}}}
\newcommand{\cice}[1]{\paramsty{\cicelink{#1}{#1}}\index{\paramsty{#1}}}
\newcommand{\yatm}[1]{\paramsty{\yatmlink{#1}{#1}}\index{\paramsty{#1}}}
\newcommand{\accessom}[1]{\paramsty{\accessomlink{#1}{#1}}\index{\paramsty{#1}}}
\newcommand{\nmldiffer}[1]{#1} % no special display of differing variables
%\newcommand{\nmldiffer}[1]{\textbf{#1}} % bold display of differing variables
%\definecolor{hilite}{cmyk}{0, 0, 0.9, 0}\newcommand{\nmldiffer}[1]{\colorbox{hilite}{#1}}\setlength{\fboxsep}{0pt} % colour highlight of differing variables (requires color package)
\newcommand{\nmllink}[2]{#1\index{\paramsty{#2}}} % don't link variables
% \newcommand{\nmllink}[2]{\href{https://github.com/mom-ocean/MOM5/search?q=#2}{#1}\index{\paramsty{#1}}} % link variables to documentation (requires hyperref package)
\definecolor{ignore}{gray}{0.7}\newcommand{\ignored}[1]{\textcolor{ignore}{#1}} % gray display of ignored variables (requires color package)
%\newcommand{\nml}[1]{{\small\textsf{\input{local/#1}}}}
\newcommand{\nml}[1]{{\footnotesize\textsf{\input{#1}}}}
\newlength{\nmllen}\setlength{\nmllen}{8ex}
%\newcommand{\doscript}[1]{\texttt{#1}\\{\footnotesize\textsf{\input{|"#1"}}}}
\newcommand{\doscript}[1]{{\footnotesize\textsf{\input{|"#1"}}}}
%\newcommand{\doscript}[1]{{\footnotesize\textsf{\input{|"#1 > tmp.tex"}\input{tmp.tex}}}}
%\newcommand{\runchanges}[1]{\subsection{#1}%
%%\renewcommand{\nmllink}[2]{\href{https://github.com/mom-ocean/MOM5/search?q=#2}{#1}\index{\paramsty{#1}}} % link to documentation (requires hyperref package)
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin-rsync/g/data3/hh5/tmp/cosima/#1/*/ocean/input.nml}%
%%\renewcommand{\nmllink}[2]{\href{https://github.com/COSIMA/cice5/search?q=#2}{#1}\index{\paramsty{#1}}} % link to documentation (requires hyperref package)
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin/g/data3/hh5/tmp/cosima/#1/*/ice/cice_in.nml}%
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin/g/data3/hh5/tmp/cosima/#1/*/ice/input_ice.nml}%
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin/g/data3/hh5/tmp/cosima/#1/*/ice/input_ice_monin.nml}%
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin/g/data3/hh5/tmp/cosima/#1/*/ice/input_ice_gfdl.nml}%
%%\renewcommand{\nmllink}[2]{\href{https://github.com/COSIMA/matm/search?q=#2}{#1}\index{\paramsty{#1}}} % link to documentation (requires hyperref package)
%\doscript{/Users/andy/anaconda/bin/python3 /Users/andy/bin/nmltab.py --format latex -dp raijin/g/data3/hh5/tmp/cosima/#1/*/atmosphere/input_atm.nml}%
%}
\title{A technical description of ACCESS-OM2, The Consortium of Ocean-Sea Ice Modelling in Australia's global ocean and sea ice model}
\author{
Andrew Kiss, Andy Hogg, Kial Stewart, Adele Morrison, Aidan Heerdegen (ANU);\\
Nicholas Hannah (Double Precision); Marshall Ward (NCI);\\
Paul Spence, Matthew England, Ryan Holmes, Alfonso Acosta Goncalves (UNSW); \\
Russell Fiedler, Simon Marsland
%, Peter Oke, Siobhan O'Farrell, \\
%Christopher Chapman %, Oc\'{e}ane Richet
(CSIRO); \\
%Maxim Nikurashin,
Fabio Dias, Abhishek Savita (UTas);\\
Petra Heil (AAD \& ACE CRC, UTas); \\
%Gary Brassington %, Helen Beggs, Justin Freeman
%(BoM);\\
Fanghua Wu (Beijing Climate Center); \\
Stephen Griffies (GFDL);
James Munroe (Memorial U.\ Newfoundland)\\
%Andrew Roberts (Naval Postgraduate School)\\ % or (LANL)\\
\TODO{consolidate author list and add anyone who's missing (order is arbitrary at this stage)}}
\date{\textsf{
\ifthenelse{\boolean{overleaf}}{\textbf{\textcolor{red}{Set `overleaf' boolean to `false' in preamble to see figures (unless you're using Overleaf).\\}}}{}
The latest version of this document is available from\\
GitHub: \url{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report}\\
%and Overleaf: \url{https://www.overleaf.com/11449164wmwcrxynvgpx} (to use Overleaf with git, see \url{https://www.overleaf.com/blog/195-new-collaborate-online-and-offline-with-overleaf-and-git-beta}; note that this feature may be shut down in the 4th quarter of 2018: \url{https://www.overleaf.com/help/343}).\\[1ex]
%Do we want to use a private GitHub repo? see \url{https://help.github.com/articles/applying-for-an-academic-research-discount/}\\[1ex] % https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/issues/4
\hfill{\footnotesize This version: typeset \today\ \DTMcurrenttime\ \DTMcurrentzone \\
\ifthenelse{\boolean{gitinfo}}{%
\hfill Last commit%
\ifthenelse{\equal{\gitDirty}{}}{:}{ (\emph{didn't commit all tracked changes}):}
git hash:
\href{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/commit/\gitAbbrevHash}{\gitAbbrevHash}
%\gitAbbrevHash\
\gitAuthorIsoDate, \\\hfill committed to branch ``\gitBranch '' by \gitAuthorName\\
\ifthenelse{\equal{\gitRoff}{}}{}{\hfill \gitRoff\ commit(s) since release \gitRel \\}
%\gitDirty\
%committed by \gitCommitterName , \gitCommitterIsoDate\ \\
\hfill\textbf{NB: git hash does not reflect any uncommitted changes to this document.}\\
%\hfill\textbf{\textcolor{red}{Set `gitinfo' boolean to `false' in preamble before pushing to Overleaf.}}
}
{\hfill Set `gitinfo' boolean to `true' in preamble to show git version information (doesn't work in Overleaf; you may also need to run setup.sh).
}
%\TODO{automatically warn if there are uncommitted changes - eg by \url{https://www.ctan.org/pkg/latexgit}}
%\FIXME{is there any way include the pdf in the git repo and also have it show an up-to-date git hash?? --- see p12 of gitinfo2 documentation}
}}}
\begin{document}
\maketitle
\note{%
%\raggedright{
\vspace{10ex}
\textbf{CONTRIBUTORS PLEASE NOTE:}\\
{\small
\begin{itemize}
\item please sign up with GitHub and click ``watch'' on \url{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report} to be kept informed of discussions
\item to discuss aspects of the paper, please post an issue at \url{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report/issues} instead of using email.
You can tag relevant parts of the .tex file with $\backslash$ISSUE\{num\} (where ``num'' is the issue number) to link to the issue page
(change tag to $\backslash$CISSUE\{num\} if the issue is closed, so it is easily changed back if the issue is reopened).
\item note contributors for sections in the .tex file with $\backslash$CONTRIBUTORS\{\ldots\}
\item add ``to do'' items to the .tex file with $\backslash$TODO\{\ldots\}
\item note errors and problems with $\backslash$FIXME\{\ldots\} in the .tex file
\item to make git diffs easier, please try to write each sentence in the .tex file on a separate line
%\item PDF is preferred for figures (especially line plots), otherwise PNG but not JPG.
%We would like all figures to be generated by a Jupyter notebook in the ``figures`` directory to facilitate editing and updating.
%Each notebook should be in a separate subdirectory, and all its output figures should be saved in that subdirectory so we can easily tell which script generated each plot.
%%Copy the ``common plot-saving code`` section from ``Template.ipynb`` to use in your notebooks.
%For latex compatibility, don't use spaces in your Jupyter notebook filename, directory name, or output image filenames.
%You'll also need to download the COSIMA Cookbook from \url{https://github.com/COSIMA/cosima-cookbook}.
%Notebooks are viewable at \url{http://nbviewer.jupyter.org/github/COSIMA/ACCESS-OM2-1-025-010deg-report/tree/master/figures/}.
%%See \url{https://github.com/aekiss/cosima-cookbook} for how to get git diff to work nicely with Jupyter notebooks.
\item use a bare number (no leading v) if you do git tags (for compatibility with the gitinfo2 package used here)
\item see \url{https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report} for how to add or edit figures
\end{itemize}
}
%}
}
\vfill
\begin{center}
\qrcode[height=0.1\textwidth]{https://cosima.org.au}\\
\href{https://cosima.org.au}{\textsf{\textbf{cosima.org.au}}}
\end{center}
\newpage
\tableofcontents
\listoffigures
\listoftables
\newpage
%\setlength{\parindent}{10ex} % doesn't work!
\setlength{\parskip}{0.5em}
\section{Purpose of this document}
This document serves two purposes:
\begin{enumerate}
\item This is a technical report to document the configuration and performance of the ACCESS-OM2 suite of models at 1$^\circ$, 0.25$^\circ$ and 0.1$^\circ$ horizontal resolution (\url{https://cosima.org.au/index.php/models/}), intended to be a resource for the user community (e.g. COSIMA) and readily updated. This approach was partly inspired by \citet{Griffies2015a}.
\item It forms the basis of one or more journal papers to announce and assess the performance of these models, e.g.\ \citet{KissETAL2020a}.
%\TODO{decide on a suitable journal.}
%\begin{itemize}
%\item JAMES? \url{http://agupubs.onlinelibrary.wiley.com/hub/journal/10.1002/(ISSN)1942-2466/} - probably not
%\item Ocean Modelling? - probably not
%\end{itemize}
\end{enumerate}
\TODO{Auto-update figures by programatically running COSIMA notebooks}, so you could have a jenkins job or somesuch checking the COSIMA tech paper notebooks are all up to date and working correctly
\url{http://tritemio.github.io/smbits/2016/01/02/execute-notebooks/} and \url{http://nbconvert.readthedocs.io/en/latest/execute_api.html}
\TODO{copy things from Nic's talk \url{https://cosima.org.au/wp-content/uploads/2018/06/COSIMA2018-Hannah.pdf}, Marshall's COSIMA 2018 workshop talk}
% done: Bluelink talk 2018, ARCCSS 2017 workshop poster, AMOS2018 talk, COSIMA 2018 workshop
\section{Introduction}
This technical report documents the ACCESS-OM2 ocean-sea ice model configurations at nominal horizontal resolutions of $1^\circ$, $0.25^\circ$ and $0.1^\circ$ developed by the Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA, \url{https://cosima.org.au}).
COSIMA is both a collaborative consortium within Australia's ocean and sea ice modelling community that integrates capability from different groups, and an ARC Linkage Project (involving the Australian National University, the University of New South Wales, the University of Tasmania, the Bureau of Meteorology, CSIRO and the Australian Antarctic Division) to develop the ACCESS-OM2 model suite described here, intended for nationwide use by Australia's ocean and sea ice modelling community, and to be incorporated into future versions of the Bluelink ocean reanalysis and forecasting system and the ACCESS coupled climate model.
The model configuration suite is designed to be accessible, well-documented and straightforward for new users to set up, run and analyse.
Model development is public (\url{https://github.com/COSIMA/access-om2}) and all model code, configuration files and inputs are available to download and ready to run on NCI's Gadi supercomputer.
Model run configurations are also tracked with git, with input files and executables tagged with git hashes for reproducibility.
Output from all significant runs will be published on the NCI data repository, and the COSIMA Cookbook (\url{https://github.com/COSIMA/cosima-cookbook}) provides Python analysis tools to handle the large data volumes produced by the high-resolution runs.
\section{Model Configuration}
\CONTRIBUTORS{Andrew Kiss to coordinate}
\TODO{incorporate things from \url{https://github.com/COSIMA/access-om2/wiki/System-description}}
\subsection{Overview}
The ACCESS-OM2 model suite is described by \citet{KissETAL2020a}; additional technical details are provided here.
Model configurations at three horizontal resolutions have been developed, named ACCESS-OM2 (nominally 1$^\circ$ horizontal resolution), ACCESS-OM2-025 (nominally 0.25$^\circ$) and ACCESS-OM2-01 (nominally 0.1$^\circ$).
The suite of three resolutions is also collectively referred to as ACCESS-OM2.
Configurations (e.g.\ run parameters and forcing) are as consistent as possible across the three resolutions (see Table~\ref{T:configs} and Appendix~\ref{S:namelists}) to facilitate studies of resolution dependence and sub-gridscale parameterisations.
The coarser models served as testbeds for developing correct configurations at higher resolutions, and are suitable for long experiments covering climatological timescales of hundreds of years, but are not eddy-resolving.
They are intended for incorporation into future versions of the ACCESS-CM global coupled climate model.
In contrast, the ACCESS-OM2-01 configuration resolves the first baroclinic deformation radius away from shelves and equatorward of about 50$^\circ$ \citep{Hallberg2013a}, and therefore resolves the mesoscale in most of the world ocean. It is suitable for runs of several decades and is intended to form the basis of the next generation of the Bluelink operational ocean forecasting system.
ACCESS-OM2 consists of two-way coupled ocean and sea ice models driven by a prescribed atmosphere (see Figure~\ref{F:coupling}).
The model source code is hosted at \url{https://github.com/COSIMA/access-om2}.
The ocean model component is the Modular Ocean Model (MOM) version 5.1 from the Geophysical Fluid Dynamics Laboratory (\url{https://mom-ocean.github.io}).
The sea ice component (\url{https://github.com/COSIMA/cice5/}) is a fork from the Los Alamos sea ice model (CICE) version 5.1.2 from Los Alamos National Laboratories (\url{https://github.com/CICE-Consortium/CICE-svn-trunk/tree/cice-5.1.2}) which we keep up to date with \url{https://github.com/CICE-Consortium/CICE-svn-trunk}.
\TODO{cite CICE doi and let CICE consortium know of publications: \url{http://cice-consortium-cice.readthedocs.io/en/master/intro/citing.html}}
These components are forced by prescribed atmospheric conditions taken from the 55-year Japanese Reanalysis for driving oceans \citep[JRA55-do,][]{TsujinoETAL2018a} via YATM (\url{https://github.com/COSIMA/libaccessom2/}).
The model components are coupled together via Ocean Atmosphere Sea Ice Soil (OASIS3-MCT) version 2.0 from CERFACS and CNRS, France (\url{https://portal.enes.org/oasis}).
The exact source code and inputs used for the experiments discussed here are listed in Table~\ref{T:configs}.
The following subsections provide further details on these model components.
\begin{figure}
\begin{center}
% \begin{tikzpicture}[->,>=stealth,thick]
%
%% \node[state, text width=30ex] (ATM)
% \node[state] (ATM)
% {\begin{tabular}{c}
% \textbf{Prescribed atmosphere}\\
% JRA55-do via YATM
% \end{tabular}};
%
% \node[state,
%% text width=30ex, % max text width
% below of=ATM,
% node distance=23ex,
% anchor=center] (ICE)
% {%
% \begin{tabular}{c}
% \textbf{Sea ice}\\
% CICE5.1
% \end{tabular}
% };
%
% \node[state,
%% text width=30ex,
% below of=ICE,
% node distance=35ex,
% anchor=center
% ] (OCEAN)
% {%
% \begin{tabular}{c}
% \textbf{Ocean}\\
% MOM5.1
% \end{tabular}
% };
%
% \path
% (ATM) edge[line width=.5ex] node[anchor=south,right]
% {
% \begin{tabular}{l}
% downward shortwave \& longwave radiation\\
% rainfall, snowfall \& runoff\\
% surface pressure\\
% 10\,m air temperature \& humidity\\ % NB: namcouple comment is out of date - TsujinoETAL2018a state this is 10m (rather than 2m)
% 10\,m wind vector
% \end{tabular}
% }
% (ICE)
% (ICE) edge[bend left=20, line width=.5ex] node[anchor=left,right]
% {
% \begin{tabular}{l}
% ocean surface stress vector\\
% rainfall, snowfall \& runoff\\
% ice melting and formation water fluxes\\
% salt flux, net heat flux\\
% shortwave flux penetrating ice\\
% downward longwave flux\\
% latent and sensible heat fluxes\\
% ice concentration\\
% \textcolor{gray}{surface pressure}
% \end{tabular}
% }
% (OCEAN)
% (OCEAN) edge[bend left=20, line width=.5ex] node[anchor=left,left]
% {
% \begin{tabular}{r}
% sea surface temperature\\
% sea surface salinity\\
% sea surface velocity vector\\
% sea surface slope vector\\
% frazil ice formation energy
% \end{tabular}
% }
% (ICE)
% ;
%
% \end{tikzpicture}
{\footnotesize
\begin{tikzpicture}[->,>=stealth,thick]
% \node[state, text width=30ex] (ATM)
\node[state,
text width=0.8\textwidth, % max text width
fill=lightblue
] (ATM)
{\begin{tabular}{c}
\textbf{Prescribed atmosphere:} JRA55-do %(Tsujino et al., 2018)
via YATM\\
{\scriptsize1958--2018, 3-hourly, 0.5625$^\circ$ resolution}\\
% {\scriptsize Climatological Antarctic runoff (Depoorter et al., 2013) at ice shelf edge}
\end{tabular}};
\node[state,
text width=0.8\textwidth, % max text width
fill=lightblue,
below of=ATM,
node distance=20ex, %15ex,
anchor=center] (ICE)
{%
\begin{tabular}{c}
\textbf{Global sea ice model:} CICE 5.1.2\\
{\scriptsize $1^\circ$, $0.25^\circ$ or $0.1^\circ$ tripolar grid; 4 ice layers + 1 snow; EVP; 5 thickness categories}
\end{tabular}
};
\node[state,
text width=0.8\textwidth, % max text width
fill=lightblue,
below of=ICE,
node distance=28ex,
anchor=center
] (OCEAN)
{%
\begin{tabular}{c}
\textbf{Global ocean model:} MOM 5.1\\
{\scriptsize Same horizontal grid as CICE; 50 or 75 $z^*$ vertical levels}\\
% {\scriptsize \textit{No ice shelf cavities, icebergs, distributed iceberg freshwater flux, tides, or waves (yet!)}}%, dynamic ice shelves
\end{tabular}
};
\path
% (ATM) edge[line width=0ex] node[anchor=south,left]
% {
% \begin{tabular}{r}
% downward shortwave \& longwave radiation\\
% rainfall, snowfall, runoff, surface pressure\\
%% 10\,m air temperature \& humidity\\ % NB: namcouple comment is out of date - TsujinoETAL2018a state this is 10m (rather than 2m)
%% 10\,m wind vector
% \end{tabular}
% }
% (ICE)
(ATM) edge[line width=2ex] node[anchor=south,right]
{
\begin{tabular}{l}
downward shortwave \& longwave radiation\\
rainfall, snowfall \& runoff\\
surface pressure\\
10\,m air temperature \& humidity\\ % NB: namcouple comment is out of date - TsujinoETAL2018a state this is 10m (rather than 2m)
10\,m wind vector
\end{tabular}
}
(ICE)
(ICE) edge[bend left=20, red, line width=1ex] node[anchor=left,right]
{
\begin{tabular}{l}
ocean surface stress\\
rainfall, snowfall \& runoff\\
ice melting and formation water fluxes\\
salt flux, net heat flux\\
shortwave flux penetrating ice\\
downward longwave flux\\
latent and sensible heat fluxes\\
% surface pressure\\ % passed to MOM but not used
ice concentration
\end{tabular}
}
(OCEAN)
(OCEAN) edge[bend left=20, blue, line width=1ex] node[anchor=left,left]
{
\begin{tabular}{r}
sea surface temperature\\
sea surface salinity\\
sea surface velocity vector\\
% sea surface slope vector\\ % passed to CICE but not used: use_ocnslope=false
frazil ice formation energy
\end{tabular}
}
(ICE)
(ICE) edge[bend left=0, white, line width=0ex] node[sloped]
{\textcolor{black}{\textbf{OASIS3-MCT-2}}}
(OCEAN)
(ATM) edge[bend left=0, black, line width=0ex] node[sloped]
{\textcolor{white}{{\tiny \textbf{OASIS3-MCT-2}}}}
(ICE)
;
\end{tikzpicture}
}
\end{center}
\caption[Coupling between model components.]{
Coupling between model components by OASIS3-MCT-2 as specified in the \param{namcouple} file (which matches the atmosphere-CICE coupling fields specified in \paramsty{atmosphere/}\param{forcing.json} and the CICE-MOM coupling fields specified in \mom{mom_oasis3_interface_nml} in \paramsty{ocean/}\param{input.nml}).
Notice that MOM receives atmospheric forcing via CICE rather than directly from YATM (CICE has the same global domain as MOM).
Surface pressure is used in the surface fluxes routines in CICE to calculate the saturated vapour pressure.
It is also passed from CICE to MOM, but we don't show it here because MOM ignores it in the current configuration since \mom{use_full_patm_for_sea_level}=false and \mom{max_ice_thickness}=0. % https://arccss.slack.com/archives/C9Q7Y1400/p1549237452412700
Similarly, the sea surface slope vector is passed from MOM to CICE but is unused (\cice{use_ocnslope} is false, so the sea surface slope is instead calculated from the sea surface velocity vector, assuming geostrophy) so is not shown here.
Also see \url{https://github.com/COSIMA/access-om2/wiki/System-description}.
}
\label{F:coupling}
\end{figure}
\begin{table}[tbp]
% update this with
% cd namelists; python make_tables.py
\input{namelists/configurations.tex}
\caption[Sources and paths to executables, inputs and outputs.]
{Sources and NCI paths to executables, inputs and outputs for the experiments in this document.
These are based on the final run of each experiment; consult run summary spreadsheets for information on any changes within these experiments and details on computational resource use.
Namelist changes within runs are tabulated in Appendix~\ref{S:namelist-diffs}.
Note that the last cycle of \param{1deg_jra55v13_iaf_spinup1_B1} was repeated with extra diagnostics in \param{1deg_jra55v13_iaf_spinup1_B1_lastcycle}.
The final source code and run configurations used here are at \url{https://doi.org/10.5281/zenodo.2653246} (or equivalently at \url{https://github.com/COSIMA/access-om2/releases/tag/GMD2019}).
The individual final run configurations are at
\url{https://github.com/COSIMA/1deg_jra55_iaf/releases/tag/1.0},
\url{https://github.com/COSIMA/025deg_jra55_iaf/releases/tag/1.0} and
\url{https://github.com/COSIMA/01deg_jra55_iaf/releases/tag/1.0}
}
\label{T:configs}
\end{table}
\pagebreak
\subsection{MOM configurations}
MOM parameters for the three model resolutions are tabulated in Appendix~\ref{S:mom-namelist}.
We discuss the choices of key parameters here.
The primary MOM5 reference is \citet{Griffies2012a}.
\citet{GriffiesHarrisonPacanowskiRosati2008a} provides many useful technical details (despite being for MOM4).
The ocean formulation is hydrostatic and Boussinesq (volume-conserving), with a free surface and $z^*$ vertical coordinate.
The Boussinesq reference density is \mom{rho0} = \SI{1035.0}{kg m^{-3}}, the default value.
%Note hazards of tuning? \citet{DommengetRezny2018a}
%see /Users/andy/Documents/COSIMA/github/aekiss/namelist-check/namelist-meeting-2018-04-06/Fabio2018_Namelist_meeting.pdf
\subsubsection{Vertical grid}
The configurations use a $z^*$ vertical coordinate \citep[\mom{vertical_coordinate}='zstar'; ][section~5.1.4]{Griffies2012a}, with partial cells (see section~\ref{S:bathymetry}).
The vertical grid is staggered, with vertical velocity points offset from tracer and horizontal velocity points.
Vertical grid parameters are summarised in Tables~\ref{T:vgrid} and~\ref{T:access-om-ofam3-access-om2} and Figure~\ref{F:vgrid}.
The vertical grids are specified in the input file \param{ocean_vgrid.nc} for each configuration.
Vertical grid data is also available in the \param{ocean.nc} output files (see variables \param{st_ocean}, \param{st_edges_ocean}, \param{sw_ocean}, \param{sw_edges_ocean}).
%ACCESS-OM2 uses the same vertical grid as the ACCESS-CM2 coupled climate model, with 50 levels and 10.0\,m spacing in the top 200\,m, then increasing to 334.7\,m by the bottom at 6000\,m. % See Simon Marsland email 2018-12-03: ncdump -v st_edges_ocean /short/p66/dhb599/archive/bb039/history/ocn/ocean_month.nc-06751231 matches ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2/1deg_jra55v13_iaf_spinup1_A/output001/ocean/ocean.nc
%This is consistent past ACCESS-OM configurations, to maintain a baseline experiment against past tunings, et cetera.
%This grid differs from KDS50, GFDL50 and OFAM51 as defined by \citet{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}.
%Other configurations (not discussed here) use a modified KDS50 vertical grid for consistency with ACCESS-OM2-025.\TODO{check}
%\TODO{update for Abhi's new KDS50 run}
The vertical grids are optimised for resolving baroclinic modes \citep{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}.
The vertical grids in ACCESS-OM2 and ACCESS-OM2-025 are slightly modified versions of KDS50 \citep[][table~1]{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}, with 50 levels and 2.3\,m spacing at the surface, increasing smoothly to 219.6\,m by the bottom at 5363.5\,m.
%See email to Andy 1 Aug 2018 - IAF uses KDS50, whereas the RYF uses GFDL50? - no, now they are both KDS50
The vertical grid in ACCESS-OM2-01 is a slightly modified version of KDS75 \citep[][table~1]{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}, with 75 levels and 1.1\,m spacing at the surface, increasing smoothly to 198.4\,m by the bottom at 5808.7\,m.
The 75 level vertical grid is finer than OFAM3 at all depths other than 100 -- 260\,m and finer at all depths than GFDL50 and NEMO46 \citep[as defined by][]{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}.
\begin{table}
\newcolumntype{R}{>{\raggedleft\arraybackslash}p{12ex}}
\begin{tabularx}{\linewidth}{XRRRRR}
%\hline
%Model & $n$ & $\Delta z_\text{min}$ (m) & $\Delta z_\text{max}$ (m) & $H_\text{max}$ (m) \\
%\hline\endfirsthead
\hline
Model & $n$ & $\Delta z_\text{min}$ (m) & $\Delta z_\text{median}$ (m) & $\Delta z_\text{max}$ (m) & $H_\text{max}$ (m) \\
\hline%\endhead
% from figures/grid/grid.ipynb
ACCESS-OM2 & 50 & 2.3 & 93.0 & 219.6 & 5363.5 \\
ACCESS-OM2-025 & 50 & 2.3 & 93.0 & 219.6 & 5363.5 \\
ACCESS-OM2-01 & 75 & 1.1 & 42.6 & 198.4 & 5808.7 \\
%ACCESS-OM2 & 50 & 10.0 & 334.7 & 6000.0\\ % ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2/1deg_jra55v13_iaf_spinup1_A/output001/ocean/ocean.nc
%ACCESS-OM2-025 & 50 & 2.3 & 219.6 & 5363.5\\ % ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2-025/025deg_jra55v13_iaf_gmredi/output001/ocean/ocean.nc
%ACCESS-OM2-01 & 75 & 1.1 & 198.4 & 5808.7\\ % ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2-01/01deg_jra55v13_iaf/output001/ocean/ocean.nc
\hline
\end{tabularx}
\caption[Vertical grid parameters.]{Vertical grid parameters: $n$ levels, with spacing of $\Delta z_\text{min}$ and $\Delta z_\text{max}$ at the surface and maximum depth $H_\text{max}$, respectively, and median spacing $\Delta z_\text{median}$.
Figure~\ref{F:vgrid} shows the distribution with depth.
\TODO{check that I'm correctly using the notation in \citet{StewartHoggGriffiesHeerdegenWardSpenceEngland2017a}}}
\label{T:vgrid}
%ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2/1deg_jra55v13_iaf_spinup1_A/output001/ocean/ocean.nc
% st_edges_ocean = 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130,
% 140, 150, 160, 170, 180, 190, 200, 210.923370361328, 229.097885131836,
% 261.064880371094, 312.015594482422, 385.282989501953, 482.015594482422,
% 601.064880371094, 739.097900390625, 890.923400878906, 1050,
% 1210.26977539062, 1372.68737792969, 1539.34790039062, 1712.24194335938,
% 1893.20642089844, 2083.87963867188, 2285.6611328125, 2499.67626953125,
% 2726.74975585938, 2967.38452148438, 3221.74975585938, 3489.67626953125,
% 3770.6611328125, 4063.87963867188, 4368.20654296875, 4682.24169921875,
% 5004.34814453125, 5332.6875, 5665.26953125, 6000 ;
%
%ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2-025/025deg_jra55v13_iaf_gmredi/output001/ocean/ocean.nc
% st_edges_ocean = 0, 2.30349978365172, 4.99384845577232, 8.13598848757999,
% 11.8057499021658, 16.0916668453325, 21.0970920758539, 26.9426551592365,
% 33.7691153258824, 41.7406645399246, 51.0487393569758, 61.9164000417828,
% 74.603329610196, 89.4114897901705, 106.691439004441, 126.849259570512,
% 150.353942802359, 177.744921530279, 209.639191756704, 246.737097161842,
% 289.82533120907, 339.775032772388, 397.532062043262, 464.095825684934,
% 540.482760486469, 627.671440120654, 726.529065262166, 837.724379025891,
% 961.639174086361, 1098.29705126241, 1247.32969180931, 1407.99436722564,
% 1579.24254229824, 1759.82425163261, 1948.40398485997, 2143.66476790834,
% 2344.38554694311, 2549.48748756835, 2758.05275811776, 2969.32320714254,
% 3182.68676319661, 3397.65794088943, 3613.85684298457, 3830.98925454079,
% 4048.82910238828, 4267.20370512379, 4485.9817563722, 4705.06374998657,
% 4924.37447144454, 5143.8571772085, 5363.46912067625 ;
%
%ncdump -v st_edges_ocean /g/data/hh5/tmp/cosima/access-om2-01/01deg_jra55v13_iaf/output001/ocean/ocean.nc
% st_edges_ocean = 0, 1.08256153078322, 2.27890782887965, 3.60099746894928,
% 5.06204550134973, 6.67665534675832, 8.46096449334211, 10.4328054259553,
% 12.6118833596512, 15.0199725050152, 17.6811327608555, 20.6219489107565,
% 23.8717945936209, 27.4631235237192, 31.4317906511912, 35.8174061765097,
% 40.6637255570393, 46.0190788650439, 51.9368430613043, 58.4759609260126,
% 65.7015105143391, 73.68532905635, 82.506695148913, 92.2530728553569,
% 103.020920848004, 114.916568916192, 128.057162887489, 142.571677097719,
% 158.601990806908, 176.304021080078, 195.848899302919, 217.424171265553,
% 241.234991113943, 267.505266772175, 296.478698137217, 328.419628890149,
% 363.61360754513, 402.367523253464, 445.009148236631, 491.885882571281,
% 543.362462501468, 599.817368143857, 661.637658178801, 729.211984813624,
% 802.921613605928, 883.129411924441, 970.166985092353, 1064.32043027562,
% 1165.81551969179, 1274.80347061364, 1391.34871454206, 1515.42016508739,
% 1646.88730976903, 1785.52199214957, 1931.00606633608, 2082.94432975782,
% 2240.88143515938, 2404.32103311377, 2572.74526934082, 2745.63295762547,
% 2922.47517863585, 3102.78758377675, 3286.11918940845, 3472.05785157725,
% 3660.23287324829, 3850.31532207019, 4042.01665846308, 4235.08622153375,
% 4429.3080316501, 4624.49726832474, 4820.49668500234, 5017.17313981398,
% 5214.41435431341, 5412.12596212308, 5610.22887322482, 5808.6569552267 ;
\end{table}
\begin{figure}[htp]
\includegraphics[width=\textwidth]{figures/grid/vgrid.pdf}
\caption[Vertical grid spacing for the ACCESS-OM2 simulations.]{Vertical grid spacing for the ACCESS-OM2 simulations.
ACCESS-OM2 and ACCESS-OM2-025 use the same vertical grid.
Left: the full depth range.
Right: the upper ocean.
The horizontal lines show the top and bottom of T cells.
Table~\ref{F:vgrid} provides further details.}
\label{F:vgrid}
\end{figure}
\pagebreak % try to avoid overrun
\subsubsection{Horizontal grid}\label{S:horizgrid}
% ncdump -h /short/v45/aek156/access-om2/input/mom_1deg/ocean_hgrid.nc
% ncdump -h /short/v45/aek156/access-om2/input/mom_025deg/ocean_hgrid.nc
% ncdump -h /short/v45/aek156/access-om2/input/mom_01deg/ocean_hgrid.nc
Grid parameters are summarised in Tables~\ref{T:hgrid} and~\ref{T:access-om-ofam3-access-om2}.
The horizontal grids are specified in the file \param{ocean_hgrid.nc} for each configuration.
In the horizontal, MOM and CICE use the same orthogonal curvilinear Arakawa B-grid with velocity components co-located at the northeast corner of tracer cells.
Model configurations have been developed with zonal resolutions of 1$^\circ$, 0.25$^\circ$ and 0.1$^\circ$ south of 65$^\circ$N.
Figures~\ref{F:horizgrid}, \ref{F:horizgridNH} and~\ref{F:horizgridscatterhist} and Table~\ref{T:hgrid} show the grid spacing at the three resolutions.
Globally, the median cell size is 92\,km, 18.1\,km and 7.2\,km, respectively, at 1$^\circ$, 0.25$^\circ$ and 0.1$^\circ$ resolution.
Although the CICE model is global, the sea ice is mostly confined to latitudes higher than 60$^\circ$, where most cell dimensions are finer than 47.4\,km, 11.3\,km and 4.5\,km, respectively, at the three resolutions.
\begin{table}
\newcolumntype{R}{>{\raggedleft\arraybackslash}p{5.3ex}}
\begin{tabularx}{\linewidth}{|X|RRR|RRR|RRR|}
\hline
&\multicolumn{3}{c|}{Global} & \multicolumn{3}{c|}{North of 60$^\circ$N} & \multicolumn{3}{c|}{South of 60$^\circ$S}\\
& {\small min} & {\small median} & {\small max} & {\small min} & {\small median} & {\small max} & {\small min} & {\small median} & {\small max}\\
\hline
% from figures/grid/grid.ipynb:
{\small ACCESS-OM2 dx} & 23.8 & 91.7 & 111.2 & 24.7 & 32.7 & 54.8 & 23.8 & 43.0 & 54.6 \\
{\small ACCESS-OM2 dy} & 15.4 & 51.4 & 111.2 & 15.4 & 47.4 & 56.6 & 27.5 & 57.5 & 76.1 \\
{\small ACCESS-OM2 dx/dy} & 0.49 & 0.92 & 3.04 & 0.49 & 0.74 & 3.04 & 0.72 & 0.75 & 0.91 \\
\hline
{\small ACCESS-OM2-025 dx} & 6.0 & 18.1 & 27.8 & 6.2 & 8.1 & 13.9 & 6.0 & 11.3 & 13.9 \\
{\small ACCESS-OM2-025 dy} & 6.0 & 18.1 & 27.8 & 6.0 & 11.1 & 13.9 & 11.7 & 11.7 & 13.9 \\
{\small ACCESS-OM2-025 dx/dy} & 0.51 & 1.0 & 1.82 & 0.53 & 0.8 & 1.82 & 0.51 & 0.96 & 1.0 \\
\hline
{\small ACCESS-OM2-01 dx} & 2.19 & 7.16 & 11.12 & 2.47 & 3.29 & 5.55 & 2.19 & 4.52 & 5.55 \\
{\small ACCESS-OM2-01 dy} & 0.88 & 7.16 & 11.12 & 0.88 & 4.39 & 5.55 & 4.7 & 4.7 & 5.55 \\
{\small ACCESS-OM2-01 dx/dy} & 0.47 & 1.0 & 5.1 & 0.52 & 0.81 & 5.1 & 0.47 & 0.96 & 1.0 \\
\hline
\end{tabularx}
\caption[Statistics of ocean T-cell horizontal dimensions and aspect ratios.]{Statistics of ocean T-cell horizontal dimensions (in km) and aspect ratios; global distributions are shown in Figure~\ref{F:horizgridscatterhist}.}\label{T:hgrid}
\end{table}
The horizontal meshes are $360\times300$, $1440\times1080$ and $3600\times2700$ at 1$^\circ$, 0.25$^\circ$ and 0.1$^\circ$, respectively.
In all cases the grid covers the global ocean, extending from the North Pole to the Antarctic shelf edge but omitting the Antarctic landmass.
The T-grid extends to
% these values are from yt_ocean
77.8766233766234$^\circ$S at 1$^\circ$,
81.0770008338366$^\circ$S at 0.25$^\circ$, and
81.1297513555451$^\circ$S at 0.1$^\circ$.
The ocean extends to the southernmost cell at 1$^\circ$, but the other resolutions have a land mask covering the southernmost cells, giving southernmost ocean T-cell latitudes of
%77.87663$^\circ$S at 1$^\circ$,
78.22584$^\circ$S at 0.25$^\circ$, and
79.58801$^\circ$S at 0.1$^\circ$.
% from geolat_t in ocean.grid.nc:
% -77.87663 in /g/data/hh5/tmp/cosima/access-om2/1deg_jra55v13_iaf_spinup1_B1/output059/ocean/ocean_grid.nc
% -78.22584 in /g/data/hh5/tmp/cosima/access-om2-025/025deg_jra55v13_iaf_gmredi6/output153/ocean/ocean_grid.nc
% -79.58801 in /g/data/hh5/tmp/cosima/access-om2-01/01deg_jra55v13_iaf/output197/ocean/ocean_grid.nc
The longitude range is $-280^\circ$E to $+80^\circ$E, placing the join in the middle of the Indian Ocean.
In all configurations the grid is tripolar \citep{Murray1996a} north of 65$^\circ$N (so the grid directions are not zonal and meridional in this region), with the tripoles placed on land at 65$^\circ$N, $-100^\circ$E and 65$^\circ$N, 80$^\circ$E. % see grid.ipynb
In the 0.25$^\circ$ and 0.1$^\circ$ configurations the grid is Mercator (i.e.\ the meridional spacing scales as the cosine of latitude) between 65$^\circ$N and 65$^\circ$S; south of 65$^\circ$S, the meridional grid spacing is held at the same value (in km) as at 65$^\circ$S.
The meridional variation of meridional grid spacing is more complicated in the 1$^\circ$ model (Figure~\ref{F:horizgridscatterhist}), and incorporates a refinement to 1/3$^\circ$ (of latitude) within 10$^\circ$ of the Equator \citep{BiMarslandUotilaOFarrellFiedlerSullivanGriffiesZhouHirst2013a, BiMarsland2010a}.
The 0.1$^\circ$ configuration had a misaligned CICE grid \WARNING in both the IAF run and the preceding RYF spinup --- see \url{https://github.com/COSIMA/access-om2/issues/190}.
%\url{https://github.com/mom-ocean/MOM5/blob/master/doc/web/user_guide.md}: ``The grid_spec file [/short/v45/aek156/access-om2/control/01deg_jra55_ryf] contains the following horizontal grid information: geographic location of T, E, C and N-cell (Tracer, East, Corner, and North cells), half and full cell lengths (in meters), rotation information between logical (i.e., grid oriented) and geographic east of cell. The complete description of the horizontal grid and namelist option is available in hgrid''
\TODO{maps of grid spacing divided by local 1st baroclinic Rossby radius from CheltonDeSzoekeSchlaxEl-NaggarSiwertz1998a \url{http://www-po.coas.oregonstate.edu/research/po/research/rossby_radius/index.html}?}
\begin{figure}[htp]
\includegraphics[width=\textwidth]{figures/grid/grid_1deg.png}\\
\includegraphics[width=\textwidth]{figures/grid/grid_025deg.png}\\
\includegraphics[width=\textwidth]{figures/grid/grid_01deg.png}
\caption{Horizontal grid spacing for the ACCESS-OM2 simulations. The colorbar limits show the minimum and maximum values. Note the meridional refinement near the equator in the 1$^\circ$ grid.
\TODO{also plot aspect ratio? see \citet{BiMarsland2010a}}}
\label{F:horizgrid}
\end{figure}
%\begin{figure}[htp]
%\includegraphics[width=\textwidth]{figures/grid/grid_scatter_1deg.png}\\
%\includegraphics[width=\textwidth]{figures/grid/grid_scatter_025deg.png}\\
%\includegraphics[width=\textwidth]{figures/grid/grid_scatter_01deg.png}
%\caption{Latitudinal variation of ocean T-cell dimensions in the ACCESS-OM2 simulations.}
%\label{F:horizgridscatter}
%\end{figure}
%
%\begin{figure}[htp]
%\includegraphics[width=\textwidth]{figures/grid/grid_hist_1deg.pdf}\\
%\includegraphics[width=\textwidth]{figures/grid/grid_hist_025deg.pdf}\\
%\includegraphics[width=\textwidth]{figures/grid/grid_hist_01deg.pdf}
%\caption{Cumulative histograms of horizontal grid spacing for ocean cells in the ACCESS-OM2 simulations.}
%\label{F:horizgridhist}
%\end{figure}
\begin{figure}[htp]
\includegraphics[width=0.32\textwidth]{figures/grid/NH_grid_1deg.png}\hfill
\includegraphics[width=0.32\textwidth]{figures/grid/NH_grid_025deg.png}\hfill
\includegraphics[width=0.32\textwidth]{figures/grid/NH_grid_01deg.png}
\caption{Land masks and T cell y-size in the Arctic tripolar region in the three resolutions.}
\label{F:horizgridNH}
\end{figure}
\begin{figure}[htp]
\includegraphics[width=.49\textwidth]{figures/grid/grid_scatter_1deg.png}\hfill
\includegraphics[width=.49\textwidth]{figures/grid/grid_hist_1deg.pdf}\\
\includegraphics[width=.49\textwidth]{figures/grid/grid_scatter_025deg.png}\hfill
\includegraphics[width=.49\textwidth]{figures/grid/grid_hist_025deg.pdf}\\
\includegraphics[width=.49\textwidth]{figures/grid/grid_scatter_01deg.png}\hfill
\includegraphics[width=.49\textwidth]{figures/grid/grid_hist_01deg.pdf}
\caption{Latitudinal variation of ocean cell dimensions (left), and cumulative histograms of horizontal grid spacing for ocean cells (right) in the ACCESS-OM2 simulations.
Table~\ref{T:hgrid} provides further statistics.}
\label{F:horizgridscatterhist}
\end{figure}
\subsubsection{Bathymetry}\label{S:bathymetry}
\CONTRIBUTORS{Russ Fiedler}
\begin{figure}[htp]
\includegraphics[width=\textwidth]{figures/bathymetry/partialcells.png}
\caption{Scatter plots of partial cell thickness versus full cell thickness in the three configurations.
The upper and lower lines have slopes of 1 and 0.2, respectively.
For ACCESS-OM2-01 the cells are full-depth when thinner than 10\,m (i.e.\ the points fall on the upper line).}
\label{F:partialcells}
\end{figure}
Topography tools:
Various iterations of the 0.1$^\circ$ bathymetry are in
\paramsty{/g/data/hh5/tmp/cosima/bathymetry}; see
\paramsty{/g/data/hh5/tmp/cosima/bathymetry/README} and
\paramsty{/short/v45/aek156/access-om2/input/mom_01deg/README-topog.txt} and
\paramsty{/home/156/aek156/payu/01deg_jra55v13_ryf8485_spinup6/README-topog.txt}.
\param{kmt_min}: minimum number of vertical cells
The \param{topog.nc} seafloor topography (bathymetry) files were set up at each resolution with the help of \url{https://github.com/COSIMA/topogtools} and \url{https://github.com/mom-ocean/MOM5/blob/master/src/tools/make_topog/topog.c} and are read in by \url{https://github.com/mom-ocean/MOM5/blob/master/src/mom5/ocean_core/ocean_topog.F90} at runtime.
This reads \paramsty{work/ocean/INPUT/topog.nc} which points to \paramsty{/short/v45/aek156/access-om2/input/mom_01deg/topog.nc} - OR DOES IT? This in turn is the same as \paramsty{/g/data/hh5/tmp/cosima/bathymetry/topog_13_06_2018.baffin.nc}.
At $0.1^\circ$ \paramsty{/short/v45/aek156/access-om2/control/01deg_jra55_iaf/config.yaml} specifies \paramsty{/short/public/access-om2/input_38570c62/mom_01deg/topog.nc}, which is the same as \paramsty{/g/data/hh5/tmp/cosima/bathymetry/topog_13_06_2018.baffin.nc}.
At $0.25^\circ$ the topography is specified in \paramsty{/home/157/amh157/payu/025deg_jra55_iaf_gmredi/config.yaml} as \paramsty{/g/data/ua8/MOM/grids/025/topog/KDS50/}
\TODO{what's the 1 deg topog?}
\FIXME{update all this}
\param{topog.nc} defines the t-cell bathymetry \param{ht}, and is used to define \param{kmt}, the number of wet cells in each t-cell column.
The depth at u-points \param{hu} is calculated internally as the minimum of the surrounding four \param{ht} values.
Similarly, the number of wet cells in each u-cell column \param{kmu} is calculated as the minimum of the surrounding four \param{kmt} values.
The land mask in the two coarser resolutions was enlarged near the tripoles to remove small wet points, but this was not done at $0.1^\circ$ (figure~\ref{F:horizgridNH}).
Consequently the $0.1^\circ$ bathymetry retains the Gulf of Ob in Siberia and many channels in the Canadian Archipelago which are absent at coarser resolution.
There are no ice shelf cavities as these are not supported in MOM5.1.
Mention the integrity checks and scripts used to generate the data (e.g. in \paramsty{/g/data/hh5/tmp/cosima/bathymetry/tools/common/}) --- should these be made publicly available? Also \url{https://github.com/aekiss/notebooks/blob/master/non-advective.ipynb}.
%See figures/bathymetry/bathymetry.ipynb
The minimum depth is
45.11\,m (10 levels) in ACCESS-OM2,
40.36\,m (9 levels) in ACCESS-OM2-025, and
10.43\,m (7 levels) in ACCESS-OM2-01
--- see \url{}
\paragraph{1$^\circ$ and 0.25$^\circ$}
\WARNING The 1$^\circ$ and 0.25$^\circ$ topography files originate from the OCCAM model, from which they inherit a number of flaws such as anomalous `pits' on the shelves (for example excessive depth in the Gulf of Carpentaria and also the East Siberian and Chukchi seas south of Wrangel Island); see \url{https://github.com/mom-ocean/MOM5/issues/172}.
\WARNING They also have land masks that differ from each other and also from the 0.1$^\circ$ topography; see \url{https://github.com/COSIMA/access-om2/issues/158}.
%The minimum depths are 45.11\,m (10 levels) at 1$^\circ$, and 40.36\,m (9 levels) 0.25$^\circ$.
The 1$^\circ$ and 0.25$^\circ$ topography files were based on previously-generated files with the GFDL50 vertical grid and a (presumably 20\%) minimum partial cell thickness.
\WARNING When adapted to KDS50 the GFDL50 minimum cell thickness produces gaps in the thickness distribution (figure~\ref{F:partialcells}), i.e.\ the small terraces produced by the GFDL minimum partial cell thickness are inherited by the topography on the KDS50 vertical grid.
See \url{https://github.com/COSIMA/access-om2/issues/141}.
\paragraph{0.1$^\circ$}
The 0.1$^\circ$ bathymetry was generated from scratch by Russ Fiedler, and is therefore unaffected by the flaws that afflict the topography at 1$^\circ$ and 0.25$^\circ$.
It is based on GEBCO 2014 30 arcsecond gridded data % original data located at /g/data/hh5/tmp/cosima/bathymetry/gebco.nc
\FIXME{which version?} \url{http://www.gebco.net/data_and_products/gridded_bathymetry_data/gebco_30_second_grid/}
GEBCO is has 1\,m vertical resolution but this is averaged within each model grid cell, so the model topography is smoother (at least, before later processing).
The topography data used in the runs is \paramsty{/short/v45/aek156/access-om2/input/mom_01deg/}\param{topog.nc}
also \paramsty{/g/data/hh5/tmp/cosima/bathymetry/}\param{topog_latest.nc}
\FIXME{update}
Topography ends at a vertical wall at the ice shelf edge (the calving line, not the grounding line).
A narrow strip along the southern boundary of the model is all land because the latitude range of the model was chosen for consistency with the previous MOM-SIS bathymetry which stopped at the grounding line.
\TODO{plot or stats on how much model bathy differs from gebco}
plot bathymetry for the 3 resolutions -- incl difference from gebco and from 0.1deg as maps, scatter plots, histograms, and differences between the 3 resolutions, eg in Canadian archipelago
\TODO{mention main places where bathy tweaks were made -- see /g/data/hh5/tmp/cosima/bathymetry/README}
\paramsty{/g/data/hh5/tmp/cosima/bathymetry/README}: ``Enforced minimum of 7 levels (approx 10m). Excavated not filled in so land mask kept. Partial cells: Enforced thickness of max(10,0.2*dz). If partial cell were thinner than half this then the cell was removed.''
We use partial cells \citep{AdcroftHillMarshall1997a, PacanowskiGnanadesikan1998a} to obtain a more accurate representation of bottom topography.
%Partial cells in ACCESS-OM2-01:
%ncdump -h /short/v45/aek156/access-om2/input/mom_01deg/topog.nc
%yields
% depth:minimum_depth = 10.43281f ;
% depth:minimum_levels = 7 ;
% depth:min_thick = 10.f ;
% depth:min_frac = 0.2f ;
%
%depth:min_thick=10m --- so there are no partial cells until the level thickness exceeds this.
For ACCESS-OM2-01 the minimum height of partial cells is 20\% of the full cell height, or $\min(10\,\text{m}, \Delta z)$, whichever is greater (depth:min_thick=10 in \param{topog.nc}; this modification is done by \url{https://github.com/mom-ocean/MOM5/blob/master/src/tools/make_topog/topog.c#L858}).
\WARNING This means the minimum thickness is greater than 20\% of the full cell thickness if this is less than 50\,m (i.e.\ for depths shallower than 543\,m) and the cells are full-depth if they thinner than 10\,m (i.e.\ for depths shallower than 103\,m) --- see figure~\ref{F:partialcells} and \url{https://github.com/COSIMA/access-om2/issues/99}). %See figures/bathymetry/bathymetry.ipynb
This produces terraces in shallow water.
This problem is fixed in more recent versions.
\subsubsection{Tracers}
\CONTRIBUTORS{Ryan Holmes}
At all three resolutions tracers (salt, temperature and age) are advected horizontally and vertically by the multidimensional piecewise parabolic method \citep{ColellaWoodward1984a}, with a monotonicity-preserving flux limiter following \citet{SureshHuynh1997a} (\param{horizontal-advection-scheme}=\param{vertical-advection-scheme}='mdppm' and \param{ppm_hlimiter}=\param{ppm_vlimiter}=3 for temp, salt and age in \paramsty{ocean/field_table}; also see \url{https://github.com/mom-ocean/MOM5/blob/master/src/mom5/ocean_tracers/ocean_tracer_advect.F90}).
\TODO{check: is this monotonicity-preserving under all conditions? \url{https://github.com/mom-ocean/MOM5/blob/99168b44ab45f4f5b4fa2544a0c3f644f0afb666/src/mom5/ocean_tracers/ocean_tracer_advect.F90}} % emailed Steve, 24 Mar 2019
%(Huynh, 1996)\TODO{find this and cite properly}
% code has this citation but this doesn't contain a chapter by Huynh
%!<REFERENCE>
%! H.T. Huynh
%! Schemes and Constraints for advection
%! 15th Intern. Conf. on Numeric. Meth. in Fluid Mech., Springer (1997)
%!</REFERENCE>
%is it H. T. Huynh, Schemes and constraints for advection, in International Conference on Numerical Methods in Fluid Dynamics, Monterey, CA, 1996. ?
%https://www.springer.com/gp/book/9783662141151
%see https://ac.els-cdn.com/S0021999197957454/1-s2.0-S0021999197957454-main.pdf?_tid=87f51b89-5d2d-46d7-a4cf-08bf6df4274d&acdnat=1541380134_9213b4915ae345d204b79fe83ed07d08
As the $0.1^\circ$ configuration does not include a mesoscale eddy parameterization or explicit isopycnal or lateral diffusion (see section~\ref{S:subgridscalehoriz}), the suppression of large lateral tracer gradients near the grid-scale in this configuration is achieved solely though spurious numerical mixing in this tracer advection scheme.
\TODO{Reference to Holmes et al numerical mixing article/s}
\subsubsection{Sub-grid scale lateral / neutral physics}\label{S:subgridscalehoriz}
\CONTRIBUTORS{Ryan Holmes}
A sub-grid scale parameterization for mesoscale eddies is included in the $1^\circ$ and $0.25^\circ$ models (\mom{ocean_nphysics_nml} \param{use_this_module}=true), but not at $0.1^\circ$ as this resolution is considered ``eddy-resolving''.
In the two coarser configurations the \citet{Gent1990} (GM) parameterization is used to represent the down-gradient isopycnal thickness flux associated with mesoscale eddies, and the along-isopycnal eddy tracer transport is parameterised by a Redi diffusivity \citep{Redi1982}.
The namelist group \mom{ocean_nphysics_util_nml} controls these parameterisations; see \citet[][section~23.8]{Griffies2012a} for further explanation.
Note that the namelists are a bit confusing, as many ignored parameters are specified --- see \url{https://github.com/COSIMA/access-om2/issues/197}.
Their parameters are recalculated from scratch for each run, rather than being picked up from restarts (\mom{nphysics_util_zero_init}=true).
The GM parameterization is implemented as a skew diffusive flux \citep{Griffies1998}.
In common with many GFDL configurations, we use the \param{ocean_nphysicsC} formulation (\mom{use_nphysicsc}=true) which differs from the default (\mom{use_nphysicsa}) in that the skew diffusive flux calculation is based on a vector streamfunction built from a sum of baroclinic modes.
% C is described as "experimental" but no longer is.
% https://arccss.slack.com/archives/C6PP0GU9Y/p1572909972001700
% Russ Fiedler 2:12 PM 6 Nov 2019
% nphysicsC hasn't been experimental for a long, long time and nphysicsA hasn't been used in GFDL's configs for a while from what I can tell. nphysicsC is used in GFDL's ESM2M, and FLOR configurations at least. om3_core3 and the supplied MOM_SIS_TOPAZ used nphysicsB.
The associated diffusivity is depth-independent but flow-dependent (\mom{agm_closure}=true, \mom{agm_closure_baroclinic}=true), and is the product of \mom{agm_closure_scaling}, an inverse timescale, a squared length scale, and a grid scaling factor (see \url{https://github.com/mom-ocean/MOM5/blob/4d60fad0e56/src/mom5/ocean_param/neutral/ocean_nphysics_util.F90#L2860}).
The length scale (\mom{agm_closure_length}) is 50\,km at $1^\circ$ and 20\,km at $0.25^\circ$ (\mom{agm_closure_length} is used because \mom{agm_closure_baroclinic}=true --- see \url{https://github.com/mom-ocean/MOM5/blob/4d60fad0e5619fe15a630732ace4f0e3b3c6f23e/src/mom5/ocean_param/neutral/ocean_nphysics_util.F90#L2756}).
The inverse timescale is an Eady growth rate determined from the horizontal density gradient averaged between \mom{agm_closure_upper_depth}=100\,m and \mom{agm_closure_lower_depth}=2000\,m using a constant buoyancy frequency of \mom{agm_closure_buoy_freq}=\SI{0.004}{s^{-1}} (these three values are the defaults).
The Eady growth rate is subject to a limiter (\mom{agm_closure_eady_cap}) and is smoothed both vertically and horizontally (\mom{agm_closure_eady_smooth_horz}=true, \mom{agm_closure_eady_smooth_vert}=true) and vertically averaged in the mixed layer (\mom{agm_closure_eady_ave_mixed}=true).
The grid scaling (\mom{agm_closure_grid_scaling}=true) reduces the GM diffusivity in proportion to how well the numerical grid resolves the first baroclinic Rossby radius (or the equatorial Rossby radius within $\pm5^\circ$ latitude), as suggested by \citep{Hallberg2013a}.
The GM diffusivity is limited to the ranges 50--\SI{600}{m^2s^{-1}} at $1^\circ$ and 1--\SI{200}{m^2s^{-1}} at $0.25^\circ$ set by \mom{agm_closure_min} and \mom{agm_closure_max}.
It is not smoothed in space (\mom{agm_smooth_space}=false) or time (\mom{agm_smooth_time}=false).
The along-isopycnal Redi tracer diffusion \citep{Redi1982} (also known as ``neutral diffusion'') in the two coarser configurations has a diffusivity that differs from GM (\mom{aredi_equal_agm}=false).
A constant coefficient of \mom{aredi}=\SI{600}{m^2s^{-1}} is used at $1^\circ$.
At $0.25^\circ$ the Redi coefficient is scaled by the resolution of the grid relative to either the first baroclinic Rossby radius, or the equatorial Rossby radius for latitudes between $\pm5^\circ$N (\mom{aredi_diffusivity_grid_scaling}=true), with a diffusivity no greater than \mom{aredi}= \SI{200}{m^2s^{-1}}.
The isopycnal slope is multiplied by the product of the following two tapering functions when used to calculate neutral diffusion.
\mom{dm_taper} defaults to true, so we use the $\tanh$ tapering scheme of \citet{DanabasogluMcWilliams1995a} in regions of isopycnal slope exceeding \mom{smax}=0.01 in magnitude, with the taper applied over a slope width \mom{swidth}=0.0005 (these are both the default values).
\mom{neutral_eddy_depth} is true, so we also use tapering over an ``eddy depth'' based on the isopycnal slope and Rossby radius, or KPP (whichever is deeper), following \citet{LargeDanabasogluDoneyMcWilliams1997a}.
Diagnostics of the form \href{https://github.com/mom-ocean/MOM5/blob/6bdbdd4892543bbade921fa3224b2530d93c6f40/src/mom5/ocean_param/neutral/ocean_nphysicsC.F90#L1285-L1290}{\param{<tracer_name>_yflux_ndiffuse}} will output the neutral (i.e.~Redi) flux of any tracer in the y-direction.
Similarly the x-flux is available via \param{<tracer_name>_xflux_ndiffuse}.
See chapter~14 of \citet{Griffies2004a} for further explanation, and chapter~23 (particularly section~23.5.2) of \citet{Griffies2012a} for implementation details.
We use the \param{ocean_nphysicsC} formulation (\mom{use_nphysicsc}=true).
Relevant MOM5 source code files are \href{https://github.com/mom-ocean/MOM5/blob/master/src/mom5/ocean_param/neutral/ocean_nphysics_util.F90}{\param{ocean_nphysics_util.F90}} and \href{https://github.com/mom-ocean/MOM5/blob/master/src/mom5/ocean_param/neutral/ocean_nphysicsC.F90}{\param{ocean_nphysicsC.F90}}.
\mom{drhodz_mom4p1} is true at $1^\circ$ but false at $0.25^\circ$.
Further testing of spatially- and temporally-dependent Redi and GM schemes has not yet been undertaken.
However, given the sensitivity of the overturning circulation in the Southern Ocean and the formation of bottom water to the presence of these schemes exposed in a preliminary study in the $0.25^\circ$ configuration, such a sensitivity study should be high on the agenda.
All three configurations include a parameterization for re-stratification in the surface mixed layer due to submesoscale eddies \citep{Fox-Kemper2008}; see namelist group \mom{ocean_submesoscale_nml}.
This parameterization applies an overturning circulation dependent on the horizontal buoyancy gradients within the mixed layer.
The optional horizontal diffusive portion of this parameterization is not used (\mom{submeso_diffusion}=false, so \mom{submeso_diffusion_biharmonic} and \mom{submeso_diffusion_scale} are ignored).
Horizontal friction is implemented with a biharmonic operator and an isotropic Smagorinsky scaling (\mom{k_smag_iso}=2.0, \mom{k_smag_aniso}=0.0) for the viscosity coefficient \citep{GriffiesHallberg2000a}; also see \citet[][chapter~25]{Griffies2012a}.
Our choice of \mom{k_smag_iso}=2.0 is below the lower limit of $\pi/\sqrt{2}\approx 2.2$ suggested by \cite{GriffiesHallberg2000a} and much less than the values of \mom{k_smag_iso}=3.0, \mom{k_smag_aniso}=3.0 used in OFAM3 (Appendix~\ref{S:ofam-namelist}), but matches what is used in ACCESS-CM2 (Appendix~\ref{S:OM2vsCM2}) and does not seem to cause numerical stability problems.
The $1^\circ$ configuration also has a grid spacing-dependent isotropic (\mom{vel_micom_aniso}=0.0) biharmonic background viscosity set by the velocity scale \mom{vel_micom_iso}=\SI{0.04}{m s^{-1}}; there is no background viscosity at the other resolutions.
The NCAR viscosity scheme is also applied at $1^\circ$ (\mom{ncar_boundary_scaling}=true), to enhance the background horizontal viscosity at western boundaries in order to ensure the western boundary currents are resolved (\mom{ncar_boundary_scaling}=true at 0.25$^\circ$ and 0.1$^\circ$ but this has no effect because \mom{vel_micom_iso} and \mom{vel_micom_aniso} are both zero).
%; see \param{ncar_*} in namelist group \mom{ocean_bihgen_friction_nml}.
%, and \paramsty{/short/public/access-om2/input_38570c62/mom_01deg/ncar_rescale.nc}. Or is this not being read? \mom{ncar_boundary_scaling_read} is false.
%This is set by \mom{ncar_boundary_scaling} in `MOM5/src/mom5/ocean_param/lateral/ocean_bihgen_friction.F90`
This increases the background viscosity at $1^\circ$ by a factor that is 4 on the i-maximum side of land cells at each depth, and decreases to 1 as a function of distance in the i direction (NB: this is not eastward distance in the tripole), with a profile that is a Gaussian with length scale \SI{500}{km} (the inverse of \mom{ncar_vconst_4} in cm), raised to the power \mom{ncar_rescale_power}=2.
\WARNING{The background viscosity is inconsistent along the tripole seam} with \mom{ncar_boundary_scaling}=true --- see \url{https://github.com/mom-ocean/MOM5/issues/282}.
At $1^\circ$ there is also background Laplacian viscosity at the bottom set by the velocity scale \mom{vel_micom_bottom}=\SI{0.01}{m s^{-1}} and calculated by a 5-point Laplacian operator (\mom{bottom_5point}=true).
The overall biharmonic viscosity is limited to \mom{visc_crit_scale}=25\% of the numerical instability threshold in ACCESS-OM2, or 100\% in the other two configurations \citep[see][equation (18.26)]{Griffies2004a}.
The Smagorinsky biharmonic viscosity $A_4$ varies spatially by orders of magnitude (Figure~\ref{F:viscosity}).
A viscous western boundary current has a width of about 3.6 times the length scale $(A_4/\beta)^{1/5}$ \citep[see][Appendix~B]{HaidvogelETAL92a}.
This thickness is about 350\,km in ACCESS-OM2, 100\,km in ACCESS-OM2-025, and 60\,km in ACCESS-OM2-01 (Figure~\ref{F:WBCwidth}), which is well-resolved by the grid in all cases.
The lateral boundary condition for velocity is no-slip, as a consequence of using a B-grid \citep{Griffies2012a}.
% we have \mom{use_side_drag_friction} unspecified and the default is false -- but this is for Deremble et al friction (law of the wall)
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=.75\textwidth]{figures/viscosity/viscosity_EAC_clim.png}
\includegraphics[width=.75\textwidth]{figures/viscosity/viscosity_GulfStream_clim.png}
\includegraphics[width=.75\textwidth]{figures/viscosity/viscosity_Agulhas_clim.png}
\caption{Time-mean surface isotropic biharmonic viscosity $A_4$ in several western boundary regions.}
\label{F:viscosity}
\end{center}
\end{figure}
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=.75\textwidth]{figures/viscosity/WBCwidth_EAC_clim.png}
\includegraphics[width=.75\textwidth]{figures/viscosity/WBCwidth_GulfStream_clim.png}
\includegraphics[width=.75\textwidth]{figures/viscosity/WBCwidth_Agulhas_clim.png}
\caption{Biharmonic western boundary current width $3.6(A_4/\beta)^{1/5}$ in several western boundary regions, based on the time-mean surface isotropic biharmonic viscosity $A_4$ (figure~\ref{F:viscosity}).}
\label{F:WBCwidth}
\end{center}
\end{figure}
\subsubsection{Sub-grid scale vertical physics}
\CONTRIBUTORS{Ryan Holmes}
Vertical diffusion of both tracers and momentum is parameterized using the K-profile parameterization \citep[KPP,][\mom{vert_mix_scheme}='kpp_mom4p1']{Large1994}, which governs mixing within the surface boundary layer, as well as interior convection (when the stratification is unstable), Richardson number-based shear instability (active mainly in the equatorial undercurrents), internal wave breaking, and double-diffusion.
\TODO{Comment on applicability of KPP at our high vertical resolution - see \citet{VanRoekelAdcroftDanabasogluGriffiesKauffmanLargeLevyReichlRingler2018a}}
KPP maintains static stability by applying large vertical diffusivity in regions with small or negative Richardson number; therefore explicit convective adjustment is not used at any resolution (see \mom{ocean_convect_nml}).
At $1^\circ$ the \citet{Jochum2009} latitudinally-dependent, depth-independent background vertical tracer diffusivity scheme is used (\mom{j09_diffusivity}=true), with diffusivity \mom{j09_bgmax}=\SI{5e-6}{m^2s^{-1}} poleward of \mom{j09_lat}=$\pm20^\circ$N, reducing to \mom{j09_bgmin}=\SI{1e-6}{m^2s^{-1}} at the equator via a cosine profile, similar to observations \citep{Gregg2003}.
The background vertical tracer diffusivity is zero in ACCESS-OM2-025 and ACCESS-OM2-01 (\mom{j09_diffusivity} is unspecified, and the default is false).
There is no additional non-tidal, non-KPP background vertical diffusivity at any resolution (\mom{background_diffusivity}=0.0).
There are no explicit tides, but we include vertical tracer diffusivity and vertical viscosity from parameterised internal and barotropic tidal processes.
Turbulent mixing and viscosity due to breaking internal tides is parameterised by the \citet{SimmonsJayneLaurentWeaver2004a} scheme (\mom{use_wave_dissipation}=true) with a vertical decay scale \mom{decay_scale}=500\,m, zero background vertical diffusivity (\mom{background_diffusivity}=0.0), a constant background vertical viscosity of \mom{background_viscosity}=\SI{1e-4}{m^2s^{-1}}, tidal current speed read from the file \param{tideamp.nc} (\mom{read_tide_speed}) and bottom roughness amplitude read from the file \param{roughness_amp.nc} (\mom{read_roughness}=true and \mom{reading_roughness_amp}=true).
The \citet{LeeRosatiSpelman2006a} scheme is used to parameterise vertical mixing and viscosity due to the drag of barotropic tides on the bottom (\mom{use_drag_dissipation}).
Further parameters are in the \mom{ocean_vert_tidal_nml} namelist group.
\TODO{investigate whether newer dissipation estimates/methods should be used, e.g.\ are \citet{LavergneFalahatMadecRoquetNycanderVic2019a} and \url{https://doi.org/10.17882/58105} relevant?}
Bottom drag is calculated from the law of the wall using prescribed spatially-varying bottom roughness and tidal current speed (\mom{cdbot_roughness_uamp}=true), with residual current \mom{uresidual}=\SI{0.05}{m s^{-1}}.
Tidal current speed is read from the file \param{tideamp.nc} and bottom roughness is read from the file \param{roughness_cdbot.nc}.
The bottom drag coefficient is restricted to the range \mom{cdbot_lo} to \mom{cdbot_hi}, where \mom{cdbot_lo} takes its default value 0.001 and \mom{cdbot_hi}=0.007 (larger than the default value 0.003).
\mom{cdbot} is unused, since \mom{cdbot_law_of_wall}=false (the default).
The tidal speed data in \param{tideamp.nc} probably originates from \citet{JayneLaurent2001a} if it came from GFDL.\TODO{try to confirm this?} % from Russ https://arccss.slack.com/archives/C9Q7Y1400/p1554428974011900
The bottom roughness files seem basically the same, except that \param{roughness_amp.nc} is on T points and \param{roughness_cdbot.nc} is on U points.
They probably originate from \citet{JayneLaurent2001a} or \citet{Jayne2009a}, which in turn are derived from \citet{SmithSandwell1997a}.\TODO{try to confirm this?}% from Russ: https://arccss.slack.com/archives/C9Q7Y1400/p1541559974040600
\TODO{What is \param{drag_coeff} in \param{ocean_grid.nc}??}
\subsubsection{Rayleigh drag}\label{S:Rayleigh}
\index{Rayleigh drag}{Rayleigh drag} is a velocity tendency term proportional to the velocity, with a negative coefficient whose inverse magnitude is the $e$-folding time for velocity decay.
It is a momentum sink that is employed as an engineering fix to improve model stability and/or realism in a few selected locations in the $1^\circ$ and $0.1^\circ$ configurations, specified in \paramsty{ocean/}\param{field_table}, as shown in figure~\ref{F:Rayleigh}.
At $1^\circ$ it is used to improve the Indonesian Throughflow transport; a damping timescale of 1.5\,hr is applied at all but the bottom 2 (3) U-cells in Lombok (Ombai) Strait and for 3/4 of the width of the Torres Strait at all depths (\WARNING{these omissions were not intended}, and could be corrected in \paramsty{ocean/}\param{field_table} in new configurations: \url{https://github.com/COSIMA/access-om2/issues/156}).
At $0.1^\circ$ a damping timescale of 1.5\,hr is used at all depths across the full width of Kara Strait to constrain the velocity, which otherwise leads to numerical instability unless an unfeasibly small timestep is used.
There is no Rayleigh drag in the $0.25^\circ$ configuration.
\begin{figure}
\begin{center}
\includegraphics[height=0.3\textwidth]{figures/Rayleigh_drag/Rayleigh_undamped_cells_1deg.png}\quad
\includegraphics[height=0.3\textwidth]{figures/Rayleigh_drag/Rayleigh_undamped_cells_01deg.png}\\
\includegraphics[height=0.3\textwidth]{figures/Rayleigh_drag/Rayleigh_damp_time_1deg.png}\quad
\includegraphics[height=0.3\textwidth]{figures/Rayleigh_drag/Rayleigh_damp_time_01deg.png}
\end{center}
\caption[Rayleigh damping locations and magnitudes.]{
Rayleigh damping locations and magnitudes.
Circles indicate where Rayleigh damping is defined in \paramsty{ocean/}\param{field_table} and white cells are the U-grid land mask.
Top row: Rayleigh damping locations at $1^\circ$ (left; in the Lombok, Ombai and Torres Straits) and $0.1^\circ$ (right; in the Kara Strait); colours in the circled cells indicate how many U-cells are not damped in each column.
Bottom row: Rayleigh damping timescale (or zero if not defined) at $1^\circ$ (left) and $0.1^\circ$ (right).
Where defined, damping timescales are all 5400\,s.
There is no Rayleigh damping at $0.25^\circ$.
\label{F:Rayleigh}