pybeepop+ 🐝

About

pybeepop+ provides a Python interface to BeePop+, an agent-based model for simulating honey bee (Apis mellifera L.) colony dynamics. The model is designed for ecological risk assessment and research applications.

References:

Minucci, J. (2025). “pybeepop+: A Python Interface for the BeePop+ Honey Bee Colony Model.” Journal of Open Research Software, 13(1). https://doi.org/10.5334/jors.550

Garber, K., et al. (2022). “Simulating the Effects of Pesticides on Honey Bee (Apis mellifera L.) Colonies with BeePop+.” Ecologies, 3(3), 22. https://doi.org/10.3390/ecologies3030022

Package author: Jeffrey Minucci, U.S. Environmental Protection Agency

Table of Contents

• Requirements
• Choosing a Simulation Engine
• Quick Start Guide
• Minimal Working Example
• Example Notebook
• API Documentation
• Compiling BeePop+ on Linux
• Contributing to pybeepop+

Requirements

Core Dependencies (All Engines)

C++ Engine Requirements (Optional)

Tip: If you can’t meet these requirements, use the Python engine instead.

Supported Platforms

• Windows 64-bit
• Linux 64-bit
• macOS (Python engine only)

Platform-Specific Dependencies

Windows
- Microsoft Visual C++ Redistributable 2015-2022

Linux
- The bundled library supports manylinux/musllinux standards (musllinux via wheel only) - If you encounter loading errors, see Compiling BeePop+ on Linux - Source code: github.com/quanted/vpoplib

macOS - Only the Python engine is supported (C++ engine unavailable due to architecture compatibility issues)

Choosing a Simulation Engine

pybeepop+ supports two simulation engines: - C++ engine (default on Windows/Linux): The original published C++ implementation, requires compiled binaries - Python engine (default on macOS): A pure Python port for improved portability and easier code inspection, with no binary dependencies

Both engines produce nearly identical results, with only negligible differences in some floating-point calculations.

Note: On macOS, only the Python engine is available. The C++ engine is not supported due to architecture-specific compatibility issues.

Selecting an Engine

Specify the engine when creating a PyBeePop instance using the engine parameter:

from pybeepop import PyBeePop

# Automatic selection (default) - tries C++ first, falls back to Python
beepop = PyBeePop(engine='auto')

# Explicitly use C++ engine
beepop = PyBeePop(engine='cpp')

# Explicitly use Python engine  
beepop = PyBeePop(engine='python')

Quick Start Guide

Installation

pip install pybeepop-plus

Basic Usage

from pybeepop import PyBeePop

# 1. Create a BeePop+ instance (auto-selects best available engine)
beepop = PyBeePop()

# 2. Configure simulation parameters
params = {
    "ICWorkerAdults": 10000,
    "ICWorkerBrood": 8000,
    "SimStart": "04/13/2015",
    "SimEnd": "09/15/2015",
    "AIAdultLD50": 0.04
}
beepop.set_parameters(params)

# 3. Load weather data
beepop.load_weather('path/to/weather.txt')

# 4. (Optional) Load pesticide exposure data
beepop.load_residue_file('path/to/residues.txt')

# 5. Run simulation
results = beepop.run_model()
print(results)

Working with Results

# Get results as DataFrame
results_df = beepop.get_output()

# Get results as JSON
results_json = beepop.get_output(json_str=True)

# Visualize time series
beepop.plot_output()  # default columns
beepop.plot_output(["Colony Size", "Adult Workers"])  # custom columns

Updating Parameters Between Runs

# Update specific parameters (others remain unchanged)
beepop.set_parameters({"ICWorkerAdults": 22200, "InitColPollen": 4000})
results_updated = beepop.run_model()

Loading Parameters from File

# Parameters file format (key=value per line)
# Example: my_parameters.txt
#   RQEggLayDelay=10
#   RQReQueenDate=06/25/2015
#   RQEnableReQueen=False

beepop.load_parameter_file('my_parameters.txt')
params = beepop.get_parameters()

Additional Resources

• Parameter Reference: Exposed BeePop+ Parameters
• Weather File Format: docs/weather_readme.txt
• Residue File Format: docs/residue_file_readme.txt
• Example Files: example_data/

Note: Parameters not explicitly set will use BeePop+ default values. See the publication for details.

Minimal Working Example

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)

Example Notebook

A Jupyter notebook demonstrating pybeepop+ usage is available here:

→ pybeepop_example.ipynb

API Documentation

Complete API reference and usage guide:

→ https://usepa.github.io/pybeepop/

Compiling BeePop+ on Linux

Build Requirements

• cmake ≥ 3.2
• gcc or g++

Compilation Steps

# 1. Clone the BeePop+ repository
git clone https://github.com/quanted/VPopLib.git
cd VPopLib

# 2. Create and enter build directory
mkdir build
cd build

# 3. Build the shared library
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON ..
cmake --build . --config Release

Using Your Custom Build

The compiled library (liblibvpop.so) will be in the build/ directory. Use it with pybeepop:

from pybeepop import PyBeePop

# Pass the path to your compiled library
beepop = PyBeePop(lib_file='/home/example/liblibvpop.so')

Contributing

We welcome community contributions. Here’s how you can help:

Code Contributions

Fork the repository and submit pull requests. All submissions will be reviewed by maintainers.

Bug Reports

Found a bug? Please open an issue with: - Description of the problem - Steps to reproduce - Expected vs. actual behavior - System information (OS, Python version, etc.)

Support & Questions

Need help? Open an issue on GitHub.

Disclaimer

This software is provided “as is” without warranty of any kind. The views expressed in this package are those of the authors and do not necessarily represent the views or policies of the U.S. Environmental Protection Agency.