Skip to content

Latest commit

 

History

History
204 lines (141 loc) · 7.25 KB

README.md

File metadata and controls

204 lines (141 loc) · 7.25 KB
Raw
logo

Stride - A modelling and optimisation framework for medical ultrasound

Build Status Documentation Status Binder

Stride is an open-source library for ultrasound modelling and tomography that provides flexibility and scalability together with production-grade performance.

Quickstart | Tutorials | Other examples | Additional packages | GPU support | Documentation

Key features

High-performance modelling

We provide high-performance, finite-difference, time-domain solvers for modelling ultrasound propagation in the human body, including:

  • Variable speed of sound, density, and attenuation.
  • Off-grid sources and receivers.
  • A variety of absorbing boundary conditions.
  • Targeting both CPUs and GPUs with the same code.

Intuitive inversion algorithms

Stride also lets users easily prototype medical tomography algorithms with only a few lines of Python code by providing:

  • Composable, automatic gradient calculations.
  • State-of-the-art reconstruction algorithms.
  • The flexibility to (re)define every step of the optimisation.

Flexibility

Solvers in Stride are written in Devito, using math-like symbolic expressions. This means that anyone can easily add new physics to Stride, which will also run on both CPUs and GPUs.

Scalability

Stride can scale seamlessly from a Jupyter notebook in a local workstation, to a multi-node CPU cluster or a GPU cluster with production-grade performance.

Quickstart

Jump right in using a Jupyter notebook directly in your browser, using binder.

Otherwise, the recommended way to install Stride is through Anaconda's package manager (version >=4.9), which can be downloaded in Anaconda or Miniconda. A Python version above 3.8 is recommended to run Stride.

To install Stride, follow these steps:

git clone https://github.com/trustimaging/stride.git
cd stride
conda env create -f environment.yml
conda activate stride
pip install -e .

You can also start using Stride through Docker:

git clone https://github.com/trustimaging/stride.git
cd stride
docker-compose up stride

which will start a Jupyter server within the Docker container and display a URL on your terminal that looks something like https://127.0.0.1:8888/?token=XXX. To access the server, copy-paste the URL shown on the terminal into your browser to start a new Jupyter session.

Running the examples

The easiest way to start working with Stride is to open the Jupyter notebooks under stride_examples/tutorials.

You can also check fully worked examples of breast imaging in 2D and 3D under stride_examples/breast2D and stride_examples/breast2D. To perform a forward run on the breast2D example, you can execute from any terminal:

cd stride_examples/examples/breast2D
mrun python 01_script_forward.py

You can control the number of workers and threads per worker by running:

mrun -nw 2 -nth 5 python 01_script_forward.py

You can configure the devito solvers using environment variables. For example, to run the same code on a GPU with OpenACC you can:

export DEVITO_COMPILER=pgcc
export DEVITO_LANGUAGE=openacc
export DEVITO_PLATFORM=nvidiaX
mrun -nw 1 -nth 5 python 01_script_forward.py

Once you've run it forward, you can run the corresponding inverse problem by doing:

mrun python 02_script_inverse.py

You can also open our interactive Jupyter notebooks in the public binder.

Additional packages

To access the 3D visualisation capabilities, we also recommend installing MayaVi:

conda install -c conda-forge mayavi

and installing Jupyter notebook is recommended to access all the examples:

conda install -c conda-forge notebook

GPU support

To run a solver using the GPU, simply add the option platform="nvidia-acc":

pde = IsoAcousticDevito(...)
await pde(..., platform="nvidia-acc")

The Devito library uses OpenACC to generate GPU code. The recommended way to access the necessary compilers is to install the NVIDIA HPC SDK before creating the Stride environment.

wget https://developer.download.nvidia.com/hpc-sdk/22.11/nvhpc_2022_2211_Linux_x86_64_cuda_multi.tar.gz
tar xpzf nvhpc_2022_2211_Linux_x86_64_cuda_multi.tar.gz
cd nvhpc_2022_2211_Linux_x86_64_cuda_multi
sudo ./install

During the installation, select the single system install option.

Once the installation is done, add the following lines to your ~/.bashrc:

export HPCSDK_HOME=/opt/nvidia/hpc_sdk/Linux_x86_64/22.11
export NVHPC_CUDA_HOME=$HPCSDK_HOME/cuda
export CUDA_ROOT=$HPCSDK_HOME/cuda/bin
export PATH=$HPCSDK_HOME/compilers/bin/:$PATH
export LD_LIBRARY_PATH=$HPCSDK_HOME/compilers/lib/:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HPCSDK_HOME/cuda/lib/:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HPCSDK_HOME/cuda/lib64/:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HPCSDK_HOME/math_libs/lib64/:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HPCSDK_CUPTI/lib64/:$LD_LIBRARY_PATH

Citing Stride

If you use Stride in your research, please cite our paper:

@misc{cueto2021-stride,
	title          =    { Stride: a flexible platform for high-performance ultrasound computed tomography  },
	author         =    { Carlos Cueto and Oscar Bates and George Strong and Javier Cudeiro and Fabio Luporini
				and Oscar Calderon Agudo and Gerard Gorman and Lluis Guasch and Meng-Xing Tang },
	journal        =    {Computer Methods and Programs in Biomedicine},
	volume         =    {221},
	pages          =    {106855},
	year           =    {2022},
	issn           =    {0169-2607},
	doi            =    {https://doi.org/10.1016/j.cmpb.2022.106855},
	url            =    {https://www.sciencedirect.com/science/article/pii/S0169260722002371},
}

Contact us

Join the conversation to share your projects, contribute, and get your questions answered.

Documentation

For details about the Stride API, check our latest documentation.