Installation

Installation

golgi runs on Linux and macOS. Its scientific core — FEniCSx/DOLFINx (FEM) and NEURON (fiber biophysics) — is most reliably installed with conda/mamba, because these packages are not portably pip-installable. golgi therefore deliberately does not declare the heavy stack as pip dependencies: you install the stack into a conda environment first, then install golgi itself with pip install -e ..

TL;DR

mamba create -n golgi -c conda-forge fenics-dolfinx python=3.12
mamba activate golgi
pip install -e .

This gets you FEniCSx; the GUI/analysis extras below complete a working install.

---

Prerequisites

• conda or (recommended) mamba / miniforge.
• A C/C++ toolchain (for the FFCx form-compiler JIT). On macOS install the Xcode command-line tools (xcode-select --install); golgi auto-detects SDKROOT.
• (optional) an NVIDIA GPU + CUDA for the AxonML high-throughput backend.

Step 1 — create the environment with FEniCSx

mamba create -n golgi -c conda-forge fenics-dolfinx python=3.12
mamba activate golgi

This pulls DOLFINx and its companions (basix, ffcx, ufl, petsc4py, mpi4py).

Step 2 — meshing + 3-D visualization

mamba install -c conda-forge gmsh python-gmsh pyvista vtk meshio h5py
pip install tetgen pymeshfix

tetgen provides the AGPL TetGen core used for volume meshing (see License & Citation).

Step 3 — fiber biophysics backend

pip install pyfibers

pyfibers is the default NEURON/MRG backend. The optional AxonML GPU surrogate is not bundled and must be obtained separately (see below).

Step 4 — GUI + analysis stack

pip install "trame" "trame-vtk" "trame-vuetify" "trame-plotly" \
            plotly kaleido matplotlib seaborn pandas \
            SQLAlchemy trimesh pykdtree

trame* powers the browser GUI; plotly/kaleido render and export figures; SQLAlchemy backs the auth/audit database.

Step 5 — install golgi

pip install -e .          # from the repository root

This installs the golgi package and the golgi console command.

---

Verify the install

# 1) the package imports and the API is reachable
python -c "import golgi; print(golgi.Study)"

# 2) fast, solver-free tests (run anywhere)
pytest tests/test_headless_api.py -m "not integration"
pytest tests/test_recording_cable.py -q

# 3) launch the GUI (then open the printed URL)
golgi

# 4) full end-to-end smoke on a synthetic nerve (needs the solver stack)
python examples/recruitment_sweep.py

If step 4 runs to completion and writes recruitment_curve.png plus vagus_study.golgi, your install is complete. See Getting Started for what to do next.

---

Optional extras

AxonML GPU backend

AxonML is a proprietary, non-commercial Duke University package (not open source) — golgi never bundles it. If you have separately obtained and accepted its license, install it into the environment; golgi will load it through a guarded hook when you select the AxonML backend. A CUDA-capable GPU is required for the speedup (it falls back to CPU otherwise). See Fiber Models & Activation and License & Citation.

Promptable segmentation (MedSAM2 / SAM)

The segmentation panel uses a MedSAM2/SAM-style model when a checkpoint is available (point it at one via the documented env var / cache path). Without a model, golgi falls back to a stub segmenter so the rest of the app still works — you can also import nerve surfaces (STL/NAS/OBJ) or pre-built bundles directly and skip segmentation entirely.

---

Reproducing an exact environment

requirements-frozen.txt is a diagnostic snapshot of a known-good environment, not an installable lock file (it contains conda file:// URLs that won't resolve off-host). Known-good major versions: DOLFINx 0.10, NEURON 9.0.1, PyFibers 0.8.5, Gmsh 4.15.2, TetGen 0.8.4, PyVista 0.48, Trame 3.12, NumPy 2.3, SciPy 1.17. For byte-level reproduction of a study, prefer a study bundle (it carries the version + frozen deps and is golgi replay-verifiable), and capture environments with conda env export.

---

Platform notes & gotchas

• macOS FFCx JIT — if form compilation fails, ensure the Xcode CLT are installed; golgi sets SDKROOT automatically when it can.
• macOS / single-rank MPI — pin the libfabric provider to TCP (FI_PROVIDER=tcp / GOLGI_FI_PROVIDER=tcp) to avoid an OFI finalize crash.
• MPI launcher — override the launcher with GOLGI_MPIRUN (mpirun / mpiexec / srun) on clusters.

More fixes are on the Troubleshooting & FAQ page.

---

See also

Getting Started · Configuration Reference · Troubleshooting & FAQ · License & Citation