Keywords: Agent-based Modeling; Scientific Computing; Evolutionary Optimization; Simulation Modeling; Multi-Objective Search

1 Summary↩︎

HEAS is a Python framework that connects agent-based simulation, evolutionary search, and scenario-based evaluation in a single reproducible pipeline. It is designed for researchers who study systems where local interactions produce system-level outcomes—ecosystems, organizations, markets, or regulatory environments—and who need to search over candidate strategies and compare them across uncertain scenarios. HEAS combines three modules: a hierarchy runtime for composing simulations from reusable process layers, an evolutionary tuner for single- or multi-objective search backed by DEAP, and a game module for evaluating strategies across scenario ensembles. Its central design principle is the metric contract: the same outcome function is shared by optimization, evaluation, and validation, so that different parts of an analysis cannot silently rank strategies by different quantities.

2 Statement of Need↩︎

Many research problems now require simulation plus search. Ecologists compare management rules under uncertain shocks; social scientists test institutional designs in heterogeneous populations; engineers tune systems with competing performance and robustness objectives. Agent-based and individual-based models are now used across disciplines to represent complex systems made up of autonomous entities [1]. These studies often need the same sequence of steps: build a model, run a search algorithm, evaluate candidate solutions across scenarios, and validate the final ranking.

Several mature tools cover parts of this workflow. Mesa [2] and NetLogo [3] provide strong foundations for building and exploring agent-based models, but leave multi-objective search and scenario comparison to project-specific scripts. AgentPy [4] adds parameter sweeps and Monte Carlo experiments in Python, but does not connect these to evolutionary optimization or tournament evaluation. DEAP [5] offers a flexible evolutionary computation toolkit, but requires the user to wire up simulation coupling, metric definitions, and scenario handling manually. EMA Workbench [6] focuses on exploratory modeling and robust decision making under deep uncertainty, emphasizing many-model experiments rather than multi-objective search over a single simulation hierarchy. OpenMOLE [7] provides workflow-based model exploration with high-performance computing support, targeting large-scale parameter space exploration rather than integrated simulation-optimization with shared metric definitions.

In each case, the connection between simulation, search, and evaluation is left to the user. A common pattern is to couple an agent-based model to NSGA-II [8], then re-score the resulting strategies in held-out scenarios. The optimizer, tournament evaluator, and validation code must compute the same outcome, yet this consistency is rarely enforced by the framework. Small differences in aggregation can change which strategy appears best without raising an error. HEAS is designed for researchers who need this end-to-end pipeline to be explicit, reproducible, and reusable across substantive domains.

3 State of the Field↩︎

Several frameworks address overlapping parts of the simulation-optimization pipeline. Table 1 summarizes how HEAS positions itself relative to existing tools.

Mesa [2] and NetLogo [3] are strong choices for building and exploring agent-based models, but they do not provide integrated multi-objective search or scenario-based evaluation. AgentPy [4] adds parameter sweeps and Monte Carlo experiments, but does not connect these to evolutionary optimization. DEAP [5] provides modular evolutionary algorithms; HEAS builds on DEAP rather than replacing it. EMA Workbench [6] supports exploratory modeling and robust decision making under deep uncertainty, but frames the workflow around many-model ensembles rather than multi-objective search within a single simulation hierarchy. OpenMOLE [7] orchestrates model exploration across high-performance computing resources, but does not enforce metric consistency across the optimization and evaluation stages.

HEAS contributes the missing integration layer: it connects hierarchical simulation, multi-objective search, scenario comparison, and a shared outcome definition in one framework. This makes HEAS useful to modelers who already know how to write a simulation, but need a more reliable bridge from simulation to search and comparative evaluation.

4 Software Design↩︎

HEAS has three modules that share a common data flow.

Hierarchy runtime. A stream is a user-defined process that reads from and writes to a shared simulation context. Streams are the basic units of composition: each one encapsulates a piece of domain logic (an ecological process, a firm, a regulator, or an ODE system) while remaining agnostic about how other streams behave. A layer groups streams that execute at the same temporal resolution. A hierarchy orders layers so that slower processes (e.g.seasonal dynamics) frame faster ones (e.g.daily agent decisions). The following example defines a stream and registers it in a two-layer hierarchy:

from heas.hierarchy.base import Stream, Context
from heas.hierarchy.orchestrator import (
    LayerSpec, StreamSpec, make_model_from_spec,
)

class Prey(Stream):
    def __init__(self, name, ctx, growth=0.05, **kw):
        super().__init__(name, ctx)
        self.growth = growth
        self.pop = 100.0

    def step(self):
        self.pop *= 1 + self.growth
        self.ctx.data["prey"] = self.pop

class Predator(Stream):
    def __init__(self, name, ctx, conversion=0.02, **kw):
        super().__init__(name, ctx)
        self.conversion = conversion

    def step(self):
        prey = self.ctx.data.get("prey", 0)
        self.ctx.data["predators"] = prey * self.conversion

spec = [
    LayerSpec(streams=[StreamSpec("prey", Prey, {"growth": 0.05})]),
    LayerSpec(streams=[StreamSpec("pred", Predator, {"conversion": 0.02})]),
]
model_factory = make_model_from_spec(spec, seed=42)

The hierarchy runtime executes layers in order, passing the shared context downstream. This separation means the same Prey stream can be reused in different hierarchies without modification.

Evolutionary tuner. The tuner connects DEAP-backed single- and multi-objective search (NSGA-II [8], MOEA/D [9]) to the hierarchy. A gene schema maps candidate parameter vectors to stream parameters, and a single metrics_episode() callable evaluates each episode. Deterministic seeding and parallel episode execution ensure reproducibility.

Game module. The game module evaluates candidate strategies across scenario ensembles and aggregates results using configurable voting rules (argmax, majority, Borda count, Copeland pairwise majority). It receives the same metrics_episode() used by the tuner, so rankings are guaranteed to be computed from the same outcome definition.

The main design trade-off is that HEAS keeps domain behavior in user-defined streams rather than imposing a single scientific model type. This is less prescriptive than a domain-specific simulator, but it lets the same workflow serve ecology, organizational analysis, policy design, and mathematical systems modeling. The metric contract is the corresponding constraint: users define the outcome once, and the same definition is passed through search, tournament evaluation, and validation.

5 Use Cases↩︎

HEAS has been applied to three reference studies that exercise different scientific logics while keeping the framework pipeline fixed. In each case, only the stream factories, gene schemas, scenarios, and episode metrics change; the hierarchy, search, tournament, and metric-contract interfaces remain the same. These studies demonstrate that the same framework surface supports both evolutionary search and held-out scenario evaluation without rewiring.

Ecological population management assembles a predator-prey arena with five streams, a 2-gene policy (risk, dispersal), and fragmentation \(\times\) shock scenarios. The evolutionary tuner ran NSGA-II with a population of 200 over 100 generations (10 episodes per evaluation, seed 42), converging to a Pareto front of 6 non-dominated solutions with hypervolume 1.098. The game module then evaluated the Pareto-optimal policies across a held-out 64-scenario ensemble; the majority-vote champion (risk=0.00, dispersal=1.00) won all 64 scenarios, with zero rank reversal between optimization ranking and tournament ranking. The same model-construction and evaluation surface supported both stages without modification.

Enterprise regulatory design reuses the same framework contracts for a four-layer regulatory arena with a 4-gene policy (tax_rate, audit_intensity, subsidy, penalty_rate). The tuner ran NSGA-II with a population of 300 over 150 generations (5 episodes per evaluation, seed 42), producing a large non-dominated set with hypervolume 4399.373. The champion policy (tax_rate=0.50, audit_intensity=0.17, subsidy=0.00, penalty_rate=0.20) achieves welfare=34.49 with variance=84.90. The domain logic changes substantially, but the search and tournament wiring do not: the same interfaces carry a different objective pair, different streams, and a larger scenario ensemble.

Wolf-Sheep ODE keeps the framework interfaces fixed while swapping the underlying model family from an agent simulation to a mean-field Lotka-Volterra system. The tuner used a population of 100 over 80 generations (10 episodes per evaluation, seed 42), converging to a Pareto front of 2 solutions with hypervolume 5.498. This case is the clearest software portability test: the 4-layer arena required no additional framework-side coupling beyond a new metrics_episode() implementation, confirming that the contract extends to a non-Mesa, non-stochastic system with the same HEAS pipeline.

6 Availability and Reproducibility↩︎

HEAS includes a command-line interface for batch runs and a browser-based playground at https://ryzhanghason.github.io/heas/ for configuring simulations, inspecting Pareto fronts, and exporting publication bundles without a backend server. The repository includes a CONTRIBUTING.md guide, a CODE_OF_CONDUCT.md, release metadata, and automated tests. These materials are intended to make the software inspectable by reviewers and usable by researchers outside the original development team.

7 Research Impact Statement↩︎

HEAS has been developed as research software rather than as a one-off script. It is packaged for installation with pip install heas, released under the LGPL-3.0 license, documented with examples and a browser playground, and covered by 56 functional tests. Source code is available at https://github.com/ryZhangHason/heas.

8 Acknowledgements↩︎

The authors acknowledge the open-source simulation and optimization communities whose tools and documentation informed HEAS, especially Mesa, NetLogo, AgentPy, DEAP, EMA Workbench, and OpenMOLE.

9 AI Usage Disclosure↩︎

The authors used AI-assisted tools for code development, refactoring support and test scaffolding. Human authors reviewed, edited, and validated AI-assisted outputs, and the core problem framing, software architecture, research design, and final scholarly claims remain the responsibility of the authors.

References↩︎