vqe_module/README.md

Quantum Compute Modules

Репозиторий содержит набор модулей для распределённой системы квантовых вычислений. Каждый модуль представляет собой тип эксперимента, который может быть выполнен на локальных вычислительных системах.

Архитектура модуля

Каждый модуль состоит из двух независимых компонентов:

Компонент	Назначение
Frontend	Пользовательский интерфейс. React SPA, компилируется в HTML, встраивается в iframe на центральном сервере.
Executor	Python модуль, который скачивается и выполняется на локальной вычислительной системе.

Frontend

Режимы работы

Frontend поддерживает два режима отображения:

Режим	Когда используется	Что показывает
List	В списке задач эксперимента	Краткая информация (карточка)
Editor	На странице отдельной задачи	Полный редактор с параметрами

API взаимодействия (postMessage)

Получение данных от системы

window.addEventListener("message", (event) => {
  const { type, data } = event.data;
  
  if (type === "plugin-data") {
    // data.taskData — JSON строка с данными задачи
    // data.mode — "List" или "Editor"
    // data.theme — "light" или "dark"
    // data.simProgress — прогресс выполнения (если есть)
  }
  
  if (type === "update") {
    // Сигнал обновить UI (после сохранения)
  }
});

Отправка данных в систему

// При изменении данных задачи
window.parent.postMessage({
  type: "plugin-update",
  data: JSON.stringify(taskData),  // Данные задачи
  qubits_needed: number            // Требуемое количество кубит
}, "*");

// Сигнал готовности (отправляется после загрузки)
window.parent.postMessage({ type: "plugin-ready" }, "*");

Обязательные экспорты

React приложение должно экспортировать компоненты с интерфейсом:

interface TaskData {
  // Определяется для каждого модуля
}

interface TaskEditorProps {
  data: TaskData | undefined;
  setData: (data: TaskData, qubits_needed: number) => void;
  counter: number;      // Инкрементируется при обновлении данных извне
  simProgress: any;     // Прогресс выполнения (conn.send из executor)
}

Сборка

npm run build
# Результат: dist/index.html — один файл со встроенными CSS/JS

Executor

Python модуль, который скачивается с сервера и выполняется на локальной ВС. Должен содержать две функции:

prepare_data

Валидация и предобработка данных задачи. Вызывается на сервере перед помещением задачи в очередь.

def prepare_data(data: dict, system_info: dict) -> dict:

Результаты, возвращаемые функцией, передаются затем в run_computation.

В случае ошибки в данных, функция должны поднять ошибку.

run_computation

Выполнение вычислений на локальной ВС.

def run_computation(conn, dev, data):
    """
    Args:
        conn: Connection объект для отправки прогресса
              conn.send(dict) — отправляет сообщение на сервер
              (сообщения сохраняются в simulation_result.result_data)
        
        dev: PennyLane устройство
             qml.device(dev['name'], wires=dev['wires'])
        
        data: processed_data из prepare_data
    
    Returns: None
    """

Пример executor'а

def prepare_data(data: dict, system_info: dict) -> dict:
    # Валидация входных данных
    if "my_param" not in data:
        return {
            "valid": False,
            "error_message": "Отсутствует параметр my_param"
        }
    
    return {
        "valid": True,
        "processed_data": data,
        "qubits_required": data.get("qubits", 10)
    }


def run_computation(conn, dev, data):
    import numpy as np
    
    for step in range(data.get("steps", 100)):
        # ... вычисления ...
        
        # Отправка прогресса
        conn.send({
            "step": step,
            "current_value": current_value
        })
    
    return

Создание нового модуля

Шаг 1: Создание Frontend

1. Скопируйте шаблон new_module/ или создайте React приложение с нуля
2. Реализуйте компоненты ListItem и EditorPage
3. Реализуйте wrapper.tsx с обработкой postMessage
4. Соберите проект: npm run build

Шаг 2: Создание Executor

1. Создайте файл executor.py
2. Реализуйте функцию prepare_data
3. Реализуйте функцию run_computation

Шаг 3: Регистрация модуля

Через API центрального сервера:

curl -X POST https://quantum-backend/experiment/types \
  -F "name=Название модуля" \
  -F "description=Описание модуля" \
  -F "file_frontend=@dist/index.html" \
  -F "file_comp_system=@executor.py"

Список модулей

Модуль	Описание	Статус
vqe	Расчёт энергии основного состояния молекул	✅ Готов

Шаблон нового модуля

git clone https://git.deowl.ru/vkrb/vqe_module
cd quantum-modules
cp -r new_module my_module
# Редактируем frontend и executor
# Регистрируем через API