{"id":13737845,"url":"https://github.com/boschresearch/statestream","last_synced_at":"2025-05-08T15:31:49.266Z","repository":{"id":105078196,"uuid":"94764662","full_name":"boschresearch/statestream","owner":"boschresearch","description":"A toolbox to explore synchronous layerwise-parallel deep neural networks.","archived":true,"fork":false,"pushed_at":"2019-07-29T08:43:55.000Z","size":2319,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-15T06:32:35.770Z","etag":null,"topics":["bcai","contribution-fork","deep-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boschresearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-19T10:22:32.000Z","updated_at":"2024-05-21T13:37:45.000Z","dependencies_parsed_at":"2024-01-07T17:10:53.092Z","dependency_job_id":null,"html_url":"https://github.com/boschresearch/statestream","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2Fstatestream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2Fstatestream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2Fstatestream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2Fstatestream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boschresearch","download_url":"https://codeload.github.com/boschresearch/statestream/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253096151,"owners_count":21853546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcai","contribution-fork","deep-learning"],"created_at":"2024-08-03T03:02:03.011Z","updated_at":"2025-05-08T15:31:49.257Z","avatar_url":"https://github.com/boschresearch.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n\nstatestream\n===========\n\nStatestream is an experimental toolbox for [streaming](https://arxiv.org/abs/1806.04965) (see also [this explanation](docs/from_one_frame_to_the_next.md)) deep neural networks. \nIt provides tools to easily design, train, visualize, and manipulate streaming deep neural networks.\n\nThis software is a research prototype and not ready for production use. It has neither been developed nor\ntested for a specific use case. However, the license conditions of the\napplicable Open Source licenses allow you to adapt the software to your needs.\n\n**Because this toolbox currently is in trial / test phase, code APIs should not be expected to stay stable and \ncontinuous improvements will be made. Please make sure you always have the current version.**\n\n![Example visualization of a very simple example.](docs/resources/statestream.png)\n\n------------------------------------------------------------------------------\n\n[Documentation](docs/README.md)\n---------------\n\n[Troubleshooting](docs/troubleshooting.md)\n-----------------\n\n------------------------------------------------------------------------------\n\nSome cornerstones\n-----------------\n\n* Emphasis on [streaming](https://arxiv.org/abs/1806.04965) (or [this](docs/from_one_frame_to_the_next.md)) data and networks.\n* Emphasis on flexible and intuitive online visualization / manipulation of network states / parameters, etc.\n* Qualitative not quantitative exploration of new network architectures (first 50 percent vs. last 2 percent performance).\n* Emphasis on parallelism (processes, GPUs, restriced across machines).\n* Suited for specific type of very large (numerous but small network modules/layers) recurrent neural networks.\n\nImplementation:\n\n* Networks are specified as yaml files.\n* For now, statestream supports Theano (default) or Tensorflow as backend.\n\n------------------------------------------------------------------------------\n\nDifferences to prominent DL-frameworks\n--------------------------------------\n\nThe statestream toolbox does not aim to improve over existing tools with respect to memory or computation efficiency but rather enables investigation of streaming networks and interact with them during runtime. In fact, the statestream toolbox is much more memory / computation in-efficient than other existing tools.\n\n* **streaming**: The network parts process information in a frame based / model-parallel synchronized manner, where one frame can be interpreted as one-step rollout of a recurrent neural network. Hence, dependent on network architecture, it may take several (up to many) frames until information is processed by the network. Now states stream through the network. While this toolbox supports only streaming network rollouts, scripts to benchmark different rollouts can be found in the __reference/__ folder.\n* **separation of 'Layers'**: In contrast to most other deep learning toolkits, which decompose the network into layers, we try to emphasise the graph-nature of neural networks already in implementation. Hence, inside the statestream toolbox the network is decomposed in nodes (neuron-pools, short NP) and edges (synapse-pools, short SP). While NPs hold the state (a.k.a. feature maps) of the network, the SPs define the transformations between those states. For both, NPs and SPs, trainable parameters can be specified (e.g. bias for NPs, weights for SPs).\n* **local updates**: Due to its streaming nature for execution, losses and more general everything that changes parameters (in statestream these\nare called plasticities) are treated as separated parts of the network. While statestream also allows 'global' losses\ncovering the entire network, it emphasises on 'local' plasticities, which rely only on information from small parts of the network to determine updates for small subset of parameters. \n\n------------------------------------------------------------------------------\n\nPros\n----\n\n* (+) Enables streaming (consistently model-parallel) networks.\n* (+) Intuitive behavior of recurrent neural networks (no extra rollout).\n* (+) Shared memory representation enables online visualization and manipulation of network behavior.\n* (+) Trivial parallelization across CPUs and GPUs due to model-parallelism.\n\nCons\n----\n\n* (-) Shared memory makes it harder to scale across machines.\n* (-) Network representation in shared memory requires a considerable amount of memory and (parallel) inter-process communication.\n* (-) For streaming (model-parallel) networks it is more challenging to specify adequate plasticities (losses).\n\n------------------------------------------------------------------------------\n\nInstallation requirements\n-------------------------\n\nThe statestream toolbox is tested with:\n\n* [Ubuntu 16.04](https://www.ubuntu.com/)\n* [Xfce](https://wiki.ubuntuusers.de/Xfce_Installation/) Desktop environment. Please see the [troubleshooting section](docs/troubleshooting.md) for color problems.\n* [Python 3.5](https://www.python.org/) (but may also work with python 2.7 with little effort)\n\nIf one wants to use GPU support, it is assumed that [CUDA toolkit \u003e=8.0](https://developer.nvidia.com/cuda-toolkit) and optionally [cuDNN \u003e=5.0](https://developer.nvidia.com/cudnn) is installed.\n\nBesides the requirements below, we strongly recomment using [anaconda](https://www.continuum.io/anaconda-overview) or [miniconda](https://conda.io/miniconda.html) to manage python packages and to set up a conda python environment, e.g.:\n\n```\nconda create --name statestream python=3.5\nsource activate statestream\n```\n\nThe statestream toolbox requires the following python packages:\n\n* [Python 3.5](https://www.python.org/)\n* [NumPy \u003e= 1.9.1 \u003c= 1.12](http://www.numpy.org/): Basic mathematical tooling.\n* [Pygame \u003e= 1.9](http://www.pygame.org/): This is the main library used for online visualization.\n* [ruamel_yaml](https://pypi.python.org/pypi/ruamel.yaml): This is used to specify network architectures.\n* [SharedArray 2.0.2](https://pypi.python.org/pypi/SharedArray): This is used for inter-process communication.\n* [h5py](http://www.h5py.org/): This library is used to store trained networks.\n* [scikit-image](http://scikit-image.org/): This library is used for image handling.\n* [Matplotlib](https://matplotlib.org/): Used to enhance visualization with Pygame.\n\nTo use the theano backend, the following packages are required:\n\n* [Theano \u003e= 0.9.0](http://deeplearning.net/software/theano/#): Please follow [these instructions](http://deeplearning.net/software/theano/install_ubuntu.html) for installation.\n* [SciPy \u003e= 0.14 \u003c0.17.1](https://scipy.org/): This is a Theano requirement.\n* [BLAS](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms): This is a Theano requirement.\n\nTo use the tensorflow backend, the following packages are required:\n\n* [Tensorflow \u003e= 1.4](https://www.tensorflow.org/): Please follow this [documentation](https://www.tensorflow.org/install/install_linux).\n\nFor the Theano backend, these requirements can be installed with:\n\n```\nconda install numpy scipy mkl theano pygpu scikit-image ruamel_yaml matplotlib h5py\npip install pygame sharedarray\n```\n\nAdditionally, Tensorflow can be installed, e.g. through:\n\n```\npip install --ignore-installed --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow_gpu-1.4.0-cp35-cp35m-linux_x86_64.whl\n```\n\n------------------------------------------------------------------------------\n\nInstallation\n------------\n\n* Check that all requirements are installed.\n* Checkout the statestream repository.\n* Compile some c/c++ functions:\n\n```\ncd statestream/ccpp\nmake\ncd ..\n```\n\n* Add the path of the repository (the folder that also contains this README.md) to the PYTHONPATH environment variable, e.g. with:\n\n```\nexport PYTHONPATH=$PYTHONPATH:/path to repository/\n```\n\n* Finally call the core once for initialization:\n\n```\npython core.py\n```\n\nNow the configuration file **~/.statestream/stcore.yml** was created and one can change the theano flag or the save folder parameter which specifies where for example models should be saved. In this folder also other log files are stored during runtime.\n\nThe demonstration example does not make use of GPU acceleration, but in order to use GPU support see the help on [devices](docs/devices.md).\n\n------------------------------------------------------------------------------\n    \nDemonstration example\n---------------------\n\nA demonstration [example](examples/demo.st_graph) is provided with this repository for which neither an external dataset nor GPU support is required. It consists of a simple 4 layer network for classification of the first 10 roman numerals: I, II, III, IV, V, VI, VII, VIII, IX, X. Dependent on the monitor settings on the system, one may want to adapt the _screen_width_ and _screen_height_ setting in **~/.statestream/stviz.yml** (available after first launch of the visualization) and the backend setting in the demo.st_graph specification. The demonstration example in particular uses a resolution of 1600 x 900. \nBy default, this example will use the tensorflow backand. For the theano backend, the line \n\n```\nbackend: tensorflow\n```\n\nin the examples/demo.st_graph file has to be removed or replaced with the line\n\n```\nbackend: theano\n```\n\nNow the demonstration can be started from the statestream folder with:\n\n\n```\npython core.py ../examples/demo.st_graph\n```\n\nIn fact, this is the preferred way to start any statestream session. The statestream terminal starts and the last line in the console should look like the following (only with the current time):\n\n```\nWed, 21 Dec 2016 12:53:41 @ initializing: (7 remaining) \u003c\u003c  \u003c\u003c\n```\n\nNow, the entire network specified in [demo.st_graph](examples/demo.st_graph) is instantiated in the background. Wait until the number of remaining items which are not yet instantiated reaches 0 and the network is ready (this can take some seconds), e.g.:\n\n```\nWed, 21 Dec 2016 12:55:03 @ 00000000 \u003c\u003c  \u003c\u003c\n```\n\nWhile waiting, one can already start the provided GUI by entering **viz on** into the terminal and hitting enter:\n\n```\nWed, 21 Dec 2016 12:53:50 @ initializing: (1 remaining) \u003c\u003c viz on \u003c\u003c\n```\n\nThe GUI opens and the network topology can be inspected. For this demonstration example, an example layout (graphview) of the network is provided. Once all items are instantiated, the network streaming can be started by pushing the play button in the GUI or entering **stream** into the terminal:\n\n```\nWed, 21 Dec 2016 12:55:24 @ 00000000 \u003c\u003c stream \u003c\u003c\n```\n\nIn the visualization, one should see a similar overview to that at the top of this readme. The network is now streaming (the counter in the statestream terminal is the current frame), e.g.:\n\n```\nWed, 21 Dec 2016 12:44:31 @ 00000732 \u003c\u003c \u003c\u003c\n```\n\nTo end the demonstration, enter **exit** in the statestream terminal.\n\nBefore running other provided examples, please set __visible_devices__ in **~/.statestream/stcore.yml** configuration file and read documentation on [devices](docs/devices.md). Also see the network [specification](docs/network_specification.md) and adapt especially paths, local devices, and the backend specified in the **st_graph** example files. For more information on the statestream terminal and visualization, please visit the [documentation](docs/README.md). Good places to start further reading are:\n\n* [Device handling](docs/devices.md)\n* [Getting creative](docs/getting_creative.md)\n* [Visualization tutorial](docs/visualization.md)\n* [Network specification](docs/network_specification.md)\n\nAn example realizing the common training / validation / test session is also provided: [st_graph file](examples/test_core_client_trainvaltest.st_graph), [client file](examples/core_clients/trainvaltest.py).\n\n------------------------------------------------------------------------------\n\nContributing\n------------\n\nPlease see also [CONTRIBUTING](CONTRIBUTING.md).\n\n------------------------------------------------------------------------------\n\nLicense\n-------\n\nThe statestream toolbox is open-sourced under the Apache-2.0 license. See the\n[LICENSE](LICENSE) file for details.\n\nFor a list of other open source components included in the statestream toolbox, see the file [3rd-party-licenses.txt](3rd-party-licenses.txt).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboschresearch%2Fstatestream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboschresearch%2Fstatestream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboschresearch%2Fstatestream/lists"}