Merge pull request #3 from GinvLab/develop

Merge develop

.github/workflows/documentation.yml

@@ -0,0 +1,34 @@
+name: Build documentation
+
+on:
+  push:
+    branches:
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+  build_docs:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - name: Julia cache
+        if: ${{ !env.ACT }}
+        uses: julia-actions/cache@v2
+      #- uses: julia-actions/cache@v2
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build docs and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.github/workflows/test.yml

@@ -0,0 +1,42 @@
+# Run package tests
+name: Package tests
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request: 
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  run_tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: ['1'] #['lts', '1', 'pre']
+        julia-arch: [x64] #[x64, x86]
+        os: [ubuntu-latest] #[ubuntu-latest, windows-latest, macOS-latest]
+        exclude:
+          - os: macOS-latest
+            julia-arch: x86
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: ${{ matrix.julia-arch }}
+      - name: Julia cache
+        if: ${{ !env.ACT }}
+        uses: julia-actions/cache@v2
+      # - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        # with:
+        #   annotate: true

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-2024 Andrea Zunino
+Copyright (c) 2019-2025 Andrea Zunino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,13 +4,18 @@
 [![Docs Latest](https://img.shields.io/badge/docs-latest-blue.svg)](https://ginvlab.github.io/EikonalSolvers.jl/dev)
 
 A library to perform __seismic traveltime__ computations by solving the eikonal equation in two (__2D__) and three dimensions (__3D__) with the possibility of computing the __gradient of a misfit function__ with respect to velocity and source location. The coordinate system can be either regular Cartesian or spherical.
-The forward algorithm is based on a fast marching (FMM) method (2nd order) with a refinement of the grid around the source location. The computation of the gradient relies on the __discrete adjoint__ method. 
-
-For historical reasons, alternative solvers are available (poorly maintained), including a first order FMM method and the fast sweeping (FS) method for global updates with different kinds of local stencils. Additionally, a continuos adjoint method to calculate the gradient is also provided.
+The forward algorithm is based on a fast marching (FMM) method (2nd order) with a refinement of the grid around the source location. The computation of the gradients relies on the __discrete adjoint__ method. 
 
 Both forward and gradient (adjoint) computations can be run in parallel using either Julia's distributed computing functions for distributed memory or threads for multicore processor. The  parallelisation scheme is "by source", distributing calculations for different seismic sources to different processors.
 
 
+This code is part of a larger project `G⁻¹Lab` (a superset of HMCLab) targeting probabilistic geophysical inverse problems. Please cite the following papers if you use this code:
+
+* Andrea Zunino, Scott Keating, Andreas Fichtner (2025), **A discrete adjoint method for deterministic and probabilistic eikonal-equation-based inversion of traveltime for velocity and source location**, arXiv preprint arXiv:2501.13532, [https://arxiv.org/abs/2501.13532v1](https://arxiv.org/abs/2501.13532v1).
+
+* Andrea Zunino, Lars Gebraad, Alessandro Ghirotto, Andreas Fichtner (2023), **HMCLab: a framework for solving diverse geophysical inverse problems using the Hamiltonian Monte Carlo method**, Geophysical Journal International, Volume 235, Issue 3, Pages 2979–2991, [https://doi.org/10.1093/gji/ggad403](https://doi.org/10.1093/gji/ggad403)
+
+
 ## Example of forward calculations in 2D
 
 Here below an example of how to calculate traveltimes at receiver stations in 2D, given a grid geometry and positions of sources and receivers.
@@ -45,10 +50,14 @@ ttimepicks,ttimegrid = eiktraveltime(velmod,grd,coordsrc,coordrec,returntt=true)
 ```
 ![ttarrays](docs/src/images/ttime-arrays.png)
 
+Finally, functions are provided to back-trace rays from receivers to sources.
+
+<p align="center"><img src="docs/src/images/rays2.png" width="70%" /></p>
+
 
 ## Example of gradient calculations in 2D
 
-The gradient of the misfit functional (see documentation) with respect to velocity and source location can be calculated as following. A set of observed traveltimes, error on the measurements and a reference velocity model are also required, see the documentation for a detailed example.
+The **gradient of the misfit functional** (see documentation) with respect to **velocity** and **source location** can be calculated as following. A set of observed traveltimes, error on the measurements and a reference velocity model are also required, see the documentation for a detailed example.
 ```julia
 # calculate the gradient of the misfit function w.r.t. velocity
 gradvel,misf = eikgradient(vel0,grd,coordsrc,coordrec,dobs,stdobs,:gradvel)

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+EikonalSolvers = "0631ba50-6b23-11e9-3fc3-378508ba069a"
 
 [compat]
 Documenter = ">=0.27"

docs/make.jl

@@ -1,7 +1,7 @@
 using Documenter, EikonalSolvers 
 
 makedocs(modules = [EikonalSolvers],
-         repo=Remotes.GitLab("JuliaGeoph","EikonalSolvers.jl"), #"https://gitlab.com/JuliaGeoph/EikonalSolvers.jl/blob/{commit}{path}#{line}", 
+         repo=Remotes.GitHub("GinvLab","EikonalSolvers.jl"), 
          sitename="EikonalSolvers.jl",
          authors = "Andrea Zunino",
          format = Documenter.HTML(prettyurls=get(ENV,"CI",nothing)=="true"),
@@ -14,30 +14,9 @@ makedocs(modules = [EikonalSolvers],
          )
 
 deploydocs(
-    repo="gitlab.com/JuliaGeoph/EikonalSolvers.jl.git",   
+    repo="github.com/GinvLab/EikonalSolvers.jl.git",   
     devbranch = "main",
-    deploy_config = Documenter.GitLab(),
+    deploy_config = Documenter.GitHubActions(),
     branch = "gl-pages",
 )
 
-
-###########################################################
-# GitLab <: DeployConfig
-
-# GitLab implementation of DeployConfig.
-
-# The following environment variables influence the build when using the GitLab configuration:
-
-#     DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be set in the GitLab settings. Make sure this variable is marked NOT to be displayed in the build log.
-
-#     CI_COMMIT_BRANCH: the name of the commit branch.
-
-#     CI_EXTERNAL_PULL_REQUEST_IID: Pull Request ID from GitHub if the pipelines are for external pull requests.
-
-#     CI_PROJECT_PATH_SLUG: The namespace with project name. All letters lowercased and non-alphanumeric characters replaced with -.
-
-#     CI_COMMIT_TAG: The commit tag name. Present only when building tags.
-
-#     CI_PIPELINE_SOURCE: Indicates how the pipeline was triggered.
-
-# The CI_* variables are set automatically on GitLab. More information on how GitLab sets the CI_* variables can be found in the GitLab documentation.

docs/src/index.md

@@ -1,8 +1,4 @@
 
-
-```@meta
-EditURL = "https://gitlab.com/JuliaGeoph/EikonalSolvers.jl/-/tree/main/docs/src/"
-```
 # Contents
 
 ```@contents
@@ -19,29 +15,30 @@ For historical reasons, alternative solvers are available (poorly maintained), i
 Both forward and gradient (adjoint) computations can be run in paralle using either Julia's distributed computing functions for distributed memory or threads for multicore processor. The parallelisation scheme is "by source", distributing calculations for different seismic sources to different processors.
 
 
-This code is part of a larger project `HMCLab` ([^ZuninoGebraadetal2023]) targeting probabilistic geophysical inverse problems. Please cite the following papers if you use this code:
+This code is part of a larger project `G⁻¹Lab` (a superset of HMCLab[^ZuninoGebraadetal2023]) targeting probabilistic geophysical inverse problems. Please cite the following papers if you use this code:
 
-* Andrea Zunino, Scott Keating, Andreas Fichtner, **Eikonal tomography using the discrete adjoint state method**, in preparation.
+* Andrea Zunino, Scott Keating, Andreas Fichtner (2025), **A discrete adjoint method for deterministic and probabilistic eikonal-equation-based inversion of traveltime for velocity and source location**, arXiv preprint arXiv:2501.13532, [https://arxiv.org/abs/2501.13532v1](https://arxiv.org/abs/2501.13532v1).
 
-* Andrea Zunino, Lars Gebraad, Alessandro Ghirotto, Andreas Fichtner, **HMCLab: a framework for solving diverse geophysical inverse problems using the Hamiltonian Monte Carlo method**, Geophysical Journal International, Volume 235, Issue 3, December 2023, Pages 2979–2991  [https://doi.org/10.1093/gji/ggad403](https://doi.org/10.1093/gji/ggad403)
+* Andrea Zunino, Lars Gebraad, Alessandro Ghirotto, Andreas Fichtner (2023), **HMCLab: a framework for solving diverse geophysical inverse problems using the Hamiltonian Monte Carlo method**, Geophysical Journal International, Volume 235, Issue 3, Pages 2979–2991, [https://doi.org/10.1093/gji/ggad403](https://doi.org/10.1093/gji/ggad403)
 
 
 
 ## Installation
 
 To install the package simple enter into the package manager mode in Julia by typing "`]`" at the REPL prompt and then use `add`, i.e.,
 ```
-(v1.8) pkg> add EikonalSolvers
+(v1.11) pkg> registry add https://github.com/Ginvlab/GinvLabRegistry
+(v1.11) pkg> add EikonalSolvers
 ```
 The package will be automatically downloaded from the web and installed.
 
-Alternatively, use the path where the directory of the package is located, be it remote (GitLab)
+Alternatively, use the path where the directory of the package is located, be it remote (GitHub)
 ```
-(v1.8) pkg> add https://gitlab.com/JuliaGeoph/EikonalSolvers.jl
+(v1.11) pkg> add https://github.com/GinvLab/EikonalSolvers.jl
 ```
 or local
 ```
-(v1.8) pkg> add /path/to/EikonalSolvers.jl
+(v1.11) pkg> add /<path>/<to>/EikonalSolvers.jl
 ```
 
 
@@ -59,6 +56,7 @@ where ``\tau`` is the travel time, ``x,y,z`` the spatial coordinates and ``v`` t
 In the numerical solution to the eikonal equation, there are two major components, the global scheme, which defines the strategy to update to the traveltime on the grid, i.e., the fast marching method and the local scheme, providing the finite difference stencils.
 
 The gradient computations are based on the adjoint state method (see below).
+For details please refer to the paper [^Zuninoetal2025].
 
 ## Numerical implementation
 
@@ -70,7 +68,7 @@ S = \dfrac{1}{2} \sum_i \dfrac{\left( \mathbf{\tau}_i^{\rm{calc}}(\mathbf{v})-\m
 ```
 The gradient of the above functional with respect to the velocity model ``\dfrac{d S}{d \mathbf{v}}`` can be calculated efficiently using the _adjoint_ state method (e.g., [^LeungQian2006], [^TreisterHaber2016]]). 
 
-In this package we employ the __discrete adjoint state method__ to compute both gradients with respect to velocity and source location [^Zuninoetal2024], which takes into account the non-linearity of the forward problem - i.e., _no_ linearisation of the forward model and _no_ rays are employed. The computational cost is almost independent of the number of receivers and, because of the discretization, the result is a "diffuse" sensitivity around the theoretical rays (see an example in the following). 
+In this package we employ the __discrete adjoint state method__ to compute both gradients with respect to velocity and source location [^Zuninoetal2025], which takes into account the non-linearity of the forward problem - i.e., _no_ linearisation of the forward model and _no_ rays are employed. The computational cost is almost independent of the number of receivers and, because of the discretization, the result is a "diffuse" sensitivity around the theoretical rays (see an example in the following). 
 
 
 ## Exported functions / API
@@ -428,7 +426,7 @@ The gradient is returned as an array where each row contains the partial derivat
 
 [^ZuninoGebraadetal2023]: Zunino A., Gebraad, L., Ghirotto, A. and Fichtner, A., (2023). HMCLab a framework for solving diverse geophysical inverse problems using the Hamiltonian Monte Carlo algorithm, Geophysical Journal International, Volume 235, Issue 3, December 2023, Pages 2979–2991, https://doi.org/10.1093/gji/ggad403.
 
-[^Zuninoetal2024]: Andrea Zunino, Scott Keating, Andreas Fichtner, Eikonal tomography using the discrete adjoint state method, in preparation.
+[^Zuninoetal2025]: Andrea Zunino, Scott Keating, Andreas Fichtner (2025), **A discrete adjoint method for deterministic and probabilistic eikonal-equation-based inversion of traveltime for velocity and source location, arXiv preprint arXiv:2501.13532.
 
 [^LeungQian2006]: Leung, S. and Qian, J. (2006). An adjoint state method for three-dimensional transmission traveltime tomography using first-arrivals. Communications in Mathematical Sciences, 4(1), 249-266.