The SuperScript agent-based model + optimisers

Mesa-based agent-based model of team formation in project-based organisations, plus the team-allocation optimisers compared in the article.

---

superscript-abm

SuperScript is an agent-based model (ABM), built on Mesa, of team formation and allocation in a project-based organisation: workers with heterogeneous skills are assembled into teams for incoming projects, and project success probabilities depend on team composition. This repository contains the ABM itself plus the team allocation optimisers used in the accompanying article (Random, Greedy, GRASP, MILP ["linear"], hierarchical reinforcement learning [RLD2/RLD1] and an Ensemble of methods), implemented in superscript_abm/optimisation_decoupled.py.

It was split out of the original SuperScript repository so it can be used as a submodule by other projects. In particular it is a submodule of OptimizationExperiments — the top-level repository with the article experiments and the reproduction instructions; start there if your goal is to reproduce the article results.

Repository layout

• superscript_abm/ — the model package.
  • model.py — SuperScriptModel (Mesa model; entry point for programmatic use).
  • optimisation_decoupled.py — optimisers (OptimiserFactory), state-space representation, runners (series/parallel), filters.
  • config.yaml — the single live configuration file: all model parameters and per-optimiser hyperparameters (see below).
  • config.py — DEPRECATED (kept for reference only; do not edit).
  • server.py, mesa_config.py — Mesa browser visualisation.
• example_run.py — demonstration script: runs a seeded 100-worker / 100-timestep simulation with the GRASP optimiser, saves tracking output to training_data/example_grasp_team_allocation/, and verifies seeded reproducibility (including ABM restart via copy_existing_abm()).
• run.py — launches the Mesa visual server (equivalent to mesa runserver).
• test_data/ — pickled ABM states: test_dataset/ and validation_dataset/ (100 states each) used by the optimisation experiments and tests.
• tests/ — unit tests for the optimisers (python -m pytest tests/ or python -m unittest).
• parameter_tuning/ — GRASP hyperparameter grid-search script.
• models/ — the ML-filter random forest (rf_trained_cv.joblib) and the four trained RLD2 PPO policies (models/RLD2*), the latter shipped via Git LFS — see "Trained RL models" below.
• Submodules: gym-superscript (Gymnasium RL environments wrapping this ABM) and rl-baselines3-zoo (fork of the SB3 training zoo used to train the RL policies).

Configuration

All configuration lives in superscript_abm/config.yaml (loaded with confuse; any key can be overridden as a SuperScriptModel constructor kwarg or by passing a custom config_file). It contains the model parameters plus, under optimisers:, the hyperparameters for each optimiser (random, greedy, grasp, linear [MILP objective coefficients and time limit], basin, exhaustive_search, exhaustive_greedy, reinforcement_learning [trained model, determinism, repeat counts], ensemble), runners: (series/parallel, num_proc) and filters: (skill_threshold / first_n / ml_filter / random).

Valid optimiser_type values (see OptimiserFactory.get_optimiser): random, greedy, grasp, linear, exhaustive_search, exhaustive_greedy, reinforcement_learning, greedy_rl, ensemble, basin.

Installation

Requires Python 3.10. The two submodules must be installed into the same environment (the RL stack is imported at module load even for non-RL optimisers, so this is not optional).

This repository ships the trained RL policies via Git LFS; install it before cloning, or models/RLD2*/best_model.zip come down as pointer files instead of weights:

sudo apt-get install git-lfs        # see https://git-lfs.com for other platforms
git lfs install                     # one-time
git clone --recursive https://github.com/Superscriptus/superscript-abm-public.git
cd superscript-abm-public
# cloned before installing Git LFS? run:  git lfs pull
python3.10 -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate.bat
python -m pip install --upgrade pip wheel
pip install -r requirements.txt
pip install gymnasium torch stable-baselines3   # see version notes below
pip install -e gym-superscript
pip install -e rl-baselines3-zoo
pip install -e .

Version notes. The environment in which the article results were produced and verified is pinned in article_requirements.txt of the top-level OptimizationExperiments repository (numpy 1.26.4, Mesa 0.9.0, gymnasium 0.29.1, stable-baselines3 2.3.2, PySCIPOpt 5.1.1; torch 1.13.1 installed separately). Prefer those pins for reproduction. Be aware of two known inconsistencies in this snapshot, kept as-is: requirements.txt pins Mesa==1.1.0 while setup.py (and the verified article environment) use Mesa==0.9.0; and setup.yml (conda spec) pins pyscipopt 4.* while the article environment used 5.1.1.

The MILP ("linear") optimiser needs SCIP via PySCIPOpt.

Trained RL models (required to run)

SuperScriptModel loads the pre-trained RLD2 PPO agent named by optimisers.reinforcement_learning.trained_model in config.yaml at construction time — every simulation, whichever optimiser you select. The four RLD2 policies used by the article are shipped here via Git LFS under models/ (each directory holds best_model.zip plus rl_zoo3 config.yml/args.yml; training-time monitor.csv/evaluations.npz logs are omitted as they are not needed to load or run):

• RLD2-v3.106-linear_1, RLD2-v3.106-nonlinear_2 — 100-worker (unfiltered) standalone RLD2, linear and nonlinear objectives.
• RLD2_20-v1.62-linear_1, RLD2_20-v1.62-nonlinear_1 — the 20-worker ensemble RL member, linear and nonlinear objectives.

Ensure Git LFS is installed (see Installation) so these arrive as real weights, not pointer files. The lower-level RLD1 agents are shipped separately inside the gym-superscript submodule under gym_superscript/trained_agents/. Note the config.yaml default at this snapshot names RLD2_20-v1.62_nonlinear_1; the model directories produced by the project use hyphenated names (e.g. RLD2_20-v1.62-nonlinear_1) — the experiment scripts in OptimizationExperiments override the model name explicitly.

Usage

Programmatic / script

from superscript_abm.model import SuperScriptModel

model = SuperScriptModel(optimiser_type='grasp',
                         worker_count=100,
                         new_projects_per_timestep=2,
                         random_seed=42)
model.run_model(100)

or run the supplied demonstration: python example_run.py.

Mesa browser visualisation

mesa runserver      # or: python run.py

Server runs on port 8521. Most important parameters can be set in the GUI (defined in superscript_abm/mesa_config.py); everything else comes from superscript_abm/config.yaml. model.data_collection must be True (default) for the simulation to run in Mesa. The social-network element is enabled in superscript_abm/server.py (slow: it recomputes the network layout each timestep); the network can also be saved for later analysis via the save_network config flag.

Note: parallel basinhopping (optimiser_type: basin) can be very slow; for real-time visualisation random or greedy are more practical.

Tests

python -m pytest tests/

Unit tests exercise the optimisers on pickled 10- and 100-worker model states with tests/test_config.yaml. RL-dependent tests require the trained models described above.

Reproducing the article results

Use the top-level OptimizationExperiments repository, which pins this repository at the article-reproducing revision and contains the golden regression suite (tests/regression/) that re-runs the optimisers on committed input states and compares against committed golden results.

Releases

• ss-v1.2 / ss-v1.3 : compatible with the original SuperScript repo.
• rl-v1.0 : compatible with the ReinforcementLearning repo on migration to TeamAllocation (release v1.0).
• article-release-v1 (this branch) : the article-reproducing snapshot with release documentation.

License and copyright

Copyright (C) 2025 Michael Christen michael.christen@mobi.ch

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for the full text.