Merge pull request #188 from NeuroML/main

Copy main to master branch

.github/workflows/prs.yaml

@@ -16,9 +16,10 @@ jobs:
       with:
         python-version: 3.9
     - name: Set up JDK 11 for jNeuroML etc
-      uses: actions/setup-java@v1
+      uses: actions/setup-java@v3
       with:
         java-version: 11
+        distribution: 'temurin'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/publish.yml

@@ -2,7 +2,7 @@ name: Publish
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
 
 jobs:
   build:
@@ -16,9 +16,10 @@ jobs:
       with:
         python-version: 3.9
     - name: Set up JDK 11 for jNeuroML etc
-      uses: actions/setup-java@v1
+      uses: actions/setup-java@v3
       with:
         java-version: 11
+        distribution: 'temurin'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.gitignore

@@ -29,3 +29,31 @@ NT_*/
 /source/Userdocs/NML2_examples/LEMS_Test_SKv3_1.xml
 /source/Userdocs/NML2_examples/LEMS_iv_complex_cell.xml
 arm64
+/source/Userdocs/NML2_examples/Ca.channel.nml
+/source/Userdocs/NML2_examples/CaDynamics_E2_NML2.nml
+/source/Userdocs/NML2_examples/Ca_LVAst.channel.nml
+/source/Userdocs/NML2_examples/Exc.spikes
+/source/Userdocs/NML2_examples/Ih.channel.nml
+/source/Userdocs/NML2_examples/Im.channel.nml
+/source/Userdocs/NML2_examples/Inh.spikes
+/source/Userdocs/NML2_examples/K_Pst.channel.nml
+/source/Userdocs/NML2_examples/K_Tst.channel.nml
+/source/Userdocs/NML2_examples/LEMS_NML_DB_network_sim.xml
+/source/Userdocs/NML2_examples/LEMS_iv_bAC217_L23_MC_40be3bf0e8_0_0.xml
+/source/Userdocs/NML2_examples/LEMS_iv_novel_cell.xml
+/source/Userdocs/NML2_examples/NMLCH000015.channel.nml
+/source/Userdocs/NML2_examples/NMLCL000109.nml.zip
+/source/Userdocs/NML2_examples/NML_DB_Net.gv.png
+/source/Userdocs/NML2_examples/NML_DB_network.net.nml
+/source/Userdocs/NML2_examples/NaTa_t.channel.nml
+/source/Userdocs/NML2_examples/NaTs2_t.channel.nml
+/source/Userdocs/NML2_examples/Nap_Et2.channel.nml
+/source/Userdocs/NML2_examples/SK_E2.channel.nml
+/source/Userdocs/NML2_examples/SKv3_1.channel.nml
+/source/Userdocs/NML2_examples/TestCell.cell.nml
+/source/Userdocs/NML2_examples/bAC217_L23_MC_40be3bf0e8_0_0.cell.nml
+/source/Userdocs/NML2_examples/bAC217_L23_MC_40be3bf0e8_0_0.hoc
+/source/Userdocs/NML2_examples/iv_bAC217_L23_MC_40be3bf0e8_0_0.net.nml
+/source/Userdocs/NML2_examples/iv_novel_cell.net.nml
+/source/Userdocs/NML2_examples/novel_cell.hoc
+/source/Userdocs/NML2_examples/pas.channel.nml

scripts/schemas/generate-jupyter-ast.py

@@ -634,6 +634,7 @@ def main(srcdir, destdir):
 
 
 if __name__ == "__main__":
-    src = "/home/asinha/Documents/02_Code/00_mine/NeuroML/software/NeuroML2/"
+    # src = "/home/asinha/Documents/02_Code/00_mine/NeuroML/software/NeuroML2/"
+    src = None
     destdir = "../../source/Userdocs/Schemas/"
     main(src, destdir)

scripts/schemas/requirements.txt

@@ -0,0 +1,2 @@
+libneuroml
+pylems

source/Devdocs/ReleaseProcess.md

@@ -31,11 +31,11 @@ These are the steps required for a new release of the NeuroML development tools.
 | Rebuild jNeuroML & commit to [jNeuroMLJar](https://sourceforge.net/p/neuroml/code/HEAD/tree/jNeuroMLJar/) and use latest for [jNeuroML for OMV](https://github.com/OpenSourceBrain/osb-model-validation/blob/master/omv/engines/getjnml.py#L8) | v2.3 |
 | Add new binary release on [https://github.com/NeuroML/jNeuroML/releases](https://github.com/NeuroML/jNeuroML/releases) | v2.3 |
 | Update version used in [neuroConstruct](https://github.com/NeuralEnsemble/neuroConstruct) | v2.3 |
-| Update docs on [http://www.neuroml.org](https://www.neuroml.org) | v2.2 |
+| Update docs on [http://docs.neuroml.org](https://docs.neuroml.org) | v2.3 |
 | Update version on [COMBINE website](https://github.com/combine-org/combine-org.github.io/blob/master/content/authors/NeuroML/_index.md) | v2.2 |
 | ANNOUNCE (mailing list, Twitter) | v2.2 |
-| Increment version numbers in all development branches | v2.1 |
-| DOI on [Zenodo](https://doi.org/10.5281/zenodo.4627568) | v2.1 |
+| Increment version numbers in all development branches | v2.3 |
+| DOI on [Zenodo](https://doi.org/10.5281/zenodo.593108) | v2.3 |
 | Update NeuroML [milestones](https://github.com/NeuroML/NeuroML2/milestones) | v2.2 |
-| New release of neuroConstruct | v2.0 |
+| New release of [neuroConstruct](https://github.com/NeuralEnsemble/neuroConstruct/releases) | v2.3 |
 | Test toolchain on Windows... | v2.0 |

source/NeuroMLOrg/CommunicationChannels.md

@@ -6,17 +6,17 @@ We're happy to talk with users, developers and modellers about using NeuroML in
 (contact:ml)=
 ## Mailing list
 
-For general discussion, queries, and troubleshooting related to NeuroML please use the mailing list: [https://lists.sourceforge.net/lists/listinfo/neuroml-technology](https://lists.sourceforge.net/lists/listinfo/neuroml-technology).
+For announcements, general discussion, queries, and troubleshooting related to NeuroML please use the mailing list: [https://lists.sourceforge.net/lists/listinfo/neuroml-technology](https://lists.sourceforge.net/lists/listinfo/neuroml-technology).
 
 (contact:chat)=
 ## Chat channels
 
-Chat channels for quick queries are also available on:
+A Gitter/Matrix chat channels for queries are also available.
+One can access it either via Gitter or Matrix/Element.
 
 - [Gitter](https://gitter.im/NeuroML/community)
 - [Matrix/Element](https://matrix.to/#/!EQLdKYsJxEfGHAybdP:gitter.im?via=gitter.im&via=matrix.org)
 
-The two rooms are bridged, so you can use either.
 Please note that activity in these rooms depends on time zones and the availability of community members.
 So, if you do not get a response soon, please post to the mailing list listed above or file an issue on GitHub as noted below.
 

source/Userdocs/GettingStarted.md

@@ -2,12 +2,28 @@
 # Getting started with NeuroML
 
 The best way to understand NeuroML is to work through NeuroML examples to see how they are constructed and what they can do.
-In this chapter, we will step through increasingly complex models to see how they are written and simulated using NeuroML.
+We present below a set of step-by-step guides to illustrate how models are written and simulated using NeuroML.
 
-To stress that **Python** is the suggested language for developing, simulating, and analysing NeuroML models, we will limit ourselves to the Python NeuroML tools only: {ref}`libNeuroML <libNeuroML>` and {ref}`pyNeuroML <pyNeuroML>`.
-You can learn more about the different NeuroML tools in their {ref}`specific sections <userdocs:software>`.
+<table>
+<tr>
+<td><a href="https://docs.neuroml.org/Userdocs/NML2_examples/SingleNeuron.html"><img src="../_images/example-single-izhikevich2007cell-sim-v.png" height=150 title="Guide 1"/></a>&nbsp;&nbsp;</td>
+<td><a href="https://docs.neuroml.org/Userdocs/IzhikevichNetworkExample.html"><img src="../_images/example_izhikevich2007network_sim-spikes.png" height=150 title="Guide 2"/></a>&nbsp;&nbsp;</td>
+<td><a href="https://docs.neuroml.org/Userdocs/SingleCompartmentHHExample.html"><img src="../_images/HH_single_compartment_example_sim-v.png" height=150 title="Guide 3"/></a>&nbsp;&nbsp;</td>
+<td><a href="https://docs.neuroml.org/Userdocs/MultiCompartmentOLMexample.html"><img src="../_images/olm.cell.xy.png" height=150 title="Guide 4"/></a>&nbsp;&nbsp;</td>
+</tr>
+</table>
 
-You do not need to install any software on your computers to run the example code included in this chapter.
-Each example is followed by a [Jupyter notebook](https://jupyter.org/index.html) for you to experiment with.
-These can be run using the "launch" button in the top right hand corner.
-Please proceed to the first example section using the navigation button on the right below.
+
+| Link to guide    | Description | Model life cycle stages |
+| :------ | ----------- | ----------------------- |
+| [Guide 1](https://docs.neuroml.org/Userdocs/NML2_examples/SingleNeuron.html) | Create and simulate a simple regular spiking Izhikevich neuron in NeuroML | Create, Validate, Simulate |
+| [Guide 2](https://docs.neuroml.org/Userdocs/IzhikevichNetworkExample.html) | Create a network of two synaptically connected populations of Izhikevich neurons  | Create, Validate, Visualise, Simulate |
+| [Guide 3](https://docs.neuroml.org/Userdocs/SingleCompartmentHHExample.html) | Build and simulate a single compartment Hodgkin-Huxley neuron | Create, Validate, Visualise, Simulate |
+| [Guide 4](https://docs.neuroml.org/Userdocs/MultiCompartmentOLMexample.html) | Create and simulate a multi compartment hippocampal OLM neuron | Create, Validate, Visualise, Simulate |
+| [Guide 5](https://docs.neuroml.org/Userdocs/OptimisingNeuroMLModels) | Optimise/fit NeuroML models to experimental data | Create, Validate, Simulate, Fit |
+| [Guide 6](https://docs.neuroml.org/Userdocs/CreatingNeuroMLModels.html\#converting-cell-models-to-neuroml-and-sharing-them-on-open-source-brain) | Guide to converting cell models to NeuroML and sharing them on Open Source Brain | Create, Validate, Simulate, Share |
+| [Guide 7](https://docs.neuroml.org/Userdocs/NML2_examples/NeuroML-DB.html) | Create novel NeuroML models from components on NeuroML-DB | Reuse, Create, Validate, Simulate |
+| [Guide 8](https://docs.neuroml.org/Userdocs/ExtendingNeuroMLv2.html\#example-lorenz-model-for-cellular-convection) | Extend NeuroML by creating a novel model type in LEMS  | Create, Simulate |
+
+
+You do not need to install any software on your computers to run many of the examples above. These examples are followed by a [Jupyter notebook](https://jupyter.org/index.html) for you to experiment with inside your browser ({ref}`more info <userdocs:usage:jupyterbooks>`).

source/Userdocs/HDF5.md

@@ -0,0 +1,24 @@
+(userdocs:hdf5)=
+# HDF5 support
+
+The XML serializations of large NeuroML models can be prohibitive to store.
+For such cases, NeuroML also includes support for saving models in the binary [HDF5](https://www.hdfgroup.org/solutions/hdf5) format via the [NeuroMLHdf5Writer in libNeuroML](https://libneuroml.readthedocs.io/en/stable/userdocs/writers.html#neuroml.writers.NeuroMLHdf5Writer). The same format can be exported also from the Java API ([example](https://github.com/NeuroML/org.neuroml.model/blob/master/src/test/java/org/neuroml/model/test/HDF5Test.java)).
+
+The format of the export is documented below:
+
+
+- {ref}`Network <schema:network>` is exported as a `network` HDF5 group with `id`, `notes`, and the `temperature` (optional) stored as attributes.
+- {ref}`Population <schema:population>` is exported as a group with id `population_<id of the population>` with `id`, `component`, `size`, `type`, and `property` tags stored as attributes.
+  - If the population is a {ref}`population list <schema:populationlist>` that includes {ref}`instances <schema:instance>` of cells, the locations of cells (x, y, z), these are stored in a 3 column table ("chunked array") with a row per instance.
+
+- {ref}`Projection <schema:projection>` is exported as a group with id `project_<id of the projection>` with `id`, `type`, `presynapticPopulation`, `postSynapticPopulation`, `synapse` as attributes.
+  - {ref}`Connection <schema:connection>` and {ref}`ConnectionWD <schema:connectionwd>` elements in projections are stored as rows in a table with the first two columns as the `pre_cell_id` and `post_cell_id` respectively, and the successive columns for the necessary attributes.
+
+- {ref}`ElectricalProjection <schema:electricalprojection>` is exported similar to Projection with the {ref}`ElectricalConnection <schema:electricalconnection>`, {ref}`ElectricalConnectionInstance <schema:electricalconnectioninstance>`, and {ref}`ElectricalConnectionInstanceW <schema:electricalconnectioninstancew>` entries stored in tables.
+- {ref}`ContinuousProjection <schema:continuousprojection>` is exported similar to Projection with the {ref}`ContinuousConnection <schema:continuousconnection>`, {ref}`ContinuousConnectionInstance <schema:continuousconnectioninstance>`, and {ref}`ContinuousConnectionInstanceW <schema:continuousconnectioninstancew>` entries stored in tables.
+- {ref}`InputList <schema:inputlist>` is exported similar to Projection with the {ref}`Input <schema:input>`, and {ref}`InputW <schema:inputw>` entries stored in tables.
+
+
+For more details, the source code of these export functions can be seen [here in the libNeuroML repository](https://github.com/NeuralEnsemble/libNeuroML/blob/2d8112178d8d82b07a20f8395ec22a23a6323a6c/neuroml/nml/helper_methods.py#L2548) and [here in org.neuroml.model](https://github.com/NeuroML/org.neuroml.model/blob/master/src/main/java/org/neuroml/model/util/hdf5/NeuroMLHDF5Writer.java).
+
+HDF5 NeuroML files can be read and processed by `jnml` and `pynml` in the same way as XML files (see [here](https://github.com/OpenSourceBrain/OpenCortex/tree/master/examples/HDF5) for LEMS Simulation file examples which reference HDF5 NeuroML models).

source/Userdocs/NML2_examples/HH_example_k_channel.nml

@@ -2,7 +2,7 @@
     <notes>k channel for HH neuron</notes>
     <ionChannelHH id="k_channel" species="k" conductance="10pS">
         <notes>Potassium channel for HH cell</notes>
-        <gateHHrates id="k_n" instances="4">
+        <gateHHrates id="n" instances="4">
             <notes>n gate for k channel</notes>
             <forwardRate type="HHExpLinearRate" rate="0.1per_ms" midpoint="-55mV" scale="10mV"/>
             <reverseRate type="HHExpRate" rate="0.125per_ms" midpoint="-65mV" scale="-80mV"/>

source/Userdocs/NML2_examples/HH_example_na_channel.nml

@@ -2,12 +2,12 @@
     <notes>Na channel for HH neuron</notes>
     <ionChannelHH id="na_channel" species="na" conductance="10pS">
         <notes>Sodium channel for HH cell</notes>
-        <gateHHrates id="na_m" instances="3">
+        <gateHHrates id="m" instances="3">
             <notes>m gate for na channel</notes>
             <forwardRate type="HHExpLinearRate" rate="1per_ms" midpoint="-40mV" scale="10mV"/>
             <reverseRate type="HHExpRate" rate="4per_ms" midpoint="-65mV" scale="-18mV"/>
         </gateHHrates>
-        <gateHHrates id="na_h" instances="1">
+        <gateHHrates id="h" instances="1">
             <notes>h gate for na channel</notes>
             <forwardRate type="HHExpRate" rate="0.07per_ms" midpoint="-65mV" scale="-20mV"/>
             <reverseRate type="HHSigmoidRate" rate="1per_ms" midpoint="-35mV" scale="10mV"/>

source/Userdocs/NML2_examples/HH_single_compartment.ipynb

@@ -72,15 +72,15 @@
     "    returns: name of the created file\n",
     "    \"\"\"\n",
     "    na_channel = IonChannelHH(id=\"na_channel\", notes=\"Sodium channel for HH cell\", conductance=\"10pS\", species=\"na\")\n",
-    "    gate_m = GateHHRates(id=\"na_m\", instances=\"3\", notes=\"m gate for na channel\")\n",
+    "    gate_m = GateHHRates(id=\"m\", instances=\"3\", notes=\"m gate for na channel\")\n",
     "\n",
     "    m_forward_rate = HHRate(type=\"HHExpLinearRate\", rate=\"1per_ms\", midpoint=\"-40mV\", scale=\"10mV\")\n",
     "    m_reverse_rate = HHRate(type=\"HHExpRate\", rate=\"4per_ms\", midpoint=\"-65mV\", scale=\"-18mV\")\n",
     "    gate_m.forward_rate = m_forward_rate\n",
     "    gate_m.reverse_rate = m_reverse_rate\n",
     "    na_channel.gate_hh_rates.append(gate_m)\n",
     "\n",
-    "    gate_h = GateHHRates(id=\"na_h\", instances=\"1\", notes=\"h gate for na channel\")\n",
+    "    gate_h = GateHHRates(id=\"h\", instances=\"1\", notes=\"h gate for na channel\")\n",
     "    h_forward_rate = HHRate(type=\"HHExpRate\", rate=\"0.07per_ms\", midpoint=\"-65mV\", scale=\"-20mV\")\n",
     "    h_reverse_rate = HHRate(type=\"HHSigmoidRate\", rate=\"1per_ms\", midpoint=\"-35mV\", scale=\"10mV\")\n",
     "    gate_h.forward_rate = h_forward_rate\n",
@@ -111,7 +111,7 @@
     "    :returns: name of the K channel file\n",
     "    \"\"\"\n",
     "    k_channel = IonChannelHH(id=\"k_channel\", notes=\"Potassium channel for HH cell\", conductance=\"10pS\", species=\"k\")\n",
-    "    gate_n = GateHHRates(id=\"k_n\", instances=\"4\", notes=\"n gate for k channel\")\n",
+    "    gate_n = GateHHRates(id=\"n\", instances=\"4\", notes=\"n gate for k channel\")\n",
     "    n_forward_rate = HHRate(type=\"HHExpLinearRate\", rate=\"0.1per_ms\", midpoint=\"-55mV\", scale=\"10mV\")\n",
     "    n_reverse_rate = HHRate(type=\"HHExpRate\", rate=\"0.125per_ms\", midpoint=\"-65mV\", scale=\"-80mV\")\n",
     "    gate_n.forward_rate = n_forward_rate\n",

source/Userdocs/NML2_examples/IzhikevichNetwork.ipynb

@@ -907,7 +907,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.7"
+   "version": "3.9.16"
   }
  },
  "nbformat": 4,

source/Userdocs/NML2_examples/LEMS_HH_single_compartment_example_sim.xml

@@ -1,34 +1,33 @@
 <Lems>
-    
+
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v1.1.1 (libNeuroML v0.5.5)
+        This LEMS file has been automatically generated using PyNeuroML v1.1.10 (libNeuroML v0.5.8)
 
      -->
-    
+
     <!-- Specify which component to run -->
     <Target component="HH_single_compartment_example_sim"/>
 
     <!-- Include core NeuroML2 ComponentType definitions -->
     <Include file="Cells.xml"/>
     <Include file="Networks.xml"/>
     <Include file="Simulation.xml"/>
-    
+
     <Include file="HH_example_net.nml"/>
     <Include file="HH_example_cell.nml"/>
     <Include file="HH_example_na_channel.nml"/>
     <Include file="HH_example_k_channel.nml"/>
     <Include file="HH_example_leak_channel.nml"/>
-   
+
     <Simulation id="HH_single_compartment_example_sim" length="300ms" step="0.01ms" target="single_hh_cell_network" seed="123">  <!-- Note seed: ensures same random numbers used every run -->
-
         <OutputFile id="output0" fileName="HH_single_compartment_example_sim.dat">
-            <OutputColumn id="pop0[0]/v" quantity="pop0[0]/v"/> 
-            <OutputColumn id="pop0[0]/iChannels" quantity="pop0[0]/iChannels"/> 
-            <OutputColumn id="pop0[0]/na/iDensity" quantity="pop0[0]/hh_b_prop/membraneProperties/na_channels/iDensity/"/> 
-            <OutputColumn id="pop0[0]/k/iDensity" quantity="pop0[0]/hh_b_prop/membraneProperties/k_channels/iDensity/"/> 
+            <OutputColumn id="pop0[0]/v" quantity="pop0[0]/v"/>
+            <OutputColumn id="pop0[0]/iChannels" quantity="pop0[0]/iChannels"/>
+            <OutputColumn id="pop0[0]/na/iDensity" quantity="pop0[0]/hh_b_prop/membraneProperties/na_channels/iDensity/"/>
+            <OutputColumn id="pop0[0]/k/iDensity" quantity="pop0[0]/hh_b_prop/membraneProperties/k_channels/iDensity/"/>
         </OutputFile>
-        
+
     </Simulation>
 
 </Lems>

source/Userdocs/NML2_examples/LEMS_example-single-izhikevich2007cell-sim.xml

@@ -1,27 +1,26 @@
 <Lems>
-    
+
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v1.1.1 (libNeuroML v0.5.5)
+        This LEMS file has been automatically generated using PyNeuroML v1.1.10 (libNeuroML v0.5.8)
 
      -->
-    
+
     <!-- Specify which component to run -->
     <Target component="example-single-izhikevich2007cell-sim"/>
 
     <!-- Include core NeuroML2 ComponentType definitions -->
     <Include file="Cells.xml"/>
     <Include file="Networks.xml"/>
     <Include file="Simulation.xml"/>
-    
+
     <Include file="izhikevich2007_single_cell_network.nml"/>
-   
+
     <Simulation id="example-single-izhikevich2007cell-sim" length="1000ms" step="0.1ms" target="IzNet" seed="123">  <!-- Note seed: ensures same random numbers used every run -->
-
         <OutputFile id="output0" fileName="example-single-izhikevich2007cell-sim.v.dat">
-            <OutputColumn id="IzhPop0[0]" quantity="IzhPop0[0]/v"/> 
+            <OutputColumn id="IzhPop0[0]" quantity="IzhPop0[0]/v"/>
         </OutputFile>
-        
+
     </Simulation>
 
 </Lems>