Getting started¶

Adelpha is a desktop app. Most people only need the installer. Developers use the same UI with make tauri-dev.

If you have the app¶

1. Download the installer for this computer, then install it.
2. Open it. On an unsigned Mac build, use Right-click → Open the first time. If macOS still blocks it, see If macOS blocks the DMG.
3. Wait for the intro and the Python runtime. The terminal live dot should turn green.

4. Open Settings and set these:

   Page	What to set
   3D Model	Bundled scanner, or import GLB. Settings.
   AI & Agents	Google AI key if you want Agents.
   Digital Twin	Simulated or 48 mT Halbach. Restart after a change.
   Devices	Camera, and devices.json for a Pi or Arduino bridge. Device link.

5. Switch workspace with the top-bar pill, or ⌘K / Ctrl+K.

Config, MRI data, and supervisor.log live outside the app. An optional Agents key is google_api_key in the app config folder.

rm -rf ~/Library/WebKit/org.adelpha.digital-twin-ui

If you are developing¶

Requirements¶

DTAM is already in this repository at sidecar/dtam/. The public Python library is sidecar/python/adelpha/ (pip install adelpha; from adelpha import telemetry, feedback). Python package.

make install
make tauri-dev

That starts Vite, the Tauri window, and python -m adelpha_runtime. You do not need three extra terminals for Twin, Agents, and MRI unless you are working in the browser only.

Passive shimming¶

Hardware → Passive shimming is an Adelpha service at /api/shim, not part of the imaging console. It runs passive_shimming from sidecar/shim/.venv. That package needs NumPy 2. The venv is gitignored. The solver commit is pinned in sidecar/shim/requirements.txt. Gradient coils are the same idea at /api/coil with sidecar/coil/.venv. The Magnet workspace designs Halbach arrays through /api/magnet/halbach. FEM imports its own STEP file and uses /api/magnet/fem; it requires Python with Gmsh and Elmer installed.

uv venv sidecar/shim/.venv --python 3.10
uv pip install --python sidecar/shim/.venv/bin/python -r sidecar/shim/requirements.txt

Restart Adelpha after the install. The desk loads a measured field map (.npy, x, y, z in mm and B in mT) and shows it before shimming; sidecar/console/notebooks/passive_shimming/data/Exp_1044_2026831.npy is one to start with. After a run, Save trays writes the top and bottom STLs and Magpylib collections to a folder you choose. Details are in sidecar/shim/README.md.

Browser-only (npm run dev)¶

Vite on port 5173 proxies /api/* to the classic ports. Start the APIs yourself:

cd sidecar/dtam && make twin-api
cd sidecar/dtam && make agents-api    # needs GOOGLE_API_KEY in sidecar/dtam/.env or the shell
cd sidecar/console && python -m services.api

The in-app terminal has no real shell in the browser. Use make tauri-dev for that.

Health checks:

curl -s http://127.0.0.1:8080/health
curl -s http://127.0.0.1:8002/health

What “good” looks like¶

Docs site¶

uv sync --group docs
make docs-serve

See Docs site.

Installers¶

make sidecar
make dist-current

That builds a current-OS installer (DMG / NSIS / deb or AppImage). Recipients of a packaged Adelpha do not start Twin or MRI APIs themselves.

Unsigned Mac builds: Right-click → Open, or see Signing.

Troubleshooting¶