Hardware Functions in xf::data_analytics::classification

decisionTreePredict

#include "xf_data_analytics/classification/decision_tree_predict.hpp"
template <
    typename MType,
    unsigned int WD,
    unsigned int MAX_FEA_NUM,
    unsigned int MAX_TREE_DEPTH = 20,
    unsigned MAX_CAT_BITS = 8
    >
void decisionTreePredict (
    hls::stream <ap_uint <WD>> dstrm_batch [MAX_FEA_NUM],
    hls::stream <bool>& estrm_batch,
    hls::stream <ap_uint <512>>& treeStrm,
    hls::stream <bool>& treeTag,
    hls::stream <ap_uint <MAX_CAT_BITS>>& predictionsStrm,
    hls::stream <bool>& predictionsTag
    )

decisionTreePredict, Top function of Decision Tree Predict.

This function first loads decision tree (the corresponding function : getTree) from treeStrm Then, read sample one by one from dstrm_batch, and output its category id into predictionsStrm streams

Note that the treeStrm is a 512-bit stream, and each 512 bits include two nodes. In each 512-bit confirm the range(0,71) is node[i].nodeInfo and range(256,327) is node[i+1].nodeInfo the range(192,255) is node[i].threshold and range(448,511) is node[i+1].threshold For detailed info of Node struct, can refer “decision_tree.hpp” Samples in input sample stream should be converted into ap_uint<WD> from MType

Parameters:

MType The data type of sample
WD The width of data type MType, can get by sizeof(MType)
MAX_FEA_NUM The max feature num function can support
MAX_TREE_DEPTH The max tree depth function can support
MAX_CAT_BITS The category max bit number
dstrm_batch Input data streams of ap_uint<WD>
estrm_batch End flag stream for input data
treeStrm Decision tree streams
treeTag End flag stream for decision tree nodes
predictionsStrm Output data streams
predictionsTagStrm End flag stream for output

axiVarColToStreams

#include "xf_data_analytics/classification/decision_tree_train.hpp"
template <
    int _BurstLen = 32,
    int _WAxi = 512,
    int _WData = 64
    >
void axiVarColToStreams (
    ap_uint <_WAxi>* ddr,
    const ap_uint <32> offset,
    const ap_uint <32> rows,
    ap_uint <32> cols,
    hls::stream <ap_uint <_WData>> dataStrm [_WAxi/_WData],
    hls::stream <bool>& eDataStrm
    )

Loading table from AXI master to stream. Table should be row based storage of identical datawidth.

Parameters:

_BurstLen burst length of AXI buffer, default is 32.
_WAxi width of AXI port, must be multiple of datawidth, default is 512.
_WData datawith, default is 64.
ddr input AXI port
offset offset(in _WAxi bits) to load table.
rows Row number of table
cols Column number of table Output streams of _WAxi/_WData channels end flag of output stream.

naiveBayesTrain

#include "xf_data_analytics/classification/naive_bayes.hpp"
template <
    int DT_WIDTH = 32,
    int WL = 3,
    typename DT = unsigned int
    >
void naiveBayesTrain (
    const int num_of_class,
    const int num_of_term,
    hls::stream <ap_uint <64>> i_data_strm [1<< WL],
    hls::stream <bool> i_e_strm [1<< WL],
    hls::stream <int>& o_terms_strm,
    hls::stream <ap_uint <64>> o_data0_strm [1<< WL],
    hls::stream <ap_uint <64>> o_data1_strm [1<< WL]
    )

naiveBayesTrain, top function of multinomial Naive Bayes Training.

This function will firstly load train dataset from the i_data_strm, then counte the frequency for each hit term. After scaning all sample, the likehood probability matrix and prior probability will be output from two independent stream

Parameters:

DT_WIDTH the width of type DT, in bits
WL the width of bit to enable dispatcher, only 3 is supported so far
DT the data type of internal counter for terms, can be 32/64-bit integer, float or double
num_of_class the number of class in sample dataset, should be exactly same with real dataset
num_of_term the number of terms, must be larger than the number of feature, and num_of_class * num_of_term <= (1 << (20-WL)) must be satisfied.
i_data_strm input data stream of ap_uint<64> in multiple channel
i_e_strm end flag stream for each input data channel
o_terms_strm the output number of statistic feature
o_data0_strm the output likehood matrix
o_data1_strm the output prior probablity vector

naiveBayesPredict

#include "xf_data_analytics/classification/naive_bayes.hpp"
template <
    int CH_NM,
    int GRP_NM
    >
void naiveBayesPredict (
    const int num_of_class,
    const int num_of_term,
    hls::stream <ap_uint <64>>& i_theta_strm,
    hls::stream <ap_uint <64>>& i_prior_strm,
    hls::stream <ap_uint <32>> i_data_strm [CH_NM],
    hls::stream <bool>& i_e_strm,
    hls::stream <ap_uint <10>>& o_class_strm,
    hls::stream <bool>& o_e_strm
    )

naiveBayesPredict, top function of multinomial Naive Bayes Prediction

The function will firstly load the train model into on-chip memory, and calculate the classfication results for each sample using argmax function.

Parameters:

CH_NM the number of channel for input sample data, should be power of 2
GRP_NM the unroll factor for handling the classes simultaneously, must be power of 2 in 1~256
num_of_term the number of class, should be exactly same with the input dataset
num_of_term the number of feature, should be exactly same with the input dataset
i_theta_strm the input likehood probability stream, [num_of_class][num_of_term]
i_prior_strm the input prior probability stream, [num_of_class]
i_data_strm the input of test data stream
i_e_strm end flag stream for i_data_strm
o_class_strm the prediction result for each input sample
o_e_strm end flag stream for o_class_strm

svmPredict

#include "xf_data_analytics/classification/svm_predict.hpp"
template <
    typename MType,
    unsigned WD,
    unsigned StreamN,
    unsigned SampleDepth
    >
void svmPredict (
    const int cols,
    hls::stream <MType> sample_strm [StreamN],
    hls::stream <bool>& e_sample_strm,
    hls::stream <ap_uint <512>>& weight_strm,
    hls::stream <bool>& eTag,
    hls::stream <ap_uint <1>>& predictionsStrm,
    hls::stream <bool>& predictionsTag
    )

svmPredict, Top function of svm Predict.

This function first loads weight (the corresponding function : getWeight) from weight_strm Then, read sample from sample_strm, and output its classification id into predictionsStrm streams

Parameters:

MType The data type of sample
WD The width of data type MType, can get by sizeof(MType)
StreamN The stream number of input sample stream vector
SampleDepth stream depth number of one input sample
cols colum number of input data sample
sample_strm Input data streams of MType
e_sample_strm End flag stream for input data
weight_strm weight streams
eTag End flag stream for weight streams
predictionsStrm Output data streams
predictionsTagStrm End flag stream for output

Hardware Functions in xf::data_analytics::clustering

kMeansPredict

#include "xf_data_analytics/clustering/kmeansPredict.hpp"
template <
    typename DT,
    int Dim,
    int Kcluster,
    int uramDepth,
    int KU,
    int DV
    >
void kMeansPredict (
    hls::stream <ap_uint <sizeof (DT)*8>> sampleStrm [DV],
    hls::stream <bool>& endSampleStrm,
    ap_uint <sizeof (DT)*8*DV> centers [KU][uramDepth],
    const int dims,
    const int kcluster,
    hls::stream <ap_uint <32>>& tagStrm,
    hls::stream <bool>& endTagStrm
    )

kMeansPredict predicts cluster index for each sample. In order to achive to acceleration, please make sure partition 1-dim of centers.

Parameters:

DT data type, supporting float and double
Dim the maximum number of dimensions,dynamic number of dimension should be not greater than the maximum.
Kcluster the maximum number of cluster,dynamic number of cluster should be not greater than the maximum.
uramDepth

the depth of uram where centers are stored. uramDepth should be not less than ceiling(Kcluster/KU)

  • ceil(Dim/DV)
KU unroll factor of Kcluster, KU centers are took part in calculating distances concurrently with one sample. After Kcluster/KU+1 times at most, ouput the minimum distance of a sample and Kcluster centers.
DV unroll factor of Dim, DV elements in a center are took part in calculating distances concurrently with one sample.
sampleStrm input sample streams, a sample needs ceiling(dims/DV) times to read.
endSampleStrm the end flag of sample stream.
centers an array stored centers, user should partition dim=1 in its defination.
dims the number of dimensions.
kcluster the number of clusters.
tagStrm tag stream, label a cluster ID for each sample.
endTagStrm end flag of tag stream.

Hardware Functions in xf::data_analytics::regression

decisionTreePredict

#include "xf_data_analytics/regression/decision_tree_predict.hpp"
template <
    typename MType,
    unsigned int WD,
    unsigned int MAX_FEA_NUM,
    unsigned int MAX_TREE_DEPTH = 10
    >
void decisionTreePredict (
    hls::stream <ap_uint <WD>> dstrm_batch [MAX_FEA_NUM],
    hls::stream <bool>& estrm_batch,
    hls::stream <ap_uint <512>>& treeStrm,
    hls::stream <bool>& treeTag,
    hls::stream <MType>& predictionsStrm,
    hls::stream <bool>& predictionsTag
    )

decisionTreePredict, Top function of Decision Tree Predict.

This function first loads decision tree (the corresponding function : getTree) from treeStrm Then, read sample one by one from dstrm_batch, and output its category id into predictionsStrm streams

Note that the treeStrm is a 512-bit stream, and each 512 bits include two nodes. In each 512-bit confirm the range(0,71) is node[i].nodeInfo and range(256,327) is node[i+1].nodeInfo the range(72,135) is node[i].regValue and range(328,391) is node[i+1].regValue the range(192,255) is node[i].threshold and range(448,511) is node[i+1].threshold For detailed info of NodeR struct, can refer “decision_tree_L1.hpp” Samples in input sample stream should be converted into ap_uint<WD> from MType

Parameters:

MType The data type of sample
WD The width of data type MType, can get by sizeof(MType)
MAX_FEA_NUM The max feature num function can support
MAX_TREE_DEPTH The max tree depth function can support
dstrm_batch Input data streams of ap_uint<WD>
estrm_batch End flag stream for input data
treeStrm Decision tree streams
treeTag End flag stream for decision tree nodes
predictionsStrm Output regression value streams
predictionsTagStrm End flag stream for output

Hardware Functions in xf::data_analytics::text

editDistance

#include "xf_data_analytics/text/editDistance.hpp"
template <
    int N,
    int M,
    int BITS
    >
void editDistance (
    hls::stream <ap_uint <BITS>>& len1_strm,
    hls::stream <ap_uint <64>>& query_strm,
    hls::stream <ap_uint <BITS>>& len2_strm,
    hls::stream <ap_uint <64>>& input_strm,
    hls::stream <ap_uint <BITS>>& max_ed_strm,
    hls::stream <bool>& i_e_strm,
    hls::stream <bool>& o_e_strm,
    hls::stream <bool>& o_match_strm
    )

Levenshtein distance implementation.

Parameters:

N maximum length of query string.
M maximum length of input stream string, N must be less than M.
BITS data width of internal edit distance in bits.
len1_strm length of the query string in bytes.
query_strm the query string folded into mutiple 8B elements.
len2_strm length of each input string in bytes.
input_strm input strings to compute edit distance against the given query string, which is folded into multiple 8B elements.
max_ed_strm the maximum threshold of edit distance.
i_e_strm end flag of input_strm and max_ed_strm.
o_e_strm end flag of output matched stream.
o_match_strm only the calculated ED less than threshold in max_ed_strm will be TRUE.

regexVM

#include "xf_data_analytics/text/regexVM.hpp"
template <int STACK_SIZE>
void regexVM (
    ap_uint <32>* bitSetBuff,
    ap_uint <64>* instrBuff,
    ap_uint <32>* msgBuff,
    unsigned int lenMsg,
    ap_uint <2>& match,
    ap_uint <16>* offsetBuff
    )

Implementation for regular expression VM (1 instruction per iteration).

Parameters:

STACK_SIZE Size of internal stack.
bitSetBuff Bit set map for character class.
instrBuff Instruction buffer.
msgBuff Message buffer as input string.
lenMsg Length of input string.
match Flag to indicate whether the input string is matched or not, 0 for mismatch, 1 for match, 2 for stack overflow.
offsetBuff Offset address for each capturing group.

regexVM_opt

#include "xf_data_analytics/text/regexVM.hpp"
template <int STACK_SIZE>
void regexVM_opt (
    ap_uint <32>* bitSetBuff,
    ap_uint <64>* instrBuff,
    ap_uint <32>* msgBuff,
    unsigned int lenMsg,
    ap_uint <2>& match,
    ap_uint <16>* offsetBuff
    )

Implementation for regular expression VM (2 instructions per iteration).

Parameters:

STACK_SIZE Size of internal stack.
bitSetBuff Bit set map for cclass.
instrBuff Instruction buffer.
msgBuff Message buffer as input string.
lenMsg Length of input string.
match Flag to indicate whether the input string is matched or not, 0 for mismatch, 1 for match, 2 for stack overflow.
offsetBuff Offset address for each capturing group.

Hardware Functions in xf::data_analytics::dataframe

readFromDataFrame

#include "xf_data_analytics/dataframe/read_from_dataframe.hpp"
void readFromDataFrame (
    int field_type [17],
    ap_uint <64>* ddr_buff,
    hls::stream <Object>& obj_strm
    )

read the data frame format data from DDR and pack into object streams

Parameters:

field_type the data type of each field id (may obtained from schema)
ddr_buff the ddr that saves data
obj_strm output Object stream

writeToDataFrame

#include "xf_data_analytics/dataframe/write_to_dataframe.hpp"
void writeToDataFrame (
    hls::stream <Object>& obj_strm,
    ap_uint <64>* ddr_buff
    )

write object stream data to DDR

all field_id in each json line is unique maximum supported field_id number is 16

Parameters:

obj_strm input stream data with type Object Struct
ddr_buff DDR buffer to save parserd data in DataFrame format

Software C Functions

xf_re_compile

#include "xf_data_analytics/text/xf_re_compile.h"
int xf_re_compile (
    const char* pattern,
    unsigned int* bitset,
    uint64_t* instructions,
    unsigned int* instr_num,
    unsigned int* cclass_num,
    unsigned int* cpgp_nm,
    uint8_t* cpgp_name_val,
    uint32_t* cpgp_name_oft
    )

Software compiler for pre-compiling input regular expression.

Parameters:

pattern Input regular expression.
bitset Bit set map for each character class.
instructions Compiled instruction list derived from input pattern.
instr_num Number of instructions.
cclass_num Number of character classes.
cpgp_nm Number of capturing groups.
cpgp_name_val Buffer of every name of each capturing group.
cpgp_name_oft Starting offset addresses for the name of each capturing group.