<img src="https://user-images.githubusercontent.com/8702042/67589472-5a1d0e80-f70d-11e9-8812-64647814ae96.png" width="60%" height="60%">
[](https://travis-ci.org/google/TensorNetwork)
A tensor network wrapper for TensorFlow, JAX, PyTorch, and Numpy.
For an overview of tensor networks please see the following:
- [Matrices as Tensor Network Diagrams](https://www.math3ma.com/blog/matrices-as-tensor-network-diagrams)
- [Crash Course in Tensor Networks (video)](https://www.youtube.com/watch?v=YN2YBB0viKo)
- [Hand-waving and interpretive dance: an introductory course on tensor networks](https://iopscience.iop.org/article/10.1088/1751-8121/aa6dc3)
- [Tensor Networks in a Nutshell](https://arxiv.org/abs/1708.00006)
- [A Practical Introduction to Tensor Networks](https://arxiv.org/abs/1306.2164)
More information can be found in our TensorNetwork papers:
- [TensorNetwork: A Library for Physics and Machine Learning](https://arxiv.org/abs/1905.01330)
- [TensorNetwork on TensorFlow: A Spin Chain Application Using Tree Tensor Networks](https://arxiv.org/abs/1905.01331)
- [TensorNetwork on TensorFlow: Entanglement Renormalization for quantum critical lattice models](https://arxiv.org/abs/1906.12030)
- [TensorNetwork for Machine Learning](https://arxiv.org/abs/1906.06329)
## Installation
```
pip3 install tensornetwork
```
## Documentation
For details about the TensorNetwork API, see the [reference documentation.](https://tensornetwork.readthedocs.io)
## Tutorials
[Basic API tutorial](https://colab.research.google.com/drive/1Fp9DolkPT-P_Dkg_s9PLbTOKSq64EVSu)
[Tensor Networks inside Neural Networks using Keras](https://colab.research.google.com/github/google/TensorNetwork/blob/master/colabs/Tensor_Networks_in_Neural_Networks.ipynb)
## Basic Example
Here, we build a simple 2 node contraction.
```python
import numpy as np
import tensornetwork as tn
# Create the nodes
a = tn.Node(np.ones((10,)))
b = tn.Node(np.ones((10,)))
edge = a[0] ^ b[0] # Equal to tn.connect(a[0], b[0])
final_node = tn.contract(edge)
print(final_node.tensor) # Should print 10.0
```
## Optimized Contractions.
Usually, it is more computationally effective to flatten parallel edges before contracting them in order to avoid trace edges.
We have `contract_between` and `contract_parallel` that do this automatically for your convenience.
```python
# Contract all of the edges between a and b
# and create a new node `c`.
c = tn.contract_between(a, b)
# This is the same as above, but much shorter.
c = a @ b
# Contract all of edges that are parallel to edge
# (parallel means connected to the same nodes).
c = tn.contract_parallel(edge)
```
## Split Node
You can split a node by doing a singular value decomposition.
```python
# This will return two nodes and a tensor of the truncation error.
# The two nodes are the unitary matrices multiplied by the square root of the
# singular values.
# The `left_edges` are the edges that will end up on the `u_s` node, and `right_edges`
# will be on the `vh_s` node.
u_s, vh_s, trun_error = tn.split_node(node, left_edges, right_edges)
# If you want the singular values in it's own node, you can use `split_node_full_svd`.
u, s, vh, trun_error = tn.split_node_full_svd(node, left_edges, right_edges)
```
## Node and Edge names.
You can optionally name your nodes/edges. This can be useful for debugging,
as all error messages will print the name of the broken edge/node.
```python
node = tn.Node(np.eye(2), name="Identity Matrix")
print("Name of node: {}".format(node.name))
edge = tn.connect(node[0], node[1], name="Trace Edge")
print("Name of the edge: {}".format(edge.name))
# Adding name to a contraction will add the name to the new edge created.
final_result = tn.contract(edge, name="Trace Of Identity")
print("Name of new node after contraction: {}".format(final_result.name))
```
## Named axes.
To make remembering what an axis does easier, you can optionally name a node's axes.
```python
a = tn.Node(np.zeros((2, 2)), axis_names=["alpha", "beta"])
edge = a["beta"] ^ a["alpha"]
```
## Edge reordering.
To assert that your result's axes are in the correct order, you can reorder a node at any time during computation.
```python
a = tn.Node(np.zeros((1, 2, 3)))
e1 = a[0]
e2 = a[1]
e3 = a[2]
a.reorder_edges([e3, e1, e2])
# If you already know the axis values, you can equivalently do
# a.reorder_axes([2, 0, 1])
print(a.tensor.shape) # Should print (3, 1, 2)
```
## NCON interface.
For a more compact specification of a tensor network and its contraction, there is `ncon()`. For example:
```python
from tensornetwork import ncon
a = np.ones((2, 2))
b = np.ones((2, 2))
c = ncon([a, b], [(-1, 1), (1, -2)])
print(c)
```
## Different backend support.
Currently, we support JAX, TensorFlow, PyTorch and NumPy as TensorNetwork backends.
We also support tensors with Abelian symmetries via a `symmetric` backend, see the [reference
documentation](https://tensornetwork.readthedocs.io/en/latest/block_sparse_tutorial.html) for more details.
To change the default global backend, you can do:
```python
tn.set_default_backend("jax") # tensorflow, pytorch, numpy, symmetric
```
Or, if you only want to change the backend for a single `Node`, you can do:
```python
tn.Node(tensor, backend="jax")
```
If you want to run your contractions on a GPU, we highly recommend using JAX, as it has the closet API to NumPy.
## Disclaimer
This library is in *alpha* and will be going through a lot of breaking changes. While releases will be stable enough for research, we do not recommend using this in any production environment yet.
TensorNetwork is not an official Google product. Copyright 2019 The TensorNetwork Developers.
## Citation
If you are using TensorNetwork for your research please cite this work using the following bibtex entry:
```
@misc{roberts2019tensornetwork,
title={TensorNetwork: A Library for Physics and Machine Learning},
author={Chase Roberts and Ashley Milsted and Martin Ganahl and Adam Zalcman and Bruce Fontaine and Yijian Zou and Jack Hidary and Guifre Vidal and Stefan Leichenauer},
year={2019},
eprint={1905.01330},
archivePrefix={arXiv},
primaryClass={physics.comp-ph}
}
```
Raw data
{
"_id": null,
"home_page": "http://github.com/google/TensorNetwork",
"name": "tensornetwork",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "",
"author": "The TensorNetwork Developers",
"author_email": "martin.ganahl@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/93/32/55c2af4e7a6257a55e6598dd199ff3aa3ca567785c67948b2dfeb5019ae7/tensornetwork-0.4.6.tar.gz",
"platform": "",
"description": "<img src=\"https://user-images.githubusercontent.com/8702042/67589472-5a1d0e80-f70d-11e9-8812-64647814ae96.png\" width=\"60%\" height=\"60%\">\n\n[](https://travis-ci.org/google/TensorNetwork)\n\n\nA tensor network wrapper for TensorFlow, JAX, PyTorch, and Numpy.\n\nFor an overview of tensor networks please see the following: \n\n- [Matrices as Tensor Network Diagrams](https://www.math3ma.com/blog/matrices-as-tensor-network-diagrams)\n\n\n- [Crash Course in Tensor Networks (video)](https://www.youtube.com/watch?v=YN2YBB0viKo)\n\n- [Hand-waving and interpretive dance: an introductory course on tensor networks](https://iopscience.iop.org/article/10.1088/1751-8121/aa6dc3)\n\n- [Tensor Networks in a Nutshell](https://arxiv.org/abs/1708.00006)\n\n- [A Practical Introduction to Tensor Networks](https://arxiv.org/abs/1306.2164)\n\nMore information can be found in our TensorNetwork papers:\n\n- [TensorNetwork: A Library for Physics and Machine Learning](https://arxiv.org/abs/1905.01330)\n\n- [TensorNetwork on TensorFlow: A Spin Chain Application Using Tree Tensor Networks](https://arxiv.org/abs/1905.01331)\n\n- [TensorNetwork on TensorFlow: Entanglement Renormalization for quantum critical lattice models](https://arxiv.org/abs/1906.12030)\n\n- [TensorNetwork for Machine Learning](https://arxiv.org/abs/1906.06329)\n\n\n## Installation\n```\npip3 install tensornetwork\n```\n\n## Documentation\n\nFor details about the TensorNetwork API, see the [reference documentation.](https://tensornetwork.readthedocs.io)\n\n\n## Tutorials\n\n[Basic API tutorial](https://colab.research.google.com/drive/1Fp9DolkPT-P_Dkg_s9PLbTOKSq64EVSu)\n\n[Tensor Networks inside Neural Networks using Keras](https://colab.research.google.com/github/google/TensorNetwork/blob/master/colabs/Tensor_Networks_in_Neural_Networks.ipynb)\n## Basic Example\n\nHere, we build a simple 2 node contraction.\n```python\nimport numpy as np\nimport tensornetwork as tn\n\n# Create the nodes\na = tn.Node(np.ones((10,))) \nb = tn.Node(np.ones((10,)))\nedge = a[0] ^ b[0] # Equal to tn.connect(a[0], b[0])\nfinal_node = tn.contract(edge)\nprint(final_node.tensor) # Should print 10.0\n```\n\n## Optimized Contractions.\nUsually, it is more computationally effective to flatten parallel edges before contracting them in order to avoid trace edges.\nWe have `contract_between` and `contract_parallel` that do this automatically for your convenience. \n\n```python\n# Contract all of the edges between a and b\n# and create a new node `c`.\nc = tn.contract_between(a, b)\n# This is the same as above, but much shorter.\nc = a @ b\n\n# Contract all of edges that are parallel to edge \n# (parallel means connected to the same nodes).\nc = tn.contract_parallel(edge)\n```\n\n## Split Node\nYou can split a node by doing a singular value decomposition. \n```python\n# This will return two nodes and a tensor of the truncation error.\n# The two nodes are the unitary matrices multiplied by the square root of the\n# singular values.\n# The `left_edges` are the edges that will end up on the `u_s` node, and `right_edges`\n# will be on the `vh_s` node.\nu_s, vh_s, trun_error = tn.split_node(node, left_edges, right_edges)\n# If you want the singular values in it's own node, you can use `split_node_full_svd`.\nu, s, vh, trun_error = tn.split_node_full_svd(node, left_edges, right_edges)\n```\n\n## Node and Edge names.\nYou can optionally name your nodes/edges. This can be useful for debugging, \nas all error messages will print the name of the broken edge/node.\n```python\nnode = tn.Node(np.eye(2), name=\"Identity Matrix\")\nprint(\"Name of node: {}\".format(node.name))\nedge = tn.connect(node[0], node[1], name=\"Trace Edge\")\nprint(\"Name of the edge: {}\".format(edge.name))\n# Adding name to a contraction will add the name to the new edge created.\nfinal_result = tn.contract(edge, name=\"Trace Of Identity\")\nprint(\"Name of new node after contraction: {}\".format(final_result.name))\n```\n\n## Named axes.\nTo make remembering what an axis does easier, you can optionally name a node's axes.\n```python\na = tn.Node(np.zeros((2, 2)), axis_names=[\"alpha\", \"beta\"])\nedge = a[\"beta\"] ^ a[\"alpha\"]\n```\n\n## Edge reordering.\nTo assert that your result's axes are in the correct order, you can reorder a node at any time during computation.\n```python\na = tn.Node(np.zeros((1, 2, 3)))\ne1 = a[0]\ne2 = a[1]\ne3 = a[2]\na.reorder_edges([e3, e1, e2])\n# If you already know the axis values, you can equivalently do\n# a.reorder_axes([2, 0, 1])\nprint(a.tensor.shape) # Should print (3, 1, 2)\n```\n\n## NCON interface.\nFor a more compact specification of a tensor network and its contraction, there is `ncon()`. For example:\n```python\nfrom tensornetwork import ncon\na = np.ones((2, 2))\nb = np.ones((2, 2))\nc = ncon([a, b], [(-1, 1), (1, -2)])\nprint(c)\n```\n\n## Different backend support.\nCurrently, we support JAX, TensorFlow, PyTorch and NumPy as TensorNetwork backends.\nWe also support tensors with Abelian symmetries via a `symmetric` backend, see the [reference\ndocumentation](https://tensornetwork.readthedocs.io/en/latest/block_sparse_tutorial.html) for more details.\n\nTo change the default global backend, you can do:\n```python\ntn.set_default_backend(\"jax\") # tensorflow, pytorch, numpy, symmetric\n```\nOr, if you only want to change the backend for a single `Node`, you can do:\n```python\ntn.Node(tensor, backend=\"jax\")\n```\n\nIf you want to run your contractions on a GPU, we highly recommend using JAX, as it has the closet API to NumPy.\n\n## Disclaimer\nThis library is in *alpha* and will be going through a lot of breaking changes. While releases will be stable enough for research, we do not recommend using this in any production environment yet.\n\nTensorNetwork is not an official Google product. Copyright 2019 The TensorNetwork Developers.\n\n## Citation\nIf you are using TensorNetwork for your research please cite this work using the following bibtex entry:\n\n```\n@misc{roberts2019tensornetwork,\n title={TensorNetwork: A Library for Physics and Machine Learning}, \n author={Chase Roberts and Ashley Milsted and Martin Ganahl and Adam Zalcman and Bruce Fontaine and Yijian Zou and Jack Hidary and Guifre Vidal and Stefan Leichenauer},\n year={2019},\n eprint={1905.01330},\n archivePrefix={arXiv},\n primaryClass={physics.comp-ph}\n}\n```\n\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A high level tensor network API for accelerated tensor network calculations.",
"version": "0.4.6",
"project_urls": {
"Homepage": "http://github.com/google/TensorNetwork"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "628575c4733e9fd7832aac61a6f7d1a473ead56769951344bacf6b4be379254f",
"md5": "32814b21ce672b4b68958dec4297fa2b",
"sha256": "33f777ea6b9579d010806b3a1ef02f4f9ff5f0707f0ceb681591ee6eb7a01b03"
},
"downloads": -1,
"filename": "tensornetwork-0.4.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32814b21ce672b4b68958dec4297fa2b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.0",
"size": 364293,
"upload_time": "2021-10-05T07:35:14",
"upload_time_iso_8601": "2021-10-05T07:35:14.870497Z",
"url": "https://files.pythonhosted.org/packages/62/85/75c4733e9fd7832aac61a6f7d1a473ead56769951344bacf6b4be379254f/tensornetwork-0.4.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "933255c2af4e7a6257a55e6598dd199ff3aa3ca567785c67948b2dfeb5019ae7",
"md5": "185b6051b17d7f90cfee33a1da1ba4ec",
"sha256": "c5af810bf6c2480e1b1f3d98ccf262c5ffb5c3c513be6611f4fdd2258bbc7704"
},
"downloads": -1,
"filename": "tensornetwork-0.4.6.tar.gz",
"has_sig": false,
"md5_digest": "185b6051b17d7f90cfee33a1da1ba4ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 184920,
"upload_time": "2021-10-05T07:35:20",
"upload_time_iso_8601": "2021-10-05T07:35:20.834575Z",
"url": "https://files.pythonhosted.org/packages/93/32/55c2af4e7a6257a55e6598dd199ff3aa3ca567785c67948b2dfeb5019ae7/tensornetwork-0.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-10-05 07:35:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google",
"github_project": "TensorNetwork",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.17"
]
]
},
{
"name": "graphviz",
"specs": [
[
">=",
"0.11.1"
]
]
},
{
"name": "opt_einsum",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "h5py",
"specs": [
[
">=",
"2.9.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.1"
]
]
}
],
"lcname": "tensornetwork"
}
JSON
