Programmer's Guide: The Code

Other than the Tcl/Tk libraries, which are in the TclTk/ directory, the code for Lens is all located in the Src/ directory. This guide briefly describes the contents of each of the source files.

Makefiles

The Makefile in the main Lens directory defines the machine-specific compiler and flags. It also determines the flags used when compiling the different versions of Lens: lens, alens, liblens, and libalens. If Lens doesn't compile properly, you may need to customize the header of that file to your machine and/or add special definition in sysext.h to fix compatibility problems with the C libraries on your system.

The Makefile in the Src/ directory defines the dependencies for each code module and sets the version number used thoughout the simulator. You may want to make a private copy of this file just so you can maintain your own version names. That way, when you start Lens and it prints the version number, you will know you are running the right one.

C Files

The Lens code is fairly cleanly partitioned, although data structures are not strongly protected and virtually all modules have access to the internals of the network structures. Within a module, the *.c file contains the important code. The *.h file defines any data structures primarily under the control of the module but used elsewhere. It also contains declarations of functions and variables defined within the module that can be called from the outside. Finally, it may contain #define macros or constants used both inside and outside the module.

The *Com.c file defines and registers the C functions that will become shell commands. These are essentially intermediaries between the shell commands and the underlying code. The functions in the *Com.c file should mainly do error checking and argument parsing and then call other functions in the *.c file to do the real work.

The following is a brief description of each of the C source files:

system.h

This mainly contains #defines. It sets limits on the sizes of common static arrays and contains all of the machine-specific definitions that affect such things as the representations of NaNs, transformations from host to network byte ordering, and whether single- or double-precision floating point is used.

sysext.h

You should place any machine-specific customizations that alter the defaults from system.h in here. It will not be overwritten when you download a new source distribution.

main.c

This contains the code that interprets command line arguments and initializes the simulator. It is the only module not included when the Lens library is compiled.

library.c, lens.h

This module is include in place of main.c when Lens is compiled as a library. It defines the startLens() and Lens() commands that are the main interface to the library. lens.h is the header file for the library.

type.h, type.c

These files define the "type" bitmasks that are used throughout the code. These include network, group, unit, and link types, types of projection creation patterns, example selection modes, noise types, and training algorithms. The header file defines the bitmasks for each type and the code file, type.c, contains commands for registering types and an initialization procedure that registers all of the built-in types. It also contain the function cleanupGroupType() that ensures that group types are coherent.

If you want to add new types, you should add them to type.h to be sure they don't conflict with the types provided. The type.h file will not be overwritten when you download a new source distribution and you should merge your additions with the new type.h file, if it has changed.

util.h, util.c

This contains all of the helper utilities that are used throughout the code, including commands for returning Tcl messages as errors and results, evaluating Tcl commands from within C, allocating stuff in a safe manner, working with the "String" datatype, opening and closing files, low-level commands for parsing files such as example files, generating random numbers and other math functions, producing noise, and some things that depend on system calls, such as time. Basically, if a function is relatively simple or low-level and may be used in more than one module, it goes in here. Furthermore, any machine-specific code than is not handled in system.h is put in here.

defaults.h

This contains a number of #define constants that set the default values for various fields in the objects and some parameters that control the behavior of Lens, such as how frequently the display is updated. Rather than editing this file, you may want to customize your version by using the .initNetwork, .initGroup and other procedures in the .lensrc file.

extension.h, extension.c

This is where most user-defined code should go. The default versions basically contain empty templates for adding fields to the extension records of various structures, adding new C functions that use those structures, and registering those as Tcl commands. If you make a large number of additions to extension.c, you may want to create some new modules and add those modules to the Makefile in the Src/ directory or just #include them in extension.c.

network.h, network.c, networkCom.c

This module defines the data structures for networks, groups, units, and links. Any commands that deal primarily with networks, groups, and units, but not links, are located here. Mainly these deal with building and destroying parts of networks. network.h contains macros for iterating over the network in various ways, making it very easy to write looping code.

connect.h, connect.c, connectCom.c

This does not define any data structures but implements a number of commands used in creating, destroying, randomizing, freezing, and saving and loading links and their weights.

example.h, example.c, exampleCom.c

This defines the data structures used to store example sets and the procedures that operate on them. It contains the code for loading and saving example sets, choosing examples and loading them into the network, and writing network output files.

train.h, train.c, trainCom.c

This contains the code used in updating weights during training. It defines the data structure and commands used to register a new weight update algorithm and contains the code for the built-in algorithms. Otherwise, the standardTrainNet() function is the one of interest in this module. It controls the presenting of batches of examples to the network, updating weights, and printing reports.

act.h, act.c

This may be the most interesting module to the programmer. It contains all of the code used in doing the forward and backward passes in the network. Everything from the processing of a single batch to calculating a unit's input is in here. The main functions of interest are standardNetTrainBatch(), standardNetTestBatch(), and standardNetTestExample(), which train the network on a batch, test the network on a set of examples, or run the network on a single example. The command configureProcs() sets the group updating and backpropagation procedures based on the group types. This module also defines and makes available some low-level procedures for operating on inputs, outputs, and targets.

object.h, object.c, objectCom.c

This module allows the C structures to be accessed from the Tcl shell. object.h defines ObjInfo and MemInfo structures that are used in registering fields in the C structures so they can be traversed and displayed with the getObject and setObject commands and the Object Viewer.

object.c defines the newObject() and addMember() functions that can be used to make any user-defined data structures accessible. It also uses these commands to describe all of the main Lens structures, including networks and their parts, example sets and their parts, and low-level types such as integers and strings. The lookupObject() function is used to traverse the object tree and printObject() is used to print the tree to a particular depth.

parallel.h, parallel.c, parallelCom.c

This handles parallel training. Because parallel training requires maintaining consistent state while receiving asynchronous messages and the ability to recover from faults such as disconnected clients, the code in here is pretty complex. You probably don't want to mess with it until you are very familiar with the pecularities of coding with Tcl libraries and interpreters.

command.h, command.c

This module defines new Tcl commands that don't really fit into other modules, such as ones that do low-level system or shell things, like nice and seed. It also calls the functions, located in the *Com.c files, to register all of the other Tcl commands.

control.h, control.c

This contains some of the commands used to interface between C and the Tcl interpreter. It defines the functions for registering C functions as Tcl commands, and commands to tell the interpreter when the network or training sets have changed so the displays can be updated. It also deals with tasks and has the code for handling interrupt signals.

display.h, display.c, displayCom.c

This contains the code for building and updating the pictures of the network in the Unit and Link Viewers.

canvRect.h, canvRect.c

This defines a new type of Tk canvas object used in the Unit and Link Viewers. It is similar to a rectangle but optimized for fast updates.

graph.h, graph.c, graphCom.c

This updates the information in the graphs.

tkConsole.c

This is a modified version of the standard TclTk module. It handles the graphical console.

Tcl Files

shell.tcl

This customizes aspects of the shell and defines shell commands, including code used to register C commands, display command help pages, create command aliases, do completion of unknown commands, and contains the front ends to some of the training and testing procedures. Unlike most of the Tcl files, this is used even in batch mode.

lensrc.tcl

This contains definitions that customize the look and feel of Lens. Rather than making changes directly to this, you can override its definitions in your own .lensrc file in your home directory.

init.tcl

This is a slightly modified version of the standard Tcl init.tcl file. It contains modifications to the command indexing code. It is used in batch mode as well.

auto.tcl

This is a slightly modified version of the standard Tcl auto.tcl file. This also contains some improvements to the indexing code. It is used in batch mode as well.

interface.tcl

This builds the main Lens display. Unlike the other Tcl files defining displays, this will rebuild the display whenever it is sourced.

display.tcl

This defines commands which build the Unit and Link Viewers.

graph.tcl

This builds the graphs.

object.tcl

This builds the object viewers.

file.tcl

This handles requests for doing file operations, such as loading example files, saving and loading weights, and printing viewers or graphs. It usually calls the fileselect box and then does error checking.

fileselect.tcl

This was a generic file browser that has been improved for Lens. You might want to borrow this if you write any other Tcl applications.

console.tcl

This defines the operation of the graphical console.