AlgoTwin-X Studio

A working, extensible algorithm digital twin and discrete-event simulation studio.

It is designed for experimentation rather than fixed animations: create a scenario, edit its JSON model, run it as a live twin, replay every state frame, compare multiple runs, and export the results.

Included features

• Shared virtual-time simulation architecture
• Deterministic event queue for resource workflows
• Live WebSocket frame streaming
• Time-travel replay with state inspection
• Scenario import/export and persistent scenario library
• Automatic scenario generation with scale and seed
• Built-in domains:
  • Graph: BFS, Dijkstra, A*
  • CPU scheduling: FCFS, Round Robin
  • Generic resource-aware DAG workflows
• Local plugin SDK (user_plugins/)
• Experiment history persisted to output/runs/
• Side-by-side comparison with automatic metric winners
• Export comparison data as:
  • PNG
  • PDF
  • CSV
  • JSON
  • ZIP bundle containing all formats
• Fully self-contained browser UI; no Node.js build step and no CDN dependency
• FastAPI OpenAPI docs at /docs

Quick start on Windows

1. Extract the project.
2. Double-click setup_windows.bat.
3. Open http://127.0.0.1:8000 if the browser does not open automatically.

Later launches:

start_windows.bat

Manual setup

Python 3.11 or 3.12 is recommended.

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run.py

Linux/macOS:

source .venv/bin/activate
pip install -r requirements.txt
python run.py

Then visit:

http://127.0.0.1:8000

How customization works

1. Edit any scenario

Every scenario has this shape:

{
  "name": "My Experiment",
  "description": "What I am testing",
  "domain": "workflow",
  "algorithm": "resource_aware",
  "config": {},
  "tags": ["custom"],
  "playback_delay_ms": 50
}

The config object is domain-specific and fully editable.

2. Build custom workflows

Example:

{
  "resources": {"cpu": 8, "gpu": 2, "ram": 64},
  "tasks": [
    {
      "id": "load_data",
      "duration": 3,
      "dependencies": [],
      "demands": {"cpu": 1, "gpu": 0, "ram": 8},
      "priority": 3
    },
    {
      "id": "train",
      "duration": 12,
      "dependencies": ["load_data"],
      "demands": {"cpu": 4, "gpu": 2, "ram": 32},
      "priority": 5
    }
  ]
}

Resource names are arbitrary. You can model cpu, gpu, ram, workers, robots, machines, bandwidth, or your own capacity units.

3. Add a new local simulation domain

Copy:

user_plugins/example_counter.py

Create a class derived from:

SimulationPlugin

Expose a module-level instance:

PLUGIN = MyPlugin()

Restart the server. The domain and its algorithms are discovered automatically and appear in the UI.

Local plugins are trusted executable Python code. The web API intentionally does not accept executable plugin uploads.

Comparison workflow

1. Run at least two experiments.
2. Open Compare & Export.
3. Select completed runs.
4. Click Compare Selected.
5. Choose a metric.
6. Export PNG, PDF, CSV, JSON, or the complete ZIP bundle.

Project structure

algotwin_x_studio/
├── app/
│   ├── exports.py
│   ├── main.py
│   ├── manager.py
│   ├── models.py
│   ├── scenario_generator.py
│   └── storage.py
├── engine/
│   ├── custom_loader.py
│   ├── kernel.py
│   ├── registry.py
│   └── plugins/
│       ├── base.py
│       ├── graph.py
│       ├── scheduling.py
│       └── workflow.py
├── user_plugins/
│   └── example_counter.py
├── static/
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── scenarios/
├── output/
│   ├── exports/
│   └── runs/
├── tests/
├── requirements.txt
├── requirements-dev.txt
├── run.py
├── setup_windows.bat
├── start_windows.bat
└── setup_linux.sh

API highlights

• GET /api/health
• GET /api/domains
• POST /api/scenarios/validate
• POST /api/scenarios/generate
• POST /api/scenarios/save
• POST /api/runs/start
• GET /api/runs
• GET /api/runs/{run_id}
• WS /ws/runs/{run_id}
• POST /api/compare
• GET /api/exports/comparison

Testing

pip install -r requirements-dev.txt
pytest -q

Current scope

This release is an end-to-end MVP. It does not yet attempt cycle-accurate CPU simulation, container orchestration fidelity, or production multi-tenant sandboxing. Those should be separate later phases rather than pretending the MVP already provides them.