Skip to main content

NeuroForge Science

Upload reconstructed neurons, assemble a circuit, analyze its structure, and explore its simulated signals in an interactive playbox.

An installable Python package with a familiar API:

import neuroforge as nf
from neuroforge import view

This is a working alpha research prototype, independent of NeuroM. It is not a drop-in replacement or an established, experimentally validated simulator. The distribution name is neuroforge-science; the Python import is neuroforge. This download is installable locally; it has not been published to PyPI.

Start on Windows

  1. Install Python 3.11 or newer if needed. Python 3.12 is the tested version.
  2. Extract the complete ZIP. Open its neuroforge-science folder.
  3. Double-click START_PLAYBOX.bat. The first launch creates a local virtual environment and installs dependencies; it needs an Internet connection.
  4. Open http://localhost:8501 if a browser tab does not open automatically.

Or use PowerShell inside the extracted folder:

python -m venv .venv
.venv\Scripts\python.exe -m pip install ".[ui]"
.venv\Scripts\python.exe -m neuroforge playbox

The startup batch file uses its own Python executable, so PowerShell activation policy does not need to change. It does not require administrator access.

Start on macOS / Linux

python3 -m venv .venv
.venv/bin/python -m pip install '.[ui]'
.venv/bin/python -m neuroforge playbox

Alternatively, run bash start_playbox.sh. Stop the local server with Ctrl+C. The playbox binds to 127.0.0.1; it is not a public website. Uploaded experiment data remain in the running local application unless you export them. Export before stopping: session state is not a persistent project database.

What scientists can upload

Input Purpose
One or more .swc files Traced 3D neuron reconstructions: one rooted tree per file
Optional synapse .csv Source/target names, signed current weights, transmission delays, evidence labels
A saved NeuroForge network .json Reopen an assembled circuit with geometry, registration and connections

The current release does not trace neurons from microscopy TIFFs, screenshots, or EM volumes, interpret SWC+ metadata, or load ASC/H5/NWB/NeuroML directly. Convert those inputs to standard SWC reconstructions using appropriate domain tools first. A file named neuron_A.swc becomes neuron neuron_A in the UI. Use those exact names in the synapse table.

Standard SWC columns:

# id type x y z radius parent
1 1 0 0 0 5 -1
2 2 20 0 0 0.8 1
3 3 -10 15 0 1.0 1
4 3 -20 25 5 0.6 3

Type 1 is soma, 2 axon, 3 basal dendrite, and 4 apical dendrite. Other nonnegative types are retained; unknown/glial/custom types are not used for proximity matches. Coordinates and radii default to micrometers. Set unit_scale_um=1000 for input in millimeters; the scale applies to both coordinates and radii.

The parser rejects duplicate IDs, invalid/missing parents, cycles, multiple roots, negative radii, nonfinite coordinates, and malformed columns. It accepts unordered parent references as a tolerant extension and canonicalizes SWC exports. Zero radii, missing soma annotations and zero-length segments produce quality warnings. It cannot certify that a reconstruction is biologically complete.

The playbox workflow

  1. Try the original four-neuron synthetic demo already loaded at startup.
  2. In Circuit map, rotate the 3D neuron geometry and inspect connections.
  3. In Analysis, inspect cable length, branch points, terminal points, axon and dendrite length, estimated neurite surface/volume, degrees, components and density.
  4. In Playbox, set current pulses, time step, electrical parameters, noise, random seed and output neuron groups. Press Run experiment.
  5. Press Play spikes inside the 3D chart. Highlighted cell bodies fired in that time bin. Inspect the spike raster and membrane voltage traces below.
  6. In Export, download a reproducible experiment ZIP, network JSON or synapse CSV.
  7. Replace the synthetic demo with your own SWC reconstructions and evidence.

Demo: stronger left input (0.35 nA versus 0.22 nA) selects the Left/A readout. Swap the currents to select Right/B. Equal symmetric input produces a tie. This behavior comes from a configured four-cell circuit with assumed excitation and cross-inhibition; it is not inferred cognition or a fitted biological experiment.

Output groups are your operational definition of a choice. The readout compares mean spike counts per neuron, preventing larger groups from winning merely because they contain more cells. Groups must be nonempty and disjoint. Ties and insufficient activity produce None/Undecided. Score shares are not probabilities or confidence intervals. There is no learning or synaptic plasticity in this release.

Load and analyze a real reconstruction

import neuroforge as nf
from neuroforge import view

neuron = nf.load_morphology("neuron_A.swc")
print(nf.analyze(neuron))
view.morphology(neuron).show()

Surface area is the sum of truncated-cone lateral areas along non-soma child segments; volume is the sum of their truncated-cone volumes. These exclude soma, end caps, spines and overlap corrections at branches. Cable length excludes soma-to-soma edges. Branch counts exclude soma samples, and root path lengths are measured along the sampled tree. These definitions are explicit and may differ from metrics produced by other morphology packages.

Assemble multiple neurons

a = nf.load_morphology("neuron_A.swc", name="A")
b = nf.load_morphology("neuron_B.swc", name="B")
network = nf.Network([a, b])
network.import_synapses("synapses.csv")
print(network.analyze())
view.network(network).show()
network.save("network.json")

Minimum synapse CSV:

source,target,weight_nA,delay_ms,provenance,note
A,B,0.8,1.0,manual,Assumed excitatory link for exploration
B,A,-0.4,2.0,manual,Assumed inhibitory link for exploration

weight_nA is a signed peak current jump on spike arrival, not a conductance or an automatically calibrated physiological measurement. Negative inhibits; positive excites. CSV imports require weights and delays, rather than making up missing electrical parameters. Optional source_node and target_node values refer to SWC sample IDs. Multiple synapses per pair and self connections are allowed.

The provenance field accepts manual, measured, inferred, or synthetic. The measured label is supplied by the investigator, not verified by this package. An anatomical contact count alone does not supply a measured current or delay. Record separate evidence and calibration in the note and your experiment records. Imports validate every row before adding any rows. Missing CSV provenance defaults to manual; it never defaults to measured.

Registration and optional geometric hypotheses

Independent reconstructions often have local coordinate origins. They cannot be connected meaningfully by proximity until registered in a common tissue frame. NeuroForge applies supplied rigid transforms; it does not recover unknown registration or stitch broken neurite fragments automatically.

import numpy as np

# Replace these example transforms with your experiment's actual registration.
a = a.translated([0, 0, 0], coordinate_frame="slice_01_um")
b = b.translated([100, 0, 0], coordinate_frame="slice_01_um")
# For a rotation + translation: a.transformed(matrix_4x4, coordinate_frame="slice_01_um")
network = nf.Network([a, b])

# Inspect suggestions without modifying the graph.
for suggestion in network.propose_connections(max_distance_um=3):
    print(suggestion)

# Explicit opt-in: add inferred links only where no directed pair already exists.
network.infer_connections(max_distance_um=3, weight_nA=0.1, delay_ms=1.0)

The inference routine finds the nearest axon-sample center to dendrite-sample center for each directed pair within the supplied threshold, excluding self links. It does not compute continuous segment or membrane contact, detect real synapses, infer neurotransmitters, or learn electrical weights/delays. Sparse sampling can miss close segments. Every suggestion records sample IDs, distance, assumed electrical values and inferred provenance. Existing measured/manual pairs are preserved. Changing registration in the UI removes inferred links.

Simulate a configured circuit

network = nf.demo_network()
result = nf.simulate(
    network,
    duration_ms=500,
    dt_ms=0.1,
    seed=42,
    parameters=nf.LIFParameters(noise_std_nA=0.0),
    stimuli=[
        nf.Stimulus("input_left", current_nA=0.35, start_ms=20, end_ms=450),
        nf.Stimulus("input_right", current_nA=0.22, start_ms=20, end_ms=450),
    ],
)
print(result.firing_rates_hz())
print(result.choice({"Left": ["choice_left"], "Right": ["choice_right"]}))
view.raster(result).show()
view.voltage(result).show()
view.save_playback(network, result, "playback.html")
result.save("simulation.npz")

Core equations, with time in ms, voltage in mV, resistance in MΩ and current in nA:

tau_m * dV/dt = -(V - V_rest) + R * (I_external + I_synaptic + I_noise)
tau_syn * dI_synaptic/dt = -I_synaptic
on delayed spike arrival: I_synaptic += signed weight_nA
if V >= V_threshold: record spike; reset V; enforce refractory period

Each SWC neuron becomes one point-neuron electrical unit. Dendritic shape, segment radii, placement and branch count do not set membrane parameters or intracellular signal propagation. The shape is used for analysis and optional connectivity hypotheses. All cells share one parameter set in this release.

Voltage integration uses an exponential constant-current update. Synaptic current is held over each step then exponentially decayed, so this is an approximation to coupled dynamics. Threshold crossings are detected at grid endpoints. Pulse boundaries and duration must align to the time step. Delays and refractory periods round upward to grid intervals. A spike recorded at time t arrives at t + ceil(delay/dt)*dt; its first effect appears at the following voltage endpoint. Saved voltages are after reset, not plotted action-potential waveforms.

Noise is a per-bin independent Gaussian current, not continuous white-noise diffusion; changing dt changes its effective statistics. Set noise to zero for deterministic experiments. For scientific work, check time-step convergence and compare against measured electrophysiology. Use a validated compartmental simulator such as NEURON when active dendrites, channels, or detailed cable dynamics are the research objective.

Commands

python -m neuroforge playbox
python -m neuroforge demo --output demo_results
python -m neuroforge demo --left 0.22 --right 0.35 --output reverse_results
python -m neuroforge analyze neuron_A.swc --output morphology_report.json
python -m neuroforge assemble neuron_A.swc neuron_B.swc --synapses synapses.csv --output network.json
python -m neuroforge simulate network.json --stimuli stimuli.json --duration-ms 500 --output run.npz

Stimulus JSON is an array of objects with target, current_nA, start_ms, and end_ms. The demo command writes an example. Installing without the optional UI uses only NumPy: python -m pip install .. The demo's HTML playback is created when Plotly is installed; the numerical demo works without it.

Export and reproducibility

The experiment bundle includes morphology SWCs, network JSON, analysis JSON, synapse CSV, and (after a run) compressed arrays, model metadata and readout groups. Network JSON preserves original sample order alongside canonical SWC. Simulation metadata embeds the exact network snapshot, pulse definitions, seed, parameters, effective delays and package/NumPy versions. Input hashes cover the decoded SWC text before scaling/registration, not necessarily byte-for-byte source files with a BOM. They track provenance and are not authenticated signatures.

import json
import numpy as np

with np.load("simulation.npz", allow_pickle=False) as arrays:
    times = arrays["times_ms"]       # [time]
    voltage = arrays["voltage_mV"]   # [time, neuron]
    spikes = arrays["spikes"]        # bool [time, neuron]
    metadata = json.loads(str(arrays["metadata_json"]))

Reproducibility assumes the same data, parameters, dt, seed and compatible runtime versions. Results are not promised bit-identical across different NumPy/platform versions. The UI limits uploads to 60 neurons / 100,000 samples; the default simulation caps traces at 5 million time-by-neuron values. Proximity matching caps candidate pair comparisons. This is a small-circuit workbench, not a whole-brain platform.

Tests and development

python -m pip install -e '.[ui,dev]'
python -m pytest -q
python -m build

Tests cover known geometry and unit conversions; corrupt/deep SWC trees; registration; inference labeling and measured-edge preservation; atomic CSV imports; graph topology; JSON roundtrips; a closed-form passive response and first-spike timing; delay rounding and event ordering; inhibition; seeded reproducibility; reversed/tied demo choices; and the interactive app's run/export journey. These are numerical/software checks, not experimental validation.

Scientific references

MIT licensed. All included SWCs and example circuitry are original synthetic teaching data, with no claim to represent a recorded cell or animal experiment.

Metadata

Release files for neuroforge-science 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neuroforge-science 0.1.0
File Size Uploaded Provenance Actions
neuroforge_science-0.1.0.tar.gz 42.7 kB Without provenance Details for neuroforge_science-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neuroforge-science 0.1.0
File Interpreter ABI Platform Actions
neuroforge_science-0.1.0-py3-none-any.whl Python 3 none any Details for neuroforge_science-0.1.0-py3-none-any.whl

Total release size: 77.8 kB

Release files / neuroforge_science-0.1.0.tar.gz

Download URL neuroforge_science-0.1.0.tar.gz
Size 42.7 kB
Tags Source
SHA-256 checksum
How to use checksums
edd1020404885f2361ede63eb316b845d8979057a9ae3e8c42f047c9c5baad5f
BLAKE2b-256 checksum
How to use checksums
9ded04330ef41ce8b2e38e4852d8da28a8b6e0e275e2805894b8d2ed9871f680
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / neuroforge_science-0.1.0-py3-none-any.whl

Download URL neuroforge_science-0.1.0-py3-none-any.whl
Size 35.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
450867a727864b9968472d1b3fdbaa004385fa529ca77230c8017068a9ac2901
BLAKE2b-256 checksum
How to use checksums
8826f9d8a9ac13623854d8702e399f3b273a81d9d198b390819e979db7d46a5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for neuroforge-science 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page