xnlogo 0.1.0

Python-to-NetLogo transpiler and integration toolkit

xnLogo

A Python-to-NetLogo transpiler and integration toolkit for agent-based modeling.

Overview

xnLogo enables researchers and developers to write agent-based simulations in Python and compile them to NetLogo. The system provides transpilation (Python to NetLogo code generation) and runtime integration (controlling NetLogo models from Python).

Write models using Python's syntax and tooling, then execute them in NetLogo's simulation environment.

Installation

pip install xnlogo

Requirements:

• Python 3.10 or later
• NetLogo 7.0 or later (for running compiled models)
• Java 17 or later (for runtime integration)

Quick Start

Create counter.py:

from xnlogo import agent

@agent
class Counter:
    count: int = 0
    
    def increment(self):
        self.count = self.count + 1
    
    def reset(self):
        self.count = 0

Compile to NetLogo:

xnlogo build counter.py

This generates counter.nlogox which can be opened in NetLogo 7.

Features

• Agent-based modeling - Define agents with state and behaviors using Python classes
• Semantic validation - Detect unsupported constructs before compilation
• NetLogo 7 support - Generate .nlogox files (legacy .nlogo also supported)
• Runtime integration - Run simulations and collect telemetry from Python
• Type annotations - Use Python type hints for agent state fields
• CLI tools - Complete command-line interface for validation, compilation, and execution

Command-Line Interface

Command	Purpose
xnlogo check <path>	Validate Python code without compiling
xnlogo build <path>	Compile to NetLogo format
xnlogo run <path>	Execute simulation in NetLogo
xnlogo export <path>	Export telemetry data to CSV/JSON

Example: Flocking Model

from xnlogo import agent

@agent
class Boid:
    speed: float = 1.0
    heading: float = 0.0
    
    def setup(self):
        self.speed = 0.5 + self.random_float(0.5)
        self.heading = self.random_float(360)
    
    def flock(self):
        neighbors = self.nearby_agents(self, Boid, radius=3)
        if neighbors:
            avg_heading = sum(n.heading for n in neighbors) / len(neighbors)
            turn = (avg_heading - self.heading) * 0.05
            self.heading = self.heading + turn
        self.forward(self.speed)

Compile and run:

xnlogo build flocking.py
xnlogo run flocking.py --ticks 100

Runtime Integration

Execute models and collect data from Python:

from pathlib import Path
from xnlogo.runtime.session import NetLogoSession, SessionConfig

config = SessionConfig(netlogo_home=Path("/Applications/NetLogo 7.0.0"))

with NetLogoSession(config) as session:
    session.load_model(Path("flocking.nlogox"))
    session.command("setup")
    session.repeat("go", 100)
    
    population = session.report("count turtles")
    avg_speed = session.report("mean [speed] of turtles")

Documentation

• User Guide - Detailed usage and examples
• Architecture - System design and internals
• Translation Rules - Python to NetLogo conversion reference
• Python-NetLogo Compatibility - Feature compatibility matrix

Project Status

xnLogo is under active development. Core features are stable:

• Agent parsing and compilation
• Python-to-NetLogo statement translation
• Semantic validation
• Runtime integration
• NetLogo 7 .nlogox output

Advanced NetLogo features (breeds, links, extensions) are in progress.

License

MIT License

Acknowledgments

Built on NetLogo by Uri Wilensky and the CCL at Northwestern University.