3 Running HTM Networks With Sessions

Running the HTM Network in Getting Started With NuPIC explains how you can run an HTM Network using either RuntimeNetwork.run() or the RunBasicNetwork() helper function.

This chapter explains how you can use the Session API to interact with the NRE and how you can explicitly turn on learning or inference for certain levels. Using sessions is required only if you want to access some of the advanced features of NuPIC. For example, using sessions makes sense when running on clusters. This chapter lays the groundwork to the topics discussed in Using the Numenta Runtime Engine: Advanced Topics.

In the last section, the chapter gives supplementary information about RuntimeNetwork.run().

Topics

Running HTM Networks: Options
Understanding the Training Process
Using the Session API to Run Your HTM Network
What RuntimeNetwork.run() Does
Accessing Session Information at Runtime

Running HTM Networks: Options

You perform training and inference by running the HTM Network. There are a number of options:

Use the RunBasicNetwork() and RunBasicNetwork() helper functions used by the Bitworm example.
Create a RuntimeNetwork instance from the Network you created, then call RuntimeNetwork.run(). See Running the HTM Network in Getting Started With NuPIC for a discussion and examples.
Use a session to run the HTM Network. See Using the Session API to Run Your HTM Network.
For large HTM Networks, advanced users can use multi-CPU machines or clusters. See Using the Numenta Runtime Engine: Advanced Topics.

After you have defined the structure of the HTM Network, you perform training and inference. During training, there are two choices:

Supervised learning - If you know which of your data points belong to which category, you can train the HTM Network using a category file. After training is complete, the HTM Network has assigned each input data point to a category.
Unsupervised learning - If you don't know the categories in your problem, the NRE still groups the data in your training data set. After training, the NRE will then assign each data point to one of the groups it decided on during training.

After the HTM Network has been trained, you can submit the trained network and new data to the NRE for inference.

Understanding the Training Process

During training, the nodes in the HTM Network perform learning and inference. This section gives an overview of the process, which is illustrated in the bitworm_session example. In contrast to Getting Started With NuPIC, which uses RuntimeNetwork, the focus of this section is on sessions.

From the NRE's point of view, the training process consists of these steps:

1. The user loads an untrained HTM Network file. The file contains the classes, links, and other information that the NRE needs to load the network.

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

3. The script that runs the HTM calls the Session constructor, then calls Session.start(). In response to the call, the NRE creates a session and creates the HTM Network, the specifies node instances, and the links.

4. The session feeds the sensor data file to the HTM Network.

5. The NRE trains the HTM Network, one level at a time:

a. Trains the bottom level using the input data.

b. Performs inference on the bottom level, sends the resulting groups to the next level and performs training on that level.

c. Performs inference on Level 2 and performs training on Level 3, and so on.

6. If a category file was submitted, the classifier node uses the category information during learning. Otherwise, the classifier node groups the data based on the input data and the parameter settings.

Using the Session API to Run Your HTM Network

This section explains how you can use the Session API to run your HTM Network on a single CPU, using fragments from the bitworm_session example.

Starting the session and running the HTM Network are two separate tasks. You must perform all session startup tasks before you can run the network.

Before you can run the HTM Network, you must configure its structure. See Constructing an HTM Network in Getting Started With NuPIC for information.

Starting the Session

Starting the session includes creating the Session object, adding the required files to the Session, and calling the start() method.

To start the session:

1. Import the session-related classes:

   from nupic.network import Session, SessionConfiguration  

2. Create a session instance:

   mySession = Session("dir/subdir/mysession") 
 

This call returns a Session object; however, it does not start the NRE yet. Upon creating the session, the system creates a directory called mySession.<num>.local_bundle where it stores files related to the runtime engine. For the example above, a directory called dir/subdir/mysession.1.local_bundle is created. See Sessions and Session Bundles for background information. 

You can customize the session by setting SessionConfiguration parameters before you actually start the session. See SessionConfiguration Object Methods.

3. Add the files the session needs, such as training data and category files, using the addFiles method, which has the following prototype:

   mySession.addFiles (<origin>,<destination> ) 
 

The addFiles() method copies the file(s) specified by <origin> to <destination>. If no destination is specified, it copies the files into the main session bundle directory, and preserves the original file names. Here's a code fragment from the Bitworm example: 

   session.addFiles("training_data.txt") 
   session.addFiles("train_catsensor.txt") 

4. Start the session.

   mySession.start() 
 

This command launches the runtime engine with the default configuration inside the bundle. The bundle's top level is now considered the working directory. The log files are placed in a subdirectory called session_log. See Table 3:, Session log files. 

 

There is a log file for each process. The Supervisor and each NP have a separate log file. These files are named logS0.txt, logN1.txt, and so on. A file called stdout.txt contains the combined information from all processes. 

 

The call to start() places a single script file called launch.py into the bundle's session_resources subdirectory. This script is complex, and is kept in the bundle to facilitate troubleshooting.

Running the HTM Network

This section first gives an overview of low-level details of running an HTM Network. It then illustrates how the bitworm_session example actually runs the network.

Low-level Session Interaction

A program that does not want to take advantage of the higher-level APIs can run the HTM Network as follows:

1. Load the HTM Network file:

   mySession.loadNetwork(<filename>)

Here, <filename> refers to an HTM Network on your local file system that you've already created. See Constructing an HTM Network in Getting Started With NuPIC.

If you'd like to avoid copying the network into the session bundle, you can use the optional copyHint parameter to loadNetwork(), which defaults to true.

   mySession.loadNetwork(self, path="net.xml", copyHint) 
 

If you're running your HTM Network remotely, the network must be copied. 

2. Interact with the nodes in the HTM Network. You can call the following methods:

Session.execute (node_regx, command)	Call Session.execute() to send an execute command directly to a set of nodes. For example: session.execute('level1', ('setInference', '1')) session.execute('level1', 'resetHistory') For help for all Supervisor commands, type the following at the Python command line:    from nupic.network import Session    mySession = Session ('test')    mySession.start()    mySession.sendRequest('help') To get help on a specific command, call mySession.sendRequest('help <cmdName>').
Session.disableNodes (node_regx) Session.enableNodes (node_regx)	When the NRE runs, it executes each enabled node's compute() method. By default, all nodes are enabled. The disableNodes()/enableNodes() methods disable or re-enable the specified nodes. node_regx is a regular expression that selects nodes. You can disable/enable individual nodes within levels. For example, during training, the Pictures example program enables one node at a level and disables the rest for faster performance. Usually, you enable individual nodes by first disabling all nodes, and then individually re-enabling desired nodes, but that approach is not required.
Session.compute (num_iter, wait)	Cycles through enabled nodes the specified number of times. Does not return until all compute() methods finish. The wait parameter is advanced. If set to True (the default), the call does not return until all computation completes. If False, the call returns immediately, even though computation has only been started. Changing this parameter is not recommended.

3. After computation is complete, you can save the trained HTM Network to a file.

   Session.saveRemoteNetwork(<filename>) 
 

This method tells the NRE to save the current state of the network to an HTM Network file. The file is stored inside the bundle. Specify a filename that is relative to the bundle directory.

4. Call stop() to stop the NRE.

   Session.stop() 

5. Copy the HTM Network file to a location outside the bundle.

   Session.getLocalBundleFiles( <origin>, <destination>) 
 

Extracts the specified file(s) from the local bundle and puts it in the specified directory (local directory by default). Identical to the Unix cp command. 

6. If you wish, you can tell the session to delete the local bundle upon completion:

   Session.setCleanupLocal() 
 

By default, the session does not clean up the bundle directory, so that users can examine its contents for debugging purposes. But if you plan to copy any files you need using Session.getLocalBundleFiles(), you can use Session.setCleanupLocal() to tell the session to remove the bundle when it is done. The bundle is removed only when the session object is deleted (which occurs if your script finishes, or the Session instance goes out of scope, or you delete the instance manually). The bundle is not deleted immediately upon calling Session.setCleanupLocal(), nor upon calling Session.stop().

See How to Use NuPIC in Complex Configurations for information on running in a multiprocessing environment.

Performing Learning in the Bitworm Example

In the Bitworm example, the training script TrainNetwork.py performs the following tasks:

1. Disables all nodes.

   session.disableNodes() 
 

By default, all nodes are enabled after the HTM Network has been loaded. Bitworm then enables nodes selectively.

2. Enables learning for the Sensor and the Level1 nodes.

   session.enableNodes("Sensor") 
   session.enableNodes("Level1") 

3. Runs the compute() method of all enabled nodes, once for every input vector.

   session.compute(numVectors) 

4. Disables learning and enables inference for the Level1 node.

   session.execute('Level1', ['setLearning', '0']) 
   session.execute('Level1', ['setInference', '1']) 

Performing Learning and Inference in the Bitworm Example

As the second part of training, you turn on inference for Level 1 and learning for Level 2. While Level 1 is in inference mode, it passes the information it deduced to the next level. Level 2 can then perform learning on those outputs.

Switching between learning and inference mode for the different levels is the appropriate way to train your network. Each Level has to complete learning before it can go into inference mode and hand off its data to the next level. Each level is trained once. Higher-level tools (RuntimeNetwork, RunBasicNetwork()) enable and disable nodes automatically. The Session API requires you enable and disable explicitly.

The program implements this as follows:

1. Returns the sensor and category sensor to the beginning of the training data.

   session.execute("Sensor", ("seek", "0")) 
   session.execute('CategorySensor', ("seek", "0")) 

2. Enables the Level 2 node (the Level 1 node is already enabled). With inference enabled earlier for Level 1, turn on learning for Level 2.

   session.enableNodes("Level2") 
   session.execute('Level2', ['setLearning', '1']) 

3. Runs the training cycles for Level 2 and finishes learning. Because the Level 2 node in Bitworm is a Zeta1TopNode, it performs classification as part of learning, that is, it attempts to map the input from the previous level to the categories in the category file.

   session.compute(numVectors) 

4. Turns off learning and turns on inference for the Level 2 node.

   session.execute('Level2', ['setLearning', '0']) 

Using Session.execute() to Access Nodes or Execute Commands at Runtime

You can retrieve and set node parameters at runtime using Session.execute(), for example:

mySession.execute('myNode', ['setParameter', 'transitionMemory', '4'])  
mySession.execute('myNode',['getParameter', 'coincidenceCount']) 

You can also execute certain commands, for example:

mySession.execute('myNode', 'pruneCoincidences') 

Use nodeHelp for the individual nodes for detailed information.

Sessions and Session Bundles

A typical session makes use of several files. To organize these files for easy transfer, analysis, and cleanup, the session manages a session bundle: a single file system directory created by the Session instance. The bundle is created immediately on session instantiation. Session methods allow you to add files to the bundle, extract files from the bundle, copy the bundle to and from a remote host, and clean up the bundle when it is no longer needed.

The Session instance creates a local bundle. The bundle holds all files associated with a single conceptual NRE session. The bundle includes configuration scripts, working inputs and outputs, and log files on the local file system. You must specify the location of the bundle on the file system when you create the Session instance using the constructor.

Because the runtime engine can be launched on a remote host, the local bundle might not be accessible to the remote NRE processes. Instead, the session instance copies the local bundle to the remote host with a file synchronization utility (rsync on Unix-like systems). This works as long as the local machine has secure-shell (ssh) access to the remote host.

The following screen shot shows the bundle layout for a typical session:

Figure 8 Session Bundle Example

The bundle directory functions as a working directory for the NRE. All relative paths used by the NRE refer to paths starting in the bundle directory. Files written to or read from relative paths refer to files stored in this directory. This includes paths used to load and save network and data files.

By default, the bundle directory is populated with a number of files and directories when you create the session:

The session_resources subdirectory holds configuration files and other immutable files that the NRE needs, but that do not change during the lifetime of the session. The launch script (launch.py) is saved into this directory.

When there is a remote bundle, this directory does not need to be synchronized after startup because the NRE does not modify files in the session_resources directory.

The session_log subdirectory holds log outputs from the NRE processes. The log subdirectory is always synchronized in the opposite direction, from the remote bundle to the local bundle. See Table 3:, Session log files.

When there is a remote bundle, the NRE always copies this directory back to the local bundle upon NRE shutdown.

Bundles and Remote Hosts

If the NRE is launched on a remote host, the main bundle directory is synchronized just before launch from the local bundle to the remote bundle, in case input files are stored in the local bundle. At any time during the session lifetime, you can add new files to the local bundle's main directory and synchronize to the remote side using the Session API. Similarly, if periodic updates of the remote outputs are needed locally, you can explicitly synchronize the local bundle with the remote bundle. When the remote NRE is shut down, the main directory and the log directory are synchronized back from the remote bundle to the local bundle. In this way, the local application can access all NRE output files.

Loading Networks Without Copying them into Bundles

You can load an HTM Network without copying it into a bundle by using the copyHint flag to Session.loadNetwork:

mySession.loadNetwork(self, path="net.xml", copyHint=True) 

When copyHint is true, (the default), the HTM Network file is copied into the bundle. When copyHint is false, the network is not copied into the bundle. This parameter is only a hint. If there is a remote bundle, the HTM Network File must be copied regardless of the value of the flag.

What RuntimeNetwork.run() Does

While all other sections in this chapter dealt with sessions, this section gives some advanced information on RuntimeNetwork, which is discussed in Running the HTM Network in Getting Started With NuPIC.

When you call RuntimeNetwork.run(), the NRE runs computation on a selected subset of the network for the specified number of iterations.

Simple Scenarios

In the simple case the user specifies an iteration number and optional selection or exclusion arguments. The names specified in the selection and exclusion arguments can refer to individual nodes or regions. 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.getElement("sensor").run(1)	Run the sensor node for one iteration
myNetwork.run(1, exclusion=["effector"])	Run the entire network, except for effector, for one iteration
myNetwork.run(10, ["sensor", "level1", "level2[0]"], exclusion=["level1[1,0]""])	Run sensor, the region level1 with the exception of node level1[1,0], and the node level2[0], for ten iterations.

Scenarios With Run Policies

NuPIC supports a wide variety of node types and learning algorithms. Different learning nodes might require complex run schemes during training. To support this, the run method can accept a RunPolicy.

The following table shows some examples with Zeta1Node an older node that is still supported:

Example	Description
myNetwork.run(TrainPhase("level2", 1000),            selection = ["sensor", "level1", "level2"])	Train the level2 region for 1000 iterations using the default algorithm. 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.
myNetwork.run(TrainPhase("topLevel", 1000), exclusion=["effector"])	Train the top level for 1000 iterations using the default algorithm. All nodes in the network will be selected, with the exception of effector.
myNetwork.run(UntilException())	Run all nodes in the network continuously until an exception occurs. Common run policies include TrainPhase, SimpleCompute, and UntilException. See the Python documentation for these policies for more details.

RuntimeNetwork.run() Parameters

You can call RuntimeNetwork.run() with the following parameters:

Parameter	Type	Description
runPolicy	integer or RunPolicy	If an integer, specifies the number of iterations to run on the selected nodes. If a run policy, hands off the RuntimeElement, its attached Session, and the selection information to the run policy, which determines how many iterations to run and what nodes to enable.
selection	list of strings (optional)	Relative names of the elements to enable. If None, the entire NetworkElement will be enabled.
exclusion	list of strings (optional)	Relative names of the elements to disable. Only necessary to disable elements that would be enabled through the current NetworkElement or the selection parameter.

Accessing Session Information at Runtime

You can interact with sessions and examine node content at runtime. You can also later access the logs generated by the NRE.

Interacting with Sessions

You can interact with sessions as follows:

Retrieve individual outputs, using the nodeOPrint Supervisor command. You can call Supervisor commands using the Session.sendRequest() method, for example:

   mySession.sendRequest('nodeOPrint <nodeName>') 
 

For help for all Supervisor commands, type the following at the Python command line: 

   from nupic.network import Session 
   mySession = Session ('test') 
   mySession.start() 
   mySession.sendRequest('help')  
 

To get help on a specific Supervisor command, call mySession.sendRequest('help <cmdName>'). 

Call Session.execute() to send a command directly to a set of nodes. For example:

   mySession.execute('level1', ('setInference', '1'))  
   mySession.execute('level1', 'resetHistory') 
 

You can call mySession.execute('<nodeName>', 'getCoincidences') to retrieve the coincidence matrix from the node. 

Instead of issuing session commands repeatedly, you can iterate through them as follows:

   for k in range (0, numIterations): 
      compute(1) 
      self.session.sendRequest ('nodeOPrint sensor') 
      self.session.sendRequest ('nodeOPrint level1\[0,0]') 
 

Then review the session_log/stdout.txt file to verify that you are getting reasonable results. 

Run mySession.compute(1) to perform a single computation on all nodes, then retrieve information from a node to see how it changed during that one computation.

Examining Node Content

You can check the number of coincidences and groups at each level and after each chunk of training data.

self.session.execute ('level1\[0,0]', 'getNGroups') 
self.session.execute ('level1\[0,0]', 'getNCoincidences') 

Check the ratio of coincidences and groups at each level.

Using Visualizer, plot coincidences at each level and plot groups (see Using HTM Network Visualizer in Getting Started With NuPIC). In an HTM that works well, you should expect a balanced histogram of group sizes. You usually don't want one or two huge groups and dozens of twin or singleton groups.

Look At Output Information

This section explores a few things you can check after you have run your application.

Examining Scripting/Session Commands

When you're not sure what's happening, you can look at the log files and any print statements you included in your program. For example, you can check the session_resources/launch.py script and the corresponding session_log/launch.txt file to see whether startup proceeded as expected.

To see whether things are scheduled appropriately, see the session bundle's /log directory for Supervisor commands.

Check whether each level is being trained appropriately. Each level should go though learning, then inference. If you're using RuntimeNetwork, these steps are followed automatically. If you're performing training and inference explicitly, see the bitworm_session example's TrainNetwork script.

Examine numbers at each level to see whether a level or a node is not getting scheduled.

Log Files

Each time you use the NRE, information is added to the logs. This information can be useful, for example, if you don't get any results.

The logs are especially useful to plug-in developers. Because plug-in developers create their own nodes, they might experience NRE crashes if errors exist in their nodes.

After a session has stopped, the following log files are available in the local session bundle directory (session_log). Currently, the stdout.txt log is the most useful log file. The rrlog.txt log is also useful, it records node requests and responses.

Table 3: Session log files

File	Description
rrlog.txt	Transcript of all requests sent to the Supervisor and all responses received back. Also useful for troubleshooting and for confirming your HTM Network is operating as expected.
launch.txt	Transcript of the commands issued to launch the Supervisor.
stdout.txt	Integrated "standard" output from the launcher, MPI, the Supervisor and all Node Processors. This file is especially useful if you are developing your own sensor, effector, or learning node plugin.
log.S0.txt	Log file generated by the Supervisor while it was running.
log.N1.txt	Log files generated by the first node processor while it was running.
log.N2.txt, ...	Log file generated by additional node processors if they existed.

The launch.py File

The call to Session.start() places a single script file called launch.py into the bundle's session_resources subdirectory. This script is complex, and is kept in the bundle to facilitate troubleshooting. The script might have useful information if your session does not seem to start at all, or if it starts but does not seem to be processing the input.

If you're using RuntimeNetwork, the session created by RuntimeNetwork creates the script.