{"id":23065562,"url":"https://github.com/iesl/box-embeddings","last_synced_at":"2026-03-16T22:02:08.958Z","repository":{"id":41991586,"uuid":"282553104","full_name":"iesl/box-embeddings","owner":"iesl","description":"Box Embeddings as Modules","archived":false,"fork":false,"pushed_at":"2022-09-22T15:27:12.000Z","size":9149,"stargazers_count":103,"open_issues_count":22,"forks_count":10,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-07-02T12:06:08.715Z","etag":null,"topics":["box-embedding","deep-learning","machine-learning"],"latest_commit_sha":null,"homepage":"https://www.iesl.cs.umass.edu/box-embeddings","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/iesl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-26T01:19:47.000Z","updated_at":"2025-06-15T22:00:07.000Z","dependencies_parsed_at":"2022-08-12T01:40:35.656Z","dependency_job_id":null,"html_url":"https://github.com/iesl/box-embeddings","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iesl/box-embeddings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iesl%2Fbox-embeddings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iesl%2Fbox-embeddings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iesl%2Fbox-embeddings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iesl%2Fbox-embeddings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iesl","download_url":"https://codeload.github.com/iesl/box-embeddings/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iesl%2Fbox-embeddings/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268133310,"owners_count":24201371,"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-07-31T02:00:08.723Z","response_time":66,"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":["box-embedding","deep-learning","machine-learning"],"created_at":"2024-12-16T05:08:58.076Z","updated_at":"2026-03-16T22:02:08.906Z","avatar_url":"https://github.com/iesl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"A fully open source Python library for **geometric representation learning**, compatible with both PyTorch and\nTensorFlow, which allows existing neural network layers to be replaced  with or transformed into boxes easily.\n\n![Tests](https://github.com/iesl/box-embeddings/workflows/Tests/badge.svg)\n![Typing/Doc/Style](https://github.com/iesl/box-embeddings/workflows/Typing/Doc/Style/badge.svg)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/iesl/box-embeddings/dev/main)\n[![codecov](https://codecov.io/gh/iesl/box-embeddings/branch/main/graph/badge.svg?token=XPNQI0QXFZ)](https://codecov.io/gh/iesl/box-embeddings)\n\n\u003chr/\u003e\n\n## 🌟 Features\n- Modular and reusable library that aids the researchers in studying probabilistic box embeddings.\n- Extensive documentation and example code, demonstrating the use of the library to make it easy to\n  adapt to existing codebases.\n- Rigorously unit-test the codebase with high coverage, ensuring an additional layer of reliability.\n- Customizable pipelines\n- Actively being maintained by [IESL at UMass](http://www.iesl.cs.umass.edu/)\n\n## 💻 Installation\n\n### Installing via pip\n\nThe preferred way to install Box Embeddings for regular usage, test, or integration into the existing workflow\nis via `pip`. Just run\n\n```shell\npip install box-embeddings\n```\n\n\n### Installing from source\n\nYou can also install Box Embeddings by cloning our git repository\n\n```shell\ngit clone https://github.com/iesl/box-embeddings\n```\n\nCreate a Python 3.7 or 3.8 virtual environment under the project directory and install the `Box Embeddings`\npackage in editable mode by running:\n\n```shell\nvirtualenv box_venv\nsource box_venv/bin/activate\npip install --editable . --user\npip install -r core_requirements.txt\n```\n## 👟 Quick start\nAfter installing `Box Embeddings`, a box can be initialized from a tensor as follows:\n\n```python\nimport torch\nfrom box_embeddings.parameterizations.box_tensor import BoxTensor\ndata_x = torch.tensor([[1,2],[-1,5]])\nbox_x = BoxTensor(data_x)\nbox_x\n```\n\nThe result `box_x` is now a `BoxTensor` object. To view other examples, visit the\n[examples section](https://github.com/iesl/box-embeddings/tree/main/usage_doc).\n\n```python\nBoxTensor(tensor([[ 1,  2],\n        [-1,  5]]))\n```\n\n\n## 📖 Command Overview\n\n| Command | Description |\n| --- | --- |\n| `box_embeddings` | An open-source library for NLP or graph learning |\n| `box_embeddings.common` | Utility modules that are used across the library |\n| `box_embeddings.initializations` | Initialization modules |\n| `box_embeddings.modules` | A collection of modules to operate on boxes|\n| `box_embeddings.parameterizations` | A collection of modules to parameterize boxes|\n\n\n## 📍 Navigating the codebase\n\n| Task | Where to go |\n| --- |:---:|\n| Contribution manual | [Link](https://github.com/iesl/box-embeddings/blob/main/.github/CONTRIBUTING.md) |\n| Source codes | [Link](https://github.com/iesl/box-embeddings/tree/main/box_embeddings) |\n| Usage documentation| [Link](https://github.com/iesl/box-embeddings/tree/main/usage_doc) |\n| Training examples | [Link](https://github.com/iesl/box-embeddings/tree/main/examples)|\n| Unit tests | [Link](https://github.com/iesl/box-embeddings/tree/main/tests)|\n\n## 📚 Reference\n\n1. If you use this library in you work, please cite the following arXiv version of the paper\n```bibtex\n@article{chheda2021box,\n  title={Box Embeddings: An open-source library for representation learning using geometric structures},\n  author={Chheda, Tejas and Goyal, Purujit and Tran, Trang and Patel, Dhruvesh and Boratko, Michael\n  and Dasgupta, Shib Sankar and McCallum, Andrew},\n  journal={arXiv preprint arXiv:2109.04997},\n  year={2021}\n}\n```\n\n2. If you use simple hard boxes with surrogate loss then cite the following paper:\n\n```bibtex\n@inproceedings{vilnis2018probabilistic,\n  title={Probabilistic Embedding of Knowledge Graphs with Box Lattice Measures},\n  author={Vilnis, Luke and Li, Xiang and Murty, Shikhar and McCallum, Andrew},\n  booktitle={Proceedings of the 56th Annual Meeting of the Association for\n  Computational Linguistics (Volume 1: Long Papers)},\n  pages={263--272},\n  year={2018}\n}\n```\n\n3. If you use softboxes without any regularizaton the cite the following paper:\n\n```bibtex\n@inproceedings{li2018smoothing,\ntitle={Smoothing the Geometry of Probabilistic Box Embeddings},\nauthor={Xiang Li and Luke Vilnis and Dongxu Zhang and Michael Boratko and Andrew McCallum},\nbooktitle={International Conference on Learning Representations},\nyear={2019},\nurl={https://openreview.net/forum?id=H1xSNiRcF7},\n}\n```\n\n4. If you use softboxes with regularizations defined in the `Regularizations` module then cite the following paper:\n\n```bibtex\n@inproceedings{patel2020representing,\ntitle={Representing Joint Hierarchies with Box Embeddings},\nauthor={Dhruvesh Patel and Shib Sankar Dasgupta and Michael Boratko and Xiang Li and Luke Vilnis\nand Andrew McCallum},\nbooktitle={Automated Knowledge Base Construction},\nyear={2020},\nurl={https://openreview.net/forum?id=J246NSqR_l}\n}\n```\n\n5. If you use Gumbel box then cite the following paper:\n\n```bibtex\n@article{dasgupta2020improving,\n  title={Improving Local Identifiability in Probabilistic Box Embeddings},\n  author={Dasgupta, Shib Sankar and Boratko, Michael and Zhang, Dongxu and Vilnis, Luke\n  and Li, Xiang Lorraine and McCallum, Andrew},\n  journal={arXiv preprint arXiv:2010.04831},\n  year={2020}\n}\n```\n\n## 💪 Contributors\n\n* Dhruvesh Patel [@dhruvdcoder](https://github.com/dhruvdcoder)\n\n* Shib Sankar Dasgupta [@ssdasgupta](https://github.com/ssdasgupta)\n\n* Michael Boratko [@mboratko](https://github.com/mboratko)\n\n* Xiang (Lorraine) Li [@Lorraine333](https://github.com/Lorraine333)\n\n* Trang Tran [@trangtran72](https://github.com/trangtran72)\n\n* Purujit Goyal [@purujitgoyal](https://github.com/purujitgoyal)\n\n* Tejas Chheda [@tejas4888](https://github.com/tejas4888)\n\nWe welcome all contributions from the community to make Box Embeddings a better package.\nIf you're a first time contributor, we recommend you start by reading our\n[CONTRIBUTING.md](https://github.com/iesl/box-embeddings/blob/main/.github/CONTRIBUTING.md) guide.\n\n\n## 💡 News and Updates\nOur library `Box Embeddings` will be officially introduced at EMNLP 2021!\n\n## 🤗 Acknowledgments\nBox Embeddings is an open-source project developed by the research team from the\n[Information Extraction and Synthesis Laboratory](http://www.iesl.cs.umass.edu/) at the\n[College of Information and Computer Sciences (UMass Amherst)](https://www.cics.umass.edu/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiesl%2Fbox-embeddings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiesl%2Fbox-embeddings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiesl%2Fbox-embeddings/lists"}