Class ConnectionMonitor. More...

#include <connection_monitor.h>

Public Member Functions
	ConnectionMonitor (ConnectionMonitorCore *connMonCorePtr)
	ConnectionMonitor constructor. More...

	~ConnectionMonitor ()
	ConnectionMonitor destructor. More...

std::vector< std::vector< float > >	calcWeightChanges ()
	Reports the weight changes since the last snapshot in a 2D weight matrix (pre x post) More...

short int	getConnectId ()
	Returns the connection ID that this ConnectionMonitor is managing. More...

int	getFanIn (int neurPostId)
	Returns the number of incoming synapses for a specific post-synaptic neuron. More...

int	getFanOut (int neurPreId)
	Returns the number of outgoing synapses for a specific pre-synaptic neuron. More...

double	getMaxWeight (bool getCurrent=false)
	Returns the max weight in the connection. More...

double	getMinWeight (bool getCurrent=false)
	Returns the min weight in the connection. More...

int	getNumNeuronsPost ()
	Returns the number of post-synaptic neurons. More...

int	getNumNeuronsPre ()
	Returns the number of pre-synaptic neurons. More...

int	getNumSynapses ()
	Returns the number of allocated synapses. More...

int	getNumWeightsChanged (double minAbsChanged=1e-5)
	Returns the number of weights that have changed since the last snapshot. More...

int	getNumWeightsInRange (double minValue, double maxValue)
	Returns the number of weights in the connection whose values are within some range (inclusive) More...

int	getNumWeightsWithValue (double value)
	Returns the number of weights in the connection with a particular value. More...

double	getPercentWeightsChanged (double minAbsChanged=1e-5)
	Returns the percentage of weights that have changed since the last snapshot. More...

double	getPercentWeightsInRange (double minValue, double maxValue)
	Returns the percentage of weights whose values are within some range (inclusive) More...

double	getPercentWeightsWithValue (double value)
	Returns the percentage of weights in the connection with a particular value. More...

long int	getTimeMsCurrentSnapshot ()
	Returns the timestamp of the current snapshot (ms since beginning of simulation) More...

long int	getTimeMsLastSnapshot ()
	Returns the timestamp of the last snapshot (ms since beginning of simulation) More...

long int	getTimeMsSinceLastSnapshot ()
	Returns the timestamp difference of the current and last snapshot. More...

double	getTotalAbsWeightChange ()
	Returns the absolute sum of all the weight changes since the last snapshot. More...

void	print ()
	Prints the current weight state as a 2D matrix (pre x post) More...

void	printSparse (int neurPostId=ALL, int maxConn=100, int connPerLine=4)
	Prints the current weight state as a sparse list of weights. More...

void	setUpdateTimeIntervalSec (int intervalSec)
	Sets the time interval (seconds) for writing snapshots to file. More...

std::vector< std::vector< float > >	takeSnapshot ()
	Takes a snapshot of the current weight state. More...

Detailed Description

The ConnectionMonitor class allows a user record weights from a particular connection. First, the method CARLsim::setConnectionMonitor must be called on a specific pair of pre-synaptic and post-synaptic group. This method then returns a pointer to a ConnectionMonitor object, which can be queried for connection data.

By default, a snapshot of all the weights will be taken once per second and dumped to file. The easiest way to use a ConnectionMonitor is to call CARLsim::setConnectionMonitor with file string "default". This will create a file with path "results/conn_{name of pre-group}_{name of post-group}.dat". It is also possible to specify a custom file string instead. Alternatively, the user may suppress creation of the binary file by using file string "null" instead.

Periodic storing can be disabled by calling ConnectionMonitor::setUpdateTimeInterval with argument intervalSec=-1.

Additionally, during a CARLsim simulation, the ConnectionMonitor object returned by CARLsim::setConnectionMonitor can be queried for connection data. The user may take a snapshot of the weights at any point in time using the method ConnectionMonitor::takeSnapshot. Note that a snapshot taken with this method will also be stored in the binary file. However, the binary file will never contain the same snapshot (captured with a certain timestamp) twice.

If at least two snapshots have been taken, the method ConnectionMonitor::calcWeightChanges will calculate the weight changes since the last snapshot. To make sure you are comparing the right snapshots, compare the timestamps returend by ConnectionMonitor::getTimeMsCurrentSnapshot and ConnectionMonitor::getTimeMsLastSnapshot.

Weights can be visualized in the Matlab Offline Analysis Toolbox (OAT) using the ConnectionMonitor utility. The OAT offers ways to plot 2D weight matrices, as well as receptive fields and response fields.

Weights can also be visualized in C++ using ConnectionMonitor::print and ConnectionMonitor::printSparse.

Example to store weights in binary every second:

// configure a network, etc. ...
sim.setupNetwork();
 
// direct storing of snapshots to default file "results/conn_{name of pre}_{name of post}.dat".
sim.setConnectionMonitor(grp0, grp1, "default");
 
// run the network for 10 seconds
sim.runNetwork(10,0);

Example that stores weight at the beginning and end of a simulation:

// configure a network, etc. ...
sim.setupNetwork();
 
// direct storing of snapshots to default file "results/conn_{name of pre}_{name of post}.dat".
// additionally, grab the pointer to the monitor object
ConnectionMonitor* CM = sim.setConnectionMonitor(grp0, grp1, "default");
 
// disable periodid storing of snapshots in binary ...
CM->setUpdateTimeIntervalSec(-1);
 
// ... and instead take a snapshot yourself and put it in the binary
CM->takeSnapshot();
 
// run the network for 10 seconds
sim.runNetwork(10,0);
 
// take another snapshot at the end and put it in the binary
CM->takeSnapshot();

Example that periodically stores to binary and does some analysis on returned weight vector

// configure a network, etc. ...
sim.setupNetwork();
 
// direct storing of snapshots to default file "results/conn_{name of pre}_{name of post}.dat".
// additionally, grab the pointer to the monitor object
ConnectionMonitor* CM = sim.setConnectionMonitor(grp0, grp1, "default");
 
// retrieve initial weights (this snapshot will also end up in the binary)
std::vector< std::vector<float> > wt = CM->takeSnapshot();
printf("The weight from pre-neuron ID 3 to post-neuron ID 7 is: %f\n",wt[3][7]);
 
// run the network for 5 seconds and print 2D weight matrix
sim.runNetwork(5,0);
CM->print();
 
// run the network for an additional 5 seconds and retrieve weight changes between last snapshot
// (at the beginning) and now (after 10 seconds)
sim.runNetwork(5,0);
std::vector< std::vector<float> > wtChanges = CM->calcWeightChanges();

Note: A snapshot taken programmatically with ConnectionMonitor::takeSnapshot can be put in the binary file by setting an optional input flag writeToFile to true.

Definition at line 148 of file connection_monitor.h.

Constructor & Destructor Documentation

◆ ConnectionMonitor()

ConnectionMonitor ( ConnectionMonitorCore * connMonCorePtr )

Creates a new instance of the ConnectionMonitor class.

Definition at line 55 of file connection_monitor.cpp.

◆ ~ConnectionMonitor()

~ConnectionMonitor ( )

Cleans up all the memory upon object deletion.

Definition at line 59 of file connection_monitor.cpp.

Member Function Documentation

◆ calcWeightChanges()

std::vector< std::vector< float > > calcWeightChanges ( )

This function calculates the difference between the current state of the weight matrix and what it was when taking the last snapshot. Weight change is reported for every synapse, in a 2D vector where the first dimension corresponds to pre-synaptic neuron ID and the second dimension corresponds to post-synaptic neuron ID. For example, element wtChange[3][8] of the return argumentr will indicate the signed weight change since the last snapshot for the synapse that connects preNeurId=3 to postNeurId=8. Synapses that are not allocated (i.e., that do not exist) are marked as float value NAN in the weight matrix. Synapses that do exist, but have zero weight, are marked as 0.0f in the weight matrix.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Returns: a 2D vector of weight changes, where the first dimension is pre-synaptic neuron ID and the second dimension is post-synaptic neuron ID. Non-existent synapses are marked with NAN.

Since: v3.0

Definition at line 66 of file connection_monitor.cpp.

◆ getConnectId()

short int getConnectId ( )

This function returns the connection ID that this ConnectionMonitor is managing. It is equivalent to the return argument of CARLsim::connect.

Since: v3.0

Definition at line 70 of file connection_monitor.cpp.

◆ getFanIn()

int getFanIn ( int neurPostId )

This function returns the number of incoming synapses for a specific post-synaptic neuron ID.

Since: v3.0

Definition at line 74 of file connection_monitor.cpp.

◆ getFanOut()

int getFanOut ( int neurPreId )

This function returns the number of outgoing synapses for a specific pre-synaptic neuron ID.

Since: v3.0

Definition at line 81 of file connection_monitor.cpp.

◆ getMaxWeight()

double getMaxWeight ( bool getCurrent = false )

This function returns the maximum weight value of all synapses in the connection.

If getCurrent is set to true, then the function will return the currently largest weight value. In a plastic connection, this value might be different from the upper bound of the weight range specified when setting up the network (i.e., the max field of the RangeWeight struct). In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

If getCurrent is set to false, then the upper bound of the configured weight range will be returned.

Parameters

[in] getCurrent whether to return the currently largest weight value (true) or the upper bound of the weight range specified during setup (false). Default: false.

Since: v3.1

Definition at line 96 of file connection_monitor.cpp.

◆ getMinWeight()

double getMinWeight ( bool getCurrent = false )

This function returns the minimum weight value of all synapses in the connection.

If getCurrent is set to true, then the function will return the currently smallest weight value. In a plastic connection, this value might be different from the lower bound of the weight range specified when setting up the network (i.e., the min field of the RangeWeight struct). In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

If getCurrent is set to false, then the lower bound of the configured weight range will be returned.

Parameters

[in] getCurrent whether to return the currently smallest weight value (true) or the lower bound of the weight range specified during setup (false). Default: false.

Since: v3.1

Definition at line 100 of file connection_monitor.cpp.

◆ getNumNeuronsPost()

int getNumNeuronsPost ( )

This function returns the number of neurons in the post-synaptic group.

Since: v3.0

Definition at line 92 of file connection_monitor.cpp.

◆ getNumNeuronsPre()

int getNumNeuronsPre ( )

This function returns the number of neurons in the pre-synaptic group.

Since: v3.0

Definition at line 88 of file connection_monitor.cpp.

◆ getNumSynapses()

int getNumSynapses ( )

This function returns the number of allocated synapses in the connection.

Since: v3.0

Definition at line 104 of file connection_monitor.cpp.

◆ getNumWeightsChanged()

int getNumWeightsChanged ( double minAbsChanged = 1e-5 )

This function returns the number of weights whose absolute value has changed at least minAbsChanged (inclusive) since the last snapshot was taken.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Parameters

[in] minAbsChanged the minimal value (inclusive) a weight has to have changed in order for it to be counted towards the number of changed synapses

Since: v3.0

Definition at line 108 of file connection_monitor.cpp.

◆ getNumWeightsInRange()

int getNumWeightsInRange	(	double	minValue,
		double	maxValue
	)

This function returns the number of synaptic weights whose values are within some specific range e[minVal,maxVal] (inclusive).

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Parameters

[in]	minValue	the lower bound of the weight range (inclusive)
[in]	maxValue	the upper bound of the weight range (inclusive)

Note: CM.getNumWeightsInRange(CM.getMinWeight(false),CM.getMaxWeight(false)) is the same as CM.getNumSynapses().

See also: ConnectionMonitor::getPercentWeightsInRange; ConnectionMonitor::getNumWeightsWithValue

Since: v3.1

Definition at line 114 of file connection_monitor.cpp.

◆ getNumWeightsWithValue()

int getNumWeightsWithValue ( double value )

This function returns the number of synaptic weights that have exactly some specific value. It could be used to determine the sparsity of the connection matrix (wtValue==0.0f).

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Machine epsilon (FLT_EPSILON) is used for floating point equality. That is, the weight value is considered equal to the input value if fabs(wt-value)<=FLT_EPSILON (inclusive).

This is a convenience function whose result is equivalent to getNumWeightsInRange(value-FLT_EPSILON,value+FLT_EPSILON).

Parameters

[in] value the exact weight value to look for

See also: ConnectionMonitor::getPercentWeightsWithValue; ConnectionMonitor::getNumWeightsInRange

Since: v3.1

Definition at line 120 of file connection_monitor.cpp.

◆ getPercentWeightsChanged()

double getPercentWeightsChanged ( double minAbsChanged = 1e-5 )

This function returns the percentage of weights whose absolute has changed at least minAbsChanged (inclusive) since the last snapshot was taken.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

This is a convenience function whose result is equivalent to getNumWeightsChanged()*100.0/getNumSynapses().

Parameters

[in] minAbsChanged the minimal value (inclusive) a weight has to have changed in order for it to be counted towards the percentage of changed synapses

Since: v3.0

Definition at line 125 of file connection_monitor.cpp.

◆ getPercentWeightsInRange()

double getPercentWeightsInRange	(	double	minValue,
		double	maxValue
	)

This function returns the percentage of synaptic weights whose values are within some specific range e[minVal,maxVal] (inclusive).

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

This is a convenience function whose result is equivalent to getNumWeightsInRange(minValue,maxValue)*100.0/getNumSynapses().

Parameters

[in]	minValue	the lower bound of the weight range (inclusive)
[in]	maxValue	the upper bound of the weight range (inclusive)

Note: CM.getNumWeightsInRange(CM.getMinWeight(false),CM.getMaxWeight(false)) is the same as CM.getNumSynapses().

See also: ConnectionMonitor::getNumWeightsInRange; ConnectionMonitor::getNumWeightsWithValue

Since: v3.1

Definition at line 129 of file connection_monitor.cpp.

◆ getPercentWeightsWithValue()

double getPercentWeightsWithValue ( double value )

This function returns the percentage of synaptic weights that have exactly some specific value. It could be used to determine the sparsity of the connection matrix (wtValue==0.0f).

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Machine epsilon (FLT_EPSILON) is used for floating point equality. That is, the weight value is considered equal to the input value if fabs(wt-value)<=FLT_EPSILON (inclusive).

This is a convenience function whose result is equivalent to getNumWeightsWithValue(value)*100.0/getNumSynapses().

Parameters

[in] value the exact weight value to look for

See also: ConnectionMonitor::getNumWeightsWithValue; ConnectionMonitor::getNumWeightsInRange

Since: v3.1

Definition at line 133 of file connection_monitor.cpp.

◆ getTimeMsCurrentSnapshot()

long int getTimeMsCurrentSnapshot ( )

This function returns the timestamp of the current weight snapshot, reported as the amount of time that has passed since the beginning of the simulation (in milliseconds). It will not take a snapshot by itself, so the time reported here is not necessarily equal to the time reported by CARLsim::getSimTime.

Since: v3.0

Definition at line 137 of file connection_monitor.cpp.

◆ getTimeMsLastSnapshot()

long int getTimeMsLastSnapshot ( )

This function returns the timestamp of the last weight snapshot, reported as the amount of time that has passed since the beginning of the simulation (in milliseconds).

Since: v3.0

Definition at line 141 of file connection_monitor.cpp.

◆ getTimeMsSinceLastSnapshot()

long int getTimeMsSinceLastSnapshot ( )

This function returns the amount of time that has been passed between the current and last weight snapshot (reported in ms).

This is a convenience function whose result is equivalent to getTimeMsCurrentSnapshot()-getTimeMsLastSnapshot().

Since: v3.0

Definition at line 145 of file connection_monitor.cpp.

◆ getTotalAbsWeightChange()

double getTotalAbsWeightChange ( )

This function calculates the absolute sum of weight changes since the last snapshot was taken.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Since: v3.0

Definition at line 149 of file connection_monitor.cpp.

◆ print()

void print ( )

This function prints the current state of the weights in a readable 2D weight matrix, where the first dimension corresponds to pre-synaptic neuron ID and the second dimension corresponds to post-synaptic neuron ID. Synapses that are not allocated (i.e., that do not exist) are marked as float value NAN in the weight matrix. Synapses that do exist, but have zero weight, are marked as 0.0f in the weight matrix.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Note: Please note that this will visualize a getNumNeuronsPre() x getNumNeuronsPost() matrix on screen. For connections between large neuronal groups, use ConnectionMonitor::printSparse.

Since: v3.0

Definition at line 153 of file connection_monitor.cpp.

◆ printSparse()

void printSparse	(	int	neurPostId = `ALL`,
		int	maxConn = `100`,
		int	connPerLine = `4`
	)

This function prints the current state of the weights as a readable sparse list of weights. This is also the standard format used for ConnectionMonitor to report a run summary (see CARLsim::runNetwork). A weight will be reported as [preId,postId] wt (+/- weight change in the last x ms). User can control for which post-synaptic neurons the list should be generated, and set limits on how many connections to print in total and per line.

In order to get the current state of the weight matrix, this function will take a snapshot itself, but will not write it to file.

Note: Please note that this is the preferred way to visualize connections between large neuronal groups. The method ConnectionMonitor::print should primarily be used for small-sized groups.

Parameters

[in]	neurPostId	The neuron ID of the post-synaptic group for which to generate the sparse weight list. Set to ALL to generate the list for all post-synaptic neurons.
[in]	maxConn	The maximum number of weights to print.
[in]	connPerLine	The number of weights to print per line.

Since: v3.0

Definition at line 157 of file connection_monitor.cpp.

◆ setUpdateTimeIntervalSec()

void setUpdateTimeIntervalSec ( int intervalSec )

This function sets the time interval (seconds) for writing weight snapshots to file. The first snapshot will be written at time t=0, and every intervalSec seconds later.

In order to disable the periodic storing of weights to file alltogether, set intervalSec to -1. In this case, only weight snapshots acquired via ConnectionMonitor::takeSnapshots will end up in the binary.

Parameters

[in] intervalSec The update time interval (number of seconds) for writing snapshots to file. Set to -1 to disable periodic weight storing. Default: 1 (every second).

Since: v3.0

Definition at line 166 of file connection_monitor.cpp.

◆ takeSnapshot()

std::vector< std::vector< float > > takeSnapshot ( )

This function takes a snapshot of the current weight matrix, stores it in the binary as well as returns it as a 2D vector where the first dimension corresponds to pre-synaptic neuron ID and the second dimension corresponds to post-synaptic neuron ID. For example, element wtChange[3][8] of the return argumentr will indicate the signed weight change since the last snapshot for the synapse that connects preNeurId=3 to postNeurId=8. Synapses that are not allocated (i.e., that do not exist) are marked as float value NAN in the weight matrix. Synapses that do exist, but have zero weight, are marked as 0.0f in the weight matrix.

Returns: a 2D vector of weights, where the first dimension is pre-synaptic neuron ID and the second dimension is post-synaptic neuron ID. Non-existent synapses are marked with NAN.

Note: Every snapshot taken will also be stored in the binary file.

Since: v3.0

Definition at line 173 of file connection_monitor.cpp.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ConnectionMonitor()

◆ ~ConnectionMonitor()

Member Function Documentation

◆ calcWeightChanges()

◆ getConnectId()

◆ getFanIn()

◆ getFanOut()

◆ getMaxWeight()

◆ getMinWeight()

◆ getNumNeuronsPost()

◆ getNumNeuronsPre()

◆ getNumSynapses()

◆ getNumWeightsChanged()

◆ getNumWeightsInRange()

◆ getNumWeightsWithValue()

◆ getPercentWeightsChanged()

◆ getPercentWeightsInRange()

◆ getPercentWeightsWithValue()

◆ getTimeMsCurrentSnapshot()

◆ getTimeMsLastSnapshot()

◆ getTimeMsSinceLastSnapshot()

◆ getTotalAbsWeightChange()

◆ print()

◆ printSparse()

◆ setUpdateTimeIntervalSec()

◆ takeSnapshot()