Metadata-Version: 2.4
Name: eiko
Version: 0.8.0
Summary: Eiko: the GPU-accelerated Eikonal equation solver
Author-email: Sebastian Kazmarek Præsius <sebastian.devel@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2026, Sebastian Kazmarek Præsius
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, https://github.com/sebftw/Eiko
Keywords: gpu,cuda,pytorch,jax,automatic differentiation,autodiff,time of flight,beamforming,shortest path,batch-processing,fast iterative Method,eikonal,eikonal equation,PDE,partial differential equations,scientific computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: ninja
Provides-Extra: jax
Requires-Dist: jax[cuda12]; extra == "jax"
Requires-Dist: pybind11; extra == "jax"
Provides-Extra: jax-local
Requires-Dist: jax[cuda12_local]; extra == "jax-local"
Requires-Dist: pybind11; extra == "jax-local"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: jax[cuda12_pip]; extra == "examples"
Requires-Dist: pybind11; extra == "examples"
Requires-Dist: optax; extra == "examples"
Requires-Dist: scipy>=1.7.0; extra == "examples"
Requires-Dist: numpy>=1.21.0; extra == "examples"
Requires-Dist: scikit-image; extra == "examples"
Requires-Dist: pyvista>=0.43.0; extra == "examples"
Requires-Dist: Pillow>=9.0.0; extra == "examples"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: tox>=4.0.0; extra == "test"
Requires-Dist: vermin; extra == "test"
Dynamic: license-file

# Eiko
**Eiko** is a GPU-accelerated Eikonal equation solver, enabling fast
computation of the shortest time-of-flight through an arbitrary 2D or 3D medium.

A few reasons to use Eiko:
1. Eiko is **fast** - up to 10x faster than comparable libraries.
2. Eiko is **differentiable**, allowing it to be used with PyTorch or JAX.
3. Eiko supports **advection**, allowing it to compute apodizations through a lens.

![Image of example](/examples/python/comparison/fps_comparison.png "Comparison between Eiko and other solvers.")

## Installation
### Requirements
Because Eiko compiles custom CUDA kernels during installation, your system must have the following:
* **OS:** Linux or Windows
* **Hardware:** NVIDIA GPU
* **Compiler:** 
  * A C++ compiler (e.g., GCC for Linux, MSVC for Windows)
  * The CUDA Toolkit (provides `nvcc`)

### Installing for MATLAB
Run `setup.m` to install Eiko for MATLAB.

### Installing for Python
Run
```
pip install eiko
```
You now have Eiko installed and ready for use.

See also [the Eiko Python installation guide](/python/PYTHON_INSTALLATION.md).

## Quick Start
An example of how to use Eiko is shown below.
<br>
See [EXAMPLES](/examples/README.md) for many more examples.

### MATLAB example
```matlab
% 1. Setup grid parameters.
N = 101;            % Number of grid points (NxN grid)
dx = 0.001;         % Grid spacing in meters (1 mm, for example)
c = 1540;           % Speed of sound in m/s (uniform medium)

% 2. Create the slowness map (1/velocity).
f = ones(N, N, 'single', 'gpuArray') / c;

% 3. Initialize the time-of-flight field.
u_init = inf(N, N, 'single', 'gpuArray'); % Unknown points set to infinity.

% Set a point source at the center of the grid to time = 0.
center_idx = ceil(N/2);
u_init(center_idx, center_idx) = 0;

% 4. Compute the numerical solution using eiko.
u_numerical = eiko(u_init, f, dx);

% 5. Visualize the result.
% Create physical coordinate axes in millimeters using dx
axis_mm = ((1:N) - center_idx) * dx * 1000;

% Set up plot.
figure;
imagesc(axis_mm, axis_mm, u_numerical * 1e6);
axis image;

% Format axes and text size.
title('Time-of-Flight Field', 'FontSize', 14, 'FontWeight', 'bold');
xlabel('x (mm)', 'FontSize', 12, 'FontWeight', 'bold');
ylabel('y (mm)', 'FontSize', 12, 'FontWeight', 'bold');

% Format colorbar.
cb = colorbar;
cb.Label.String = 'Time (\mus)';
cb.Label.FontSize = 12;
```
For 3D inputs, call `eiko3d`.

### Python example

```python
from eiko import eiko

# 1. Setup device and grid parameters.
device = torch.device("cuda")
N = 101
dx = 0.001  # Grid spacing in meters (1 mm)
c = 1540.0  # Speed of sound in m/s (uniform medium)

# 2. Create the slowness map (1/velocity) on the device.
f = torch.full((N, N), 1.0 / c, dtype=torch.float32, device=device)

# 3. Initialize the time-of-flight field.
# Unknown points are set to infinity
u_init = torch.full((N, N), float('inf'), dtype=torch.float32, device=device)

# Set a point source at the center of the grid to time = 0.
center_idx = N // 2
u_init[center_idx, center_idx] = 0.0

# 4. Compute the numerical solution.
u_numerical = eiko(u_init, f, dx=dx)
```
For 3D inputs, use `from eiko import eiko3d`.


The result should look something like this:

![Image of example](/images/eiko_example.png "Result of the example code.")

## Project Layout
The files are as follows:
```
Eiko/
├── examples/       # Example scripts (tomography, lens design, etc.).
│   ├── matlab/     #   MATLAB example scripts 
│   └── python/     #   Python example scripts
├── matlab/         # MATLAB Eiko library
├── python/         # Python Eiko library
├── src/            # Core CUDA C++ Eiko implementation and interface
├── pyproject.toml  # Python package configuration (for pip install)
├── setup.m         # MATLAB compilation and setup script
├── THEORY.md       # Mathematical background and Eikonal algorithm details
└── README.md       # This file
```
To learn more about how Eiko works, see [THEORY](THEORY.md).

## Citing
You can cite Eiko as
```
@misc{eiko2026,
  author = {Pr{\ae}sius, Sebastian},
  title = {Eiko: the GPU-accelerated Eikonal equation solver},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/sebftw/Eiko}}
}
```
