Skip to main content

System Design

Overview​

The Virtual Rodent system is designed as a modular simulation environment. The architecture separates simulation state, simulation execution, environmental features, behavioural agents, stimuli, recording and application-level functionality.

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 system 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
    │
    └── Simulated rat behaviour

RecorderPlugin
    │
    └── Experiment data recording and export

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

This approach allows functionality to be added without requiring major changes to the simulation 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 in which the simulated rat operates.

Behavioural Agent​

The behavioural agent represents the simulated rat.

The agent is responsible for:

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

The planned 3D implementation uses Vector3 to represent the rat's position.

Behaviour presets allow different strategies to be represented, 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:

  • Rat 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

New functionality can be implemented as additional components without requiring the entire simulation architecture to be redesigned.

AI Attribution: The preceding document was generated and edited with assistance from ChatGPT Web (GPT-5.6 Luna).