vqe_module/README.md

# Quantum Compute Modules

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


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

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

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

## Frontend

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

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

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

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

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

```javascript
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 (после сохранения)
  }
});
```

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

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

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

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

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

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

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

### Сборка

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

## Executor

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

### prepare_data

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

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

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

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

### run_computation

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

```python
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'а

```python
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 центрального сервера:

```bash
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` | Расчёт энергии основного состояния молекул | ✅ Готов |

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

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