{"id":24772854,"url":"https://github.com/neuronsimulator/ringtest","last_synced_at":"2025-10-11T22:30:16.469Z","repository":{"id":43319122,"uuid":"63783573","full_name":"neuronsimulator/ringtest","owner":"neuronsimulator","description":"Ring network model test to demonstrate the use of CoreNEURON","archived":false,"fork":false,"pushed_at":"2025-07-21T14:11:53.000Z","size":183,"stargazers_count":12,"open_issues_count":1,"forks_count":6,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-07-21T16:33:56.304Z","etag":null,"topics":["coreneuron","hpc","neuron","neuroscience"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neuronsimulator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-20T13:26:26.000Z","updated_at":"2025-07-21T14:11:58.000Z","dependencies_parsed_at":"2024-04-09T19:53:05.332Z","dependency_job_id":"77879482-c049-41a2-9fba-262ac676d09b","html_url":"https://github.com/neuronsimulator/ringtest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/neuronsimulator/ringtest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronsimulator%2Fringtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronsimulator%2Fringtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronsimulator%2Fringtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronsimulator%2Fringtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neuronsimulator","download_url":"https://codeload.github.com/neuronsimulator/ringtest/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronsimulator%2Fringtest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279009071,"owners_count":26084549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coreneuron","hpc","neuron","neuroscience"],"created_at":"2025-01-29T04:33:42.394Z","updated_at":"2025-10-11T22:30:16.048Z","avatar_url":"https://github.com/neuronsimulator.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Using CoreNEURON with NEURON\n\n## Introduction\n\nThis tutorial shows how to build a simple network model using [NEURON](https://www.neuron.yale.edu/neuron/) and simulating it using [CoreNEURON](https://github.com/BlueBrain/CoreNeuron).\n\n## Installation\n\nFor up to date NEURON installation instructions with CoreNEURON, see [documentation here](https://github.com/neuronsimulator/nrn/blob/master/docs/coreneuron/installation.rst). As CoreNEURON rely on auto-vectorisation compiler, make sure to use vendor compilers like Intel, Cray, AMD, NVIDIA HPC SDK.\n\nOnce NEURON is installed, and you set `PATH` and `PYTHONPATH` environmental variables then you should be able to do:\n\n```\npython -c \"from neuron import h; from neuron import coreneuron\"\n```\n\nIf you get `ImportError` then make sure `PYTHONPATH` is set up correctly and `python` version is same as the one used for NEURON installation.\n\n## Compile MOD files\n\nNow we will start building the `ringtest` model. Clone the GitHub repository as:\n\n```bash\ngit clone https://github.com/nrnhines/ringtest.git\ncd ringtest\n```\n\nThis repository contains a `mod` sub-directory which has MOD files (for the gap-junction related test). Using the standard NEURON workflow, we can build a `special` executable using `nrnivmodl` and `-coreneuron` option. Make sure to load necessary compiler and MPI modules:\n\n```bash\nnrnivmodl -coreneuron mod\n```\n\nThis will create `x86_64/special` executable in the `ringtest` directory (where `x86_64` is platform architecture).\n\n\n## Make Model CoreNEURON Compatible\n\nAs described in the [documentation here](https://github.com/neuronsimulator/nrn/blob/master/docs/coreneuron/how-to/coreneuron.md), one may have to make minor modifications to make a model compatible with CoreNEURON.\nIn `ringtest.py`, the relevant changes have already been made:\n```python\nh.cvode.cache_efficient(1)\nif use_coreneuron:\n    from neuron import coreneuron\n    coreneuron.enable = True\n    coreneuron.gpu = coreneuron_gpu\n```\nso the `-coreneuron` (`use_coreneuron`) and `-gpu` (`coreneuron_gpu`) arguments can be used to enable CoreNEURON.\n\nBy using `coreneuron` module, one can enable CoreNEURON as shown above. Note that CoreNEURON requires NEURON's internal data structures to be in cache efficient form and hence the `cvode.cache_efficient(1)` method must be executed prior to initialization of the model i.e. `h.stdinit()`.\n\n## Running Simulation\n\nWe are ready to run this model using NEURON or CoreNEURON. To run with NEURON, you can do:\n\n```bash\nmpiexec -n 2 ./x86_64/special -mpi -python ringtest.py -tstop 100\n```\n\nThis will run NEURON for `100 milliseconds` using 2 MPI processes and writes spike output to the `spk2.std` file. These are standard steps for running simulations with NEURON (which you are already familiar with).\n\nNote that `ringtest.py` has a `prun` method which internally calls ` pc.psolve(tstop)`. If `coreneuron.enable` is set to `True` then NEURON will internally use CoreNEURON to simulate the model. We can now use `-coreneuron` CLI parameter to run the model using CoreNEURON as:\n\n```bash\nmpiexec -n 2 ./x86_64/special -mpi -python ringtest.py -tstop 100 -coreneuron\n```\n\nThis will run simulation using CoreNEURON for `100 milliseconds` and writes spike output to the `spk2.std` file. If you compare the spikes generated by NEURON run and CoreNEURON run then should be identical. Make sure to sort spikes using `sortspike` command provided by NEURON:\n\n```\nsortspike spk2.std spk2.coreneuron.std\n```\n\n#### Running on GPUs\n\nIf you have compiled NEURON+CoreNEURON with GPU support, you can run the model on GPU using `-gpu` CLI option:\n\n```bash\nmpiexec -n 2 ./x86_64/special -mpi -python ringtest.py -tstop 100 -coreneuron -gpu\n```\n\nWe typically use the number of MPI ranks per node equal to the number of GPUs per node. So, if you have `X` number of nodes where each node has `Y` GPUs then the total number of MPI ranks are `X x Y`.\n\n#### Using Threads\n\nNEURON uses `PThread` to support threading whereas CoreNEURON uses OpenMP. In order to enable thread usage you have to set appropriate number of threads using [ParallelContext.nthread()](https://www.neuron.yale.edu/neuron/static/py_doc/modelspec/programmatic/network/parcon.html#ParallelContext.nthread). With this, if you run simulation using CoreNEURON, for each thread on NEURON side CoreNEURON will create an equivalent OpenMP thread. With this ring test we have CLI option `-nt` that you can use to enable threads:\n\n```bash\nmpiexec -n 2 ./x86_64/special -mpi -python ringtest.py -tstop 100 -coreneuron -nt 2\n```\n\nWith `-nt 2`, each MPI process will start 2 OpenMP threads on CoreNEURON side for simulation.\n\n\n## Performance Benchmarking\n\nHere are some additional points if you want to compare performance between NEURON and CoreNEURON :\n\n* Make sure to use optimization flags depending upon your compiler suite (see [CoreNEURON page](https://github.com/BlueBrain/CoreNeuron))\n* Prefer Intel/Cray/PGI compilers over GCC and Clang (specifically for CoreNEURON to enable vectorisation)\n* In order to compare performance, your model should be sufficiently large (and not a trivial test). For example, in the above tutorial, we built a small network with 16 rings each with 8 cells. You can build a larger network using additional command line arguments as:\n\n```bash\nmpirun -n 4 ./x86_64/special -mpi -python ringtest.py -tstop 100 -nring 1024 -ncell 128 -branch 32 64\n```\n\nSee command line arguments for more information about arguments:\n\n```bash\n→ python ringtest.py -h\nusage: ringtest.py [-h] [-nring N] [-ncell N] [-npt N] [-branch N N]\n                   [-compart N N] [-tstop float] [-gran N] [-rparm]\n                   [-filemode] [-gpu] [-show] [-gap] [-coreneuron] [-nt N]\n                   [-multisplit]\n\noptional arguments:\n  -h, --help    show this help message and exit\n  -nring N      number of rings (default 16)\n  -ncell N      number of cells per ring (default 8)\n  -npt N        number of cells per type (default 8)\n  -branch N N   range of branches per cell (default 10 20)\n  -compart N N  range of compartments per branch (default [1,1])\n  -tstop float  stop time (ms) (default 100.0)\n  -gran N       global Random123 index (default 0)\n  -rparm        randomize parameters\n  -filemode     Run CoreNEURON with file mode\n  -gpu          Run CoreNEURON on GPU\n  -show         show type topologies\n  -gap          use gap junctions\n  -coreneuron   run coreneuron\n  -nt N         nthread\n  -multisplit   intra-rank thread balance. All pieces of cell on same rank.\n```\n\n##### Sample Performance Test\n\nIn order to compare the performance of NEURON and CoreNEURON, we compiled both simulators using Intel compilers. Note that the ringtest is not ideal for benchmarking due to low comutational complexity of each cell (`cell.hoc` uses `HH` channel in soma compartment).\n\n**NOTE** : When you run simulation using NEURON and call `pc.psolve(tstop)`, it will directly start execution of timesteps. But in case of CoreNEURON, when you call `pc.psolve(tstop)`, NEURON will internally do the following steps:\n\n1. Copy in-memory model to CoreNEURON\n2. CoreNEURON will copy data to GPU if GPU is enabled\n3. CoreNEURON will run timesteps\n4. CoreNEURON will copy back results from CPU to GPU if GPU is enabled\n5. NEURON will copy results back from CoreNEURON\n\nThese steps are typically fast but if you are running a very small model for short duration then you might see an overhead. So make sure to check timing stats printed by CoreNEURON. For example, CoreNEURON prints simulation time (i.e. Step 3) in the form of `Solver Time : X Seconds`.\n\nFor comparison of NEURON and CoreNEURON performance, here are some executions with NEURON and CoreNEURON running on single core:\n\n```bash\n# NEURON CPU Run\n$ mpiexec -n 1 ./x86_64/special -mpi -python ringtest.py -tstop 10 -nring 128 -ncell 128 -branch 32 64\n.........\nruntime=20.86  load_balance=100.0%  avg_comp_time=20.8548\n.......\n\n# CoreNEURON CPU Run\n$ mpiexec -n 1 ./x86_64/special -mpi -python ringtest.py -tstop 10 -nring 128 -ncell 128 -branch 32 64 -coreneuron\n.........\nSolver Time : 15.846\n.........\n\n# CoreNEURON GPU Run\n$ mpiexec -n 1 ./x86_64/special -mpi -python ringtest.py -tstop 10 -nring 128 -ncell 128 -branch 32 64 -coreneuron -gpu\n..........\nSolver Time : 0.431226\n..........\n```\n\nFor above test the execution time is reduced from 174sec to 78sec for CPU and to 22.7sec for GPU. This speedup is still less than expected due to lower computational complexity of the model. But also note that we are running CPU execution with single core. Make sure to use all CPU resources for actual comparison. Try with your model and if you see any performance issues, please open an issue on [NEURON GitHub repository](https://github.com/neuronsimulator/nrn/issues/new).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuronsimulator%2Fringtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneuronsimulator%2Fringtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuronsimulator%2Fringtest/lists"}