Model Rotation

Three commands handle the rotation of the three objects involved:

Command	Object	Direction
`SURFATT_rotate_src_rec`	Source–receiver table (`csv`)	Geographic → rotated
`SURFATT_rotate_topo`	Topography grid	Geographic → rotated
`SURFATT_rotate_model`	Model file (`h5`)	Rotated → geographic

Rotation convention

All three commands share the same two parameters:

-c clat/clon: the reference point, which is moved to $(0^\circ, 0^\circ)$ ;
-a angle: an additional anti-clockwise rotation, in degrees, about the axis through that new origin.

The transformation is a rigid rotation of the sphere, so great-circle distances between any pair of points are unchanged. The inverse problem is identical, only more efficiently gridded.

The rotation must be applied consistently to every input, with the same -a and -c. The domain section of input_params.yml also refers to the rotated frame: with grid_method: 1, lon_min_max and lat_min_max must be given in rotated coordinates; with grid_method: 0, the bounding box is derived from the rotated source–receiver table automatically.

Workflow

The Hawaii example rotates the array by $-30^\circ$ about $(19.5^\circ, -155.5^\circ)$ :


pos_str=19.5/-155.5
angle=-30
 
# 1. rotate the source and receiver locations
SURFATT_rotate_src_rec -i src_rec_file_raw.csv -a $angle -c $pos_str \
                       -o src_rec_file_rotated.csv
 
# 2. rotate the topography onto the rotated grid
SURFATT_rotate_topo -i hawaii.nc -a $angle -c $pos_str \
                    -x -0.75/0.8 -y -0.75/1 -o hawaii_rotated.nc
 
# 3. run the inversion in the rotated frame
mpirun -np 8 SURFATT_tomo -i input_params.yml
 
# 4. rotate the recovered model back to geographic coordinates
SURFATT_rotate_model -i OUTPUT_FILES/final_model.h5 -a 30 -c $pos_str \
                     -o OUTPUT_FILES/final_model.csv

Step 4 uses -a 30, the negative of the angle used in steps 1 and 2. SURFATT_rotate_model applies the inverse transform, so its -a must be the negated forward angle, while -c stays the same.

Command `SURFATT_rotate_model`


Usage: SURFATT_rotate_model -i model_file -o out_file -c clat/clon [-a angle] [-k keyname] [-h]

 Rotate a model from the local (rotated) frame back to geographic
 coordinates and convert to csv format.

 required arguments:
  -i model_file        Path to model file in HDF5 format
  -o out_file          Output csv file name
  -c clat/clon         Centre of rotation (lat/lon)

 optional arguments:
  -a angle             Rotation angle in degrees (default: 0)
  -k keyname           Export only this scalar dataset as the model column
                       One of: vs, vsv, vsh, vp, rho, zeta, gamma
                       optionally with a model_/grad_ prefix and an _NNN
                       iteration suffix, e.g. model_vs_042 in model_iter.h5
                       The csv column is named after the bare field, so
                       model_vs_042 is written as a column named vs
                       Without -k, vs is exported together with whichever
                       anisotropy fields the file carries: g0/theta for
                       azimuthal, vsv/zeta for radial
  -h                   Print help message

The command reads the model grid (x, y, z) from the HDF5 file, maps every grid point back to geographic coordinates, and writes the result as a csv table.

Exported columns

The first three columns are always lon, lat, and depth. The remaining columns depend on the fields stored in the model file:

Model parametrization	Columns
Isotropic	`lon`, `lat`, `depth`, `vs`
Azimuthal anisotropy	`lon`, `lat`, `depth`, `vs`, `g0`, `theta`
Radial anisotropy	`lon`, `lat`, `depth`, `vs`, `vsv`, `zeta`

Velocities, $G_0$ , and $\zeta$ are scalars, so their values are unaffected by the rotation. The fast-axis azimuth theta is not: it is rotated by the same angle as the grid and normalised to $[0^\circ, 180^\circ)$ , the period of a $2\theta$ anisotropy.

Exporting a single field

With -k, only the requested dataset is written as the model column. The name may carry the model_ / grad_ prefix and the _NNN iteration suffix used inside model_iter.h5, which makes it possible to export any intermediate model or gradient:


angle_back=30
pos_str=19.5/-155.5
 
# model of the first iteration, i.e. the model before any update
SURFATT_rotate_model -i OUTPUT_FILES/model_iter.h5 -a $angle_back -c $pos_str \
                     -k model_vs_000 -o OUTPUT_FILES/initial_model.csv

The column is named after the bare field (vs in the example above), so one plotting script can read either export.

The rotated table is no longer a regular grid in geographic coordinates. Interpolate it onto a regular grid — for example with pygmt.surface — before plotting. See Outputs and Visualization for a complete example.