doc/utilities/utilities.rst

7621b5d564 Oliv*0001 Utilities
                0002 *********
                0003
                0004 .. _MITgcmutils:
                0005
                0006 MITgcmutils
                0007 ===========
                0008
58679b5a83 Esta*0009 This Python package includes a number of helpful functions and scripts for
                0010 dealing with MITgcm output.  You can install it from the model repository (in
                0011 directory :filelink:`utils/python/MITgcmutils`) or from the Python Package
                0012 Index:
7621b5d564 Oliv*0013
                0014 ::
                0015
                0016     pip install --user MITgcmutils
                0017
                0018 The following functions are exposed at the package level:
                0019
58679b5a83 Esta*0020 - from module mds: :meth:`~MITgcmutils.mds.rdmds` and
                0021   :meth:`~MITgcmutils.mds.wrmds`
                0022 - from module mnc: :meth:`~MITgcmutils.mnc.rdmnc` and
                0023   :meth:`~MITgcmutils.mnc.mnc_files`
                0024 - from module ptracers: :meth:`~MITgcmutils.ptracers.iolabel` and:
                0025   :meth:`~MITgcmutils.ptracers.iolabel2num`
7621b5d564 Oliv*0026 - from module diagnostics: :meth:`~MITgcmutils.diagnostics.readstats`
                0027
58679b5a83 Esta*0028 The package also includes a standalone script for joining tiled mnc files:
                0029 gluemncbig_.
7621b5d564 Oliv*0030
                0031 For more functions, see the individual modules:
                0032
                0033 mds
                0034 ---
                0035
                0036 .. automodule:: MITgcmutils.mds
                0037     :members:
                0038
                0039 mnc
                0040 ---
                0041
                0042 .. automodule:: MITgcmutils.mnc
                0043     :members:
                0044
                0045 diagnostics
                0046 -----------
                0047
                0048 .. automodule:: MITgcmutils.diagnostics
                0049     :members:
                0050
                0051 ptracers
                0052 --------
                0053
                0054 .. automodule:: MITgcmutils.ptracers
                0055     :members:
                0056
58679b5a83 Esta*0057 density
                0058 -------
7621b5d564 Oliv*0059
58679b5a83 Esta*0060 .. automodule:: MITgcmutils.density
7621b5d564 Oliv*0061     :members:
                0062
58679b5a83 Esta*0063 miscellaneous utilities
                0064 -----------------------
7621b5d564 Oliv*0065
58679b5a83 Esta*0066 .. automodule:: MITgcmutils.utils
                0067     :members:
                0068
                0069 conversion
                0070 ----------
                0071
                0072 .. automodule:: MITgcmutils.conversion
7621b5d564 Oliv*0073     :members:
                0074
                0075 cs
                0076 --
                0077
                0078 .. automodule:: MITgcmutils.cs
                0079     :members:
                0080
                0081 llc
                0082 ---
                0083
                0084 .. automodule:: MITgcmutils.llc
                0085     :members:
                0086
58679b5a83 Esta*0087 examples
                0088 --------
                0089
                0090 .. automodule:: MITgcmutils.examples
                0091     :members:
                0092
7621b5d564 Oliv*0093 .. _gluemncbig:
                0094
                0095 gluemncbig
                0096 ----------
                0097
58679b5a83 Esta*0098 This command line script is part of MITgcmutils and provides a convenient
                0099 method for stitching together NetCDF files into a single file covering the
                0100 model domain. Be careful though - the resulting files can get very large.
7621b5d564 Oliv*0101
                0102 .. program-output:: ../utils/python/MITgcmutils/scripts/gluemncbig --help
f460f9a57e Ivan*0103
                0104
                0105 .. _Bash scripts:
                0106
                0107 Bash scripts
                0108 ============
                0109
                0110 :filelink:`utils/scripts` contains utilities for handling model input and
                0111 output. You can add these command line scripts to the system's search path by
                0112 modifying the ``PATH`` variable. To permanently access MITgcm bash utilities,
                0113 put this line in your shell configuration file e.g. ``.bashrc`` or ``.zshrc``:
                0114
                0115 ::
                0116
                0117     export PATH=$PATH:/path/to/your/MITgcm/utils/scripts
                0118
                0119 .. _gluemnc:
                0120
                0121 gluemnc
                0122 -------
                0123
                0124 The ``gluemnc`` script is a utility for combining multiple NetCDF (.nc) output
                0125 files generated by MITgcm's **MNC** package, :filelink:`pkg/mnc`. MITgcm writes
                0126 output in a tiled format, each file corresponds to a different sub-region of
                0127 the computational domain. ``gluemnc`` merges these tiles into a single global
                0128 NetCDF file for easier post-processing and visualization.
                0129
                0130 Usage
                0131 ^^^^^
                0132
                0133 .. code-block:: sh
                0134
                0135    gluemnc <mnc_filename>
                0136
                0137 Options
                0138 """""""
                0139
                0140 - ``<mnc_filename>``: A pattern matching the tiled NetCDF files to merge.
                0141   Typically, this is a prefix shared by all relevant files, e.g.
                0142   ``state.0000000000.*``
                0143
                0144 Example
                0145 """""""
                0146
                0147 :filelink:`pkg/mnc` produces NetCDF output on a per tile format. Here, we show
                0148 a six tile decompostion of oceanic state variables:
                0149
                0150 .. code-block:: sh
                0151
                0152    state.0000000000.t001.nc  state.0000000000.t002.nc  state.0000000000.t003.nc
                0153    state.0000000000.t004.nc  state.0000000000.t005.nc  state.0000000000.t006.nc
                0154
                0155 You can merge these into a single file using:
                0156
                0157 .. code-block:: sh
                0158
                0159    gluemnc state.0000000000.*
                0160
                0161 This will generate a single file containing the full computational domain,
                0162 ``state.0000000000.glob.nc``.
                0163
                0164 Dependencies
                0165 ^^^^^^^^^^^^
                0166
                0167 ``gluemnc`` requires the following:
                0168
                0169 - ``ncks`` installed from
                0170   `NetCDF Operators (NCO) <http://nco.sourceforge.net>`_.
                0171 - :filelink:`utils/scripts/xplodemnc` in a findable location, either by adding
                0172   it to the system search path or by copy+pasting the script in your working
                0173   directory.
                0174
                0175 Notes
                0176 ^^^^^
                0177
                0178 - The script **only works for tiled output** from MITgcm's **MNC** package. It
                0179   does not merge output from other formats like binary files.
                0180 - Merging large datasets may require significant memory.