pram2mesa

Tools for translating PyPRAM's Probabilistic Relational Agent-Based Models to Mesa's Agent-Based Models

pram2mesa is a tool allowing a Probabilistic Relational Agent-Based Model (PRAM) to be translated into an Agent-Based Model (ABM). There are a few tradeoffs here:

• PRAMs work at a group level, while ABMs work at an individual agent level
• PRAMs have a more formal grammar, while ABMs are open-ended
• PRAMs are often much faster than ABMs, especially on very large populations

Core to this project, however, is a more theoretical purpose - demonstrating the interconnectedness of the two frameworks. While they are not the same, they are similar in many ways, allowing a tool like pram2mesa to exist. For more on comparing these frameworks, see the Media section.

Installation

Dependencies (For Translation)

• Python 3.8
• PyPRAM (must be installed separately; see below)
• astor
• autopep8
• dill
• iteround

Dependencies (For Running Translated ABMs)

• Mesa
• networkx (also a dependency of Mesa)
• dill

Setup

To install pram2mesa and its dependencies (except PyPRAM) simply use pip:

pip install pram2mesa

PyPRAM must be installed separately. See PyPRAM's Setup for details or just use:

pip install git+https://github.com/momacs/pram.git

Bear in mind that any computer running a translated ABM will (of course) need Mesa, but also dill.

Also, note that many of the samples require further dependencies to run, although most should be covered by installing PyPRAM.

Usage

Translating the PRAM

To translate a PRAM, first create the PRAM in a Python file or interpreter. Make sure that you do not run the PRAM. If you do, your new ABM will be setup with the ending configuration of the PRAM, not the beginning.

my_pram = (Simulation().
    add(...)
)

Ensure you have imported pram2mesa:

from pram2mesa import pram2mesa

Then simply supply your PRAM simulation and a nice file-safe name for your new files:

pram2mesa(my_pram, 'MyNewABM')

By default, pram2mesa will automatically clean the outputted Python files in an attempt to make them PEP8-compliant. To disable this, simply set autopep to False:

pram2mesa(my_pram, 'MyNewABM', autopep=False)

This will create a new directory called MyNewABM (or MyNewABM_1 if MyNewABM already exists; or MyNewABM_2 etc...) containing three Python files and three JSON files:

MyNewABM
+-- MyNewABMAgent.py
+-- MyNewABMGroups.json
+-- MyNewABMModel.py
+-- MyNewABMRules.json
+-- MyNewABMSites.json
+-- make_python_identifier.py

Running the ABM

Once you've created the files, you can instantiate your new model and run it as you normally would in Mesa. Make sure to keep all the files together; the Agent and Model classes need the JSON files during their initialization and use make_python_identifier.py as well.

from MyNewABMModel import MyNewABMModel

model = MyNewABMModel()

You will want to be sure to add a datacollector to the model to measure and graph outputs.

model.datacollector = DataCollector(...)

The Models that pram2mesa generates do not override run_model(). If you want, you can override it yourself in the Model class, or just use step():

for i in range(num_runs):
    model.step()

Then, you can extract graphs or other data from your datacollector. If you are unfamiliar with Mesa, you can look at their documentation which includes some well-written tutorials. The files named run_abm.py in each folder of this project's Samples directory may also be useful.

Acknowledgements

Thank you to my research mentors, Drs. Paul Cohen and Tomek Loboda, for their support on this project.

This project is supported by the Brackenridge Fellowship at the University of Pittsburgh Honors College.

License

This project is licensed under the MIT License.