xmitgcm is a python package for reading MITgcm binary MDS files into xarray data structures. By storing data in dask arrays, xmitgcm enables parallel, out-of-core analysis of MITgcm output data.
- HTML documentation: https://xmitgcm.readthedocs.org
- Issue tracker: https://github.com/MITgcm/xmitgcm/issues
- Source code: https://github.com/MITgcm/xmitgcm
xmitgcm is compatible with python >=3.7. It requires xarray (>= version 0.14.1) and dask (>= version 1.0). These packages are most reliably installed via the conda environment management system, which is part of the Anaconda python distribution. Assuming you have conda available on your system, the dependencies can be installed with the command:
conda install xarray dask
If you are using earlier versions of these packages, you should update before installing xmitgcm.
If you just want to use xmitgcm, the easiest way is to install via pip:
pip install xmitgcm
This will automatically install the latest release from pypi.
xmitgcm is under active development. To obtain the latest development version, you may clone the source repository and install it:
git clone https://github.com/MITgcm/xmitgcm.git cd xmitgcm python setup.py install
Users are encouraged to fork xmitgcm and submit issues and pull requests.
First make sure you understand what an xarray Dataset object is. Then find some MITgcm MDS data. If you don't have any data of your own, you can download the xmitgcm test repositories To download the some test data, run the shell commands:
$ curl -L -J -O https://ndownloader.figshare.com/files/6494718 $ tar -xvzf global_oce_latlon.tar.gz
This will create a directory called global_oce_latlon which we will use
for the rest of these examples. If you have your own data, replace this with
the path to your mitgcm files.
To open MITgcm MDS data as an xarray.Dataset, do the following in python:
from xmitgcm import open_mdsdataset data_dir = './global_oce_latlon' ds = open_mdsdataset(data_dir)
data_dir, should be the path (absolute or relative) to an
MITgcm run directory. xmitgcm will automatically scan this directory and
try to determine the file prefixes and iteration numbers to read. In some
configurations, the open_mdsdataset function may work without further
keyword arguments. In most cases, you will have to specify further details.
Consult the online documentation for more details.