Installation

Installation

golgi's compiled scientific core — FEniCSx/DOLFINx (the finite-element solver) and, for biophysical thresholds, NEURON — is installed with conda/mamba, because those are not portably pip-installable. Everything else golgi needs (the Trame GUI, PyVista/VTK visualization, meshing helpers, figure export, the auth database, …) is an ordinary PyPI dependency and is installed automatically by pip install -e ..

golgi runs on Linux, macOS, and Windows. The install is: create a conda environment → install golgi with pip → download the tissue database. Each step is below.

---

1. Prerequisites

• conda, or (recommended) mamba / miniforge.
• A C/C++ toolchain (for the FFCx form-compiler JIT):
  • Linux — gcc/g++ (usually already present).
  • macOS — the Xcode command-line tools (xcode-select --install); golgi auto-detects SDKROOT.
  • Windows — the Microsoft MSVC Build Tools.
• (optional) an NVIDIA GPU + CUDA if you plan to use the AxonML high-throughput backend.

2. Create the environment and install golgi

# (a) conda environment with the compiled scientific core
mamba create -n golgi -c conda-forge python=3.12 \
    fenics-dolfinx gmsh python-gmsh pyvista vtk meshio h5py

# On Linux, if this fails due to channel conflicts, add --override-channels:
# mamba create -n golgi -c conda-forge --override-channels python=3.12 fenics-dolfinx gmsh python-gmsh pyvista vtk meshio h5py

mamba activate golgi

# (b) golgi itself + all of its PyPI dependencies, from the repository root
pip install -e .

Step (a) also brings DOLFINx's companions (basix, ffcx, ufl, petsc4py, mpi4py). Installing gmsh/pyvista/vtk/meshio/h5py from conda-forge gives the best-integrated binaries; because golgi's dependencies are unpinned, step (b) detects them and skips them, fetching only what's missing.

Step (b) installs the golgi package, the cuff_designer module, the golgi console command, and the remaining PyPI stack (Trame, SQLAlchemy + bcrypt, trimesh, plotly/kaleido, matplotlib, scikit-image, SimpleITK, opencv, …).

3. Download the tissue-properties database

golgi uses the IT'IS Foundation material database for Cole–Cole tissue conductivity. It is not redistributed with golgi (IT'IS has its own license), so fetch it once — this downloads it directly from itis.swiss and installs it under resources/tissue_db/:

golgi fetch-tissue-db          # equivalently: python -m golgi.conductivity.fetch_itis

golgi still runs without it — the Cole–Cole dialog falls back to a Custom preset — but field solves that use tissue properties need it. For attribution (DOI), manual installation, and the $GOLGI_ITIS_DB override, see Conductivity & Tissue Properties.

4. (Optional) NEURON backend for activation thresholds

The GUI and FEM run without NEURON; only activation-threshold computation needs it.

mamba install -c conda-forge neuron     # recommended
pip install -e ".[neuron]"              # adds pyfibers, the NEURON/MRG backend

5. Verify the install

# API reachable
python -c "import golgi; print(golgi.Study)"

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

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

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

If the last command 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 (pip install -e ".[gpu]" pulls the supporting torch); golgi loads AxonML through a guarded hook when you select that 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 pinned version snapshot of a known-good environment (name==version for every package, no local paths). It is a diagnostic reference, not a one-shot installable lock file: the compiled scientific core (FEniCSx/DOLFINx, PETSc/SLEPc, MPI, NEURON) comes from conda, not PyPI, so those lines cannot simply be pip install-ed. 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.4, 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); capture whole 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.
• Windows / NEURON — the GUI and FEM install cleanly; NEURON is the one component that is easiest on Linux/macOS. If pip install neuron has no matching wheel for your Python, use mamba install -c conda-forge neuron or run threshold computations on Linux/WSL.
• conda + pip OpenCV — if a conda opencv is already present, pip may still add opencv-python (different distribution name) as a second copy; harmless in practice, but if cv2 misbehaves, install OpenCV from a single source.
• 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 · Conductivity & Tissue Properties · Configuration Reference · Troubleshooting & FAQ · License & Citation