-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathaccess-om3-doc.tex
309 lines (275 loc) · 15.9 KB
/
access-om3-doc.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
\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-om3-doc/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-om3-doc/issues/#1}{ISSUE #1}}}}}\index{ISSUE}}
\newcommand{\CISSUE}[1]{\note{\colorbox{gray}{\textsf{\textbf{\href{https://github.com/COSIMA/access-om3-doc/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-OM3}
\author{
Andrew Kiss
\TODO{add anyone who contributed}}
\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-om3-doc}\\
%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-om3-doc/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-om3-doc} to be kept informed of discussions
\item to discuss aspects of the paper, please post an issue at \url{https://github.com/COSIMA/access-om3-doc/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 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-om3-doc} for how to add or edit figures
\end{itemize}
}
%}
}
\vfill
\begin{center}
\qrcode[height=0.1\textwidth]{http://cosima.org.au}\\
\href{http://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}
\newpage
\section{Acknowledgments}
Model development has been partly funded by ARC Linkage grant LP200100406.
\TODO{and ACCESS-NRI}
Runs were undertaken on the NCI National Facility in Canberra, which is supported by the Australian Commonwealth Government.
\appendix
\section{Namelists}\label{S:namelists}
\rowcolors{1}{lightblue}{white}
% \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}\renewcommand{\nmldiffer}[1]{\colorbox{hilite}{#1}}\setlength{\fboxsep}{0pt} % colour highlight of differing variables (requires color package)
\renewcommand{\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)
%\newcommand{\nml}[1]{{\small\textsf{\input{local/#1}}}} % use nml tables generated from local files
%\renewcommand{\nml}[1]{{\small\textsf{\input{raijin/#1}}}} % use nml tables generated on raijin
\renewcommand{\nml}[1]{{\small\textsf{\input{tables/#1}}}} % use nml tables from gadi mirror
%\newlength{\nmllen}\setlength{\nmllen}{13ex}
These tables show the namelist files used for standard configurations of ACCESS-OM2 and ACCESS-OM3.
These tables are auto-generated by \param{make_tables.py} which uses \param{nmltab} (\url{https://github.com/aekiss/nmltab}).
Variables are weblinks to source code searches.
Variables that differ between the models are \nmldiffer{\textcolor{link}{highlighted}}.
\ignored{Greyed values} are ignored. % (greying only works in groups with use_this_module shown, so typically doesn't work for tables of differences).
\TODO{generate complete tables that include the default values of parameters not specified in namelists}
\rowcolors{1}{lightblue}{white}
%\setlength{\nmllen}{18ex} % works well for 3 columns
\setlength{\nmllen}{13ex} % works well for 4 columns
\subsection{MOM namelists}\label{S:mom-namelist}
%\renewcommand{\nmllink}[2]{\href{https://github.com/mom-ocean/MOM5/search?q=#2}{#1}\index{\paramsty{#2}}} % link to documentation (requires hyperref package)
%\renewcommand{\nmllink}[2]{\hypertarget{mom:#2}{\href{https://github.com/mom-ocean/MOM5/search?q=#2}{#1}}\index{\paramsty{#2}}} % link to documentation (requires hyperref package)
\renewcommand{\nmllink}[2]{\hexhypertarget{mom:#2}{\href{https://github.com/mom-ocean/MOM6/search?q=#2}{#1}}\index{\paramsty{#2}}} % link to documentation (requires hyperref package)
%\nml{mom_nml.tex}
\nml{MOM_input/mom6_global_nml.tex}
%\nml{mom6_sis2_regional_nml.tex}
\subsection{CICE namelists}\label{S:cice-namelist}
See \url{https://cice-consortium-cice.readthedocs.io/en/main/}% \url{https://ncar.github.io/CICE/users_guide/ice_nml_var.html}.
%\renewcommand{\nmllink}[2]{\hexhypertarget{cice:#2}{\href{https://github.com/ESCOMP/CICE/search?q=#2}{#1}}\index{\paramsty{#2}}} % link to documentation (requires hyperref package)
\renewcommand{\nmllink}[2]{\hexhypertarget{cice:#2}{\href{https://cice-consortium-cice.readthedocs.io/en/main/search.html?q=#2}{#1}}\index{\paramsty{#2}}} % link to documentation (requires hyperref package)
\nml{ice_in/cice_nml.tex}
\clearpage
\phantomsection % fix hyperrefs to references
\addcontentsline{toc}{part}{References}
\setlength{\parskip}{0em}
\bibliographystyle{ametsoc2014}
\bibliography{access-om3-doc}
\clearpage
\phantomsection % fix hyperrefs to index
%\addcontentsline{toc}{chapter}{\protect\numberline{}{Index}}
\addcontentsline{toc}{part}{\indexname}
\printindex
\end{document}