# \[ANN\] Announcing Eikonal.jl

**URL:** <https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960>\
**Category:** Package Announcements\
**Created:** [August 18, 2023, 4:53pm UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960 "2023-08-18T16:53:34Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![ffevotte](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ffevotte/32/6587_2.png) [@ffevotte](https://discourse.julialang.org/u/ffevotte)\
**Post date:** [August 18, 2023, 4:53pm UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/1 "2023-08-18T16:53:34Z")

</div>

[`Eikonal.jl`](https://github.com/triscale-innov/Eikonal.jl) implements solvers for [Eikonal equations](https://en.wikipedia.org/wiki/Eikonal_equation) of the form:  
\begin{align} &\qquad \left\Vert\nabla \tau\right\Vert = \sigma(x), &&\forall x\in\Omega\subset\mathbb{R}^N,\\ &\qquad\tau(x\_0) = 0, &&\forall x\_0\in\Gamma\subset\Omega,\end{align}  
where one seeks the unknown field \tau, which can be interpreted as the time of first arrival of a (wave) front that originates in \Gamma and moves with slowness \sigma (_i.e_ its speed is given by 1/\sigma).

Eikonal equations arise as a high-frequency approximation of waves propagation equations (much like geometric optics); they can also be interpreted as continuous shortest path problems.

`Eikonal.jl` implements two kinds of methods for solving the Eikonal equation:

- Fast Sweeping Method (FSM) \[1\],
- Fast Marching Method (FMM) \[2\].

_(Please note that the FSM implementation has benefited from more work than the FMM. Only the FSM can handle problems in arbitrary dimension; FMM is (for now) limited to 2D problems. The API is also (for now) slightly inconsistent between FSM and FMM)._

Previously existing packages allowing to handle such problems include [`FastMarching.jl`](https://github.com/hellemo/FastMarching.jl) which, as the name implies, implements only the FMM. Although there are many cases in which the FSM should be faster, even the FMM implementation of `Eikonal.jl` should be faster than that of `FastMarching.jl` (but the latter may be more accurate in complex cases).

Although a formal documentation is almost inexistant at this point, a few usage examples of `Eikonal.jl` are presented in its [README.md](https://github.com/triscale-innov/Eikonal.jl/blob/main/README.md). Maybe the two most interesting are (click on the images below to get all details):

- computing the time of first arrival of a water wavefront passing through a small opening:  
[![](https://global.discourse-cdn.com/julialang/original/3X/3/0/30a974cea7f79a15bc069a76e2c30dd37dc8ad32.png)](https://github.com/triscale-innov/Eikonal.jl/blob/main/docs/ripple-tank/ripple-tank.md)
- finding a shortest path to move an object in a complex environment (shamelessly and heavily inspired by [James Sethian’s page](https://math.berkeley.edu/~sethian/2006/Applications/Robotics/robotics.html)):  
[![](https://global.discourse-cdn.com/julialang/original/3X/5/3/53ff0f6872c4cd7a22c6ca4242062b7920b9e235.gif)](https://github.com/triscale-innov/Eikonal.jl/blob/main/docs/piano/piano.md)

Finally, the package has just been registered, so you can simply install and use it using the standard `Pkg` tooling:

```julia
import Pkg; Pkg.add("Eikonal")
using Eikonal

```

If you do play with it, please do not hesitate to report back!

* * *

1. Zhao, Hongkai (2005-01-01). “A fast sweeping method for Eikonal equations”. Mathematics of Computation. 74 (250): 603–627. [DOI: 10.1090/S0025-5718-04-01678-3](https://doi.org/10.1090%2FS0025-5718-04-01678-3) 

2. J.A. Sethian. A Fast Marching Level Set Method for Monotonically Advancing Fronts, Proc. Natl. Acad. Sci., 93, 4, pp.1591–1595, 1996. [PDF](https://math.berkeley.edu/~sethian/2006/Papers/sethian.fastmarching.pdf)

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [August 18, 2023, 5:01pm UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/2 "2023-08-18T17:01:28Z")

</div>

Impressive that the whole thing is only 400 lines of code. Nice usage of tuples, cartesian indices, and generated functions to get dimension-agnostic code.

---

<div class="post-metadata">

**Author:** ![raman\_kumar](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/raman_kumar/32/26782_2.png) [@raman\_kumar](https://discourse.julialang.org/u/raman_kumar)\
**Post date:** [August 18, 2023, 5:15pm UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/3 "2023-08-18T17:15:46Z")

</div>

What are other possible uses of it other than following listed in [Eikonal equations](https://en.wikipedia.org/wiki/Eikonal_equation) Wikipedia ? 💬

- A concrete application is the [computation of radiowave attenuation in the atmosphere](https://en.wikipedia.org/wiki/Computation_of_radiowave_attenuation_in_the_atmosphere).
- Finding the [shape from shading](https://en.wikipedia.org/wiki/Shape_from_Shading) in computer vision.
- Geometric optics
- Continuous shortest path problems
- Image segmentation
- Study of the shape for a solid propellant rocket grain  
:julia_troll: :juliadocs: :juliaislisp: :juliabouncer:

---

<div class="post-metadata">

**Author:** ![ffevotte](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ffevotte/32/6587_2.png) [@ffevotte](https://discourse.julialang.org/u/ffevotte)\
**Post date:** [August 18, 2023, 5:26pm UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/4 "2023-08-18T17:26:51Z")

</div>

Note that the uses listed in Wikipedia already cover a broad field. For example,

- I think seismologists sometimes use geometric optics models, which they solve either via ray-tracing methods or by solving Eikonal equations;
- continuous shortest path problems have tons of applications in robotics
- image segmentation / skeletonization also finds a lot of application in diverse fields such as medical imagery or (again) robotics.

  

James Sethian (who invented the Fast Marching method) also has a page that lists a lot of applications of the FMM:

[https://math.berkeley.edu/~sethian/2006/Applications/Menu\_Expanded\_Applications.html](https://math.berkeley.edu/~sethian/2006/Applications/Menu_Expanded_Applications.html)

Not all of them are directly related to solving Eikonal equations, though; some are “tweaked” problems that can also be solved using Fast Marching-like methods, but are not necessarily exactly Eikonal equations (at least not in the form I describe above).

---

<div class="post-metadata">

**Author:** ![LaurentPlagne](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laurentplagne/32/10103_2.png) [@LaurentPlagne](https://discourse.julialang.org/u/LaurentPlagne)\
**Post date:** [August 21, 2023, 9:23am UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/5 "2023-08-21T09:23:48Z")

</div>

Actually less than 300 SLOC 😉  
(I love the piano example)

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [August 21, 2023, 10:44am UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/6 "2023-08-21T10:44:12Z")

</div>

This looks very cool! I am wondering whether we could be using this in Agents.jl as an alternative to path finding in obstacle courses (we have A-star now)! cc @cryptic.ax !

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [August 21, 2023, 11:06am UTC](https://discourse.julialang.org/t/ann-announcing-eikonal-jl/102960/7 "2023-08-21T11:06:18Z")

</div>

Just to advertise, PackageAnalyzer can be used to get a quantitative look at this beautiful package (or any other one 🙂):

```julia
julia> using PackageAnalyzer

julia> analyze("Eikonal")
PackageV1 Eikonal:
  * repo: https://github.com/triscale-innov/Eikonal.jl.git
  * uuid: a6aab1ba-8f88-4217-b671-4d0788596809
  * version: 0.1.1
  * is reachable: true
  * tree hash: ac89a6cf8c89a741448deb8692aaacba745ecee0
  * Julia code in `src`: 303 lines
  * Julia code in `test`: 63 lines (17.2% of `test` + `src`)
  * documentation in `docs`: 891 lines (74.6% of `docs` + `src`)
  * documentation in README & docstrings: 67 lines (18.1% of README + `src`)
  * has license(s) in file: MIT
    * filename: LICENSE
    * OSI approved: true
  * number of contributors: 1 (and 1 anonymous contributors)
  * number of commits: 43
  * has `docs/make.jl`: true
  * has `test/runtests.jl`: true
  * has continuous integration: true
    * GitHub Actions

```

It comes up with 303 lines, but that includes the precompile script added in Eikonal v0.1.1 (`analyze("Eikonal"; version=v"0.1")` reports 280 lines).