ngclearn.engine package

Subpackages

• ngclearn.engine.cables package
  • Subpackages
    • ngclearn.engine.cables.rules package
      • Submodules
      • ngclearn.engine.cables.rules.chebb_rule module
      • ngclearn.engine.cables.rules.hebb_rule module
      • ngclearn.engine.cables.rules.rule module
      • Module contents
  • Submodules
  • ngclearn.engine.cables.cable module
  • ngclearn.engine.cables.dcable module
  • ngclearn.engine.cables.scable module
  • Module contents
• ngclearn.engine.nodes package
  • Submodules
  • ngclearn.engine.nodes.enode module
  • ngclearn.engine.nodes.fnode module
  • ngclearn.engine.nodes.node module
  • ngclearn.engine.nodes.snode module
  • ngclearn.engine.nodes.spnode_lif module
  • ngclearn.engine.nodes.spnode_enc module
  • ngclearn.engine.nodes.fnode_ba module
  • Module contents

Submodules

ngclearn.engine.ngc_graph module

class ngclearn.engine.ngc_graph.NGCGraph(K=5, name='ncn', batch_size=1)

Bases: object

Implements the full model structure/graph for an NGC system composed of nodes and cables. Note that when instantiating this object, it is important to call .compile(), like so:

graph = NGCGraph(…)

info = graph.compile()

Parameters

• K – number of iterative inference/settling steps to simulate

• name – (optional) the name of this projection graph (Default=”ncn”)

• batch_size –

  fixed batch-size that the underlying compiled static graph system should assume (Note that you can set this also as an argument to .compile() )

  Note

  if “use_graph_optim” is set to False, then this argument is not meaningful as the system will work with variable-length batches

apply_constraints()

Apply any constraints to the signals embedded in this graph. This function will execute any of the following pre-configured constraints:

1) compute new precision matrices (if applicable)

2) project weights to adhere to vector norm constraints

calc_updates(debug_map=None)

Calculates the updates to synaptic weight matrices along each learnable wire within this graph via a generalized Hebbian learning rule.

Parameters

debug_map – (Default = None), a Dict to place named signals inside (for debugging)

clamp(clamp_targets)

Clamps an externally provided named value (a vector/matrix) to the desired compartment within a particular Node of this NGC graph. Note that clamping means this value typically means the value clamped on will persist (it will NOT evolve according to the injected node’s dynamics over simulation steps, unless is_persistent = True).

Parameters

clamp_targets –

3-Tuple containing a named external signal to clamp

node_name (Tuple[0])

the (str) name of the node to clamp a data signal to.

compartment_name (Tuple[1])

the (str) name of the node’s compartment to clamp this data signal to.

signal (Tuple[2])

the data signal block to clamp to the desired compartment name

clear()

Clears/deletes any persistent signals currently embedded w/in this graph’s Nodes

clone_state()

Clones the entire state of this graph (in terms of signals/tensors) and stores each node’s state dictionary in global has map

Returns

a Dict (hash table) containing string names that map to physical Node objects

compile(use_graph_optim=True, batch_size=- 1)

Executes a global “compile” of this simulation object to ensure internal system coherence. (Only call this function after the constructor has been set).

Parameters

• use_graph_optim – if True, this simulation will use static graph acceleration (Default = True)

• batch_size – if > 0, will set the integer global batch_size of this simulation object (otherwise, self.batch_size will be used)

Returns

a dictionary containing post-compilation information about this simulation object

evolve(clamped_vars=None, readout_vars=None, init_vars=None, cold_start=True, K=- 1, masked_vars=None)

Evolves this simulation object for one full K-step episode given input information through clamped and initialized variables. Note that this is a convenience function written to embody an NGC system’s full settling process, its local synaptic update calculations, as well as the optimization of and application of constraints to the synaptic parameters contained within .theta.

Parameters

• clamped_vars – list of 3-tuple strings containing named Nodes, their compartments, and values to (persistently) clamp on. Note that this list takes the form: [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

• readout_vars – list of 2-tuple strings containing Nodes and their compartments to read from (in this function’s output). Note that this list takes the form: [(node1_name, node1_compartment), node2_name, node2_compartment),…]

• init_vars – list of 3-tuple strings containing named Nodes, their compartments, and values to initialize each Node from. Note that this list takes the form: [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

• cold_start – initialize all non-clamped/initialized Nodes (i.e., their compartments contain None) to zero-vector starting points

• K – number simulation steps to run (Default = -1), if <= 0, then self.K will be used instead

• masked_vars – list of 4-tuple that instruct which nodes/compartments/masks/clamped values to apply. This list is used to trigger auto-associative recalls from this NGC graph. Note that this list takes the form: [(node1_name, node1_compartment, mask, value), node2_name, node2_compartment, mask, value),…]

Returns

readouts, delta;

where “readouts” is a 3-tuple list of the form [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

extract(node_name, node_var_name)

Extract a particular signal from a particular node embedded in this graph

Parameters

• node_name – name of the node from the NGC graph to examine

• node_var_name – compartment name w/in Node to extract signal from

Returns

an extracted signal (vector/matrix) OR None if either the node does not exist or the entire system has not been simulated (meaning that no node dynamics have been run yet)

getNode(node_name)

Extract a particular node from this graph

Parameters

node_name – name of the node from the NGC graph to examine

Returns

the desired Node (object) or None if the node does not exist

inject(injection_targets)

Injects an externally provided named value (a vector/matrix) to the desired compartment within a particular Node of this NGC graph. Note that injection means this value does not persist (it will evolve according to the injected node’s dynamics over simulation steps).

Parameters

• injection_targets –

  3-Tuple containing a named external signal to clamp

  node_name (Tuple[0])

  the (str) name of the node to clamp a data signal to.

  compartment_name (Tuple[1])

  the (str) name of the compartment to clamp this data signal to.

  signal (Tuple[2])

  the data signal block to clamp to the desired compartment name

• is_persistent – if True, clamped data value will persist throughout simulation (Default = True)

parse_node_values(node_values)

set_cycle(nodes, param_order=None)

Set an execution cycle in this graph

Parameters

nodes – an ordered list of Node(s) to create an execution cycle for

set_learning_order(param_order)

Forces this simulation object to arrange its .theta and delta to follow a particular order.

Parameters

param_order – a list of Cables/Nodes which will dictate the strict order in which parameter updates will be calculated and how they are arranged in .theta (note that delta and theta will match the same dictated order)

set_optimization(opt_algo)

Sets the internal optimization algorithm used by this simulation object.

Parameters

opt_algo – optimization algorithm to be used, e.g., SGD, Adam, etc. (Note: must be a valid TF2 optimizer.)

set_theta(theta_target)

set_to_resting_state(batch_size=- 1)

set_to_state(state_map)

Set every state of every node in this graph to the values contained in the global Dict (hash table) “state_map”

Parameters

state_map – a Dict (hash table) containing string names that map to physical Node objects

settle(clamped_vars=None, readout_vars=None, init_vars=None, cold_start=True, K=- 1, debug=False, masked_vars=None, calc_delta=True)

Execute this NGC graph’s iterative inference using the execution pathway(s) defined at construction/initialization.

Parameters

• clamped_vars – list of 3-tuple strings containing named Nodes, their compartments, and values to (persistently) clamp on. Note that this list takes the form: [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

• readout_vars – list of 2-tuple strings containing Nodes and their compartments to read from (in this function’s output). Note that this list takes the form: [(node1_name, node1_compartment), node2_name, node2_compartment),…]

• init_vars – list of 3-tuple strings containing named Nodes, their compartments, and values to initialize each Node from. Note that this list takes the form: [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

• cold_start – initialize all non-clamped/initialized Nodes (i.e., their compartments contain None) to zero-vector starting points/resting states

• K – number simulation steps to run (Default = -1), if <= 0, then self.K will be used instead

• debug – <UNUSED>

• masked_vars – list of 4-tuple that instruct which nodes/compartments/masks/clamped values to apply. This list is used to trigger auto-associative recalls from this NGC graph. Note that this list takes the form: [(node1_name, node1_compartment, mask, value), node2_name, node2_compartment, mask, value),…]

• calc_delta – compute the list of synaptic updates for each learnable parameter within .theta? (Default = True)

Returns

readouts, delta;

where “readouts” is a 3-tuple list of the form [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…], and “delta” is a list of synaptic adjustment matrices (in the same order as .theta)

step(calc_delta=False)

Online function for simulating exactly one discrete time step of this simulated NGC graph given its exact current state.

Parameters

calc_delta – compute the list of synaptic updates for each learnable parameter within .theta? (Default = True)

Returns

readouts, delta;

where “readouts” is a 3-tuple list of the form [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…], and “delta” is a list of synaptic adjustment matrices (in the same order as .theta)

ngclearn.engine.proj_graph module

class ngclearn.engine.proj_graph.ProjectionGraph(name='sampler')

Bases: object

Implements a projection graph – useful for conducting ancestral sampling of a directed generative model or ancestral projection of a clamped graph. Note that when instantiating this object, it is important to call .compile(), like so:

graph = ProjectionGraph(…)

info = graph.compile()

Parameters

name – the name of this projection graph

apply_constraints()

Apply any constraints to the signals embedded in this graph. This function will execute any of the following pre-configured constraints:

1) compute new precision matrices (if applicable)

2) project weights to adhere to vector norm constraints

calc_updates(debug_map=None)

Calculates the updates to synaptic weight matrices along each learnable wire within this NCN operation graph via a generalized Hebbian learning rule.

Parameters

debug_map – (Default = None), a Dict to place named signals inside (for debugging)

clamp(clamp_targets)

Clamps an externally provided named value (a vector/matrix) to the desired compartment within a particular Node of this projection graph.

Parameters

clamp_targets –

3-Tuple containing a named external signal to clamp

node_name (Tuple[0])

the (str) name of the node to clamp a data signal to.

compartment_name (Tuple[1])

the (str) name of the node’s compartment to clamp this data signal to.

signal (Tuple[2])

the data signal block to clamp to the desired compartment name

clear()

Clears/deletes any persistent signals currently embedded w/in this graph’s Nodes

compile(batch_size=- 1)

Executes a global “compile” of this simulation object to ensure internal system coherence. (Only call this function after the constructor has been set).

Parameters

batch_size – <UNUSED>

Returns

a dictionary containing post-compilation information about this simulation object

extract(node_name, node_var_name)

Extract a particular signal from a particular node embedded in this graph

Parameters

• node_name – name of the node from the NGC graph to examine

• node_var_name – compartment name w/in Node to extract signal from

Returns

an extracted signal (vector/matrix) OR None if node does not exist

getNode(node_name)

Extract a particular node from this graph

Parameters

node_name – name of the node from the NGC graph to examine

Returns

the desired Node (object)

project(clamped_vars=None, readout_vars=None)

Project signals through the execution pathway(s) defined by this graph

Parameters

• clamped_vars – list of 2-tuples containing named Nodes that will be clamped with particular values. Note that this list takes the form: [(node1_name, node_value1), node2_name, node_value2),…]

• readout_vars – list of 2-tuple strings containing named Nodes and their compartments to read signals from. Note that this list takes the form: [(node1_name, node1_compartment), node2_name, node2_compartment),…]

Returns

readout values - a list of 3-tuples named signals corresponding to the ones in “readout_vars”. Note that

this list takes the form: [(node1_name, node1_compartment, value), node2_name, node2_compartment, value),…]

set_cold_state(batch_size=- 1)

set_cycle(nodes)

Set execution cycle for this graph

Parameters

nodes – an ordered list of Node(s) to create an execution cycle for

Module contents