Merge pull request #256 from rmodrak/master

Documentation updates

docs/README

@@ -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

docs/install/issues.rst

@@ -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.
 
 
 

docs/user_guide/03.rst

@@ -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.
 
 
 
@@ -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.
 
 
 
@@ -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:
 
@@ -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_m}/
+          {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>`_
 

docs/user_guide/03/receiver_side.rst

@@ -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>`_
+

docs/user_guide/03/source_side.rst

@@ -0,0 +1,186 @@
+
+.. warning::
+
+   This page is still under construction.  To help improve the
+   documentation, feel free to submit a pull request.
+
+Source-side 3D Green's functions
+================================
+
+Generating source-side 3D Green's functions using SPECFEM3D/3D_GLOBE
+--------------------------------------------------------------------
+
+In principle, any 3D solver can be used to generate Green's functions, as long as the `requirements  <https://uafgeotools.github.io/mtuq/user_guide/03/source_side.html#requirements-for-mtuq-source-side-green-s-functions>`_ below are satisfied.  
+
+So far, however, the source-side Green's function machinery has been tested using only SPECFEM3D/3D_GLOBE.  To convert SPECFEM3D/3D_GLOBE output to MTUQ-compliant Green's functions, the following steps are necessary.
+
+
+**Generate SAC binary files**
+
+SAC binary output format is natively supported by SPECFEM3D_GLOBE (in the parameter file, set `OUTPUT_SEISMOS_SAC_BINARY = .true.`).
+
+Unfortunately, SAC binary output format is not natively supported by SPECFEM3D, so it becomes necessary to manually convert SPECFEM3D output to SAC binary format.
+
+
+**Convert to SI units**
+
+MTUQ uses the fully SI convention described below. In contrast, SPECFEM3D/3D_GLOBE use a mixed SI and CGS convention, in which moment tensor elements are input in terms of dynes and centimeters, and seismograms are output in meters. As a result, it is necessary to scale SPECFEM3D/3D_GLOBE seismograms by 10^7 prior to using them as MTUQ Green's functions.
+
+
+**Additional amplitude scaling**
+
+In addition to converting to SI units, it is also necessary to account for any scaling factors in the SPECFEM3D/3D_GLOBE input files. Such scaling factors can enter, for example, through the `M_rr,M_tt,M_pp,M_rt,M_rp,M_tp` values in the moment tensor input file or through the `scaling factor <https://github.com/SPECFEM/specfem3d/blob/bf45798f3af9d792326a829de920fd944cf7c7dd/EXAMPLES/applications/homogeneous_halfspace_HEX27_elastic_no_absorbing/DATA/FORCESOLUTION#L8>`_ in the force input file.
+
+
+**Rotate to vertical, radial, transverse components**
+
+Conveniently, SPECFEM3D_GLOBE can be made to automatically rotate output seismograms into vertical, radial and transverse components (set `ROTATE_SEISMOGRAMS_RT = .true.` in the parameter file).
+
+No modifications are necessary on account of moment tensor basis convention, since MTUQ's `up-south-east` convention matches SPECFEM3D/3D_GLOBE's.
+
+
+
+
+Requirements for MTUQ source-side 3D Green's functions
+------------------------------------------------------
+
+**File format**
+
+Individual Green's functions must be written to SAC binary files.  
+
+A total 18 SAC binary files are required to represent the response between a given hypocenter and station (corresponding to 6 moment tensor elements times 3 directions of motion).
+
+
+
+**Units convention**
+
+For a moment tensor inversion, each SAC binary file must give the response in meters to a 1 Newton-meter force couple.
+
+For a force inversion, each SAC binary file must give the response in meters to a 1 Newton force.
+
+In both cases, MTUQ uses a fully SI units convention (compare with SPECFEM3D/3D_GLOBE notes, above).
+
+
+
+**Basis convention**
+
+MTUQ uses an `up-south-east` basis convention in which `r` denotes up, `t` denotes south, and `p` denotes east.
+
+Green's functions must be rotated into into vertical `Z`, radial `R` and transverse `T` components relative to the source-receiver backazimuth.
+
+Place all seismograms for the same hypocenter in a single directory as follows:
+
+.. code ::
+
+  {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
+          ...
+
+The corresponding convention for force responses is:
+
+.. code ::
+
+  {event_id}/
+      {depth_in_km}/
+          {net}.{sta}.{loc}.Z.Fr.sac
+          {net}.{sta}.{loc}.Z.Ft.sac
+          {net}.{sta}.{loc}.Z.Fp.sac
+          {net}.{sta}.{loc}.R.Fr.sac
+          {net}.{sta}.{loc}.R.Ft.sac
+          {net}.{sta}.{loc}.R.Fp.sac
+          {net}.{sta}.{loc}.T.Fr.sac
+          {net}.{sta}.{loc}.T.Fp.sac
+          {net}.{sta}.{loc}.T.Fp.sac
+          ...
+
+
+**Origin time convention**
+
+For origin time, MTUQ uses a centroid convention (`more details <https://github.com/uafgeotools/mtuq/issues/140>`_), so that `t=0` in the `GreensTensor` time discretization corresponds to mean source excitation time.
+
+MTUQ uses the begin time (`B`) and end time (`E`) headers from the SAC binary files to align the Green's functions relative to centroid origin time.  
+
+Currently, these are the only SAC headers used in reading Green's functions.
+
+(Note that different `SAC headers <https://ds.iris.edu/files/sac-manual/manual/file_format.html>`_ are required in reading `observed data <https://uafgeotools.github.io/mtuq/user_guide/02.html#file-format-metadata-and-data-processing-requirements>`_.)
+
+
+
+Hypocenter searches (experimental)
+----------------------------------
+
+Currently, only searches over source depth are possible with source-side 3D Green's functions (no other hypocenter parameters).
+
+The current `depth search <https://github.com/uafgeotools/mtuq/blob/568e49a73817e4e2dbab1189210214da6906266f/mtuq/io/clients/SPECFEM3D_SAC.py#L117>`_ implementation is especially crude and experimental (consider local modifications to suit your needs).
+
+To allow depth searches, create subdirectories for each centroid depth as follows:
+
+.. code ::
+
+  {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
+      {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
+      ...
+
+
+Working example
+---------------
+
+A working of example using source-side 3D Green's functions from SPECFEM3D_GLOBE in a moment tensor inversion:
+
+`test_greens_SPECFEM3D_SAC.py <https://github.com/rmodrak/mtuq/blob/master/tests/test_greens_SPECFEM3D_SAC.py>`_
+

docs/user_guide/05/gallery_force.rst

@@ -33,6 +33,10 @@ For a grid of regulary-spaced forces, `ds` may look something like:
       * origin_idx  (origin_idx) int64 0
 
 
+.. note::
+
+    Force grids are implemented using parameters `F0, phi, h`, which are related to `r, phi, theta` spherical coordinates (`physics convention <https://en.wikipedia.org/wiki/Spherical_coordinate_system>`_) by `F0 = r`, `phi = phi`, `h = cos(theta)`.  In addition, `F0, phi, h` are related to geographic directions by these `formulas <https://uafgeotools.github.io/mtuq/_modules/mtuq/util/math.html#to_rtp>`_.
+
 
 Misfit values
 """""""""""""

docs/user_guide/05/gallery_mt.rst

@@ -37,6 +37,12 @@ For a grid of regulary-spaced moment tensors, `ds` may look something like:
 
 
 
+.. note::
+
+    Moment tensor grids are implemented using the `rho, v, w, kappa, sigma, h` parameterization of `Tape2012 <https://uafgeotools.github.io/mtuq/references.html>`_ and `Tape2015 <https://uafgeotools.github.io/mtuq/references.html>`_, from which `formulas <https://github.com/rmodrak/mtpar>`_ converting to parameterizations can be derived.
+
+
+
 Misfit values
 """""""""""""