template class xilinx_apps::cosinesim::CosineSim

Overview

The main API class for the Cosine Similarity Alveo Product. More…

#include <cosinesim.hpp>

template <typename Value>
class CosineSim
{
public:
    // typedefs

    typedef Value ValueType;

    // construction

    CosineSim(const Options& options);

    // methods

    const Options& getOptions();
    Value* getPopulationVectorBuffer(RowIndex& rowIndex);
    void finishCurrentPopulationVector(Value* pbuf);

    std::vector<Result> matchTargetVector(
        unsigned numResults,
        const Value* elements
        );
};

Detailed Documentation

The main API class for the Cosine Similarity Alveo Product.

Instantiate an object of this class to store population vectors in an Alveo accelerator card and run cosine similarity matches with target vectors.

Typedefs

typedef Value ValueType

the integral type of population and target vector elements (same as the Value template parameter)

Construction

CosineSim(const Options& options)

Constructs a CosineSim object.

Parameters:

options

the configuration options for consine similarity operations. See the Options struct for details.

Methods

const Options& getOptions()

Returns the configuration settings with which this CosineSim object was constructed. See Options for details.

Returns:

an Options struct containing the configuration settings

Value* getPopulationVectorBuffer(RowIndex& rowIndex)

Allocates a buffer for the caller to fill with population vector element values.

Call this function to fetch a buffer to fill with integers for one population vector. Also supply an integer variable, which is passed by reference, to receive the assigned row index for the population vector. Upon running matchTargetVector(), match results will contain this same row index to refer to the matching population vector.

After fetching the memory buffer, write your population vector values to the buffer. The buffer will be interpreted as a C array whose element type is an integer of the size specified in the valueSize argument to the CosineSimBase() constructor.

You may write to separate buffers from multiple threads simultaneously, but this function itself is not thread safe, so be sure to call it in a critical section.

Parameters:

rowIndex

an integer variable to receive the row index for the buffer

Returns:

a memory buffer large enough to hold enough integers for one population vector

void finishCurrentPopulationVector(Value* pbuf)

Processes a population vector buffer after the caller has filled it with population vector values.

After fetching a buffer with CosineSim::getPopulationVectorBuffer() and filling it with population vector values, call this function, passing the same buffer, to process the buffer for sending to the Alveo accelerator card.

Parameters:

pbuf	the population vector buffer

std::vector<Result> matchTargetVector(
    unsigned numResults,
    const Value* elements
    )

Runs a match of a given target vector against all population vectors.

The elements array argument must contain as many elements as specified in Options::vecLength.

Parameters:

numResults	the number of match results to return
elements	a C array of target vector elements

Returns:

a std::vector of Result objects, one per match result