Skip to main content

System Design

Overview​

RODENT is a research platform. It provides project access, editable experiment templates, a 3D workspace, a simulation runner and recordings. The current statistical agent is a demonstration placeholder, not a validated biological rat model.

The modular structure allows individual components to be developed and tested independently while still operating as part of a single simulation.

High-Level Architecture​

The diagram below is the simulation subsystem, not the entire research platform. Around it, the website handles project creation, accounts, scoped team access, experiment selection and review. The local backend or hosted Supabase database stores project data; the embedded Godot build supplies the 3D view and kernel. The API and data map describes those boundaries.

The simulation subsystem can be represented as:

┌─────────────────────────────────────────────┐
│              Application / UI               │
│        Experiment Configuration & Controls  │
└──────────────────────┬──────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────┐
│             Simulation Kernel               │
│        Fixed-Step Simulation Execution      │
└──────────────────────┬──────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────┐
│            Simulation Context               │
│  State • Events • Configuration • Randomness│
└──────────┬────────────┬────────────┬─────────┘
           │            │            │
           ▼            ▼            ▼
      Arena Plugin  Stimulus Plugin  Agent Plugin
           │            │            │
           └────────────┴────────────┘
                        │
                        ▼
                Recorder Plugin
                        │
                        ▼
                 JSON / CSV Export

Simulation Kernel​

The simulation kernel controls the execution of the simulation.

Its responsibilities include:

  • Advancing simulation time
  • Maintaining the fixed simulation time step
  • Executing registered simulation plugins
  • Coordinating simulation updates
  • Supporting pause and step-based execution
  • Supporting reset and initialisation

The simulation uses a fixed time step so that simulation behaviour is independent of rendering or display speed.

For example, the project uses a fixed delta of:

0.1 seconds

This provides a consistent basis for scheduled events and behavioural calculations.

Simulation Context​

The SimulationContext provides shared state and information used by the simulation components.

It provides a common location for information such as:

  • Simulation time
  • Current simulation step
  • Random number generator
  • Experiment configuration
  • Events
  • Simulation state

Centralising this information allows plugins to communicate without tightly coupling their implementations.

Plugin Architecture​

Major simulation functionality is implemented using plugins.

Current plugin responsibilities include:

ArenaPlugin
    │
    └── Arena and environment

StimulusPlugin
    │
    └── Light, odour, sound and treatment events

StatisticalAgentPlugin
    │
    └── Demonstration-agent movement

RecorderPlugin
    │
    └── Experiment data recording and export

Plugins are registered with the simulation and executed according to their configured priority.

This is a partial microkernel approach. The small kernel owns time, state and plugin order, while arena, stimuli, demo agent and recording behaviour sit in plugins. It is partial because the website, Godot editor panels, Supabase access rules and some 3D presentation code are ordinary application components, not dynamically loaded plugins. That is a practical boundary: we can extend simulation behaviour without forcing project management or UI code into the kernel.

Arena​

The arena represents the physical experimental environment.

It is responsible for:

  • Defining the simulation environment
  • Defining regions
  • Providing physical boundaries
  • Providing collision information
  • Supporting environmental structures

The arena provides the spatial context for the current demo agent and for future researcher-supplied models.

Demo Agent​

The current statistical agent is used to exercise the platform and test repeatable runs. Its movement and preset names should not be treated as research-validated predictions of a real rat.

The placeholder currently provides:

  • Position
  • Movement
  • Turning
  • Behavioural characteristics
  • Collision handling
  • Behaviour selection
  • Interaction with the environment

The behavioural model stores the rat's floor position as a Vector2. The two values are mapped to Godot's X and Z floor axes by the 3D renderer, while the Y axis is reserved for elevation. Camera, lighting and rendered scene objects use Vector3, but adding a visual height does not change the deterministic movement model.

Demo presets illustrate different strategies, including:

  • Explorer
  • Balanced
  • Shelter Seeker

Stimulus System​

The stimulus system represents environmental influences that can affect the simulation.

The system supports:

  • Light
  • Odour
  • Sound

Stimuli have configurable properties and can be scheduled to activate at specific simulation steps.

Treatment conditions are also represented within the experiment system and support:

  • No treatment
  • Placebo
  • Medicine

Treatment events include dose and administration timing.

Recording System​

The recorder captures information generated during the simulation.

Recorded information includes:

  • Demo agent position
  • Current region
  • Active stimuli
  • Treatment events
  • User interventions

Recording is performed during simulation execution so that changes in state can be reconstructed after the experiment.

Data Export​

Simulation results can be exported in structured formats.

JSON​

JSON provides a structured representation of the experiment and its recorded events.

CSV​

CSV provides a tabular representation suitable for analysis using spreadsheet software or external data-processing tools.

The resulting workflow is:

Simulation
    ↓
Recorder
    ↓
Recorded Experiment State
    ↓
JSON / CSV
    ↓
External Analysis

Determinism​

Reproducibility is a core system requirement.

The simulation uses:

  • A defined random seed
  • Fixed simulation time steps
  • Controlled random number generation

The objective is that running the same experiment with the same configuration and random seed produces the same simulation results.

Display speed should not affect the underlying simulation outcome.

Automated determinism tests are used to verify this behaviour.

Experiment Configuration​

Experiments are represented using external configuration data.

A configuration can define simulation parameters such as:

  • Random seed
  • Fixed simulation step
  • Arena settings
  • Stimuli
  • Stimulus schedules
  • Treatment conditions
  • Other experiment parameters

This separates experiment configuration from the implementation of the simulation itself.

System Extensibility​

The modular architecture is intended to support future extensions.

Potential additions include:

  • Additional stimulus types
  • More behavioural models
  • Additional arena components
  • More complex treatment protocols
  • Additional recording formats
  • Machine learning integration
  • Advanced statistical analysis

The next step is to define a model contract for the internal and external APIs. A researcher-supplied model should declare its type, version, inputs, outputs, units and validation rules. Drag and drop is a convenient upload action, but the platform must validate and map the uploaded file to a supported extension point before running it. Template edits and script changes should update the visible setup and create a versioned intervention in the recording. Future light, odour and temperature overlays need testable definitions before they can be described as scientific exposure visualizations.

Ahmed's arena template builder already exists on a separate feature branch. It provides a 2D layout authoring route and exports a normal experiment configuration, but is not yet part of the integrated researcher workspace. This is different from the future model adapter: drawing a region or wall changes configuration; uploading a behavioural model would change how simulation decisions are computed and needs a stricter execution boundary.

New simulation behaviour can then be implemented as additional components without redesigning the kernel. The project and user interface can evolve separately. The development path so far has been largely bottom-up: core stepping and testable plugins came first, followed by 3D presentation, then the website and access workflow. The present redesign brings the researcher workflow back to the foreground.

AI Attribution: This document was drafted and edited with AI assistance, including ChatGPT and OpenAI Codex. The team reviewed it against the implemented project.