charwick/helipad

An agent-based modeling framework for Python with a shallow learning curve and powerful visualization capabilities.

Helipad

Helipad is an agent-based modeling framework for Python with powerful visualization capabilities and a shallow learning curve. Documentation and API reference can be found at helipad.dev.

Features

• ⚓️ A simple hook-based API makes it easy to build a model without worrying about the features you don’t need
• 📈 Interactive and live-updating visualizations, including time series, bar charts, networks, spatial, and an API for writing custom visualizations
• 👋🏻 Flexible parameter API allows parameter values to be set programmatically, adjusted manually from the control panel while the model is running, or shocked stochastically
• 🪐 Cross-platform and multimodal. Models can be written and run with a Tkinter GUI, in Jupyter notebooks, or without a GUI at all
• 🤹🏻‍♂️ Agents can barter, buy and sell with money, reproduce both haploid and polyploid, and more
• 🕺🏻 A variety of model types: sequential or random-activation models, matching models, multi-level models, network models, spatial models, and more

How to Use

You can install Helipad using either Pip or Conda, depending on your preferred package manager.

pip install helipad

conda install -c charwick helipad

Once installed, getting started with a model is very simple.

from helipad import *
heli = Helipad()

#Use the heli object to set up here

heli.launchCpanel()

The included bootstrap model contains a more detailed template, and the sample models exemplify various use cases. The documentation also includes a complete hook and function reference.

Requirements

Helipad requires Python 3.8 or higher. The following libraries are also required:

• Matplotlib for visualization
• Pandas for data collection
• NetworkX for network analysis and spatial visualization
• Optional: Jupyter, Ipywidgets, and ipympl to run Helipad in Jupyter notebooks
• Optional: Shapely for geospatial models.

How to Cite

If you use Helipad in your own research, please cite as follows:

Harwick, Cameron (2021). “Helipad: A Framework for Agent-Based Modeling in Python.” Working paper available at ssrn.com/abstract=3870501.

Version History

• 1.6: Geospatial models, agent scatterplot visualizer, new Agents and Edges containers
• 1.5: Polar grid spatial models, various spatial improvements
• 1.4: More consistent container API, localization, miscellaneous interface improvements
• 1.3: Allow mixing time series and other plots, display networks on spatial maps, goods API improvements
• 1.2: Extensible visualization API, events, performance profiling, Jupyterlab support
• 1.1: Virtual parameters, improved Jupyter flexibility, spatial pre-alpha, misc improvements
• 1.0: Jupyter integration, hook decorators, and separated control panel from plotting
• 0.7: Ability to output stackplots, parameter sweeps, and an updated parameter identification pattern
• 0.6: Support for multi-level models
• 0.5: Support for matching models, and the checkGrid class
• 0.4: Initial PyPI release

helipad's Issues

No module named 'ipympl'

I have installed helipad via pip on a Ubuntu system that has Anaconda installed. I cannot run any of the the samples. The same error is returned:

runfile('/home/zinvor/HelipadSpace/helipad-master/sample-models/Cities.py', wdir='/home/zinvor/HelipadSpace/helipad-master/sample-models')
Traceback (most recent call last):

  File "/home/zinvor/HelipadSpace/helipad-master/sample-models/Cities.py", line 186, in <module>
    viz = heli.useVisual(TimeSeries)

  File "/home/zinvor/.local/lib/python3.9/site-packages/helipad/model.py", line 356, in useVisual
    self.visual = viz(self) if viz is not None else None

  File "/home/zinvor/.local/lib/python3.9/site-packages/helipad/visualize.py", line 94, in __init__
    super().__init__(model)

  File "/home/zinvor/.local/lib/python3.9/site-packages/helipad/visualize.py", line 55, in __init__
    get_ipython().magic('matplotlib widget')

  File "/usr/lib/python3/dist-packages/IPython/core/interactiveshell.py", line 2434, in magic
    return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)

  File "/usr/lib/python3/dist-packages/IPython/core/interactiveshell.py", line 2336, in run_line_magic
    result = fn(*args, **kwargs)

  File "<decorator-gen-101>", line 2, in matplotlib

  File "/usr/lib/python3/dist-packages/IPython/core/magic.py", line 187, in <lambda>
    call = lambda f, *a, **k: f(*a, **k)

  File "/usr/lib/python3/dist-packages/IPython/core/magics/pylab.py", line 99, in matplotlib
    gui, backend = self.shell.enable_matplotlib(args.gui.lower() if isinstance(args.gui, str) else args.gui)

  File "/usr/lib/python3/dist-packages/IPython/core/interactiveshell.py", line 3515, in enable_matplotlib
    pt.activate_matplotlib(backend)

  File "/usr/lib/python3/dist-packages/IPython/core/pylabtools.py", line 322, in activate_matplotlib
    plt.switch_backend(backend)

  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 276, in switch_backend
    class backend_mod(matplotlib.backend_bases._Backend):

  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 277, in backend_mod
    locals().update(vars(importlib.import_module(backend_name)))

  File "/usr/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)

  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import

  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load

  File "<frozen importlib._bootstrap>", line 972, in _find_and_load_unlocked

  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed

  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import

  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load

  File "<frozen importlib._bootstrap>", line 984, in _find_and_load_unlocked

ModuleNotFoundError: No module named 'ipympl'

I installed imympl and pwm separately for good measure using pip but continue to see the same. What is producing this behavior?

docker with helipad

I want to start by saying how well thought out this framework in terms of productivity! I am having trouble getting up and running though and my issue might not be related to helipad per see. I use docker environment for my dev setup so I am not able to follow the typical examples that are listed here, do you have examples I can follow to render say via a webserver but using the same API?

Windows installer does not install 1.3

Using pip install -U helipad in a Windows system installs an old version of helipad that is broken (the misnamed graphics.py file that does not have the complete code that is included in visualize.py that I installed on my Ubuntu machine.

'NoneType' object has no attribute 'down' - PatchesRect.neighbors

Hi, I've started using the Helipad framework in anger recently - thank you for sharing it!

I'm currently trying to setup a non-wrapping grid with corners on, so I can call neighbors on a patch and get the Moore neighbourhood, but the combination of (wrap=False, corners=True) throws an error on setup - is this a supported combination?

Details

helipad: v1.6.1
Error: AttributeError: 'NoneType' object has no attribute 'down' (on: patch.left.down)
Line: spatial.py:165 (in PatchesRect.neighbors)
if self.corners: neighbors += [(patch.down.right, self.corners), (patch.left.down, self.corners)]

Code to Reproduce

import helipad
print(helipad.version)

from helipad import Helipad

heli = Helipad()
heli.name = 'Model Name'
heli.agents.order = 'random'
heli.stages = 1

heli.param('stopafter', 'debug_run')

@heli.event
def debug_run(model):
return model.t >= 20

mapPlot = heli.spatial(dim=(10,10), wrap=False, corners=False) # 1. OK
mapPlot = heli.spatial(dim=(10,10), wrap=True, corners=True) # 2. OK
mapPlot = heli.spatial(dim=(10,10), wrap=False, corners=True) # 3. Not OK

heli.launchVisual()