The LOVEE package:
A set of 8 Matlab scripts and 7 functions to forward model and invert
a collection of Love-wave phase and/or group velocities of any order modes
Below are descriptions for the scripts, the functions, and the examples.
SCRIPTS
make_synthetic_ex2_rayleigh: writes "velocity_values.txt", "velocity_values_errs.txt",
"frequency_values.txt", "mode_values.txt", and "vtype_values.txt"
calls "raylee_lysmer.m"
make_synthetic_ex2_love: writes "velocity_values.txt", "velocity_values_errs.txt",
"frequency_values.txt", "mode_values.txt", and "vtype_values.txt"
calls "lovee_lysmer.m"
make_synthetic_ex1: writes "modx_phase_vels.ascii" and "modx_freqs.ascii"
calls "lovee_lysmer.m"
make_initial_model_dix_ex2: writes "vp_init.txt", "vs_init.txt", "rho_init.txt",
"vpf.txt", "rhof.txt",
"grid_values_solid.txt", "grid_values_fluid.txt",
and "input_params.txt"
no calls
make_initial_model_dix_ex1: writes "velocity_values.txt", "velocity_values_errs.txt",
"frequency_values.txt", "mode_values.txt", "vtype_values.txt",
"vp_init.txt", "vs_init.txt", "rho_init.txt",
"vpf.txt", "rhof.txt",
"grid_values_solid.txt", "grid_values_fluid.txt",
and "input_params.txt"
no calls
lovee_invert: reads "velocity_values.txt", "velocity_values_errs.txt",
"frequency_values.txt", "mode_values.txt", "vtype_values.txt",
"vp_init.txt", "vs_init.txt", "rho_init.txt",
"vpf.txt", "rhof.txt",
"grid_values_solid.txt", "grid_values_fluid.txt",
and "input_params.txt"
no write
calls "lovee_sensitivity.m", "lovee_lysmer.m",
"linvers.m", and "check_nans.m"
plot_results_dix_ex1: no read/write/calls
to be run immediately after lovee_invert
plot_results_dix_ex2: no read/write/calls
to be run immediately after lovee_invert
FUNCTIONS
lovee_lysmer: INPUT
Nn number of nodes in solid part of model
hv vector of grid spacings for solid (meters)
f frequency (Hz)
modn which mode (1=fundamental, 2=first overtone, etc)
vsv S-wave velocity model in solid, a vector (m/s)
rhov density model in solid, a vector (kg/m^3)
OUTPUT
kk wavenumber for the Love wave at this
frequency
vpk phase velocity for the Love wave at
this frequency
vgk group velocity for the Love wave at
this frequency
ev horizontal displacement
eigenfunction (mode shapes)
DEPENDENCIES
none
raylee_lysmer: INPUT
Nn number of nodes in solid part of model
Nnf number of nodes in fluid part of model
hv vector of grid spacings for solid (meters)
hvf vector of grid spacings for fluid (meters)
f frequency (Hz)
modn which mode (1=fundamental, 2=first overtone, etc)
vsv S-wave velocity model in solid, a vector (m/s)
vpv P-wave velocity model in solid, a vector (m/s)
rhov density model in solid, a vector (kg/m^3)
vpv P-wave velocity model in fluid, a vector (m/s)
rhov density model in fluid, a vector (kg/m^3)
OUTPUT
kk wavenumber for the Rayleigh wave at this
frequency
vpk phase velocity for the Rayleigh wave at
this frequency
vgk group velocity for the Rayleigh wave at
this frequency
ev vertical and horizontal displacement
eigenfunctions (mode shapes), note these
are scrambled
DEPENDENCIES
"stoneley_vel.m" - a version is included here although
it isn't used in the examples since it addresses the
case of a water layer
lovee_sensitivity: INPUT
Nn number of nodes in solid part of model
hv vector of grid spacings for solid (meters)
f frequency (Hz)
modn vector of mode numbers (1=fundamental, 2=first overtone, etc)
vsv S-wave velocity model in solid, a vector (m/s)
rhov density model in solid, a vector (kg/m^3)
vflg vector of phase or group flag (0=phase, 1=group)
OUTPUT
U modeled velocities (group or phase
depending on vflg) over the entire
frequency range
snsmf_vstotf group or phase velocity sensitivity
kernel for Vs (again, depending on vflg)
snsmf_htotf group or phase velocity sensitivity
kernel (again, depending on vflg)
for an interface in the layering
changing its depth
DEPENDENCIES
"lovee_lymser.m"
linvers: INPUT
U_data velocity data to be inverted
U modeled velocity data
snsmf_vstot the jacobian or kernel matrix
mcmisr the inverse square root of the model
covariance matrix
dcmisr the inverse square root of the data
covariance matrix
Nn number of elements
vsv the current S-wave wave velocity model
vsg the initial guess for S-wave velocity
OUTPUT
dvs the velocity update
DEPENDENCIES
none
check_nans INPUT
U modeled velocity data
U_data velocity data to be inverted
fks vector of frequencies
modn vector of mode numbers
vflg vector flags indicating group or phase
snsmf_vstotf Vs sensitivity kernel
OUTPUT
Ur modeled velocity data with NaNs removed
U_datar velocity data to be inverted with NaNs removed
fksr vector of frequencies with NaNs removed
fksri vector of original frequency indicies
modnr vector of mode numbers with NaNs removed
vflgr vector flags indicating group or phase with NaNs removed
snsmf_vstotfr Vs sensitivity kernel with NaNs removed
DEPENDENCIES
none
convsm_1d is an additional utility function which zero-phase convolutional
smoothing to an input vector
The codes write and read the following text files:
velocity_values.txt: The measured Love velocities
velocity_values_errs.txt: Error bars on the measurements
frequency_values.txt: Frequencies at which the measurements are made
mode_values.txt: Mode number (Fundamental=1, First overtone=2, etc)
vtype_values.txt: Vector of velocity type, either phase (0) or group (1)
vp_init.txt Initial P-wave velocity model in solid (for Love-waves, this is not used)
vs_init.txt Initial S-wave velocity model in solid
rho_init.txt Initial density model in solid
vpf.txt P-wave velocity in fluid layer (for Love-waves, this is not used)
rhof.txt Density in fluid layer (for Love-waves, this is not used)
grid_values_solid.txt Finite element grid in solid layer
grid_values_fluid.txt Finite element grid in fluid layer (for Love-waves, this is not used)
input_params.txt See description below
The file "input_params.txt" is automatically generated by the make_initial_model scripts.
This file contains these quantities:
% flag for fixed poisson's ratio (0=no,1=yes)
% smoothness scale (m)
% a priori model standard deviation factor
% maximum number of updates (iterations)
% number of measurements
% number of elements in solid part of model
% number of elements in fluid part of model
% lower chi squared window
% higher chi squared window
Note that the first and seventh quantities, the ones with poisson's ratio and elements in
the fluid part, are not used for Love wave inversion. They are kept in the input file so that
files can be exchanged with the codes for Rayleigh-Scholte wave inversion
The lower and higher chi-squared values define a window of chi-squared when the code can terminate
the iterative perturbational inversion.
The smoothness scale is a regularization parameter that is typically less than the maximum sensitivity depth,
usually one-tenth of that depth.
The a prior model standard deviation factor is usually set to 2 and this factor multiplies the average data
standard deviation to give the model standard deviation.
EXAMPLES
Place all 8 scripts and 7 functions into the same directory.
For the first inversion example, execute the
following scripts in order
>> make_synthetic_ex1
>> make_initial_model_dix_ex1
>> lovee_invert
>> plot_results_ex1
This generates Figures 1, 2, and 3 in the paper.
For the second inversion example, execute the
following scripts in order
>> make_synthetic_ex2_rayleigh
>> make_initial_model_dix_ex2
>> make_synthetic_ex2_love
>> lovee_invert
>> plot_results_ex2
This generates Figures 4, 5, and 6 in the paper.
Matt Haney and Victor Tsai
1 October 2019