Agent‑based models thrive on parallelism. FLAME GPU executes agent functions as CUDA kernels, so one workstation‑class GPU can simulate millions of agents in real time—if you structure the model cleanly. This guide shows a practical, GPU‑friendly path from NetLogo/Mesa to FLAME GPU.
What we’ll cover
- Choosing a CUDA‑ready template and getting FLAME GPU built
- Minimal project layout that’s easy to maintain
- A tiny agent function skeleton and messaging pattern
- Validation against your CPU model
- A simple throughput benchmark (agents/s and cost per million agent‑steps)
- Profiling and common bottlenecks
Precision note: most ABMs are fine in FP32. If your model is sensitive, see the FP64 checklist.
Start in seconds with the fastest, most affordable cloud GPU clusters.
Launch an instance in under a minute. Enjoy flexible pricing, powerful hardware, and 24/7 support. Scale as you grow—no long-term commitment needed.
1) Pick your image on your GPU service
Your job runs inside a container. Two options that work well:
A) CUDA runtime + build from source (portable)
- Template: Ubuntu 24.04 LTS (CUDA 12.6)
- Add build tools and Python if you’ll use the Python API.
# Dockerfile (sketch)
FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential cmake git python3 python3-pip \
&& rm -rf /var/lib/apt/lists/*
ENV NVIDIA_VISIBLE_DEVICES=all \
NVIDIA_DRIVER_CAPABILITIES=compute,utility
B) Use a maintained FLAME GPU image (fastest)
- Point your template to your lab’s private image that already includes FLAME GPU and dependencies.
Either way, confirm GPU visibility inside the container:
nvidia-smi
2) Project layout
/work
├── CMakeLists.txt
├── src/
│ ├── agents.cu # agent functions
│ ├── model.cu # model description & layers
│ └── main.cu # entry point
├── python/ # optional Python driver
└── data/ # inputs, seeds, checkpoints
Initialize CMake and build out‑of‑tree:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
3) Agent function + messaging (skeleton)
FLAME GPU runs agent functions over agent arrays on the GPU. Use messages for local interactions.
// agents.cu
#include <flamegpu/flamegpu.h>
// Each agent reads messages in its neighborhood and updates velocity
FLAMEGPU_AGENT_FUNCTION(step, flamegpu::MessageSpatial2D, flamegpu::MessageSpatial2D) {
const float x = FLAMEGPU->getVariable<float>("x");
const float y = FLAMEGPU->getVariable<float>("y");
float vx = FLAMEGPU->getVariable<float>("vx");
float vy = FLAMEGPU->getVariable<float>("vy");
// simple cohesion
float cx = 0.f, cy = 0.f; int n = 0;
for (const auto &m : FLAMEGPU->message_in(x, y)) { // spatial iteration
cx += m.getVariable<float>("x");
cy += m.getVariable<float>("y");
n++;
}
if (n) { cx /= n; cy /= n; vx += 0.05f * (cx - x); vy += 0.05f * (cy - y); }
// write output state and position
FLAMEGPU->setVariable<float>("vx", vx);
FLAMEGPU->setVariable<float>("vy", vy);
FLAMEGPU->setVariable<float>("x", x + vx);
FLAMEGPU->setVariable<float>("y", y + vy);
// emit message for neighbors next step
FLAMEGPU->message_out.setVariable<float>("x", x);
FLAMEGPU->message_out.setVariable<float>("y", y);
return flamegpu::ALIVE;
}
Model description (pattern)
// model.cu
#include <flamegpu/flamegpu.h>
using namespace flamegpu;
ModelDescription model("abm");
AgentDescription agent = model.newAgent("A");
agent.newVariable<float>("x"); agent.newVariable<float>("y");
agent.newVariable<float>("vx"); agent.newVariable<float>("vy");
MessageSpatial2D::Description msg(model);
msg.setBounds(0, 100, 0, 100); // domain bounds
msg.setRadius(1.0f); // interaction radius
msg.newVariable<float>("x");
msg.newVariable<float>("y");
LayerDescription layer = model.newLayer("L");
layer.addAgentFunction(step);
Cela reflète les motifs NetLogo courants (tortues + rayon de vision), mais dans une structure de réseaux compatible avec les GPU.
4) Courez, lancez et contrôlez
. /build/abm --agents 5_000_000 --étapes 1000 --seed 42 \
--données de sortie/points de contrôle --checkpoint-interval 100
- Gardez graines déterministes pour validation.
- Écrivez des points de contrôle moins nombreux et plus grands pour réduire la charge d'E/S.
5) Validez par rapport à votre modèle de processeur
- Choisissez un petit monde et des règles identiques.
- Courez Référence du processeur (Netlogo/MESA) et GPU pour un horizon court.
- Comparez les indicateurs agrégés : dénombrements, positions moyennes, tailles de clusters ou statistiques spécifiques à un domaine.
- Les différences doivent se situer dans les limites de la variance stochastique pour la même graine.
Si les résultats divergent, vérifiez le rayon du message, les conditions aux limites et l'ordre des mises à jour.
6) Indice de référence en termes de débit et de coût
Utilisez des chiffres importants pour la planification.
indicateurs :
agents : <N>
étapes : <T>
wall_seconds : <... >
agent_pas_per_seconde : N*T/wall_seconds
cost_per_million_agent_steps : (prix_per_hour * wall_seconds/3600)/1e6 * (N*T)
Enregistrez le modèle GPU/la VRAM, le pilote, la version du GPU CUDA, la version du GPU FLAME et la ligne de commande exacte.
7) Profilage et goulots d'étranglement
- nvidia-smi: utilisation de la montre et VRAM.
- nsys/ncu: identifier les noyaux à faible taux d'occupation ou à accès non fusionné.
- Messagerie: les messages spatiaux s'adaptent mieux que toutes les paires par force brute ; gardez des rayons réalistes.
- Copies des appareils Host ↔: éviter les transferts par étape ; sorties par lots.
- Branchement: divisez les agents par état en fonctions/couches distinctes lorsque les branches sont chaudes.
8) Résolution des problèmes
GPU inactif
Trop peu d'agents ou beaucoup de travail côté hôte. Augmentez N, réduisez les E/S par étape ou déplacez la configuration dans le code du périphérique.
À court de mémoire
Réduisez la taille des variables d'agent, fragmentez les sorties ou choisissez un profil VRAM plus grand.
Résultats non déterministes
Réparez les graines et évitez les réductions non ordonnées du côté de l'hôte. Document RNG.
Erreurs de construction
Faites correspondre CUDA à votre image de base et à votre chaîne d'outils CMake. Nettoyez et reconstruisez.
Extrait de méthodes (copier-coller)
matériel :
processeur graphique : « <model>(<VRAM>Go) »
chauffeur : « <NVIDIA driver>»
<CUDA version>cuda : « »
logiciel :
<version>flambeau : « »
image : « Ubuntu 24.04 LTS (CUDA 12.6) »
modèle :
domaine : « [0,100] x [0,100] »
agents : <N>
règles : « démo réservée à la cohésion »
courir :
cmd : ». <N><T>/build/abm --agents --steps --seed 42"
points de contrôle : « tous les 100 pas »
sorties :
wall_seconds : « <... > »
agent_pas_par_seconde : « <... > »
coûts_per_million_agent_steps : « <... > »
Lecture associée
Essayez Compute dès aujourd'hui
Démarrez une instance GPU avec un modèle compatible CUDA (par exemple, Ubuntu 24.04 LTS/CUDA 12.6) ou votre propre image GROMACS. Profitez d'une facturation flexible à la seconde avec modèles personnalisés et la possibilité de démarrer, d'arrêter et de reprendre vos sessions à tout moment. Vous n'êtes pas sûr des exigences du FP64 ? Contactez le support pour vous aider à sélectionner le profil matériel le mieux adapté à vos besoins informatiques.
