Overview

GENIUS Framework Documentation

GENIUS is a multi-code agentic workflow framework designed for autonomous computational science across Quantum ESPRESSO, LAMMPS, VASP, SPPARKS, FEniCS, and GROMACS. It couples a Smart Knowledge Graph approach for parameter discovery with a Finite State Machine (FSM) execution engine and Multi-LLM hierarchy.

The framework consists of a FastAPI backend server (workflow_server.py), an independent Knowledge Graph service (qe_knowledge_graph.py), core engineering modules (eng/fsm/, eng/interfaces/, eng/core/), and an interactive web interface.

Framework Architecture & Directory Structure

GENIUS Core Framework Structure

workflow_server.py        # Main FastAPI server application (port 8001-8019)
qe_knowledge_graph.py     # Knowledge graph implementation & parameter retriever
eng/                      # Engineering core components
  ├── fsm/                # Finite State Machine state engine & state transitions
  ├── interfaces/         # LLM interface agents & OpenRouter API clients
  ├── core/               # Core business logic & input file generators
  └── assets/             # Parameter cards, crosswalks & schemas
setup_qe_wf.sh            # Automated installation script (Conda environments)
wf-tech-doc.md            # Technical API specification & JSON schemas
total results/            # Computational output storage (JSON & PNG timelines)

Supported Simulation Programs & Parameter Specs

Program Coverage & Knowledge Graph Node Stats

Program            Parameters    Taxonomy     Output Format
───────────────────────────────────────────────────────────────
Quantum ESPRESSO   240 params    77 conds     pw.x input file (.in)
VASP               558 tags      130 conds    INCAR file
LAMMPS             768 commands  339 conds    LAMMPS script (.lammps)
SPPARKS            101 commands  90 conds     SPPARKS input
GROMACS            Biopolymers   Forcefield   mdp file

Installation & Setup

The GENIUS Framework relies on Miniconda to set up isolated environments for both the workflow orchestration server and native simulation binaries.

Automated Setup — setup_qe_wf.sh

# 1. Clone the repository
git clone https://github.com/KIT-Workflows/agentic-workflow-framework.git
cd agentic-workflow-framework

# 2. Run the automated installation script
chmod +x setup_qe_wf.sh
./setup_qe_wf.sh

# The script creates two Conda environments:
#  - qe_wf : Main workflow server env (Python 3.11, FastAPI, Pydantic, NetworkX, ASE)
#  - qe    : Quantum ESPRESSO simulation environment from conda-forge

# 3. Activate the workflow environment
conda activate qe_wf

OpenRouter API Configuration (.env)

.env — Key Environment Variables

# OpenRouter API Key for Multi-LLM Orchestration
LM_API="sk-or-v1-your_openrouter_api_key_here"

# Primary Model Hierarchy
PRIMARY_MODEL="databricks/dbrx-instruct"
FALLBACK_MODEL_1="meta-llama/llama-3.1-405b-instruct"
FALLBACK_MODEL_2="anthropic/claude-3.5-sonnet"

# Evaluation Task Models
PARAM_EVAL_MODEL="mistralai/mixtral-8x22b-instruct"
CONDITION_MODEL="mistralai/mixtral-8x22b-instruct"

Multi-Program & HPC Execution

GENIUS supports local parallel execution via OpenMPI, containerized execution via Docker, and remote HPC dispatch via SSH tunneling and Slurm workload schedulers.

Local & MPI Execution Settings

# Quantum ESPRESSO settings in project_config
"qe_settings": {
  "use_slurm": false,
  "qe_env": "qe",
  "n_cores": 32,
  "conda_path": "/home/ubuntu/miniconda3/etc/profile.d/conda.sh",
  "qe_prefix": "mpirun -n 32",
  "module_name": "qe"
}

SSH Tunneling for Remote AWS & HPC Clusters

SSH Tunnel Command for HPC Access

# Forward port 8001 from HPC headnode to local machine
ssh -L 8001:127.0.0.1:8001 username@your.hpc.address

# Launch the workflow server on the HPC headnode
python workflow_server.py

Knowledge Graph Engine (qe_knowledge_graph.py)

The Knowledge Graph engine organizes parameter relationships, dependencies, and validation rules using NetworkX graph data structures. It serves graph schemas dynamically over HTTP at /api/data.

Running Knowledge Graph Server

# Start the independent Knowledge Graph server
python qe_knowledge_graph.py

# Server automatically binds an available port in range 8001-8019
# API data endpoint: GET http://localhost:8001/api/data

Graph Node JSON Schema

Knowledge Graph Node Example

{
  "parameter_name": "ecutwfc",
  "namelist": "&SYSTEM",
  "type": "REAL",
  "default_value": 60.0,
  "unit": "Ry",
  "description": "Kinetic energy cutoff for wavefunctions.",
  "connections": ["ecutrho", "dual", "k_points"]
}

Finite State Machine (FSM) Pipeline

The workflow execution is governed by a strict 7-state Finite State Machine (implemented in eng/fsm/) that guarantees deterministic execution, error recovery, and model fallback.

FSM State Transitions

1. STATE: INITIAL
   Prompt parsing & project workspace initialization
2. STATE: KG_RETRIEVAL
   Knowledge Graph query for parameter cards & constraints
3. STATE: PARAMETER_EVALUATION
   Taxonomy matching & value assignment via LLM
4. STATE: CODE_GENERATION
   Syntax generation for pw.x (.in), INCAR, or LAMMPS (.lammps)
5. STATE: SOLVER_EXECUTION
   Execution via local MPI or Slurm cluster dispatch
6. STATE: RESULTS_ANALYSIS
   SCF convergence extraction & energy parsing
7. STATE: FINAL
   Packaging JSON artifacts & timeline rendering

FastAPI REST API Reference (workflow_server.py)

The FastAPI server (default base URL: http://127.0.0.1:8001) exposes endpoints for creating, managing, and streaming workflows.

GET /ping

Health check endpoint. Returns {"status": "ok", "message": "API is running"}.

POST /workflow/

Creates and starts a new workflow. Request payload requires calculation_prompt, lm_api key, gen_model_hierarchy, and optional project_config. Returns {"status": "started", "workflow_id": "..."}.

GET /workflow-status/{workflow_id}

Checks current workflow state: {"status": "running", "current_state": "STATE: SOLVER_EXECUTION"}.

POST /stop-workflow/{workflow_id}

Stops a running workflow. Returns {"status": "success", "message": "Workflow stopped"}.

GET /results/{workflow_id}

Retrieves JSON computational outputs and SCF energy results.

GET /timeline/{workflow_id}

Returns a PNG image visualization of the state machine timeline graph.

GET /logs

Provides real-time log streaming using Server-Sent Events (SSE / EventSource).

Launch Cloud Workbench 🚀