# EDYS
Tackling emergent dysfunctions (EDYs) in cooperation with Fraunhofer-IKS
## Setup
Install this environment using `pip install marl-factory-grid`.
## First Steps
### Quickstart
Most of the env. objects (entites, rules and assets) can be loaded automatically.
Just define what your environment needs in a *yaml*-configfile like:
<details><summary>Example ConfigFile</summary>
# Default Configuration File
General:
# RNG-seed to sample the same "random" numbers every time, to make the different runs comparable.
env_seed: 69
# Individual vs global rewards
individual_rewards: true
# The level.txt file to load from marl_factory_grid/levels
level_name: large
# View Radius; 0 = full observatbility
pomdp_r: 3
# Print all messages and events
verbose: false
# Run tests
tests: false
# Agents section defines the characteristics of different agents in the environment.
# An Agent requires a list of actions and observations.
# Possible actions: Noop, Charge, Clean, DestAction, DoorUse, ItemAction, MachineAction, Move8, Move4, North, NorthEast, ...
# Possible observations: All, Combined, GlobalPosition, Battery, ChargePods, DirtPiles, Destinations, Doors, Items, Inventory, DropOffLocations, Maintainers, ...
# You can use 'clone' as the agent name to have multiple instances with either a list of names or an int specifying the number of clones.
Agents:
Wolfgang:
Actions:
- Noop
- Charge
- Clean
- DestAction
- DoorUse
- ItemAction
- Move8
Observations:
- Combined:
- Other
- Walls
- GlobalPosition
- Battery
- ChargePods
- DirtPiles
- Destinations
- Doors
- Items
- Inventory
- DropOffLocations
- Maintainers
# Entities section defines the initial parameters and behaviors of different entities in the environment.
# Entities all spawn using coords_or_quantity, a number of entities or coordinates to place them.
Entities:
# Batteries: Entities representing power sources for agents.
Batteries:
initial_charge: 0.8
per_action_costs: 0.02
# ChargePods: Entities representing charging stations for Batteries.
ChargePods:
coords_or_quantity: 2
# Destinations: Entities representing target locations for agents.
# - spawn_mode: GROUPED or SINGLE. Determines how destinations are spawned.
Destinations:
coords_or_quantity: 1
spawn_mode: GROUPED
# DirtPiles: Entities representing piles of dirt.
# - initial_amount: Initial amount of dirt in each pile.
# - clean_amount: Amount of dirt cleaned in each cleaning action.
# - dirt_spawn_r_var: Random variation in dirt spawn amounts.
# - max_global_amount: Maximum total amount of dirt allowed in the environment.
# - max_local_amount: Maximum amount of dirt allowed in one position.
DirtPiles:
coords_or_quantity: 10
initial_amount: 2
clean_amount: 1
dirt_spawn_r_var: 0.1
max_global_amount: 20
max_local_amount: 5
# Doors are spawned using the level map.
Doors:
# DropOffLocations: Entities representing locations where agents can drop off items.
# - max_dropoff_storage_size: Maximum storage capacity at each drop-off location.
DropOffLocations:
coords_or_quantity: 1
max_dropoff_storage_size: 0
# GlobalPositions.
GlobalPositions: { }
# Inventories: Entities representing inventories for agents.
Inventories: { }
# Items: Entities representing items in the environment.
Items:
coords_or_quantity: 5
# Machines: Entities representing machines in the environment.
Machines:
coords_or_quantity: 2
# Maintainers: Entities representing maintainers that aim to maintain machines.
Maintainers:
coords_or_quantity: 1
# Rules section specifies the rules governing the dynamics of the environment.
Rules:
# Environment Dynamics
# When stepping over a dirt pile, entities carry a ratio of the dirt to their next position
EntitiesSmearDirtOnMove:
smear_ratio: 0.2
# Doors automatically close after a certain number of time steps
DoorAutoClose:
close_frequency: 10
# Maintainers move at every time step
MoveMaintainers:
# Respawn Stuff
# Define how dirt should respawn after the initial spawn
RespawnDirt:
respawn_freq: 15
# Define how items should respawn after the initial spawn
RespawnItems:
respawn_freq: 15
# Utilities
# This rule defines the collision mechanic, introduces a related DoneCondition and lets you specify rewards.
# Can be omitted/ignored if you do not want to take care of collisions at all.
WatchCollisions:
done_at_collisions: false
# Done Conditions
# Define the conditions for the environment to stop. Either success or a fail conditions.
# The environment stops when an agent reaches a destination
DoneAtDestinationReach:
# The environment stops when all dirt is cleaned
DoneOnAllDirtCleaned:
# The environment stops when a battery is discharged
DoneAtBatteryDischarge:
# The environment stops when a maintainer reports a collision
DoneAtMaintainerCollision:
# The environment stops after max steps
DoneAtMaxStepsReached:
max_steps: 500
</details>
Have a look in [\quickstart](./quickstart) for further configuration examples.
### Make it your own
#### Levels
Varying levels are created by defining Walls, Floor or Doors in *.txt*-files (see [./environment/levels](./environment/levels) for examples).
Define which *level* to use in your *configfile* as:
```yaml
General:
level_name: rooms # 'double', 'large', 'simple', ...
```
... or create your own , maybe with the help of [asciiflow.com](https://asciiflow.com/#/).
Make sure to use `#` as [Walls](marl_factory_grid/environment/entity/wall.py), `-` as free (walkable) floor, `D` for [Walls](./modules/doors/entities.py).
Other Entites (define you own) may bring their own `Symbols`
#### Entites
Entites are [Objects](marl_factory_grid/environment/entity/object.py) that can additionally be assigned a position.
Abstract Entities are provided.
#### Groups
[Groups](marl_factory_grid/environment/groups/objects.py) are entity Sets that provide administrative access to all group members.
All [Entites](marl_factory_grid/environment/entity/global_entities.py) are available at runtime as EnvState property.
#### Rules
[Rules](marl_factory_grid/environment/entity/object.py) define how the environment behaves on microscale.
Each of the hookes (`on_init`, `pre_step`, `on_step`, '`post_step`', `on_done`)
provide env-access to implement customn logic, calculate rewards, or gather information.
[Results](marl_factory_grid/environment/entity/object.py) provide a way to return `rule` evaluations such as rewards and state reports
back to the environment.
#### Assets
Make sure to bring your own assets for each Entity living in the Gridworld as the `Renderer` relies on it.
PNG-files (transparent background) of square aspect-ratio should do the job, in general.
<img src="/marl_factory_grid/environment/assets/wall.png" width="5%">
<!--suppress HtmlUnknownAttribute -->
<html      html>
<img src="/marl_factory_grid/environment/assets/agent/agent.png" width="5%">
Raw data
{
"_id": null,
"home_page": "https://github.com/illiumst/marl-factory-grid/import",
"name": "Marl-Factory-Grid",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "artificial intelligence,pytorch,multiagent reinforcement learning,simulation,emergence,gymnasium,environment,deepdiff,natsort",
"author": "Steffen Illium",
"author_email": "steffen.illium@ifi.lmu.de",
"download_url": "https://files.pythonhosted.org/packages/82/05/5718138e7d1c8f4fa17fc696a36ffeda7a4ab9d4881a586160f280e87ec5/Marl-Factory-Grid-0.2.5.tar.gz",
"platform": null,
"description": "# EDYS\n\nTackling emergent dysfunctions (EDYs) in cooperation with Fraunhofer-IKS\n\n## Setup\nInstall this environment using `pip install marl-factory-grid`.\n\n## First Steps\n\n\n### Quickstart\nMost of the env. objects (entites, rules and assets) can be loaded automatically. \nJust define what your environment needs in a *yaml*-configfile like:\n\n<details><summary>Example ConfigFile</summary> \n \n # Default Configuration File\n \n General:\n # RNG-seed to sample the same \"random\" numbers every time, to make the different runs comparable.\n env_seed: 69\n # Individual vs global rewards\n individual_rewards: true\n # The level.txt file to load from marl_factory_grid/levels\n level_name: large\n # View Radius; 0 = full observatbility\n pomdp_r: 3\n # Print all messages and events\n verbose: false\n # Run tests\n tests: false\n \n # Agents section defines the characteristics of different agents in the environment.\n \n # An Agent requires a list of actions and observations.\n # Possible actions: Noop, Charge, Clean, DestAction, DoorUse, ItemAction, MachineAction, Move8, Move4, North, NorthEast, ...\n # Possible observations: All, Combined, GlobalPosition, Battery, ChargePods, DirtPiles, Destinations, Doors, Items, Inventory, DropOffLocations, Maintainers, ...\n # You can use 'clone' as the agent name to have multiple instances with either a list of names or an int specifying the number of clones.\n Agents:\n Wolfgang:\n Actions:\n - Noop\n - Charge\n - Clean\n - DestAction\n - DoorUse\n - ItemAction\n - Move8\n Observations:\n - Combined:\n - Other\n - Walls\n - GlobalPosition\n - Battery\n - ChargePods\n - DirtPiles\n - Destinations\n - Doors\n - Items\n - Inventory\n - DropOffLocations\n - Maintainers\n \n # Entities section defines the initial parameters and behaviors of different entities in the environment.\n # Entities all spawn using coords_or_quantity, a number of entities or coordinates to place them.\n Entities:\n # Batteries: Entities representing power sources for agents.\n Batteries:\n initial_charge: 0.8\n per_action_costs: 0.02\n \n # ChargePods: Entities representing charging stations for Batteries.\n ChargePods:\n coords_or_quantity: 2\n \n # Destinations: Entities representing target locations for agents.\n # - spawn_mode: GROUPED or SINGLE. Determines how destinations are spawned.\n Destinations:\n coords_or_quantity: 1\n spawn_mode: GROUPED\n \n # DirtPiles: Entities representing piles of dirt.\n # - initial_amount: Initial amount of dirt in each pile.\n # - clean_amount: Amount of dirt cleaned in each cleaning action.\n # - dirt_spawn_r_var: Random variation in dirt spawn amounts.\n # - max_global_amount: Maximum total amount of dirt allowed in the environment.\n # - max_local_amount: Maximum amount of dirt allowed in one position.\n DirtPiles:\n coords_or_quantity: 10\n initial_amount: 2\n clean_amount: 1\n dirt_spawn_r_var: 0.1\n max_global_amount: 20\n max_local_amount: 5\n \n # Doors are spawned using the level map.\n Doors:\n \n # DropOffLocations: Entities representing locations where agents can drop off items.\n # - max_dropoff_storage_size: Maximum storage capacity at each drop-off location.\n DropOffLocations:\n coords_or_quantity: 1\n max_dropoff_storage_size: 0\n \n # GlobalPositions.\n GlobalPositions: { }\n \n # Inventories: Entities representing inventories for agents.\n Inventories: { }\n \n # Items: Entities representing items in the environment.\n Items:\n coords_or_quantity: 5\n \n # Machines: Entities representing machines in the environment.\n Machines:\n coords_or_quantity: 2\n \n # Maintainers: Entities representing maintainers that aim to maintain machines.\n Maintainers:\n coords_or_quantity: 1\n \n \n # Rules section specifies the rules governing the dynamics of the environment.\n Rules:\n # Environment Dynamics\n # When stepping over a dirt pile, entities carry a ratio of the dirt to their next position\n EntitiesSmearDirtOnMove:\n smear_ratio: 0.2\n # Doors automatically close after a certain number of time steps\n DoorAutoClose:\n close_frequency: 10\n # Maintainers move at every time step\n MoveMaintainers:\n \n # Respawn Stuff\n # Define how dirt should respawn after the initial spawn\n RespawnDirt:\n respawn_freq: 15\n # Define how items should respawn after the initial spawn\n RespawnItems:\n respawn_freq: 15\n \n # Utilities\n # This rule defines the collision mechanic, introduces a related DoneCondition and lets you specify rewards.\n # Can be omitted/ignored if you do not want to take care of collisions at all.\n WatchCollisions:\n done_at_collisions: false\n \n # Done Conditions\n # Define the conditions for the environment to stop. Either success or a fail conditions.\n # The environment stops when an agent reaches a destination\n DoneAtDestinationReach:\n # The environment stops when all dirt is cleaned\n DoneOnAllDirtCleaned:\n # The environment stops when a battery is discharged\n DoneAtBatteryDischarge:\n # The environment stops when a maintainer reports a collision\n DoneAtMaintainerCollision:\n # The environment stops after max steps\n DoneAtMaxStepsReached:\n max_steps: 500\n\n </details>\n\nHave a look in [\\quickstart](./quickstart) for further configuration examples.\n\n### Make it your own\n\n#### Levels\nVarying levels are created by defining Walls, Floor or Doors in *.txt*-files (see [./environment/levels](./environment/levels) for examples).\nDefine which *level* to use in your *configfile* as: \n```yaml\nGeneral:\n level_name: rooms # 'double', 'large', 'simple', ...\n```\n... or create your own , maybe with the help of [asciiflow.com](https://asciiflow.com/#/).\nMake sure to use `#` as [Walls](marl_factory_grid/environment/entity/wall.py), `-` as free (walkable) floor, `D` for [Walls](./modules/doors/entities.py).\nOther Entites (define you own) may bring their own `Symbols`\n\n#### Entites\nEntites are [Objects](marl_factory_grid/environment/entity/object.py) that can additionally be assigned a position.\nAbstract Entities are provided.\n\n#### Groups\n[Groups](marl_factory_grid/environment/groups/objects.py) are entity Sets that provide administrative access to all group members. \nAll [Entites](marl_factory_grid/environment/entity/global_entities.py) are available at runtime as EnvState property.\n\n\n#### Rules\n[Rules](marl_factory_grid/environment/entity/object.py) define how the environment behaves on microscale.\nEach of the hookes (`on_init`, `pre_step`, `on_step`, '`post_step`', `on_done`) \nprovide env-access to implement customn logic, calculate rewards, or gather information.\n\n\n\n[Results](marl_factory_grid/environment/entity/object.py) provide a way to return `rule` evaluations such as rewards and state reports \nback to the environment.\n#### Assets\nMake sure to bring your own assets for each Entity living in the Gridworld as the `Renderer` relies on it.\nPNG-files (transparent background) of square aspect-ratio should do the job, in general.\n\n<img src=\"/marl_factory_grid/environment/assets/wall.png\" width=\"5%\"> \n<!--suppress HtmlUnknownAttribute -->\n<html      html> \n<img src=\"/marl_factory_grid/environment/assets/agent/agent.png\" width=\"5%\">\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework to research MARL agents in various setings.",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/illiumst/marl-factory-grid/import"
},
"split_keywords": [
"artificial intelligence",
"pytorch",
"multiagent reinforcement learning",
"simulation",
"emergence",
"gymnasium",
"environment",
"deepdiff",
"natsort"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "98db5dd79d3a6fd4cc267e9b0ba63a7ccfffd1ea513024bc6b8430070a0ab95e",
"md5": "a9b08f1ca21077141eeaf4f2bec427cf",
"sha256": "7dc37b110c63322f6a4aeda42c2e4e7f0f926cc86c2ce1a9c369d63dc62b1783"
},
"downloads": -1,
"filename": "Marl_Factory_Grid-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9b08f1ca21077141eeaf4f2bec427cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 265851,
"upload_time": "2023-12-01T10:15:51",
"upload_time_iso_8601": "2023-12-01T10:15:51.674531Z",
"url": "https://files.pythonhosted.org/packages/98/db/5dd79d3a6fd4cc267e9b0ba63a7ccfffd1ea513024bc6b8430070a0ab95e/Marl_Factory_Grid-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "82055718138e7d1c8f4fa17fc696a36ffeda7a4ab9d4881a586160f280e87ec5",
"md5": "90051d6e1bc442f65fac0c29c52dda3b",
"sha256": "74acfa9451f35beeba8151aedcaf4fe2ff21c59234bef64795c3e589b7b88ae4"
},
"downloads": -1,
"filename": "Marl-Factory-Grid-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "90051d6e1bc442f65fac0c29c52dda3b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 526759,
"upload_time": "2023-12-01T10:15:54",
"upload_time_iso_8601": "2023-12-01T10:15:54.144676Z",
"url": "https://files.pythonhosted.org/packages/82/05/5718138e7d1c8f4fa17fc696a36ffeda7a4ab9d4881a586160f280e87ec5/Marl-Factory-Grid-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-01 10:15:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "illiumst",
"github_project": "marl-factory-grid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "marl-factory-grid"
}
JSON
