![logo](https://github.com/joserapa98/tensorkrowch/blob/master/docs/figures/svg/tensorkrowch_logo_dark.svg#gh-dark-mode-only) ![logo](https://github.com/joserapa98/tensorkrowch/blob/master/docs/figures/svg/tensorkrowch_logo_light.svg#gh-light-mode-only) [![DOI](https://zenodo.org/badge/453954432.svg)](https://zenodo.org/badge/latestdoi/453954432) # Tensor Networks with PyTorch **TensorKrowch** is a Python library built on top of **PyTorch** that simplifies the training of Tensor Networks as machine learning models and their integration into deep learning pipelines. The primary goal of **TensorKrowch** is to offer an efficient and user-friendly framework for constructing and training diverse Tensor Networks. By providing essential components like ``Nodes``, ``Edges``, and ``TensorNetworks``, **TensorKrowch** facilitates the creation and training of these models. Notably, even the included implementations of ``MPS`` or ``PEPS`` only rely on these fundamental components. As a result, users who grasp the basic tools of **TensorKrowch** gain the ability to build a wide range of networks, ranging from simple Matrix Product States to more intricate architectures. The true strength of **TensorKrowch** lies in its support for rapid experimentation, enabling users to create and train different models with just a few lines of code changes. It's important to note that while **TensorKrowch** is a versatile library, it may not always be the fastest option in certain scenarios. However, it excels as a tool for exploration and identification of the most suitable Tensor Network. Once the ideal network is determined, users can develop further optimized code specifically tailored to that network. Nevertheless, **TensorKrowch** incorporates various optimizations to ensure efficient training performance. ## Documentation For detailed usage instructions, API reference, and code examples, please refer to the official **TensorKrowch** [documentation](https://joserapa98.github.io/tensorkrowch). ## Requirements * python >= 3.8 * torch >= 1.9 * opt_einsum >= 3.0 ## Installation To install the package, run the following command: ``` pip install tensorkrowch ``` You can also install directly from GitHub with: ``` pip install git+https://github.com/joserapa98/tensorkrowch.git@master ``` or download the repository on your computer and run ``` pip install . ``` in the repository folder. Tests are written outside the Python module, therefore they are not installed together with the package. To test the installation, clone the repository and run, in a Unix terminal ``` python -m pytest -v ``` inside the repository folder. > [!NOTE] Certain tests may experience failure as a result of statistical anomalies or hardware constraints. We advise reviewing the error messages to determine if these failures stem from such occurrences. Should this be the case, consider rerunning the tests to ascertain if the errors persist. ## Example With **TensorKrowch** you can experiment building Tensor Networks: ```python import torch import tensorkrowch as tk net = tk.TensorNetwork() node1 = tk.randn(shape=(7, 5), axes_names=('left', 'right'), name='node1', network=net, param_node=True) node2 = tk.randn(shape=(7, 5), axes_names=('left', 'right'), name='node2', network=net, param_node=True) node1['left'] ^ node2['left'] node1['right'] ^ node2['right'] ``` It is also quite easy to contract the network and compute gradients: ```python result = node1 @ node2 result.tensor.backward() assert node1.grad is not None assert node2.grad is not None ``` In **TensorKrowch** ``TensorNetworks`` work like **PyTorch** layers. Thus creating hybrid neural-tensor network models is straightforward: ```python import torch.nn as nn my_model = nn.Sequential( tk.models.MPSLayer(n_features=101, in_dim=3, out_dim=10, bond_dim=5), nn.ReLU(), nn.Linear(10, 10)) data = torch.randn(500, 100, 3) # batch x n_features x in_dim my_model(data) # batch x out_dim ``` ## Tutorials To fully grasp the basic components of **TensorKrowch** and harness its potential, it is highly recommended to explore the available tutorials. These tutorials provide a detailed introduction to the fundamental elements of the library and guide you through the process of constructing and training tensor networks. By immersing yourself in the tutorials, you will become familiar with key concepts and best practices for using **TensorKrowch**. You will learn how to define ``Nodes``, create connections between through their ``Edges``, and configure the ``TensorNetwork`` structure. This hands-on approach will greatly enhance your understanding and proficiency with **TensorKrowch**. * [First Steps with TensorKrowch](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/0_first_steps.html) * [Creating a Tensor Network in TensorKrowch](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/1_creating_tensor_network.html) * [Contracting and Differentiating the Tensor Network](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/2_contracting_tensor_network.html) * [How to save Memory and Time with TensorKrowch (ADVANCED)](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/3_memory_management.html) * [The different Types of Nodes (ADVANCED)](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/4_types_of_nodes.html) * [How to subclass TensorNetwork to build Custom Models](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/5_subclass_tensor_network.html) * [Creating a Hybrid Neural-Tensor Network Model](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/6_mix_with_pytorch.html) ## Example Notebooks In addition to the informative tutorials, there is also a collection of examples that serve as practical demonstrations of how to apply **TensorKrowch** in various contexts, showcasing its versatility. With the code provided in the examples, you will be able to reproduce key research findings that bridge the gap between tensor networks and machine learning. These examples provide a hands-on approach to understanding the intricacies of **TensorKrowch**, allowing you to explore its potential and adapt it to your specific needs. * [Training MPS in different ways](https://joserapa98.github.io/tensorkrowch/_build/html/examples/training_mps.html) * [Hybrid Tensorial Neural Network model](https://joserapa98.github.io/tensorkrowch/_build/html/examples/hybrid_tnn_model.html) * [Tensorizing Neural Networks](https://joserapa98.github.io/tensorkrowch/_build/html/examples/tensorizing_nn.html) * [DMRG-like training of MPS](https://joserapa98.github.io/tensorkrowch/_build/html/examples/mps_dmrg.html) * [Hybrid DMRG-like training of MPS](https://joserapa98.github.io/tensorkrowch/_build/html/examples/mps_dmrg_hybrid.html) ## License **TensorKrowch** is licensed under the MIT License. Please see the [LICENSE](https://github.com/joserapa98/tensorkrowch/blob/master/LICENSE.txt) file for more information. ## Citing If you use TensorKrowch in your work, please cite [TensorKrowch's paper](https://www.arxiv.org/abs/2306.08595): - J. R. Pareja Monturiol, D. Pérez-García, and A. Pozas-Kerstjens, "TensorKrowch: Smooth integration of tensor networks in machine learning", Quantum **8**, 1364 (2024), arXiv:2306.08595. ``` @article{pareja2024tensorkrowch, title={Tensor{K}rowch: {S}mooth integration of tensor networks in machine learning}, author={Pareja Monturiol, Jos{\'e} Ram{\'o}n and P{\'e}rez-Garc{\'i}a, David and Pozas-Kerstjens, Alejandro}, journal={Quantum}, volume={8}, pages={1364}, year={2024}, publisher={Verein zur F{\"o}rderung des Open Access Publizierens in den Quantenwissenschaften}, doi = {10.22331/q-2024-06-11-1364}, archivePrefix = {arXiv}, eprint = {2306.08595} } ```

{ "_id": null, "home_page": null, "name": "tensorkrowch", "maintainer": null, "docs_url": null, "requires_python": ">=3.8", "maintainer_email": "Jos\u00e9 Ram\u00f3n Pareja Monturiol <joserapa98@gmail.com>", "keywords": "tensor, network, tensor network, tensor networks, mps, mpo, peps, quantum", "author": null, "author_email": "Jos\u00e9 Ram\u00f3n Pareja Monturiol <joserapa98@gmail.com>", "download_url": "https://files.pythonhosted.org/packages/39/a2/f31189c076aae6820c6144efb9793365821bc6d02e10d84df8b60ad3d4cb/tensorkrowch-1.1.5.tar.gz", "platform": null, "description": "![logo](https://github.com/joserapa98/tensorkrowch/blob/master/docs/figures/svg/tensorkrowch_logo_dark.svg#gh-dark-mode-only)\n![logo](https://github.com/joserapa98/tensorkrowch/blob/master/docs/figures/svg/tensorkrowch_logo_light.svg#gh-light-mode-only)\n\n[![DOI](https://zenodo.org/badge/453954432.svg)](https://zenodo.org/badge/latestdoi/453954432)\n\n# Tensor Networks with PyTorch\n\n**TensorKrowch** is a Python library built on top of **PyTorch** that simplifies\nthe training of Tensor Networks as machine learning models and their integration\ninto deep learning pipelines.\n\nThe primary goal of **TensorKrowch** is to offer an efficient and user-friendly\nframework for constructing and training diverse Tensor Networks. By providing\nessential components like ``Nodes``, ``Edges``, and ``TensorNetworks``,\n**TensorKrowch** facilitates the creation and training of these models. Notably,\neven the included implementations of ``MPS`` or ``PEPS`` only rely on these\nfundamental components.\n\nAs a result, users who grasp the basic tools of **TensorKrowch** gain the ability\nto build a wide range of networks, ranging from simple Matrix Product States to\nmore intricate architectures.\n\nThe true strength of **TensorKrowch** lies in its support for rapid experimentation,\nenabling users to create and train different models with just a few lines of code\nchanges.\n\nIt's important to note that while **TensorKrowch** is a versatile library, it\nmay not always be the fastest option in certain scenarios. However, it excels\nas a tool for exploration and identification of the most suitable Tensor Network.\nOnce the ideal network is determined, users can develop further optimized code\nspecifically tailored to that network.\n\nNevertheless, **TensorKrowch** incorporates various optimizations to ensure\nefficient training performance.\n\n\n## Documentation\n\nFor detailed usage instructions, API reference, and code examples, please refer\nto the official **TensorKrowch** [documentation](https://joserapa98.github.io/tensorkrowch).\n\n\n## Requirements\n\n* python >= 3.8\n* torch >= 1.9\n* opt_einsum >= 3.0\n\n\n## Installation\n\nTo install the package, run the following command:\n\n```\npip install tensorkrowch\n```\n\nYou can also install directly from GitHub with:\n\n```\npip install git+https://github.com/joserapa98/tensorkrowch.git@master\n```\n\nor download the repository on your computer and run \n\n```\npip install .\n```\n\nin the repository folder.\n\nTests are written outside the Python module, therefore they are not installed\ntogether with the package. To test the installation, clone the repository and\nrun, in a Unix terminal\n\n```\npython -m pytest -v\n```\n\ninside the repository folder.\n\n> [!NOTE]\nCertain tests may experience failure as a result of statistical anomalies or \nhardware constraints. We advise reviewing the error messages to determine if \nthese failures stem from such occurrences. Should this be the case, consider \nrerunning the tests to ascertain if the errors persist.\n\n\n## Example\n\nWith **TensorKrowch** you can experiment building Tensor Networks:\n\n```python\nimport torch\nimport tensorkrowch as tk\n\nnet = tk.TensorNetwork()\n\nnode1 = tk.randn(shape=(7, 5),\n axes_names=('left', 'right'),\n name='node1',\n network=net,\n param_node=True)\nnode2 = tk.randn(shape=(7, 5),\n axes_names=('left', 'right'),\n name='node2',\n network=net,\n param_node=True)\n\nnode1['left'] ^ node2['left']\nnode1['right'] ^ node2['right']\n```\n\nIt is also quite easy to contract the network and compute gradients:\n\n```python\nresult = node1 @ node2\nresult.tensor.backward()\n\nassert node1.grad is not None\nassert node2.grad is not None\n```\n\nIn **TensorKrowch** ``TensorNetworks`` work like **PyTorch** layers. Thus\ncreating hybrid neural-tensor network models is straightforward:\n\n```python\nimport torch.nn as nn\n\nmy_model = nn.Sequential(\n tk.models.MPSLayer(n_features=101,\n in_dim=3,\n out_dim=10,\n bond_dim=5),\n nn.ReLU(),\n nn.Linear(10, 10))\n\ndata = torch.randn(500, 100, 3) # batch x n_features x in_dim\nmy_model(data) # batch x out_dim\n```\n\n\n## Tutorials\n\nTo fully grasp the basic components of **TensorKrowch** and harness its potential,\nit is highly recommended to explore the available tutorials. These tutorials\nprovide a detailed introduction to the fundamental elements of the library and\nguide you through the process of constructing and training tensor networks.\n\nBy immersing yourself in the tutorials, you will become familiar with key\nconcepts and best practices for using **TensorKrowch**. You will learn how to\ndefine ``Nodes``, create connections between through their ``Edges``, and\nconfigure the ``TensorNetwork`` structure. This hands-on approach will greatly\nenhance your understanding and proficiency with **TensorKrowch**.\n\n* [First Steps with TensorKrowch](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/0_first_steps.html)\n* [Creating a Tensor Network in TensorKrowch](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/1_creating_tensor_network.html)\n* [Contracting and Differentiating the Tensor Network](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/2_contracting_tensor_network.html)\n* [How to save Memory and Time with TensorKrowch (ADVANCED)](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/3_memory_management.html)\n* [The different Types of Nodes (ADVANCED)](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/4_types_of_nodes.html)\n* [How to subclass TensorNetwork to build Custom Models](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/5_subclass_tensor_network.html)\n* [Creating a Hybrid Neural-Tensor Network Model](https://joserapa98.github.io/tensorkrowch/_build/html/tutorials/6_mix_with_pytorch.html)\n\n\n## Example Notebooks\n\nIn addition to the informative tutorials, there is also a collection of examples\nthat serve as practical demonstrations of how to apply **TensorKrowch** in\nvarious contexts, showcasing its versatility.\n\nWith the code provided in the examples, you will be able to reproduce key research\nfindings that bridge the gap between tensor networks and machine learning. These\nexamples provide a hands-on approach to understanding the intricacies of\n**TensorKrowch**, allowing you to explore its potential and adapt it to your\nspecific needs.\n\n* [Training MPS in different ways](https://joserapa98.github.io/tensorkrowch/_build/html/examples/training_mps.html)\n* [Hybrid Tensorial Neural Network model](https://joserapa98.github.io/tensorkrowch/_build/html/examples/hybrid_tnn_model.html)\n* [Tensorizing Neural Networks](https://joserapa98.github.io/tensorkrowch/_build/html/examples/tensorizing_nn.html)\n* [DMRG-like training of MPS](https://joserapa98.github.io/tensorkrowch/_build/html/examples/mps_dmrg.html)\n* [Hybrid DMRG-like training of MPS](https://joserapa98.github.io/tensorkrowch/_build/html/examples/mps_dmrg_hybrid.html)\n\n\n## License\n\n**TensorKrowch** is licensed under the MIT License. Please see the [LICENSE](https://github.com/joserapa98/tensorkrowch/blob/master/LICENSE.txt) file for more information.\n\n\n## Citing\n\nIf you use TensorKrowch in your work, please cite [TensorKrowch's paper](https://www.arxiv.org/abs/2306.08595):\n\n- J. R. Pareja Monturiol, D. P\u00e9rez-Garc\u00eda, and A. Pozas-Kerstjens, \n\"TensorKrowch: Smooth integration of tensor networks in machine learning\", \nQuantum **8**, 1364 (2024), arXiv:2306.08595.\n\n```\n@article{pareja2024tensorkrowch,\n title={Tensor{K}rowch: {S}mooth integration of tensor networks in machine learning},\n author={Pareja Monturiol, Jos{\\'e} Ram{\\'o}n and P{\\'e}rez-Garc{\\'i}a, David and Pozas-Kerstjens, Alejandro},\n journal={Quantum},\n volume={8},\n pages={1364},\n year={2024},\n publisher={Verein zur F{\\\"o}rderung des Open Access Publizierens in den Quantenwissenschaften},\n doi = {10.22331/q-2024-06-11-1364},\n archivePrefix = {arXiv},\n eprint = {2306.08595}\n}\n```\n", "bugtrack_url": null, "license": "MIT License Copyright (c) 2023 Jos\u00e9 Ram\u00f3n Pareja Monturiol Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ", "summary": "Tensor Networks with PyTorch", "version": "1.1.5", "project_urls": { "Documentation": "https://joserapa98.github.io/tensorkrowch", "GitHub": "https://github.com/joserapa98/tensorkrowch" }, "split_keywords": [ "tensor", " network", " tensor network", " tensor networks", " mps", " mpo", " peps", " quantum" ], "urls": [ { "comment_text": "", "digests": { "blake2b_256": "1ead964d1354f695f0b5b10cf7c4fe0227741e57bbeac7a7bf31a3cc65b28111", "md5": "4a7148c79fa64f5a9a5c98f0e74f52c4", "sha256": "f4d92b327b3f5b3e0e13b973b939edff8f95f8d44c4a88e1c0daec15dbf784e6" }, "downloads": -1, "filename": "tensorkrowch-1.1.5-py3-none-any.whl", "has_sig": false, "md5_digest": "4a7148c79fa64f5a9a5c98f0e74f52c4", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.8", "size": 135592, "upload_time": "2024-06-11T14:44:09", "upload_time_iso_8601": "2024-06-11T14:44:09.014445Z", "url": "https://files.pythonhosted.org/packages/1e/ad/964d1354f695f0b5b10cf7c4fe0227741e57bbeac7a7bf31a3cc65b28111/tensorkrowch-1.1.5-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "blake2b_256": "39a2f31189c076aae6820c6144efb9793365821bc6d02e10d84df8b60ad3d4cb", "md5": "e881f1142ea7d418baba24503209811b", "sha256": "88449af5df7ff1d2941c08003641db381cb4e784645b05cc5ef3c455fe4f75c6" }, "downloads": -1, "filename": "tensorkrowch-1.1.5.tar.gz", "has_sig": false, "md5_digest": "e881f1142ea7d418baba24503209811b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.8", "size": 129640, "upload_time": "2024-06-11T14:44:10", "upload_time_iso_8601": "2024-06-11T14:44:10.641122Z", "url": "https://files.pythonhosted.org/packages/39/a2/f31189c076aae6820c6144efb9793365821bc6d02e10d84df8b60ad3d4cb/tensorkrowch-1.1.5.tar.gz", "yanked": false, "yanked_reason": null } ], "upload_time": "2024-06-11 14:44:10", "github": true, "gitlab": false, "bitbucket": false, "codeberg": false, "github_user": "joserapa98", "github_project": "tensorkrowch", "travis_ci": false, "coveralls": false, "github_actions": true, "lcname": "tensorkrowch" }

Elapsed time: 0.25972s