{"id":18043270,"url":"https://github.com/ccnmaastricht/angorapy","last_synced_at":"2025-04-09T22:04:36.518Z","repository":{"id":39566677,"uuid":"206078847","full_name":"ccnmaastricht/angorapy","owner":"ccnmaastricht","description":"Build embodied brain models with ease.","archived":false,"fork":false,"pushed_at":"2025-01-31T13:36:33.000Z","size":163930,"stargazers_count":18,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T22:04:25.370Z","etag":null,"topics":["computational-neuroscience","deep-learning","keras","neuroscience","sensorimotor-modeling"],"latest_commit_sha":null,"homepage":"http://angorapy.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccnmaastricht.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-03T13:03:05.000Z","updated_at":"2024-11-27T13:08:54.000Z","dependencies_parsed_at":"2024-08-13T21:57:31.161Z","dependency_job_id":null,"html_url":"https://github.com/ccnmaastricht/angorapy","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccnmaastricht%2Fangorapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccnmaastricht%2Fangorapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccnmaastricht%2Fangorapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccnmaastricht%2Fangorapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccnmaastricht","download_url":"https://codeload.github.com/ccnmaastricht/angorapy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119296,"owners_count":21050755,"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":["computational-neuroscience","deep-learning","keras","neuroscience","sensorimotor-modeling"],"created_at":"2024-10-30T17:07:51.971Z","updated_at":"2025-04-09T22:04:36.510Z","avatar_url":"https://github.com/ccnmaastricht.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://img.shields.io/pypi/v/angorapy)\n![](https://img.shields.io/pypi/pyversions/angorapy)\n![](https://img.shields.io/github/license/ccnmaastricht/angorapy)\n![Monthly Downloads](https://img.shields.io/pypi/dm/angorapy)\n![Total Downloads](https://static.pepy.tech/badge/angorapy)\n\u003ca href=https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2023.1223687/full\u003e\n   \u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/Frontiers-Technical_Paper-white?style=flat\"\u003e\n\u003c/a\u003e\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/img/angorapy.svg\" width=25% align=\"center\" /\u003e\u003c/p\u003e\n\u003ch3\u003e \u003cp align=\"center\"\u003e Build Embodied Brain Models with Ease \u003c/p\u003e \u003c/h3\u003e\n\n\u003cbr /\u003e\n   \n**AngoraPy** is an open source modeling library for buidling [goal-driven](https://pubmed.ncbi.nlm.nih.gov/26906502/) embodied brain models. It provides an easy-to-us API to build and train deep neural network models of the brain on various, customizable, sensorimotor tasks, using reinforcement learning. AngoraPy employs state-of-the-art machine learning techniques, optimized for distributed computation scaling from local workstations to high-performance computing clusters. We aim to hide as much of this under the hood of an intuitive, high-level API but preserve the option for customizing most aspects of the pipeline.\n\n## :sparkles: Features\n\n![angorapy-features](https://github.com/user-attachments/assets/4732a3a7-0144-45e1-b3e8-1602d338f42f)\n\n## 📥 Installation\n\n### Prerequisites\nAngoraPy requires Python 3.6 or higher. It is recommended to use a virtual environment to install AngoraPy and its dependencies. Additionally, some prerequisites are required. \n\nOn Ubuntu, these can be installed by running\n\n    sudo apt-get install swig\n\nAdditionally, to run AngoraPy with its native distribution, you need MPI installed. On Ubuntu, this can be done by running\n\n    sudo apt-get install libopenmpi-dev\n\nHowever, any other MPI implementation should work as well.\n\n### Installing AngoraPy\n\n#### Binaries\nAngoraPy is available as a binary package on PyPI. To install it, run \n\n    pip install angorapy\n\nin your terminal.\n\nIf you would like to install a specific version, you can specify it by appending `==\u003cversion\u003e` to the command above. For example, to install version 0.9.0, run \n\n    pip install angorapy==0.10.8\n\n#### Source Installation\nTo install AngoraPy from source, clone the repository and run `pip install -e .` in the root directory.\n\n#### Test Your Installation\nYou can test your installation by running the following command in your terminal:\n\n    python -m angorapy.train CartPole-v1\n\nTo test your MPI installation, run\n\n    mpirun -np \u003cnumthreads\u003e --use-hwthread-cpus python -m angorapy.train LunarLanderContinuous-v2\n\nwhere `\u003cnumthreads\u003e` is the number of threads you want to (and can) use.\n\n### Docker\n\nAlternatively, you can install AngoraPy and all its dependencies in a docker container using the Dockerfile provided in this repository (/docker/Dockerfile). To this end, download the repository and build the docker image from the /docker directory:\n\n```bash\nsudo docker build -t angorapy:master https://github.com/ccnmaastricht/angorapy.git#master -f - \u003c Dockerfile\n```\n\nTo install different versions, replace `#master` in the source by the tag/branch of the respective version you want to install.\n\n## 🚀 Getting Started\n[ ➡️ Tutorial Section on Getting Started](https://github.com/weidler/angorapy-tutorials/tree/main/get-started)\n\nThe scripts `train.py`, `evaluate.py` and `observe.py` provide ready-made scripts for training and evaluating an agent in any environment. With `pretrain.py`, it is possible to pretrain the visual component. `benchmark.py` provides functionality for training a batch of agents possibly using different configs for comparison of strategies.\n\n### Training an Agent\n\nThe `train.py` commandline interface provides a convenient entry-point for running all sorts of experiments using the builtin models and environments in angorapy. You can train an agent on any environment with optional hyperparameters. Additionally, a monitor will be automatically linked to the training of the agent. For more detail consult the \u003ca href=\"monitor/README.md\"\u003eREADME on monitoring\u003c/a\u003e.\n\nBase usage of `train.py` is as follows:\n\n    python -m angorapy.train ENV --architecture MODEL\n    \nFor instance, training `LunarLanderContinuous-v2` using the `deeper` architecture is possible by running:\n\n    python -m angorapy.train LunarLanderContinuous-v2 --architecture deeper\n    \nFor more advanced options like custom hyperparameters, consult\n\n    python -m angorapy.train -h\n\n\n### Evaluating and Observing an Agent\n[ ➡️ Tutorial Section on Agent Analysis](https://github.com/weidler/angorapy-tutorials/tree/main/analysis)\n\nThere are two more entry points for evaluating and observing an agent: `evaluate` and `observe`. General usage is as follows\n\n    python -m angorapy.evaluate ID\n    python -m angorapy.observe ID\n\nWhere ID is the agent's ID given when its created (`train.py` prints this outt, in custom scripts get it with `agent.agent_id`).\n\n### Writing a Training Script\nTo train agents with custom models, environments, etc. you write your own script. The following is a minimal example:\n\n```python\n\nfrom angorapy import make_task\nfrom angorapy.models import get_model_builder\nfrom angorapy.agent.ppo_agent import PPOAgent\n\nenv = make_task(\"LunarLanderContinuous-v2\")\nmodel_builder = get_model_builder(\"simple\", \"ffn\")\nagent = PPOAgent(model_builder, env)\nagent.drill(100, 10, 512)\n```\n\nFor more details, consult the [examples](examples).\n\n### Customizing the Models and Environments\n[ ➡️ Tutorial Section on Customization](https://github.com/weidler/angorapy-tutorials/tree/main/customization)\n\n## 🎓 Documentation\n\nDetailed documentation of AngoraPy is provided in the READMEs of most subpackages. Additionally, we provide [examples and tutorials](https://github.com/weidler/angorapy-tutorials/) that get you started with writing your own scripts using AngoraPy. For further readings on specific modules, consult the following READMEs:\n\n- [Agent](angorapy/agent) [WIP]\n- [Environments](angorapy/tasks)\n- [Models](angorapy/models)\n- [Analysis](angorapy/analysis)\n- [Monitoring](angorapy/monitor)\n\nIf you are missing a documentation for a specific part of AngoraPy, feel free to open an issue and we will do our best to add it.\n\n## 🔀 Distributed Computation\n\nPPO is an asynchronous algorithm, allowing multiple parallel workers to generate experience independently.\nWe allow parallel gathering and optimization through MPI. Agents will automatically distribute their workers evenly on\nthe available CPU cores, while optimization is distributed over all available GPUs. If no GPUs are available, all CPUs\nshare the task of optimizing.\n\nDistribution is possible locally on your workstation and on HPC sites.\n\n### 💻 Local Distributed Computing with MPI\n\nTo use MPI locally, you need to have a running MPI implementation, e.g. Open MPI 4 on Ubuntu.\nTo execute `train.py` via MPI, run\n\n```bash\nmpirun -np 12 --use-hwthread-cpus python -m angorapy.train ...\n```\n\nwhere, in this example, 12 is the number of locally available CPU threads and `--use-hwthread-cpus`\nmakes available threads (as opposed to only cores). Usage of `train.py` is as described previously.\n\n### :cloud: Distributed Training on SLURM-based HPC clusters\n\n*Please note that the following is optimized and tested on the specific cluster we use, but should extend to at least\nany SLURM based setup.*\n\nOn any SLURM-based HPC cluster you may submit your job with sbatch usising the following script template:\n\n```bash\n#!/bin/bash -l\n#SBATCH --job-name=\"angorapy\"\n#SBATCH --account=xxx\n#SBATCH --time=24:00:00\n#SBATCH --nodes=32\n#SBATCH --ntasks-per-core=1\n#SBATCH --ntasks-per-node=12\n#SBATCH --cpus-per-task=1\n#SBATCH --partition=normal\n#SBATCH --constraint=gpu\u0026startx\n#SBATCH --hint=nomultithread\n\nexport OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK\nexport CRAY_CUDA_MPS=1\n\n# load virtual environment\nsource ${HOME}/robovenv/bin/activate\n\nexport DISPLAY=:0\nsrun python3 -u train.py ...\n```\n\nThe number of parallel workers will equal the number of nodes times the number of CPUs per node\n(32 x 12 = 384 in the template above).\n\n## 🔗 Citing AngoraPy\n\nIf you use AngoraPy for your research, please cite the technical paper\n\n    Weidler, T., Goebel, R., \u0026 Senden, M. (2023). AngoraPy: A Python toolkit for modeling anthropomorphic goal-driven sensorimotor systems. Frontiers in Neuroinformatics, 17. 10.3389/fninf.2023.1223687\n\nOr using bibtex\n\n```bibtex\n @software{weidler_angorapy_2023,\n   AUTHOR  =   {Weidler, Tonio  and Goebel, Rainer  and Senden, Mario },\n   TITLE   =   {AngoraPy: A Python toolkit for modeling anthropomorphic goal-driven sensorimotor systems},\n   JOURNAL =   {Frontiers in Neuroinformatics},\n   VOLUME  =   {17},\n   YEAR    =   {2023},\n   DOI     =   {10.3389/fninf.2023.1223687},\n   ISSN    =   {1662-5196},\n}\n```\n\n## Funding\n\nThis project was supported by the European Union's Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3). It is further supported by an Open Science Fund from the Dutch Research Council (Nederlandse Organisatie voor Wetenschappelijk Onderzoek; NWO). We are grateful for their support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccnmaastricht%2Fangorapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccnmaastricht%2Fangorapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccnmaastricht%2Fangorapy/lists"}