(1) Overview
Introduction
Honey bees (Apis mellifera L.) provide critical pollination services for both natural and agricultural systems, with $50 billion USD of crops completely dependent on pollination in the United States alone [1]. However, honey bees are facing a wide range of stressors resulting in elevated colony failure rates including climate change [2], pathogens [3], habitat loss and decreased food availability [4], and exposure to pesticides [5, 6].
Agent-based colony simulation models, such as the BeePop+ model developed by US EPA and USDA [7], offer the opportunity to explore how these interacting stressors may impact colony dynamics such as colony size, honey production and overwintering success across a variety of scenarios. Agent-based models can also produce emergent behavior that is typical of complex systems such as eusocial bee colonies. These models can also be used to predict colony-level pesticide impacts based on toxicological information gathered from laboratory tests on single bees.
The BeePop+ colony simulation model was published in 2022 by the US EPA and USDA to support the pesticide risk assessment process [7]. BeePop+ was an update to the existing USDA model VarroaPop [8], which added pesticide exposure and effects modeling capabilities. BeePop+ is an agent-based model that simulates dynamics such as queen egg-laying behavior, development and food consumption of brood and adult bees, and foraging activity patterns based on weather. Queens are simulated as individual agents, while other castes are simulated as collective ‘day-cohort’ agents. Pesticide exposure occurs via collection of contaminated pollen and nectar, with pesticide residue levels set by the user via a daily residue file. Interactions with parasitic Varroa destructor mites can also be simulated simultaneously. A sensitivity analysis of BeePop+ input parameters is available in Kuan et al. (2018) [9]. The pybeepop+ package for Python provides a convenient and modern interface for running BeePop+ that facilitates greater adoption and application by the scientific, academic, conservation, and industry community.
Implementation and architecture
The pybeepop+ Python package wraps the C++-based BeePop+ model in an easy-to-use application programming interface (API). Previously, the BeePop+ model was only accessible via built-in C++ interface functions [10], or a web-based graphical user interface that lacks the pesticide exposure and effects modules [11].
The pybeepop+ package uses Python’s ctypes library to provide seamless communication between Python and the compiled C++ BeePop+ shared library. This approach allows for direct library loading without requiring additional wrapper languages or binding generators. The package loads the BeePop+ shared library (.dll on Windows, .so on Linux) directly using ctypes.CDLL(), establishing a connection to the compiled C++ code. Function call marshaling is handled through ctypes, which automatically converts between Python and C data types. Simple data types like integers and doubles are passed using ctypes primitives (ctypes.c_int, ctypes.c_double), while strings are converted to byte arrays using a utility function that creates C-compatible character pointer arrays. Complex data structures are passed using pointer arrays. Results from the C++ library are retrieved through pointer references, decoded from bytes to Python strings, and then parsed into pandas DataFrames.
The pybeepop+ package is designed to provide a fast and user-friendly method for running a full-featured version of BeePop+ in Python, a programming language that is widely used in scientific settings. It also allows for rapid modification of BeePop+ parameter values and input files, which enables automated, high-throughput analyses that require many hundreds or thousands of model runs. Model results are output as pandas [12] DataFrame objects (or JSON strings), which facilitates downstream analysis and plotting.
The pybeepop+ package includes pre-compiled binary versions of BeePop+ for Windows (64-bit) and Linux (64-bit). The package will try to detect your platform and architecture and use the correct library binary. For Linux, a wide range of distributions are supported with the ‘manylinux’ and ‘musllinux’ standards. Alternately, BeePop+ can be built from source on any Linux system, and pybeepop+ can connect to an alternate shared library binary specified by the user.
An early version of the pybeepop+ package was used to fit BeePop+ to empirical data from a honey bee colony feeding study using Bayesian inference [13]. The Python-native interface of pybeepop+ allowed for integration with the pyABC package [14] for sampling, and dask [15] for parallelization of over 10 million individual model runs. The pybeepop+ package is currently being used by the US EPA to fit BeePop+ to a range of colony feeding study datasets across several pesticides to explore the generalizability of the model.
Installing pybeepop+ is simple using the pip package manager in Python:
pip install pybeepop-plus
Following installation, the model object can be imported and instantiated from within Python:
from pybeepop import PyBeePop
beepop = PyBeePop()
To run the model, users must first define the daily weather conditions for each day of the simulation via a comma-delimited weather file that specifies maximum, minimum and average temperature (°C), wind speed (m/s), and rainfall (mm). Optionally, pesticide residues in foraged nectar and pollen can also be specified for each simulation day through a separate comma-delimited file. More details on the required weather and pesticide residue file formats are available in the package documentation.
# load weather file by its path
weather = ‘/home/example/test_weather.txt’
beepop.load_weather(weather)
# load pesticide residue file by its path (optional)
pesticide_file = ‘/home/example/pesticide_residues.txt’
beepop.load_contamination_file(pesticide_file)
BeePop+ model parameters can then be set using a Python dictionary consisting of parameter names and values. Parameter names are validated, and invalid names will produce an error with feedback to the user. Parameters that are not defined remain at the BeePop+ default values.
# define a dictionary of BeePop+ parameters
params = {“ICWorkerAdults”: 10000, “ICWorkerBrood”: 8000,
“SimStart”: “04/13/2015”, “SimEnd”: “09/15/2015”,
“AIAdultLD50”: 0.04}
beepop.set_parameters(params)
Once all required and optional inputs and parameters are defined, the user can run the model and save the output as a pandas DataFrame (default) or JSON string (Table 1). The pybeepop+ package can also produce a time series plot of the simulation displaying multiple output columns selected by the user (Figure 1).
Table 1
Abbreviated example output from a pybeepop+ model run. The full pandas DataFrame contains 44 columns of model outputs.
| DATE | COLONY SIZE | ADULT DRONES | ADULT WORKERS | FORAGERS |
|---|---|---|---|---|
| Initial | 10000 | 0 | 6762 | 3238 |
| 4/13/2015 | 10615 | 0 | 7055 | 3560 |
| 4/14/2015 | 10908 | 0 | 7348 | 3560 |
| 4/15/2015 | 11523 | 0 | 7641 | 3882 |
| 4/16/2015 | 12138 | 0 | 7934 | 4204 |
| 4/17/2015 | 12431 | 0 | 8227 | 4204 |
| 4/18/2015 | 12724 | 0 | 8520 | 4204 |
| … | ||||
| 9/12/2015 | 55973 | 921 | 31651 | 23401 |
| 9/13/2015 | 55924 | 907 | 31488 | 23529 |
| 9/14/2015 | 55854 | 892 | 31329 | 23633 |
Figure 1
Example of a model run time series plot produced by the plot_output() function within pybeepop+.
results = beepop.run_model()
print(results)
results.to_csv(‘example_beepop_results.csv’,
index=False)
columns_to_plot = [
“Colony Size”,
“Adult Workers”,
“Capped Worker Brood”,
“Worker Larvae”,
“Worker Eggs”,
]
beepop.plot_output(columns_to_plot)
Quality control
Unit tests and functional tests are implemented with the pytest framework and are automatically triggered via GitHub continuous integration upon pushes, pull requests, and releases on the ‘main’ branch. As of publication, 21 unit and functional tests are implemented, representing 82% test coverage across the code base. Test coverage reports are automatically posted on the project’s documentation page at https://usepa.github.io/pybeepop/. Users can run the tests locally by cloning the pybeepop+ GitHub repository and calling pytest on the tests directory. The repository also contains example input files and an example Jupyter notebook that can be run to quickly verify that the package is functioning properly. The following is a minimal working example that runs without requiring input files:
from pybeepop import PyBeePop
import tempfile
import os
# Create minimal synthetic weather data
weather_data = “““04/01/2023, 20.0, 10.0, 15.0, 3.0, 0.0, 12.0
04/02/2023, 22.0, 12.0, 17.0, 2.5, 0.0, 12.1
04/03/2023, 21.0, 11.0, 16.0, 3.2, 2.0, 12.2
04/04/2023, 19.0, 9.0, 14.0, 2.8, 0.0, 12.3
04/05/2023, 23.0, 13.0, 18.0, 2.1, 0.0, 12.4”””
# Write to temporary file
with tempfile.NamedTemporaryFile(mode=‘w’, suffix=‘.txt’, delete=False) as f:
f.write(weather_data)
temp_weather_file = f.name
try:
# Create BeePop+ instance and run simulation
beepop = PyBeePop()
beepop.set_parameters({
“ICWorkerAdults”: 10000,
“ICWorkerBrood”: 5000,
“SimStart”: “04/01/2023”,
“SimEnd”: “04/05/2023”
})
beepop.load_weather(temp_weather_file)
# Run model and display results
results = beepop.run_model()
print(results[[‘Date’, ‘Colony Size’, ‘Adult Workers’]].head())
finally:
# Clean up temporary file
os.unlink(temp_weather_file)
(2) Availability
Operating system
Windows (64-bit) and Linux (64-bit).
Programming language
Python version 3.6 or above.
Additional system requirements
No additional requirements.
Dependencies
C++ runtime libraries:
Windows - Microsoft Visual C++ 2015 or newer
Linux – glibc version 2.4 or newer
Python packages:
pandas > 2.0.0
matplotlib > 3.1
List of contributors
N/A
Software location
Archive
Name: Zenodo
Persistent identifier: DOI: 10.5281/zenodo.14548642
Licence: MIT
Publisher: Jeffrey Minucci
Version published: 0.1.3
Date published: 6/25/2025
Code repository
Language
English
(3) Reuse potential
The pybeepop+ package makes the full-featured BeePop+ honey bee colony model widely available to researchers, regulators and the conservation community for the first time, as it streamlines model installation and provides a user-friendly API. The US EPA is currently using pybeepop+ to fit the BeePop+ model to a wide range of pesticide colony feeding studies and assess the ability of the model to predict impacts from various active ingredients. There are also ongoing efforts at the agency to expand pybeepop+ with standardized simulation scenarios for various key crops, which will facilitate use of BeePop+ in higher-tier pollinator risk assessments. Future development directions for the package include additional plotting capabilities, a batch mode that allows for multiple runs with varying initial parameter values, and a probabilistic mode that samples initial parameters based on a specified range or distribution.
The pybeepop+ package is actively maintained as an open-source project on GitHub by US EPA staff. Anyone interested in contributing to pybeepop+ can interact with the project on GitHub by submitting pull requests with new features. The project uses GitHub Issues (https://github.com/usepa/pybeepop/issues) as the primary mechanism for community support and collaboration. Users can request support, submit detailed bug reports to help improve the software, propose new functionality or enhancements to the package, and share use cases. The maintainers actively monitor and respond to issues, providing technical assistance and guidance. This centralized support system ensures that all discussions are publicly visible and searchable, creating a knowledge base that benefits the user community.
Acknowledgements
We thank K. Garber, G. DeGrandi-Hoffman, R. Curry, D. Dawson, C. Douglass, J. Milone, and S.T. Purucker for their contributions to the underlying BeePop+ model and their feedback on pybeepop+ features. We thank D. Smith, E.A. Paulukonis, C. Strauch, and E. Huang for helpful feedback on the Python package and manuscript. This paper has been reviewed in accordance with Agency policy and approved for publication. The views expressed in this article are those of the authors and do not necessarily represent the views or policies of the US EPA. Any mention of trade names, products, or services does not imply an endorsement by the US EPA.
Competing Interests
The author has no competing interests to declare.