RFC: Wrap grdmath

[weiji14]

Description of proposed changes

Initial commit for wrapping the grdmath function which is a "Raster calculator for grids (element by element)".

Preview docs at https://pygmt-git-wrap-grdmath-gmt.vercel.app/api/generated/pygmt.GrdMathCalc.html.

This is an initial proof of concept that is meant to solicit ideas from other PyGMT developers. The current implementation works by building and storing a 'computational graph' of the grid operations in a GrdMathCalc class object. An output NetCDF grid or xarray.DataArray is produced upon calling .compute() or by setting outgrid=True.

Example code:

import pygmt

grdcalc = pygmt.GrdMathCalc()  # instantiate grdmath Calculator object

# Basic square root operation
grid0 = grdcalc.sqrt(ingrid="@earth_relief_01d", outgrid=True, region=[0, 3, 6, 9])

# Complex chained operation
grid1 = grdcalc.sqrt(ingrid="@earth_relief_01d_p")
assert grid1.arg_str == "@earth_relief_01d_p SQRT"
grid2 = grdcalc.std(ingrid="@earth_relief_01d_g")
assert grid2.arg_str == "@earth_relief_01d_g STD"
grid3 = grid1.multiply(ingrid=grid2, region=[0, 3, 6, 9])
assert (
    grid3.arg_str == "@earth_relief_01d_p SQRT @earth_relief_01d_g STD -R0/3/6/9 MUL"
)
output = grid3.compute()

The API here is inspired by many other Python 'array' libraries. Note that there is a Python array API standard that is in the works which should inform the grdmath implementation here. E.g. doing grdcalc.mean should ideally follow the API style of np.mean if possible.

References:

• Sources of inspiration:
  • Building computational graphs in Python - common in Deep Learning frameworks like Chainer, Pytorch and Tensorflow
  • The compute in dask.Array.compute - https://docs.dask.org/en/latest/generated/dask.array.Array.compute.html
• Python array API standard:
  • /~https://github.com/data-apis/array-api
  • https://data-apis.org/blog/announcing_the_consortium

Fixes #916

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[totallynotdavid]

Is there a timeline for when this will be released or merged into main?

[weiji14]

Is there a timeline for when this will be released or merged into main?

Hi @totallynotdavid, this is a proof of concept and we don't have an exact timeline on when to merge this PR. We've somewhat deprioritized grdmath because common operations can often be done more intuitively in xarray (see #916 (comment)). But if there's a math operator you're interested in that's not available in xarray, we could try to get this PR going again.