Skip to content

Commit

Permalink
Merge branch 'master' into waveform_plot
Browse files Browse the repository at this point in the history
  • Loading branch information
@thurinj
thurinj committed Apr 5, 2024
2 parents baee1fe + 5ebdd79 commit c4fb27d
Show file tree
Hide file tree
Showing 32 changed files with 1,112 additions and 140 deletions.
2 changes: 1 addition & 1 deletion docs/README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ HOW TO UPDATE DOCS
>> ./build.bash


3. If build fails with "Encountered unknown tag 'do', then try the following:
3. If build fails with "Encountered unknown tag 'do'", try the following:

Modify the sphinx autosummary source code by adding 'jinja2.ext.do' to the jinja
Environment() extensions list
Expand Down
4 changes: 2 additions & 2 deletions docs/install/issues.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,13 @@ We note that some versions of GMT and ObsPy do not plot `full moment tensors <ht
Speeding up conda installs
--------------------------

Older versions of the conda package manager can be very slow. For a significant potential speed up, conda can be updated as follows:
Older versions of the conda package manager can be very slow. For a potential speed up, conda can be updated as follows:

.. code::
conda update -n base conda
For reference, the largest potential speed up comes from the new `mamba <https://conda.org/blog/2023-11-06-conda-23-10-0-release>`_ dependency solver, which was `adopted <https://conda.org/blog/2023-11-06-conda-23-10-0-release>`_ in the 23.10 release.
For reference, the largest potential speed up comes from the new `mamba <https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community>`_ dependency solver, which was `adopted <https://conda.org/blog/2023-11-06-conda-23-10-0-release>`_ in the 23.10 release.



Expand Down
3 changes: 3 additions & 0 deletions docs/library/autogen.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,11 @@ autogen
mtuq.graphics.plot_time_shifts
mtuq.graphics.plot_amplitude_ratios
mtuq.graphics.plot_log_amplitude_ratios
mtuq.graphics.plot_cross_corr
mtuq.graphics._plot_attrs
mtuq.graphics.attrs._default_backend
mtuq.graphics.attrs._pygmt_backend
mtuq.graphics.attrs.PyGMTUtilities
mtuq.grid.DeviatoricGridRandom
mtuq.grid.DeviatoricGridSemiregular
mtuq.grid.DoubleCoupleGridRandom
Expand Down
3 changes: 2 additions & 1 deletion docs/library/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,12 +93,13 @@ Depth and hypocenter visualization
============================================================================================================ ============================================================================================================


Time shift and amplitude ratio visualization
Station attributes visualization
--------------------------------------------

============================================================================================================ ============================================================================================================
`mtuq.graphics.plot_time_shifts <generated/mtuq.graphics.plot_time_shifts.html>`_ Plots time shifts by location and component
`mtuq.graphics.plot_amplitude_ratios <generated/mtuq.graphics.plot_amplitude_ratios.html>`_ Plots amplitude ratios by location and component
`mtuq.graphics.plot_cross_corr <generated/mtuq.graphics.plot_cross_corr.html>`_ Plots normalized cross-correlation by location and component
============================================================================================================ ============================================================================================================


Expand Down
90 changes: 44 additions & 46 deletions docs/user_guide/03.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,29 @@
Acquiring Green's functions
===========================

The response of a medium to an impulsive source is called a Green's function. This page describes the role of Green's functions in source inversions, the types of Green's functions supported by MTUQ, and how these types can be obtained.
The response of a medium to an impulsive source is called a Green's function. This page describes the role of Green's functions in source inversions, the types of Green's functions supported by MTUQ, and how these different types can each be obtained.


Role of Green's functions
-------------------------

By combining Green's functions, it is possible to obtain synthetics from any moment tensor or force source. Generating synthetics in this way is useful because it provides cost savings compared with on-the-fly wavefield simulations. Synthetics can then be compared with data to determine a best-fitting source.



`GreensTensor` objects
----------------------

`GreensTensor <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.html>`_ objects provide access to a set of Green's functions describing the medium response between a given station and origin.
`GreensTensor <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.html>`_ objects provide access to a set of Green's functions describing the medium response between a given hypocenter and station.

Methods built into the `GreensTensor` class allow data processing and synthetics generation. In particular, the `get_synthetics <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.get_synthetics.html#mtuq.GreensTensor.get_synthetics>`_ method accepts a `MomentTensor` or `Force` and returns corresponding synthetics.



Methods built into the `GreensTensor` class allow data processing and synthetics generation. In particular, the `get_synthetics <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.get_synthetics.html#mtuq.GreensTensor.get_synthetics>`_ method accepts a `MomentTensor` or `Force` and returns corresponding synthetics for the given station.
Green's function conventions
----------------------------

A major goal of MTUQ is to avoid exposing users to unnecessary complexity. For Green's functions, MTUQ tries to accomplish this by understanding external conventions and converting to a common internal format. Specifically, MTUQ uses an `up-south-east` `convention <https://docs.obspy.org/packages/autogen/obspy.imaging.mopad_wrapper.beach.html#supported-basis-systems>`_ for internally storing impulse responses corresponding to individual force couples. (Moment tensors and forces are internally represented using the same `up-south-east` basis.)

Under the hood, MTUQ deals with a variety of external conventions related to (1) the symmetry of the medium (for example, 1D media require fewer independent Green's functions than 3D media); (2) the choice of local Cartesian basis convention (for example, some authors employ `up-south-east`, others `north-east-down`). A sense of what's involved can be obtained by browsing the `source code <https://github.com/uafgeotools/mtuq/tree/master/mtuq/greens_tensor>`_ and references therein.



Expand All @@ -34,7 +40,7 @@ To download AK135 Green's functions and generate MTUQ `GreensTensor` objects:
from mtuq import download_greens_functions
greens_tensors = download_greens_functions(stations, origins, model="ak135f_2s")
A limitation of syngine is that Green's functions can be downloaded only on a station-by-station basis, not over an entire subset of Earth. An alternative that avoids this limitation is to compute your own Green's functions.
A limitation of syngine is that Green's functions can be downloaded only on a station-by-station basis, not over an entire area or volume. An alternative that avoids this limitation is to compute your own Green's functions.



Expand All @@ -44,7 +50,9 @@ Computing Green's functions from 1D Earth models

MTUQ supports the following 1D Green's functions formats: AxiSEM (preferred) and FK.

`AxiSEM <https://github.com/geodynamics/axisem>`_ performs spectral element wave simulations in radially-symmetric Earth models. To generate synthetics in a format MTUQ natively supports, follow the instructions for in the `AxiSEM user manual <https://raw.githubusercontent.com/geodynamics/axisem/master/MANUAL/manual_axisem1.3.pdf>`_ under "Output wavefields in NetCDF formated needed by instaseis." AxiSEM NetCDF files can be used to retrieve vertical, radial, and transverse displacement in units of m*(N-m)^-1.
`AxiSEM <https://github.com/geodynamics/axisem>`_ performs spectral element wave simulations in radially-symmetric Earth models. AxiSEM NetCDF files can be used to retrieve vertical, radial, and transverse displacement in units of m*(N-m)^-1.

To generate AxiSEM synthetics in a format MTUQ supports, follow the instructions in the `AxiSEM user manual <https://raw.githubusercontent.com/geodynamics/axisem/master/MANUAL/manual_axisem1.3.pdf>`_ under "Output wavefields in NetCDF format needed by instaseis."

To open an AxiSEM database client in MTUQ:

Expand Down Expand Up @@ -81,60 +89,50 @@ Computing Green's functions from 3D Earth models

MTUQ currently supports 3D Green's functions from SPECFEM3D/3D_GLOBE.

To generate a complete Green's function database for a given hypocenter and depth, six SPECFEM3D wavefield simulations are required. Output must be saved as/converted to SAC files at individual stations using the following filename convention, which comes from `GRD_CMT3D <https://github.com/UTCompSeismo/GRD_CMT3D/tree/master/cmt3d>`_. Place all SAC files corresponding to a single hypocenter and depth in the same directory as follows:
To generate a full set of Green's functions for a given hypocenter and depth, six SPECFEM3D/3D_GLOBE wavefield simulations are required. Output must be saved as/converted to SAC files at individual stations using the following filename convention, which comes from `GRD_CMT3D <https://github.com/UTCompSeismo/GRD_CMT3D/tree/master/cmt3d>`_. Place all SAC files corresponding to a single hypocenter and depth in the same directory as follows:

.. code ::
{basedir}/{event_id}/
{net}.{sta}.{loc}.Z.Mrr.sac
{net}.{sta}.{loc}.Z.Mtt.sac
{net}.{sta}.{loc}.Z.Mpp.sac
{net}.{sta}.{loc}.Z.Mrt.sac
{net}.{sta}.{loc}.Z.Mrp.sac
{net}.{sta}.{loc}.Z.Mtp.sac
{net}.{sta}.{loc}.R.Mrr.sac
{net}.{sta}.{loc}.R.Mtt.sac
{net}.{sta}.{loc}.R.Mpp.sac
{net}.{sta}.{loc}.R.Mrt.sac
{net}.{sta}.{loc}.R.Mrp.sac
{net}.{sta}.{loc}.R.Mtp.sac
{net}.{sta}.{loc}.T.Mrr.sac
{net}.{sta}.{loc}.T.Mtt.sac
{net}.{sta}.{loc}.T.Mpp.sac
{net}.{sta}.{loc}.T.Mrt.sac
{net}.{sta}.{loc}.T.Mrp.sac
{net}.{sta}.{loc}.T.Mtp.sac
To open an SPECFEM3D database client in MTUQ:
{event_id}/
{depth_in_km}/
{net}.{sta}.{loc}.Z.Mrr.sac
{net}.{sta}.{loc}.Z.Mtt.sac
{net}.{sta}.{loc}.Z.Mpp.sac
{net}.{sta}.{loc}.Z.Mrt.sac
{net}.{sta}.{loc}.Z.Mrp.sac
{net}.{sta}.{loc}.Z.Mtp.sac
{net}.{sta}.{loc}.R.Mrr.sac
{net}.{sta}.{loc}.R.Mtt.sac
{net}.{sta}.{loc}.R.Mpp.sac
{net}.{sta}.{loc}.R.Mrt.sac
{net}.{sta}.{loc}.R.Mrp.sac
{net}.{sta}.{loc}.R.Mtp.sac
{net}.{sta}.{loc}.T.Mrr.sac
{net}.{sta}.{loc}.T.Mtt.sac
{net}.{sta}.{loc}.T.Mpp.sac
{net}.{sta}.{loc}.T.Mrt.sac
{net}.{sta}.{loc}.T.Mrp.sac
{net}.{sta}.{loc}.T.Mtp.sac
To open a SPECFEM3D/3D_GLOBE database client:

.. code ::
.. code::
from mtuq import open_db
db = open_db(path_SPECFEM3D_output_directory, format="SPECFEM3D")
Once opened, a SPECFEM3D database client can be used to generate `GreensTensor <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.html>`_ objects as follows:
Once opened, the database client can be used to generate `GreensTensor <https://uafgeotools.github.io/mtuq/library/generated/mtuq.GreensTensor.html>`_ objects as follows:

.. code::
greens_tensors = db.get_greens_tensors(stations, origin)
For more information, see also:

Green's function conventions
----------------------------

A variety of Green's function conventions exist. Figuring out which are used in a particular application can be challenging because it depends on

- the type of medium under consideration (for example, acoustic media require fewer independent Green's functions than elastic media)

- the symmetry of the medium (for example, 1D media require fewer independent Green's functions than 3D media)

- the choice of local Cartesian basis conventions (for example, some authors employ `up-south-east`, others `north-east-down`; see `ObsPy documentation <https://docs.obspy.org/packages/autogen/obspy.imaging.mopad_wrapper.beach.html#supported-basis-systems>`_ for more information)

A major goal is to avoid exposing users to unnecessary basis complexity. MTUQ accomplishes this by understanding external formats and converting to a common internal format that works for both 1D and 3D media.

For internally storing moment tensors, forces, and Green's functions, MTUQ consistently uses an `up-south-east` Cartesian convention.
`Source-side Green's function details (under construction) <https://uafgeotools.github.io/mtuq/user_guide/03/source_side.html>`_

`Receiver-side Green's function details (under construction) <https://uafgeotools.github.io/mtuq/user_guide/03/receiver_side.html>`_

14 changes: 14 additions & 0 deletions docs/user_guide/03/receiver_side.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@

.. warning::

This page is still under construction. To help improve the
documentation, feel free to submit a pull request.


Receiver-side 3D Green's functions
==================================

A working of example using receiver-side 3D Green's functions from SPECFEM3D in a moment tensor inversion:

`test_greens_SPECFEM3D_SGT.py <https://github.com/rmodrak/mtuq/blob/master/tests/test_greens_SPECFEM3D_SGT.py>`_

Loading

0 comments on commit c4fb27d

Please sign in to comment.