DISCONTINUATION OF PROJECT.
This project will no longer be maintained by Intel.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this project.
If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project. Table of Contents
- Intel® Pattern Matching Technology
- CuriePME API reference
This repository contains the CuriePME library, which provides access to the Pattern Matching Engine (PME) within the Intel® Curie™ Compute Module.
Supported Curie™ hardware platforms:
This library can be used in the following development environments:
-
On Ubuntu 14.04 LTS or 16.04 LTS, using the latest version of the Curie Open Developer Kit
-
In the Arduino IDE ("Download as a ZIP", unzip, place inside your libraries folder)
the PME is a hardware engine capable of learning and recognizing patterns in arbitrary sets of data. The CuriePME library provides access to the PME, making it possible to implement machine-learning pattern matching or classification algorithms which are accelerated by the pattern-matching capabilities of the PME.
- Basic Functions Supported:
- Learning Patterns
- Recognizing Patterns
- Storing Pattern Memory (Knowledge) [Requires SerialFlash Library]
- Retrieving Pattern Memory (Knowledge) [Requires SerialFlash Library]
The Pattern Matching Engine (PME) is a parallel data recognition engine with the following features:
-
128 parallel Processing Elements (PE) each with"
-
128 byte input vector
-
128 byte model memory.
-
8-Bit Arithmetic Units
-
Two distance evaluation norms with 16-bit resolution:
- L1 norm (Manhattan Distance)
- Lsup (Supremum) norm (Chebyshev Distance)
-
Support for up to 32,768 Categories
-
Classification states:
* ID - Identified * UNC - Uncertain * UNK - Unknown
-
-
Two Classification Functions:
- k-nearest neighbors (KNN)
- Radial Basis Function (RBF)
-
Support for up to 127 Contexts
CuriePME.noMatch (uint32_t): The value returned by classify() to indicate a pattern could not be classifiedCuriePME.minContext (uint16_t): Minimum context valueCuriePME.maxContext (uint16_t): Maximum context valueCuriePME.maxVectorSize (int32_t): Maximum pattern size (in bytes) that can be accepted by learn() and classify()CuriePME.firstNeuronID (int32_t): ID of first neuron in networkCuriePME.lastNeuronID (int32_t): ID of last neuron in networkCuriePME.maxNeurons (int32_t): Number of neurons in the network
void CuriePME.begin(void)
Initialize the PME so it is ready for operation
Parameters
none
Return value
none
void CuriePME.forget(void)
Clear any data committed to the network, making the network ready to learn again.
Parameters
none
Return value
none
uint16_t CuriePME.learn(uint8_t *pattern_vector, int32_t vector_length, uint8_t category)
Takes a pattern pattern_vector of size vector_length, and commits it to the
network as training data. The category parameter indicates to the PME which
category this training vector belongs to- that is, if a future input has a
sufficiently similar pattern, it will be classified as the same category passed
with this pattern.
Parameters
uint8_t *pattern_vector: Pointer to the training data. Training data must be no longer than 128 bytesint32_t vector_length: The size (in bytes) of your training vectoruint8_t category: The category that should be assigned to this data
Return value
Total number of committed neurons in the network after the learning operation is complete
uint16_t CuriePME.classify(uint8_t *pattern_vector, int32_t vector_length)
Takes a pattern pattern_vector of size vector_length, and uses the
committed neurons in the network to classify the pattern
Parameters
uint8_t *pattern_vector: Pointer to the data to be classified. Pattern data must be no longer than 128 bytesint32_t vector_length: The size (in bytes) of the data to be classified
Return value
CuriePME.noMatch if the input data did not match any of the trained categories.
Otherwise, the trained category assigned by the network will be returned
void CuriePME.beginSaveMode(void)
Puts the network into a state that allows the neuron contents to be read
Parameters
none
Return value
none
uint16_t CuriePME.iterateNeuronsToSave(neuronData& data_array)
When in save mode, this method can be called to obtain the data for the next committed neuron. Each successive call will increment an internal pointer and return the data for successive committed neurons, until all committed neurons have been read.
Parameters
neuronData& data_array: aneuronDatatype in which the neuron data will be placed
Return value
0 when all committed neurons have been read. Otherwise, this method returns the trained category of the neuron being read
void CuriePME.endSaveMode(void)
Takes the network out of save mode
Parameters
none
Return value
none
void CuriePME.beginRestoreMode(void)
Puts the network into a state that allows the neuron contents to be restored from a file
Parameters
none
Return value
none
void CuriePME.iterateNeuronsToRestore(neuronData& data_array)
When in restore mode, this method can be called to write data to the next available neuron. Each successive call will increment an internal pointer until all the neurons in the network have been written.
Parameters
neuronData& data_array: aneuronDatatype containing the neuron data
Return value
none
void CuriePME.endRestoreMode(void)
Takes the network out of restore mode
Parameters
none
Return value
none
void CuriePME.setClassifierMode(PATTERN_MATCHING_CLASSIFICATION_MODE mode)
Sets the classifying function to be used by the network
Parameters
PATTERN_MATCHING_CLASSIFICATION_MODE modeThe classifying function to use. Valid values are:RBF_Mode(default)KNN_Mode
Return value
none
PATTERN_MATCHING_CLASSIFICATION_MODE CuriePME.getClassifierMode(void)
Gets the classifying function being used by the network
Parameters
none
Return value
PATTERN_MATCHING_CLASSIFICATION_MODE mode The classifying function being used.
Possible values are:
RBF_ModeKNN_Mode
void CuriePME.setDistanceMode(PATTERN_MATCHING_DISTANCE_MODE mode)
Sets the distance function to be used by the network
Parameters
-
PATTERN_MATCHING_DISTANCE_MODE modeThe distance function to use. Valid values are:LSUP_Distance(default)L1_Distance
Return value
none
PATTERN_MATCHING_DISTANCE_MODE CuriePME.getDistanceMode(void)
Gets the distance function being used by the network
Parameters
none
Return value
PATTERN_MATCHING_DISTANCE_MODE mode The distance function being used.
Possible values are:
LSUP_DistanceL1_Distance
void CuriePME.setGlobalContext(uint16_t context)
Writes a value to the Global Context Register. Valid context values range between 1-127. A context value of 0 enables all neurons, with no regard to their context
Parameters
uint16_t context: a value between 0-127 representing the desired context. A context value of 0 selects all neurons, regardless of their context value.
Return value
none
uint16_t CuriePME.getGlobalContext(void)
Reads the Global Context Register
Parameters
none
Return value
uint16_t, the contents of the Global Context Register (a value between 0-127)
uint16_t CuriePME.getCommittedCount(void)
Gets the number of committed neurons in the network (NOTE: this method should not be used in save/restore mode, because it will give inaccurate results)
Parameters
none
Return value
uint16_t, the number of comitted neurons in the network
void CuriePME.readNeuron(int32_t neuronID, neuronData& data_array)
Read a specific neuron by its ID
Parameters
int32_t neuronID: value between 1-128 representing a specific neuronneuronData& data_array: neuronData type in which to write the neuron data
Return value
none
uint16_t CuriePME.writeVector(uint8_t *pattern_vector, int32_t vector_length)
(Should only be used in KNN_Mode) Takes a pattern pattern_vector of size
vector_length, and uses the committed neurons in the network to classify the
pattern
Parameters
uint8_t *pattern_vector: Pointer to the data to be classified. Pattern data must be no longer than 128 bytesint32_t vector_length: The size (in bytes) of the data to be classified
Return value
CuriePME.noMatch if the input data did not match any of the trained categories.
Otherwise, the trained category assigned by the network will be returned