Example implemented using NetworkAPI

src/CMakeLists.txt

@@ -185,6 +185,7 @@ set(examples_files
     examples/hotgym/Hotgym.cpp # contains conflicting main()
     examples/hotgym/HelloSPTP.cpp
     examples/hotgym/HelloSPTP.hpp
+    examples/hotgym_NetworkAPI/hotgym_napi.cpp
     examples/mnist/MNIST_SP.cpp
 )
 
@@ -356,6 +357,30 @@ else()
 		${EXTERNAL_INCLUDES}
 		)
 endif()
+
+#########################################################
+## NetworkAPI version of hotgym
+
+set(src_executable_hotgym_napi hotgym_napi)
+add_executable(${src_executable_hotgym_napi} examples/hotgym_NetworkAPI/hotgym_napi.cpp)
+# link with the static library
+target_link_libraries(${src_executable_hotgym_napi} 
+    ${INTERNAL_LINKER_FLAGS}
+    ${core_library}
+    ${COMMON_OS_LIBS}
+)                  
+target_compile_options( ${src_executable_hotgym_napi} PUBLIC ${INTERNAL_CXX_FLAGS})
+target_compile_definitions(${src_executable_hotgym_napi} PRIVATE ${COMMON_COMPILER_DEFINITIONS})
+target_include_directories(${src_executable_hotgym_napi} PRIVATE 
+		${CORE_LIB_INCLUDES} 
+		${EXTERNAL_INCLUDES}
+		)
+add_custom_target(hotgym_napi_run
+          COMMAND ${src_executable_hotgym_napi}
+          DEPENDS ${src_executable_hotgym_napi}
+          COMMENT "Executing ${src_executable_hotgym_napi}"
+          VERBATIM)
+
 #########################################################
 ## MNIST Spatial Pooler Example
 #

src/examples/hotgym_NetworkAPI/README.md

@@ -0,0 +1,80 @@
+# C++ example using Network API
+The program `hotgym_napi` is an example of an app using the Network API tools available in the htm.core library.  In this example we generate a sin wave with some noise as the input.  This is passed to an encoder to turn that into SDR format.  This is passed to two instances of SpatialPooler (SP), one is configured for local inhibition and one for global inhibition.  The output of the SP for global inhibition is passed on to the temporalMemory (TM) algorithm.  The output of the TM can be written to a file so that it can be plotted.
+
+```
+  ///////////////////////////////////////////////////////////////
+  //
+  //                 .------------------.
+  //                 |    encoder       |
+  //         data--->|  (RDSERegion)    |
+  //                 |                  |
+  //                 `------------------'
+  //                     |           |
+  //      .------------------.    .------------------.
+  //      |   SP (local)     |    |   SP (global)    |
+  //      |    (SPRegion)    |    |   (SPRegion)     |
+  //      |                  |    |                  |
+  //      `------------------'    `------------------'
+  //                                       |
+  //                              .------------------.
+  //                              |      TM          |
+  //                              |   (TMRegion)     |
+  //                              |                  |
+  //                              `------------------'
+  //
+  //////////////////////////////////////////////////////////////////
+```
+
+Each "region" is a wrapper around an algorithm.  This wrapper provides a uniform interface that can be plugged into the Network API engine for execution. The htm.core library contains regions for each of the primary algorithms in the library. The user can create their own algorithms and corresponding regions and plug them into the Network API engine by registering them with the Network class.  The following chart shows the 'built-in' C++ regions.  
+<table>
+<thead>
+	<tr>
+		<th>Built-in Region</th>
+		<th>Algorithm</th>
+	</tr>
+</thead>
+<tbody>
+	<tr>
+		<td>ScalarSensor</td>
+		<td>ScalarEncoder;  Original encoder for numeric values</td>
+	</tr>
+	<tr>
+		<td>RDSERegion</td>
+		<td>RandomDistributedScalarEncoder (RDSE);  advanced encoder for numeric values.</td>
+	</tr>
+	<tr>
+		<td>SPRegion</td>
+		<td>SpatialPooler (SP)</td>
+	</tr>
+	<tr>
+		<td>TMRegion</td>
+		<td>TemporalMemory (TM)</td>
+	</tr>
+	<tr>
+		<td>VectorFileSensor</td>
+		<td>for reading from a file</td>
+	</tr>
+	<tr>
+		<td>VectorFileEffector</td>
+		<td>for writing to a file</td>
+	</tr>
+</tbody>
+</table>
+
+## Usage
+
+```
+   hotgym_napi  [iterations [filename]]
+```
+- *iterations* is the number of times to execute the regions configured into the network. The default is 5000.
+- *filename* is the path for a file to be written which contains the following for each iteration.  The default is no file written.
+```
+        <iteration>, <sin data>, <anomaly>\n
+```
+
+## Plotting
+
+The `hotgym_napi` program can output data if a filename is specified. Any plotting program can be used to display this CSD data.
+
+## Experimentation
+It is intended that this program be used as a launching point for experimenting with combinations of the regions and using different parameters.  Try it and see what happens...

src/examples/hotgym_NetworkAPI/hotgym_napi.cpp

@@ -0,0 +1,132 @@
+/* ---------------------------------------------------------------------
+ * HTM Community Edition of NuPIC
+ * Copyright (C) 2013-2015, Numenta, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses.
+ * --------------------------------------------------------------------- */
+
+#include <htm/engine/Network.hpp>
+#include <htm/utils/Random.hpp>
+#include <htm/utils/Log.hpp>
+#include <fstream>
+
+using namespace htm;
+
+static bool verbose = false;
+#define VERBOSE if (verbose)  std::cout << "    "
+
+
+//this runs as an executable
+
+int main(int argc, char* argv[]) {
+  htm::UInt EPOCHS = 5000;      // number of iterations (calls to encoder/SP/TP compute() )
+  const UInt DIM_INPUT = 1000;  // Width of encoder output
+  const UInt COLS = 2048;       // number of columns in SP, TP
+  const UInt CELLS = 8;         // cells per column in TP
+  Random rnd(42);               // uses fixed seed for deterministic output
+  std::ofstream ofs;
+
+  //  Runtime arguments:  hotgym_napi [epochs [filename]]
+  if(argc >= 2) {
+    EPOCHS = std::stoi(argv[1]);         // number of iterations (default 5000)
+  }
+  if (argc >= 3) {
+    ofs.open(argv[2], std::ios::out);    // output filename (for plotting)
+  }
+
+  try {
+
+    std::cout << "initializing\n";
+
+    Network net;
+
+    // Declare the regions to use
+    std::string encoder_parameters = "{size: " + std::to_string(DIM_INPUT) + ", activeBits: 4, radius: 0.5, seed: 2019 }";
+    std::shared_ptr<Region> region1 =  net.addRegion("region1", "RDSERegion", encoder_parameters);
+    std::shared_ptr<Region> region2a = net.addRegion("region2a", "SPRegion", "{columnCount: " + std::to_string(COLS) + "}");
+    std::shared_ptr<Region> region2b = net.addRegion("region2b", "SPRegion", "{columnCount: " + std::to_string(COLS) + ", globalInhibition: true}");
+    std::shared_ptr<Region> region3 =  net.addRegion("region3", "TMRegion", "{activationThreshold: 9, cellsPerColumn: " + std::to_string(CELLS) + "}");
+
+    // Setup data flows between regions
+    net.link("region1", "region2a", "", "", "encoded", "bottomUpIn");
+    net.link("region1", "region2b", "", "", "encoded", "bottomUpIn");
+    net.link("region2b", "region3", "", "", "bottomUpOut", "bottomUpIn");
+
+    net.initialize();
+
+    ///////////////////////////////////////////////////////////////
+    //
+    //                 .------------------.
+    //                 |    encoder       |
+    //         data--->|  (RDSERegion)    |
+    //                 |                  |
+    //                 `------------------'
+    //                     |           |
+    //      .------------------.    .------------------.
+    //      |   SP (local)     |    |   SP (global)    |
+    //      |                  |    |                  |
+    //      |                  |    |                  |
+    //      `------------------'    `------------------'
+    //                                       |
+    //                              .------------------.
+    //                              |      TM          |
+    //                              |   (TMRegion)     |
+    //                              |                  |
+    //                              `------------------'
+    //
+    //////////////////////////////////////////////////////////////////
+
+
+    // enable this to see a trace as it executes
+    // net.setLogLevel(LogLevel::LogLevel_Verbose);
+
+    std::cout << "Running: \n";
+    // RUN
+    for (size_t i = 0; i < EPOCHS; i++) {
+      // genarate some data to send to the encoder
+      //  -- A sin wave, one degree rotation per iteration, 1% noise added
+      double data = std::sin(i * (3.1415 / 180)) + (double)rnd.realRange(-0.01f, +0.1f);
+      region1->setParameterReal64("sensedValue", data); // feed data into RDSE encoder for this iteration.
+
+      // Execute an iteration.
+      net.run(1);
+
+      // output values
+      double an = ((double *)region3->getOutputData("anomaly").getBuffer())[0];
+      VERBOSE << "Epoch = " << i << std::endl;
+      VERBOSE << "  Data        = " << data << std::endl;
+      VERBOSE << "  Encoder out = " << region1->getOutputData("encoded").getSDR() << std::endl;
+      VERBOSE << "  SP (local)  = " << region2a->getOutputData("bottomUpOut").getSDR() << std::endl;
+      VERBOSE << "  SP (global) = " << region2b->getOutputData("bottomUpOut").getSDR() << std::endl;
+      VERBOSE << "  TM output   = " << region3->getOutputData("bottomUpOut").getSDR() << std::endl;
+      VERBOSE << "  ActiveCells = " << region3->getOutputData("activeCells").getSDR() << std::endl;
+      VERBOSE << "  winners     = " << region3->getOutputData("predictedActiveCells").getSDR() << std::endl;
+      VERBOSE << "  Anomaly     = " << an << std::endl;
+
+      // Save the data for plotting.   <iteration>, <sin data>, <anomaly>\n
+      if (ofs.is_open())
+        ofs << i << "," << data << "," << an << std::endl;
+    }
+    if (ofs.is_open())
+      ofs.close();
+
+  } catch (Exception &e) {
+    std::cerr << e.what();
+    if (ofs.is_open())
+      ofs.close();
+    return 1;
+  }
+
+  return 0;
+}
+

src/htm/utils/Random.hpp

@@ -129,7 +129,7 @@ class Random : public Serializable  {
    * return random from range [from, to)
    */
   Real realRange(Real from, Real to) {
-    NTA_ASSERT(from <= to);
+    NTA_ASSERT(from <= to) << "realRange: invalid range.";
     const Real split = to - from;
     return from + static_cast<Real>(split * getReal64());
   }