Concepts

Understanding three concepts — plugins, scenario definitions, and scenario runs — is enough to use NeuroSim effectively.

Plugins

A plugin (also called a component) is an independent simulation participant. Each plugin models some element of the system being simulated: a power grid node, a network device, a SCADA controller, a sensor array, a traffic generator, or anything else relevant to your scenario.

Plugins are developed separately from NeuroSim Core and connect to it over Kafka when they start up. Core has no built-in knowledge of any specific plugin — it discovers them dynamically as they register.

When a plugin is running and connected, NeuroSim calls it online. The Dashboard and Scenario Editor both show which plugins are currently online.

What a plugin provides

Each plugin declares:

• A name and description identifying what it simulates
• A configuration schema — the set of parameters Core sends to the plugin when a run starts (e.g., node count, failure probability, timing parameters)
• Capabilities — named commands that can be sent to the plugin while a run is active (e.g., inject-fault, pause, set-load)
• A control topic — a dedicated Kafka topic where Core sends initialization and command messages to that specific plugin

Plugins communicate by sending and receiving messages on the scenario run's Kafka topic, where they are stored and streamed live to the NeuroSim UI.

Scenario Definitions

A scenario definition is a saved, named configuration that describes what a simulation will do — which plugins participate, and with what settings.

Think of a definition as a template or recipe. It answers: "If I were to run this simulation, which plugins would be involved, and how would each one be configured?"

A definition contains:

• A name and optional description
• A list of plugins (by ID), each with their individual configuration

Definitions are persisted in the database and survive Core restarts. They appear on the Dashboard and in the Scenario Editor.

Locked vs. unlocked definitions

A definition starts unlocked, meaning it can be freely edited. Once a run has been started from a definition, it becomes locked — its configuration is frozen to ensure that historical runs can always be traced back to the exact settings that produced them, and the scenario can be re-run with the same settings again in the future.

If you want to modify a locked definition, use Use as Template to create a new unlocked copy of the scenario definition that you can change.

Scenario Runs

A scenario run is a single execution of a scenario definition. Where a definition describes what to simulate, a run is the live (or recorded) instance of that simulation actually happening.

Each run:

• Gets a unique ID and its own dedicated Kafka topic
• Sends initialization parameters to each plugin and waits for them to confirm readiness
• Captures every message exchanged during the simulation to its Kafka topic
• Tracks timing (start time, end time, duration) and statistics (event counts by type and per plugin)

Runs progress through the following lifecycle:

A definition can have many runs over its lifetime. Each run is independent — running the same definition twice produces two separate, complete event histories.

How They Fit Together

Plugin A ──┐
Plugin B ──┼──► Scenario Definition ──► Scenario Run 1
Plugin C ──┘         (template)     └──► Scenario Run 2
                                    └──► Scenario Run 3

You build a definition once (or reuse and fork existing ones), then execute it as many runs as needed. All runs from a definition share the same plugin configuration snapshot, and each run's complete message history is available for later analysis.