Add common alias cores (x) for grdimage and other multi-threaded modules (#625)

Used for setting the number of cores to be used
in any OpenMP-enabled multi-threaded algorithms.
See also https://docs.generic-mapping-tools.org/6.1/cookbook/options.html#selecting-number-of-cpu-cores-the-x-option.

Author: weiji14

pygmt/base_plotting.py

@@ -310,6 +310,7 @@ def grdcontour(self, grid, **kwargs):
         I="shading",
         C="cmap",
         t="transparency",
+        x="cores",
     )
     @kwargs_to_strings(R="sequence")
     def grdimage(self, grid, **kwargs):
@@ -327,6 +328,7 @@ def grdimage(self, grid, **kwargs):
         grid : str or xarray.DataArray
             The file name of the input grid or the grid loaded as a DataArray.
         {t}
+        {x}
 
         """
         kwargs = self._preprocess(**kwargs)

pygmt/helpers/decorators.py

@@ -89,6 +89,16 @@
             Only visible when PDF or raster format output is selected.
             Only the PNG format selection adds a transparency layer
             in the image (for further processing). """,
+    "x": """\
+        cores : int
+            ``[[-]n]``.
+            Limit the number of cores to be used in any OpenMP-enabled
+            multi-threaded algorithms. By default we try to use all available
+            cores. Set a number *n* to only use n cores (if too large it will
+            be truncated to the maximum cores available). Finally, give a
+            negative number *-n* to select (all - n) cores (or at least 1 if
+            n equals or exceeds all).
+            """,
 }