ssh2d
ssh2d generates or applies two-dimensional fractional perturbation
fields with isotropic or axis-aligned anisotropic correlation lengths to
selected model fields in multiparameter two-dimensional NetCDF grids.
The perturbation field can be tapered using similar functionality as in
merge2d.
Synopsis
gmt ssh2d [-A model.nc] -Rregion -Iincrement -Dstddev [statistics] \
-Goutput.nc
Behavior
The default von Karman model uses -D fractional standard deviation, -C
correlation lengths, and -U Hurst exponent. Gaussian, exponential, and
white-noise spectra are also available. One correlation length gives isotropic
statistics. x/y lengths give axis-aligned anisotropy. Rotated anisotropy is not
yet implemented.
Shared statistical options apply to every -F field, while repeatable
field/value forms override individual parameters. Fields use a common Gaussian
realization by default. -Q+i gives each field an independent realization,
and padding controls periodic edge effects. Every realization has zero mean
and its requested sample standard deviation before localization.
Without -A, -R and -I define the output lattice and -F names
the NetCDF fields. Their output names receive an _heterogeneity suffix.
Without -F, the field is named heterogeneity. In application mode,
geometry is inherited unless -R or -I requests a subset or new regular
lattice. -H fills only enclosed horizontal NaN holes. Edge-connected NaNs
are preserved. Horizontal resampling follows and uses GMT’s common -n
interpolation setting. Each valid value then becomes m * (1 + epsilon).
Source coordinate and value scaling precedes gap filling and generation.
Scaling does not reorder data, and both transformed coordinates must be regular
and increasing. -Z applies final coordinate and field scaling without
reordering. When the lattice changes, scalar ancillary variables are retained,
while unselected variables tied to changed coordinates are omitted. Unresolved
missing values remain NaN.
-P supplies an xy-monotone support. -EE and -EB convert a
non-monotone polygon using the selected BLEND envelope method, and +w
writes the converted polygon. -W permits distinct x/y windows and symmetric
or side-specific taper ratios. The taper is shared by all fields, is applied
after normalization, and can be written as the weight variable with
long_name="heterogeneity taper weight" and units 1.
Usage
gmt ssh2d [gq] 6.5.0 [64-bit] - Generate or apply two-dimensional small-scale heterogeneities in
multiparameter NetCDF grids
usage: gmt ssh2d [<model.nc>[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scales>][+V<units>]⏎
…[+n<missing>]] [-A] -G<output.nc> [-F<fields>] -D[<field>/]<sigma> [-C[<field>/]<xlen>/<ylen>]
[-U[<field>/]<hurst>] [-H<n|l|a|s|m>[<args>][+m<maxgap>]] [-M<v|g|e|w>] [-P<polygon>] [-EE|B[+w]]
[-Q<seed>[+i][+n|+p<factor>]] [-W[<xwindow>/<ywindow>][+r<ratios>][+w]] [-Z[+x<sx>][+X<unit>]⏎
…[+y<sy>][+Y<unit>][+v<scales>][+V<units>]] [-R<west>/<east>/<south>/<north>[+r]] [-I<xinc>[+e|n]⏎
…[/<yinc>[+e|n]]] [-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]] [-V[q|e|w|t|i|c|d]]
[-di<nodata>[+c<col>]]
REQUIRED ARGUMENTS:
-G<output.nc>
Write a multiparameter NetCDF grid. Synthetic output contains the generated heterogeneity
fields. Application output contains the perturbed selected variables and preserves compatible
unselected variables and metadata from the input model.
-D[<field>/]<sigma>
Set the shared or field-specific fractional standard deviation. Sigma must be greater than
zero and is expressed as a fraction of the model value rather than in percent. Every output
field needs either a shared value or a field-specific value. For example, -D0.05 gives every
field a standard deviation of 5 percent, while -D0.05 -Dvp/0.03 -Dvs/0.08 uses 3 percent for
vp, 8 percent for vs, and 5 percent for every other selected field.
OPTIONAL ARGUMENTS:
-A
Apply each generated heterogeneity field to its selected model variable as model*(1+epsilon).
Missing model values remain missing. Without -A, write the heterogeneity fields themselves.
Application mode requires one input model and -F.
<model.nc>[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scales>][+V<units>][+n<missing>]
Supply one NetCDF model in application mode. Variables selected by -F must be numeric two-
dimensional fields that share x and y coordinates. NetCDF packing and missing-value metadata
are decoded first. Use +n to identify an additional input missing-value sentinel. +x and +y to
scale coordinates. +X and +Y to set working coordinate units. +v to scale selected fields. +V
to set their working units. One +v or +V entry is broadcast. Otherwise entries follow -F
order. Scaling does not reorder coordinates or data. Both transformed axes must be regular and
increasing. For example, model.nc+x0.001+Xkm+y0.001+Ykm+v0.001,0.001+Vkm/s,km/s converts
coordinates from m to km and vp and vs from m/s to km/s when used with -Fvp,vs.
-C[<field>/]<xlen>[/<ylen>]
Set shared or field-specific correlation lengths in transformed coordinate units. Lengths must
be greater than zero and are required for von Karman, Gaussian, and exponential models. White
noise does not use them. One length is isotropic. xlen/ylen specifies axis-aligned anisotropy.
For example, -C20 uses 20 along both axes, -C20/10 uses x and y lengths of 20 and 10, and
-C20/10 -Cvs/8/4 overrides those lengths for vs.
-F<field1,field2,...>
Set field names and their order. In synthetic mode, omitting -F creates one variable named
heterogeneity. -Fvp,vs creates variables vp_heterogeneity and vs_heterogeneity. In application
mode, -F is required and selects exact NetCDF variable names, such as -Fvp,vs,rho. Selected
variables must share the same coordinate dimensions. Field-specific -D, -C, and -U options and
+v, +V, and output -Z value lists use this order and these names.
-U[<field>/]<hurst>
Set the shared or field-specific Hurst exponent for the von Karman model. The value must be
greater than zero and less than one. The default exponent is 0.15. Gaussian, exponential, and
white models do not use this option. For example, -U0.3 applies 0.3 to every field, while
-U0.3 -Uvs/0.7 uses 0.7 for vs.
-H<n|l|a|s|m>[<args>][+m<maxgap>]
Fill strictly internal horizontal missing-data holes before -R/-I resampling and heterogeneity
application. Original non-missing nodes and boundary-connected missing regions are preserved.
Without -H, internal holes are not filled. Available methods are:
Nearest neighbor (n). Optionally append a search radius in grid nodes.
Linear Delaunay interpolation (l). This is the default method.
Local weighted average (a). Optionally append radius/sectors in grid nodes. The default
radius and sector count are 3 and 4.
Spline interpolation (s). Optionally append tension from 0 through 1. The default tension is
0.
Minimum-curvature interpolation (m). Optionally append tension from 0 through 1. The default
tension is 0.
+m fills only holes whose x and y spans are each no larger than maxgap grid nodes. Without
+m, every strictly internal hole is eligible. For example, -Ha4/8+m20 uses local weighted
averaging with radius 4 and 8 sectors for holes spanning at most 20 nodes.
-M<v|g|e|w>
Select the statistical model: von Karman (v), Gaussian (g), exponential (e), or white noise
(w). Von Karman is the default. White noise does not require -C, and only von Karman uses -U.
For example, -Mg selects the Gaussian model.
-P<polygon>
Restrict the heterogeneity to a polygonal support supplied as x/y vertices in transformed
working coordinates. Without -P, -W uses the complete rectangular working domain. The polygon
must lie within that domain and must have a strict xy-monotone boundary unless -E converts it.
GMT remote polygon files beginning with @ are accepted.
-EE|B[+w]
Convert a non-monotone -P polygon using the strict envelope (-EE) or best piecewise envelope
(-EB). Append +w to write the converted polygon beside the input with a _monotone suffix.
Without -E, a non-monotone polygon is rejected. For example, -Pstar.txt -EB+w uses the best
conversion and writes star_monotone.txt.
-Q<seed>[+i][+n|+p<factor>]
Control random-number generation and spectral padding. The default seed is 1, and multiple
fields use the same underlying realization. Append +i to derive an independent realization for
each field. The default padding is one maximum correlation length at every edge. +n disables
padding and +p<factor> changes that multiple. For example, -Q42+i+p2 uses seed 42, independent
fields, and padding of two correlation lengths.
-R<west>/<east>/<south>/<north>[+r]
Specify the min/max coordinates of your data region in user units. Use dd:mm[:ss] for regions
given in arc degrees, minutes [and seconds]. Use -R<xmin>/<xmax>/<ymin>/<ymax>[+u<unit>] for
regions given in projected coordinates, with <unit> selected from e|f|k|M|n|u [Default: e]. If
+u is set, projected regions centered on (0,0) may be set via -R<halfwidth>[/⏎
…<halfheight>]+u<unit>, where <halfheight> defaults to <halfwidth> if not given. Use
[yyyy[-mm[-dd]]]T[hh[:mm[:ss[.xxx]]]] format for time axes. Append +r if -R specifies the
coordinates of the lower left and upper right corners of a rectangular area.
Alternatively, use -R<code><x0>/<y0>/<n_columns>/<n_rows> for origin and grid dimensions,
where <code> is a 2-char combo from [T|M|B][L|C|R] (top/middle/bottom/left/center/right) and
grid spacing must be specified via -I<dx>[/<dy>] (also see -r).
Set the working output region. Synthetic mode requires -R. In application mode, -R optionally
selects a region contained within the transformed model domain. Otherwise the complete model
region is used. Input scaling and -H precede region selection.
-I<dx>[/<dy>]
Set positive working output increments. One value applies to x and y. two values set them
independently. Synthetic mode requires -I. In application mode, omitting -I retains the
transformed model increments. Common option -n controls horizontal interpolation when -R or -I
changes the lattice.
-W[<xwindow>[/<ywindow>]][+r<r>|<rx>/<ry>|<rx1>/<rx2>/<ry1>/<ry2>][+w]
Taper the heterogeneity inside the -P support or the complete rectangular domain. One window
name applies to both axes. Two names set x and y independently. Cosine is the default on both
axes. A taper ratio is the fraction of a support dimension occupied by the transition at one
edge. Each ratio must be at least 0 and less than 0.5, and 0 disables that edge taper. The
default ratio is 0.2 at all four edges. One ratio applies everywhere, rx/ry sets symmetric
ratios by axis, and rx1/rx2/ry1/ry2 sets every edge independently. Append +w to include the
NetCDF variable weight. For example, -Wcosine/tukey+r0.1/0.3 uses cosine in x, Tukey in y, and
symmetric x and y ratios of 0.1 and 0.3.
-Z[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scales>][+V<units>]
Transform output coordinates and values after generation or application. +x and +y scale
coordinates. +X and +Y set coordinate units. +v supplies one broadcast value scale or one
scale per -F field. +V sets field units. Scaling occurs in place and does not reorder grid
rows, columns, or fields. For example, -Z+x1000+Xm+y1000+Ym+v1000,1000+Vm/s,m/s converts
coordinates from km to m and two selected velocity fields from km/s to m/s.
-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]
Specify a grid interpolation directive:
b: B-spline.
c: Bicubic spline [Default].
l: Bilinear spline.
n: Nearest-neighbor value, i.e., no spline at all.
Optional modifiers:
+a Switch off anti-aliasing (except for linear) [Default is ON].
+b Change boundary conditions, where <BC> can be either g for geographic, p for periodic, or
n for natural boundary conditions. For p and n you may optionally append x or y [Default
is both]: x for periodic boundary conditions on x, y for periodic boundary conditions on
y [Default is Natural conditions, unless grid is known to be geographic].
+c Clip interpolated grid to input z-min/max [Default may exceed limits].
+t Change the minimum weight in vicinity of NaNs. A <threshold> of 1.0 requires all nodes
involved in interpolation to be non-NaN; 0.5 will interpolate about half way from a non-
NaN to a NaN node [Default is 0.5].
Control GMT horizontal interpolation onto a changed -R/-I lattice. Common -n does not fill
missing values and does not conflict with -H, which fills strictly internal holes first.
Processing order:
NetCDF missing-value and packing conversion. Input coordinate and field scaling. Regular
increasing-axis validation. -H internal-hole filling. -R/-I and common -n horizontal
resampling. Heterogeneity generation. BLEND tapering. Optional model application. Then -Z
output transformation. If the lattice changes, scalar ancillary variables are unchanged and
incompatible coordinate-dependent variables are omitted. Unresolved missing values are written
as NaN.
-V[q|e|w|t|i|c|d]
Change the verbosity level (currently w). Choose among 7 levels; each level adds more detailed
messages:
q: Quiet, not even fatal error messages.
e: Error messages only.
w: Warnings [Default when no -V is given].
t: Timings (time-intensive operations only).
i: Informational messages (or just -V with no level appended).
c: Compatibility warnings.
d: Debugging messages.
-di<nodata>[+c<col>] Replace any <nodata> values in input data with NaN.
+c Append first column to be affected [2].
-^ (or -) Print short synopsis message.
-+ (or +) Print longer synopsis message.
-? (or no arguments) Print this usage message.
--PAR=<value> Temporarily override GMT default setting(s) (repeatable).
(See gmt.conf documentation for GMT default parameters).
Examples
See ssh2d examples.