Data

Tools

Indexes

Applications

Experiments

Open Source Science

agent-torch

large population models

https://github.com/agenttorch/agenttorch

Science Score: 54.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ✓
    CITATION.cff file
    Found CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    1 of 5 committers (20.0%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (14.4%) to scientific vocabulary

Keywords

agent-based-modeling ai-agents-framework autograd differentiable-simulations scientific-computing
Last synced: 6 months ago · JSON representation ·

Repository

large population models

Basic Info
  • Host: GitHub
  • Owner: AgentTorch
  • License: other
  • Language: Jupyter Notebook
  • Default Branch: master
  • Homepage: https://lpm.media.mit.edu/docs
  • Size: 136 MB
Statistics
  • Stars: 400
  • Watchers: 10
  • Forks: 66
  • Open Issues: 9
  • Releases: 0
Topics
agent-based-modeling ai-agents-framework autograd differentiable-simulations scientific-computing
Created over 2 years ago · Last pushed 6 months ago
Metadata Files
Readme Contributing License Code of conduct Citation

readme.md

Large Population Models

making complexity simple
differentiable learning over millions of autonomous agents

Documentation Get in Touch Join Us

Overview

Many grand challenges like climate change and pandemics emerge from complex interactions of millions of individual decisions. While LLMs and agent simulations excel at individual behavior, they can't model these intricate societal dynamics. Enter Large Population Models (LPMs): a new paradigm to simulate millions of interacting entities, capturing behaviors at collective scale. It exponentially to understand the ripple effects of countless decisions.

AgentTorch, our open-source platform, makes building and running massive LPMs accessible. It's optimized for GPUs, allowing efficient simulation of large-scale systems. Think PyTorch, but for large-scale agent-based simulations. AgentTorch LPMs have four design principles:

  • Scalability: AgentTorch models can simulate large-scale populations in seconds on commodity hardware.
  • Differentiability: AgentTorch models can differentiate through simulations with stochastic dynamics and conditional interventions, enabling gradient-based optimization.
  • Composition: AgentTorch models can compose with deep neural networks (eg: LLMs), mechanistic simulators (eg: mitsuba) or other LPMs. This helps describe agent behavior using LLMs, calibrate simulation parameters and specify expressive interaction rules.
  • Generalization: AgentTorch helps simulate diverse ecosystems - humans in geospatial worlds, cells in anatomical worlds, autonomous avatars in digital worlds.

Our research is making an impact - winning awards at AI conferences and being used in real-world applications. Learn more here.

https://github.com/AgentTorch/AgentTorch/assets/13482350/4c3f9fa9-8bce-4ddb-907c-3ee4d62e7148

Installation

Install the most recent version from source using pip:

```sh

pip install git+https://github.com/agenttorch/agenttorch ```

Some models require extra dependencies that have to be installed separately. For more information regarding this, as well as the hardware the project has been run on, please see docs/install.md.

Alternately, the easiest way to install AgentTorch (v0.6.0) is from pypi: ```

pip install agent-torch ```

AgentTorch is meant to be used in a Python >=3.9 environment. If you have not installed Python 3.9, please do so first from python.org/downloads.

Getting Started

The following section depicts the usage of existing models and population data to run simulations on your machine. It also acts as a showcase of the Agent Torch API.

Executing a Simulation

```py

re-use existing models and population data easily

from agenttorch.examples.models import movement from agenttorch.populations import astoria from agent_torch.core.environment import envs

runner = envs.create(model=covid, population=astoria) # create simulation and init runner

simsteps = runner.config["simulationmetadata"]["numstepsperepisode"] numepisodes = runner.config["simulationmetadata"]["numepisodes"]

for epi in range(numepisodes): runner.step(simsteps)

runner.reset() # re-initializes the sim parameters for new episode

```

License

Copyright (c) 2023-2025 Ayush Chopra

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means: - You can freely use, modify, and distribute this software - If you use this software to provide services over a network, you must make your source code available to users - Any modifications or derivative works must also be licensed under AGPL-3.0 - You must give appropriate credit and indicate any changes made - For full terms, see LICENSE.md file in this repository

For commercial licensing options or inquiries about using this software in a proprietary product, please reach out to request a license wavier.

Guides and Tutorials

Understanding the Framework

A detailed explanation of the architecture of the Agent Torch framework can be found here.

Creating a Model

A tutorial on how to create a simple predator-prey model can be found in the tutorials/ folder.

Prompting Agent Behavior with LLM Archetypes

```py from agenttorch.core.llm.archetype import Archetype from agenttorch.core.llm.behavior import Behavior from agenttorch.core.llm.backend import LangchainLLM from agenttorch.populations import NYC userprompttemplate = "Your age is {age} {gender},{unemploymentrate} the number of COVID cases is {covidcases}."

Using Langchain to build LLM Agents

agentprofile = "You are a person living in NYC. Given some info about you and your surroundings, decide your willingness to work. Give answer as a single number between 0 and 1, only." llmlangchain = LangchainLLM( openaiapikey=OPENAIAPIKEY, agentprofile=agentprofile, model="gpt-3.5-turbo" )

Create an object of the Archetype class

n_arch is the number of archetypes to be created. This is used to calculate a distribution from which the outputs are then sampled.

archetype = Archetype(n_arch=7)

Create an object of the Behavior class

You have options to pass any of the above created llm objects to the behavior class

Specify the region for which the behavior is to be generated. This should be the name of any of the regions available in the populations folder.

earningbehavior = Behavior( archetype=archetype.llm(llm=llmlangchain, userprompt=userprompttemplate), region=NYC ) kwargs = { "month": "January", "year": "2020", "covidcases": 1200, "device": "cpu", "currentmemorydir": "/path-to-save-memory", "unemploymentrate": 0.05, } output = earningbehavior.sample(kwargs) ```

Contributing to Agent Torch

Thank you for your interest in contributing! You can contribute by reporting and fixing bugs in the framework or models, working on new features, creating new models, or by writing documentation for the project.

Take a look at the contributing guide for instructions on how to setup your environment, make changes to the codebase, and contribute them back to the project.

Owner

  • Name: AgentTorch
  • Login: AgentTorch
  • Kind: organization

Citation (CITATION.cff) 

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: Chopra
    given-names: Ayush
    orcid: https://orcid.org/0000-0002-4070-4139
title: "AgentTorch: Large Population Models"
version: 0.4.0
identifiers:
  - type: doi
    value: media.mit.edu/~ayushc/research/agency.pdf
date-released: 2024-05-28

GitHub Events

Total
  • Issues event: 9
  • Watch event: 184
  • Delete event: 5
  • Issue comment event: 12
  • Push event: 95
  • Pull request event: 24
  • Fork event: 27
  • Create event: 4
Last Year
  • Issues event: 9
  • Watch event: 184
  • Delete event: 5
  • Issue comment event: 12
  • Push event: 95
  • Pull request event: 24
  • Fork event: 27
  • Create event: 4

Committers

Last synced: about 2 years ago

All Time
  • Total Commits: 121
  • Total Committers: 5
  • Avg Commits per committer: 24.2
  • Development Distribution Score (DDS): 0.256
Past Year
  • Commits: 121
  • Committers: 5
  • Avg Commits per committer: 24.2
  • Development Distribution Score (DDS): 0.256
Top Committers
Name Email Commits
Ayush Chopra a****a@A****l 90
Ayush Chopra a****a@A****n 19
jk-cim j****n@g****m 6
Jayakumar Subramanian j****m@a****m 4
Ayush Chopra a****a@d****u 2
Committer Domains (Top 20 + Academic)
dhcp-10-29-229-173.dyn.mit.edu: 1 adobe.com: 1 ayushs-mbp.lan: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 16
  • Total pull requests: 39
  • Average time to close issues: about 1 month
  • Average time to close pull requests: 12 days
  • Total issue authors: 10
  • Total pull request authors: 9
  • Average comments per issue: 1.5
  • Average comments per pull request: 0.21
  • Merged pull requests: 30
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 4
  • Pull requests: 14
  • Average time to close issues: 12 days
  • Average time to close pull requests: 23 days
  • Issue authors: 3
  • Pull request authors: 6
  • Average comments per issue: 0.75
  • Average comments per pull request: 0.14
  • Merged pull requests: 8
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • gamemaker1 (4)
  • jzanetti (2)
  • mikeboensel (2)
  • sanchit-ahuja (1)
  • mindcrime (1)
  • KatoStevenMubiru (1)
  • abrahami (1)
  • ayushchopra96 (1)
  • janakan2466 (1)
  • facundoy (1)
Pull Request Authors
  • gamemaker1 (20)
  • sneakatyou (11)
  • ayushchopra96 (11)
  • arcAman07 (5)
  • hardik1408 (5)
  • LazyLogistics (3)
  • anna8murphy (2)
  • BombayBrownBoy09 (2)
  • dmehrab06 (1)
  • kaganhitit11 (1)
Top Labels
Issue Labels
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 176 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 9
  • Total maintainers: 2
pypi.org: agent-torch

large population models

  • Versions: 9
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 176 Last month
Rankings
Dependent packages count: 7.5%
Forks count: 30.2%
Average: 36.7%
Stargazers count: 39.1%
Dependent repos count: 69.8%
Maintainers (2)
ayushchopra gamemaker1
Last synced: 6 months ago

Dependencies

requirements.txt pypi
  • Jinja2 ==3.1.2
  • Markdown ==3.4.4
  • MarkupSafe ==2.1.3
  • Pillow ==9.5.0
  • PyYAML ==6.0
  • Pygments ==2.15.1
  • QtPy ==2.3.1
  • Send2Trash ==1.8.2
  • Werkzeug ==2.3.6
  • absl-py ==1.4.0
  • antlr4-python3-runtime ==4.9.3
  • anyio ==3.7.1
  • appnope ==0.1.3
  • argon2-cffi ==21.3.0
  • argon2-cffi-bindings ==21.2.0
  • asttokens ==2.2.1
  • attrs ==23.1.0
  • backcall ==0.2.0
  • beautifulsoup4 ==4.12.2
  • bleach ==6.0.0
  • branca ==0.6.0
  • cachetools ==5.3.1
  • census ==0.8.20
  • certifi ==2023.5.7
  • cffi ==1.15.1
  • charset-normalizer ==3.1.0
  • comm ==0.1.3
  • contourpy ==1.1.0
  • coverage ==7.2.7
  • cycler ==0.11.0
  • debugpy ==1.6.7
  • decorator ==5.1.1
  • defusedxml ==0.7.1
  • epiweeks ==2.2.0
  • et-xmlfile ==1.1.0
  • exceptiongroup ==1.1.2
  • executing ==1.2.0
  • fastjsonschema ==2.17.1
  • filelock ==3.12.2
  • folium ==0.14.0
  • fonttools ==4.40.0
  • google-auth ==2.22.0
  • google-auth-oauthlib ==1.0.0
  • grad-june ==0.1.8
  • h5py ==3.8.0
  • idna ==3.4
  • imageio ==2.31.1
  • importlib-metadata ==6.7.0
  • importlib-resources ==5.12.0
  • iniconfig ==2.0.0
  • ipdb ==0.13.13
  • ipykernel ==6.24.0
  • ipython ==8.12.2
  • ipython-genutils ==0.2.0
  • ipywidgets ==8.0.7
  • jax ==0.4.13
  • jaxlib ==0.4.13
  • jedi ==0.18.2
  • jellyfish ==0.11.2
  • joblib ==1.2.0
  • jsonschema ==4.18.0
  • jsonschema-specifications ==2023.6.1
  • jupyter ==1.0.0
  • jupyter-console ==6.6.3
  • jupyter-events ==0.6.3
  • jupyter_client ==8.3.0
  • jupyter_core ==5.3.1
  • jupyter_server ==2.7.0
  • jupyter_server_terminals ==0.4.4
  • jupyterlab-pygments ==0.2.2
  • jupyterlab-widgets ==3.0.8
  • kiwisolver ==1.4.4
  • matplotlib ==3.7.1
  • matplotlib-inline ==0.1.6
  • mistune ==3.0.1
  • ml-dtypes ==0.2.0
  • mpmath ==1.3.0
  • nbclassic ==1.0.0
  • nbclient ==0.8.0
  • nbconvert ==7.6.0
  • nbformat ==5.9.0
  • nest-asyncio ==1.5.6
  • networkx ==3.0
  • normflows ==1.6.2
  • notebook ==6.5.4
  • notebook_shim ==0.2.3
  • numpy ==1.24.3
  • oauthlib ==3.2.2
  • omegaconf ==2.3.0
  • openpyxl ==3.1.2
  • opt-einsum ==3.3.0
  • overrides ==7.3.1
  • packaging ==23.1
  • pandas ==1.5.0
  • pandocfilters ==1.5.0
  • parso ==0.8.3
  • pexpect ==4.8.0
  • pickleshare ==0.7.5
  • pkgutil_resolve_name ==1.3.10
  • platformdirs ==3.8.0
  • pluggy ==1.2.0
  • prometheus-client ==0.17.0
  • prompt-toolkit ==3.0.39
  • protobuf ==4.24.0
  • psutil ==5.9.5
  • ptyprocess ==0.7.0
  • pure-eval ==0.2.2
  • pyasn1 ==0.5.0
  • pyasn1-modules ==0.3.0
  • pycparser ==2.21
  • pyg-lib ==0.2.0
  • pyparsing ==3.1.0
  • pytest ==7.2.0
  • pytest-cov ==4.0.0
  • python-dateutil ==2.8.2
  • python-json-logger ==2.0.7
  • pytz ==2023.3
  • pyzmq ==25.1.0
  • qtconsole ==5.4.3
  • referencing ==0.29.1
  • requests ==2.31.0
  • requests-oauthlib ==1.3.1
  • rfc3339-validator ==0.1.4
  • rfc3986-validator ==0.1.1
  • rpds-py ==0.8.8
  • rsa ==4.9
  • scikit-learn ==1.2.2
  • scipy ==1.10.1
  • six ==1.16.0
  • sniffio ==1.3.0
  • soupsieve ==2.4.1
  • stack-data ==0.6.2
  • sympy ==1.12
  • tensorboard-data-server ==0.7.1
  • tensorboard-plugin-wit ==1.8.1
  • terminado ==0.17.1
  • threadpoolctl ==3.1.0
  • tinycss2 ==1.2.1
  • tomli ==2.0.1
  • torch ==2.0.0
  • torch-cluster ==1.6.1
  • torch-geometric ==2.3.0
  • torch-scatter ==2.1.1
  • torch-sparse ==0.6.17
  • torch-spline-conv ==1.2.2
  • tornado ==6.3.2
  • tqdm ==4.65.0
  • traitlets ==5.9.0
  • typing_extensions ==4.6.3
  • tzdata ==2023.3
  • urllib3 ==2.0.3
  • us ==3.1.1
  • wcwidth ==0.2.6
  • webencodings ==0.5.1
  • websocket-client ==1.6.1
  • wget ==3.2
  • widgetsnbextension ==4.0.8
  • zipp ==3.15.0
setup.py pypi