Implementation:Recommenders team Recommenders GeoIMC Algorithm

Knowledge Sources	Recommenders
Domains	Matrix Completion, Manifold Optimization, Recommendation
Last Updated	2026-02-10 00:00 GMT

Overview

The IMCProblem class implements the core GeoIMC (Geometric Inductive Matrix Completion) optimization problem, performing matrix completion on a Riemannian manifold using side feature information.

Description

The IMCProblem class sets up an optimization problem over a product manifold consisting of two Stiefel manifolds and a symmetric positive definite manifold, corresponding to the U, B, V parametrization of the low-rank solution. The cost function computes the reconstruction error on observed entries of the rating matrix (stored as a CSR sparse matrix) plus L2 regularization on the B matrix (controlled by lambda1). The Euclidean gradient (_egrad) is computed analytically for all three components, with the B gradient symmetrized. A numba-accelerated (@njit with nogil and parallel) static method _computeLoss_csrmatrix computes residuals efficiently in CSR format. The solve method uses Pymanopt's Conjugate Gradient solver with backtracking line search to find the optimal U, B, V matrices. The optima_reached flag prevents redundant re-optimization, and reset clears the solution state.

Usage

Use the IMCProblem class when you need to perform inductive matrix completion with user and item side features. This approach is suitable when side information (feature matrices X and Z) is available and the goal is to complete a partially observed rating matrix while operating on a geometrically meaningful manifold. Configure the rank parameter to control the dimensionality of the factorization and lambda1 for regularization strength.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/models/geoimc/geoimc_algorithm.py
• Lines: 1-176

Signature

class IMCProblem(object):
    def __init__(self, dataPtr, lambda1=1e-2, rank=10)
    def _loadTarget(self)
    @staticmethod
    @njit(nogil=True, parallel=True)
    def _computeLoss_csrmatrix(a, b, cd, indices, indptr, residual_global)
    def _cost(self, params, residual_global)
    def _egrad(self, params, residual_global)
    def solve(self, *args)
    def _optimize(self, max_opt_time, max_opt_iter, verbosity)
    def reset(self)

Import

from recommenders.models.geoimc.geoimc_algorithm import IMCProblem

I/O Contract

Inputs

Name	Type	Required	Description
dataPtr	DataPtr	Yes	Data object containing X (row features), Z (column features), and target matrix Y
lambda1	float	No	Regularization parameter for B matrix (default 1e-2)
rank	int	No	Rank of the U, B, V factorization (default 10)
max_opt_time (solve)	int	Yes	Maximum optimization time in seconds
max_opt_iter (solve)	int	Yes	Maximum number of optimization iterations
verbosity (solve)	int	Yes	Verbosity level for Pymanopt solver logs

Outputs

Name	Type	Description
W (attribute)	list	List of three numpy arrays [U, B, V] representing the optimized manifold solution
_optimize return	float	Final cost value after optimization

Usage Examples

Basic Usage

from recommenders.models.geoimc.geoimc_algorithm import IMCProblem

# Initialize the IMC problem with data and hyperparameters
imc = IMCProblem(dataPtr=data, lambda1=1e-2, rank=10)

# Solve the optimization problem
imc.solve(max_opt_time=200, max_opt_iter=20, verbosity=0)

# Access the learned parameters
U, B, V = imc.W

# Reset and re-solve with different settings
imc.reset()
imc.solve(max_opt_time=500, max_opt_iter=50, verbosity=1)