4 Running the HTM Network

This chapter discusses the tasks involved in running an HTM Network. It explains how you can use the RuntimeNetwork API to invoke the NRE and looks at some examples.

Topics

Understanding Learning and Inference
Understanding the Runtime Network
Using the RuntimeNetwork Object to Perform Training
Using the RuntimeNetwork Object to Perform Inference
Training Your HTM Network: The Pictures Example

Understanding Learning and Inference

You can run your HTM Network in several ways:

During training, you use the RuntimeNetwork class to submit training data and an untrained HTM Network to the NRE.

After the training run, each node in the HTM Network knows about part of the domain and the trained HTM Network is a model of the domain world. You can save the trained HTM Network to a file.

During inference, the HTM Network uses the learned model to process inputs one level at a time. You use the RuntimeNetwork class to load the trained network into the NRE, specify the input and output data, and run the network.
During analysis and debugging, you use the RuntimeNetwork class to load the trained network into the NRE and then query the nodes for information about their trained state.

What Happens During Training

Training is the most complex of the three scenarios discussed above. During training, the NRE performs learning and inference on nodes at each level in the HTM Network. This section is a step-by-step introduction to the process; other sections in this chapter explains how you can implement it.

From the NuPIC point of view, the training process consists of these steps:

1. The script creates a RuntimeNetwork. CreateRuntimeNetwork expects an untrained HTM Network as the argument (usually a previously saved HTM Network file). CreateRuntimeNetwork also expects training files that you must make available to the NRE.

2. The script initializes the sensor with input data from a file. In many cases, the script also initializes the CategorySensor with a file.

3. The script calls RuntimeNetwork.run() for each level of the HTM Network using a run policy.

Training is done one level at a time:

a. First, you train the bottom level using the input data.

b. Next, the NRE performs inference on the bottom level, sends the resulting groups to Level 2 and performs training on Level 2.

c. Next, the HTM Network performs inference on Level 2 and performs training on Level 3, and so on.

The script uses a run policy which handles the details of setting each level's mode (learning or inference).

4. If a category file was submitted, the top-level node uses the category information during learning.

Understanding the Runtime Network

RuntimeNetwork allows you to train and test your HTM network and to perform additional analysis on individual nodes. RuntimeNetwork launches the NRE, loads an HTM Network, and provides an interface that allows you to manipulate the HTM Network at runtime. If you need more direct control over communication with the NRE you can use the Session API, discussed in Running HTM Networks With Sessions, page 59 in Advanced NuPIC Programming.

A RuntimeNetwork instance has these components.

A Network object that contains the nodes, links, and regions that define the structure of the HTM Network (see Constructing an HTM Network). When you create a RuntimeNetwork, you specify the Network explicitly or specify an HTM Network XML file for loading the network.
A Session object that interacts with the Numenta Runtime Engine. When you use RuntimeNetwork, you don't need to specify the Session explicitly. Instead, RuntimeNetwork creates a session and manages it for you. See Sessions and NRE Supervisor, page 54 in Advanced NuPIC Programming for more information.
A temporary directory called a session bundle that stores files needed by the NRE.

The RuntimeNetwork object has the following associated function and methods:

Table 4: Using RuntimeNetwork

Function/Method	Description
CreateRuntimeNetwork	Creates a RuntimeNetwork instance. Takes as arguments the name of a network file, additional files required by the NRE, and any NRE configuration options. runtimeNet = CreateRuntimeNetwork (<filename>, [files = ...)
RuntimeNetwork.run()	Initiates the computation of selected HTM nodes in the NRE and waits for that computation to complete. See What RuntimeNetwork.run() Does.
RuntimeNetwork.getElement()	Accesses nodes or regions at runtime. See Accessing Individual Elements.
RuntimeNetwork.getParameter() RuntimeNetwork.setParameter()	Gets or sets accessible parameters on HTM nodes in the NRE.
RuntimeNetwork.execute()	Sends node-specific commands to individual nodes or regions in the NRE.

For detailed information you can use help from the Python command prompt. See Getting Node Help.

Accessing Individual Elements

While the NRE processes your HTM Network, you can access individual elements by calling RuntimeNetwork.getElement.

For example, you can load and initialize the sensors that were defined in the HTM Network file.

   sensor = runtimeNet.getElement("Sensor") 
   categorySensor = runtimeNet.getElement("CategorySensor") 
   
   sensor.execute("loadFile", trainingFile, "0") 
   categorySensor.execute("loadFile", trainingCategories, "0") 

What RuntimeNetwork.run() Does

When you call RuntimeNetwork.run(), the NRE runs computation for the specified number of iterations using optional selection or exclusion arguments.

If no selection is specified, the entire network will be enabled. You can also disable individual elements that would by default be enabled using the exclusion parameter. The names specified in the selection and exclusion arguments can refer to individual nodes or regions.

NuPIC supports a wide variety of node types and learning algorithms. Different learning nodes might require a RunPolicy instead of the number of iterations during training. For example, a Zeta1Node requires level by level training.

The following table shows some examples:

Example	Description
myNetwork.run(1000)	Run the entire network for 1000 iterations
myNetwork.run(1000, ["sensor", "level1"])	Run the sensor node and the region level1 for 1000 iterations
myNetwork.run(1, exclusion=["effector"])	Run the entire network, except for effector, for one iteration
myNetwork.run(Zeta1Train("level2", 1000),            selection = ["sensor", "level1", "level2"])	Run Zeta 1 training on the level2 region for 1000 iterations. Nodes with names "sensor" and all nodes in the level1 and level2 regions will be selected. Learning will be turned on for all nodes in level2.

Using the RuntimeNetwork Object to Perform Training

During training, each enabled node in the HTM Network reads its inputs and updates its internal model. Bottom-level and mid-level nodes perform pooling of patterns, but do not associate their groups with category labels. Over time, the HTM learns that certain patterns appear frequently and together in time.

If the learning nodes in your HTM Network are Zeta1Nodes, you can use the Zeta1Train run policy during training. Zeta1Train is a run policy specific to the Zeta1 algorithm, which requires that you train your network one level at a time. When training level L, the nodes at level L+1 and higher must be disabled. Nodes at levels L-1 and lower must be in inference mode. The Zeta1Train policy handles this Zeta1-specific logic.

The following example uses Zeta1Train to train an HTM Network.

1. Train your network one level at a time. For example, for a two-level network:

a. Call run() to perform training on Level1 nodes:

   runtimeNet.run(Zeta1Train("Level1", numVectors),  
                 selection=["Sensor", "Level1"]) 

b. Reset all sensors to make sure they start at the beginning of the file.

   sensor.setParameter("position", "0") 
   categorySensor.setParameter("position", "0") 

c. Call run() to perform training on Level2 nodes. During this run, the Level2 nodes take the information from the trained Level1 nodes as input.

   runtimeNet.run(Zeta1Train("Level2", numVectors),  
                             Selection = ["Sensor", "Level1", "Level2") 

2. Save the trained network file and clean up.

   runtimeNet.writeXML(trainedNetworkFilename) 
   runtimeNet.cleanupBundleWhenDone() 

Using the RuntimeNetwork Object to Perform Inference

After the HTM Network has been trained, you can perform inference. Inference is simpler because you are typically running the whole HTM Network. During inference, you submit data and a trained HTM Network to the NRE, which processes and categorizes the data.

You use the RuntimeNetwork object for inference as follows:

1. Create the RuntimeNetwork loading in the trained HTM Network you saved at the end of the training process and a set of data.

   runtimeNet = CreateRuntimeNetwork(trainedNetwork, files=[testFile]) 
 

In most cases, you perform inference first with the training data to verify that they are categorized correctly. You then perform inference with the test data. 

2. Retrieve the runtime object corresponding to the sensor and load the testFile file into that sensor runtime node.

   sensor = runtimeNet.getElement('Sensor') 
   sensor.execute('loadFile', testFile) 
 

Optionally, if the sensor is a vector file sensor, you can retrieve the number of vectors loaded in the previous command:

   numVectors = sensor.getParameter('numVectors') 

3. Set the filename so the effector outputs are stored:

   fileOutputEffector = runtimeNet.getElement('FileOutput') 
   fileOutputEffector.execute("setFile", resultsFile) 

4. Run the HTM Network. During inference, we exclude the category sensor because we want for the runtime engine to determine the categories.

   runtimeNet.run(numVectors, exclusion=["CategorySensor"]) 

5. Retrieve the results file and clean up.

   fileOutputEffector.execute("flushFile") 
   runtimeNet.getFiles(resultsFile) 
   runtimeNet.cleanupBundleWhenDone()

To perform inference with the Zeta1 algorithm, you run the network in order of level. No run policy is required because training has already been performed so no switch from training to inference is needed.

Training Your HTM Network: The Pictures Example

The basic pattern of creating the HTM Network structure, performing training using RuntimeNetwork, and performing inference using RuntimeNetwork is the same for all HTM Networks. The details might differ depending on the problem you're working with. Numenta includes a number of example programs to illustrate different approaches. This section briefly discusses the Pictures example.

The Pictures example performs training in a slightly unusual fashion. This section gives an overview of the training stages in the Pictures example. See the Pictures example itself for more details.

Stage 1: Training at the Bottom Level

The Pictures example uses an advanced learning technique of training a single node at each level and replicating its state to all the other nodes at that level. This approach is possible because the example sweeps across each training image. As a result, all bottom-level nodes would receive the same windowed images.

At the bottom level, training proceeds as follows:

1. Enable computation of a single bottom-level node and the Sensor.

2. Enable learning for that node.

3. Limit the window size of the Sensor (ImageSensor) to the receptive field of that node.

4. Calculate the number of iterations necessary to sweep the appropriately-sized window over all the training images. This number depends on the size of the image and the size of the window.

5. Compute for the full number of training iterations.

6. Disable learning and enable inference for that node.

7. Clone that node's state to all the other bottom-level nodes.

Stage 2: Training for Mid-Level Nodes

At the next level, training proceeds as follows:

1. Enable computation on a single mid-level node and on exactly the set of bottom-level nodes that provide inputs to that mid-level node (plus the sensor that feeds those nodes).

2. Enable learning for this single mid-level node.

3. Expand the sensor window as necessary to provide valid inputs to all of the enabled bottom-level nodes.

4. Reset the sensor to the first image and recompute the number of training iterations necessary to sweep over all the images with the new window size.

5. Compute for the full number of training iterations.

6. Disable learning for that node.

7. Enable inference for that node.

8. Clone the trained mid-level node's state to all the other mid-level nodes.

Stage 3: Training for Top-Level Nodes

For the top-level node, input from the preceding mid-level nodes and category information are used for training.

1. Enable computation of all nodes.

2. Enable learning for the top-level node only.

3. Expand the sensor window to provide valid inputs (that is, the entire image) to all bottom-level nodes.

4. Reset the sensor to the first image and recompute the number of training iterations necessary.

5. Compute for the full number of training iterations.

6. Disable learning for the top-level node.

7. Enable inference for the top-level node.