{"id":50971190,"url":"https://github.com/zombie-einstein/thants","last_synced_at":"2026-06-19T02:31:49.509Z","repository":{"id":318731275,"uuid":"1042210155","full_name":"zombie-einstein/thants","owner":"zombie-einstein","description":"Thanks ants!","archived":false,"fork":false,"pushed_at":"2025-11-15T23:57:14.000Z","size":1341,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T12:06:35.032Z","etag":null,"topics":["a-life","multi-agent-reinforcement-learning","reinforcement-learning","reinforcement-learning-environments"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zombie-einstein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-21T16:48:57.000Z","updated_at":"2025-12-21T07:58:35.000Z","dependencies_parsed_at":"2025-10-13T17:10:48.558Z","dependency_job_id":"5e7f04f5-1100-41f3-a72b-c9092bad0357","html_url":"https://github.com/zombie-einstein/thants","commit_stats":null,"previous_names":["zombie-einstein/thants"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/zombie-einstein/thants","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombie-einstein%2Fthants","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombie-einstein%2Fthants/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombie-einstein%2Fthants/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombie-einstein%2Fthants/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zombie-einstein","download_url":"https://codeload.github.com/zombie-einstein/thants/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombie-einstein%2Fthants/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34515405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["a-life","multi-agent-reinforcement-learning","reinforcement-learning","reinforcement-learning-environments"],"created_at":"2026-06-19T02:31:47.767Z","updated_at":"2026-06-19T02:31:49.482Z","avatar_url":"https://github.com/zombie-einstein.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/zombie-einstein/thants/raw/main/.github/images/thants.gif\" /\u003e\n  \u003cbr\u003e\n  \u003cem\u003eThanks ants!\u003c/em\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n# Thants\n\n*Multi-agent and multi-team reinforcement-learning environment modelling ant foraging*\n\n## Introduction\n\nThants is a rl environment library based on models of ant colonies foraging for food, also supporting\nenvironments with multiple competing colonies.\n\nThants is implemented using JAX, allowing the environments to be run on GPU enabling large scale performant\nsimulation, and the ability to run environments alongside JAX and Pytorch ML tools.\n\nThe environment is implemented using the [Jumanji](https://github.com/instadeepai/jumanji) RL environment API, with some modification\nfor the multi-colony case.\n\n## Usage\n\n### Installation\n\nThants can be installed from pypi using\n\n```commandline\npip install thants\n```\n\n### Examples\n\n#### Single Colony\n\nThe single colony environment follows the [Jumanji](https://github.com/instadeepai/jumanji)\nenvironment API, with actions provided as an array of individual\nactions:\n\n```python\nfrom thants.envs import ThantsMono\nimport jax\n\nenv = ThantsMono(dims=(50, 50))\nkey = jax.random.PRNGKey(101)\nstate, obs = env.reset(key)\nstate_history = [state]\n\nfor _ in range(50):\n    key, action_key = jax.random.split(key, 2)\n    actions = jax.random.choice(\n        action_key, env.num_actions, (env.num_agents,)\n    )\n    state, obs = env.step(state, actions)\n    state_history.append(state)\n\nenv.animate(state_history, 100, \"mono_colony.gif\")\n```\n\n#### Multi-Colony\n\nIn the multi-colony case each colony is treated independently (and can be\ndifferent sizes), so actions, observations, timesteps are list/tuples of\narrays/structs:\n\n```python\nfrom thants.envs import Thants\nimport jax\nimport jax.numpy as jnp\n\nenv = Thants((50, 100))\nkey = jax.random.PRNGKey(101)\nstate, obs = env.reset(key)\nstate_history = [state]\n\nfor _ in range(50):\n    key, k1, k2 = jax.random.split(key, 3)\n    # List of action arrays per colony\n    actions = [\n        jax.random.choice(k1, env.num_actions, (env.num_agents[0],)),\n        jax.random.choice(k2, env.num_actions, (env.num_agents[1],)),\n    ]\n    state, obs = env.step(state, actions)\n    state_history.append(state)\n\nenv.animate(state_history, 100, \"multi_colony.gif\")\n```\n\nPreset simple environments can be imported from `thants.envs.ThantsDual` and\n`thants.envs.ThantsQuad` with 2 and 4 colonies respectively.\n\n## Environment\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/zombie-einstein/thants/raw/main/.github/images/thants_env.gif\" /\u003e\n  \u003cbr\u003e\n  \u003cem\u003eA Thants environment with two competing colonies.\u003c/em\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\nThe environment is modelled as a grid, wrapped at the boundaries. Ants (the agents)\noccupy individual cells on the grid (and cannot overlap). Ants can pick up, carry,\nand deposit food, or deposit persistent signals that can be observed by other ants\nin the same colony.\n\n### State\n\n#### Colonies\n\nThe state of the ant colonies is represented by a single struct:\n\n- *Ants*: Individual ants themselves have several components:\n    - *Positions*: 2d indices of ant positions on the environment grid.\n    - *Carrying*: The amount of food being carried by each ant.\n    - *Health*: Ant health (currently unused).\n- *Colony Index*: The index of the colony each ant belongs to\n- *Nests*: 2d array indicating the index of the colony each cell belongs to\n  (`0` in the case a cell is not the nest of any colony).\n- *Signals*: 4d array of signal deposits at each cell for each colony. Signals have\n  multiple channels to facilitate communication between ants (i.e. the 2nd dimension\n  of the array is the signal channel).\n\n#### Environment\n\nThe state of the environment then consists of the colonies and state shared\nby all the colonies\n\n- *Colonies*: Ant colonies state\n- *Food*: 2d array representing the amount of food deposited at each cell\n- *Terrain*: 2d array of flags indicating if a cell can be occupied by an ant. This\n  allows obstacles to be placed on the environment.\n\n#### Updates\n\nEach step of the environment performs the following update to the state:\n\n- Convert integer action choices into state updates\n- Apply ant position updates\n- Apply food pick-up and deposit actions\n- Drop any new food deposits\n- Dissipate and propagate signals\n- Apply signal deposit actions\n- Clear any food that has been deposited on a nest (i.e. the food is consumed\n  by the colony)\n\nThe behaviour of the dynamics of signals can be customised by implementing the\n[`thants.signals.SignalPropagator`](src/thants/signals.py) base class and\npassing it when initialising the environment.\n\n#### State Generators\n\nThe initialisation of the environment can be customised by implementing the\nrelevant base class and passing them to the environment.\n\n### Actions\n\nAnts can select from several discrete actions, indicated by an integer value:\n\n- `0`: Null action (i.e. no change to the environment)\n- `1 - 4`: Move in one of the four ordinal directions (if possible)\n- `5`: Take a fixed amount of food from the ants location (if possible)\n- `6`: Deposit a fixed amount of food from the ants location (if possible)\n- `7+`: Deposit a fixed amount of signal at the ants location\n\nNote that actions can be selected, but may not be possible e.g. attempting\nto move to an occupied cell, or taking food from an empty cell. In this\ncase there will be no change in state due to the chosen action.\n\n### Observations\n\nIndividual agent observations also consist of several components. Observations are\nindividually made for the local neighbourhood of each ant, i.e. the surrounding\ncells on the environment grid, and their own cell:\n\n- `ants`: Flag indicating if a cell in the neighbourhood is occupied by an ant,\n  with the shape `[n-ants, n-colonies, 9]` where the second dimensions indicates the\n  individual colonies. The ants from the same colony will always be on the first row.\n- `signals`: Signal deposits in the neighbourhood (across all channels), signals are\n  observed individually for each colony.\n- `food`: Food deposits within the neighbourhood.\n- `nest`: Flag indicating if a neighbouring cell is designated as a nest for the ants colony.\n- `terrain`: Flag indicating if a neighbouring cell can be occupied.\n- `carrying`: Amount of food currently being carried by each ant.\n\nthe number of local cells observed by each agent can be customised with the `view_distance`\nenvironment parameter.\n\n### Rewards\n\nBy default, rewards are granted to ants when they deposit food on their colonies nest.\nReward signals can be customised by implementing the respective base class\n[`thants.rewards.RewardFn`](src/thants/rewards.py).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzombie-einstein%2Fthants","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzombie-einstein%2Fthants","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzombie-einstein%2Fthants/lists"}