# ncon
[![][tests-workflow-img]][tests-workflow-url] [![][codecov-img]][codecov-url]
ncon is a Python 3 package that implements the NCon function as described here:
https://arxiv.org/abs/1402.0939
This Python implementation lacks some of the fancier features described in
the paper, but the interface is the same.
ncon requires numpy and works with numpy ndarrays. It also works with the
various tensors from [this](https://github.com/mhauru/abeliantensors) package,
but does not require it.
## Installation
`pip install --user ncon`
## Usage
The only thing this package exports is the function `ncon`. It takes a list of
tensors to be contracted, and a list index lists that specify what gets
contracted with that. It returns a single tensor, that is the result of the
contraction. Here's how the syntax works:
```
ncon(L, v, order=None, forder=None, check_indices=True):
```
The first argument `L` is a list of tensors.
The second argument `v` is a list of list, one for each tensor in `L`.
Each `v[i]` consists of integers, each of which labels an index of `L[i]`.
Positive labels mark indices which are to be contracted (summed over).
So if for instance `v[m][i] == 2` and `v[n][j] == 2`, then the `i`th index of
`L[m]` and the `j`th index of `L[n]` are to be identified and summed over.
Negative labels mark indices which are to remain free (uncontracted).
The keyword argument `order` is a list of all the positive labels, which
specifies the order in which the pair-wise tensor contractions are to be done.
By default it is `sorted(all-positive-numbers-in-v)`, so for instance
`[1,2,...]`. Note that whenever an index joining two tensors is about to be
contracted together, `ncon` contracts at the same time all indices connecting
these two tensors, even if some of them only come up later in order.
Correspondingly `forder` specifies the order to which the remaining free
indices are to be permuted. By default it is
`sorted(all-negative-numbers-in-v, reverse=True)`,
meaning for instance `[-1,-2,...]`.
If both `order` and `forder` are provided by the user, then objects other than
integers can be used to label the indices. This has been tested with string
labels, but in principle many other types of objects should work too.
If `check_indices=True` (the default) then checks are performed to make sure
the contraction is well-defined. If not, an `ValueError` with a helpful
description of what went wrong is provided.
If the syntax sounds a lot like Einstein summation, as implemented for example
by `np.einsum`, then that's because it is. The benefits of `ncon` are that many
tensor networkers are used to its syntax, and it is easy to dynamically
generate index lists and contractions.
#### Examples
Here are a few examples, straight from the test file.
A matrix product:
```
from ncon import ncon
a = np.random.randn(3, 4)
b = np.random.randn(4, 5)
ab_ncon = ncon([a, b], ((-1, 1), (1, -2)))
ab_np = np.dot(a, b)
assert np.allclose(ab_ncon, ab_np)
```
Here the last index of `a` and the first index of `b` are contracted.
The result is a tensor with two free indices, labeled by `-1` and `-2`.
The one labeled with `-1` becomes the first index of the result. If we gave the
additional argument `forder=[-2,-1]` the transpose would be returned instead.
A more complicated example:
```a = np.random.randn(3, 4, 5)
b = np.random.randn(5, 3, 6, 7, 6)
c = np.random.randn(7, 2)
d = np.random.randn(8)
e = np.random.randn(8, 9)
result_ncon = ncon(
(a, b, c, d, e), ([3, -2, 2], [2, 3, 1, 4, 1], [4, -1], [5], [5, -3])
)
result_np = np.einsum("ijk,kilml,mh,q,qp->hjp", a, b, c, d, e)
assert np.allclose(result_ncon, result_np)
```
Notice that the network here is disconnected, `d` and `e` are not contracted
with any of the others. When contracting disconnected networks, the connected
parts are always contracted first, and their tensor product is taken at the
end. Traces are also okay, like here on two indices of `c`. By default, the
contractions are done in the order [1,2,3,4,5]. This may not be the optimal
choice, in which case we should specify a better contraction order as a keyword
argument.
[tests-workflow-img]: https://github.com/mhauru/ncon/actions/workflows/tests-and-coverage.yaml/badge.svg
[tests-workflow-url]: https://github.com/mhauru/ncon/actions/workflows/tests-and-coverage.yaml
[codecov-img]: https://codecov.io/gh/mhauru/ncon/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/mhauru/ncon
Raw data
{
"_id": null,
"home_page": "https://github.com/mhauru/ncon",
"name": "ncon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "tensor networks",
"author": "Markus Hauru",
"author_email": "markus@mhauru.org",
"download_url": "https://files.pythonhosted.org/packages/55/f5/20e6a201e45dd1b77bc6cb7a1bb46d3bbeb790d63f38d41534d5e686708a/ncon-2.0.0.tar.gz",
"platform": null,
"description": "# ncon\n[![][tests-workflow-img]][tests-workflow-url] [![][codecov-img]][codecov-url]\n\nncon is a Python 3 package that implements the NCon function as described here:\nhttps://arxiv.org/abs/1402.0939\nThis Python implementation lacks some of the fancier features described in\nthe paper, but the interface is the same.\n\nncon requires numpy and works with numpy ndarrays. It also works with the\nvarious tensors from [this](https://github.com/mhauru/abeliantensors) package,\nbut does not require it.\n\n## Installation\n\n`pip install --user ncon`\n\n## Usage\n\nThe only thing this package exports is the function `ncon`. It takes a list of\ntensors to be contracted, and a list index lists that specify what gets\ncontracted with that. It returns a single tensor, that is the result of the\ncontraction. Here's how the syntax works:\n```\nncon(L, v, order=None, forder=None, check_indices=True):\n```\nThe first argument `L` is a list of tensors.\nThe second argument `v` is a list of list, one for each tensor in `L`.\nEach `v[i]` consists of integers, each of which labels an index of `L[i]`.\nPositive labels mark indices which are to be contracted (summed over).\nSo if for instance `v[m][i] == 2` and `v[n][j] == 2`, then the `i`th index of\n`L[m]` and the `j`th index of `L[n]` are to be identified and summed over.\nNegative labels mark indices which are to remain free (uncontracted).\n\nThe keyword argument `order` is a list of all the positive labels, which\nspecifies the order in which the pair-wise tensor contractions are to be done.\nBy default it is `sorted(all-positive-numbers-in-v)`, so for instance\n`[1,2,...]`. Note that whenever an index joining two tensors is about to be\ncontracted together, `ncon` contracts at the same time all indices connecting\nthese two tensors, even if some of them only come up later in order.\n\nCorrespondingly `forder` specifies the order to which the remaining free\nindices are to be permuted. By default it is\n`sorted(all-negative-numbers-in-v, reverse=True)`,\nmeaning for instance `[-1,-2,...]`.\n\nIf both `order` and `forder` are provided by the user, then objects other than\nintegers can be used to label the indices. This has been tested with string\nlabels, but in principle many other types of objects should work too.\n\nIf `check_indices=True` (the default) then checks are performed to make sure\nthe contraction is well-defined. If not, an `ValueError` with a helpful\ndescription of what went wrong is provided.\n\nIf the syntax sounds a lot like Einstein summation, as implemented for example\nby `np.einsum`, then that's because it is. The benefits of `ncon` are that many\ntensor networkers are used to its syntax, and it is easy to dynamically\ngenerate index lists and contractions.\n\n#### Examples\n\nHere are a few examples, straight from the test file.\n\nA matrix product:\n```\nfrom ncon import ncon\na = np.random.randn(3, 4)\nb = np.random.randn(4, 5)\nab_ncon = ncon([a, b], ((-1, 1), (1, -2)))\nab_np = np.dot(a, b)\nassert np.allclose(ab_ncon, ab_np)\n```\nHere the last index of `a` and the first index of `b` are contracted.\nThe result is a tensor with two free indices, labeled by `-1` and `-2`.\nThe one labeled with `-1` becomes the first index of the result. If we gave the\nadditional argument `forder=[-2,-1]` the transpose would be returned instead.\n\nA more complicated example:\n```a = np.random.randn(3, 4, 5)\nb = np.random.randn(5, 3, 6, 7, 6)\nc = np.random.randn(7, 2)\nd = np.random.randn(8)\ne = np.random.randn(8, 9)\nresult_ncon = ncon(\n (a, b, c, d, e), ([3, -2, 2], [2, 3, 1, 4, 1], [4, -1], [5], [5, -3])\n)\nresult_np = np.einsum(\"ijk,kilml,mh,q,qp->hjp\", a, b, c, d, e)\nassert np.allclose(result_ncon, result_np)\n```\nNotice that the network here is disconnected, `d` and `e` are not contracted\nwith any of the others. When contracting disconnected networks, the connected\nparts are always contracted first, and their tensor product is taken at the\nend. Traces are also okay, like here on two indices of `c`. By default, the\ncontractions are done in the order [1,2,3,4,5]. This may not be the optimal\nchoice, in which case we should specify a better contraction order as a keyword\nargument.\n\n[tests-workflow-img]: https://github.com/mhauru/ncon/actions/workflows/tests-and-coverage.yaml/badge.svg\n[tests-workflow-url]: https://github.com/mhauru/ncon/actions/workflows/tests-and-coverage.yaml\n[codecov-img]: https://codecov.io/gh/mhauru/ncon/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/mhauru/ncon\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tensor network contraction function for Python 3.",
"version": "2.0.0",
"split_keywords": [
"tensor",
"networks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "46b7d507c8624babf43dbff7ec9f39042299bcf1173d789127dc495d0e86bd18",
"md5": "024dbd71e15aff6e729eea176d3162a9",
"sha256": "561c39da0bf0fc6c993b22f27593bd592ce2c4f689fb66508cd84d3e46054c95"
},
"downloads": -1,
"filename": "ncon-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "024dbd71e15aff6e729eea176d3162a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 8642,
"upload_time": "2023-03-13T19:23:14",
"upload_time_iso_8601": "2023-03-13T19:23:14.213670Z",
"url": "https://files.pythonhosted.org/packages/46/b7/d507c8624babf43dbff7ec9f39042299bcf1173d789127dc495d0e86bd18/ncon-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55f520e6a201e45dd1b77bc6cb7a1bb46d3bbeb790d63f38d41534d5e686708a",
"md5": "a3d5f3c039aec7fde6862da82df6cb62",
"sha256": "b307e6d8c1d14ddac2510256c2955e5b9d3b6f4916ec8932be1cd11490bfb28a"
},
"downloads": -1,
"filename": "ncon-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a3d5f3c039aec7fde6862da82df6cb62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11199,
"upload_time": "2023-03-13T19:23:15",
"upload_time_iso_8601": "2023-03-13T19:23:15.678142Z",
"url": "https://files.pythonhosted.org/packages/55/f5/20e6a201e45dd1b77bc6cb7a1bb46d3bbeb790d63f38d41534d5e686708a/ncon-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-13 19:23:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mhauru",
"github_project": "ncon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ncon"
}
JSON
