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