Getting Started

New to Sentinel?

Work through Your First Inversion — it reconstructs a stiffness map from data bundled with the package, in a few seconds, with nothing to download. This page covers installation and setup.

Installation

Install Julia

Sentinel needs Julia 1.11+. The easiest way to install and manage Julia is juliaup:

# macOS / Linux
curl -fsSL https://install.julialang.org | sh

Restart your shell, then verify (and keep Julia current):

juliaup status      # installed channels
julia --version     # should be ≥ 1.11
juliaup update      # update to the latest stable release

On macOS you can alternatively brew install juliaup.

Install Sentinel

Sentinel.jl is not yet registered in the Julia General registry. Two ways to install:

As a package — use it from your own environment:

using Pkg
Pkg.add(url="https://github.com/mechneurolab/sentinel")

As a clone — recommended for development (editing source, running the test suite, using the bin/sentinel CLI, and running the bundled examples):

git clone https://github.com/mechneurolab/sentinel.git
cd sentinel

using Pkg
Pkg.activate(".")     # use Sentinel's own project environment
Pkg.instantiate()     # install the pinned dependencies

Or develop the clone into another environment so your edits are picked up live:

using Pkg
Pkg.develop(path="/path/to/sentinel")

Requirements: Julia 1.11+, Ferrite.jl 1.3.0 (installed automatically).

Optional Dependencies

# MUMPS solver (recommended for large problems)
Pkg.add("MUMPS")

# GPU acceleration (Apple Silicon)
Pkg.add("Metal")

# GPU acceleration (NVIDIA)
Pkg.add("CUDA")
Pkg.add("CUDSS")

# AppleAccelerate (macOS — loaded automatically, ~13% faster sparse solves)
Pkg.add("AppleAccelerate")

AppleAccelerate

On macOS, Sentinel automatically loads AppleAccelerate if available, switching the BLAS/LAPACK backend to Apple's Accelerate framework. This gives ~13% faster sparse LU solves on Apple Silicon.

Development setup (VS Code)

The Julia extension for VS Code gives an integrated REPL, debugger, and plot pane — a convenient way to run Sentinel.

1. Install the extension. In VS Code → Extensions, install "Julia" (julialang.language-julia). It auto-detects the juliaup-managed Julia.

2. Open the cloned repo (File → Open Folder → your sentinel/ clone).

3. Use Sentinel's environment. Start a Julia REPL (Command Palette → "Julia: Start REPL"). The status bar should show the sentinel project; if not, click it and choose the repo folder, or run ] activate . in the REPL.

4. Set the thread count. The inversion parallelizes across Julia threads, but VS Code starts the REPL with one thread by default. In Settings, set julia.NumThreads to "auto" (all cores) or a number, then restart the REPL. Verify with Threads.nthreads().

Why threads matter

The inversion auto-selects a multicore strategy from the material model and the thread count (see How to Run Inversions in Parallel and Command-Line Interface). With a single thread it runs serially — so set julia.NumThreads before a real run.

Running an inversion from a .mat file

You can start an inversion directly from an MRE .mat data file — the mesh and displacement files are generated from it automatically, so no pre-built mesh is needed. There are three entry points.

1. InversionProblem + solve — declarative, writes files + provenance:

using Sentinel

prob = InversionProblem(data="scan.mat", frequency=60.0, mesh_strategy=2,
                        model=:isotropic, output="inv/scan")
result = solve(prob)            # → InversionResult

result.state.converged          # did it converge?
result.material                 # reconstructed properties

2. Sentinel.invert — one shot, shear modulus on the image voxel grid:

using Sentinel

res = Sentinel.invert("scan.mat";
    opts = (material_model="isotropic", regularization="total_variation",
            reg_weight=1e-3, frequency_hz=60.0, density_kg_m3=1000.0,
            max_global_iters=20, mesh_resolution=1,
            compute_backend="auto"))   # gradient device: "auto" | "gpu" | "cpu"

res.real_shear   # storage modulus (Pa) on the original voxel grid (NaN outside the mask)
res.imag_shear   # loss modulus (Pa)
res.voxel_size   # (mm); res.dims; res.stats (convergence/QA summary)

Note

invert is not exported — call it as Sentinel.invert.

3. TOML + the sentinel CLI:

# inversion.toml
[data]
mat = "scan.mat"
frequency_hz = 60.0
output = "recon"

[model]
type = "isotropic"

bin/sentinel invert inversion.toml --threads 8    # Model 1 → multicore (auto)

A runnable, no-download version is in examples/run_mat_demo.sh, which uses the bundled test/fixtures/forge_mre_uiuc.mat. See the Command-Line Interface guide for the full CLI reference.

To get results out to MATLAB or ParaView, see How to Export Results to MATLAB and ParaView.

Where to go next

• Run your first reconstruction — Your First Inversion.

• Set up the problem — How to Choose a Material Model, How to Generate a Mesh from MRI Data, and How to Add DTI Fiber Directions.

• Tune the reconstruction — How to Choose and Configure Regularization and How to Choose an Optimizer.

• Configure a run with a Fortran-compatible .dat runfile — Configuring Inverse Runfiles.

• Export results to MATLAB, ParaView, or ReconProps.mat — How to Export Results to MATLAB and ParaView.

• Drive Sentinel from the shell — Command-Line Interface.

• Understand the equations and the solver — the Mathematical Reference and Inverse Solver Pipeline.