ssh3d
ssh3d generates or applies three-dimensional fractional perturbation
fields with isotropic or axis-aligned anisotropic correlation lengths to
selected model fields in multiparameter three-dimensional NetCDF cubes.
The perturbation field can be tapered using similar functionality as in
merge3d.
Synopsis
gmt ssh3d [-A model.nc] -Rregion -Iincrement -Tzmin/zmax/dz \
-Dstddev [statistics] -Goutput.nc
Behavior
The spectral models and normalization follow ssh2d. One correlation length
is isotropic; three lengths define axis-aligned x/y/z anisotropy. Shared
statistics apply to every selected field, while field-specific -D, -C,
and -U values override them. Fields share a realization unless -Q+i is
selected, and spectral padding reduces periodic edge effects.
Without -A, -R, -I, and -T define a regular NetCDF cube. In
application mode geometry is inherited unless those options request a subset
or new lattice. Source +x, +y, +z, and +v transforms occur
first. They never reorder data. Transformed coordinates must be regular and
increasing. A negative input scale can therefore convert a descending axis to
the required increasing working convention while preserving layer order.
-H fills enclosed horizontal NaN holes independently on each z layer.
-R and -I then resample horizontally with the common -n method.
-T resamples vertically with -S. -S+g also bridges internal
vertical gaps, optionally subject to a maximum gap in transformed z units.
After preprocessing, each valid selected value becomes m * (1 + epsilon).
-Z performs final axis and field scaling without reordering, so a negative
output z scale can restore the original convention. When the lattice changes,
scalar ancillary variables are retained and incompatible coordinate-dependent
variables are omitted. Unresolved or missing values remain NaN.
-P defines an xy polygon extruded/extended through the model’s vertical axis,
while -L restricts its vertical interval. A non-monotone polygon may be
converted with -EE or -EB. -W accepts independent x/y/z window
functions and one, three, or six taper ratios for symmetric or side-specific
control. All fields share the same tapering parameters, which is applied after
statistical normalization and may be written as the weight variable with
long_name="heterogeneity taper weight" and units 1.
Usage
gmt ssh3d [gq] 6.5.0 [64-bit] - Generate or apply three-dimensional small-scale heterogeneities in
multiparameter NetCDF cubes
usage: gmt ssh3d [<model.nc>[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+z<sz>][+Z<unit>][+v<scales>]⏎
…[+V<units>][+n<missing>]] [-A] -G<output.nc> [-F<fields>] -D[<field>/]<sigma> [-C[<field>/⏎
…]<xlen>/<ylen>/<zlen>] [-U[<field>/]<hurst>] [-H<n|l|a|s|m>[<args>][+m<maxgap>]] [-S<a|c|e|l|n|⏎
…s<p>>[+g[<maxgap>]]] [-M<v|g|e|w>] [-P<polygon>] [-L<zlo>/<zhi>] [-EE|B[+w]] [-Q<seed>[+i][+n|⏎
…+p<factor>]] [-W[<xwindow>/<ywindow>/<zwindow>][+r<ratios>][+w]] [-T<zmin>/<zmax>/<dz>]
[-Z[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+z<sz>][+Z<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 cube. 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>][+z<sz>][+Z<unit>][+v<scales>][+V<units>]⏎
…[+n<missing>]
Supply one NetCDF model in application mode. Variables selected by -F must be numeric three-
dimensional fields that share x, y, and z coordinates. NetCDF packing and missing-value
metadata are decoded first. Use +n to identify an additional input missing-value sentinel.
+x, +y, and +z to scale coordinates. +X, +Y, and +Z 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. All
transformed axes must be regular and increasing. A negative axis scale may convert a
descending convention without rearranging model layers. For example,
model.nc+x0.001+Xkm+y0.001+Ykm+z-0.001+Zkm+v0.001,0.001+Vkm/s,km/s converts horizontal
coordinates from m to km, reverses the sign and converts the z coordinates from m to km, and
converts vp and vs from m/s to km/s when used with -Fvp,vs.
-C[<field>/]<xlen>[/<ylen>/<zlen>]
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. Supply either one isotropic length or all three axis-aligned lengths
xlen/ylen/zlen. For example, -C20 uses 20 along all axes, -C20/10/2 introduces axis-aligned
anisotropy, and -C20/10/2 -Cvs/8/4/1 overrides the 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 independently on every native z layer
before -R/-I resampling and heterogeneity application. Original non-missing nodes and
boundary-connected missing regions are preserved. Without -H, internal horizontal 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 horizontal heterogeneity support to a polygon supplied as x/y vertices in
transformed working coordinates. The polygon is extruded through the -L interval or the
complete working z domain. Without -P, -W uses the complete rectangular x-y domain. The
polygon must lie within that domain and have a strict xy-monotone boundary unless -E converts
it. GMT remote polygon files beginning with @ are accepted.
-L<zlo>/<zhi>
Restrict the vertical taper support to an interval in transformed z units. The interval must
lie inside the working z domain and zlo must be less than zhi. Without -L, -W uses the
complete working z domain. For example, -L0/20 limits the heterogeneity to those z
coordinates.
-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 boundary. +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 horizontal 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 horizontal 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.
-T<zmin>/<zmax>/<dz>
Set a regular increasing working z axis with zmin < zmax and dz > 0. Synthetic mode requires
-T. In application mode, -T optionally subsets or resamples within the transformed input z
domain. Otherwise the transformed input z axis is unchanged. Option -S controls vertical
interpolation. For example, -T0/60/0.5 creates 121 z layers.
-S<a|c|e|l|n|s<p>>[+g[<maxgap>]]
Choose Akima (a), cubic spline (c), step-up (e), linear (l), nearest-neighbor (n), or
smoothing spline (s<p>) vertical interpolation with a non-negative fit parameter p. Linear
interpolation is the default. Interpolation remains within contiguous non-missing runs. Append
+g to bridge internal missing runs, optionally only when the gap distance does not exceed
maxgap in transformed z units. Values are not extrapolated beyond data domain. Use -Sl+g to
fill every internal vertical gap linearly, or -Sc+g5 to use a cubic spline only across gaps
whose brackets are at most 5 z units apart. In application mode, -S requires -T unless +g is
used. Option -H fills enclosed holes within native x-y layers. Common -n controls horizontal
resampling.
-W[<xwindow>[/<ywindow>/<zwindow>]][+r<r>|<rx>/<ry>/<rz>|<rx1>/<rx2>/<ry1>/<ry2>/<rz1>/<rz2>]⏎
…[+w]
Taper the heterogeneity inside the -P and -L supports or the complete working cube. One window
name applies to all axes. Three names set x, y, and z independently. Cosine is the default on
every axis. A taper ratio is the fraction of a support dimension occupied by the transition at
one boundary. Each ratio must be at least 0 and less than 0.5, and 0 disables that boundary
taper. The default ratio is 0.2 at all six boundaries. One ratio applies everywhere. Three
ratios set symmetric x, y, and z tapers. Six ratios set beginning and ending x, y, and z
tapers in that order. Append +w to include the NetCDF variable weight. For example,
-Wcosine+r0.2/0.2/0.2/0.2/0/0.2 disables the beginning z taper while using a 0.2 ending z
taper.
-Z[+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+z<sz>][+Z<unit>][+v<scales>][+V<units>]
Transform output coordinates and values after generation or application. +x, +y, and +z scale
coordinates. +X, +Y, and +Z 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, layers, or fields. A negative +z therefore produces a decreasing output z axis.
For example, -Z+z-1000+Zm+v1000,1000+Vm/s,m/s restores a positive-up z convention in m and
converts two velocity fields from km/s to m/s without reordering model layers.
-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 horizontal holes
first. Option -S independently controls vertical interpolation.
Processing order:
NetCDF missing-value and packing conversion. Input coordinate and field scaling. Regular
increasing-axis validation. -H horizontal internal-hole filling. -R/-I and common -n
horizontal resampling. -T/-S vertical resampling or gap bridging. 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 ssh3d examples.