Getting Started¶

The fastest way to understand CompNeuroVis is to run one example, then continue with the matching tutorial or concept docs. If you only need one recommendation, start with Static Surface First Look.

Install¶

Base install:

pip install -e .

If you want local docs authoring or PR-readiness checks:

pip install -e ".[contrib]"

If you want matplotlib-backed colormaps such as mpl:viridis:

pip install -e ".[matplotlib]"

Optional simulator backends:

pip install -e ".[neuron]"

pip install -e ".[jaxley]"

If you want contributor tooling plus a simulator backend in one environment:

pip install -e ".[matplotlib,neuron]"
pip install -e ".[contrib,jaxley]"

The current frontend is a local PyQt6/VisPy desktop app, so examples should be run in a normal GUI session.

Choose Your First Example¶

Static Surface First Look¶

Run:

python examples/surface_plot/static_surface_visualizer.py

Use this if you want the lowest-friction first run. It renders a 3-D sinc surface with appearance controls and requires no simulator backend. Then continue with Build a static surface.

Surface Plus Linked Cross-Section¶

Run:

python examples/surface_plot/surface_cross_section_visualizer.py

Use this if you want a 3-D surface linked to a line plot through shared controls. It uses a reusable GridSliceOperatorSpec so the slice logic is not owned by the surface view itself. Then continue with Build a static surface and the generated Example Index for adjacent variants.

Custom Backend With Your Own Solver¶

Run:

python examples/custom/fitzhugh_nagumo_backend.py

Use this if you want the closest runnable reference for "I have my own model and solver." This example subclasses BufferedSession directly, owns a small RK4 integrator, builds Scene / Field / LinePlotViewSpec / PanelSpec manually, and handles controls and actions without using the NEURON or Jaxley helpers. When you need timestamped perf logs for debugging, prefer AppSpec(diagnostics=DiagnosticsSpec(perf_log_enabled=True)) over shell-only environment variables. Then continue with Session/update model and the generated Example Index.

Complex Cell Morphology Viewer¶

Run:

python examples/neuron/complex_cell_example.py

Requires:

pip install -e ".[neuron]"

Use this if you want a live SWC-backed morphology view with traces. Then continue with Build a NEURON session.

Live Jaxley Multicell Example¶

Run:

python examples/jaxley/multicell_example.py

Requires:

pip install -e ".[jaxley]"

Use this if you want a live procedurally built multicell simulation with synaptic connectivity. Then continue with Build a Jaxley session.

Replay a Precomputed Animation¶

Run:

python examples/surface_plot/animated_surface_replay.py

Use this if your data already exists as frames and you want to play them back through the same frontend. Then continue with Build a replay app.

After Your First Run¶

Read Build a static surface if you started with static or grid-based field examples.
Read Build a NEURON session if you started with the NEURON workflow.
Read Build a Jaxley session if you started with the Jaxley workflow.
Read Build a replay app if you started from precomputed frames.
Browse the generated Example Index if you want more runnable entrypoints.
Return to Docs home if you want the broader docs map.

Local Docs Commands¶

Serve the docs site locally:

python -m mkdocs serve

Build the docs site in strict mode:

python -m mkdocs build --strict

Published docs deploy through GitHub Pages from the repo's Actions workflow. After GitHub Pages is configured to use GitHub Actions, pushes to main publish the strict MkDocs build automatically at https://orrenravid1.github.io/CompNeuroVis/.

Contributor PR Flow¶

Run python scripts/pr_readiness.py check while iterating locally.
Commit your implementation changes normally.
As the last commit before you push to main or open a PR, run python scripts/pr_readiness.py seal --commit.

seal --commit reruns the readiness checks, writes a commit-keyed receipt under .compneurovis/pr-readiness/, and adds one final attestation commit automatically.