The EncoderRegion, a generic plugin container for encoders.

.clang-format

@@ -2,4 +2,6 @@
 Language: Cpp
 BasedOnStyle: LLVM
 DisableFormat: false
+IndentWidth: 2
+ColumnLimit: 120
 ...

VERSION

@@ -1 +1 @@
-v2.0.11
+v2.0.0

bindings/py/cpp_src/bindings/encoders/py_RDSE.cpp

@@ -108,7 +108,9 @@ fields are filled in automatically.)");
         py_RDSE.def_property_readonly("size",
             [](RDSE &self) { return self.size; });
 
-        py_RDSE.def("encode", &RDSE::encode, R"()");
+        py_RDSE.def("encode", [](RDSE &self, htm::Real64 value, htm::SDR* sdr) {
+            self.encode( value, *sdr );
+        });
 
         py_RDSE.def("encode", [](RDSE &self, Real64 value) {
             auto sdr = new SDR({self.size});

bindings/py/cpp_src/bindings/encoders/py_ScalarEncoder.cpp

@@ -115,12 +115,14 @@ fields are filled in automatically.)");
     py_ScalarEnc.def_property_readonly("size",
         [](const ScalarEncoder &self) { return self.size; });
 
-    py_ScalarEnc.def("encode", &ScalarEncoder::encode, R"()");
+    py_ScalarEnc.def("encode", [](ScalarEncoder &self, htm::Real64 value, htm::SDR* sdr) {
+        self.encode( value, *sdr );
+    });
 
     py_ScalarEnc.def("encode", [](ScalarEncoder &self, htm::Real64 value) {
         auto output = new SDR( self.dimensions );
         self.encode( value, *output );
-        return output; },
-R"()");
+        return output; 
+    });
   }
 }

src/CMakeLists.txt

@@ -83,6 +83,7 @@ set(algorithm_files
 
 set(encoders_files 
     htm/encoders/BaseEncoder.hpp
+	htm/encoders/GenericEncoder.hpp
     htm/encoders/ScalarEncoder.cpp
     htm/encoders/ScalarEncoder.hpp
     htm/encoders/RandomDistributedScalarEncoder.hpp
@@ -110,6 +111,8 @@ set(engine_files
     htm/engine/RegionImplFactory.hpp
     htm/engine/RegisteredRegionImpl.hpp
     htm/engine/RegisteredRegionImplCpp.hpp
+    htm/engine/RegisteredEncoder.hpp
+    htm/engine/RegisteredEncoderCpp.hpp
     htm/engine/Spec.cpp
     htm/engine/Spec.hpp
     htm/engine/YAMLUtils.cpp
@@ -150,6 +153,8 @@ set(os_files
 )
 
 set(regions_files
+    htm/regions/EncoderRegion.cpp
+    htm/regions/EncoderRegion.hpp
     htm/regions/ScalarSensor.cpp
     htm/regions/ScalarSensor.hpp
     htm/regions/SPRegion.cpp

src/htm/encoders/GenericEncoder.hpp

@@ -0,0 +1,139 @@
+/* ---------------------------------------------------------------------
+ * HTM Community Edition of NuPIC
+ * Copyright (C) 2019, David McDougall
+ *
+ * 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.
+ * --------------------------------------------------------------------- */
+
+/** @file
+ * Defines the base class for all encoders.
+ */
+
+#ifndef NTA_GENERIC_ENCODER
+#define NTA_GENERIC_ENCODER
+
+#include <htm/ntypes/BasicType.hpp>
+#include <htm/types/Sdr.hpp>
+#include <string>
+
+namespace htm {
+
+struct BaseParameters {
+};
+
+// This structure is populated with the FIELD( ) macro
+typedef struct {
+  std::string name;
+  int offset;
+  NTA_BasicType type;
+  std::string default_value;
+} ParameterDescriptorFields;
+typedef struct {
+  NTA_BasicType expectedInputType;
+  size_t expectedInputSize;
+  char *parameterStruct;
+  size_t parameterSize;
+  std::map<std::string, ParameterDescriptorFields> parameters;
+} ParameterDescriptor;
+
+#define FIELD(n)                                        \
+  { #n,                                                 \
+    { #n,                                               \
+      (int)((char *)&args_.n - (char *)&args_),         \
+      BasicType::getType(typeid(args_.n)),              \
+      std::to_string(args_.n)}                          \
+  }
+
+
+/**
+ * Base class for all encoders that can be used as a plugin for EncoderRegion.
+ * An encoder converts a value to a sparse distributed representation.
+ *
+ * Subclasses must implement method encode and Serializable interface.
+ * Subclasses can optionally implement method reset.
+ *
+ * There are several critical properties which all encoders must have:
+ *
+ * 1) Semantic similarity:  Similar inputs should have high overlap.  Overlap
+ * decreases smoothly as inputs become less similar.  Dissimilar inputs have
+ * very low overlap so that the output representations are not easily confused.
+ *
+ * 2) Stability:  The representation for an input does not change during the
+ * lifetime of the encoder.
+ *
+ * 3) Sparsity: The output SDR should have a similar sparsity for all inputs and
+ * have enough active bits to handle noise and subsampling.
+ *
+ * Reference: https://arxiv.org/pdf/1602.05925.pdf
+ */
+class GenericEncoder : public Serializable {
+public:
+  virtual std::string getName() const = 0;
+
+  /**
+   * Members dimensions & size describe the shape of the encoded output SDR.
+   * This is the total number of bits in the result.
+   */
+  const std::vector<UInt> &dimensions = dimensions_;
+  const UInt &size = size_;
+
+  virtual void reset() {}
+
+  // for use by generic EncoderRegion to
+  // generically pass parameter structure to encoder
+  virtual void initialize(BaseParameters *ptrToParameters) = 0; 
+  virtual ParameterDescriptor getDescriptor() = 0; // parameter descriptors
+  virtual void encode(void *input, size_t input_count,
+                      SDR &output) = 0; // untyped encode( ) call.
+
+  virtual ~GenericEncoder() {}
+
+  // overridden by including the macro CerealAdapter in subclass.
+  virtual void cereal_adapter_save(ArWrapper &a) const {};
+  virtual void cereal_adapter_load(ArWrapper &a){};
+
+  // encoders should override
+  virtual bool operator==(const GenericEncoder &other) const { return true; }
+
+protected:
+  GenericEncoder() {
+    // initialize with dummy dimensions.  
+    // Must set real dimensions later by calling init_base() again.
+    std::vector<UInt> dim({0});
+    init_base(dim);
+  }
+
+  GenericEncoder(const std::vector<UInt> dimensions) { 
+    init_base(dimensions); 
+  }
+
+  void init_base(const std::vector<UInt> dimensions) {
+    dimensions_ = dimensions;
+    size_ = SDR(dimensions).size;
+  }
+
+
+
+
+private:
+    std::vector<UInt> dimensions_;
+    UInt              size_;
+};
+
+
+
+
+
+
+} // end namespace htm
+#endif // NTA_GENERIC_ENCODER

src/htm/encoders/RandomDistributedScalarEncoder.cpp

@@ -27,37 +27,44 @@
 using namespace std;
 using namespace htm;
 
-RandomDistributedScalarEncoder::RandomDistributedScalarEncoder(
-                                              const RDSE_Parameters &parameters)
-  { initialize( parameters ); }
+RandomDistributedScalarEncoder::RandomDistributedScalarEncoder() {}
+// Note: This encoder is not useable until initialize() is called.
 
-void RandomDistributedScalarEncoder::initialize( const RDSE_Parameters &parameters)
-{
+RandomDistributedScalarEncoder::RandomDistributedScalarEncoder( const RDSE_Parameters &params) { 
+  initialize( params ); 
+}
+
+RandomDistributedScalarEncoder::RandomDistributedScalarEncoder(ArWrapper &wrapper) {
+  cereal_adapter_load(wrapper);
+}
+
+
+void RandomDistributedScalarEncoder::initialize(const RDSE_Parameters &params) {
   // Check size parameter
-  NTA_CHECK( parameters.size > 0u );
+  NTA_CHECK(params.size > 0u);
 
   // Initialize parent class.
-  BaseEncoder<Real64>::initialize({ parameters.size });
+  GenericEncoder::init_base({params.size});
 
   // Check other parameters
   UInt num_active_args = 0;
-  if( parameters.activeBits > 0u)   { num_active_args++; }
-  if( parameters.sparsity   > 0.0f) { num_active_args++; }
+  if (params.activeBits > 0u) {  num_active_args++; }
+  if (params.sparsity > 0.0f) {  num_active_args++; }
   NTA_CHECK( num_active_args != 0u )
       << "Missing argument, need one of: 'activeBits' or 'sparsity'.";
   NTA_CHECK( num_active_args == 1u )
       << "Too many arguments, choose only one of: 'activeBits' or 'sparsity'.";
 
   UInt num_resolution_args = 0;
-  if( parameters.radius     > 0.0f) { num_resolution_args++; }
-  if( parameters.category )         { num_resolution_args++; }
-  if( parameters.resolution > 0.0f) { num_resolution_args++; }
+  if (params.radius > 0.0f) { num_resolution_args++; }
+  if (params.category) { num_resolution_args++; }
+  if (params.resolution > 0.0f) { num_resolution_args++; }
   NTA_CHECK( num_resolution_args != 0u )
       << "Missing argument, need one of: 'radius', 'resolution', 'category'.";
   NTA_CHECK( num_resolution_args == 1u )
       << "Too many arguments, choose only one of: 'radius', 'resolution', 'category'.";
 
-  args_ = parameters;
+  args_ = params;
   // Finish filling in all of parameters.
 
   // Determine number of activeBits.
@@ -88,8 +95,7 @@ void RandomDistributedScalarEncoder::initialize( const RDSE_Parameters &paramete
   }
 }
 
-void RandomDistributedScalarEncoder::encode(Real64 input, SDR &output)
-{
+void RandomDistributedScalarEncoder::encode(Real64 input,  SDR &output) {
   // Check inputs
   NTA_CHECK( output.size == size );
   if( isnan(input) ) {
@@ -126,13 +132,36 @@ void RandomDistributedScalarEncoder::encode(Real64 input, SDR &output)
   output.setDense( data );
 }
 
+//  bool RandomDistributedScalarEncoder::equals(const BaseEncoder &other) const
+//  {
+
+bool RandomDistributedScalarEncoder::operator==(const GenericEncoder &other) const {
+  if (other.getName() != getName())
+    return false;
+  const RandomDistributedScalarEncoder &o = static_cast<const RandomDistributedScalarEncoder &>(other);
+  if (parameters.size == o.parameters.size &&
+      parameters.activeBits == o.parameters.activeBits &&
+      parameters.sparsity == o.parameters.sparsity &&
+      parameters.radius == o.parameters.radius &&
+      parameters.resolution == o.parameters.resolution &&
+      parameters.category == o.parameters.category &&
+      parameters.seed == o.parameters.seed)
+        return true;
+    return false;
+}
+
+
 std::ostream & htm::operator<<(std::ostream & out, const RandomDistributedScalarEncoder &self)
 {
-  out << "RDSE ";
+  out << self.getName();
   out << "  size:       " << self.parameters.size << ",\n";
   out << "  activeBits: " << self.parameters.activeBits << ",\n";
   out << "  resolution: " << self.parameters.resolution << ",\n";
   out << "  category:   " << self.parameters.category << ",\n";
   out << "  seed:       " << self.parameters.seed << std::endl;
   return out;
 }
+
+// Register RandomDistributedScalarEncoder for Cereal Serialization
+CEREAL_REGISTER_TYPE(RandomDistributedScalarEncoder);
+CEREAL_REGISTER_POLYMORPHIC_RELATION(GenericEncoder, RandomDistributedScalarEncoder)