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 and macOS. On Windows, run it inside WSL2 (Windows Subsystem for Linux): the FEniCSx solver stack — PETSc/petsc4py — has no native-Windows build on conda-forge, so the finite-element and fiber-tracing solvers cannot run under native Windows Python. Inside a WSL2 Ubuntu shell the install below works verbatim, and the GUI still opens in your Windows browser (WSL2 forwards localhost). See Windows (WSL2) below.

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 — install inside WSL2 and use the Linux toolchain there (see Windows (WSL2)).
• (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
# On Linux, if this fails due to channel conflicts, add --override-channels:
# mamba install -c conda-forge --override-channels neuron
pip install -e ".[neuron]"              # adds pyfibers, the NEURON/MRG backend
pyfibers_compile
# If compilation fails on Linux, install compilers:
# mamba install -c conda-forge --override-channels compilers

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.

---

Windows (WSL2)

golgi's finite-element and fiber-tracing solvers are built on FEniCSx/DOLFINx, which depends on PETSc via petsc4py. conda-forge does not ship a Windows (win-64) build of petsc4py/PETSc (PETSc does not build under MSVC), so those solvers cannot run under native Windows Python — a native install fails at ModuleNotFoundError: No module named 'petsc4py' the moment a solve is launched.

The supported way to run golgi on Windows is WSL2, where you get a real Linux environment:

# 1. In an elevated PowerShell (installs WSL2 + Ubuntu, then reboot if prompted):
wsl --install

# 2. In the Ubuntu (WSL2) shell — install miniforge/mamba, then follow the Linux steps verbatim:
mamba create -n golgi -c conda-forge python=3.12 fenics-dolfinx gmsh python-gmsh pyvista vtk meshio h5py
mamba activate golgi
pip install -e .
golgi fetch-tissue-db
golgi                       # open the printed http://localhost:… URL in your Windows browser

The GUI is served over localhost, which WSL2 forwards to Windows automatically, so it opens in your normal Windows browser. Keep the repository on the Linux filesystem (e.g. ~/golgi, not /mnt/c/…) for far better I/O performance.

---

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 — the FEniCSx solver stack (PETSc/petsc4py, and therefore DOLFINx's solver path) has no native-Windows conda-forge build, so meshing-to-FEM and fiber tracing cannot run under native Windows Python — install under WSL2 instead (see Windows (WSL2)).
• 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