Improve grdseamount documentation (#3712) (#3714)

* Improve grdseamount docs

Cleaning up and adding figures

* fine tune

* Update grdseamount.rst

* update -M

* Update grdseamount.c

* Update grdseamount.rst

Co-authored-by: Paul Wessel <[email protected]>

Author: github-actions[bot]

doc/rst/source/supplements/potential/grdseamount.rst

@@ -22,7 +22,8 @@ Synopsis
 [ |-F|\ [*flattening*] ]
 [ |-G|\ *grdfile* ]
 [ |-L|\ [*cut*] ]
-[ |-M|\ *list* ] [ |-N|\ *norm* ]
+[ |-M|\ [*list*] ]
+[ |-N|\ *norm* ]
 [ |-Q|\ *bmode*/*qmode* ]
 [ |-S|\ *scale* ]
 [ |-T|\ *t0*\ [/*t1*/*dt*]\ [**+l**] ]
@@ -48,7 +49,7 @@ a background depth (more complicated backgrounds may be added via :doc:`grdmath
 The input must contain *lon*, *lat*, *radius*, *height* for each seamount.
 For elliptical features (**-E**) we expect *lon*, *lat*, *azimuth*, *semi-major*, *semi-minor*,
 *height* instead. If flattening is specified (**-F**) with no value appended
-then a final column with flattening is expected (cannot be used for plateaus).
+then a final column with *flattening* is expected (cannot be used for plateaus).
 For temporal evolution of topography the **-T** option may be used, in which case the
 data file must have two final columns with the start and stop time of seamount construction.
 In this case you may choose to write out a cumulative shape or just the increments produced
@@ -73,13 +74,23 @@ Optional Arguments
 
 **-A**\ [*out/in*]
     Build a mask grid, append outside/inside values [1/NaN].
-    Here, height is ignored and **-L**, **-N** and **-Z** are disallowed.
+    Here, height and flattening are ignored and **-L**, **-N** and **-Z** are disallowed.
 
 .. _-C:
 
 **-C**
     Select shape function: choose among **c** (cone), **d** (disc), **g** (Gaussian)
-    and **p** (parabolic) shape [Default is Gaussian].
+    and **p** (parabolic) shape [Default is Gaussian].  All but the disc can furthermore
+    be truncated via a flattening parameter *f* set by **-F**.
+
+.. figure:: /_images/GMT_seamount_types.*
+   :width: 500 px
+   :align: center
+
+   The four types of seamounts selectable via option **-C**.  In all cases, :math:`h_0` is the maximum
+   *height*, :math:`r_0` is the basal *radius*, :math:`h_c` is the noise floor set via **-L** [0], and
+   *f* is the *flattening* set via **-F** [0]. The top radius :math:`r_t` is only nonzero if there is
+   flattening and hence does not apply to the disc model.
 
 .. _-D:
 
@@ -95,10 +106,18 @@ Optional Arguments
     for each seamount.  [Default is Circular data format, expecting
     *lon, lat, radius, height*].
 
+.. figure:: /_images/GMT_seamount_map.*
+   :width: 500 px
+   :align: center
+
+   Use **-E** to select elliptical rather than circular shape in map view.  Both shapes require
+   lon, lat. Circular only requires the radius :math:`r_0` while elliptical requires the azimuth
+   :math:`\alpha` and the major and minor semi-axes .
+
 .. _-F:
 
 **-F**\ [*flattening*]
-    Seamounts are to be truncated to guyots.  Append *flattening*, otherwise we expect
+    Seamounts are to be truncated to guyots.  Append *flattening* from 0 (no flattening to 1 (no feature!), otherwise we expect
     to find it in last input column [no truncation].  Ignored if used with **-Cd**.
 
 .. _-G:
@@ -119,24 +138,30 @@ Optional Arguments
 
 .. _-M:
 
-**-M**\ *list*
-    Write the names of all grids that were created to the text file *list*.
-    Requires **-T**.
+**-M**\ [*list*]
+    Write the times and names of all grids that were created to the text file *list*.
+    Requires **-T**.  If not *list* file is given then we write to standard output.
 
 .. _-N:
 
 **-N**\ *norm*
-    Normalize grid so maximum grid height equals *norm*.
+    Normalize grid so maximum grid height equals *norm* [no normalization]
 
 .. _-Q:
 
 **-Q**\ *bmode*/*qmode*
     Only to be used in conjunction with **-T**.  Append two different modes settings:
     The *bmode* determines how we construct the surface.  Specify **c** for cumulative
-    volume through time, or **i** for incremental volume added for each time slice.
-    The *qmode* determines the volume flux curve.  Give **g** for a Gaussian volume flux history
+    volume through time [Default], or **i** for incremental volume added for each time slice.
+    The *qmode* determines the volume flux curve.  Give **g** for a Gaussian volume flux history [Default]
     or **l** for a linear volume flux history between the start and stop times of each feature.
 
+.. figure:: /_images/GMT_seamount_flux.*
+   :width: 500 px
+   :align: center
+
+   Use *qmode* in **-Q** to choose between a linear (**l**) or Gaussian (**g**) cumulative volume flux model.
+
 .. _-S:
 
 **-S**\ *scale*

doc/scripts/GMT_seamount_flux.ps

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Illustrate the two different volume-flux curves
+ps=GMT_seamount_flux.ps
+gmt set FONT_ANNOT_PRIMARY 14p
+# Two flux curves
+gmt math -T0/1/1 T = | gmt psxy -R0/1/0/1.1 -JX6.5i/1i -W1p,- -Bxa0.25fg0.5 -Byafg0.5 -Bx+l"Normalized seamount lifespan (@%6%t/@~D@~@%6%t@%%)" -By+l"@%6%V(t)/V@-0@-@%%" -BWSne -K --FONT_LABEL=16p,Helvetica,black -P > $ps
+gmt math -T0/1/0.01 T 0.5 SUB 6 MUL ERF 2 DIV 0.5 ADD = | gmt psxy -R -J -O -W3p >> $ps

doc/scripts/GMT_seamount_flux.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Illustrate the circular and elliptical bases of seamounts
+ps=GMT_seamount_map.ps
+gmt set MAP_VECTOR_SHAPE 0.5
+
+# Circle
+echo 0 0 | gmt psxy -R-1/1/-1/1 -Jx1i -Sc1.3i -W2p -P -K > $ps
+echo 0 0 | gmt psxy -R -J -Sc0.1i -Gblack -O -K >> $ps
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-0.8	0	1	0
+0	-0.8	0	1
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+0	0
+0.45	0.45
+EOF
+echo 0.55 0.55 r@-0@- | gmt pstext -R -J -O -K -F+f14p,Times-Italic >> $ps
+echo "0 0 lon,lat "| gmt pstext -R -J -O -K -F+f14p,Times-Italic+jTR -Dj0.05i >> $ps
+echo circular | gmt pstext -R -J -O -K -F+f16p+cTL >> $ps
+# Ellipse
+echo 0 0 30 1.7i 0.7i | gmt psxy -R -J -O -K -Se -W2p -X2.5i >> $ps
+echo 0 0 | gmt psxy -R -J -Sc0.1i -Gblack -O -K >> $ps
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-0.8	0	1	0
+0	-0.8	0	1
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+>
+0	0
+0.736121593217	0.425
+>
+0	0
+-0.175	0.303108891325
+EOF
+echo 0 0 0.2i 30 90 | gmt psxy -R -J -O -K -Sm4p+b -Gblack -W0.25p >> $ps
+echo 0.736121593217 0.425 major | gmt pstext -R -J -O -K -F+f14p,Times-Italic+jBL -Dj0.03i -N >> $ps
+echo -0.175	0.303108891325 minor | gmt pstext -R -J -O -K -F+f14p,Times-Italic+jBR -Dj0.03i -N >> $ps
+echo 0.125 0.275 @~a@~ | gmt pstext -R -J -O -K -F+f14p,Times-Italic >> $ps
+echo "0 0 lon,lat "| gmt pstext -R -J -O -K -F+f14p,Times-Italic+jTR -Dj0.05i >> $ps
+echo elliptical | gmt pstext -R -J -O -K -F+f16p+cTL >> $ps
+gmt psxy -R -J -O -T >> $ps

doc/scripts/GMT_seamount_map.ps

@@ -0,0 +1,144 @@
+#!/bin/bash
+# Plot four different seamount types selectable in grdseamount
+# 1. Conical seamount
+gmt set MAP_VECTOR_SHAPE 0.5
+ps=GMT_seamount_types.ps
+cat << EOF > tmp
+0	1
+1	1
+4	0
+EOF
+cat << EOF > body
+-4	0
+-1	1
+0	1
+1	1
+4	0
+EOF
+gmt psxy -R-5/5/-0.05/1.5 -JX6.5i/1.25i -P -K -Glightgray body -Y6i > $ps
+gmt psxy -R -J -O -K -W2p tmp >> $ps
+gmt psxy -R -J -O -K -W0.5p,- << EOF >> $ps
+-4	0
+0	1.33333
+4	0
+EOF
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-5	0	5	0
+0	0	0	1.7
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+>
+-0.5	0.2
+4.3	0.2
+>
+1	0
+1	1
+>
+3.4	0
+3.4	0.3
+EOF
+gmt pstext -R -J -O -K -F+f16p,Times-Italic+j -N << EOF >> $ps
+1	-0.05	TC	r@-t@- = fr@-0@-
+4	-0.05	TC	r@-0@-
+3.4	-0.05	TC	r@-c@-
+4.3	0.2	LM	h@-c@-
+-0.2	1	RM	h@-0@-
+EOF
+echo "@%1%c@%% (cone)" | gmt pstext -R -J -O -K -F+f18p+cTL -Dj0.1i >> $ps
+# 2. Parabolic seamount
+echo "0	1" > tmp
+echo "1	1" >> tmp
+gmt math -T1/4/0.1 T 4 DIV 2 POW NEG 1 ADD 1 0.25 2 POW SUB DIV = >> tmp
+gmt math -T-4/-1/0.1 T 4 DIV 2 POW NEG 1 ADD 1 0.25 2 POW SUB DIV = body
+gmt math -T1/4/0.1 T 4 DIV 2 POW NEG 1 ADD 1 0.25 2 POW SUB DIV = >> body
+gmt math -T-4/4/0.1 T 4 DIV 2 POW NEG 1 ADD 1 0.25 2 POW SUB DIV = line
+gmt psxy -R -J -O -K -Glightgray body -Y-1.4i >> $ps
+gmt psxy -R -J -O -K -W2p tmp >> $ps
+gmt psxy -R -J -O -K -W0.5p,- line >> $ps
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-5	0	5	0
+0	0	0	1.5
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+>
+-0.5	0.2
+4.3	0.2
+>
+1	0
+1	1
+>
+3.60555	0
+3.60555	0.3
+EOF
+gmt pstext -R -J -O -K -F+f16p,Times-Italic+j -N << EOF >> $ps
+1	-0.05	TC	r@-t@- = fr@-0@-
+4	-0.05	TC	r@-0@-
+3.60555	-0.05	TC	r@-c@-
+4.3	0.2	LM	h@-c@-
+-0.2	1	RM	h@-0@-
+EOF
+echo "@%1%p@%% (parabolic)" | gmt pstext -R -J -O -K -F+f18p+cTL -Dj0.1i >> $ps
+# 3. Gaussian seamount
+echo "0	1" > tmp
+echo "1	1" >> tmp
+gmt math -T1/4/0.1 T 4 DIV 2 POW 4.5 MUL NEG EXP 0.25 2 POW 4.5 MUL EXP MUL = >> tmp
+gmt math -T-4/-1/0.1 T 4 DIV 2 POW 4.5 MUL NEG EXP 0.25 2 POW 4.5 MUL EXP MUL = body
+gmt math -T1/4/0.1 T 4 DIV 2 POW 4.5 MUL NEG EXP 0.25 2 POW 4.5 MUL EXP MUL = >> body
+gmt math -T-4/4/0.1 T 4 DIV 2 POW 4.5 MUL NEG EXP 0.25 2 POW 4.5 MUL EXP MUL = line
+gmt psxy -R-5/5/-0.05/1.35 -J -O -K -Glightgray body -Y-1.6i >> $ps
+gmt psxy -R -J -O -K -W2p tmp >> $ps
+gmt psxy -R -J -O -K -W0.5p,- line >> $ps
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-5	0	5	0
+0	0	0	1.6
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+>
+-0.5	0.2
+4.3	0.2
+>
+1	0
+1	1
+>
+2.59	0
+2.59	0.3
+EOF
+gmt pstext -R -J -O -K -F+f16p,Times-Italic+j -N << EOF >> $ps
+1	-0.05	TC	r@-t@- = fr@-0@-
+4	-0.05	TC	r@-0@-
+4.3	0.2	LM	h@-c@-
+2.59	-0.05	TC	r@-c@-
+-0.2	1	RM	h@-0@-
+EOF
+echo "@%1%g@%% (Gaussian)" | gmt pstext -R -J -O -K -F+f18p+cTL -Dj0.1i >> $ps
+# Disc
+cat << EOF > tmp
+0	1
+4	1
+4	0
+EOF
+cat << EOF > body
+-4	0
+-4	1
+4	1
+4	0
+EOF
+gmt psxy -R -J -O -K -Glightgray body -Y-1.45i >> $ps
+gmt psxy -R -J -O -K -W2p tmp >> $ps
+gmt psxy -R -J -O -K -Sv0.1i+e+s -Gblack -W0.5p -N << EOF >> $ps
+-5	0	5	0
+0	0	0	1.4
+EOF
+gmt psxy -R -J -O -K -W0.25p,- << EOF >> $ps
+>
+-0.5	0.2
+4.3	0.2
+EOF
+gmt pstext -R -J -O -K -F+f16p,Times-Italic+j -N << EOF >> $ps
+4	-0.05	TC	r@-0@- = r@-c@-
+4.3	0.2	LM	h@-c@-
+-0.2	1	RM	h@-0@-
+EOF
+echo "@%1%d@%% (disc)" | gmt pstext -R -J -O -F+f18p+cTL -Dj0.1i >> $ps
+
+rm -f tmp body line

doc/scripts/GMT_seamount_map.sh

@@ -34,7 +34,7 @@
 #define THIS_MODULE_MODERN_NAME	"grdseamount"
 #define THIS_MODULE_LIB		"potential"
 #define THIS_MODULE_PURPOSE	"Create synthetic seamounts (Gaussian, parabolic, cone or disc, circular or elliptical)"
-#define THIS_MODULE_KEYS	"<T{,GG},TD("
+#define THIS_MODULE_KEYS	"<T{,GG},LD),MD),TD("
 #define THIS_MODULE_NEEDS	"R"
 #define THIS_MODULE_OPTIONS "-:RVbdefhir" GMT_OPT("H")
 
@@ -150,7 +150,7 @@ static int usage (struct GMTAPI_CTRL *API, int level) {
 	const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_CLASSIC_NAME, THIS_MODULE_PURPOSE);
 	if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
 	GMT_Message (API, GMT_TIME_NONE, "usage: %s [infile(s)] -G<outgrid> %s\n\t%s [-A[<out>/<in>]] [-Cc|d|g|p] [-D%s]\n", name, GMT_I_OPT, GMT_Rgeo_OPT, GMT_LEN_UNITS2_DISPLAY);
-	GMT_Message (API, GMT_TIME_NONE, "\t[-E] [-F[<flattening>]] [-L[<hcut>]] [-M<list>] [-N<norm>] [-Q<bmode><fmode>] [-S<r_scale>]\n");
+	GMT_Message (API, GMT_TIME_NONE, "\t[-E] [-F[<flattening>]] [-L[<hcut>]] [-M[<list>]] [-N<norm>] [-Q<bmode><fmode>] [-S<r_scale>]\n");
 	GMT_Message (API, GMT_TIME_NONE, "\t[-T<t0>[/<t1>/<dt>|<file>|<n>[+l]]] [-Z<base>] [%s] [%s] [%s] [%s]\n\t[%s] [%s]\n\t[%s] [%s]\n\n",
 		GMT_bi_OPT, GMT_di_OPT, GMT_e_OPT, GMT_f_OPT, GMT_h_OPT, GMT_i_OPT, GMT_r_OPT, GMT_PAR_OPT);