braindynamicsusyd / nftsim Goto Github PK

From @RomeshA

There should be a way to name populations and give them a single
letter subscript, which would then enable us to refer to populations
with labels like 'e','r','s', and to connections like 'ee','ei'...
rather than population 1, couple 3. This would also make it easier to
compare similar components when the model is changing and thus the
indexes might change.

I could imagine a solution using something like Python dictionaries to have key:value pairs, where the key would be 'ee', 'ei' for connections and 'e', 'i'. I think numeric indexing is more general, so labels are mainly a human readable decoration. Maybe we can generate a mapping between the two?

Apparently the equivalent dictionary structure in C++ is called std::map. However, I've never used it.

Placeholder issue to track time spent on meetings about the code

Currently there are several integration methods used by different Classes:

• RK4 and Euler

We should incorporate an integration method that has the same rate of convergence in both the determinsitc and stochastic part like the predictor-corrector method (aka, Heun's method or modified Euler method)

Write a script to produce API documentation for developers and/or contributors.
This will involve documenting the code according to standards.

Neurofield has been tested mainly with GNU GCC >= 4.8 on linux platforms (RHEL 6, 7 and Open SUSE Leap 42.1).

Update: Unfortunately gateway was dongraded from RHEL 7 to 6, making the default compiler GNU GCC 4.4 and thus not compatible with C++11.

Mac OS: errors with CLANG have been reported.
Windows: untested.

The code should be compiled with several compiler that support C++11 standard and fix the code so it can be used across different platforms.

This issue is self explanatory.

A colon in the comments at the top of a config file seems to prevent the simulation from being run.
As an example the following comment

/Config file for EIRS-BG model, with the following populations excitatory:
(e), inhibitory (i), reticular nuclei/TRN (r) and relay nuclei/SRN (s) forming
the corticothalamic section, combined with the basal ganglia populations D1
and D2 (striatal neurons expressing either the D1 class or D2 class of
dopamine receptor), GPi (globus pallidus internal), GPe (globus pallidus
external), STN (subthalamic nucleus)./

produces the following error:

Unable to find next input variable: Time From configuration file:

We basically need a comment symbol for the config file (eg, #) ...

The word Output , case sensitive, in the comment lines causes the following error:
Trying to output population 0, which is an invalid population.

The doc for coupling type Matrix says:

Coupling becomes connection matrix, where connection strength does 
\emph{not} change with time.  The format of the nu matrix is the same 
as the population connection matrix, each row is to the same 
node, each column is from the same node. When outputting, each 
specified outputting node output the indexed row.

What does that mean? Each row is the TO node? And each column the FROM node?

In the config file matrix.conf the size of the matrix for Couple 2 is Nodes x Nodes. What additional feature does this coupling provide that is not achieved by giving a vector of length Nodes in coupling type Map?
Is it this coupling allowing for the introduction of something like long range corticocortical structural connectivity?

Long overdue answer: it is used for spatially nonuniform coupling

From @RomeshA

Related to #19

If we're changing the parser, I wonder if it would be better to
separate the dendrites from the populations - there are as many of
them as there are couples, of course. They are presently contained
within the population blocks because of the way that the config file
is currently read, but I think this makes the config file more
confusing to read.

Coefficients of the current method for the wave equation is untraceable.
We basically need to re-implement a method from scratch.

We need to select a style guide for naming conventions and documentation to use it throughout the code.

For general coding practices in C++11 we'll follow:
https://github.com/isocpp/CppCoreGuidelines

For other matters such as naming conventions, spaces and indentations we'll adopt:
https://google.github.io/styleguide/cppguide.html

Add this case to the collection of configuration files.

Previous work done by:
van Albada et al.

As a request this is rather vague because it does not specify which variable will be modulated.
More specifically, PR is interested in having a coupling which acts as a slow (temporal) variable and has been shown to be able to drive the onset and cease of seizures.

Similar mechanisms as those used in plasticity could be used.

In the eegcode there was an implementation of neuromodulation of sigma.

Add new class that generalizes the ramp. With this class users can defined as many piecewise linear segments to ramp up or down the synaptic coupling weights.

Include:

• tests
• config file
• docu

The code is already available in my fork, but I need to clean it up and write the docu, plus the pull request and such.

With this class is possible to reproduce the results in Zhao and Robinson, August 2015.

Add example configurations for these to the repository

As part of good programming practices the source file should include

• Original author name
• Authors who have substantially modified, altered and re factored the code.
• Restore Peter Drysdale name

I started using TravisCI on my fork and it works very well. So far it compiles with GNU-GCC under a Debian distro. However, the integration can be configured to compile with different versions of different compilers (eg, clang) on linux and mac os.

Test scripts can be configured to run as well.

Unit testing is process in which the smallest testable parts of an application, called units, are individually and independently scrutinized for proper operation.

It's desirable to have automated unit testing so after any change we verify that our functions still work as expected. In other words, unit tests prevent future changes from breaking functionality.

For instance, in the case of the stencil a unit test would consist of

• evaluating a known function with a continuous second derivative (the laplacian of the function);
• and, comparing the analytical results with the ones from the code.

If the results differ, then the test fails.

Patchy propagator is a new type of propagator and has been used in modelling studies of the visual cortex.
A class for this propagator was implemented in EEG code.

This task also entails a small research project on the way spatiotemporal noise will be generated.
Generate signals using a linear combination of sinc functions.

There are certain considerations to have:

• Cutoff frequency (around 256 Hz). The power spectrum should be flat up to this frequency.
• Time step size will depend on cuttoff frequency. The sampling frequency (1/ dt) should be at least 10x than the cutoff frequency to have a proper smooth representation of the "noise" signal. For instance for a cuttoff freq of 256 Hz, dt = 2**-11
• Number of pulses: find a way to determine a good number of pulses based on simulation length, dt and cutoff frequency.
• Locations of the pulses. Uniformly spaced or random locations?
• Amplitude of the pulses. Drawn from a normal distribution or a uniform distribution?
• Normalization: How to correctly normalize the signal if we generate samples at each time step? Should the power of the signal be always 1?

We need to have a set of configuration files, with their corresponding output, to test against output files produced after modifications to the code.

This task involves:

• writing a script to automate the execution of most, if not all, the configuration files available.
• saving the corresponding outputs and keep them in the repository (under test/).
• writing a script to perform a diff between current reference output files and new output files.

Modifications that do not alter functionality should not produce a different output.
These reference output files will have to be updated following changes in (i) the class hierarchy; (ii) variable names; (iii) solvers. In the latter case, the output files prior to the modifications and after the modifications, will likely be different. These differences have to be reported and documented under this issue or a new issue.

Change base class Dendrite.
Make the old base class Dendrite a derived class that preserves the integral form.

Once #44 is finished, the new implementation should be compared with the previous one

From @RomeshA
Relates to #18

The order in which parameters are entered matters, and the order is
determined by the ordering of the statements in the init() function in
the cpp files, which means that there is no way to know what the
correct order is without inspecting the file.

Problems:
This makes it impossible
to implement the general parser without somehow modifying it to store
the correct order. The solution to this must be to make the config
files order-invariant. One possibility would be to rewind the file
pointer after each parameter is read, back to the original position
from which the init function was called. We would need to check
carefully what conditions this might impose on having duplicate or
similar parameter names. In this case, we would still need to somehow
return from the init function with the file pointer at the end of the
block (in preparation for the next block) - this could be difficult.

Potential Solution:
One option is to make the config file whitespace-dependent (and then
use newlines to separate logical blocks)?

Questions:
What's a logical block in the config file? An object with its parameters?

@felixfung
Is it still possible to restart a simulation?

• Automate benchmark execution. A script will take a .conf file and save information about execution times, memory, hardware used, etc (use this branch)

• Write benchmark results to file.

Placeholder to time track time spent on admin tasks

Use tools to check for consistency, detect errors and clean up code to enable cross compilation.

In the same spirit as #31: there were some more verbose and human readable error messages in eegcode, which where shortened.

The same files are a good example of this in particular the error message referring to the Courant condition.

Part of the generalization will involve adopting a standard naming convention for classes, variables and methods. An evaluation on how current specific classes may be generalized or integrated into a class that is flexible enough to express different plasticity rules.

Add instructions to get up the GitHub SSH keys to the wiki

Remove nf_eirs and related packages because they belong in the CT repository
Update documentation and instructions for setting up the helpers

The Launch script is written in Perl, and is scheduled for deprecation in favour of the Matlab helper scripts

Some comments found in EEG code do not longer exist in the current version, making the code more cryptic for a new dev and for anyone reading the code for the first time.

And example of this are the comments found in waveeqn.cpp that never made into wave.cpp.

While most of the development here follows a Solo Virtuoso patter, that is not a license to hack or erase details of previous versions. In particular when a) the revision history of the code has not been ported from svn to git and b) the decisions made when refactoring eegcode into neurofield were not written down.

@felixfung

Some questions about stencils:
https://github.com/BrainDynamicsUSYD/neurofield-paper/issues/3

For the 1D case, for solving an hyperbolic PDE with a finite difference method, the Courant condition is

(delta t / delta x)  * c <= 1,

where c is the wave velocity. The upper boundary 1 is due to the fact that in the worst case, the c = delta x / delta t. However, we normally want c < delta x / delta t.

In the 2D case, we have

delta t <= (1/c) *[ (1 / delta x)**2 + (1 / delta y)**2]**-0.5 ,

because we have delta x = delta y

then

delta t <= (1/c) *[ 2 / (delta x)**2]**-0.5 ,
           <= (1/c) *[ (delta x)**2 / 2 ]**0.5 ,
            <= (delta  x/c) * (1  / sqrt(2)) ,
delta t / delta x <= (1/c) * (1 / sqrt(2))

or

c * delta t / delta x <= (1 / sqrt(2))

which is approximately 0.707.

In the code we currently have

c * delta t / delta x <= sqrt(2)

twice the upper boundary after which the accuracy of the simulation worsens.

• Double check using books on numerical methods for hyperbolic PDEs.

Add this case to the collection of config files.

Reference:
Robinson et al., 2015 (to be submitted) on Eigenmodes of Brain Activity

Some of the school machines give Error: suffix or operands invalid for vbroadcastsd when compiling. It appears to be SSE related, and can be fixed by disabling march=native and mtune=native. The root cause may be something to do with the system libraries

From @RomeshA

Another problem is that the derived classes must be added to
solver.cpp in order for them to be used by the program. It would be
better if only the derived class's header or cpp file was required.

Add the same configuration file that it is included as an example of input and output.

Try to derive the expression for the finite difference method (in 2D) from the current implementation in the code.

Base documents:

• Chris Rennie's thesis
• Abramowitz and Stegun: Handbook of Mathematical Functions
• A. R. Mitchell. Computational methods in partial differential equations. John Wiley & Sons, London, 1969.

Placeholder issue to track time spent on reviewing code and handling pull request

Need to use a chmod. Any way to implement this?

Add configurations corresponding to published results for bursting

Review the current pull request #40. This new Couple class uses a smooth function (a difference of atan functions).

• The code needs to be cleaned and improved where possible.
• Adopt variable, fn and class naming according to style guide.
• Write a short config file demonstrating how to use the new class.
• Write the relevant documentation in the user manual (add figures if possible using matlab helpers).

Pull request #40 won't be merged. Start in a new branch that is up to date with the current master branch and add new files based on the these files..

Suggested variable name changes:
nu0 -> nu_min
t1 --> t_half_up
t2 --> t_half_down

Suggested filename:
couple_diff_arctan

Manual - Information about the the base classes and some derived classes, configuration files, usage of +nf module.

Wiki - Information about github, project distribution, extra tutorials, setting up the environment

From @RomeshA
A general Matlab interface needs to be able to specify options for
any NeuroField object. However, the parameters of the object are
different for each of the classes, as well as for derived classes.
Therefore, the Matlab interface needs to be able to generate strings
for arbitrary parameters, which should be fine because the parameters
follow a standard syntax (with colons and dashes).

From @pausz
This interface could also handle the calculation of the steady-states values for different models.
It will require handling symbolic expressions and incorporating a root finding algorithm.

• Research on ABC
• Study cases
• Propose implementation

The current implementation of the harmonic operator is supposed to be an explicit solution of a forced harmonic oscillator. Although it may be slightly faster than an iterative forward method, the latter is more general and doesn't rely on assumptions of linearity and homogeneous parameters like the current implementation.

Change class Harmonic. Make the old class Harmonic a derived class that preserves the integral form.
Write a new class Harmonic with the differential form.