lems / jlems Goto Github PK

Java Interpreter for the Low Entropy Model Specification language

Home Page: https://docs.neuroml.org/Userdocs/Software/jLEMS.html

License: MIT License

Shell 0.01% Java 70.17% XSLT 4.70% CSS 0.18% Batchfile 0.01% HTML 24.92%

jlems's Introduction

LEMS

The Low Entropy Model Specification language. This repository contains the Schema for the language, some examples and code for generating the documentation.

LEMS Documentation

See http://lems.github.io/LEMS

For more details on LEMS see:

Robert C. Cannon, Padraig Gleeson, Sharon Crook, Gautham Ganapathy, Boris Marin, Eugenio Piasini and R. Angus Silver, LEMS: A language for expressing complex biological models in concise and hierarchical form and its use in underpinning NeuroML 2, Frontiers in Neuroinformatics 2014, doi: 10.3389/fninf.2014.00079

Java based LEMS interpreter/simulator

jLEMS (see also here).

jLEMS can be used to parse and execute any LEMS model. For an application which adds NeuroML 2 ComponentType definitions and various options for importing & exporting LEMS to other formats, see jNeuroML.

Python based LEMS interpreter/simulator

PyLEMS (see also here).

This code is distributed under the terms of the GNU General Public License v3.

jlems's People

Contributors

Stargazers

Watchers

Forkers

pgleeson finnk ragna-s snigdhad hugh-osborne lungd tarelli sanjayankur31 bulksecuritygeneratorprojectv2

jlems's Issues

jLEMS doesn't like unprettified LEMS code

See NeuroML/jNeuroML#2

Rewrite matches expected test error

@pgleeson the API branch (I brought in the changes from api_merged) is failing to build. The testReadFromString test in XMLExamplesReaderTest is failing when testing the file input.xml
XMLExamplesReaderTest.testReadFromString:56 Rewrite matches expected:<12111> but was:<12057>

I'm commenting this test in the api branch for now until we fix it.

Time resolution for condition testing

Checking a condition (OnCondition element in dynamics) at the end of a step is a bit inaccurate (see bounce example without zeroing the height for a serious failure). Integrators should at least interpolate, and maybe solve for the exact time when the condition is passed.

Create URLInclusionReader

The different include can be specified as URLs, in that case FileInclusionReader wouldn't work.

vfgen xml generation

VectorFieldGENerator http://www.warrenweckesser.net/vfgen/index.html
automatically generates code for many differential equation solvers and analysis tools (including xpp, matlab, lsoda) from a xml description of the dynamics. It would be very convenient translating preparsed flattened LEMS to vfgen, instead of having to rewrite exporters for all those formats.

Bóris

Legend for GUI frame

A legend should be added to the plot frame showing what's plotted against each colour trace.

This could be as a tooltip when the mouse floats over the graph or as a menu option with a popup dialog

Super in Dynamics breaks reserialization.

On resolving dynamics with a <Super/> element, the contents of the supertype dynamics are copied.
Serializing the component type then writes them out in full so it is different from the original.

Checking for missing attributes

jLEMS should be stricter on missing attributes that would default to 0 otherwise.

Allow jLEMS to include files specified for inclusion in a NeuroML file

Have jlems parse & handle <include href=...> statements like these:
https://github.com/OpenSourceBrain/GranuleCell/blob/13156c204dc0835d873e1e27881b94d4cf32b81d/neuroConstruct/generatedNeuroML2/GranuleCell.net.nml

instead of requiring repetition of all the includes in the LEMS file (using <Include file="...") like here:

https://github.com/OpenSourceBrain/GranuleCell/blob/13156c204dc0835d873e1e27881b94d4cf32b81d/neuroConstruct/generatedNeuroML2/LEMS_GranuleCell.xml

How to get the unit of a quantity?

Given the targetComponent and a quantity, say "hhpop[0]/v" what is the best way to get what is the unit of v?

Include inside comments are still read

An Include element inside an XML comment in a Lems file is still read in & processed, e.g.

    <!-- Including file with a <neuroml> root, a "real" NeuroML 2 file 
    <Include file="NML2_SingleCompHHCell.nml"/>-->

Correct framing of GUI

Framing of the plot against the labelled axed needs to be fixed. When the gui opens initially the lines on the plot (corresponding to the real plotted values) are out of alignment with the axis labels:

Also, when the window is resized, the plot area should ideally resize also:

Deprecate <Link>

<Link> has been marked as a candidate for deprecation (#55). It is used in NeuroML2, though.

Second test issue

And another one.

Remove ComponentReference

After discussions at UCL with @robertcannon, we have decided that ComponentReferences are just adding entropy to LEMS, since all the cases where they are used can be straightforwardly implemented using Child(ren)s. Relates to #32.

exceptions from conditions with .and.

Eg (t .gt. a .and. t .lt. b) - needs examples and tests.

Move to use Maven?

It would be nice if jLEMS used maven for the build so we could easily integrate it with all the other maven projects we have. I could help setting this up.

Replace class ComponentBehavior with ComponentDynamics for a more consistent underlying API?

Not urgent, but I assume somebody sometime might want to develop on top of the source classes?

Support for resetting a parameter value of a component on instantiating a new child

This will be needed in various scenarios:

Changing vshift in a channel prototype when instantiated as part of a channelDensity
Setting x, y, z location of cell when instantiating a list of positioned cells
Setting v0 in a cell instance

Robert currently working on underlying issues relating to this...

Outline structure of modularised jLEMS

Ideas for modularising jLEMS

These modules will make it easier to replace core implementations of jLEMS (e.g jLEMS or jLEMSDev) and abstract out the interaction with LEMS models by other Java applications.

API to model

Being worked on here:
Related to #51

API to run time

Could be based on implementation of api here: https://github.com/LEMS/jLEMS/tree/development/src/main/java/org/lemsml/jlems/api

Check if overridden/extended component type in new Component actually exists

For example some Lems files ran fine with:
<abstractCell id="hhcell" type="pointCellCondBased" ...> even though abstractCell didn't exist (was renamed baseCell)
e.g. https://github.com/NeuroML/NeuroML2/blob/0c468a12d52e06b8c779bcb2d53ee280d02a768f/NeuroML2CoreTypes/LEMS_NML2_Ex1_HH.xml#L53

Would be good to catch such errors for completeness

Add -include command line option

Add an option to specify a folder with xml files which can be included in the main model file, e.g.

./lems -include ../NeuroML2/NeuroML2CoreTypes examples/LEMS_NML2_Ex0_IaF.xml

Robert, assign this to me if you're happy with this change

Implement independent model parsing API for LEMS

To be used by jLEMS & jLEMSDev, see #52

Initial work on this by @robertcannon here: https://github.com/robertcannon/jLEMSDev/tree/721713d26ceffaf48918349783a4cc635beba9f5/src/org/lemsml/jlems/core/api

Also interesting to investigate for defining a grammar for LEMS & automating some generation of the API: http://javadude.com/tools/antxr/

Tests for component flattening

Need tests for the three ways of running a model: plain tree, flattened component behavior, and flattened components.

Discrete dynamics

Robert and I have discussed the possibility of supporting systems defined in terms of maps instead of odes. We ended up considering an StateUpdate element. For example, take the Logistic map: x_{n+1} = mu * x_n * (1 - x_n) where mu is a parameter. The dynamics would be defined as something like this:

<Dynamics>
        <StateVariable name="x" dimension="none" exposure="x"/>
        <StateUpdate variable="x" value="mu * x * (1 - x)"/>
</Dynamics>

There are several discrete time (a.k.a maps) neuronal models:
http://www.sciencedirect.com/science/article/pii/S0370157310003224

MathML support

There is some preliminary support for exporting expressions to MathML from ParseTrees, but this is not yet complete.

Will be needed for conversion to SBML & others...

Discussion list

Not specifically a jLEMS thing, but we could do with one along the lines of openworm-discuss. Probably the same one for jLEMS and pyLEMS.

Flattener does not handle DerivedParameter or ConditionalDerivedVariable

Both elements are missing from https://github.com/LEMS/jLEMS/blob/master/src/main/java/org/lemsml/jlems/core/flatten/ComponentFlattener.java, and lead to errors when some NeuroML2 comp types are flattened.

@robertcannon, can you have a look at this? This can be a test case for making changes to jLEMS (in a branch of yours on jLEMS) and potentially merging them back to jLEMSDev. The versions should end up being pretty much the same (apart from ReceivePort/EventPort). Note Constant was also missing from ComponentFlattener and I've added that in jLEMS.

A more general way to set initial conditions for state variables

This is more of a philosophical issue. From my point of view, initial conditions are more related to particular runs of a given model than to the general definition of the dynamics and parameters. In other (code) words:

<Parameter name="x0" description="initial condition"/>
...
<OnStart>
            <StateAssignment variable="x" value="x0"/>
</OnStart>

and then define x0 in each run. It would be interesting having mechanisms to grab initial conditions from data files, possibly generated by a previous simulation. That would require the definition of a standard format for storing timeseries.

Changing parameters when an existing comp is used in a ComponentReference

e.g. ionChannel in channelDensity

<HHCell id="hhcellScale2" capacitance="1pF" injection="4pA" v0="-60mV">
    <ChannelPopulation channel="na" number="6000"  erev="50mV" />
    <ChannelPopulation channel="kscale" number="1800" erev="-77mV" >
        <set component="kscale" scale="0.5"/>
    </ChannelPopulation>
</HHCell>

See example in development here: https://github.com/LEMS/jLEMS/blob/nml2beta3/src/test/resources/example-channelshift.xml

Deprecate <ConditionalDerivedVariable>, <Case>

<ConditionalDerivedVariable> has been marked as a candidate for deprecation (#55). It is used in NeuroML2, though.

Decide location of API package

@tarelli's api branch is nearly ready to merge, though the final issue is that LEMSDocumentReader uses java.io.File, which is not allowed in the org.lemsml.jlems.core.* by https://github.com/LEMS/jLEMS/blob/development2/src/test/java/org/lemsml/jlems/test/CoreDependenciesTest.java.

This can be resolved by moving the api package from org.lemsml.jlems.core.api to org.lemsml.jlems.api. This is probably reasonable since it's best that core remains fully approved by @robertcannon (e.g. so that it works with GWT), though it would require updating all Geppetto repos using jLEMS.

Thoughts?

Deprecate <NamedDimensionalType> ?

The only Element from the previous list (#55) that is not used in the NeuroML2 schamata (dev branch) is <NamedDimensionalType>. Candidate for deprecation?

Support instances in populations & allow modification of properties of component instances

For example:

<populationList id="ipop" component="izMixed" size="3">
    <instance id="0"/>
    <instance id="1"/>
    <instance id="2"/>        
    <!-- Or ideally: -->
              <instance id="0"><location x="0" y="0" z="0"/></instance>

</populationList>

See https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/LEMS_NML2_Ex13_Instances.xml
and
https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/Networks.xml#L56

Scaling of variables in OutputFile

It would be useful being able to do

<OutputColumn id="v" quantity="pop/0/hh/v" scale="1mV"

similarly to what's already done here:

<Line id="V" quantity="pop/0/hh/v" scale="1mV" color="#ffffff" timeScale="1ms"

Enable With to reference child instance (not via Path)

Example:

https://github.com/NeuroML/NeuroML2/blob/experimental/LEMSexamples/LEMS_NML2_Ex16_Inputs.xml#L51

https://github.com/NeuroML/NeuroML2/blob/experimental/NeuroML2CoreTypes/Inputs.xml#L139

Code generation in build process?

I'm not a fan of the code generation for jlems.model during the build process. Since the types in this repository are meant to be fairly stable now, it would be better to do the one-off schema generation and then a one-off generation of jlems.model from the schema and check it in. Most future schema changes should only add new classes, not modify existing ones.

Flattening of populations

Hi
I have been working on matlab and C(+cvode) exporters, and I would like to know whether there would be a way of flattening at the entire network level. In other words, what I need is just a large system of ODEs, comprising each cell dynamics, for all cells in a population, for all populations -- as well as the ODEs associated with connectivity (i.e. synaptic dynamics). I am basing these new exporters on the Brian exporter.

Check usage of this & parent in component path resolution

Added keywords this and parent in:
https://github.com/robertcannon/jLEMS/blob/639c554db6e1fa4b5179ae751f2608af643778d0/src/org/lemsml/jlems/type/Component.java

Example of usage:
https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/Inputs.xml#L362
which is needed for:
https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/LEMS_NML2_Ex12_Net2.xml#L26

Remove speculative elements that are not part of any spec

The core.type.geometry package is not used in any models and could be removed entirely so it doesn't appear in the docs. Likewise, core.type.procedure should probably be removed.

core.type.structure is tricky - some parts are used in some example models, but it is still only a proof of concept, not a candidate for standardization.

Deprecate <Fixed>

Fixed has been marked as a candidate for deprecation (#55). It is used in NeuroML2, though.

Improve File menu items & better window event handling

At the moment the File menu includes a number of options that are not needed/implemented:

@robertcannon is it ok to remove open/save/import until they are required/implemented? It's probably fine for now to have jLEMS as a one model per session applicaton, and saving data controlled by what's in the Simulation element.

This menu could be reduced to:

Close window
Exit

Also, currently closing one window (via a window event, not a menu selection) in a model with multiple windows closes the whole application. This should probably be changed to just closing that window unless its the last open.

Tidy README, decide Version, update links to docs

README should point out that this is still a work in progress & give some more info
URL to docs still refs the Sourceforge version & uses older format
Version numbering should be consistent (0.9.0?)

Test issue

Just trying the issue tracking here.

Implement SingleSimulation CompType & allow recording Lems simulations to file

Create example with simple single simulation element, as in previous Lems.

This should allow recording of displayed variables to file, e.g.:

        <Simulation id="sim1" length="400ms" step="0.01ms" target="net2">
                <Display id="d1" title="Ex6: Cells with ..." timeScale="1ms">
                        <Line id="l2" quantity="pasPop[0]/v" scale="1mV" color="#00ffff" save="pas6_v.dat"/>
                </Display>

                <Display id="d2" title="Ex6: Cells with ..." timeScale="1ms">
                        <Line id ="l1" quantity="pasPop[0]/nmdaSyn1/g" scale="1nS"  color="#1111FF" save="ex6_syn.dat"/>
                </Display>

        </Simulation>```

Allow <Include>ing of xml with root different from <Lems>

A statement like:

should allow a file with root to be included, the root ignored, and everything inside treated as normal lems components.

This simple extension should allow any type of xml to be imported and using 'root' makes it clear that it's just the top level element that should be ignored (an error can be thrown if the root is different). In future some more complex XPath/XInclude based expression could be used to pick out the appropriate element, but this should not be needed for now.

Rootfinding based events

In NeuroML, we do

            <StateVariable name="spiking" dimension="none"/>
            <OnCondition test="v .gt. thresh .and. spiking .lt. 0.5">
                <StateAssignment variable="spiking" value="1"/>
                <EventOut port="spike"/>
            </OnCondition>

            <OnCondition test="v .lt. thresh">
                <StateAssignment variable="spiking" value="0"/>
            </OnCondition>

to detect spikes. This involves the creation of a new state variable, and some "ad hoc" logic. This degree of "imperativeness" seems to go against the declarative philosophy of NeuroML/LEMS.
I would suggest defining and detecting events as zero-crossings of state functions in a given direction, i.e., we would just need to say something like

            <OnCondition test="v - thresh" direction="increasing">
                <EventOut port="spike"/>
            </OnCondition>

this would simplify the component, but jLEMS would then need to store history in order to detect events. @robertcannon, would that require drastic changes to the interpreter?