OPF Code Review (29 Aug 2011)

Engineering NuPIC
, ,
1

###Warning: page contains outdated information
We have retained this page for historical reasons.

This page provides some guidance to code reviewers of the initial OPF implementation.

Changes from the Initial Draft of the OPF Architecture Overview Document

The primary change from the OPF Architecture overview document is that OPF Controller’s responsibilities were moved to the “Worker Shell” (e.g., run_opf_experiment, Grok Hypersearch/Production worker). In particular, this concerns ownership of the main control loop: the Worker Shell will now read input records (when and from wherever it deems appropriate) and simply push one record at-a-time into the model via OpfExperiment class instead of having OPF pull the records via its own loop. This change provides more flexibility to the Worker Shell (in terms of how it manages its input/output data streams) and simplifies OPF.

OPF Directories and Modules

trunk/examples/opf/experiments

Contains description.py files that describe OPF-based experiments. NOTE that the format of these description files will change (significantly). Presently, they are using a low-level representation (versus LPF’s descriptionTemplate-based description.py files) that will also change as we finalize the settings.

trunk/examples/opf/bin

run_opf_experiment.py: top-level script for running a single experiment and model checkpointing support. Replaces LPF’s RunExperiment.py.

trunk/py/regions

OPF replaced CLARegion that contained SP and TP with two separate regions that give OPF’s CLAModel better control over SP and TP. The new SP and TP regions are implemented in:

  • SPRegion.py
  • TPRegion.py

trunk/py/nupic/frameworks/opf

source file description
opfexperiment.py Implements OPFExperiment class, which is presently a light-weight host for the underlying model. Provides support for instantiation, saving/loading a model from, and command-handling. NOTE: the command-handling functionality will soon be replaced by direct method calls into OPFExperiment instance – this decision corresponds to movement of the control (“pull”) loop out of OPF.
descriptionapi.py A temporary (place-holder) implementation of DescriptionAPI interface and implementation classes. DescriptionAPI provides access to an individual experiment’s description.py file (this class replaces the legacy getBaseDatasets/getDatasets/getDescription functions that were used in LPF). This will be re-written once we formalize description.py format for OPF.
model.py Defines ModelIface - an abstract base class that defines the Model interface
clamodel.py CLA-based implementation of ModelIface
modelfactory.py Object factory for instantiating model instances
opfhelpers.py Helper classes for using the OPFExperiment class
opfutils.py Misc. shared data structures and utility classes/functions.
opfenvironment.py A collection of interfaces (abstract base classes) that define OPF’s interface to the external environment (prediction logging, metrics logging, python logging initialization, etc.). NOTE: EnvironmentAdapterIface class will be going away after python logging initialization support is extracted from it. NOTE: DatasetReaderIface will also go away, since the Worker Shell is now responsible for reading records directly, obviating the need for this interface.
opfbasicenvironment.py File-based implementation of interfaces that are defined in opfenvironment.py. These are used by run_opf_experiment.py
opfexperimentcommands.py Defines commands supported by OPFExperiment class. NOTE: This module will go away shortly, once commands are replaced by OPFExperiment methods – this upcoming change corresponds to the decision of moving the control loop from OPFExperiment out to the worker “shell” (worker’s top-level logic).
metrics.py Defines OPF’s prediction metrics interface and implements several prediction metrics algorithms.
predictionmetricsmanager.py Manages a collection of temporal and non-temporal metrics collectors.
opftaskphasedriver.py Implements OPFTaskPhaseDriver class. OPFTaskPhaseDriver manages the phase-based OPF task cycle workflow (e.g., learn for M iterations, infer for N iterations, repeat); it accepts a record as input and generates model workflow(s) corresponding to the current phase of the task’s cycle.
modelcallbacks.py Reusable OPF task callbacks that apply to any ModelIface-based model. These callbacks are used for experimentation/research/testing.
clamodelcallbacks.py Numenta CLA-specific OPF task callbacks that apply only to CLAModel. These callbacks are used for experimentation/research/testing.

trunk/py/nupic/frameworks/opf/jsonschema

This directory contains JSON schema files that describe various parameters shared by OPF.