Metadata-Version: 2.4
Name: pytmmutils
Version: 1.0.0
Summary: Python package for reading/writing data in support of the Transport Matrix Method (TMM)
Author-email: Samar Khatiwala <samkat6@gmail.com>, Jamie Carr <jammehcarr@gmail.com>
Project-URL: Homepage, https://github.com/samarkhatiwala/pytmmutils
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pyioutils
Requires-Dist: pymatreader
Dynamic: license-file

This repository contains functions written in Python for reading and writing files in support of the Transport Matrix Method ([TMM](https://github.com/samarkhatiwala/tmm)). They are translations of the original Matlab code and, for the most part, work identically (but adhere to Python conventions such as 0-based indexing).

**IMPORTANT**: Please do NOT post this code on your own github or other website. See LICENSE.txt for licensing information.

Feel free to email if you have any questions: <samkat6@gmail.com>

------------------------------------------------------------------------------------------------

**Installation**

```bash
pip install pytmmutils
```
(This should automatically install any required modules, including my [`pyioutils`](https://github.com/samarkhatiwala/pyioutils) package.)

**Usage**

The various functions for manipulating TMM-related data, such as mapping "matrix" to  "grid" (and vice versa), depend on configuration, grid, box geometry and forcing data from the underlying general circulation model from which the transport matrices (TMs) were extracted. These data as well as the TMs are distributed as Matlab .mat files. To use them in Python you will first need to convert the underlying Matlab data to a Python-compatible format. The function `convertmat2dict` does this for you by translating the variables in the .mat file to Python datatypes and placing them in a dictionary. In particular, because these data are used by most functions, it is recommended that you convert  `config_data.mat`, `grid.mat`, `boxes.mat` and `profile_data.mat`  into dictionaries and save them to files and place them in the same corresponding locations as the .mat files. See `examples/example1.py` for how to perform the conversion and save the resulting dictionary in a HDF5 file.

Note that the above translation also changes the data orientation to be compatible with Python conventions (e.g., a Matlab 3-d array oriented as (longitude, latitude, depth) is permuted into a 3-d NumPy array oriented as (depth, latitude, longitude)).

The various examples in the `examples` directory illustrate different functionality which should enable you to replicate the Matlab workflow in TMM scripts such as `make_input_files...m` entirely in Python. To facilitate running these examples, the `TestData` directory contains translated data for the `MIT_Matrix_Global_2.8deg` configuration.

