Implementation:Recommenders team Recommenders PySARPlus Cpp

Knowledge Sources	Recommenders
Domains	Recommender Systems, Collaborative Filtering, High-Performance Computing
Last Updated	2026-02-10 00:00 GMT

Overview

High-performance C++ implementation of SAR (Smart Adaptive Recommendations) top-K prediction, exposed to Python via pybind11.

Description

The pysarplus.cpp file provides the performance-critical C++ backend for the SARplus recommendation engine. It defines three main components: MemoryMapFile, which uses POSIX mmap to map the pre-computed SAR similarity matrix file into shared memory for zero-copy access across Spark executors; item_score, a lightweight struct pairing item IDs with scores and providing comparison operators; and SARModel, the core prediction engine. The SARModel class reads the memory-mapped file, which stores item-to-item similarity data in a compact binary format with an offset table followed by sorted item-score pairs. The predict method iterates over items a user has interacted with, looks up related items via the offset table, computes recommendation scores using a join_prod_sum operation (a sorted merge join with dot-product accumulation using binary search), and maintains a bounded priority queue for efficient top-K selection. The module is compiled into a Python extension via pybind11, exposing SARModelCpp and SARPrediction classes.

Usage

This C++ module is used internally by the PySARPlus Python wrapper when high-performance prediction is needed for large-scale SAR models. It is compiled as a native extension and loaded automatically. Use it when running SAR recommendations on large datasets where pure Python or PySpark performance is insufficient.

Code Reference

Source Location

• Repository: Recommenders
• File: contrib/sarplus/python/src/pysarplus.cpp
• Lines: 1-224

Signature

// MemoryMapFile - memory-maps a file for zero-copy access
class MemoryMapFile {
public:
    MemoryMapFile(std::string& path);
    ~MemoryMapFile();
    void* addr();
};

// item_score - item ID and score pair
struct item_score {
    int32_t id;
    float score;
    int get_id();
    float get_score();
};

// SARModel - core prediction engine
class SARModel {
public:
    SARModel(std::string& path);
    std::vector<item_score> predict(
        std::vector<int32_t>& items_of_user,
        std::vector<float>& ratings,
        int32_t top_k,
        bool remove_seen
    );
};

// Python module (pybind11)
// Exposes: SARPrediction (.id, .score) and SARModelCpp (.predict)

Import

from pysarplus_cpp import SARModelCpp, SARPrediction

I/O Contract

Inputs

Name	Type	Required	Description
path	std::string	Yes	File path to the memory-mapped SAR similarity matrix binary file.
items_of_user	std::vector<int32_t>	Yes	List of item IDs the user has interacted with.
ratings	std::vector<float>	Yes	Corresponding ratings for each item in items_of_user. Must be the same length.
top_k	int32_t	Yes	Number of top recommended items to return.
remove_seen	bool	Yes	Whether to exclude items the user has already seen from the results.

Outputs

Name	Type	Description
return	std::vector<item_score>	List of top-K item predictions, each containing an item ID and a recommendation score.

Usage Examples

Basic Usage

from pysarplus_cpp import SARModelCpp

# Load the pre-computed SAR model from a binary file
model = SARModelCpp("/path/to/model.sar")

# Predict top-10 items for a user who has seen items [1, 5, 12]
# with corresponding ratings [4.0, 3.5, 5.0]
predictions = model.predict([1, 5, 12], [4.0, 3.5, 5.0], 10, True)

for pred in predictions:
    print(f"Item: {pred.id}, Score: {pred.score}")

Dependencies

• pybind11 - C++ to Python binding framework
• POSIX mmap - Memory-mapped file I/O for zero-copy data access
• C++ STL - priority_queue, vector, unordered_set, algorithm for efficient computation