Home

Awesome

<!--- OgmaNeo Copyright(c) 2016-2017 Ogma Intelligent Systems Corp. All rights reserved. This copy of OgmaNeo is licensed to you under the terms described in the OGMANEO_LICENSE.md file included in this distribution. --->

OgmaNeo

Join the chat at https://gitter.im/ogmaneo/Lobby Build Status

Introduction

Welcome to Ogma OgmaNeo library. A C++ library that contains implementation(s) of Online Predictive Hierarchies, as described in the arXiv.org paper: Feynman Machine: The Universal Dynamical Systems Computer.

The current release of this library contains a form of Sparse Predictive Hierarchies. Refer to the arXiv.org paper for further details.

Examples using this library can be found in the OgmaNeoDemos GitHub repository, and alongside the language bindings within this repository.

SWIG based language bindings for Python, Java (JNI), and C# are found in subdirectories. Refer to Readme.md files in those subdirectories for further information.

Overview

OgmaNeo is a fully online learning algorithm, so data must be passed in an appropriately streamed fashion.

The simplest usage of the predictive hierarchy involves calling:

    #include <neo/Architect.h>
    #include <neo/Hierarchy.h>

	using namespace ogmaneo;

    // Create the Resources and main ComputeSystem
    std::shared_ptr<ogmaneo::Resources> res = std::make_shared<ogmaneo::Resources>();

    res->create(ogmaneo::ComputeSystem::_gpu);

    // Use the Architect to build the desired hierarchy
    ogmaneo::Architect arch;
    arch.initialize(1234, res);

    // 1 input layer
    arch.addInputLayer(ogmaneo::Vec2i(4, 4))
        .setValue("in_p_alpha", 0.02f)
        .setValue("in_p_radius", 16);

    // 3 layers using chunk encoders
    for (int l = 0; l < 3; l++)
        arch.addHigherLayer(ogmaneo::Vec2i(36, 36), ogmaneo::_chunk)
        .setValue("sfc_chunkSize", ogmaneo::Vec2i(6, 6))
        .setValue("sfc_ff_radius", 12)
        .setValue("hl_poolSteps", 2)
        .setValue("p_alpha", 0.08f)
        .setValue("p_beta", 0.16f)
        .setValue("p_radius", 12);

    // Generate the hierarchy
    std::shared_ptr<ogmaneo::Hierarchy> hierarchy = arch.generateHierarchy();

    // Input and prediction fields (4x4 size)
    ogmaneo::ValueField2D inputField(ogmaneo::Vec2i(4, 4));
    ogmaneo::ValueField2D predField(ogmaneo::Vec2i(4, 4));

You can then step the simulation with:

    // Fill the inputField and step the simulation
    hierarchy->activate(std::vector<ogmaneo::ValueField2D>{ inputField });

    hierarchy->learn(std::vector<ogmaneo::ValueField2D>{ inputField });

	// Retrieve the prediction (same dimensions as the input field)
    predField = hierarchy->getPredictions().front();

Parameters

The OgmaNeo Architect interface has several adjustable parameters.

Parameters are adjusted by performing value changes on the parameter modifier returned by layer add calls.

    // 1 input layer
    arch.addInputLayer(ogmaneo::Vec2i(4, 4))
        .setValue("in_p_alpha", 0.02f)
        .setValue("in_p_radius", 16);

    // 3 layers using chunk encoders
    for (int l = 0; l < 3; l++)
        arch.addHigherLayer(ogmaneo::Vec2i(36, 36), ogmaneo::_chunk)
        .setValue("sfc_chunkSize", ogmaneo::Vec2i(6, 6))
        .setValue("sfc_ff_radius", 12)
        .setValue("hl_poolSteps", 2)
        .setValue("p_alpha", 0.08f)
        .setValue("p_beta", 0.16f)
        .setValue("p_radius", 12);

Parameters are grouped by (possibly several) prefixes. Below is a list of parameters:

Global (additional parameters, prefix 'ad'):

Hierarchy layers (prefix 'hl'):

Predictor (prefix 'p'):

Encoders

Sparse features Chunk (prefix 'sfc'):

Sparse features Distance (prefix 'sfd'):

Requirements

OgmaNeo requires:

These requirements must be installed and setup before building the OgmaNeo library.

The library has been tested extensively on:

CMake

Version 3.1+ of CMake is required when building the library.

The CMakeLists.txt file uses an ExternalProject to download and build the FlatBuffers package. It also defines custom build targets to automatically package kernel code into the library. Kernel packaging is required for OgmaNeoDemos, and the Python bindings PyOgmaNeo.

OpenCL

OpenCL (Open Compute Language, version 1.2 and upwards) is used to compile, upload and run kernel code on CPU and GPU devices. An OpenCL SDK, with system drivers that support OpenCL 1.2, is required to build and use the OgmaNeo library.

The open source POCL package (Portable Computing Language) can be used for devices that don't have OpenCL vendor driver support. For example the OgmaNeo library using POCL (release branch 0.13) has been tested on the Raspberry Pi3 device and the Travis continuous integration service.

CL2 header file

The Khronos Group's cl2.hpp header file is required when building OgmaNeo. It needs to be placed alongside your OpenCL header files. The header file can be downloaded from Github https://github.com/KhronosGroup/OpenCL-CLHPP/releases

Flatbuffers

The FlatBuffers package (version 1.4.0), an efficient cross platform serialization library, is used to load and save OgmaNeo internal data (such as hierarchies and agents).

The OgmaNeo CMake build system uses the CMake\FindFlatBuffers.cmake script to find the schema compiler and C++ header file include directory. As well as adding a custom build step to compile schema files (extension .fbs) and generate helper header files.

If you do not already have the Flatbuffers package installed, the OgmaNeo CMakeLists.txt script will automatically download and build the package into a 3rdparty directory local to the build.

Building

The following commands can be used to build the OgmaNeo library:

git clone https://github.com/ogmacorp/ogmaneo.git
cd ogmaneo
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=../install ..
make
make install

The cmake command can be passed a CMAKE_INSTALL_PREFIX to determine where to install the library and header files.

The BUILD_SHARED_LIBS boolean cmake option can be used to create dynamic/shared object library (default is to create a static library). On Linux it's recommended to add -DBUILD_SHARED_LIBS=ON

make install can be run to install the library. make uninstall can be used to uninstall the library.

On Windows systems it is recommended to use cmake-gui to define which generator to use and specify optional build parameters, such as CMAKE_INSTALL_PREFIX.

Language bindings

The following language bindings exist for the OgmaNeo library:

They each exist in a subdirectory, and a Readme.md file in each subdirectory provides information on how to build these SWIG based bindings.

Contributions

Refer to the CONTRIBUTING.md file for information on making contributions to OgmaNeo.

License and Copyright

<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br />The work in this repository is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>. See the OGMANEO_LICENSE.md and LICENSE.md file for further information.

Contact Ogma via licenses@ogmacorp.com to discuss commercial use and licensing options.

The OgmaNeo library uses the Google FlatBuffers package that is licensed with an Apache License (Version 2.0). Refer to this LICENSE.txt file for the full licensing text associated with the FlatBuffers package.

OgmaNeo Copyright (c) 2016-2018 Ogma Intelligent Systems Corp. All rights reserved.