{
    "info": {
        "author": "Jordan Dawe",
        "author_email": "jordan.dawe@unbounce.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3"
        ],
        "description": "# pytorch-tree-lstm\n\nThis repo contains a PyTorch implementation of the child-sum Tree-LSTM model\n([Tai et al. 2015](https://arxiv.org/abs/1503.00075)) implemented with\nvectorized tree evaluation and batching.  This module has been tested with\nPython 3.6.6, PyTorch 0.4.0, and PyTorch 1.0.1.\n\n## High-level Approach\n\nEfficient batching of tree data is complicated by the need to have evaluated all\nof a node's children before we can evaluate the node itself.  To minimize the\nperformance impact of this issue, we break the node evaluation process into\nsteps such that at each step we evaluate all nodes for which all child\nnodes have been previously evaluated.  This allows us to evaluate multiple nodes\nwith each torch operation, increasing computation speeds by an order of magnitude\nover recursive approaches.\n\nAs an example, consider the following tree:\n\n![tree](tree.png)\n\nOn the first step of the tree calculation, we can evaluate nodes 1 & 3 in parallel\nas neither has any child nodes.  At the second step we are able to evaluate node\n2, as its child node 3 was evaluated previously.  Lastly we evaluate node 0, which\ndepends on nodes 1 and 2.  Doing this we can reduce a four-node computation to three\nsteps.  Bigger trees with more leaf nodes will experience larger performance gains.\n\nTo facilitate this approach we encode the Tree structure and features into four\nTensors.  For a tree with N nodes, E edges, and F features, the required Tensors\nare:\n\n* `features` - A size N x F tensor containing the features for each node.\n* `adjacency_list` - A size E x 2 tensor containing the node indexes of the\nparent node and child node for every connection in the tree.\n* `node_order` - A size N tensor containing the calculation step at which\na node can be evaluated.  Note that the order that node data is stored in `features`\nand `node_order` must be identical.\n* `edge_order` - A size E tensor containing the calculation step at which\neach entry in the `adjacency_list` is needed in order to retrieve the child nodes\nfor a current node.  Note that the order that parent-child data is stored in\n`adjacency_list` and `edge_order` must be identical.\n\n`node_order` and `edge_order` hold redundant information\nderivable from the `adjacency_list` and `features`; however, precomputing\nthese tensors gives a significant performance improvement due to the current\nlack of an efficient set intersection function in PyTorch 1.0.  The order\ntensors can be generated using the `treelstm.calculate_evaluation_orders`\nfunction.  `calculate_evaluation_orders` accepts the `adjacency_list` tensor\nand the length of the features tensor and returns the two order tensors:\n\n```python\nimport treelstm\nnode_order, edge_order = treelstm.calculate_evaluation_orders(adjacency_list, len(features))\n```\n\nThe tensor representation of the example tree above would be:\n\n```python\nfeatures: tensor([[1., 0.],\n                  [0., 1.],\n                  [0., 0.],\n                  [1., 1.]])\n\nadjacency_list: tensor([[0, 1],\n                        [0, 2],\n                        [2, 3]])\n\nnode_order: tensor([2, 0, 1, 0])\n\nedge_order: tensor([2, 2, 1])\n```\n\n## Installation\n\nThe `pytorch-tree-lstm` package can be installed via `pip`:\n\n```bash\npip install pytorch-tree-lstm\n```\n\nOnce installed, the library can be imported via:\n\n```python\nimport treelstm\n```\n\n## Usage\n\nThe file `tree_list.py` contains the TreeLSTM module.  The module accepts the\n`features`, `node_order`, `adjacency_list`, `edge_order`\ntensors detailed above as input.\n\nThese tensors can be batched together by concatenation (`torch.cat()`) with the\nexception of the `adjacency_list`.  The `adjacency_list` contains indexes into\nthe `features` tensor used to retrieve child features for performing sums over\nnode children, and when batched together these indexes must be adjusted for the\nnew position of the features in the batched tensors.\n\nThe `treelstm.batch_tree_input` function is provided to do this concatenation\nand adjustment.  `treelstm.batch_tree_input` accepts a list of dictionaries\ncontaining fields `features`, `node_order`, `adjacency_list`, and\n`edge_order` and returns a dictionary containing those same fields\nwith the individual dictionaries in the list concatenated together and the\n`adjacency_list` indexes adjusted, as well as a `tree_sizes` list storing the\nsize of each tree in the batch.  Given a PyTorch\n[`Dataset`](https://pytorch.org/docs/stable/data.html#torch.utils.data.Dataset)\nobject that returns tree data as a dictionary of tensors with the above keys,\n`treelstm.batch_tree_input` is suitable for use as a `collate_fn` argument to\nthe PyTorch\n[`DataLoader`](https://pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader)\nobject:\n\n```python\nimport treelstm\n\ntrain_data_generator = DataLoader(\n    TreeDataset(),\n    collate_fn=treelstm.batch_tree_input,\n    batch_size=64\n)\n```\n\nUnbatching the batched tensors can be done via\n\n```python\ntorch.split(tensor, tree_sizes, dim=0)\n```\n\nWhere `tree_sizes` is a list containing the number of nodes in each tree in the\nbatch.  This function is also provided by the `treelstm.unbatch_tree_tensor`\nfunction for convenience.  As mentioned above, a `tree_sizes` list suitable for\nuse by this function is generated by `batch_tensors.batch_tree_tensor`.\n\n## Example\n\nExample code that generates tensors for the four node example tree above and\ntrains a toy classification problem against the Tree labels is available in\nthe `example_usage.py` script.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/unbounce/pytorch-tree-lstm",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pytorch-tree-lstm",
        "package_url": "https://pypi.org/project/pytorch-tree-lstm/",
        "platform": "",
        "project_url": "https://pypi.org/project/pytorch-tree-lstm/",
        "project_urls": {
            "Homepage": "https://github.com/unbounce/pytorch-tree-lstm"
        },
        "release_url": "https://pypi.org/project/pytorch-tree-lstm/0.1.3/",
        "requires_dist": [
            "numpy",
            "torch"
        ],
        "requires_python": ">=3",
        "summary": "A Tree-LSTM model package for PyTorch",
        "version": "0.1.3"
    },
    "last_serial": 5417660,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8f027aa63c766b2f5f062d0bf43df677",
                    "sha256": "041e5214de2ffa2631f8c7c839cec9da316e43f5397b96903c9dc003769f5b8a"
                },
                "downloads": -1,
                "filename": "pytorch_tree_lstm-0.1.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8f027aa63c766b2f5f062d0bf43df677",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3",
                "size": 7272,
                "upload_time": "2019-04-15T17:07:27",
                "url": "https://files.pythonhosted.org/packages/6d/77/349fd4056b7d869d5edb46ab53471c512312aab578d6a6e5d9e87b58619f/pytorch_tree_lstm-0.1.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "df5c474085a49ab6240d356ca36ae2b7",
                    "sha256": "2cf9936303ed90707cf936cce0f51eafaf1ad0f84d6e6883f5567a7cf9702c96"
                },
                "downloads": -1,
                "filename": "pytorch-tree-lstm-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "df5c474085a49ab6240d356ca36ae2b7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3",
                "size": 5931,
                "upload_time": "2019-04-15T17:07:29",
                "url": "https://files.pythonhosted.org/packages/75/bd/ce60ddf4469c164ae6460bc9ba8b7049271517d60f3239bca5065ec63f0f/pytorch-tree-lstm-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "42668cbaaf8993fcdb1efe4a914ea983",
                    "sha256": "2e9ce988f9b6bf4921a91fbba96480004afbc9a7fe668bf3b67efd7bfc73c97c"
                },
                "downloads": -1,
                "filename": "pytorch_tree_lstm-0.1.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "42668cbaaf8993fcdb1efe4a914ea983",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3",
                "size": 7288,
                "upload_time": "2019-04-17T00:31:33",
                "url": "https://files.pythonhosted.org/packages/bb/8a/ef9d9adf12eb569cfa011f5d25d5a87af5032a56ae0e1b0ca1a80f2b31ca/pytorch_tree_lstm-0.1.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "a07e0facb7a5172b42e858f4e2dcf2d9",
                    "sha256": "7e3d68f4f54674f9e2166dc1ac6fe7bc8585d81f9076eef1c6cfd47d2bda5552"
                },
                "downloads": -1,
                "filename": "pytorch-tree-lstm-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "a07e0facb7a5172b42e858f4e2dcf2d9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3",
                "size": 5947,
                "upload_time": "2019-04-17T00:31:35",
                "url": "https://files.pythonhosted.org/packages/d4/ef/41a6a09970e3a2f276abf36c11255fbd27e429f5d98dd4dc33ed3bdfb148/pytorch-tree-lstm-0.1.1.tar.gz"
            }
        ],
        "0.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cc745ec03d0468eeb62c40ac5e9daa38",
                    "sha256": "fe75d4c51018a0d3443e0b88611f2f706bcdbd28dbf1f2dbba753b2a7e306381"
                },
                "downloads": -1,
                "filename": "pytorch_tree_lstm-0.1.2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "cc745ec03d0468eeb62c40ac5e9daa38",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3",
                "size": 7289,
                "upload_time": "2019-06-17T17:03:59",
                "url": "https://files.pythonhosted.org/packages/4a/90/aab767ae5263110bd8751ef8f5e046554003fad7f84f9493e8b3399d4437/pytorch_tree_lstm-0.1.2-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "397712eff5a1ae19f3dac05bf24fe429",
                    "sha256": "f483157c57b98a96b8b58d087ba552e3e1d833b64e36d42c44af12f151e88ade"
                },
                "downloads": -1,
                "filename": "pytorch-tree-lstm-0.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "397712eff5a1ae19f3dac05bf24fe429",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3",
                "size": 5952,
                "upload_time": "2019-06-17T17:04:01",
                "url": "https://files.pythonhosted.org/packages/da/17/09a1f1db730b404d2898c22db3543e7ac0bc813ea2b343bf9977053395b2/pytorch-tree-lstm-0.1.2.tar.gz"
            }
        ],
        "0.1.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3f908be7e2214386c14275a5db1578a7",
                    "sha256": "4a4ee5eb5d21d59f47776e4ce51fd71c5ed1c8f20959d6024d8f0e93f1906a9f"
                },
                "downloads": -1,
                "filename": "pytorch_tree_lstm-0.1.3-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "3f908be7e2214386c14275a5db1578a7",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3",
                "size": 7332,
                "upload_time": "2019-06-18T23:08:23",
                "url": "https://files.pythonhosted.org/packages/1c/96/4eab893abdb0afef9797faf6ef1bb8da254ae354e078a781e10e6ee1913a/pytorch_tree_lstm-0.1.3-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "cf26641f24405fd5ea2c066ecb1a2c59",
                    "sha256": "b8026d31f51fe05baed9595258b2908e3fd8c33f0568db657c5db5006c2b6b2c"
                },
                "downloads": -1,
                "filename": "pytorch-tree-lstm-0.1.3.tar.gz",
                "has_sig": false,
                "md5_digest": "cf26641f24405fd5ea2c066ecb1a2c59",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3",
                "size": 6001,
                "upload_time": "2019-06-18T23:08:24",
                "url": "https://files.pythonhosted.org/packages/8f/0f/dba443d4f9b2acfd8f7bd81d0598d51a96d68956a2628f5cf1424ef67f41/pytorch-tree-lstm-0.1.3.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3f908be7e2214386c14275a5db1578a7",
                "sha256": "4a4ee5eb5d21d59f47776e4ce51fd71c5ed1c8f20959d6024d8f0e93f1906a9f"
            },
            "downloads": -1,
            "filename": "pytorch_tree_lstm-0.1.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3f908be7e2214386c14275a5db1578a7",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3",
            "size": 7332,
            "upload_time": "2019-06-18T23:08:23",
            "url": "https://files.pythonhosted.org/packages/1c/96/4eab893abdb0afef9797faf6ef1bb8da254ae354e078a781e10e6ee1913a/pytorch_tree_lstm-0.1.3-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "cf26641f24405fd5ea2c066ecb1a2c59",
                "sha256": "b8026d31f51fe05baed9595258b2908e3fd8c33f0568db657c5db5006c2b6b2c"
            },
            "downloads": -1,
            "filename": "pytorch-tree-lstm-0.1.3.tar.gz",
            "has_sig": false,
            "md5_digest": "cf26641f24405fd5ea2c066ecb1a2c59",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3",
            "size": 6001,
            "upload_time": "2019-06-18T23:08:24",
            "url": "https://files.pythonhosted.org/packages/8f/0f/dba443d4f9b2acfd8f7bd81d0598d51a96d68956a2628f5cf1424ef67f41/pytorch-tree-lstm-0.1.3.tar.gz"
        }
    ]
}