abm-framework

ABM Framework

A service-centric agent-based modeling framework for social systems and public health applications.

Features

✨ Service-Centric Architecture - Agents are data containers, services contain all behavior logic 🔄 Event-Driven - Flexible event scheduling for complex interactions 🕸️ Network-Based - Built-in support for social networks using NetworkX 🎯 Zero Circular Dependencies - Clean, maintainable architecture 📊 Research-Ready - Designed for epidemiology and public health research 🚀 Extensible - Easy to add custom agents, services, and behaviors

Installation

pip install abm-framework

Quick Example

from layer1_core.entities.agent import Agent
from layer1_core.managers.service import Service
from layer2_simulation.world_builder import WorldBuilder
from layer2_simulation.single_runner import SingleRunner
from layer1_core.managers.schedule import Schedule

# 1. Define agents (data only)
class Student(Agent):
    def __init__(self, agent_id, mood=0.5):
        super().__init__(agent_id)
        self.mood = mood

# 2. Define services (behavior logic)
class InteractionService(Service):
    def interact(self, student1, student2):
        student1.mood += 0.1
        student2.mood += 0.1

    def schedule_interactions(self, schedule, students, steps):
        for step in range(1, steps):
            s1, s2 = random.sample(students, 2)
            schedule.add_event(
                step=step,
                event=lambda: self.interact(s1, s2)
            )

# 3. Build world
class SchoolWorld(WorldBuilder):
    def __init__(self, params):
        super().__init__(params)
        self.schedule = Schedule()

        # Register services
        self.interaction_service = InteractionService()
        self.services.register(self.interaction_service)

        # Create agents
        self.students = [Student(f"s{i}") for i in range(params['n_students'])]

    def setup_events(self):
        self.interaction_service.schedule_interactions(
            self.schedule, self.students, 1000
        )

# 4. Run simulation
world = SchoolWorld({'n_students': 50})
world.setup_events()

runner = SingleRunner(world)
runner.run(stopping_condition=lambda s: s.get_current_step() >= 1000)

print(f"Average mood: {sum(s.mood for s in world.students) / len(world.students):.2f}")

Architecture

The framework follows a layered service-centric architecture:

Core Principles

1. Agents are data containers - Hold state (age, mood, etc.) with no behavior methods
2. Services contain all behavior - All logic, interactions, and computations
3. Services schedule events - Only services add events to the schedule
4. Zero circular dependencies - Clean imports and dependencies

Layers

• Layer 1: Core - Agents, Services, Networks, Schedules
• Layer 2: Simulation - WorldBuilder, SingleRunner, Parameters
• Layer 3: Parallel - Batch execution (planned)
• Layer 4: Analysis - Parameter sweeps, calibration, workflows (planned)

Documentation

• 📘 Quickstart Guide
• 🏗️ Service-Centric Architecture
• ⚡ Quick Reference
• 🏫 School Demo - Complete example with students, teachers, friendships

Use Cases

Perfect for modeling:

• 🏥 Disease transmission and interventions
• 🏫 Educational systems and outcomes
• 🏘️ Neighborhood effects and segregation
• 👥 Social network dynamics
• 📊 Policy impact analysis

Requirements

• Python 3.9+
• NetworkX 3.0+

Contributing

Contributions welcome! Please read our contributing guidelines.

Citation

If you use this framework in your research, please cite:

@software{abm_framework_2026,
  title = {ABM Framework: Service-Centric Agent-Based Modeling},
  author = {Your Name},
  year = {2026},
  url = {https://github.com/yourusername/abm-framework}
}

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Note: This is an early-stage framework under active development. APIs may change.