{"id":31939682,"url":"https://github.com/alibaba/curvature-learning-framework","last_synced_at":"2025-10-14T08:44:56.276Z","repository":{"id":46091524,"uuid":"392245702","full_name":"alibaba/Curvature-Learning-Framework","owner":"alibaba","description":"Curvlearn, a Tensorflow based non-Euclidean deep learning framework.","archived":false,"fork":false,"pushed_at":"2022-04-24T03:48:06.000Z","size":11354,"stargazers_count":165,"open_issues_count":3,"forks_count":32,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-09-23T00:43:32.894Z","etag":null,"topics":["geometric-deep-learning","hyperbolic","non-euclidean-deep-learning","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alibaba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-03T08:29:06.000Z","updated_at":"2025-09-17T10:22:14.000Z","dependencies_parsed_at":"2022-08-31T11:23:49.125Z","dependency_job_id":null,"html_url":"https://github.com/alibaba/Curvature-Learning-Framework","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alibaba/Curvature-Learning-Framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FCurvature-Learning-Framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FCurvature-Learning-Framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FCurvature-Learning-Framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FCurvature-Learning-Framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alibaba","download_url":"https://codeload.github.com/alibaba/Curvature-Learning-Framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FCurvature-Learning-Framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018302,"owners_count":26086345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geometric-deep-learning","hyperbolic","non-euclidean-deep-learning","tensorflow"],"created_at":"2025-10-14T08:44:51.525Z","updated_at":"2025-10-14T08:44:56.268Z","avatar_url":"https://github.com/alibaba.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=center\u003e\n    \u003cimg src=\"docs/logo.png\" width=\"400\"\u003e\n\u003c/div\u003e\n\nEnglish | [简体中文](README_CN.md) \n\n#### *NEWS!*\n- [April 16] [*CurvFaiss*](examples/curvfaiss/README.md), the nearest neighbor search tool in the non-Euclidean space, is available now! \n- [March 29] Our paper *[AMCAD: Adaptive Mixed-Curvature Representation based Advertisement Retrieval System](https://arxiv.org/abs/2203.14683)* has been accepted by ICDE'22!\n- [November 03] The [detailed explanation](https://mp.weixin.qq.com/s/uP_wU5nnd7faBoo5B_7Xfw?spm=ata.21736010.0.0.5b9d2c7eQ67WZg) is posted on Alimama Tech Blog!\n\n## Why Non-Euclidean Geometry\n\nConsidering these simple graph structures shown below. Nodes with same color has 2-hop distance whereas 1-hop distance between nodes with different color. Now how could we embed these structures in Euclidean space while keeping these distance unchanged?\n\n\u003cdiv align=center\u003e\n    \u003cimg src=\"docs/graph_structure.png\" width=\"400\"\u003e\n\u003c/div\u003e\n\nActually perfect embedding without distortion, appearing naturally in hyperbolic (negative curvature) or spherical (positive curvature) space, is infeasible in Euclidean space [[1](https://arxiv.org/abs/1911.05076)].\n\nAs shown above, due to the high capacity of modeling complex structured data, e.g. scale-free, hierarchical or cyclic, there has been an growing interest in building deep learning models under non-Euclidean geometry, e.g. link prediction [[2](https://arxiv.org/abs/1910.12933)], recommendation [[3](https://arxiv.org/abs/1809.01703)]. \n\n## What's CurvLearn\n\nIn this repository, we provide a framework, named ```CurvLearn```,  for training deep learning models in non-Euclidean spaces. \n\nThe framework implements the non-Euclidean operations in Tensorflow and remains the similar interface style for developing deep learning models. \n\nCurrently, ```CurvLearn``` serves for training several recommendation models in Alibaba. We implement ```CurvLearn``` on top of our distributed (graph/deep learning) training engines including [Euler](https://github.com/alibaba/euler) and [x-deeplearning](https://github.com/alibaba/x-deeplearning). The figure below shows how the category tree is embedded in hyperbolic space by using ```CurvLearn```.\n\n\u003cdiv align=center\u003e\n    \u003cimg src=\"docs/sample.png\" width=\"400\"\u003e\n\u003c/div\u003e\n\n\n## Why CurvLearn\n\n```CurvLearn``` has the following major features.\n\n1. **Easy-to-Use**. Converting a Tensorflow model from Euclidean space to non-Euclidean spaces with ```CurvLearn``` is graceful and undemanding, due to the manifold operations are decoupled from model architecture and similar to vanilla Tensorflow operations. For researchers, ```CurvLearn``` also reserves lucid [interfaces](curvlearn/README.md) for developing novel manifolds and optimizers. \n2. **Comprehensive methods**. ```CurvLearn``` is the first Tensorflow based non-Euclidean deep learning framework and supports several typical non-Euclidean spaces, e.g. constant curvature and mixed-curvature manifolds, together with necessary manifold operations and optimizers.\n3. **Verified by tremendous industrial traffic**. ```CurvLearn``` is serving on Alibaba's sponsored search platform with billions of online traffic in several key scenarios e.g. matching and cate prediction. Compared to Euclidean models, ```CurvLearn``` can bring more revenue and the RPM (revenue per mille) increases more than 1%.\n\nNow we are working on exploring more non-Euclidean methods and integrating operations with Tensorflow. PR is welcomed!\n\n## CurvLearn Architecture\n\n\u003cdiv align=center\u003e\n    \u003cimg src=\"docs/architecture.png\" width=\"400\"\u003e\n\u003c/div\u003e\n\n\n### Manifolds\n\nWe implemented several types of constant curvature manifolds and the mixed-curvature manifold.\n\n- ```curvlearn.manifolds.Euclidean``` - Euclidean space with zero curvature.\n- ```curvlearn.manifolds.Stereographic``` - Constant curvature stereographic projection model. The curvature can be positive, negative or zero.\n- ```curvlearn.manifolds.PoincareBall``` - The stereographic projection of the Lorentz model with negative curvature.\n- ```curvlearn.manifolds.ProjectedSphere``` - The stereographic projection of the sphere model with positive curvature.\n- ```curvlearn.manifolds.Product``` - Mixed-curvature space consists of multiple manifolds with different curvatures.\n\n### Operations\n\nTo build a non-Euclidean deep neural network, we implemented several basic neural network operations. Complex operations can be decomposed into basic operations explicitly or realized in tangent space implicitly.\n\n- ```variable(t, c)``` - Defines a riemannian variable from manifold or tangent space at origin according to its name.\n- ```to_manifold(t, c, base)``` - Converts a tensor ```t``` in the tangent space of ```base``` point to the manifold.\n- ```to_tangent(t, c, base)``` - Converts a tensor ```t``` in the manifold to the tangent space of ```base``` point.\n- ```weight_sum(tensor_list, a, c)``` - Computes the sum of tensor list ```tensor_list``` with weight list ```a```.\n- ```mean(t, c, axis)``` - Computes the average of elements along ```axis``` dimension of a tensor ```t```.\n- ```sum(t, c, axis)``` - Computes the sum of elements along ```axis``` dimension of a tensor ```t```.\n- ```concat(tensor_list, c, axis)``` - Concatenates tensor list ```tensor_list``` along ```axis``` dimension.\n- ```matmul(t, m, c)``` - Multiplies tensor ```t``` by euclidean matrix ```m```.\n- ```add(x, y, c)``` - Adds tensor ```x``` and tensor ```y```.\n- ```add_bias(t, b, c)``` - Adds a euclidean bias vector ```b``` to tensor ```t```.\n- ```activation(t, c_in, c_out, act)``` - Computes the value of  activation function ```act``` for the input tensor ```t```.\n- ```linear(t, in_dim, out_dim, c_in, c_out, act, scope)``` - Computes the linear transformation for the input tensor ```t```.\n- ```distance(src, tar, c)``` - Computes the squared geodesic/distance between ```src``` and ```tar```.\n\n### Optimizers\n\nWe also implemented several typical riemannian optimizers. Please refer to [[4](https://arxiv.org/abs/1810.00760)] for more details.\n\n- ```curvlearn.optimizers.rsgd``` - Riemannian stochastic gradient optimizer.\n- ```curvlearn.optimizers.radagrad``` - Riemannian Adagrad optimizer.\n- ```curvlearn.optimizers.radam``` - Riemannian Adam optimizer.\n\n## How to use CurvLearn\n\nTo get started with ```CurvLearn``` quickly, we provide a simple binary classification model as a quick start and three representative examples for the application demo.\nNote that the non-Euclidean model is sensitive to the hyper-parameters such as learning rate, loss functions, optimizers, and initializers. It is necessary to tune those hyper-parameters when transferring to other datasets.\n\n### Installation\n\n```CurvLearn``` requires tensorflow~=1.15, compatible with both python 2/3.\n\nThe preferred way for installing is via `pip`. \n\n```bash\npip install curvlearn\n```\n\n### Quick Start\n\nHere we show how to build binary classification model using ```CurvLearn```. Model includes ```Stereographic``` manifold, ```linear``` operations , ```radam``` optimizer, etc.\n\nInstructions and implement details are shown in  [Quick Start](examples/quick_start.ipynb).\n\n### HGCN on Link Prediction [[2](https://arxiv.org/abs/1910.12933)]\n\nHGCN (Hyperbolic Graph Convolutional Neural Network) is the first inductive hyperbolic GCN that leverages \nboth the expressiveness of GCNs and hyperbolic geometry to learn inductive node representations for hierarchical and scale-free graphs.\nRun the command to check the accuracy on the OpenFlight airport dataset.\nRunning environment and performance are listed in [hgcn](examples/hgcn/README.md).\n\n```python\npython examples/hgcn/train.py\n```\n\n### HyperML on Recommendation Ranking [[3](https://arxiv.org/abs/1809.01703)]\n\nHyperML (Hyperbolic Metric Learning) applies hyperbolic geometry to recommender systems through metric learning approach \nand achieves state-of-the-art performance on multiple benchmark datasets.\nRun the command to check the accuracy on the Amazon Kindle-Store dataset. \nRunning environment and performance are listed in [hyperml](examples/hyperml/README.md).\n\n```python\npython examples/hyperml/train.py\n```\n\n###  Hyper Tree Pre-train Model\n\nIn the real-world, data is often organized in tree-like structure or can be represented hierarchically.\nIt has been proven that hyperbolic deep neural networks have significant advantages over tree-data representation than Euclidean models.\nIn this case, we present a hyperbolic graph pre-train model for category tree in [Taobao](https://www.taobao.com/).\nThe further details including dataset description, model architecture and visualization of results can be found in [CateTreePretrain](examples/tree_pretrain/README.md).\n\n```\npython examples/tree_pretrain/run_model.py\n```\n\n## References\n\n[1] Bachmann, Gregor, Gary Bécigneul, and Octavian Ganea. \"Constant curvature graph convolutional networks.\" *International Conference on Machine Learning*. PMLR, 2020.\n\n[2] Chami, Ines, et al. \"Hyperbolic graph convolutional neural networks.\" *Advances in neural information processing systems* 32 (2019): 4868-4879.\n\n[3] Vinh Tran, Lucas, et al. \"Hyperml: A boosting metric learning approach in hyperbolic space for recommender systems.\" *Proceedings of the 13th International Conference on Web Search and Data Mining*. 2020.\n\n[4] Bécigneul, Gary, and Octavian-Eugen Ganea. \"Riemannian adaptive optimization methods.\" *arXiv preprint arXiv:1810.00760* (2018).\n\n## License\nThis project is licensed under the Apache License, Version 2.0, unless otherwise explicitly stated.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fcurvature-learning-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falibaba%2Fcurvature-learning-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fcurvature-learning-framework/lists"}