NGCGraph

An NGCGraph represents one of the core structural components of an NGC system. This particular object is what Node(s) and Cable(s) are ultimately embedded/integrated into in order to simulate a full NGC process (key functions include the primary settling process and synaptic update calculation routine). Furthermore, the NGCGraph contains several tool functions to facilitate analysis of the system evolved over time.

NGC Graph

The NGCGraph class serves as a core building block for forming a complete NGC computational processing system.

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

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

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

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

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

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

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

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

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)

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)

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)

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

clear()

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