{"id":28517533,"url":"https://github.com/projectmesa/mesa-frames","last_synced_at":"2025-10-22T02:57:59.656Z","repository":{"id":215758517,"uuid":"738465564","full_name":"projectmesa/mesa-frames","owner":"projectmesa","description":"Extension of mesa for performance and scalability","archived":false,"fork":false,"pushed_at":"2025-10-17T17:42:54.000Z","size":8277,"stargazers_count":32,"open_issues_count":48,"forks_count":16,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-10-18T19:56:45.576Z","etag":null,"topics":["agent-based-modeling","agent-based-modelling","complex-systems","complexity-analysis","gis","mesa","modeling-agents","pandas","simulation","simulation-environment","simulation-framework","spatial-models"],"latest_commit_sha":null,"homepage":"https://projectmesa.github.io/mesa-frames","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/projectmesa.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-01-03T09:41:29.000Z","updated_at":"2025-10-06T22:17:54.000Z","dependencies_parsed_at":"2024-05-19T01:36:20.335Z","dependency_job_id":"b52cb9e2-1ac8-429b-8943-fd01c02ce764","html_url":"https://github.com/projectmesa/mesa-frames","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"5eef75205df3d2d8628c5a519c163ff56a628802"},"previous_names":["adamamer20/mesa-frames"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/projectmesa/mesa-frames","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectmesa%2Fmesa-frames","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectmesa%2Fmesa-frames/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectmesa%2Fmesa-frames/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectmesa%2Fmesa-frames/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectmesa","download_url":"https://codeload.github.com/projectmesa/mesa-frames/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectmesa%2Fmesa-frames/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280370893,"owners_count":26319317,"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","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"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":["agent-based-modeling","agent-based-modelling","complex-systems","complexity-analysis","gis","mesa","modeling-agents","pandas","simulation","simulation-environment","simulation-framework","spatial-models"],"created_at":"2025-06-09T05:08:47.677Z","updated_at":"2025-10-22T02:57:59.650Z","avatar_url":"https://github.com/projectmesa.png","language":"Python","readme":"# mesa-frames 🚀\n\nmesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax. mesa-frames allows for the use of [vectorized functions](https://stackoverflow.com/a/1422198) which significantly speeds up operations whenever simultaneous activation of agents is possible.\n\n## Why DataFrames? 📊\n\nDataFrames are optimized for simultaneous operations through [SIMD processing](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data). At the moment, mesa-frames supports the use of Polars library.\n\n- [Polars](https://pola.rs/) is a new DataFrame library with a syntax similar to pandas but with several innovations, including a backend implemented in Rust, the Apache Arrow memory format, query optimization, and support for larger-than-memory DataFrames.\n\nThe following is a performance graph showing execution time using mesa and mesa-frames for the [Boltzmann Wealth model](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html).\n\n![Performance Graph with Mesa](https://github.com/projectmesa/mesa-frames/blob/main/examples/boltzmann_wealth/boltzmann_with_mesa.png)\n\n![Performance Graph without Mesa](https://github.com/projectmesa/mesa-frames/blob/main/examples/boltzmann_wealth/boltzmann_no_mesa.png)\n\n([You can check the script used to generate the graph here](https://github.com/projectmesa/mesa-frames/blob/main/examples/boltzmann_wealth/performance_plot.py), but if you want to additionally compare vs Mesa, you have to uncomment `mesa_implementation` and its label)\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install mesa-frames\n```\n\n### Install from Source\n\nTo install the most updated version of mesa-frames, you can clone the repository and install the package in editable mode.\n\n#### Cloning the Repository\n\nTo get started with mesa-frames, first clone the repository from GitHub:\n\n```bash\ngit clone https://github.com/projectmesa/mesa-frames.git\ncd mesa_frames\n```\n\n#### Installing in a Conda Environment\n\nIf you want to install it into a new environment:\n\n```bash\nconda create -n myenv\n```\n\nIf you want to install it into an existing environment:\n\n```bash\nconda activate myenv\n```\n\nThen, to install mesa-frames itself:\n\n```bash\npip install -e .\n```\n\n#### Installing in a Python Virtual Environment\n\nIf you want to install it into a new environment:\n\n```bash\npython3 -m venv myenv\nsource myenv/bin/activate  # On Windows, use `myenv\\Scripts\\activate`\n```\n\nIf you want to install it into an existing environment:\n\n```bash\nsource myenv/bin/activate  # On Windows, use `myenv\\Scripts\\activate`\n```\n\nThen, to install mesa-frames itself:\n\n```bash\npip install -e .\n```\n\n## Usage\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/projectmesa/mesa-frames/blob/main/docs/general/user-guide/2_introductory-tutorial.ipynb)\n\n**Note:** mesa-frames is currently in its early stages of development. As such, the usage patterns and API are subject to change. Breaking changes may be introduced. Reports of feedback and issues are encouraged.\n\n[You can find the API documentation here](https://projectmesa.github.io/mesa-frames/api).\n\n### Creation of an Agent\n\nThe agent implementation differs from base mesa. Agents are only defined at the AgentSet level. You can import `AgentSet`. As in mesa, you subclass and make sure to call `super().__init__(model)`. You can use the `add` method or the `+=` operator to add agents to the AgentSet. Most methods mirror the functionality of `mesa.AgentSet`. Additionally, `mesa-frames.AgentSet` implements many dunder methods such as `AgentSet[mask, attr]` to get and set items intuitively. All operations are by default inplace, but if you'd like to use functional programming, mesa-frames implements a fast copy method which aims to reduce memory usage, relying on reference-only and native copy methods.\n\n```python\nfrom mesa-frames import AgentSet\n\nclass MoneyAgents(AgentSet):\n    def __init__(self, n: int, model: Model):\n        super().__init__(model)\n        # Adding the agents to the agent set\n        self += pl.DataFrame(\n            {\"wealth\": pl.ones(n, eager=True)}\n        )\n\n    def step(self) -\u003e None:\n        # The give_money method is called\n        self.do(\"give_money\")\n\n    def give_money(self):\n        # Active agents are changed to wealthy agents\n        self.select(self.wealth \u003e 0)\n\n        # Receiving agents are sampled (only native expressions currently supported)\n        other_agents = self.df.sample(\n            n=len(self.active_agents), with_replacement=True\n        )\n\n        # Wealth of wealthy is decreased by 1\n        self[\"active\", \"wealth\"] -= 1\n\n        # Compute the income of the other agents (only native expressions currently supported)\n        new_wealth = other_agents.group_by(\"unique_id\").len()\n\n        # Add the income to the other agents\n        self[new_wealth, \"wealth\"] += new_wealth[\"len\"]\n```\n\n### Creation of the Model\n\nCreation of the model is fairly similar to the process in mesa. You subclass `Model` and call `super().__init__()`. The `model.sets` attribute has the same interface as `mesa-frames.AgentSet`. You can use `+=` or `self.sets.add` with a `mesa-frames.AgentSet` (or a list of `AgentSet`) to add agents to the model.\n\n```python\nfrom mesa-frames import Model\n\nclass MoneyModelDF(Model):\n    def __init__(self, N: int, agents_cls):\n        super().__init__()\n        self.n_agents = N\n        self.sets += MoneyAgents(N, self)\n\n    def step(self):\n        # Executes the step method for every agentset in self.sets\n        self.sets.do(\"step\")\n\n    def run_model(self, n):\n        for _ in range(n):\n            self.step()\n```\n\n## What's Next? 🔮\n\n- Refine the API to make it more understandable for someone who is already familiar with the mesa package. The goal is to provide a seamless experience for users transitioning to or incorporating mesa-frames.\n- Adding support for default mesa functions to ensure that the standard mesa functionality is preserved.\n- Adding GPU functionality (cuDF and Dask-cuDF).\n- Creating a decorator that will automatically vectorize an existing mesa model. This feature will allow users to easily tap into the performance enhancements that mesa-frames offers without significant code alterations.\n- Creating a unique class for AgentSet, independent of the backend implementation.\n\n## License\n\nCopyright 2024 Adam Amer, Project Mesa team and contributors\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nFor the full license text, see the [LICENSE](https://github.com/projectmesa/mesa-frames/blob/main/LICENSE) file in the GitHub repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectmesa%2Fmesa-frames","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectmesa%2Fmesa-frames","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectmesa%2Fmesa-frames/lists"}