<div align="center">
<a href="https://opendilab.github.io/DI-treetensor/"><img width="500px" height="auto" src="https://github.com/opendilab/DI-treetensor/blob/main/docs/source/_static/di-treetensor.svg"></a>
</div>
---
[](https://pypi.org/project/DI-treetensor/)
[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Docs+Deploy%22)
[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Code+Test%22)
[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Badge+Creation%22)
[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Package+Release%22)
[](https://codecov.io/gh/opendilab/DI-treetensor)
[](https://github.com/opendilab/DI-treetensor/stargazers)
[](https://github.com/opendilab/DI-treetensor/network)
[](https://github.com/opendilab/DI-treetensor/issues)
[](https://github.com/opendilab/DI-treetensor/pulls)
[](https://github.com/opendilab/DI-treetensor/graphs/contributors)
[](https://github.com/opendilab/DI-treetensor/blob/master/LICENSE)
`treetensor` is a generalized tree-based tensor structure mainly developed by [OpenDILab Contributors](https://github.com/opendilab).
Almost all the operation can be supported in form of trees in a convenient way to simplify the structure processing when the calculation is tree-based.
## Installation
You can simply install it with `pip` command line from the official PyPI site.
```shell
pip install di-treetensor
```
For more information about installation, you can refer to [Installation](https://opendilab.github.io/DI-treetensor/main/tutorials/installation/index.html#).
## Documentation
The detailed documentation are hosted on [https://opendilab.github.io/DI-treetensor](https://opendilab.github.io/DI-treetensor/).
Only english version is provided now, the chinese documentation is still under development.
## Quick Start
You can easily create a tree value object based on `FastTreeValue`.
```python
import builtins
import os
from functools import partial
import treetensor.torch as torch
print = partial(builtins.print, sep=os.linesep)
if __name__ == '__main__':
# create a tree tensor
t = torch.randn({'a': (2, 3), 'b': {'x': (3, 4)}})
print(t)
print(torch.randn(4, 5)) # create a normal tensor
print()
# structure of tree
print('Structure of tree')
print('t.a:', t.a) # t.a is a native tensor
print('t.b:', t.b) # t.b is a tree tensor
print('t.b.x', t.b.x) # t.b.x is a native tensor
print()
# math calculations
print('Math calculation')
print('t ** 2:', t ** 2)
print('torch.sin(t).cos()', torch.sin(t).cos())
print()
# backward calculation
print('Backward calculation')
t.requires_grad_(True)
t.std().arctan().backward()
print('grad of t:', t.grad)
print()
# native operation
# all the ops can be used as the original usage of `torch`
print('Native operation')
print('torch.sin(t.a)', torch.sin(t.a)) # sin of native tensor
```
The result should be
```text
<Tensor 0x7f0dae602760>
├── a --> tensor([[-1.2672, -1.5817, -0.3141],
│ [ 1.8107, -0.1023, 0.0940]])
└── b --> <Tensor 0x7f0dae602820>
└── x --> tensor([[ 1.2224, -0.3445, -0.9980, -0.4085],
[ 1.5956, 0.8825, -0.5702, -0.2247],
[ 0.9235, 0.4538, 0.8775, -0.2642]])
tensor([[-0.9559, 0.7684, 0.2682, -0.6419, 0.8637],
[ 0.9526, 0.2927, -0.0591, 1.2804, -0.2455],
[ 0.4699, -0.9998, 0.6324, -0.6885, 1.1488],
[ 0.8920, 0.4401, -0.7785, 0.5931, 0.0435]])
Structure of tree
t.a:
tensor([[-1.2672, -1.5817, -0.3141],
[ 1.8107, -0.1023, 0.0940]])
t.b:
<Tensor 0x7f0dae602820>
└── x --> tensor([[ 1.2224, -0.3445, -0.9980, -0.4085],
[ 1.5956, 0.8825, -0.5702, -0.2247],
[ 0.9235, 0.4538, 0.8775, -0.2642]])
t.b.x
tensor([[ 1.2224, -0.3445, -0.9980, -0.4085],
[ 1.5956, 0.8825, -0.5702, -0.2247],
[ 0.9235, 0.4538, 0.8775, -0.2642]])
Math calculation
t ** 2:
<Tensor 0x7f0dae602eb0>
├── a --> tensor([[1.6057, 2.5018, 0.0986],
│ [3.2786, 0.0105, 0.0088]])
└── b --> <Tensor 0x7f0dae60c040>
└── x --> tensor([[1.4943, 0.1187, 0.9960, 0.1669],
[2.5458, 0.7789, 0.3252, 0.0505],
[0.8528, 0.2059, 0.7699, 0.0698]])
torch.sin(t).cos()
<Tensor 0x7f0dae621910>
├── a --> tensor([[0.5782, 0.5404, 0.9527],
│ [0.5642, 0.9948, 0.9956]])
└── b --> <Tensor 0x7f0dae6216a0>
└── x --> tensor([[0.5898, 0.9435, 0.6672, 0.9221],
[0.5406, 0.7163, 0.8578, 0.9753],
[0.6983, 0.9054, 0.7185, 0.9661]])
Backward calculation
grad of t:
<Tensor 0x7f0dae60c400>
├── a --> tensor([[-0.0435, -0.0535, -0.0131],
│ [ 0.0545, -0.0064, -0.0002]])
└── b --> <Tensor 0x7f0dae60cbe0>
└── x --> tensor([[ 0.0357, -0.0141, -0.0349, -0.0162],
[ 0.0476, 0.0249, -0.0213, -0.0103],
[ 0.0262, 0.0113, 0.0248, -0.0116]])
Native operation
torch.sin(t.a)
tensor([[-0.9543, -0.9999, -0.3089],
[ 0.9714, -0.1021, 0.0939]], grad_fn=<SinBackward>)
```
For more quick start explanation and further usage, take a look at:
* [Quick Start](https://opendilab.github.io/DI-treetensor/main/tutorials/quick_start/index.html)
## Extension
If you need to translate `treevalue` object to runnable source code, you may use the [potc-treevalue](https://github.com/potc-dev/potc-treevalue) plugin with the installation command below
```
pip install DI-treetensor[potc]
```
In potc, you can translate the objects to runnable python source code, which can be loaded to objects afterwards by the python interpreter, like the following graph
For more information, you can refer to
- [potc-dev/potc](https://github.com/potc-dev/potc)
- [potc-dev/potc-treevalue](https://github.com/potc-dev/potc-treevalue)
- [potc-dev/potc-torch](https://github.com/potc-dev/potc-torch)
- [Potc Plugin Installation](https://opendilab.github.io/DI-treetensor/main/tutorials/plugins/index.html#potc-support)
## Contribution
We appreciate all contributions to improve DI-treetensor, both logic and system designs. Please refer to CONTRIBUTING.md for more guides.
And users can join our [slack communication channel](https://join.slack.com/t/opendilab/shared_invite/zt-v9tmv4fp-nUBAQEH1_Kuyu_q4plBssQ), or contact the core developer [HansBug](https://github.com/HansBug) for more detailed discussion.
## License
`DI-treetensor` released under the Apache 2.0 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/opendilab/DI-treetensor",
"name": "DI-treetensor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Tree-structured Value Management",
"author": "HansBug, DI-engine's Contributors",
"author_email": "hansbug@buaa.edu.cn",
"download_url": "https://files.pythonhosted.org/packages/1d/cd/7d63040fd7a5b037aad773a17d37983f97d655faae493a2f664af1c32667/DI-treetensor-0.4.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <a href=\"https://opendilab.github.io/DI-treetensor/\"><img width=\"500px\" height=\"auto\" src=\"https://github.com/opendilab/DI-treetensor/blob/main/docs/source/_static/di-treetensor.svg\"></a>\n</div>\n\n---\n\n[](https://pypi.org/project/DI-treetensor/)\n\n\n\n\n[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Docs+Deploy%22)\n[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Code+Test%22)\n[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Badge+Creation%22)\n[](https://github.com/opendilab/DI-treetensor/actions?query=workflow%3A%22Package+Release%22)\n[](https://codecov.io/gh/opendilab/DI-treetensor)\n\n[](https://github.com/opendilab/DI-treetensor/stargazers)\n[](https://github.com/opendilab/DI-treetensor/network)\n\n[](https://github.com/opendilab/DI-treetensor/issues)\n[](https://github.com/opendilab/DI-treetensor/pulls)\n[](https://github.com/opendilab/DI-treetensor/graphs/contributors)\n[](https://github.com/opendilab/DI-treetensor/blob/master/LICENSE)\n\n`treetensor` is a generalized tree-based tensor structure mainly developed by [OpenDILab Contributors](https://github.com/opendilab).\n\nAlmost all the operation can be supported in form of trees in a convenient way to simplify the structure processing when the calculation is tree-based.\n\n## Installation\n\nYou can simply install it with `pip` command line from the official PyPI site.\n\n```shell\npip install di-treetensor\n```\n\nFor more information about installation, you can refer to [Installation](https://opendilab.github.io/DI-treetensor/main/tutorials/installation/index.html#).\n\n## Documentation\n\nThe detailed documentation are hosted on [https://opendilab.github.io/DI-treetensor](https://opendilab.github.io/DI-treetensor/).\n\nOnly english version is provided now, the chinese documentation is still under development.\n\n## Quick Start\n\nYou can easily create a tree value object based on `FastTreeValue`.\n\n```python\nimport builtins\nimport os\nfrom functools import partial\n\nimport treetensor.torch as torch\n\nprint = partial(builtins.print, sep=os.linesep)\n\nif __name__ == '__main__':\n # create a tree tensor\n t = torch.randn({'a': (2, 3), 'b': {'x': (3, 4)}})\n print(t)\n print(torch.randn(4, 5)) # create a normal tensor\n print()\n\n # structure of tree\n print('Structure of tree')\n print('t.a:', t.a) # t.a is a native tensor\n print('t.b:', t.b) # t.b is a tree tensor\n print('t.b.x', t.b.x) # t.b.x is a native tensor\n print()\n\n # math calculations\n print('Math calculation')\n print('t ** 2:', t ** 2)\n print('torch.sin(t).cos()', torch.sin(t).cos())\n print()\n\n # backward calculation\n print('Backward calculation')\n t.requires_grad_(True)\n t.std().arctan().backward()\n print('grad of t:', t.grad)\n print()\n\n # native operation\n # all the ops can be used as the original usage of `torch`\n print('Native operation')\n print('torch.sin(t.a)', torch.sin(t.a)) # sin of native tensor\n\n```\n\nThe result should be\n\n```text\n<Tensor 0x7f0dae602760>\n\u251c\u2500\u2500 a --> tensor([[-1.2672, -1.5817, -0.3141],\n\u2502 [ 1.8107, -0.1023, 0.0940]])\n\u2514\u2500\u2500 b --> <Tensor 0x7f0dae602820>\n \u2514\u2500\u2500 x --> tensor([[ 1.2224, -0.3445, -0.9980, -0.4085],\n [ 1.5956, 0.8825, -0.5702, -0.2247],\n [ 0.9235, 0.4538, 0.8775, -0.2642]])\n\ntensor([[-0.9559, 0.7684, 0.2682, -0.6419, 0.8637],\n [ 0.9526, 0.2927, -0.0591, 1.2804, -0.2455],\n [ 0.4699, -0.9998, 0.6324, -0.6885, 1.1488],\n [ 0.8920, 0.4401, -0.7785, 0.5931, 0.0435]])\n\nStructure of tree\nt.a:\ntensor([[-1.2672, -1.5817, -0.3141],\n [ 1.8107, -0.1023, 0.0940]])\nt.b:\n<Tensor 0x7f0dae602820>\n\u2514\u2500\u2500 x --> tensor([[ 1.2224, -0.3445, -0.9980, -0.4085],\n [ 1.5956, 0.8825, -0.5702, -0.2247],\n [ 0.9235, 0.4538, 0.8775, -0.2642]])\n\nt.b.x\ntensor([[ 1.2224, -0.3445, -0.9980, -0.4085],\n [ 1.5956, 0.8825, -0.5702, -0.2247],\n [ 0.9235, 0.4538, 0.8775, -0.2642]])\n\nMath calculation\nt ** 2:\n<Tensor 0x7f0dae602eb0>\n\u251c\u2500\u2500 a --> tensor([[1.6057, 2.5018, 0.0986],\n\u2502 [3.2786, 0.0105, 0.0088]])\n\u2514\u2500\u2500 b --> <Tensor 0x7f0dae60c040>\n \u2514\u2500\u2500 x --> tensor([[1.4943, 0.1187, 0.9960, 0.1669],\n [2.5458, 0.7789, 0.3252, 0.0505],\n [0.8528, 0.2059, 0.7699, 0.0698]])\n\ntorch.sin(t).cos()\n<Tensor 0x7f0dae621910>\n\u251c\u2500\u2500 a --> tensor([[0.5782, 0.5404, 0.9527],\n\u2502 [0.5642, 0.9948, 0.9956]])\n\u2514\u2500\u2500 b --> <Tensor 0x7f0dae6216a0>\n \u2514\u2500\u2500 x --> tensor([[0.5898, 0.9435, 0.6672, 0.9221],\n [0.5406, 0.7163, 0.8578, 0.9753],\n [0.6983, 0.9054, 0.7185, 0.9661]])\n\n\nBackward calculation\ngrad of t:\n<Tensor 0x7f0dae60c400>\n\u251c\u2500\u2500 a --> tensor([[-0.0435, -0.0535, -0.0131],\n\u2502 [ 0.0545, -0.0064, -0.0002]])\n\u2514\u2500\u2500 b --> <Tensor 0x7f0dae60cbe0>\n \u2514\u2500\u2500 x --> tensor([[ 0.0357, -0.0141, -0.0349, -0.0162],\n [ 0.0476, 0.0249, -0.0213, -0.0103],\n [ 0.0262, 0.0113, 0.0248, -0.0116]])\n\n\nNative operation\ntorch.sin(t.a)\ntensor([[-0.9543, -0.9999, -0.3089],\n [ 0.9714, -0.1021, 0.0939]], grad_fn=<SinBackward>)\n\n```\n\nFor more quick start explanation and further usage, take a look at:\n\n* [Quick Start](https://opendilab.github.io/DI-treetensor/main/tutorials/quick_start/index.html)\n\n## Extension\n\nIf you need to translate `treevalue` object to runnable source code, you may use the [potc-treevalue](https://github.com/potc-dev/potc-treevalue) plugin with the installation command below\n\n```\npip install DI-treetensor[potc]\n```\n\nIn potc, you can translate the objects to runnable python source code, which can be loaded to objects afterwards by the python interpreter, like the following graph\n\n\n\nFor more information, you can refer to\n\n- [potc-dev/potc](https://github.com/potc-dev/potc)\n- [potc-dev/potc-treevalue](https://github.com/potc-dev/potc-treevalue)\n- [potc-dev/potc-torch](https://github.com/potc-dev/potc-torch)\n- [Potc Plugin Installation](https://opendilab.github.io/DI-treetensor/main/tutorials/plugins/index.html#potc-support)\n\n## Contribution\n\nWe appreciate all contributions to improve DI-treetensor, both logic and system designs. Please refer to CONTRIBUTING.md for more guides.\n\nAnd users can join our [slack communication channel](https://join.slack.com/t/opendilab/shared_invite/zt-v9tmv4fp-nUBAQEH1_Kuyu_q4plBssQ), or contact the core developer [HansBug](https://github.com/HansBug) for more detailed discussion.\n\n## License\n\n`DI-treetensor` released under the Apache 2.0 license.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "A flexible, generalized tree-based tensor structure.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/opendilab/DI-treetensor"
},
"split_keywords": [
"tree-structured",
"value",
"management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c9ef2cb8e56fb744b3270bf267ba850579086f18a53c5a904bcc7c81c10e99ca",
"md5": "626c99413e24c2cb56b0799f08d2c98d",
"sha256": "e2ef90273ade792111c7f0958dd90db6c01908fdb96f26054f5965dde3847ca7"
},
"downloads": -1,
"filename": "DI_treetensor-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "626c99413e24c2cb56b0799f08d2c98d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 46049,
"upload_time": "2023-05-29T08:30:24",
"upload_time_iso_8601": "2023-05-29T08:30:24.526275Z",
"url": "https://files.pythonhosted.org/packages/c9/ef/2cb8e56fb744b3270bf267ba850579086f18a53c5a904bcc7c81c10e99ca/DI_treetensor-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1dcd7d63040fd7a5b037aad773a17d37983f97d655faae493a2f664af1c32667",
"md5": "3c91eae79c293a396744c9087f13a51e",
"sha256": "6ac3a7cf3130db1e3fba28a253733efc9fa11ca54af5200b7e73a96a6dfacee5"
},
"downloads": -1,
"filename": "DI-treetensor-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "3c91eae79c293a396744c9087f13a51e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 38529,
"upload_time": "2023-05-29T08:30:27",
"upload_time_iso_8601": "2023-05-29T08:30:27.267078Z",
"url": "https://files.pythonhosted.org/packages/1d/cd/7d63040fd7a5b037aad773a17d37983f97d655faae493a2f664af1c32667/DI-treetensor-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-29 08:30:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "opendilab",
"github_project": "DI-treetensor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "di-treetensor"
}
JSON
