Repast Simphony: Statecharts and Priority Scheduling for Complex Social Simulations

Repast Simphony: Statecharts and Scheduling for Complex Social Simulations

Introduction

Agent-based modeling (ABM) of social systems demands tools that can faithfully represent the rich, state-dependent behavior of human actors—behavior that shifts based on context, history, and interaction. Repast Simphony, developed at Argonne National Laboratory, addresses this challenge with a mature, Java-based ABM platform that combines a powerful statechart engine with a flexible, tick-based scheduler. While Mesa and NetLogo dominate introductory ABM courses, Repast Simphony is the platform of choice for large-scale, production-grade social simulations in defense, public health, and organizational research.

This article focuses on two of Repast Simphony's most distinctive capabilities: its statechart-driven agent behavior and its priority-based scheduling system—features that set it apart from simpler ABM frameworks.

Statechart-Driven Agent Behavior

Most ABM frameworks model agent behavior as a flat set of rules evaluated each tick. Repast Simphony takes a fundamentally different approach by allowing modelers to define agent behavior using UML-style statecharts directly within its graphical editor (the Repast Simphony IDE, built on Eclipse).

A statechart encodes an agent's lifecycle as a hierarchy of states and transitions:

• States represent stable behavioral modes (e.g., Susceptible, Exposed, Infectious, Recovered in an epidemiological model, or Employed, Job-Seeking, Retired in a labor-market model).
• Transitions are triggered by events, elapsed time, or evaluated conditions (guards).
• Hierarchical states allow complex behaviors to be nested—an Employed state might contain sub-states like Productive, OnLeave, and Stressed, each with their own transition logic.

This approach yields several practical advantages for social simulation:

1. Auditability: Statecharts are visual artifacts that domain experts (sociologists, policy analysts) can review and validate without reading Java code.
2. Correctness: State machines prevent impossible behavioral combinations—an agent cannot simultaneously be Employed and Retired.
3. Reusability: Statechart components can be shared across agent types, reducing duplication in multi-population models.

Repast Simphony compiles statecharts to efficient Java bytecode at model initialization, so there is no runtime interpretation overhead. In practice, models with hundreds of thousands of agents using statecharts run comfortably on a single workstation.

Priority-Based Scheduling

Social processes rarely unfold in a strict round-robin sequence. In a labor-market simulation, firms post vacancies before workers search; in a disease model, transmission events must precede recovery checks within the same tick. Repast Simphony's Schedule API handles this through a priority system that gives modelers fine-grained control over execution order.

Key scheduling concepts:

A typical pattern in a social influence model:

// Firms post vacancies first (priority 1.0)
schedule.schedule(ScheduleParameters.createRepeating(1, 1, 1.0),
    () -> firms.forEach(Firm::postVacancies));

// Workers search and match (priority 0.5 — runs after firms)
schedule.schedule(ScheduleParameters.createRepeating(1, 1, 0.5),
    () -> workers.forEach(Worker::searchAndApply));

// Statistics collection runs last
schedule.schedule(ScheduleParameters.createRepeating(1, 1, ScheduleParameters.LAST),
    dataCollector::collect);

This explicit ordering eliminates a common source of subtle bugs in social ABMs: unintended simultaneity, where the sequence of agent updates inadvertently drives results.

Batch Runs and Parameter Sweeps

Repast Simphony includes a batch runner that integrates with its parameter sweep XML configuration. Modelers define parameter ranges in a batch_params.xml file, and the runner executes all combinations across multiple CPU cores. Results are written to tab-separated files compatible with R, Python (pandas), and Excel.

For high-throughput sweeps on HPC clusters, Repast HPC—a C++ companion framework—can scale the same conceptual model to millions of agents across thousands of MPI ranks. The two frameworks share design philosophy, making migration from workstation to cluster relatively straightforward.

When to Choose Repast Simphony

Repast Simphony is the right tool when:

• Agent behavior is complex and state-dependent: Statecharts shine in models of organizational behavior, social stratification, or multi-stage life-course processes.
• Execution order matters: The priority scheduler prevents subtle ordering artifacts that plague simpler frameworks.
• Java integration is an asset: Repast Simphony agents can directly call any Java library—GIS toolkits (GeoTools), network analysis (JUNG), or machine-learning libraries (Weka).
• Auditability is required: Government and defense clients often require that model logic be reviewable by non-programmers; statechart diagrams satisfy this requirement.

It is less suitable for rapid prototyping or for teams without Java experience. For those use cases, Mesa (Python) or NetLogo remain better entry points.

Getting Started

• Official site & downloads: https://repast.github.io
• Documentation: Repast Simphony User's Guide
• Model library: Repast Model Library — includes worked examples in social dynamics, epidemiology, and organizational simulation
• Community forum: Repast Interest Group (Google Groups)
• Repast HPC (cluster scaling): https://repast.github.io/repast_hpc.html

Conclusion

Repast Simphony occupies a unique niche in the social ABM landscape: it combines the visual clarity of statechart-based behavior modeling with a rigorous, priority-aware scheduler and seamless Java ecosystem integration. For technical teams building production-grade social simulations—where correctness, auditability, and scalability are non-negotiable—Repast Simphony remains one of the most capable platforms available. Its learning curve is steeper than Python-based alternatives, but the investment pays dividends in model fidelity and long-term maintainability.