Utilities
*********

.. _MITgcmutils:

MITgcmutils
===========

This Python package includes a number of helpful functions and scripts for
dealing with MITgcm output.  You can install it from the model repository (in
directory :filelink:`utils/python/MITgcmutils`) or from the Python Package
Index:

::

    pip install --user MITgcmutils

The following functions are exposed at the package level:

- from module mds: :meth:`~MITgcmutils.mds.rdmds` and
  :meth:`~MITgcmutils.mds.wrmds`
- from module mnc: :meth:`~MITgcmutils.mnc.rdmnc` and
  :meth:`~MITgcmutils.mnc.mnc_files`
- from module ptracers: :meth:`~MITgcmutils.ptracers.iolabel` and:
  :meth:`~MITgcmutils.ptracers.iolabel2num`
- from module diagnostics: :meth:`~MITgcmutils.diagnostics.readstats`

The package also includes a standalone script for joining tiled mnc files:
gluemncbig_.

For more functions, see the individual modules:

mds
---

.. automodule:: MITgcmutils.mds
    :members:

mnc
---

.. automodule:: MITgcmutils.mnc
    :members:

diagnostics
-----------

.. automodule:: MITgcmutils.diagnostics
    :members:

ptracers
--------

.. automodule:: MITgcmutils.ptracers
    :members:

density
-------

.. automodule:: MITgcmutils.density
    :members:

miscellaneous utilities
-----------------------

.. automodule:: MITgcmutils.utils
    :members:

conversion
----------

.. automodule:: MITgcmutils.conversion
    :members:

cs
--

.. automodule:: MITgcmutils.cs
    :members:

llc
---

.. automodule:: MITgcmutils.llc
    :members:

examples
--------

.. automodule:: MITgcmutils.examples
    :members:

.. _gluemncbig:

gluemncbig
----------

This command line script is part of MITgcmutils and provides a convenient
method for stitching together NetCDF files into a single file covering the
model domain. Be careful though - the resulting files can get very large.

.. program-output:: ../utils/python/MITgcmutils/scripts/gluemncbig --help


.. _Bash scripts:

Bash scripts
============

:filelink:`utils/scripts` contains utilities for handling model input and 
output. You can add these command line scripts to the system's search path by 
modifying the ``PATH`` variable. To permanently access MITgcm bash utilities, 
put this line in your shell configuration file e.g. ``.bashrc`` or ``.zshrc``:

::

    export PATH=$PATH:/path/to/your/MITgcm/utils/scripts

.. _gluemnc:

gluemnc
-------

The ``gluemnc`` script is a utility for combining multiple NetCDF (.nc) output 
files generated by MITgcm's **MNC** package, :filelink:`pkg/mnc`. MITgcm writes 
output in a tiled format, each file corresponds to a different sub-region of 
the computational domain. ``gluemnc`` merges these tiles into a single global 
NetCDF file for easier post-processing and visualization.

Usage
^^^^^

.. code-block:: sh

   gluemnc <mnc_filename>

Options
"""""""

- ``<mnc_filename>``: A pattern matching the tiled NetCDF files to merge. 
  Typically, this is a prefix shared by all relevant files, e.g.
  ``state.0000000000.*``

Example
"""""""

:filelink:`pkg/mnc` produces NetCDF output on a per tile format. Here, we show 
a six tile decompostion of oceanic state variables:

.. code-block:: sh

   state.0000000000.t001.nc  state.0000000000.t002.nc  state.0000000000.t003.nc
   state.0000000000.t004.nc  state.0000000000.t005.nc  state.0000000000.t006.nc

You can merge these into a single file using:

.. code-block:: sh

   gluemnc state.0000000000.*

This will generate a single file containing the full computational domain, 
``state.0000000000.glob.nc``.

Dependencies
^^^^^^^^^^^^

``gluemnc`` requires the following:

- ``ncks`` installed from 
  `NetCDF Operators (NCO) <http://nco.sourceforge.net>`_. 
- :filelink:`utils/scripts/xplodemnc` in a findable location, either by adding 
  it to the system search path or by copy+pasting the script in your working 
  directory. 

Notes
^^^^^

- The script **only works for tiled output** from MITgcm's **MNC** package. It 
  does not merge output from other formats like binary files.
- Merging large datasets may require significant memory.