EPCF

This repository contains the PyTorch implementation of EPCF: An Equivariant Positional Propagation Enhanced Graph Neural Network for Collaborative Filtering, a position-aware collaborative filtering model for recommendation. The code keeps a lightweight graph collaborative filtering pipeline and introduces coordinate-aware propagation and a coordinate regularization term for user-item representation learning.

Main Idea

EPCF enhances graph collaborative filtering by incorporating equivariant positional propagation on positional features extracted from the normalized interaction graph. During each propagation layer, the model:

• performs lightweight neighborhood aggregation;
• constructs equivariant edge representations from relative positional distances and embedding-level attention;
• propagates positional features via an equivariant message-passing mechanism that preserves permutation and orthogonal equivariance;
• fuses the resulting positional information with collaborative filtering embeddings;
• learns recommendation representations under a coordinate-aware BPR objective.

The model code is in code/model.py.

Project Structure

.
├── code/
│   ├── main.py          # Training entry point
│   ├── model.py         # PureMF and EPCF model definitions
│   ├── dataloader.py    # Dataset loaders
│   ├── procedure.py     # Training and evaluation routines
│   ├── register.py      # Dataset/model registry
│   ├── parse.py         # Command-line arguments
│   ├── utils.py         # Sampling, loss, metrics, and utilities
│   └── sources/         # Optional C++ negative sampler source
├── data/                # Processed datasets
├── requirements.txt
└── README.md

Environment

The original experiments used the dependency versions listed in requirements.txt.

pip install -r requirements.txt

The optional C++ sampler requires cppimport and pybind11. If it is not available, the code automatically falls back to the Python negative sampler.

Quick Start

Run training from the code directory:

cd code
python main.py --dataset gowalla --model epcf --layer 3 --recdim 32 --bpr_batch 256 --lr 0.0005 --decay 1e-4 --topks "[20]" --seed 2020

Common dataset names include:

gowalla, yelp2018, amazon-book, amazon-book-anotherversion,
amazon-kindle, douban-book, tmall, programmableweb, lastfm

Data Format

For most datasets, train.txt and test.txt use one user per line:

user_id item_id item_id ...

For two-column datasets loaded by Loaderbri, files use:

user_id item_id

All ids are expected to be zero-based. The two-column loader also handles one-based ids by converting them to zero-based ids.

Outputs

Training checkpoints are written to code/checkpoints/, and TensorBoard logs are written to code/runs/. These directories are ignored by Git.

Reproducibility Notes

The released code preserves the training objective, sampling strategy, propagation equations, evaluation metrics, and default hyperparameters used in the working experiment code. For comparable results, use the same dataset files, dependency versions, random seed, and hardware backend.

Acknowledgements

This project builds on a public PyTorch graph collaborative filtering implementation and keeps its data loading, BPR training, and evaluation structure where applicable.