darwin3 |
|
|
|
|||
Warning, /doc/outp_pkgs/outp_pkgs.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit f460f9a5 on 2025-03-19 20:40:18 UTCaf61fa61c7 Jeff*0001 0002 .. _outp_pack: 0003 1c65381846 Jeff*0004 Packages II - Diagnostics and I/O 0005 ********************************* 0006 9ce7d74115 Jeff*0007 MITgcm includes several packages related to input and output during a 0008 model integration. The packages described in this chapter are related to 0009 the choice of input/output fields and their on-disk format. 0010 bf89a37abc Phob*0011 .. _sub_outp_pkg_diagnostics: 0012 9ce7d74115 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 14.
0013 pkg/diagnostics – A Flexible Infrastructure 0014 =========================================== 0015 0016 Introduction 0017 ------------ 0018 0019 This section of the documentation describes the diagnostics package 0020 (:filelink:`pkg/diagnostics`) 0021 available within MITgcm. A large selection of model diagnostics is 0022 available for output. In addition to the diagnostic quantities 0023 pre-defined within MITgcm, there exists the option, in any code setup, to 0024 define a new diagnostic quantity and include it as part of the 0025 diagnostic output with the addition of a single subroutine call in the 0026 routine where the field is computed. As a matter of philosophy, no 0027 diagnostic is enabled as default, thus each user must specify the exact 0028 diagnostic information required for an experiment. This is accomplished 0029 by enabling the specific diagnostics of interest from the list of 0030 :ref:`available diagnostics <diagnostics_list>`. Additional diagnostic quantities, 0031 defined within different MITgcm 0032 packages, are available and are listed in the diagnostic list subsection 0033 of the manual section associated with each relevant package. Instructions for 0034 enabling diagnostic output and defining new diagnostic quantities are 0035 found in :numref:`usage_notes` of this document. 0036 0037 Once a diagnostic is enabled, MITgcm will continually increment an array 0038 specifically allocated for that diagnostic whenever the appropriate 0039 quantity is computed. A counter is defined which records how many times 0040 each diagnostic quantity has been incremented. Several special 0041 diagnostics are included in the list of :ref:`available diagnostics <diagnostics_list>`.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 43.
0042 Quantities referred to as “counter diagnostics” are defined for selected diagnostics which record the 0043 frequency at which a diagnostic is incremented separately for each model** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 45.
0044 grid location. Quantities referred to as “user diagnostics” are included 0045 to facilitate defining new diagnostics for a particular 0046 experiment. 0047 0048 Equations 0049 --------- 0050 0051 Not relevant. 0052 0053 Key Subroutines and Parameters 0054 ------------------------------ 0055 0056 There are several utilities within MITgcm available to users to enable, 0057 disable, clear, write and retrieve model diagnostics, and may be called 0058 from any routine. The available utilities and the CALL sequences are 0059 listed below. 0060 0061 :filelink:`diagnostics_addtolist.F <pkg/diagnostics/diagnostics_addtolist.F>`: 0062 This routine is the underlying interface 0063 routine for defining a new permanent diagnostic in the main model or in 0064 a package. The calling sequence is: 0065 0066 :: 0067 0068 CALL DIAGNOSTICS_ADDTOLIST ( 0069 O diagNum, 0070 I diagName, diagCode, diagUnits, diagTitle, diagMate, 0071 I myThid ) 0072 0073 where: 0074 diagNum = diagnostic Id number - Output from routine 0075 diagName = name of diagnostic to declare 0076 diagCode = parser code for this diagnostic 0077 diagUnits = field units for this diagnostic 0078 diagTitle = field description for this diagnostic 0079 diagMate = diagnostic mate number 0080 myThid = my Thread Id number 0081 0082 :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>`: 0083 This is the main user interface routine to the 0084 diagnostics package. This routine will increment the specified 0085 diagnostic quantity with a field sent through the argument list. 0086 0087 :: 0088 0089 CALL DIAGNOSTICS_FILL( 0090 I inpFld, diagName, 0091 I kLev, nLevs, bibjFlg, bi, bj, myThid ) 0092 0093 where: 0094 inpFld = Field to increment diagnostics array 0095 diagName = diagnostic identificator name (8 characters long) 0096 kLev = Integer flag for vertical levels: 0097 > 0 (any integer): WHICH single level to increment in qdiag. 0098 0,-1 to increment "nLevs" levels in qdiag, 0099 0 : fill-in in the same order as the input array 0100 -1: fill-in in reverse order. 0101 nLevs = indicates Number of levels of the input field array 0102 (whether to fill-in all the levels (kLev<1) or just one (kLev>0)) 0103 bibjFlg = Integer flag to indicate instructions for bi bj loop 0104 = 0 indicates that the bi-bj loop must be done here 0105 = 1 indicates that the bi-bj loop is done OUTSIDE 0106 = 2 indicates that the bi-bj loop is done OUTSIDE 0107 AND that we have been sent a local array (with overlap regions) 0108 (local array here means that it has no bi-bj dimensions) 0109 = 3 indicates that the bi-bj loop is done OUTSIDE 0110 AND that we have been sent a local array 0111 AND that the array has no overlap region (interior only) 0112 NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter 0113 bi = X-direction tile number - used for bibjFlg=1-3 0114 bj = Y-direction tile number - used for bibjFlg=1-3 0115 myThid = my thread Id number 0116 0117 :filelink:`diagnostics_scale_fill.F <pkg/diagnostics/diagnostics_scale_fill.F>`: 0118 This is a possible alternative routine 0119 to :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>` 0120 which performs the same functions and has an 0121 additional option to scale the field before filling or raise the field 0122 to a power before filling. 0123 0124 :: 0125 0126 CALL DIAGNOSTICS_SCALE_FILL( 0127 I inpFld, scaleFact, power, diagName, 0128 I kLev, nLevs, bibjFlg, bi, bj, myThid ) 0129 0130 0131 where all the arguments are the same as for DIAGNOSTICS_FILL with 0132 the addition of: 0133 scaleFact = Scaling factor to apply to the input field product 0134 power = Integer power to which to raise the input field (after scaling) 0135 0136 :filelink:`diagnostics_fract_fill.F <pkg/diagnostics/diagnostics_fract_fill.F>`: 0137 This is a specific alternative routine 0138 to :filelink:`diagnostics_scale_fill.F <pkg/diagnostics/diagnostics_scale_fill.F>` 0139 for the case of a diagnostics which is 0140 associated to a fraction-weight factor (referred to as the diagnostics** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 142.
0141 “counter-mate”). This fraction-weight field is expected to vary during 0142 the simulation and is provided as argument to :filelink:`diagnostics_fract_fill.F <pkg/diagnostics/diagnostics_frac_fill.F>` 0143 in order to perform fraction-weighted time-average diagnostics. Note 0144 that the fraction-weight field has to correspond to the diagnostics 0145 counter-mate which has to be filled independently with a call to 0146 :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>`. 0147 0148 :: 0149 0150 CALL DIAGNOSTICS_FRACT_FILL( 0151 I inpFld, fractFld, scaleFact, power, diagName, 0152 I kLev, nLevs, bibjFlg, bi, bj, myThid ) 0153 0154 0155 where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with 0156 the addition of: 0157 fractFld = fraction used for weighted average diagnostics 0158 0159 :filelink:`diagnostics_is_on.F <pkg/diagnostics/diagnostics_is_on.F>`: 0160 Function call to inquire whether a diagnostic 0161 is active and should be incremented. Useful when there is a computation 0162 that must be done locally before a call to :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>`. 0163 The call sequence: 0164 0165 :: 0166 0167 flag = DIAGNOSTICS_IS_ON( diagName, myThid ) 0168 0169 where: 0170 diagName = diagnostic identificator name (8 characters long) 0171 myThid = my thread Id number 0172 0173 :filelink:`diagnostics_count.F <pkg/diagnostics/diagnostics_count.F>`: 0174 This subroutine increments the diagnostics 0175 counter only. In general, the diagnostics counter is incremented at the 0176 same time as the diagnostics is filled, by calling :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>`. 0177 However, there are few cases where the counter is not incremented during 0178 the filling (e.g., when the filling is done level per level but level 1 0179 is skipped) and needs to be done explicitly with a call to subroutine 0180 :filelink:`diagnostics_count.F <pkg/diagnostics/diagnostics_count.F>`. The call sequence is: 0181 0182 :: 0183 0184 CALL DIAGNOSTICS_COUNT( 0185 I diagName, bi, bj, myThid ) 0186 0187 where: 0188 diagName = name of diagnostic to increment the counter 0189 bi = X-direction tile number, or 0 if called outside bi,bj loops 0190 bj = Y-direction tile number, or 0 if called outside bi,bj loops 0191 myThid = my thread Id number 0192 0193 0194 The diagnostics are computed at various times and places within MITgcm. 0195 Because MITgcm may employ a staggered grid, diagnostics may be computed 0196 at grid box centers, corners, or edges, and at the middle or edge in the 0197 vertical. Some diagnostics are scalars, while others are components of 0198 vectors. An internal array is defined which contains information 0199 concerning various grid attributes of each diagnostic. The :varlink:`gdiag` array 0200 (in common block diagnostics in file :filelink:`DIAGNOSTICS.h <pkg/diagnostics/DIAGNOSTICS.h>`) is internally 0201 defined as a character*16 variable, and is equivalenced to a** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 203.
0202 character*1 “parse” array in output in order to extract the 0203 grid-attribute information. The :varlink:`gdiag` array is described in :numref:`diagnostic_parsing_array`. 0204 0205 0206 .. table:: Diagnostic Parsing Array 0207 :name: diagnostic_parsing_array 0208 0209 +-----------+-----------------------+-----------------------------------------------------+ 0210 | Array | Value | Description | 0211 +===========+=======================+=====================================================+ 0212 | parse(1) | :math:`\rightarrow` S | scalar diagnostic | e2c4ac4a43 Ed D*0213 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0214 | | :math:`\rightarrow` U | U-vector component diagnostic | e2c4ac4a43 Ed D*0215 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0216 | | :math:`\rightarrow` V | V-vector component diagnostic | e2c4ac4a43 Ed D*0217 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0218 | parse(2) | :math:`\rightarrow` U | C-grid U-point | e2c4ac4a43 Ed D*0219 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0220 | | :math:`\rightarrow` V | C-grid V-point | e2c4ac4a43 Ed D*0221 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0222 | | :math:`\rightarrow` M | C-grid mass point | e2c4ac4a43 Ed D*0223 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0224 | | :math:`\rightarrow` Z | C-grid vorticity (corner) point | e2c4ac4a43 Ed D*0225 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0226 | parse(3) | :math:`\rightarrow` | used for level-integrated output: cumulate levels | e2c4ac4a43 Ed D*0227 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0228 | | :math:`\rightarrow` r | same but cumulate product by model level thickness | e2c4ac4a43 Ed D*0229 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0230 | | :math:`\rightarrow` R | same but cumulate product by hFac & level thickness | e2c4ac4a43 Ed D*0231 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0232 | parse(4) | :math:`\rightarrow` P | positive definite diagnostic | e2c4ac4a43 Ed D*0233 +-----------+-----------------------+-----------------------------------------------------+ a5ec81ed49 Timo*0234 | | :math:`\rightarrow` A | Adjoint variable diagnostic | 0235 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0236 | parse(5) | :math:`\rightarrow` C | with counter array | e2c4ac4a43 Ed D*0237 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0238 | | :math:`\rightarrow` P | post-processed (not filled up) from other diags | e2c4ac4a43 Ed D*0239 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0240 | | :math:`\rightarrow` D | disable diagnostic for output | e2c4ac4a43 Ed D*0241 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0242 | parse(6-8)| | retired, formerly 3-digit mate number | e2c4ac4a43 Ed D*0243 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0244 | parse(9) | :math:`\rightarrow` U | model level + :math:`\frac{1}{2}` | e2c4ac4a43 Ed D*0245 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0246 | | :math:`\rightarrow` M | model level middle | e2c4ac4a43 Ed D*0247 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0248 | | :math:`\rightarrow` L | model level - :math:`\frac{1}{2}` | e2c4ac4a43 Ed D*0249 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0250 | parse(10) | :math:`\rightarrow` 0 | levels = 0 | e2c4ac4a43 Ed D*0251 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0252 | | :math:`\rightarrow` 1 | levels = 1 | e2c4ac4a43 Ed D*0253 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0254 | | :math:`\rightarrow` R | levels = Nr | e2c4ac4a43 Ed D*0255 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0256 | | :math:`\rightarrow` L | levels = MAX(Nr,NrPhys) | e2c4ac4a43 Ed D*0257 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0258 | | :math:`\rightarrow` M | levels = MAX(Nr,NrPhys) - 1 | e2c4ac4a43 Ed D*0259 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0260 | | :math:`\rightarrow` G | levels = ground_level number | e2c4ac4a43 Ed D*0261 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0262 | | :math:`\rightarrow` I | levels = seaice_level number | e2c4ac4a43 Ed D*0263 +-----------+-----------------------+-----------------------------------------------------+ 9ce7d74115 Jeff*0264 | | :math:`\rightarrow` X | free levels option (need to be set explicitly) | e2c4ac4a43 Ed D*0265 +-----------+-----------------------+-----------------------------------------------------+ ba0b047096 Mart*0266 9ce7d74115 Jeff*0267 0268 95e7dbd5d6 Oliv*0269 As an example, consider a diagnostic whose associated :varlink:`gdiag` 0270 parameter is equal to ``UUR MR``. From :varlink:`gdiag` we can determine 0271 that this diagnostic is a U-vector component located at the C-grid U-point, 0272 model mid-level (M) with Nr levels (last R). 9ce7d74115 Jeff*0273 0274 In this way, each diagnostic in the model has its attributes (i.e., vector 0275 or scalar, C-grid location, etc.) defined internally. The output 0276 routines use this information in order to determine what type of 0277 transformations need to be performed. Any interpolations are done at the 0278 time of output rather than during each model step. In this way the user 0279 has flexibility in determining the type of output gridded data. 0280 0281 .. _usage_notes: 0282 0283 Usage Notes 0284 ----------- 0285 0286 Using available diagnostics 0287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0288 0289 To use the diagnostics package, other than enabling it in ``packages.conf`` 0290 and turning the :varlink:`useDiagnostics` flag in ``data.pkg`` to ``.TRUE.``, there are two 0291 further steps the user must take to enable the diagnostics package for 0292 output of quantities that are already defined in MITgcm under an** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 294.
0293 experiment’s configuration of packages. A parameter file 0294 ``data.diagnostics`` must be supplied in the run directory, and the file 0295 :filelink:`DIAGNOSTICS_SIZE.h <pkg/diagnostics/DIAGNOSTICS_SIZE.h>` 0296 must be included in the code directory. The steps 0297 for defining a new (permanent or experiment-specific temporary) 0298 diagnostic quantity will be outlined later. 0299 0300 The namelist in parameter file ``data.diagnostics`` will activate a 0301 user-defined list of diagnostics quantities to be computed, specify the 0302 frequency and type of output, the number of levels, and the name of all 0303 the separate output files. A sample ``data.diagnostics`` namelist file: 0304 0305 :: 0306 0307 # Diagnostic Package Choices 0308 #-------------------- 0309 # dumpAtLast (logical): always write output at the end of simulation (default=F) 0310 # diag_mnc (logical): write to NetCDF files (default=useMNC) 0311 #--for each output-stream: 0312 # fileName(n) : prefix of the output file name (max 80c long) for outp.stream n 0313 # frequency(n):< 0 : write snap-shot output every |frequency| seconds 0314 # > 0 : write time-average output every frequency seconds 0315 # timePhase(n) : write at time = timePhase + multiple of |frequency| 0316 # averagingFreq : frequency (in s) for periodic averaging interval 0317 # averagingPhase : phase (in s) for periodic averaging interval 0318 # repeatCycle : number of averaging intervals in 1 cycle 0319 # levels(:,n) : list of levels to write to file (Notes: declared as REAL) 0320 # when this entry is missing, select all common levels of this list 0321 # fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n 0322 # (see "available_diagnostics.log" file for the full list of diags) 0323 # missing_value(n) : missing value for real-type fields in output file "n" 0324 # fileFlags(n) : specific code (8c string) for output file "n" 0325 #-------------------- 0326 &DIAGNOSTICS_LIST 0327 fields(1:2,1) = 'UVEL ','VVEL ', 0328 levels(1:5,1) = 1.,2.,3.,4.,5., 1d99daeaf6 Oliv*0329 fileName(1) = 'diagout1', 9ce7d74115 Jeff*0330 frequency(1) = 86400., 0331 fields(1:2,2) = 'THETA ','SALT ', 1d99daeaf6 Oliv*0332 fileName(2) = 'diagout2', 0333 fileFlags(2) = ' P ', 0334 levels(1:5,2) = 100000.0, 70000.0, 50000.0, 30000.0, 20000.0, 9ce7d74115 Jeff*0335 frequency(2) = 3600., 0336 & 0337 0338 &DIAG_STATIS_PARMS 0339 & 0340 0341 In this example, there are two output files that will be generated for 0342 each tile and for each output time. The first set of output files has 0343 the prefix ``diagout1``, does time averaging every 86400. seconds, 0344 (frequency is 86400.), and will write fields which are multiple-level 0345 fields at output levels 1-5. The names of diagnostics quantities are 0346 ``UVEL`` and ``VVEL``. The second set of output files has the prefix diagout2, 1d99daeaf6 Oliv*0347 does time averaging every 3600. seconds and the names of diagnostics quantities 0348 are ``THETA`` and ``SALT``. It interpolates vertically to the pressure levels 0349 100000 Pa, ..., 20000 Pa. 0350 0351 The :varlink:`fileFlags` parameter is explained in 0352 :numref:`diagnostic_fileFlags`. Only the first three characters matter. The 0353 first character determines the precision of the output files. The default is 0354 to use :varlink:`writeBinaryPrec`. The second character determines whether the 0355 fields are to be integrated or interpolated vertically or written as is (the 0356 default). Interpolation is only available in the atmosphere. The desired 0357 pressure levels need to be specified in ``levels``. The third character is 0358 used to time average the product of a diagnostic with the appropriate 0359 thickness factor, hFacC, hFacW or hFacS. This is mostly useful with a 0360 non-linear free surface where the thickness factors vary in time. This will 0361 have an effect only for certain diagnostics, as determined by the parsing code 0362 (see :numref:`diagnostic_parsing_array` and the file available_diagnostics.log 0363 for a given setup): parse(3) has to be ``'R'``, parse(5) blank and parse(9:10) 0364 ``'MR'``. Vorticity-point diagnostics cannot be hFac weighted. Note that the 0365 appropriate hFac factors are automatically included when integrating vertically 0366 (second character ``'I'``), so the 'h' is not needed in this case 0367 but could still improve accuracy of a time-averaged vertical integral when using 0368 non-linear free surface. 0369 0370 .. table:: Diagnostic fileFlags 0371 :name: diagnostic_fileflags 0372 0373 +---------------+-------+----------------------------------------------+ 0374 | Character pos | Value | Description | 0375 +===============+=======+==============================================+ 0376 | 1 | R | precision: 32 bits | 0377 +---------------+-------+----------------------------------------------+ 0378 | | D | precision: 64 bits | 0379 +---------------+-------+----------------------------------------------+ 0380 | | | precision: writeBinaryPrec | 0381 +---------------+-------+----------------------------------------------+ 0382 | 2 | I | integrate vertically | 0383 +---------------+-------+----------------------------------------------+ 0384 | | P | interpolate vertically | 0385 +---------------+-------+----------------------------------------------+ 0386 | | | do not integrate or interpolate | 0387 +---------------+-------+----------------------------------------------+ 0388 | 3 | h | multiply by hFac (if permitted) when filled | 0389 +---------------+-------+----------------------------------------------+ 0390 9ce7d74115 Jeff*0391 0392 The user must assure that enough computer memory is allocated for the 0393 diagnostics and the output streams selected for a particular experiment. 0394 This is accomplished by modifying the file 0395 :filelink:`DIAGNOSTICS_SIZE.h <pkg/diagnostics/DIAGNOSTICS_SIZE.h>` and 0396 including it in the experiment code directory. The parameters that 0397 should be checked are called :varlink:`numDiags`, :varlink:`numLists`, :varlink:`numperList`, and 0398 :varlink:`diagSt_size`. 0399 0400 :varlink:`numDiags` (and :varlink:`diagSt_size`): 0401 All MITgcm diagnostic quantities are stored in the single diagnostic 0402 array :varlink:`gdiag` which is located in the file and has the form: 0403 0404 :: 0405 0406 _RL qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy) 0407 _RL qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy) 0408 COMMON / DIAG_STORE_R / qdiag, qSdiag 0409 0410 The first two-dimensions of :varlink:`diagSt_size` correspond to the horizontal dimension 0411 of a given diagnostic, and the third dimension of :varlink:`diagSt_size` is used to 0412 identify diagnostic fields and levels combined. In order to minimize the 0413 memory requirement of the model for diagnostics, the default MITgcm 0414 executable is compiled with room for only one horizontal diagnostic 0415 array, or with :varlink:`numDiags` set to Nr. In order for the user to enable more 0416 than one 3-D diagnostic, the size of the diagnostics common 0417 must be expanded to accommodate the desired diagnostics. This can be 0418 accomplished by manually changing the parameter :varlink:`numDiags` in the file . 0419 :varlink:`numDiags` should be set greater than or equal to the sum of all the 0420 diagnostics activated for output each multiplied by the number of levels 0421 defined for that diagnostic quantity. For the above example, there are four 0422 multiple level fields, which the available diagnostics list (see below) indicates 0423 are defined at the MITgcm vertical resolution, Nr. The value of :varlink:`numDiags` in 0424 :filelink:`DIAGNOSTICS_SIZE.h <pkg/diagnostics/DIAGNOSTICS_SIZE.h>` would therefore be equal to 4*Nr, or, say 40 if 0425 Nr=10. 0426 0427 :varlink:`numLists` and :varlink:`numperList`: 0428 The parameter :varlink:`numLists` must be set greater than or equal to the number 0429 of separate output streams that the user specifies in the namelist 0430 file ``data.diagnostics``. The parameter :varlink:`numperList` corresponds to the 0431 maximum number of diagnostics requested per output streams. 0432 a5ec81ed49 Timo*0433 0434 Adjoint variables 0435 ~~~~~~~~~~~~~~~~~ 0436 0437 The diagnostics package can also be used to print adjoint state variables. Using the diagnostics package ba0b047096 Mart*0438 as opposed to using the standard 'adjoint dump' options allows one to take advantage of all the 0439 averaging and post processing routines available to other diagnostics variables. a5ec81ed49 Timo*0440 0441 Currently, the available adjoint state variables are: 0442 0443 :: 0444 a10c595eb6 Timo*0445 109 |ADJetan | 1 | |SM A M1|dJ/m |dJ/dEtaN: Sensitivity to sea surface height anomaly 0446 110 |ADJuvel | 15 | 111 |UURA MR|dJ/(m/s) |dJ/dU: Sensitivity to zonal velocity 0447 111 |ADJvvel | 15 | 110 |VVRA MR|dJ/(m/s) |dJ/dV: Sensitivity to meridional velocity 0448 112 |ADJwvel | 15 | |WM A LR|dJ/(m/s) |dJ/dW: Sensitivity to vertical velocity 0449 113 |ADJtheta| 15 | |SMRA MR|dJ/degC |dJ/dTheta: Sensitivity to potential temperature e9a960d146 Oliv*0450 114 |ADJsalt | 15 | |SMRA MR|dJ/(g/kg) |dJ/dSalt: Sensitivity to salinity a10c595eb6 Timo*0451 115 |ADJtaux | 1 | 116 |UU A U1|dJ/(N/m^2) |dJ/dTaux: Senstivity to zonal surface wind stress 0452 116 |ADJtauy | 1 | 115 |VV A U1|dJ/(N/m^2) |dJ/dTauy: Sensitivity to merid. surface wind stress 1ac7194fda plla*0453 117 |ADJempmr| 1 | |SM A U1|dJ/(kg/m^2/s) |dJ/dEmPmR: Sensitivity to net surface freshwater flux 0454 118 |ADJqnet | 1 | |SM A U1|dJ/(W/m^2) |dJ/dQnet: Sensitivity to net surface heat flux a10c595eb6 Timo*0455 119 |ADJqsw | 1 | |SM A U1|dJ/(W/m^2) |dJ/dQsw: Sensitivitiy to net Short-Wave radiation 0456 120 |ADJsst | 1 | |SM A M1|dJ/K |dJ/dSST: Sensitivity to Sea Surface Temperature e9a960d146 Oliv*0457 121 |ADJsss | 1 | |SM A M1|dJ/(g/kg) |dJ/dSSS: Sensitivity to Sea Surface Salinity a10c595eb6 Timo*0458 122 |ADJbtdrg| 1 | |SM A M1|dJ/d() |dJ/dCd: Sensitivity to bottom drag coefficient 0459 123 |ADJdifkr| 15 | |SMRA MR|dJ/d(m^2/s)) |dJ/dKr: Sensitivity to vertical diffusivity 0460 124 |ADJepsix| 15 | 125 |UURA UR|dJ/(m^2/s) |dJ/dEddyPsiX: Sensitivity to zonal eddystreamfunction 0461 125 |ADJepsiy| 15 | 124 |VVRA UR|dJ/(m^2/s) |dJ/dEddyPsiY: Sensitivity to meridional eddystreamfunction 0462 0463 0464 Additionally the packages :ref:`gmredi <sub_phys_pkg_gmredi>`, 0465 :ref:`ptracrs <sub_phys_pkg_ptracers>`, :ref:`exf <sub_phys_pkg_exf>`, and 0466 :ref:`seaice <sub_phys_pkg_seaice>` have the following available adjoint diagnostics 0467 0468 :: 0469 0470 225 |ADJkapgm| 15 | |SMRA MR|dJ/d[m^2/s] |dJ/dKgm: Sensitivity to GM Intensity 0471 226 |ADJkapre| 15 | |SMRA MR|dJ/d[m^2/s] |dJ/dKredi: Sensitivity to Redi Coefficient 0472 1d99daeaf6 Oliv*0473 :: a10c595eb6 Timo*0474 0475 227 |TRAC01 | 15 | |SMR MR|mol C/m |Dissolved Inorganic Carbon concentration 0476 241 |ADJptr01| 15 | |SMRA MR|dJ/mol C/m |sensitivity to Dissolved Inorganic Carbon concentration 0477 0478 :: 0479 0480 221 |ADJustrs| 1 | 222 |UU A U1|dJ/(N/m^2) |dJ/dustress: Senstivity to zonal surface wind stress 0481 222 |ADJvstrs| 1 | 221 |VV A U1|dJ/(N/m^2) |dJ/dvstrs: Sensitivity to merid. surface wind stress 0482 223 |ADJhflux| 1 | |SM A U1|dJ/(W/m^2) |dJ/dhflux: Sensitivity to upward heat flux 0483 224 |ADJsflux| 1 | |SM A U1|dJ/(m/s) |dJ/dhflux: Sensitivity to upward fresh water flux 0484 225 |ADJatemp| 1 | |SM A U1|dJ/K |dJ/datemp: Sensitivity to atmos. surface temperature 0485 226 |ADJpreci| 1 | |SM A U1|dJ/(m/s) |dJ/daqh: Sensitivity to precipitation 0486 227 |ADJroff | 1 | |SM A U1|dJ/(m/s) |dJ/daqh: Sensitivity to river runoff 0487 228 |ADJswdn | 1 | |SM A U1|dJ/(W/m^2) |dJ/dswdown: Sensitivity to downward SW radiation 0488 229 |ADJlwdn | 1 | |SM A U1|dJ/(W/m^2) |dJ/dlwdown: Sensitivity to downward LW radiation 0489 230 |ADJuwind| 1 | |UM A U1|dJ/d(m/s) |dJ/duwind: Senstivity to zonal 10-m wind speed 0490 231 |ADJvwind| 1 | |VM A U1|dJ/d(m/s) |dJ/dvwind: Senstivity to meridional 10-m wind speed 0491 232 |ADJclsst| 1 | |SM A U1|dJ/K |dJ/dclimsst: Sensitivity to restoring SST 0492 233 |ADJclsss| 1 | |SM A U1|dJ/(g/kg) |dJ/dclimsss: Sensitivity to restoring SSS 0493 0494 :: 0495 0496 332 |ADJarea | 1 | |SM A M1|dJ/(m^2/m^2) |dJ/darea: Sensitivity to seaice fractional ice-cover 0497 333 |ADJheff | 1 | |SM A M1|dJ/dm |dJ/dheff: Sensitvity to seaice ice thickness 0498 334 |ADJhsnow| 1 | |SM A M1|dJ/dm |dJ/dhsnow: Sensitivity to seaice snow thickness 0499 335 |ADJuice | 1 | 336 |UU A M1|dJ/(m/s) |dJ/duice: sensitivity to zonal ice velocity 0500 336 |ADJvice | 1 | 335 |VV A M1|dJ/(m/s) |dJ/dvice: sensitivity to meridional ice velocity a5ec81ed49 Timo*0501 0502 Some notes to the user 0503 ^^^^^^^^^^^^^^^^^^^^^^ 0504 0505 1. This feature is currently untested with OpenAD. 0506 0507 2. This feature does not work with the divided adjoint. 0508 a10c595eb6 Timo*0509 3. The sensitivity to sea surface height `ADJetan` is technically one time step 0510 ahead of other adjoint diagnostics printed at the same time step number. To be 0511 concrete, if `ADJetan` is written via the diagnostics package at every 0512 iteration, `n`, then each field will technically correspond to the written 0513 iteration number, `n+1`. This is simply due to a techincality about when this 0514 variable is printed in relation to the adjoint pressure solve. a5ec81ed49 Timo*0515 ba0b047096 Mart*0516 4. The diagStats options are not available for these variables. a5ec81ed49 Timo*0517 0518 5. Adjoint variables are recognized by checking the 10 character variable `diagCode`. ba0b047096 Mart*0519 To add a new adjoint variable, set the 4th position of `diagCode` to A a5ec81ed49 Timo*0520 (notice this is the case for the list of available adjoint variables). 0521 0522 0523 Using pkg/diagnostics for adjoint variables 0524 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 0525 ba0b047096 Mart*0526 1. Make sure the following flag is defined in either 0527 :filelink:`AUTODIFF_OPTIONS.h <pkg/autodiff/AUTODIFF_OPTIONS.h>` a5ec81ed49 Timo*0528 or `ECCO_CPPOPTIONS.h` if that is being used. 0529 ba0b047096 Mart*0530 :: a5ec81ed49 Timo*0531 0532 #define ALLOW_AUTODIFF_MONITOR 0533 ba0b047096 Mart*0534 2. Be sure to increase `numlists` and `numDiags` appropriately in a5ec81ed49 Timo*0535 :filelink:`DIAGNOSTICS_SIZE.h <pkg/diagnostics/DIAGNOSTICS_SIZE.h>`. 0536 Safe values are e.g. 10-20 and 500-1000 respectively. 0537 ba0b047096 Mart*0538 3. Specify desired variables in ``data.diagnostics`` 0539 as any other variable, as in the following example or as in this a5ec81ed49 Timo*0540 :filelink:`data.diagnostics <verification/global_ocean.cs32x15/input_ad/data.diagnostics>`. 0541 Note however, adjoint and forward diagnostic variables cannot ba0b047096 Mart*0542 be in the same list. That is, a single `fields(:,:)` list a5ec81ed49 Timo*0543 cannot contain both adjoint and forward variables. 0544 0545 :: 0546 0547 &DIAGNOSTICS_LIST 0548 # --- 0549 fields(1:5,1) = 'ADJtheta','ADJsalt ', 0550 'ADJuvel ','ADJvvel ','ADJwvel ' 0551 filename(1) = 'diags/adjState_3d_snaps', 0552 frequency(1)=-86400.0, 0553 timePhase(1)=0.0, 0554 #--- 0555 fields(1:5,2) = 'ADJtheta','ADJsalt ', 0556 'ADJuvel ','ADJvvel ','ADJwvel ' 0557 filename(2) = 'diags/adjState_3d_avg', 0558 frequency(2)= 86400.0, 0559 #--- 0560 & 0561 ba0b047096 Mart*0562 Note: the diagnostics package automatically provides a phase shift of :math:`frequency/2`, a5ec81ed49 Timo*0563 so specify `timePhase = 0` to match output from `adjDumpFreq`. 0564 0565 9ce7d74115 Jeff*0566 Adding new diagnostics to the code 0567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0568 0569 In order to define and include as part of the diagnostic output any 0570 field that is desired for a particular experiment, two steps must be** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 572.
0571 taken. The first is to enable the “User Diagnostic” in ``data.diagnostics``.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 573.
0572 This is accomplished by adding one of the “User Diagnostic” field names 0573 (see :ref:`available diagnostics <diagnostics_list>`):``UDIAG1`` through ``UDIAG10``, 0574 for multi-level fields, or ``SDIAG1`` through 0575 ``SDIAG10`` for single level fields) to the ``data.diagnostics`` namelist in one ba0b047096 Mart*0576 of the output streams. 9ce7d74115 Jeff*0577 The second step is to add a call to 0578 :filelink:`diagnostics_fill.F <pkg/diagnostics/diagnostics_fill.F>` from the 0579 subroutine in which the quantity desired for diagnostic output is 0580 computed. 0581 0582 In order to add a new diagnostic to the permanent set of diagnostics 0583 that the main model or any package contains as part of its diagnostics 0584 menu, the subroutine :filelink:`diagnostics_addtolist.F <pkg/diagnostics/diagnostics_addtolist.F>` 0585 should be called during the 0586 initialization phase of the main model or package. For the main model, 0587 the call should be made from subroutine 0588 :filelink:`diagnostics_main_init.F <pkg/diagnostics/diagnostics_main_init.F>`, and for 0589 a package, the call should probably be made from from inside the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 591.
0590 particular package’s init\_fixed routine. A typical code sequence to set 0591 the input arguments to :filelink:`diagnostics_addtolist.F <pkg/diagnostics/diagnostics_addtolist.F>` would look like: 0592 0593 :: 0594 0595 diagName = 'RHOAnoma' 0596 diagTitle = 'Density Anomaly (=Rho-rhoConst)' 0597 diagUnits = 'kg/m^3 ' 0598 diagCode = 'SMR MR ' 0599 CALL DIAGNOSTICS\_ADDTOLIST( diagNum, 0600 I diagName, diagCode, diagUnits, diagTitle, 0, myThid ) 0601 0602 If the new diagnostic quantity is associated with either a vector pair 0603 or a diagnostic counter, the :varlink:`diagMate` argument must be provided with the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 605.
0604 proper index corresponding to the “mate”. The output argument from 0605 :filelink:`diagnostics_addtolist.F <pkg/diagnostics/diagnostics_addtolist.F>` 0606 that is called :varlink:`diagNum` here contains a running 0607 total of the number of diagnostics defined in the code up to any point 0608 during the run. The sequence number for the next two diagnostics defined 0609 (the two components of the vector pair, for instance) will be :varlink:`diagNum`\+1 0610 and :varlink:`diagNum`\+2. The definition of the first component of the vector pair** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 612.
0611 must fill the “mate” segment of the :varlink:`diagCode` as diagnostic number 0612 :varlink:`diagNum`\+2. Since the subroutine increments :varlink:`diagNum`, the definition of** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 614.
0613 the second component of the vector fills the “mate” part of :varlink:`diagCode` 0614 with :varlink:`diagNum`. A code sequence for this case would look like: 0615 0616 :: 0617 0618 diagName = 'UVEL ' 0619 diagTitle = 'Zonal Component of Velocity (m/s)' 0620 diagUnits = 'm/s ' 0621 diagCode = 'UUR MR ' 0622 diagMate = diagNum + 2 0623 CALL DIAGNOSTICS_ADDTOLIST( diagNum, 0624 I diagName, diagCode, diagUnits, diagTitle, diagMate, myThid ) 0625 0626 diagName = 'VVEL ' 0627 diagTitle = 'Meridional Component of Velocity (m/s)' 0628 diagUnits = 'm/s ' 0629 diagCode = 'VVR MR ' 0630 diagMate = diagNum 0631 CALL DIAGNOSTICS_ADDTOLIST( diagNum, 0632 I diagName, diagCode, diagUnits, diagTitle, diagMate, myThid ) 0633 0634 0635 .. _diagnostics_list: 0636 0637 0638 MITgcm kernel available diagnostics list: 0639 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0640 0641 :: 0642 94ce2f298c Oliv*0643 --------------------------------------------------------------- 0644 <-Name->|<- code ->|<-- Units -->|<- Tile (max=80c) 0645 ------------------------------------------------------------------------ 0646 SDIAG1 |SM L1|user-defined |User-Defined Surface Diagnostic #1 0647 SDIAG2 |SM L1|user-defined |User-Defined Surface Diagnostic #2 0648 SDIAG3 |SM L1|user-defined |User-Defined Surface Diagnostic #3 0649 SDIAG4 |SM L1|user-defined |User-Defined Surface Diagnostic #4 0650 SDIAG5 |SM L1|user-defined |User-Defined Surface Diagnostic #5 0651 SDIAG6 |SM L1|user-defined |User-Defined Surface Diagnostic #6 0652 SDIAG7 |SU L1|user-defined |User-Defined U.pt Surface Diagnostic #7 0653 SDIAG8 |SV L1|user-defined |User-Defined V.pt Surface Diagnostic #8 0654 SDIAG9 |UU L1|user-defined |User-Defined U.vector Surface Diag. #9 0655 SDIAG10 |VV L1|user-defined |User-Defined V.vector Surface Diag. #10 0656 UDIAG1 |SM MR|user-defined |User-Defined Model-Level Diagnostic #1 0657 UDIAG2 |SM MR|user-defined |User-Defined Model-Level Diagnostic #2 0658 UDIAG3 |SMR MR|user-defined |User-Defined Model-Level Diagnostic #3 0659 UDIAG4 |SMR MR|user-defined |User-Defined Model-Level Diagnostic #4 0660 UDIAG5 |SU MR|user-defined |User-Defined U.pt Model-Level Diag. #5 0661 UDIAG6 |SV MR|user-defined |User-Defined V.pt Model-Level Diag. #6 0662 UDIAG7 |UUR MR|user-defined |User-Defined U.vector Model-Lev Diag.#7 0663 UDIAG8 |VVR MR|user-defined |User-Defined V.vector Model-Lev Diag.#8 0664 UDIAG9 |SM ML|user-defined |User-Defined Phys-Level Diagnostic #9 0665 UDIAG10 |SM ML|user-defined |User-Defined Phys-Level Diagnostic #10 0666 SDIAGC |SM C L1|user-defined |User-Defined Counted Surface Diagnostic 0667 SDIAGCC |SM L1|count |User-Defined Surface Diagnostic Counter 0668 ETAN |SM M1|m |Surface Height Anomaly 0669 ETANSQ |SM P M1|m^2 |Square of Surface Height Anomaly 0670 DETADT2 |SM M1|m^2/s^2 |Square of Surface Height Anomaly Tendency 0671 THETA |SMR MR|degC |Potential Temperature 9a969add02 Oliv*0672 SALT |SMR MR|g/kg |Salinity 94ce2f298c Oliv*0673 RELHUM |SMR MR|percent |Relative Humidity 9a969add02 Oliv*0674 SALTanom|SMR MR|g/kg |Salt anomaly (=SALT-35; g/kg) 94ce2f298c Oliv*0675 UVEL |UUR MR|m/s |Zonal Component of Velocity (m/s) 0676 VVEL |VVR MR|m/s |Meridional Component of Velocity (m/s) 0677 WVEL |WM LR|m/s |Vertical Component of Velocity (r_units/s) 0678 THETASQ |SMRP MR|degC^2 |Square of Potential Temperature 9a969add02 Oliv*0679 SALTSQ |SMRP MR|(g/kg)^2 |Square of Salinity 0680 SALTSQan|SMRP MR|(g/kg)^2 |Square of Salt anomaly (=(SALT-35)^2 (g^2/kg^2) 94ce2f298c Oliv*0681 UVELSQ |UURP MR|m^2/s^2 |Square of Zonal Comp of Velocity (m^2/s^2) 0682 VVELSQ |VVRP MR|m^2/s^2 |Square of Meridional Comp of Velocity (m^2/s^2) 0683 WVELSQ |WM P LR|m^2/s^2 |Square of Vertical Comp of Velocity 0684 UE_VEL_C|UMR MR|m/s |Eastward Velocity (m/s) (cell center) 0685 VN_VEL_C|VMR MR|m/s |Northward Velocity (m/s) (cell center) 0686 UV_VEL_C|UMR MR|m^2/s^2 |Product of horizontal Comp of velocity (cell center) 0687 UV_VEL_Z|UZR MR|m^2/s^2 |Meridional Transport of Zonal Momentum (m^2/s^2) 0688 WU_VEL |WU LR|m.m/s^2 |Vertical Transport of Zonal Momentum 0689 WV_VEL |WV LR|m.m/s^2 |Vertical Transport of Meridional Momentum 0690 UVELMASS|UUr MR|m/s |Zonal Mass-Weighted Comp of Velocity (m/s) 0691 VVELMASS|VVr MR|m/s |Meridional Mass-Weighted Comp of Velocity (m/s) 0692 WVELMASS|WM LR|m/s |Vertical Mass-Weighted Comp of Velocity 0693 PhiVEL |SMR P MR|m^2/s |Horizontal Velocity Potential (m^2/s) 0694 PsiVEL |SZ P MR|m.m^2/s |Horizontal Velocity Stream-Function 0695 UTHMASS |UUr MR|degC.m/s |Zonal Mass-Weight Transp of Pot Temp 0696 VTHMASS |VVr MR|degC.m/s |Meridional Mass-Weight Transp of Pot Temp 0697 WTHMASS |WM LR|degC.m/s |Vertical Mass-Weight Transp of Pot Temp (K.m/s) 9a969add02 Oliv*0698 USLTMASS|UUr MR|g/kg.m/s |Zonal Mass-Weight Transp of Salinity 0699 VSLTMASS|VVr MR|g/kg.m/s |Meridional Mass-Weight Transp of Salinity 0700 WSLTMASS|WM LR|g/kg.m/s |Vertical Mass-Weight Transp of Salinity 94ce2f298c Oliv*0701 UVELTH |UUR MR|degC.m/s |Zonal Transport of Pot Temp 0702 VVELTH |VVR MR|degC.m/s |Meridional Transport of Pot Temp 0703 WVELTH |WM LR|degC.m/s |Vertical Transport of Pot Temp 9a969add02 Oliv*0704 UVELSLT |UUR MR|g/kg.m/s |Zonal Transport of Salinity 0705 VVELSLT |VVR MR|g/kg.m/s |Meridional Transport of Salinity 0706 WVELSLT |WM LR|g/kg.m/s |Vertical Transport of Salinity 94ce2f298c Oliv*0707 UVELPHI |UUr MR|m^3/s^3 |Zonal Mass-Weight Transp of Pressure Pot.(p/rho) Anomaly 0708 VVELPHI |VVr MR|m^3/s^3 |Merid. Mass-Weight Transp of Pressure Pot.(p/rho) Anomaly 0709 RHOAnoma|SMR MR|kg/m^3 |Density Anomaly (=Rho-rhoConst) 0710 RHOANOSQ|SMRP MR|kg^2/m^6 |Square of Density Anomaly (=(Rho-rhoConst)^2) 0711 URHOMASS|UUr MR|kg/m^2/s |Zonal Transport of Density 0712 VRHOMASS|VVr MR|kg/m^2/s |Meridional Transport of Density 0713 WRHOMASS|WM LR|kg/m^2/s |Vertical Transport of Density 0714 WdRHO_P |WM LR|kg/m^2/s |Vertical velocity times delta^k(Rho)_at-const-P 0715 WdRHOdP |WM LR|kg/m^2/s |Vertical velocity times delta^k(Rho)_at-const-T,S 0716 PHIHYD |SMR MR|m^2/s^2 |Hydrostatic Pressure Pot.(p/rho) Anomaly 0717 PHIHYDSQ|SMRP MR|m^4/s^4 |Square of Hyd. Pressure Pot.(p/rho) Anomaly 0718 PHIBOT |SM M1|m^2/s^2 |Bottom Pressure Pot.(p/rho) Anomaly 0719 PHIBOTSQ|SM P M1|m^4/s^4 |Square of Bottom Pressure Pot.(p/rho) Anomaly 9a969add02 Oliv*0720 PHI_SURF|SM M1|m^2/s^2 |Surface Dynamical Pressure Pot.(p/rho) 94ce2f298c Oliv*0721 PHIHYDcR|SMR MR|m^2/s^2 |Hydrostatic Pressure Pot.(p/rho) Anomaly @ const r 9a969add02 Oliv*0722 PHI_NH |SMR MR|m^2/s^2 |Non-Hydrostatic Pressure Pot.(p/rho) 94ce2f298c Oliv*0723 MXLDEPTH|SM M1|m |Mixed-Layer Depth (>0) 0724 DRHODR |SM LR|kg/m^4 |Stratification: d.Sigma/dr (kg/m3/r_unit) 0725 CONVADJ |SMR LR|fraction |Convective Adjustment Index [0-1] 0726 oceTAUX |UU U1|N/m^2 |zonal surface wind stress, >0 increases uVel 0727 oceTAUY |VV U1|N/m^2 |meridional surf. wind stress, >0 increases vVel 9a969add02 Oliv*0728 atmPload|SM U1|Pa |Atmospheric pressure loading anomaly (vs surf_pRef) 94ce2f298c Oliv*0729 sIceLoad|SM U1|kg/m^2 |sea-ice loading (in Mass of ice+snow / area unit) 0730 oceFWflx|SM U1|kg/m^2/s |net surface Fresh-Water flux into the ocean (+=down), >0 decreases salinity 0731 oceSflux|SM U1|g/m^2/s |net surface Salt flux into the ocean (+=down), >0 increases salinity 0732 oceQnet |SM U1|W/m^2 |net surface heat flux into the ocean (+=down), >0 increases theta 0733 oceQsw |SM U1|W/m^2 |net Short-Wave radiation (+=down), >0 increases theta 0734 oceFreez|SM U1|W/m^2 |heating from freezing of sea-water (allowFreezing=T) 0735 TRELAX |SM U1|W/m^2 |surface temperature relaxation, >0 increases theta 0736 SRELAX |SM U1|g/m^2/s |surface salinity relaxation, >0 increases salt 0737 surForcT|SM U1|W/m^2 |model surface forcing for Temperature, >0 increases theta 0738 surForcS|SM U1|g/m^2/s |model surface forcing for Salinity, >0 increases salinity 0739 TFLUX |SM U1|W/m^2 |total heat flux (match heat-content variations), >0 increases theta 0740 SFLUX |SM U1|g/m^2/s |total salt flux (match salt-content variations), >0 increases salt 0741 RCENTER |SM MR|m |Cell-Center Height 0742 RSURF |SM M1|m |Surface Height 9a969add02 Oliv*0743 hFactorC|SMr MR|1 |Center cell-thickness fraction [-] 0744 hFactorW|SUr MR|1 |Western-Edge cell-thickness fraction [-] 0745 hFactorS|SVr MR|1 |Southern-Edge cell-thickness fraction [-] 94ce2f298c Oliv*0746 TOTUTEND|UUR MR|m/s/day |Tendency of Zonal Component of Velocity 0747 TOTVTEND|VVR MR|m/s/day |Tendency of Meridional Component of Velocity 0748 TOTTTEND|SMR MR|degC/day |Tendency of Potential Temperature 9a969add02 Oliv*0749 TOTSTEND|SMR MR|g/kg/day |Tendency of Salinity 94ce2f298c Oliv*0750 --------------------------------------------------------------- 0751 <-Name->|<- code ->|<-- Units -->|<- Tile (max=80c) 0752 --------------------------------------------------------------- 0753 MoistCor|SM MR|W/m^2 |Heating correction due to moist thermodynamics 9a969add02 Oliv*0754 HeatDiss|SM MR|W/m^2 |Heating from frictional dissipation 94ce2f298c Oliv*0755 gT_Forc |SMR MR|degC/s |Potential Temp. forcing tendency 9a969add02 Oliv*0756 gS_Forc |SMR MR|g/kg/s |Salinity forcing tendency 94ce2f298c Oliv*0757 AB_gT |SMR MR|degC/s |Potential Temp. tendency from Adams-Bashforth 9a969add02 Oliv*0758 AB_gS |SMR MR|g/kg/s |Salinity tendency from Adams-Bashforth 94ce2f298c Oliv*0759 gTinAB |SMR MR|degC/s |Potential Temp. tendency going in Adams-Bashforth 9a969add02 Oliv*0760 gSinAB |SMR MR|g/kg/s |Salinity tendency going in Adams-Bashforth 94ce2f298c Oliv*0761 AB_gU |UUR MR|m/s^2 |U momentum tendency from Adams-Bashforth 0762 AB_gV |VVR MR|m/s^2 |V momentum tendency from Adams-Bashforth 9a969add02 Oliv*0763 AB_gW |WM LR|m/s^2 |W momentum tendency from Adams-Bashforth 0764 TAUXEDDY|UU LR|N/m^2 |Zonal Eddy Stress 0765 TAUYEDDY|VV LR|N/m^2 |Meridional Eddy Stress 0766 U_EulerM|UUR MR|m/s |Zonal Eulerian-Mean Velocity (m/s) 0767 V_EulerM|VVR MR|m/s |Meridional Eulerian-Mean Velocity (m/s) 94ce2f298c Oliv*0768 ADVr_TH |WM LR|degC.m^3/s |Vertical Advective Flux of Pot.Temperature 0769 ADVx_TH |UU MR|degC.m^3/s |Zonal Advective Flux of Pot.Temperature 0770 ADVy_TH |VV MR|degC.m^3/s |Meridional Advective Flux of Pot.Temperature 0771 DFrE_TH |WM LR|degC.m^3/s |Vertical Diffusive Flux of Pot.Temperature (Explicit part) 0772 DFxE_TH |UU MR|degC.m^3/s |Zonal Diffusive Flux of Pot.Temperature 0773 DFyE_TH |VV MR|degC.m^3/s |Meridional Diffusive Flux of Pot.Temperature 0774 DFrI_TH |WM LR|degC.m^3/s |Vertical Diffusive Flux of Pot.Temperature (Implicit part) 0775 SM_x_TH |UM MR|degC |Pot.Temp. 1rst Order Moment Sx 0776 SM_y_TH |VM MR|degC |Pot.Temp. 1rst Order Moment Sy 0777 SM_z_TH |SM MR|degC |Pot.Temp. 1rst Order Moment Sz 0778 SMxx_TH |UM MR|degC |Pot.Temp. 2nd Order Moment Sxx 0779 SMyy_TH |VM MR|degC |Pot.Temp. 2nd Order Moment Syy 0780 SMzz_TH |SM MR|degC |Pot.Temp. 2nd Order Moment Szz 0781 SMxy_TH |SM MR|degC |Pot.Temp. 2nd Order Moment Sxy 0782 SMxz_TH |UM MR|degC |Pot.Temp. 2nd Order Moment Sxz 0783 SMyz_TH |VM MR|degC |Pot.Temp. 2nd Order Moment Syz 0784 SM_v_TH |SM P MR|(degC)^2 |Pot.Temp. sub-grid variance 9a969add02 Oliv*0785 ADVr_SLT|WM LR|g/kg.m^3/s |Vertical Advective Flux of Salinity 0786 ADVx_SLT|UU MR|g/kg.m^3/s |Zonal Advective Flux of Salinity 0787 ADVy_SLT|VV MR|g/kg.m^3/s |Meridional Advective Flux of Salinity 0788 DFrE_SLT|WM LR|g/kg.m^3/s |Vertical Diffusive Flux of Salinity (Explicit part) 0789 DFxE_SLT|UU MR|g/kg.m^3/s |Zonal Diffusive Flux of Salinity 0790 DFyE_SLT|VV MR|g/kg.m^3/s |Meridional Diffusive Flux of Salinity 0791 DFrI_SLT|WM LR|g/kg.m^3/s |Vertical Diffusive Flux of Salinity (Implicit part) 0792 SALTFILL|SM MR|g/kg.m^3/s |Filling of Negative Values of Salinity 0793 SM_x_SLT|UM MR|g/kg |Salinity 1rst Order Moment Sx 0794 SM_y_SLT|VM MR|g/kg |Salinity 1rst Order Moment Sy 0795 SM_z_SLT|SM MR|g/kg |Salinity 1rst Order Moment Sz 0796 SMxx_SLT|UM MR|g/kg |Salinity 2nd Order Moment Sxx 0797 SMyy_SLT|VM MR|g/kg |Salinity 2nd Order Moment Syy 0798 SMzz_SLT|SM MR|g/kg |Salinity 2nd Order Moment Szz 0799 SMxy_SLT|SM MR|g/kg |Salinity 2nd Order Moment Sxy 0800 SMxz_SLT|UM MR|g/kg |Salinity 2nd Order Moment Sxz 0801 SMyz_SLT|VM MR|g/kg |Salinity 2nd Order Moment Syz 0802 SM_v_SLT|SM P MR|(g/kg)^2 |Salinity sub-grid variance 94ce2f298c Oliv*0803 VISCAHZ |SZ MR|m^2/s |Harmonic Visc Coefficient (m2/s) (Zeta Pt) 0804 VISCA4Z |SZ MR|m^4/s |Biharmonic Visc Coefficient (m4/s) (Zeta Pt) 0805 VISCAHD |SM MR|m^2/s |Harmonic Viscosity Coefficient (m2/s) (Div Pt) 0806 VISCA4D |SM MR|m^4/s |Biharmonic Viscosity Coefficient (m4/s) (Div Pt) 0807 VISCAHW |WM LR|m^2/s |Harmonic Viscosity Coefficient (m2/s) (W Pt) 0808 VISCA4W |WM LR|m^4/s |Biharmonic Viscosity Coefficient (m4/s) (W Pt) 0809 VAHZMAX |SZ MR|m^2/s |CFL-MAX Harm Visc Coefficient (m2/s) (Zeta Pt) 0810 VA4ZMAX |SZ MR|m^4/s |CFL-MAX Biharm Visc Coefficient (m4/s) (Zeta Pt) 0811 VAHDMAX |SM MR|m^2/s |CFL-MAX Harm Visc Coefficient (m2/s) (Div Pt) 0812 VA4DMAX |SM MR|m^4/s |CFL-MAX Biharm Visc Coefficient (m4/s) (Div Pt) 0813 VAHZMIN |SZ MR|m^2/s |RE-MIN Harm Visc Coefficient (m2/s) (Zeta Pt) 0814 VA4ZMIN |SZ MR|m^4/s |RE-MIN Biharm Visc Coefficient (m4/s) (Zeta Pt) 0815 VAHDMIN |SM MR|m^2/s |RE-MIN Harm Visc Coefficient (m2/s) (Div Pt) 0816 VA4DMIN |SM MR|m^4/s |RE-MIN Biharm Visc Coefficient (m4/s) (Div Pt) 0817 VAHZLTH |SZ MR|m^2/s |Leith Harm Visc Coefficient (m2/s) (Zeta Pt) 0818 VA4ZLTH |SZ MR|m^4/s |Leith Biharm Visc Coefficient (m4/s) (Zeta Pt) 0819 VAHDLTH |SM MR|m^2/s |Leith Harm Visc Coefficient (m2/s) (Div Pt) 0820 VA4DLTH |SM MR|m^4/s |Leith Biharm Visc Coefficient (m4/s) (Div Pt) 0821 VAHZLTHD|SZ MR|m^2/s |LeithD Harm Visc Coefficient (m2/s) (Zeta Pt) 0822 VA4ZLTHD|SZ MR|m^4/s |LeithD Biharm Visc Coefficient (m4/s) (Zeta Pt) 0823 VAHDLTHD|SM MR|m^2/s |LeithD Harm Visc Coefficient (m2/s) (Div Pt) 0824 VA4DLTHD|SM MR|m^4/s |LeithD Biharm Visc Coefficient (m4/s) (Div Pt) 9a969add02 Oliv*0825 VAHZLTHQ|SZ MR|m^2/s |LeithQG Harm Visc Coefficient (m2/s) (Zeta Pt) 0826 VAHDLTHQ|SM MR|m^2/s |LeithQG Harm Visc Coefficient (m2/s) (Div Pt) 94ce2f298c Oliv*0827 VAHZSMAG|SZ MR|m^2/s |Smagorinsky Harm Visc Coefficient (m2/s) (Zeta Pt) 0828 VA4ZSMAG|SZ MR|m^4/s |Smagorinsky Biharm Visc Coeff. (m4/s) (Zeta Pt) 0829 VAHDSMAG|SM MR|m^2/s |Smagorinsky Harm Visc Coefficient (m2/s) (Div Pt) 0830 VA4DSMAG|SM MR|m^4/s |Smagorinsky Biharm Visc Coeff. (m4/s) (Div Pt) 0831 momKE |SMR MR|m^2/s^2 |Kinetic Energy (in momentum Eq.) 0832 momHDiv |SMR MR|s^-1 |Horizontal Divergence (in momentum Eq.) 0833 momVort3|SZR MR|s^-1 |3rd component (vertical) of Vorticity 0834 Strain |SZR MR|s^-1 |Horizontal Strain of Horizontal Velocities 0835 Tension |SMR MR|s^-1 |Horizontal Tension of Horizontal Velocities 9a969add02 Oliv*0836 Stretch |SM MR|s^-1 |Vortex stretching from QG Leith dynamic viscosity 94ce2f298c Oliv*0837 USidDrag|UUR MR|m/s^2 |U momentum tendency from Side Drag 0838 VSidDrag|VVR MR|m/s^2 |V momentum tendency from Side Drag 9a969add02 Oliv*0839 Um_Diss |UUR MR|m/s^2 |U momentum tendency from Dissipation (Explicit part) 0840 Vm_Diss |VVR MR|m/s^2 |V momentum tendency from Dissipation (Explicit part) 0841 Um_ImplD|UUR MR|m/s^2 |U momentum tendency from Dissipation (Implicit part) 0842 Vm_ImplD|VVR MR|m/s^2 |V momentum tendency from Dissipation (Implicit part) 94ce2f298c Oliv*0843 Um_Advec|UUR MR|m/s^2 |U momentum tendency from Advection terms 0844 Vm_Advec|VVR MR|m/s^2 |V momentum tendency from Advection terms 0845 Um_Cori |UUR MR|m/s^2 |U momentum tendency from Coriolis term 0846 Vm_Cori |VVR MR|m/s^2 |V momentum tendency from Coriolis term 9a969add02 Oliv*0847 Um_dPhiX|UUR MR|m/s^2 |U momentum tendency from Pressure/Potential grad 0848 Vm_dPhiY|VVR MR|m/s^2 |V momentum tendency from Pressure/Potential grad 94ce2f298c Oliv*0849 Um_Ext |UUR MR|m/s^2 |U momentum tendency from external forcing 0850 Vm_Ext |VVR MR|m/s^2 |V momentum tendency from external forcing 0851 Um_AdvZ3|UUR MR|m/s^2 |U momentum tendency from Vorticity Advection 0852 Vm_AdvZ3|VVR MR|m/s^2 |V momentum tendency from Vorticity Advection 0853 Um_AdvRe|UUR MR|m/s^2 |U momentum tendency from vertical Advection (Explicit part) 0854 Vm_AdvRe|VVR MR|m/s^2 |V momentum tendency from vertical Advection (Explicit part) 9a969add02 Oliv*0855 Wm_Diss |WMr LR|m/s^2 |W momentum tendency from Dissipation 0856 Wm_Advec|WMr LR|m/s^2 |W momentum tendency from Advection terms 0857 WSidDrag|WMr LR|m/s^2 |Vertical momentum tendency from Side Drag 0858 botTauX |UU U1|N/m^2 |zonal bottom stress, >0 increases uVel 0859 botTauY |VV U1|N/m^2 |meridional bottom stress, >0 increases vVel 0860 ADVx_Um |UM MR|m^4/s^2 |Zonal Advective Flux of U momentum 0861 ADVy_Um |VZ MR|m^4/s^2 |Meridional Advective Flux of U momentum 0862 ADVrE_Um|WU LR|m^4/s^2 |Vertical Advective Flux of U momentum (Explicit part) 0863 ADVx_Vm |UZ MR|m^4/s^2 |Zonal Advective Flux of V momentum 0864 ADVy_Vm |VM MR|m^4/s^2 |Meridional Advective Flux of V momentum 0865 ADVrE_Vm|WV LR|m^4/s^2 |Vertical Advective Flux of V momentum (Explicit part) 0866 VISCx_Um|UM MR|m^4/s^2 |Zonal Viscous Flux of U momentum 0867 VISCy_Um|VZ MR|m^4/s^2 |Meridional Viscous Flux of U momentum 0868 VISrE_Um|WU LR|m^4/s^2 |Vertical Viscous Flux of U momentum (Explicit part) 94ce2f298c Oliv*0869 VISrI_Um|WU LR|m^4/s^2 |Vertical Viscous Flux of U momentum (Implicit part) 9a969add02 Oliv*0870 VISCx_Vm|UZ MR|m^4/s^2 |Zonal Viscous Flux of V momentum 0871 VISCy_Vm|VM MR|m^4/s^2 |Meridional Viscous Flux of V momentum 0872 VISrE_Vm|WV LR|m^4/s^2 |Vertical Viscous Flux of V momentum (Explicit part) 94ce2f298c Oliv*0873 VISrI_Vm|WV LR|m^4/s^2 |Vertical Viscous Flux of V momentum (Implicit part) 9ce7d74115 Jeff*0874 95e7dbd5d6 Oliv*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 876.
0875 The meaning of the “code” column is explained in 16a282d98d Jeff*0876 :numref:`diagnostic_parsing_array`. The last character of the code, in particular, 0877 determines the number of vertical levels in the diagnostic (of the commonly used codes, 0878 "1" represents a 2-D diagnostic, "R" and "L" are multi-level diagnostics). 9ce7d74115 Jeff*0879 0880 MITgcm packages: available diagnostics lists 0881 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0882 0883 For a list of the diagnostic fields available in the different MITgcm 0884 packages, follow the link to the available diagnostics listing in the manual section 0885 describing the package: 0886 0887 - :filelink:`pkg/aim_v23`: :ref:`available diagnostics <aim_diagnostics>` 0888 0889 - :filelink:`pkg/exf`: :ref:`available diagnostics <ssub_phys_pkg_exf_diagnostics>` 0890 0891 - :filelink:`pkg/gchem`: :ref:`available diagnostics <gchem_diagnostics>` 0892 0893 - :filelink:`pkg/generic_advdiff`: :ref:`available diagnostics <gad_diagnostics>` 0894 0895 - :filelink:`pkg/gridalt`: :ref:`available diagnostics <gridalt_diagnostics>` 0896 0897 - :filelink:`pkg/gmredi`: :ref:`available diagnostics <ssub_phys_pkg_gmredi_diagnostics>` 0898 0899 - :filelink:`pkg/fizhi`: :ref:`available diagnostics <fizhi_diagnostics>` 0900 0901 - :filelink:`pkg/kpp`: :ref:`available diagnostics <ssub_phys_pkg_kpp_diagnostics>` 0902 0903 - :filelink:`pkg/land`: :ref:`available diagnostics <land_diagnostics>` 0904 0905 - :filelink:`pkg/mom_common`: :ref:`available diagnostics <mom_diagnostics>` 0906 0907 - :filelink:`pkg/obcs`: :ref:`available diagnostics <ssub_phys_pkg_obcs_diagnostics>` 0908 0909 - :filelink:`pkg/thsice`: :ref:`available diagnostics <thsice_diagnostics>` 0910 0911 - :filelink:`pkg/seaice`: :ref:`available diagnostics <ssub_phys_pkg_seaice_diagnostics>` 0912 0913 - :filelink:`pkg/shap_filt`: :ref:`available diagnostics <shapiro_diagnostics>` 0914 0915 - :filelink:`pkg/ptracers`: :ref:`available diagnostics <ptracers_diagnostics>` 0916 0917 0918 .. _pkg_mdsio: 0919 0920 Fortran Native I/O: pkg/mdsio and pkg/rw 0921 ======================================== 0922 0923 pkg/mdsio 0924 --------- 0925 0926 Introduction 0927 ~~~~~~~~~~~~ 0928 0929 :filelink:`pkg/mdsio` contains a group of Fortran routines intended as a** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 931.
0930 general interface for reading and writing direct-access (“binary”) 0931 Fortran files. :filelink:`pkg/mdsio` routines are used by :filelink:`pkg/rw`. 0932 0933 Using pkg/mdsio 0934 ~~~~~~~~~~~~~~~ 0935 0936 :filelink:`pkg/mdsio` is geared toward the reading and writing of 0937 floating point (Fortran ``REAL*4`` or ``REAL*8``) arrays. It assumes 0938 that the in-memory layout of all arrays follows the per-tile MITgcm 0939 convention 0940 0941 :: 0942 0943 C Example of a "2D" array 0944 _RL anArray(1-OLx:sNx+OLx,1-OLy:sNy+OLy,nSx,nSy) 0945 0946 C Example of a "3D" array 0947 _RL anArray(1-OLx:sNx+OLx,1-OLy:sNy+OLy,1:Nr,nSx,nSy) 0948** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 950.
0949 where the first two dimensions are spatial or “horizontal” indicies that** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 951.
0950 include a “halo” or exchange region (please see :numref:`sarch` and 0951 :numref:`sub_phys_pkg_exch2` which describe domain decomposition), and the remaining 0952 indicies (``Nr``, ``nSx``, and ``nSx``) are often present but may or may not be necessary for a specific variable.. 0953 0954 In order to write output, :filelink:`pkg/mdsio` is called with a 0955 function such as: 0956 0957 :: 0958 0959 CALL MDSWRITEFIELD(fn,prec,lgf,typ,Nr,arr,irec,myIter,myThid) 0960 0961 where: 0962 0963 ``fn``** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 965.
0964 is a ``CHARACTER`` string containing a file “base” name which 0965 will then be used to create file names that contain tile and/or 0966 model iteration indicies 0967 0968 ``prec`` 0969 is an integer that contains one of two globally defined values 0970 (``precFloat64`` or ``precFloat32``) 0971 0972 ``lgf`` 0973 is a ``LOGICAL`` that typically contains the globally defined 0974 ``globalFile`` option which specifies the creation of globally 0975 (spatially) concatenated files 0976 0977 ``typ`` 0978 is a ``CHARACTER`` string that specifies the type of the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 980.
0979 variable being written (``’RL’`` or ``’RS’``) 0980 0981 ``Nr`` 0982 is an integer that specifies the number of vertical levels 0983 within the variable being written 0984 0985 ``arr`` 0986 is the variable (array) to be written 0987 0988 ``irec`` 0989 is the starting record within the output file that will contain 0990 the array 0991 0992 ``myIter,myThid`` 0993 are integers containing, respectively, the current model 0994 iteration count and the unique thread ID for the current context 0995 of execution 0996 0997 As one can see from the above (generic) example, enough information is 0998 made available (through both the argument list and through common 0999 blocks) for :filelink:`pkg/mdsio` to perform the following tasks: 1000 1001 #. open either a per-tile file such as: 1002 1003 ``uVel.0000302400.003.001.data`` 1004** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1006.
1005 or a “global” file such as 1006 1007 ``uVel.0000302400.data`` 1008 1009 #. byte-swap (as necessary) the input array and write its contents** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1011.
1010 (minus any halo information) to the binary file – or to the correct 1011 location within the binary file if the ``globalfile`` option is used, and 1012** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1014.
1013 #. create an ASCII–text metadata file (same name as the binary but with 1014 a ``.meta`` extension) describing the binary file contents (often, 1015 for later use with the MATLAB :filelink:`rdmds() <utils/matlab/rdmds.m>` utility). 1016 1017 Reading output with :filelink:`pkg/mdsio` is very similar to writing it. A typical 1018 function call is 1019 1020 :: 1021 1022 CALL MDSREADFIELD(fn,prec,typ,Nr,arr,irec,myThid) 1023 1024 where variables are exactly the same as the ``MDSWRITEFIELD`` example 1025 provided above. It is important to note that the ``lgf`` argument is 1026 missing from the ``MDSREADFIELD`` function. By default, :filelink:`pkg/mdsio` will 1027 first try to read from an appropriately named global file and, failing 1028 that, will try to read from a per-tile file. 1029 1030 Important considerations 1031 ~~~~~~~~~~~~~~~~~~~~~~~~ 1032 1033 When using :filelink:`pkg/mdsio`, one should be aware of the following package 1034 features and limitations: 1035 1036 - **Byte-swapping:** 1037 For the most part, byte-swapping is gracefully handled. All files intended for 1038 reading/writing by :filelink:`pkg/mdsio` should contain big-endian (sometimes** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1040.
1039 called “network byte order”) data. By handling byte-swapping within 1040 the model, MITgcm output is more easily ported between different 1041 machines, architectures, compilers, etc. Byteswapping can be turned 21d0859333 Oliv*1042 on/off at compile time within :filelink:`pkg/mdsio` using the ``_BYTESWAPIO`` 9ce7d74115 Jeff*1043 CPP macro which is usually set within a :filelink:`genmake2 <tools/genmake2>` options file or 1044 ``optfile`` (see :numref:`genmake2_optfiles`). 1045 Additionally, some compilers may have byte-swap options that are 1046 speedier or more convenient to use. 1047 1048 - **Data types:** e2c4ac4a43 Ed D*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1050.
1049 Data types are currently limited to single– or double–precision floating point 9ce7d74115 Jeff*1050 values. These values can be converted, on-the-fly, from one to the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1052.
1051 other so that any combination of either single– or double–precision 1052 variables can be read from or written to files containing either** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1054.
1053 single– or double–precision data. 1054 1055 - **Array sizes:** 1056 Array sizes are limited; :filelink:`pkg/mdsio` is very much geared towards the 1057 reading/writing of per-tile (that is, domain-decomposed and halo-ed)** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1059.
1058 arrays. Data that cannot be made to “fit” within these assumed sizes 1059 can be challenging to read or write with :filelink:`pkg/mdsio`. 1060 1061 - **Tiling:** 1062 Tiling or domain decomposition is automatically handled by :filelink:`pkg/mdsio` for 1063 logically rectangular grid topologies (e.g., lat-lon grids) and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1065.
1064 “standard” cubed sphere topologies. More complicated topologies will 1065 probably not be supported. :filelink:`pkg/mdsio` can, without any 1066 coding changes, read and write to/from files that were run on the 1067 same global grid but with different tiling (grid decomposition) 1068 schemes. For example, :filelink:`pkg/mdsio` can use and/or create identical** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1070.
1069 input/output files for a “C32” cube when the model is run with 1070 either 6, 12, or 24 tiles (corresponding to 1, 2 or 4 tiles per 1071 cubed sphere face). This is one of the primary advantages 1072 that the :filelink:`pkg/mdsio` package has over :filelink:`pkg/mnc`. 1073 1074 - **Single-CPU I/O:** 1075 This option can be specified with the flag** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1077.
1076 ``useSingleCpuIO = .TRUE.`` in the ``PARM01`` namelist within the main ``data`` file. Single–CPU 1077 I/O mode is appropriate for computers (e.g., some SGI systems) where 1078 it can either speed overall I/O or solve problems where the 1079 operating system or file systems cannot correctly handle multiple 1080 threads or MPI processes simultaneously writing to the same file. 1081 1082 - **Meta-data:** 1083 Meta-data is written by MITgcm on a per-file basis using a second file with a 1084 ``.meta`` extension as described above. MITgcm itself does not read 1085 the ``*.meta`` files, they are there primarly for convenience during 1086 post-processing. One should be careful not to delete the meta-data 1087 files when using MATLAB post-processing scripts such as :filelink:`rdmds() <utils/matlab/rdmds.m>` 1088 since it relies upon them. 1089 1090 - **Numerous files:** 1091 If one is not careful (e.g., dumping many variables every time step over a long integration), :filelink:`pkg/mdsio` e2c4ac4a43 Ed D*1092 will write copious amounts of files. The creation of both a binary (``*.data``) 9ce7d74115 Jeff*1093 and ASCII text meta-data (``*.meta``) file for each output type step 1094 exacerbates the issue. Some operating 1095 systems do not gracefully handle large numbers (e.g., many 1096 thousands to millions) of files within one directory. So care should be taken to 1097 split output into smaller groups using subdirectories. 1098 1099 - **Overwriting output:** 1100 Overwriting of output is the **default behavior** for :filelink:`pkg/mdsio`. If a model tries to write 1101 to a file name that already exists, the older file **will be 1102 deleted**. For this reason, MITgcm users should be careful to move e2c4ac4a43 Ed D*1103 output that they wish to keep into, for instance, subdirectories 9ce7d74115 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1105.
1104 before performing subsequent runs that may over–lap in time or 1105 otherwise produce files with identical names (e.g., Monte-Carlo 1106 simulations). 1107** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1109.
1108 - **No “halo” information:**** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1110.
1109 “Halo” information is neither written nor read by :filelink:`pkg/mdsio`. Along the horizontal dimensions,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1111.
1110 all variables are written in an ``sNx``–by–``sNy`` fashion. So, 1111 although variables (arrays) may be defined at different locations on 1112 Arakawa grids [U (right/left horizontal edges), V (top/bottom 1113 horizontal edges), M (mass or cell center), or Z (vorticity or cell 1114 corner) points], they are all written using only interior (``1:sNx`` 1115 and ``1:sNy``) values. For quantities defined at U, V, and M points, 1116 writing ``1:sNx`` and ``1:sNy`` for every tile is sufficient to 1117 ensure that all values are written globally for some grids (e.g., 1118 cubed sphere, re-entrant channels, and doubly-periodic rectangular 1119 regions). For Z points, failing to write values at the ``sNx+1`` and 1120 ``sNy+1`` locations means that, for some tile topologies, not all 1121 values are written. For instance, with a cubed sphere topology at** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1123.
1122 least two corner values are “lost” (fail to be written for any tile) 1123 if the ``sNx+1`` and ``sNy+1`` values are ignored. If this is an issue, we recommend 1124 switching to :filelink:`pkg/mnc`, which writes the ``sNx+1`` and ``sNy+1`` grid 1125 values for the U, V, and Z locations. Also, :filelink:`pkg/mnc` is 1126 capable of reading and/or writing entire halo regions and more 1127 complicated array shapes which can be helpful when 1128 debugging -- features that do not exist within :filelink:`pkg/mdsio`. 1129 dcaaa42497 Jeff*1130 .. tabularcolumns:: |\Y{.4}|L|L| 1131 1132 1133 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1134 | CPP Flag Name | Default | Description | 1135 +===============================================+=========+======================================================================================================================+ 1136 | :varlink:`SAFE_IO` | #undef | if defined, stops the model from overwriting its own files | 1137 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1138 | :varlink:`ALLOW_WHIO` | #undef | I/O will include tile halos in the files | 1139 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 9ce7d74115 Jeff*1140 1141 pkg/rw basic binary I/O utilities 1142 --------------------------------- 1143 1144 :filelink:`pkg/rw` provides a very rudimentary binary I/O capability for 1145 quickly writing *single record* direct-access Fortran binary files. It 1146 is primarily used for writing diagnostic output. 1147 1148 Introduction 1149 ~~~~~~~~~~~~ 1150 1151 :filelink:`pkg/rw` is an interface to the more general :filelink:`pkg/mdsio` package. 1152 :filelink:`pkg/rw` can be used to write or read direct-access Fortran binary files 1153 for 2-D XY and 3-D XYZ arrays. The arrays are 1154 assumed to have been declared according to the standard MITgcm 1155 2-D or 3-D floating point array type: 1156 1157 :: 1158 1159 C Example of declaring a standard two dimensional "long" 1160 C floating point type array (the _RL macro is usually 1161 C mapped to 64-bit floats in most configurations) 1162 _RL anArray(1-OLx:sNx+OLx,1-OLy:sNy+OLy,nSx,nSy) 1163 1164 Each call to a :filelink:`pkg/rw` read or write routine will read (or write) to the 1165 first record of a file. To write direct access Fortran files with 1166 multiple records use the higher-level routines in :filelink:`pkg/mdsio` rather than :filelink:`pkg/rw` routines. To 1167 write self-describing files that contain embedded information describing 1168 the variables being written and the spatial and temporal locations of 1169 those variables use the :filelink:`pkg/mnc` instead (see :numref:`pkg_mnc`) which 1170 produces `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ format output. 1171 dcaaa42497 Jeff*1172 .. tabularcolumns:: |\Y{.4}|L|L| 1173 1174 1175 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1176 | CPP Flag Name | Default | Description | 1177 +===============================================+=========+======================================================================================================================+ 1178 | :varlink:`RW_SAFE_MFLDS` | #define | use READ_MFLDS in "safe" mode (set/check/unset for each file to read); involves more thread synchronization | 1179 | | | which could slow down multi-threaded run | 1180 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1181 | :varlink:`RW_DISABLE_SMALL_OVERLAP` | #undef | disable writing of small-overlap size array (to reduce memory size since those S/R do a local copy to 3-D | 1182 | | | full-size overlap array) | 1183 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1184 9ce7d74115 Jeff*1185 .. _pkg_mnc: 1186 1187 NetCDF I/O: pkg/mnc 1188 =================== 1189 1190 Package :filelink:`pkg/mnc` is a set of convenience routines written to expedite 1191 the process of creating, appending, and reading `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files. 1192 `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ is 1193 an increasingly popular self-describing file format intended primarily for scientific data sets. 1194 An extensive collection of netCDF `documentation <https://www.unidata.ucar.edu/software/netcdf/docs/index.html>`_,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1196.
1195 including a `user’s guide <https://www.unidata.ucar.edu/software/netcdf/docs/user_guide.html>`_, 1196 `tutorial <https://www.unidata.ucar.edu/software/netcdf/docs/tutorial_8dox.html>`_, 1197 `FAQ <https://www.unidata.ucar.edu/software/netcdf/docs/faq.html>`_, 1198 `support archive <https://www.unidata.ucar.edu/support/help/MailArchives/netcdf/maillist.html>`_ and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1200.
1199 other information can be obtained from UCAR’s web 1200 site http://www.unidata.ucar.edu/software/netcdf. 1201** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1203.
1202 Since it is a “wrapper” for `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_, 1203 :filelink:`pkg/mnc` depends upon the Fortran-77 1204 interface included with the standard `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ v3.x library which is often 1205 called ``libnetcdf.a``. Please contact your local systems administrators 1206 or email mitgcm-support@mitgcm.org for help building and installing 1207 `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ for your particular 1208 platform. 1209 1210 Every effort has been made to allow :filelink:`pkg/mnc` and :filelink:`pkg/mdsio` (see :numref:`pkg_mdsio`) to 1211 peacefully co-exist. In may cases, the model can read one format and 1212 write to the other. This side-by-side functionality can be used to, for 1213 instance, help convert pickup files or other data sets between the two 1214 formats. 1215 1216 Using pkg/mnc 1217 ------------- 1218 1219 pkg/mnc configuration: 1220 ~~~~~~~~~~~~~~~~~~~~~~ 1221 1222 As with all MITgcm packages, :filelink:`pkg/mnc` can be turned on or off at compile time 1223 using the ``packages.conf`` file or the :filelink:`genmake2 <tools/genmake2>` ``-enable=mnc`` or 1224 ``-disable=mnc`` switches. 1225** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1227.
1226 While :filelink:`pkg/mnc` is likely to work “as is”, there are a few compile–time 1227 constants that may need to be increased for simulations that employ 1228 large numbers of tiles within each process. Note that the important 1229 quantity is the maximum number of tiles **per process**. Since MPI 1230 configurations tend to distribute large numbers of tiles over relatively 1231 large numbers of MPI processes, these constants will rarely need to be 1232 increased. 1233** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1235.
1234 If :filelink:`pkg/mnc` runs out of space within its “lookup” tables during a simulation, 1235 then it will provide an error message along with a recommendation of 1236 which parameter to increase. The parameters are all located within :filelink:`MNC_COMMON.h <pkg/mnc/MNC_COMMON.h>` and 1237 the ones that may need to be increased are: 1238 1239 +----------------+----------+--------------------------------------+ 1240 | Name |Default | Description | 1241 +================+==========+======================================+ 1242 | MNC_MAX_ID | 1000 | IDs for various low-level entities | 1243 +----------------+----------+--------------------------------------+ 1244 | MNC_MAX_INFO | 400 | IDs (mostly for object sizes) | 1245 +----------------+----------+--------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1247.
1246 | MNC_CW_MAX_I | 150 | IDs for the “wrapper” layer | 1247 +----------------+----------+--------------------------------------+ 1248** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1250.
1249 In those rare cases where :filelink:`pkg/mnc` “out-of-memory” error messages are 1250 encountered, it is a good idea to increase the too-small parameter by a** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1252.
1251 factor of 2–10 in order to avoid wasting time on an iterative** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1253.
1252 compile–test sequence. 1253 1c87316fba Jeff*1254 .. _pkg_mnc_inputs: 1255 9ce7d74115 Jeff*1256 pkg/mnc Inputs: 1257 ~~~~~~~~~~~~~~~ 1258 1259 Like most MITgcm packages, all of :filelink:`pkg/mnc` can be turned on/off at runtime 1260 using a single flag in ``data.pkg``: 1261 1262 +---------------------------------+---------+------------+----------------------------------------------+ 1263 | Name | Type | Default | Description | 1264 +=================================+=========+============+==============================================+ 1265 | :varlink:`useMNC` | L | .FALSE. | overall MNC ON/OFF switch | 1266 +---------------------------------+---------+------------+----------------------------------------------+ 1267** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1269.
1268 One important MNC–related flag is present in the main ``data`` namelist 1269 file in the ``PARM03`` section: 1270 1271 +---------------------------------+---------+------------+----------------------------------------------+ 1272 | Name | Type | Default | Description | 1273 +=================================+=========+============+==============================================+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1275.
1274 | :varlink:`outputTypesInclusive` | L | .FALSE. | use all available output “types” | 1275 +---------------------------------+---------+------------+----------------------------------------------+ 1276 1277 which specifies that turning on :filelink:`pkg/mnc` for a particular type of output 1278 should not simultaneously turn off the default output method as it 1279 normally does. Usually, this option is only used for debugging purposes 1280 since it is inefficient to write output types using both :filelink:`pkg/mnc` and :filelink:`pkg/mdsio` 1281 or ASCII output. This option can also be helpful when transitioning from 1282 :filelink:`pkg/mdsio` to :filelink:`pkg/mnc` since the output can be readily compared. 1283** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1285.
1284 For run-time configuration, most of the :filelink:`pkg/mnc`–related model parameters are 1285 contained within a Fortran namelist file called ``data.mnc``. The 1286 available parameters currently include: 1287 1288 +---------------------------------+---------+------------+----------------------------------------------+ 1289 | Name | Type | Default | Description | 1290 +=================================+=========+============+==============================================+ 1291 | :varlink:`mnc_use_outdir` | L | .FALSE. | create a directory for output | 1292 +---------------------------------+---------+------------+----------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1294.
1293 | :varlink:`mnc_outdir_str` | S | ’mnc\_’ | output directory name | 1294 +---------------------------------+---------+------------+----------------------------------------------+ 1295 | :varlink:`mnc_outdir_date` | L | .FALSE. | embed date in the outdir name | 1296 +---------------------------------+---------+------------+----------------------------------------------+ 1297 | :varlink:`mnc_outdir_num` | L | .TRUE. | optional | 1298 +---------------------------------+---------+------------+----------------------------------------------+ 1299 | :varlink:`pickup_write_mnc` | L | .TRUE. | use MNC to write pickup files | 1300 +---------------------------------+---------+------------+----------------------------------------------+ 1301 | :varlink:`pickup_read_mnc` | L | .TRUE. | use MNC to read pickup file | 1302 +---------------------------------+---------+------------+----------------------------------------------+ 1303 | :varlink:`mnc_use_indir` | L | .FALSE. | use a directory (path) for input | 1304 +---------------------------------+---------+------------+----------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1306.
1305 | :varlink:`mnc_indir_str` | S | ‘ ’ | input directory (or path) name | 1306 +---------------------------------+---------+------------+----------------------------------------------+ 1307 | :varlink:`snapshot_mnc` | L | .TRUE. | write snapshot output w/MNC | 1308 +---------------------------------+---------+------------+----------------------------------------------+ 1309 | :varlink:`monitor_mnc` | L | .TRUE. | write :filelink:`pkg/monitor` output w/MNC | 1310 +---------------------------------+---------+------------+----------------------------------------------+ 21d0859333 Oliv*1311 | :varlink:`timeave_mnc` | L | .TRUE. | write :filelink:`pkg/timeave` output w/MNC | 9ce7d74115 Jeff*1312 +---------------------------------+---------+------------+----------------------------------------------+ 21d0859333 Oliv*1313 | :varlink:`autodiff_mnc` | L | .TRUE. | write :filelink:`pkg/autodiff` output w/MNC | 9ce7d74115 Jeff*1314 +---------------------------------+---------+------------+----------------------------------------------+ 1315 | :varlink:`mnc_max_fsize` | R | 2.1e+09 | max allowable file size (<2GB) | 1316 +---------------------------------+---------+------------+----------------------------------------------+ 1317 | :varlink:`mnc_filefreq` | R | -1 | frequency of new file creation (seconds) | 1318 +---------------------------------+---------+------------+----------------------------------------------+ 1319 | :varlink:`readgrid_mnc` | L | .FALSE. | read grid quantities using MNC | 1320 +---------------------------------+---------+------------+----------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1322.
1321 | :varlink:`mnc_echo_gvtypes` | L | .FALSE. | list pre-defined “types” (debug) | 1322 +---------------------------------+---------+------------+----------------------------------------------+ 1323 1324 Unlike the older :filelink:`pkg/mdsio` method, :filelink:`pkg/mnc` has the ability to create or use 1325 existing output directories. If either :varlink:`mnc_outdir_date` or 1326 :varlink:`mnc_outdir_num` is ``.TRUE.``, then :filelink:`pkg/mnc` will try to create directories on a 1327 *per process* basis for its output. This means that a single directory 1328 will be created for a non-MPI run and multiple directories (one per MPI 1329 process) will be created for an MPI run. This approach was chosen since 1330 it works safely on both shared global file systems (such as NFS and AFS) 1331 and on local (per-compute-node) file systems. And if both 1332 :varlink:`mnc_outdir_date` and :varlink:`mnc_outdir_num` are ``.FALSE.``, then the :filelink:`pkg/mnc` 1333 package will assume that the directory specified in :varlink:`mnc_outdir_str` 1334 already exists and will use it. This allows the user to create and 1335 specify directories outside of the model. 1336 1337 For input, :filelink:`pkg/mnc` can use a single global input directory. This is a just 1338 convenience that allows :filelink:`pkg/mnc` to gather all of its input files from a path 1339 other than the current working directory. As with :filelink:`pkg/mdsio`, the default is 1340 to use the current working directory. 1341 1342 The flags :varlink:`snapshot_mnc`, :varlink:`monitor_mnc`, :varlink:`timeave_mnc`, and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1344.
1343 :varlink:`autodiff_mnc` allow the user to turn on :filelink:`pkg/mnc` for particular “types” of 1344 output. If a type is selected, then :filelink:`pkg/mnc` will be used for all output that 1345 matches that type. This applies to output from the main model and from 1346 all of the optional MITgcm packages. Mostly, the names used here 1347 correspond to the names used for the output frequencies in the main 1348 ``data`` namelist file. 1349 1350 The :varlink:`mnc_max_fsize` parameter is a convenience added to help users 1351 work around common file size limitations. On many computer systems, 1352 either the operating system, the file system(s), and/or the `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ 1353 libraries are unable to handle files greater than two or four gigabytes 1354 in size. :filelink:`pkg/mnc` is able to work within this limitation by** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1356.
1355 creating new files which grow along the `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ “unlimited” (usually, 1356 time) dimension. The default value for this parameter is just slightly 1357 less than 2GB which is safe on virtually all operating systems. 1358 Essentially, this feature is a way to intelligently and automatically 1359 split files output along the unlimited dimension. On systems that 1360 support large file sizes, these splits can be readily concatenated (that 1361 is, un-done) using tools such as the NetCDF 1362 Operators (with `ncrcat <http://nco.sourceforge.net/nco.html#ncrcat-netCDF-Record-Concatenator>`_) 1363 which is available at http://nco.sourceforge.net. 1364 1365 Another way users can force the splitting of :filelink:`pkg/mnc` files along the time 1366 dimension is the :varlink:`mnc_filefreq` option. With it, files that contain 1367 variables with a temporal dimension can be split at regular intervals 1368 based solely upon the model time (specified in seconds). For some 1369 problems, this can be much more convenient than splitting based upon 1370 file size. 1371** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1373.
1372 Additional :filelink:`pkg/mnc`–related parameters may be contained within each package. 1373 Please see the individual packages for descriptions of their use of :filelink:`pkg/mnc`. 1374 1375 pkg/mnc output: 1376 ~~~~~~~~~~~~~~~ 1377 1378 Depending upon the flags used, :filelink:`pkg/mnc` will produce zero or more directories 1379 containing one or more `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files as output. These files are either** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1381.
1380 mostly or entirely compliant with the `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ “CF” convention (v1.0) and 1381 any conformance issues will be fixed over time. The patterns used for file names are: 1382 1383 - BASENAME.tileNum.nc 1384 - BASENAME.nIter.faceNum.nc 1385 - BASENAME.nIter.tileNum.nc 1386 1387 and examples are: 1388 1389 1390 - grid.t001.nc, grid.t002.nc 1391 - input.0000072000.f001.nc 1392 - state.0000000000.t001.nc, surfDiag.0000036000.t001.nc 1393 1394 1395 where BASENAME is the name selected to represent a set of variables 1396 written together, nIter is the current iteration number as specified 1397 in the main ``data`` namelist input file and written in a zero-filled 1398 10-digit format, tileNum is a three-or-more-digit zero-filled and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1400.
1399 ``t``–prefixed tile number, «faceNum» is a three-or-more-digit** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1401.
1400 zero-filled and ``f``–prefixed face number, and ``.nc`` is the file** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1402.
1401 suffix specified by the current `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ “CF” conventions. 1402 1403 Some example BASENAME values are: 1404 1405 **grid** 1406 contains the variables that describe the various grid constants 1407 related to locations, lengths, areas, etc. 1408 1409 **state** 1410 contains the variables output at the :varlink:`dumpFreq` time frequency 1411 1412 **pickup.ckptA, pickup.ckptB**** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1414.
1413 are the “rolling” checkpoint files 1414 1415 **tave** 1416 contains the time-averaged quantities from the main model 1417** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1419.
1418 All :filelink:`pkg/mnc` output is currently done in a “file-per-tile” fashion since most 1419 `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ v3.x implementations cannot write safely within MPI or 1420 multi-threaded environments. This tiling is done in a global fashion and 1421 the tile numbers are appended to the base names as described above. Some 1422 scripts to manipulate :filelink:`pkg/mnc` output are available at** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1424.
1423 :filelink:`utils/matlab` which includes a spatial “assembly” script 1424 :filelink:`mnc_assembly.m <utils/matlab/mnc_assembly.m>`. 1425 1426 More general manipulations can be performed on `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files with** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1428.
1427 the NetCDF Operators (“NCO”) at http://nco.sourceforge.net** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1429.
1428 or with the Climate Data Operators (“CDO”) at https://code.mpimet.mpg.de/projects/cdo. f460f9a57e Ivan*1429 See :ref:`gluemnc <gluemnc>` for post-processing NetCDF output via command line. 9ce7d74115 Jeff*1430 1431 Unlike the older :filelink:`pkg/mdsio` routines, :filelink:`pkg/mnc` reads and writes variables on** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1433.
1432 different “grids” depending upon their location in the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1434.
1433 Arakawa C–grid. The following table provides examples: 1434 1435 +---------------+-----------------------+--------------+--------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1437.
1436 | Name | C–grid location | # in X | # in Y | 1437 +===============+=======================+==============+==============+ 1438 | Temperature | mass | sNx | sNy | 1439 +---------------+-----------------------+--------------+--------------+ 1440 | Salinity | mass | sNx | sNy | 1441 +---------------+-----------------------+--------------+--------------+ 1442 | U velocity | U | sNx+1 | sNy | 1443 +---------------+-----------------------+--------------+--------------+ 1444 | V velocity | V | sNx | sNy+1 | 1445 +---------------+-----------------------+--------------+--------------+ 1446 | Vorticity | vorticity | sNx+1 | sNy+1 | 1447 +---------------+-----------------------+--------------+--------------+ 1448** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1450.
1449 and the intent is two–fold: 1450 1451 #. For some grid topologies it is impossible to output all quantities 1452 using only ``sNx,sNy`` arrays for every tile. Two examples of this 1453 failure are the missing corners problem for vorticity values on the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1455.
1454 cubed sphere and the velocity edge values for some open–boundary 1455 domains. 1456 1457 #. Writing quantities located on velocity or vorticity points with the 1458 above scheme introduces a very small data redundancy. However, any 1459 slight inconvenience is easily offset by the ease with which one can, 1460 on every individual tile, interpolate these values to mass points** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1462.
1461 without having to perform an “exchange” (or “halo-filling”) operation 1462 to collect the values from neighboring tiles. This makes the most** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1464.
1463 common post–processing operations much easier to implement. 1464 1465 pkg/mnc Troubleshooting 1466 ----------------------- 1467 1468 Build troubleshooting: 1469 ~~~~~~~~~~~~~~~~~~~~~~ 1470 1471 In order to build MITgcm with :filelink:`pkg/mnc` enabled, 1472 the `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ v3.x Fortran-77 1473 (not Fortran-90) library must be available. This library is composed of 1474 a single header file (called ``netcdf.inc``) and a single library file 1475 (usually called ``libnetcdf.a``) and it must be built with the same 1476 compiler with compatible compiler 1477 options as the one used to build MITgcm (in other words, 1478 while one does not have to build ``libnetcdf.a`` 1479 with the same exact set of compiler options as MITgcm, 1480 one must avoid using some specific different compiler options which are incompatible, 1481 i.e., causing a compile-time or run-time error). 1482 1483 For more details concerning the netCDF build and install process, please 1484 visit the `Getting and Building NetCDF guide <https://www.unidata.ucar.edu/software/netcdf/docs/getting_and_building_netcdf.html>`_** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1486.
1485 which includes an extensive list of known–good netCDF configurations for various platforms. 1486 1487 Runtime troubleshooting: 1488 ~~~~~~~~~~~~~~~~~~~~~~~~ 1489 1490 Please be aware of the following: 1491 1492 - As a safety feature, the :filelink:`pkg/mnc` does not, by default, allow 1493 pre-existing files to be appended to or overwritten. This is in 1494 contrast to the older :filelink:`pkg/mdsio` which will, without any warning, 1495 overwrite existing files. If MITgcm aborts with an error message 1496 about the inability to open or write to a netCDF file, please check 1497 **first** whether you are attempting to overwrite files from a 1498 previous run. 1499** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1501.
1500 - The constraints placed upon the “unlimited” (or “record”) dimension 1501 inherent with `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ v3.x 1502 make it very inefficient to put variables 1503 written at potentially different intervals within the same file. For 1504 this reason, :filelink:`pkg/mnc` output is split into groups of files which attempt 1505 to reflect the nature of their content. 1506 1507 - On many systems, `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ 1508 has practical file size limits on the order** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1510.
1509 of 2–4GB (the maximium memory addressable with 32bit pointers or 1510 pointer differences) due to a lack of operating system, compiler, ba0b047096 Mart*1511 and/or library support. The latest revisions of 9ce7d74115 Jeff*1512 `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ v3.x have 1513 large file support and, on some operating systems, file sizes are 1514 only limited by available disk space. 1515 1516 - There is an 80 character limit to the total length of all file names. 1517 This limit includes the directory (or path) since paths and file 1518 names are internally appended. Generally, file names will not exceed 1519 the limit and paths can usually be shortened using, for example, soft 1520 links. 1521 1522 - :filelink:`pkg/mnc` does not (yet) provide a mechanism for reading information from a** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1524.
1523 single “global” file as can be done with :filelink:`pkg/mdsio`. This is 1524 in progress. 1525 1526 pkg/mnc Internals 1527 ----------------- 1528** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1530.
1529 :filelink:`pkg/mnc` is a two-level convenience library (or “wrapper”) 1530 for most of the `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ Fortran API. Its purpose is to streamline the 1531 user interface to `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ by maintaining internal relations (look-up 1532 tables) keyed with strings (or names) and entities such as `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files, 1533 variables, and attributes. 1534 1535 The two levels of :filelink:`pkg/mnc` are: 1536 1537 Upper level 1538 1539 1540 The upper level contains information about two kinds of 1541 associations: 1542 1543 grid type 1544 is lookup table indexed with a grid type name. Each grid type 1545 name is associated with a number of dimensions, the dimension 1546 sizes (one of which may be unlimited), and starting and ending 1547 index arrays. The intent is to store all the necessary size and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1549.
1548 shape information for the Fortran arrays containing MITgcm–style** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1550.
1549 “tile” variables (i.e., a central region surrounded by a** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1551.
1550 variably-sized “halo” or exchange region as shown in :numref:`comm-prim` 1551 and :numref:`tiling_detail`). 1552 1553 variable type 1554 is a lookup table indexed by a variable type name. For each 1555 name, the table contains a reference to a grid type for the 1556 variable and the names and values of various attributes. 1557 1558 Within the upper level, these associations are not permanently tied 1559 to any particular `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ file. This allows the information to be 1560 re-used over multiple file reads and writes. 1561 1562 Lower level 1563 1564 1565 In the lower (or internal) level, associations are stored for `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ 1566 files and many of the entities that they contain including 1567 dimensions, variables, and global attributes. All associations are 1568 on a per-file basis. Thus, each entity is tied to a unique `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ 1569 file and will be created or destroyed when files are, respectively, 1570 opened or closed. 1571** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1573.
1572 pkg/mnc grid–tTypes and variable–types: 1573 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1574 1575 As a convenience for users, :filelink:`pkg/mnc` includes numerous routines 1576 to aid in the writing of data to `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ format. Probably the biggest** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1578.
1577 convenience is the use of pre-defined “grid types” and “variable types”.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1579.
1578 These “types” are simply look-up tables that store dimensions, indicies, 1579 attributes, and other information that can all be retrieved using a 1580 single character string. 1581** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1583.
1582 The “grid types” are a way of mapping variables within MITgcm to `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1584.
1583 arrays. Within MITgcm, most spatial variables are defined using 2–D or** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1585.
1584 3–D arrays with “overlap” regions (see :numref:`comm-prim`, a possible vertical index,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1586.
1585 and :numref:`tiling_detail`) and tile indicies such as the following “U” 1586 velocity: 1587 1588 :: 1589 1590 _RL uVel (1-OLx:sNx+OLx,1-OLy:sNy+OLy,Nr,nSx,nSy) 1591 1592 as defined in :filelink:`DYNVARS.h <model/inc/DYNVARS.h>`. 1593 1594 The grid type is a character string that encodes the presence and types 1595 associated with the four possible dimensions. The character string ba0b047096 Mart*1596 follows the format: 9ce7d74115 Jeff*1597 1598 :: 1599 ba0b047096 Mart*1600 H0_H1_H2__V__T 9ce7d74115 Jeff*1601 1602 (note the double underscore 1603 between H2 and V, and V and T) where the terms 1604 H0, H1, H2, V, T can be almost any combination 1605 of the following: 1606 1607 +------------------------------------------------+---------------+------------+ 1608 | Horizontal | Vertical | Time | 1609 +----------------+------------------+------------+---------------+------------+ 1610 | H0: location | H1: dimensions | H2: halo | V: location | T: level | 1611 +================+==================+============+===============+============+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1613.
1612 | – | xy | Hn | – | – | 1613 +----------------+------------------+------------+---------------+------------+ 1614 | U | x | Hy | i | t | 1615 +----------------+------------------+------------+---------------+------------+ 1616 | V | y | | c | | 1617 +----------------+------------------+------------+---------------+------------+ 1618 | Cen | | | | | 1619 +----------------+------------------+------------+---------------+------------+ 1620 | Cor | | | | | 1621 +----------------+------------------+------------+---------------+------------+ 1622 1623 A example list of all pre-defined combinations is contained in the file :filelink:`pkg/mnc/pre-defined_grids.txt`. 1624 1625 The variable type is an association between a variable type name and the 1626 following items: 1627 1628 +------------------------+-------------------------------------+ 1629 | Item | Purpose | 1630 +========================+=====================================+ 1631 | grid type | defines the in-memory arrangement | 1632 +------------------------+-------------------------------------+ 1633 | bi,bj dimensions | tiling indices, if present | 1634 +------------------------+-------------------------------------+ 1635 1636 and is used by the ``mnc_cw__[R|W]`` subroutines for reading and writing 1637 variables. 1638 1639 Using pkg/mnc: examples 1640 ~~~~~~~~~~~~~~~~~~~~~~~ 1641 1642 Writing variables to `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files can be accomplished in as few as two 1643 function calls. The first function call defines a variable type, 1644 associates it with a name (character string), and provides additional 1645 information about the indicies for the tile (bi,bj) 1646 dimensions. The second function call will write the data at, if 1647 necessary, the current time level within the model. 1648 1649 Examples of the initialization calls can be found in the file 1650 :filelink:`model/src/ini_model_io.F` where these function calls: 1651 1652 :: 1653 1654 C Create MNC definitions for DYNVARS.h variables 1655 CALL MNC_CW_ADD_VNAME('iter', '-_-_--__-__t', 0,0, myThid) 1656 CALL MNC_CW_ADD_VATTR_TEXT('iter',1, 1657 & 'long_name','iteration_count', myThid) 1658 1659 CALL MNC_CW_ADD_VNAME('model_time', '-_-_--__-__t', 0,0, myThid) 1660 CALL MNC_CW_ADD_VATTR_TEXT('model_time',1, 1661 & 'long_name','Model Time', myThid) 1662 CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,'units','s', myThid) 1663 1664 CALL MNC_CW_ADD_VNAME('U', 'U_xy_Hn__C__t', 4,5, myThid) 1665 CALL MNC_CW_ADD_VATTR_TEXT('U',1,'units','m/s', myThid) 1666 CALL MNC_CW_ADD_VATTR_TEXT('U',1, 1667 & 'coordinates','XU YU RC iter', myThid) 1668 1669 CALL MNC_CW_ADD_VNAME('T', 'Cen_xy_Hn__C__t', 4,5, myThid) 1670 CALL MNC_CW_ADD_VATTR_TEXT('T',1,'units','degC', myThid) 1671 CALL MNC_CW_ADD_VATTR_TEXT('T',1,'long_name', 1672 & 'potential_temperature', myThid) 1673 CALL MNC_CW_ADD_VATTR_TEXT('T',1, 1674 & 'coordinates','XC YC RC iter', myThid) 1675 1676 initialize four ``VNAME``\ s and add one or more 1677 `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ attributes to each. 1678 1679 The four variables defined above are subsequently written at specific 1680 time steps within :filelink:`model/src/write_state.F` using the function calls: 1681 1682 :: 1683 1684 C Write dynvars using the MNC package 1685 CALL MNC_CW_SET_UDIM('state', -1, myThid) 1686 CALL MNC_CW_I_W('I','state',0,0,'iter', myIter, myThid) 1687 CALL MNC_CW_SET_UDIM('state', 0, myThid) 1688 CALL MNC_CW_RL_W('D','state',0,0,'model_time',myTime, myThid) 1689 CALL MNC_CW_RL_W('D','state',0,0,'U', uVel, myThid) 1690 CALL MNC_CW_RL_W('D','state',0,0,'T', theta, myThid) 1691 1692 While it is easiest to write variables within typical 2-D and 3-D fields 1693 where all data is known at a given time, it is also possible to write** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1695.
1694 fields where only a portion (e.g., a “slab” or “slice”) is known at a 1695 given instant. An example is provided within :filelink:`pkg/mom_vecinv/mom_vecinv.F` 1696 where an offset vector is used: 1697 1698 :: 1699 1700 IF (useMNC .AND. snapshot_mnc) THEN 1701 CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fV', uCf, 1702 & offsets, myThid) 1703 CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fU', vCf, 1704 & offsets, myThid) 1705 ENDIF 1706 1707 to write a 3-D field one depth slice at a time. 1708 1709 Each element in the offset vector corresponds (in order) to the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1711.
1710 dimensions of the “full” (or virtual) array and specifies which are 1711 known at the time of the call. A zero within the offset array means that 1712 all values along that dimension are available while a positive integer 1713 means that only values along that index of the dimension are available. 1714 In all cases, the matrix passed is assumed to start (that is, have an 1715 in-memory structure) coinciding with the start of the specified slice. 1716 Thus, using this offset array mechanism, a slice can be written along 1717 any single dimension or combinations of dimensions. 1718 1c87316fba Jeff*1719 .. _pkg_monitor: 9ce7d74115 Jeff*1720 1721 Monitor: Simulation State Monitoring Toolkit 1722 ============================================ 1723 1724 Introduction 1725 ------------ 1726 1727 :filelink:`pkg/monitor` is primarily intended as a convenient method for 1728 calculating and writing the following statistics: 1729 1730 - minimum 1731 - maximum 1732 - mean 1733 - standard deviation 1734 1735 for spatially distributed fields. By default, :filelink:`pkg/monitor` output is sent** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1737.
1736 to the “standard output” channel where it appears as ASCII text 1737 containing a ``%MON`` string such as this example: 1738 1739 :: 1740 1741 (PID.TID 0000.0001) %MON time_tsnumber = 3 1742 (PID.TID 0000.0001) %MON time_secondsf = 3.6000000000000E+03 1743 (PID.TID 0000.0001) %MON dynstat_eta_max = 1.0025466645951E-03 1744 (PID.TID 0000.0001) %MON dynstat_eta_min = -1.0008899950901E-03 1745 (PID.TID 0000.0001) %MON dynstat_eta_mean = 2.1037438449350E-14 1746 (PID.TID 0000.0001) %MON dynstat_eta_sd = 5.0985228723396E-04 1747 (PID.TID 0000.0001) %MON dynstat_eta_del2 = 3.5216706549525E-07 1748 (PID.TID 0000.0001) %MON dynstat_uvel_max = 3.7594045977254E-05 1749 (PID.TID 0000.0001) %MON dynstat_uvel_min = -2.8264287531564E-05 1750 (PID.TID 0000.0001) %MON dynstat_uvel_mean = 9.1369201945671E-06 1751 (PID.TID 0000.0001) %MON dynstat_uvel_sd = 1.6868439193567E-05 1752 (PID.TID 0000.0001) %MON dynstat_uvel_del2 = 8.4315445301916E-08 1753 1754 :filelink:`pkg/monitor` text can be readily parsed by the ``testreport`` script 1755 to determine, somewhat crudely but quickly, how similar the output from 1756 two experiments are when run on different platforms or before/after code 1757 changes. 1758 1759 :filelink:`pkg/monitor` output can also be useful for quickly diagnosing 1760 practical problems such as CFL limitations, model progress (through 1761 iteration counts), and behavior within some packages that use it. 1762 1763 Using pkg/monitor 1764 ----------------- 1765 1766 As with most packages, :filelink:`pkg/monitor` can be turned on or off at compile 1767 and/or run times using the ``packages.conf`` and ``data.pkg`` files. 1768 1769 The monitor output can be sent to the standard output channel, to an** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1771.
1770 :filelink:`pkg/mnc`–generated file, or to both simultaneously. For :filelink:`pkg/mnc` output, 1771 the flag ``monitor_mnc=.TRUE.`` should be set within the ``data.mnc`` file. For output to both ASCII and 1772 :filelink:`pkg/mnc`, the flag ``outputTypesInclusive=.TRUE.`` should be set 1773 within the ``PARM03`` section of the main ``data`` file. 1774 It should be noted that the ``outputTypesInclusive`` flag will make 1775 **ALL** kinds of output (that is, everything written by :filelink:`pkg/mdsio`, 1776 :filelink:`pkg/mnc`, and :filelink:`pkg/monitor`) simultaneously active so it should be used** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1778.
1777 only with caution -– and perhaps only for debugging purposes. 1778 dcaaa42497 Jeff*1779 1780 .. tabularcolumns:: |\Y{.4}|L|L| 1781 1782 1783 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1784 | CPP Flag Name | Default | Description | 1785 +===============================================+=========+======================================================================================================================+ 1786 | :varlink:`MONITOR_TEST_HFACZ` | #undef | disable use of hFacZ | 1787 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1788 1789 9ce7d74115 Jeff*1790 Grid Generation 1791 =============== 1792 1793 The horizontal discretizations within MITgcm have been written to work 1794 with many different grid types including: 1795 1796 - cartesian coordinates 1797** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1799.
1798 - spherical polar (“latitude-longitude”) coordinates 1799 1800 - general curvilinear orthogonal coordinates 1801 1802 The last of these, especially when combined with the domain 1803 decomposition capabilities of MITgcm, allows a great degree of grid 1804 flexibility. To date, general curvilinear orthogonal coordinates have 1805 been used extensively in conjunction with** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1807.
1806 so-called “cubed sphere” grids. However, it is important to observe that 1807 cubed sphere arrangements are only one example of what is possible with 1808 domain-decomposed logically rectangular regions each containing 1809 curvilinear orthogonal coordinate systems. Much more sophisticated 1810 domains can be imagined and constructed. 1811 1812 In order to explore the possibilities of domain-decomposed curvilinear 1813 orthogonal coordinate systems, a suite of grid generation software** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1815.
1814 called “SPGrid” (for SPherical Gridding) has been developed. SPGrid is a 1815 relatively new facility and papers detailing its algorithms are in 1816 preparation. Although SPGrid is new and rapidly developing, it has 1817 already demonstrated the ability to generate some useful and interesting 1818 grids. 1819 1820 This section provides a very brief introduction to SPGrid and shows some 1821 early results. For further information, please contact the MITgcm 1822 support list MITgcm-support@mitgcm.org. 1823 1824 Using SPGrid 1825 ------------ 1826 1827 The SPGrid software is not a single program. Rather, it is a collection 1828 of C++ code and `MATLAB <https://www.mathworks.com/>`_ scripts that can be used as a framework or 1829 library for grid generation and manipulation. Currently, grid creation 1830 is accomplished by either directly running `MATLAB <https://www.mathworks.com/>`_ scripts or by writing** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1832.
1831 a C++ “driver” program. The `MATLAB <https://www.mathworks.com/>`_ scripts are suitable for grids** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1833.
1832 composed of a single “face” (that is, a single logically rectangular 1833 region on the surface of a sphere). The C++ driver programs are 1834 appropriate for grids composed of multiple connected logically 1835 rectangular patches. Each driver program is written to specify the 1836 shape and connectivity of tiles and the preferred grid density (that is, 1837 the number of grid cells in each logical direction) and edge locations 1838 of the cells where they meet the edges of each face. The driver programs 1839 pass this information to the SPGrid library, which generates the actual 1840 grid and produces the output files that describe it. 1841 1842 Currently, driver programs are available for a few examples including** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1844.
1843 cubes, “lat-lon caps” (cube topologies that have conformal caps at the 1844 poles and are exactly lat-lon channels for the remainder of the domain),** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1846.
1845 and some simple “embedded” regions that are meant to be used within 1846 typical cubes or traditional lat-lon grids. 1847 1848 To create new grids, one may start with an existing driver program and 1849 modify it to describe a domain that has a different arrangement. The** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1851.
1850 number, location, size, and connectivity of grid “faces” (the name used 1851 for the logically rectangular regions) can be readily changed. Further, 1852 the number of grid cells within faces and the location of the grid cells 1853 at the face edges can also be specified. 1854 1855 SPGrid requirements 1856 ~~~~~~~~~~~~~~~~~~~ 1857 1858 The following programs and libraries are required to build and/or run 1859 the SPGrid suite: 1860 1861 - `MATLAB <https://www.mathworks.com/>`_ is a run-time requirement since many of the generation 1862 algorithms have been written as `MATLAB <https://www.mathworks.com/>`_ scripts. 1863 1864 - The `Geometric Tools Engine <https://geometrictools.com>`_ (a C++ library) is needed for the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1866.
1865 main “driver” code. 1866 1867 - The `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ library is needed for file I/O. 1868 1869 - The `Boost serialization library <http://www.boost.org/doc/libs/1_66_0/libs/serialization/doc/index.html>`_ is also used for I/O: 1870 1871 - a typical Linux/Unix build environment including the make utility 1872 (preferably GNU Make) and a C++ compiler (SPGrid was developed with 1873 g++ v4.x). 1874 1875 Obtaining SPGrid 1876 ~~~~~~~~~~~~~~~~ 1877 1878 The latest version can be obtained from: 1879 1880 1881 Building SPGrid 1882 ~~~~~~~~~~~~~~~ 1883 1884 The procedure for building is similar to many open source projects: 1885 1886 :: 1887 1888 tar -xf spgrid-0.9.4.tar.gz 1889 cd spgrid-0.9.4 1890 export CPPFLAGS="-I/usr/include/netcdf-3" 1891 export LDFLAGS="-L/usr/lib/netcdf-3" 1892 ./configure 1893 make 1894 1895 where the ``CPPFLAGS`` and ``LDFLAGS`` environment variables can be 1896 edited to reflect the locations of all the necessary dependencies. 1897 SPGrid is known to work on Fedora Core Linux (versions 4 and 5) and is 1898 likely to work on most any Linux distribution that provides the needed 1899 dependencies. 1900 1901 Running SPGrid 1902 ~~~~~~~~~~~~~~ 1903 1904 Within the ``src`` sub-directory, various example driver programs exist. 1905 These examples describe small, simple domains and can generate the input 1906 files (formatted as either binary ``*.mitgrid`` or netCDF) used by 1907 MITgcm. 1908 1909 One such example is called ``SpF_test_cube_cap`` and it can be run with 1910 the following sequence of commands: 1911 1912 :: 1913 1914 cd spgrid-0.9.4/src 1915 make SpF_test_cube_cap 1916 mkdir SpF_test_cube_cap.d 1917 ( cd SpF_test_cube_cap.d && ln -s ../../scripts/*.m . ) 1918 ./SpF_test_cube_cap 1919 1920 which should create a series of output files: 1921 1922 :: 1923 1924 SpF_test_cube_cap.d/grid_*.mitgrid 1925 SpF_test_cube_cap.d/grid_*.nc 1926 SpF_test_cube_cap.d/std_topology.nc 1927 1928 where the ``grid_.mitgrid`` and ``grid_.nc`` files contain the grid 1929 information in binary and netCDF formats and the ``std_topology.nc`` 1930 file contains the information describing the connectivity (both** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1932.
1931 edge–edge and corner–corner contacts) between all the faces. 1932 1933 Example Grids 1934 ------------- 1935 1936 The following grids are various examples created with SPGrid. 1937** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1939.
1938 Pre– and Post–Processing Scripts and Utilities 1939 ============================================== 1940 1941 There are numerous tools for pre-processing data, converting model 1942 output and analysis written in `MATLAB <https://www.mathworks.com/>`_, Fortran (f77 and f90) and perl. 1943 As yet they remain undocumented although many are self-documenting** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1945.
1944 (`MATLAB <https://www.mathworks.com/>`_ routines have “help” written into them). 1945** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1947.
1946 Here we’ll summarize what is available but this is an ever growing 1947 resource so this may not cover everything that is out there: 1948 1949 Utilities Supplied With the Model 1950 --------------------------------- 1951 1952 We supply some basic scripts with the model to facilitate conversion or 1953 reading of data into analysis software. 1954 1955 utils/scripts 1956 ~~~~~~~~~~~~~ 1957 1958 In the directory :filelink:`utils/scripts`, :filelink:`joinds <utils/scripts/joinds>` 1959 and :filelink:`joinmds <utils/scripts/joinmds>` 1960 are perl scripts used to joining multi-part files created by 1961 MITgcm. Use :filelink:`joinmds <utils/scripts/joinmds>`. 1962 You will only need :filelink:`joinds <utils/scripts/joinds>` if you are 1963 working with output older than two years (prior to c23). 1964 1965 utils/matlab 1966 ~~~~~~~~~~~~ 1967 1968 In the directory :filelink:`utils/matlab` you will find 1969 several `MATLAB <https://www.mathworks.com/>`_ scripts (``.m`` 1970 files). The principle script is :filelink:`rdmds.m <utils/matlab/rdmds.m>`, used for reading 1971 the multi-part model output files into `MATLAB <https://www.mathworks.com/>`_ . Place the scripts in 1972 your `MATLAB <https://www.mathworks.com/>`_ path or change the path appropriately, ba0b047096 Mart*1973 then at the `MATLAB <https://www.mathworks.com/>`_ 9ce7d74115 Jeff*1974 prompt type: 1975 1976 :: 1977 1978 >> help rdmds 1979 1980 to get help on how to use :filelink:`rdmds <utils/matlab/rdmds.m>`. 1981 1982 Another useful script scans the terminal output file for :filelink:`pkg/monitor` 1983 information. 1984 1985 Most other scripts are for working in the curvilinear coordinate systems, 1986 and as yet are unpublished and undocumented. 1987 1988 pkg/mnc utils 1989 ~~~~~~~~~~~~~ 1990 f460f9a57e Ivan*1991 The following scripts and utilities have been written to help manipulate 1992 `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files: 9ce7d74115 Jeff*1993 1994 Tile Assembly: 1995 A `MATLAB <https://www.mathworks.com/>`_ script 1996 :filelink:`mnc_assembly.m <utils/matlab/mnc_assembly.m>` is available for** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1998.
1997 spatially “assembling” :filelink:`pkg/mnc` output. A convenience wrapper script 1998 called :filelink:`gluemnc.m <utils/matlab/gluemnc.m>` is also provided. Please use the 1999 `MATLAB <https://www.mathworks.com/>`_ help facility for more information. 2000 f460f9a57e Ivan*2001 A bash script :filelink:`gluemnc <utils/scripts/gluemnc>` is available for** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2003.
2002 spatially “assembling” :filelink:`pkg/mnc` NetCDF output. Please see 2003 :numref:`gluemnc` for details. 2004 9ce7d74115 Jeff*2005 gmt: 2006 As MITgcm evolves to handle more complicated domains and topologies, 2007 a suite of matlab tools is being written to more gracefully handle** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2009.
2008 the model files. This suite is called “gmt” which refers to** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2010.
2009 “generalized model topology” pre-/post-processing. Currently, this ba0b047096 Mart*2010 directory contains a `MATLAB <https://www.mathworks.com/>`_ script 9ce7d74115 Jeff*2011 :filelink:`gmt/rdnctiles.m <utils/matlab/gmt/rdnctiles.m>` that 2012 is able to read `netCDF <http://www.unidata.ucar.edu/software/netcdf/>`_ files for any domain. 2013 Additional scripts are being created that will work with these 2014 fields on a per-tile basis. 2015 2016 Pre-Processing Software 2017 ----------------------- 2018 2019 There is a suite of pre-processing software for interpolating bathymetry 2020 and forcing data, written by Adcroft and Biastoch. At some point, these 2021 will be made available for download. If you are in need of such 2022 software, contact one of them. 2023 2024 Potential Vorticity Matlab Toolbox 2025 ================================== 2026 2027 Author: Guillaume Maze 2028 2029 Introduction 2030 ------------ 2031 2032 This section of the documentation describes a `MATLAB <https://www.mathworks.com/>`_ package that aims 2033 to provide useful routines to compute vorticity fields (relative, 2034 potential and planetary) and its related components. This is an offline 2035 computation. It was developed to be used in mode water studies, so that 2036 it comes with other related routines, in particular ones computing 2037 surface vertical potential vorticity fluxes. 2038 a251b89fbb Guil*2039 .. note:: 2040 2041 This toolbox was developed in 2006 for the `CLIMODE project <https://www.nsf.gov/awardsearch/showAward?AWD_ID=0425150>`_. 2042 The toolbox routines are available on this 2043 `archived repository <https://github.com/gmaze/gmaze_legacy/tree/master/matlab/MIT>`_. 2044 9ce7d74115 Jeff*2045 Equations 2046 --------- 2047 2048 Potential vorticity 2049 ~~~~~~~~~~~~~~~~~~~ 2050 0bad585a21 Navi*2051 The package computes the three components of the relative vorticity, 2052 :math:`\boldsymbol{\omega}`, defined by: 9ce7d74115 Jeff*2053 2054 .. math:: 2055 \begin{aligned} 0bad585a21 Navi*2056 \boldsymbol{\omega} &= \nabla \times {\bf U} 2057 = \begin{pmatrix} 9ce7d74115 Jeff*2058 \omega_x\\ 2059 \omega_y\\ 2060 \zeta 0bad585a21 Navi*2061 \end{pmatrix} 2062 \simeq 2063 \begin{pmatrix} 2064 -\partial_z v\\ 2065 -\partial_z u\\ 2066 \partial_x v - \partial_y u 2067 \end{pmatrix} 2068 \end{aligned} 9ce7d74115 Jeff*2069 :label: pv_eq1 2070 2071 where we omitted the vertical velocity component (as done throughout the package). 2072 2073 The package then computes the potential vorticity as: 2074 2075 .. math:: 2076 \begin{aligned} 0bad585a21 Navi*2077 Q &= -\frac{1}{\rho} \boldsymbol{\omega} \cdot \nabla \sigma_\theta\\ 2078 &= -\frac{1}{\rho}\left(\omega_x \frac{\partial \sigma_\theta}{\partial x} + ba0b047096 Mart*2079 \omega_y \frac{\partial \sigma_\theta}{\partial y} + 0bad585a21 Navi*2080 \left(f + \zeta\right) \frac{\partial \sigma_\theta}{\partial z}\right) 2081 \end{aligned} 9ce7d74115 Jeff*2082 :label: pv_eq2 2083 2084 where :math:`\rho` is the density, :math:`\sigma_\theta` is the 2085 potential density (both eventually computed by the package) and 2086 :math:`f` is the Coriolis parameter. 2087 2088 The package is also able to compute the simpler planetary vorticity as: 2089 2090 .. math:: 2091 \begin{aligned} 0bad585a21 Navi*2092 Q_{\rm spl} & = -\frac{f}{\rho}\frac{\sigma_\theta}{\partial z} 2093 \end{aligned} 9ce7d74115 Jeff*2094 :label: pv_eq3 2095 2096 Surface vertical potential vorticity fluxes 2097 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2098 2099 These quantities are useful in mode water studies because of the 2100 impermeability theorem which states that for a given potential density 2101 layer (embedding a mode water), the integrated PV only changes through 2102 surface input/output. 2103 0bad585a21 Navi*2104 Vertical PV fluxes due to diabatic and frictional processes are given by: 9ce7d74115 Jeff*2105 2106 .. math:: 0bad585a21 Navi*2107 J^B_z = -\frac{f}{h}\left( \frac{\alpha Q_{\rm net}}{\text{C}_p}-\rho_0 \beta S_{\rm net}\right) 9ce7d74115 Jeff*2108 :label: pv_eq14a 2109 2110 .. math:: 0bad585a21 Navi*2111 J^F_z = \frac{1}{\rho\delta_e} (\hat{\boldsymbol{k}} \times \boldsymbol{\tau}) \cdot \nabla \sigma_m 9ce7d74115 Jeff*2112 :label: pv_eq15a 2113 2114 These components can be computed with the package. Details on the 2115 variables definition and the way these fluxes are derived can be found 2116 in :numref:`notes_flux_form`. 2117 2118 We now give some simple explanations about these fluxes and how they can 2119 reduce the PV value of an oceanic potential density layer. 2120 2121 Diabatic process 2122 ^^^^^^^^^^^^^^^^ 2123** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2125.
2124 Let’s take the PV flux due to surface buoyancy forcing from 2125 :eq:`pv_eq14a` and simplify it as: 2126 2127 .. math:: 2128 2129 \begin{aligned} 0bad585a21 Navi*2130 J^B_z \simeq -\frac{\alpha f}{h \text{C}_p} Q_{\rm net}\end{aligned} 9ce7d74115 Jeff*2131 0bad585a21 Navi*2132 When the net surface heat flux :math:`Q_{\rm net}` is upward, i.e., negative 9ce7d74115 Jeff*2133 and cooling the ocean (buoyancy loss), surface density will increase, 2134 triggering mixing which reduces the stratification and then the PV. 2135 2136 .. math:: 2137 \begin{aligned} 0bad585a21 Navi*2138 Q_{\rm net} &< 0 \phantom{WWW}\text{(upward, cooling)} \\ 9ce7d74115 Jeff*2139 J^B_z &> 0 \phantom{WWW}\text{(upward)} \\ 0bad585a21 Navi*2140 -\rho^{-1} \nabla \cdot J^B_z &< 0 \phantom{WWW}\text{(PV flux divergence)} \\ 2141 PV &\searrow \phantom{WWWi}\text{where } Q_{\rm net}<0 \end{aligned} 9ce7d74115 Jeff*2142 2143** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2145.
2144 Frictional process: “Down-front” wind-stress 2145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2146** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2148.
2147 Now let’s take the PV flux due to the “wind-driven buoyancy flux” from 2148 :eq:`pv_eq15a` and simplify it as: 2149 2150 .. math:: 2151 \begin{aligned} 2152 J^F_z &= \frac{1}{\rho\delta_e} \left( \tau_x\frac{\partial \sigma}{\partial y} - \tau_y\frac{\partial \sigma}{\partial x} \right) \\ 2153 &\simeq \frac{1}{\rho\delta_e} \tau_x\frac{\partial \sigma}{\partial y} \end{aligned} 2154 2155 When the wind is blowing from the east above the Gulf Stream (a region 2156 of high meridional density gradient), it induces an advection of dense 0bad585a21 Navi*2157 water from the northern side of the Gulf Stream to the southern side through 9ce7d74115 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2159.
2158 Ekman currents. Then, it induces a “wind-driven” buoyancy lost and 2159 mixing which reduces the stratification and the PV. 2160 2161 .. math:: 2162 \begin{aligned} 0bad585a21 Navi*2163 (\hat{\boldsymbol{k}} \times \boldsymbol{\tau}) \cdot \nabla \sigma &> 0 \phantom{WWW}\text{("Down-front" wind)} \\ 9ce7d74115 Jeff*2164 J^F_z &> 0 \phantom{WWW}\text{(upward)} \\ 0bad585a21 Navi*2165 -\rho^{-1} \nabla \cdot J^F_z &< 0 \phantom{WWW}\text{(PV flux divergence)} \\ 2166 PV &\searrow \phantom{WWW}\text{where } (\hat{\boldsymbol{k}} \times \boldsymbol{\tau}) \cdot \nabla \sigma>0 2167 \end{aligned} 9ce7d74115 Jeff*2168 2169 2170 Diabatic versus frictional processes 2171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2172 2173 A recent debate in the community arose about the relative role of these 2174 processes. Taking the ratio of :eq:`pv_eq14a` and 2175 :eq:`pv_eq15a` leads to: 2176 2177 .. math:: 2178 2179 \begin{aligned} 0bad585a21 Navi*2180 \frac{J^F_z}{J^B_z} & = \frac{ \dfrac{1}{\rho\delta_e} (\hat{\boldsymbol{k}} \times \boldsymbol{\tau}) \cdot \nabla \sigma } 2181 {-\dfrac{f}{h}\left( \dfrac{\alpha Q_{\rm net}}{\text{C}_p} - \rho_0 \beta S_{\rm net}\right)} \\ 2182 &\simeq \frac{Q_{\rm Ek}/\delta_e}{Q_{\rm net}/h} \nonumber 2183 \end{aligned} 9ce7d74115 Jeff*2184 2185 where appears the lateral heat flux induced by Ekman currents: 2186 2187 .. math:: 2188 2189 \begin{aligned} 0bad585a21 Navi*2190 Q_{\rm Ek} & = -\frac{\text{C}_p}{\alpha\rho f} (\hat{\boldsymbol{k}} \times \boldsymbol{\tau}) \cdot \nabla \sigma 9ce7d74115 Jeff*2191 \nonumber \\ 0bad585a21 Navi*2192 & = \frac{\text{C}_p}{\alpha}\delta_e \vec{\bf u}_{\rm Ek} \cdot \nabla \sigma\end{aligned} 9ce7d74115 Jeff*2193 2194 which can be computed with the package. In the aim of comparing both 2195 processes, it will be useful to plot surface net and lateral 2196 Ekman-induced heat fluxes together with PV fluxes. 2197 2198 Key routines 2199 ------------ 2200 2201 - **A_compute_potential_density.m**: Compute the potential density 2202 field. Requires the potential temperature and salinity (either total 2203 or anomalous) and produces one output file with the potential density 2204 field (file prefix is ``SIGMATHETA``). The routine uses :filelink:`utils/matlab/densjmd95.m`, 2205 a Matlab counterpart of the MITgcm built-in function to compute the 2206 density. 2207 2208 - **B_compute_relative_vorticity.m**: Compute the three components 2209 of the relative vorticity defined in :eq:`pv_eq1`. 2210 Requires the two horizontal velocity components and produces three 2211 output files with the three components (files prefix are ``OMEGAX``, 2212 ``OMEGAY`` and ``ZETA``). 2213 2214 - **C_compute_potential_vorticity.m**: Compute the potential 2215 vorticity without the negative ratio by the density. Two options are 2216 possible in order to compute either the full component (term into 2217 parenthesis in :eq:`pv_eq2` or the planetary component 2218 (:math:`f\partial_z\sigma_\theta` in :eq:`pv_eq3`). Requires 2219 the relative vorticity components and the potential density, and 2220 produces one output file with the potential vorticity (file prefix is 2221 ``PV`` for the full term and ``splPV`` for the planetary component). 2222 2223 - **D_compute_potential_vorticity.m**: Load the field computed with 2224 and divide it by :math:`-\rho` to obtain the correct potential 2225 vorticity. Require the density field and after loading, overwrite the 2226 file with prefix ``PV`` or ``splPV``. 2227 2228 - **compute_density.m**: Compute the density :math:`\rho` from the 2229 potential temperature and the salinity fields. 2230 2231 - **compute_JFz.m**: Compute the surface vertical PV flux due to 2232 frictional processes. Requires the wind stress components, density, 2233 potential density and Ekman layer depth (all of them, except the wind 2234 stress, may be computed with the package), and produces one output 2235 file with the PV flux :math:`J^F_z` (see :eq:`pv_eq15a` and 2236 with ``JFz`` as a prefix. 2237 2238 - **compute_JBz.m**: Compute the surface vertical PV flux due to 2239 diabatic processes as: 2240 2241 .. math:: 2242 \begin{aligned} 0bad585a21 Navi*2243 J^B_z & = -\frac{f}{h}\frac{\alpha Q_{\rm net}}{\text{C}_p} \end{aligned} 9ce7d74115 Jeff*2244 2245 which is a simplified version of the full expression given in 2246 :eq:`pv_eq14a`. Requires the net surface heat flux and the 2247 mixed layer depth (of which an estimation can be computed with the 2248 package), and produces one output file with the PV flux :math:`J^B_z` 2249 and with JBz as a prefix. 2250 2251 - **compute\_QEk.m**: Compute the horizontal heat flux due to Ekman 2252 currents from the PV flux induced by frictional forces as: 2253 2254 .. math:: 2255 \begin{aligned} 0bad585a21 Navi*2256 Q_{\rm Ek} & = - \frac{\text{C}_p \delta_e}{\alpha f}J^F_z\end{aligned} 9ce7d74115 Jeff*2257 2258 Requires the PV flux due to frictional forces and the Ekman layer 2259 depth, and produces one output with the heat flux and with QEk as a 2260 prefix. 2261 2262 - **eg\_main\_getPV**: A complete example of how to set up a master 2263 routine able to compute everything from the package. 2264 2265 Technical details 2266 ----------------- 2267 2268 File name 2269 ~~~~~~~~~ 2270 2271 A file name is formed by three parameters which need to be set up as 2272 global variables in `MATLAB <https://www.mathworks.com/>`_ before running any routines. They are: 2273 2274 - the prefix, i.e., the variable name (``netcdf_UVEL`` for example). This 2275 parameter is specified in the help section of all diagnostic 2276 routines. 2277 2278 - ``netcdf_domain``: the geographical domain. 2279 2280 - ``netcdf_suff``: the netcdf extension (nc or cdf for example). 2281 2282 Then, for example, if the calling `MATLAB <https://www.mathworks.com/>`_ routine had set up: 2283 2284 :: 2285 2286 global netcdf_THETA netcdf_SALTanom netcdf_domain netcdf_suff 2287 netcdf_THETA = 'THETA'; 2288 netcdf_SALTanom = 'SALT'; 2289 netcdf_domain = 'north_atlantic'; 2290 netcdf_suff = 'nc'; 2291 2292 the routine A_compute_potential_density.m to compute the potential 2293 density field, will look for the files: 2294 2295 :: 2296 2297 THETA.north_atlantic.nc 2298 SALT.north_atlantic.nc 2299 2300 and the output file will automatically be: 2301 ``SIGMATHETA.north_atlantic.nc``. 2302 2303 Otherwise indicated, output file prefix cannot be changed. 2304 2305 Path to file 2306 ~~~~~~~~~~~~ 2307 2308 All diagnostic routines look for input files in a subdirectory (relative 2309 to the `MATLAB <https://www.mathworks.com/>`_ routine directory) 2310 called ``./netcdf-files``, which in turn is 2311 supposed to contain subdirectories for each set of fields. For example, 2312 computing the potential density for the timestep 12H00 02/03/2005 will 2313 require a subdirectory with the potential temperature and salinity files 2314 like: 2315 2316 :: 2317 2318 ./netcdf-files/200501031200/THETA.north_atlantic.nc 2319 ./netcdf-files/200501031200/SALT.north_atlantic.nc 2320 2321 The output file ``SIGMATHETA.north\_atlantic.nc`` will be created in 2322 ``./netcdf-files/200501031200/``. All diagnostic routines take as argument 2323 the name of the timestep subdirectory into ``./netcdf-files``. 2324 2325 Grids 2326 ~~~~~ 2327 2328 With MITgcm numerical outputs, velocity and tracer fields may not be 2329 defined on the same grid. Usually, ``UVEL`` and ``VVEL`` are defined on a C-grid 2330 but when interpolated from a cube-sphere simulation they are defined on 2331 a A-grid. When it is needed, routines allow to set up a global variable 2332 which define the grid to use. 2333 2334 .. _notes_flux_form: 2335 2336 Notes on the flux form of the PV equation and vertical PV fluxes 2337 ---------------------------------------------------------------- 2338 2339 Flux form of the PV equation 2340 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2341 2342 The conservative flux form of the potential vorticity equation is: 2343 2344 .. math:: 2345 \begin{aligned} 0bad585a21 Navi*2346 \frac{\partial \rho Q}{\partial t} + \nabla \cdot \vec{\bf J} & = 0 2347 \end{aligned} 9ce7d74115 Jeff*2348 :label: pv_eq4 2349 2350 where the potential vorticity :math:`Q` is given by :eq:`pv_eq2`. 2351 2352 The generalized flux vector of potential vorticity is: 2353 2354 .. math:: 2355 \begin{aligned} 0bad585a21 Navi*2356 \vec{\bf J} & = \rho Q \vec{\bf u} + \vec{\bf N}_Q 2357 \end{aligned} 9ce7d74115 Jeff*2358 2359 which allows to rewrite :eq:`pv_eq4` as: 2360 2361 .. math:: 2362 \begin{aligned} 0bad585a21 Navi*2363 \frac{DQ}{dt} & = - \frac{1}{\rho} \nabla \cdot \vec{\bf N}_Q 2364 \end{aligned} 9ce7d74115 Jeff*2365 :label: pv_eq5 2366 0bad585a21 Navi*2367 where the non-advective PV flux :math:`\vec{\bf N}_Q` is given by: 9ce7d74115 Jeff*2368 2369 .. math:: 2370 \begin{aligned} 0bad585a21 Navi*2371 \vec{\bf N}_Q & = -\frac{\rho_0}{g}B \vec{\boldsymbol{\omega}}_a + \vec{\bf F} \times \nabla \sigma_\theta 2372 \end{aligned} 9ce7d74115 Jeff*2373 :label: pv_eq6 2374 2375 Its first component is linked to the buoyancy forcing: 2376 2377 .. math:: 2378 \begin{aligned} 0bad585a21 Navi*2379 B & = -\frac{g}{\rho_o}\frac{D \sigma_\theta}{dt} 2380 \end{aligned} 9ce7d74115 Jeff*2381 2382 and the second one to the non-conservative body forces per unit mass: 2383 2384 .. math:: 2385 \begin{aligned} 0bad585a21 Navi*2386 \vec{\bf F} & = \frac{D \vec{\bf u}}{Dt} + 2 \vec{\boldsymbol{\Omega}} \times \vec{\bf u} + \nabla p 2387 \end{aligned} 9ce7d74115 Jeff*2388 2389 Note that introducing :math:`B` into :eq:`pv_eq6` yields: 2390 2391 .. math:: 2392 \begin{aligned} 0bad585a21 Navi*2393 \vec{\bf N}_Q & = \boldsymbol{\omega}_a \frac{D \sigma_\theta}{dt} + \vec{\bf F} \times \nabla \sigma_\theta 2394 \end{aligned} 9ce7d74115 Jeff*2395 2396** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2398.
2397 Determining the PV flux at the ocean’s surface 2398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2399 2400 In the context of mode water study, we are particularly interested in how 2401 the PV may be reduced by surface PV fluxes because a mode water is 2402 characterized by a low PV value. Considering the volume limited by two 2403 :math:`iso-\sigma_\theta`, PV flux is limited to surface processes and 0bad585a21 Navi*2404 then vertical component of :math:`\vec{\bf N}_Q`. It is supposed that 2405 :math:`B` and :math:`\vec{\bf F}` will only be non-zero in the mixed layer 9ce7d74115 Jeff*2406 (of depth :math:`h` and variable density :math:`\sigma_m`) exposed to** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2408.
2407 mechanical forcing by the wind and buoyancy fluxes through the ocean’s 2408 surface. 2409 2410 Given the assumption of a mechanical forcing confined to a thin surface 2411 Ekman layer (of depth :math:`\delta_e`, eventually computed by the 2412 package) and of hydrostatic and geostrophic balances, we can write: 2413 2414 .. math:: 2415 \begin{aligned} 0bad585a21 Navi*2416 \vec{\bf u}_g & = \frac{1}{\rho f} \hat{\boldsymbol{k}} \times \nabla p \\ 2417 \frac{\partial p_m}{\partial z} & = -\sigma_m g \\ 2418 \frac{\partial \sigma_m}{\partial t} + \vec{\bf u}_m \cdot \nabla \sigma_m & = -\frac{\rho_0}{g}B 2419 \end{aligned} 9ce7d74115 Jeff*2420 :label: pv_eq7 2421 2422 where: 2423 2424 .. math:: 2425 \begin{aligned} 0bad585a21 Navi*2426 \vec{\bf u}_m & = \vec{\bf u}_g + \vec{\bf u}_{\rm Ek} + o(R_o) 2427 \end{aligned} 9ce7d74115 Jeff*2428 :label: pv_eq8 2429 2430 is the full velocity field composed of the geostrophic current 0bad585a21 Navi*2431 :math:`\vec{\bf u}_g` and the Ekman drift: 9ce7d74115 Jeff*2432 2433 .. math:: 2434 \begin{aligned} 0bad585a21 Navi*2435 \vec{\bf u}_{\rm Ek} & = -\frac{1}{\rho f} \hat{\boldsymbol{k}} \times \frac{\partial \boldsymbol{\tau}}{\partial z} 2436 \end{aligned} 9ce7d74115 Jeff*2437 :label: pv_eq9 2438 0bad585a21 Navi*2439 (where :math:`\boldsymbol{\tau}` is the wind stress) and last by other ageostrophic 9ce7d74115 Jeff*2440 components of :math:`o(R_o)` which are neglected. 2441 2442 Partitioning the buoyancy forcing as: 2443 2444 .. math:: 2445 \begin{aligned} 0bad585a21 Navi*2446 B & = B_g + B_{\rm Ek} 2447 \end{aligned} 9ce7d74115 Jeff*2448 :label: pv_eq10 2449 2450 and using :eq:`pv_eq8` and :eq:`pv_eq9`, :eq:`pv_eq7` becomes: 2451 2452 .. math:: 2453 \begin{aligned} 0bad585a21 Navi*2454 \frac{\partial \sigma_m}{\partial t} + \vec{\bf u}_g \cdot \nabla \sigma_m & = -\frac{\rho_0}{g} B_g 2455 \end{aligned} 9ce7d74115 Jeff*2456** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2458.
2457 revealing the “wind-driven buoyancy forcing”: 2458 2459 .. math:: 2460 \begin{aligned} 0bad585a21 Navi*2461 B_{\rm Ek} & = \frac{g}{\rho_0}\frac{1}{\rho f}\left(\hat{\boldsymbol{k}} \times \frac{\partial \boldsymbol{\tau}}{\partial z}\right)\cdot \nabla \sigma_m 2462 \end{aligned} 9ce7d74115 Jeff*2463 2464 Note that since: 2465 2466 .. math:: 2467 \begin{aligned} 0bad585a21 Navi*2468 \frac{\partial B_g}{\partial z} & = \frac{\partial}{\partial z}\left(-\frac{g}{\rho_0} \vec{\bf u}_g \cdot \nabla \sigma_m\right) 2469 = -\frac{g}{\rho_0}\frac{\partial \vec{\bf u}_g}{\partial z} \cdot \nabla \sigma_m 2470 = 0 2471 \end{aligned} 9ce7d74115 Jeff*2472 2473 :math:`B_g` must be uniform throughout the depth of the mixed layer and 2474 then being related to the surface buoyancy flux by integrating 2475 :eq:`pv_eq10` through the mixed layer: 2476 2477 .. math:: 2478 \begin{aligned} 0bad585a21 Navi*2479 \int_{-h}^0 B\,dz &= h B_g + \int_{-h}^0 B_{\rm Ek}\,dz = \mathcal{B}_{\rm in} 2480 \end{aligned} 9ce7d74115 Jeff*2481 :label: pv_eq11 2482 0bad585a21 Navi*2483 where :math:`\mathcal{B}_{\rm in}` is the vertically integrated surface buoyancy (in)flux: 9ce7d74115 Jeff*2484 2485 .. math:: 2486 \begin{aligned} 0bad585a21 Navi*2487 \mathcal{B}_{\rm in} & = \frac{g}{\rho_o}\left( \frac{\alpha Q_{\rm net}}{\text{C}_p} - \rho_0\beta S_{\rm net}\right) 2488 \end{aligned} 9ce7d74115 Jeff*2489 :label: pv_eq12 2490 2491 with :math:`\alpha\simeq 2.5\times10^{-4}\, \text{K}^{-1}` the thermal 2492 expansion coefficient (computed by the package otherwise), 0bad585a21 Navi*2493 :math:`\text{C}_p=4187 \text{ J kg}^{-1}\text{K}^{-1}` the specific heat of 2494 seawater, :math:`Q_{\rm net}\text{ (W m$^{-2}$)}` the net heat surface ba0b047096 Mart*2495 flux (positive downward, warming the ocean), :math:`\beta\text{ 2496 ((g/kg)$^{-1}$)}` the saline contraction coefficient, and 0bad585a21 Navi*2497 :math:`S_{\rm net}=S*(E-P)\text{ ((g/kg) m s$^{-1}$)}` the net freshwater ba0b047096 Mart*2498 surface flux with :math:`S\text{ (g/kg)}` the surface salinity and 2499 :math:`(E-P)\text{ (m s$^{-1}$)}` the fresh water flux. 9ce7d74115 Jeff*2500 2501 Introducing the body force in the Ekman layer: 2502 2503 .. math:: 2504 \begin{aligned} 0bad585a21 Navi*2505 F_z & = \frac{1}{\rho}\frac{\partial \boldsymbol{\tau}}{\partial z} 2506 \end{aligned} 9ce7d74115 Jeff*2507 2508 the vertical component of :eq:`pv_eq6` is: 2509 2510 .. math:: 2511 \begin{aligned} 0bad585a21 Navi*2512 \vec{\bf N}_Q \cdot \hat{\boldsymbol{k}} &= -\frac{\rho_0}{g}(B_g+B_{\rm Ek}) \omega_z 9ce7d74115 Jeff*2513 + \frac{1}{\rho} 0bad585a21 Navi*2514 \left( \frac{\partial \boldsymbol{\tau}}{\partial z} \times \nabla \sigma_\theta \right) \cdot \hat{\boldsymbol{k}} \\ 9ce7d74115 Jeff*2515 &= -\frac{\rho_0}{g}B_g\omega_z 2516 -\frac{\rho_0}{g} 0bad585a21 Navi*2517 \left[ \frac{g}{\rho_0}\frac{1}{\rho f} \left( \hat{\boldsymbol{k}} \times \frac{\partial \boldsymbol{\tau}}{\partial z} \right) 2518 \cdot \nabla \sigma_m \right]\omega_z 9ce7d74115 Jeff*2519 + \frac{1}{\rho} 0bad585a21 Navi*2520 \left( \frac{\partial \boldsymbol{\tau}}{\partial z}\times \nabla \sigma_\theta \right)\cdot\hat{\boldsymbol{k}}\\ 9ce7d74115 Jeff*2521 &= -\frac{\rho_0}{g}B_g\omega_z 0bad585a21 Navi*2522 + \left(1-\frac{\omega_z}{f}\right)\left(\frac{1}{\rho}\frac{\partial \boldsymbol{\tau}}{\partial z} 2523 \times \nabla \sigma_\theta \right)\cdot\hat{\boldsymbol{k}}\end{aligned} 9ce7d74115 Jeff*2524 2525 and given the assumption that :math:`\omega_z\simeq f`, the second term 2526 vanishes and we obtain: 2527 2528 .. math:: 2529 \begin{aligned} 0bad585a21 Navi*2530 \vec{\bf N}_Q \cdot \hat{\boldsymbol{k}} & = -\frac{\rho_0}{g}f B_g . 2531 \end{aligned} 9ce7d74115 Jeff*2532 :label: pv_eq13 2533 2534 Note that the wind-stress forcing does not appear explicitly here but 2535 is implicit in :math:`B_g` through :eq:`pv_eq11`: the buoyancy 2536 forcing :math:`B_g` is determined by the difference between the 0bad585a21 Navi*2537 integrated surface buoyancy flux :math:`\mathcal{B}_{\rm in}` and the 9ce7d74115 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2539.
2538 integrated “wind-driven buoyancy forcing”: 2539 2540 .. math:: 2541 2542 \begin{aligned} 0bad585a21 Navi*2543 B_g &= \frac{1}{h}\left( \mathcal{B}_{\rm in} - \int_{-h}^0B_{\rm Ek}dz \right) \\ 2544 &= \frac{1}{h}\frac{g}{\rho_0}\left( \frac{\alpha Q_{\rm net}}{\text{C}_p} - \rho_0 \beta S_{\rm net}\right) ba0b047096 Mart*2545 - \frac{1}{h}\int_{-h}^0 0bad585a21 Navi*2546 \frac{g}{\rho_0}\frac{1}{\rho f}\left (\hat{\boldsymbol{k}}\times \frac{\partial \boldsymbol{\tau}}{\partial z} \right) \cdot \nabla \sigma_m dz \\ 2547 &= \frac{1}{h}\frac{g}{\rho_0}\left( \frac{\alpha Q_{\rm net}}{\text{C}_p} - \rho_0 \beta S_{\rm net}\right) 2548 - \frac{g}{\rho_0}\frac{1}{\rho f \delta_e}\left (\hat{\boldsymbol{k}}\times \boldsymbol{\tau} \right) \cdot \nabla \sigma_m\end{aligned} 9ce7d74115 Jeff*2549 2550 Finally, from :eq:`pv_eq6`, the vertical surface flux of PV may 2551 be written as: 2552 2553 .. math:: 2554 \begin{aligned} 0bad585a21 Navi*2555 \vec{\bf N}_Q \cdot \hat{\boldsymbol{k}} &= J^B_z + J^F_z \\ 2556 J^B_z &= -\frac{f}{h}\left( \frac{\alpha Q_{\rm net}}{\text{C}_p}-\rho_0 \beta S_{\rm net}\right) \\ 2557 J^F_z &= \frac{1}{\rho\delta_e} (\hat{\boldsymbol{k}}\times \boldsymbol{\tau}) \cdot \nabla \sigma_m \end{aligned} 5ab6faf8fd gael*2558 2559 .. _sub_outp_pkg_flt: 2560** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2562.
2561 pkg/flt – Simulation of float / parcel displacements 2562 ==================================================== 2563 2564 .. include:: flt.rst
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated from https://github.com/darwinproject/darwin3 by the 2.3.7-MITgcm-0.1 LXR engine. The LXR team |
|