documentation/pages/charisma.md

# Подключение к суперкомпьютеру cHARISMa

Вычислительные эксперименты с высокими требованиями к вычислительным ресурсам можно запускать на суперкомпьютере cHARISMa. Процесс подключения и запуска включает в себя следующие шаги:

1. Получить доступ к суперкомпьютеру
2. Создать в пространстве имён приложения секрет с реквизитами доступа.
3. Создать MLDev-пайплайн вычислительного эксперимента
   1. Создать в MLDev-пайплайне объект класса `CharismaStage` на основе `ContainerStage` этапа, запускаемого на суперкомпьютере.
4. Собрать MLDev-пайплайн, получив в результате:
   1. ExperimentPipeline
   2. Sif-образ docker
5. Загрузить sif-образ docker в файловое хранилище S3
6. Запустить пайплайн


## Настройка доступа к суперкомпьютеру

Для получения реквизитов доступа к суперкомпьютеру cHARISMa нужно зарегистрироваться - https://hpc.hse.ru/users/registration

После успешного прохождения регистрации, вы получите логин и пароль для ssh-доступа к суперкомпьютеру. Чтобы фреймворк мог загружать задачи на суперкомпьютер, нужно добавить эти реквизиты в модуль. 

Если у вас есть доступ к фреймворку средствами kubernetes, реквизиты можно добавить, применив следующий манифест

```yaml
apiVersion: v1
data:
  credentials: dXNlcjpwYXNzd29yZA==
kind: Secret
metadata:
  name: charisma-ssh-credentials
  namespace: pu-{username}-pa-{appname}
type: Opaque
```

Главная информация здесь в поле `data.credentials` - это строка `user:password`, закодированная в base64. Имя `metadata.name` можно указать любое. Пространство имён `metadata.namespace` - это название приложения, такое же как в базовых компонентах, размещённых в папке app.

Альтернативно, в манифесте `ExperimentPipeline` который будет содержать этап подключения к суперкомпьютеру, можно указать переменные окружения `UNIP_MLDEV_CHARISMA_USERNAME` и `UNIP_MLDEV_CHARISMA_PASSWORD`:

```yaml
apiVersion: "unified-platform.cs.hse.ru/v1"
kind: ExperimentPipeline
metadata:
  name: my-pipeline
...
  stages:
  - name: my-charisma-stage
...
    entryPoint:
      cmd:
      - python
      - main.py
    env:
    - name: UNIP_MLDEV_CHARISMA_USERNAME
      value: "user"
    - name: UNIP_MLDEV_CHARISMA_PASSWORD
      value: "password"
```

## Создание MLDev-пайплайна эксперимента с подключением к суперкомпьютеру

Для подключения к cHARISMa необходимо создать этап типа `CharismaStage` в пайплайне MLDev, взяв за основу сущестующий этап `ContainerStage`.

При этом, в `ContainerStage` вместо лимитов `cpu`, `memory`, `gpu` нужно указывать в разделе лимитов:

- `time` - время, которое бронируется на суперкомпьютере, строка в формате `D-HH:MM:SS` - `Дни-Часы:Минуты:Секунды`.
- `nodes` - целое число, количество узлов
- `cpus` - целое число, количество CPU
- `gpus` - целое число, количество GPU
- `node_type` - строка, тип вычислительного узла в формате `type_a`. Возможные типы - https://hpc.hse.ru/hardware/hpc-cluster

В `UnipPipeline` нужно включить `CharismaStage`, не включая соответствующий `ContainerStage`.

```yaml
stage: !BasicStage &stage
  name: stage
  inputs:
    - !StageVar
      name: my_data
  outputs:
    - !StageVar
      name: my_result
  script:
    - python main.py

my_container_stage: !ContainerStage &my_container_stage
  name: my-stage
  base_image: platform-reg.stratpro.hse.ru/my_lab/project:9b6adde
  stage: *stage
  build:
    <<: *build
  code: *code
  resource_limits:
    time: 0-01:00:00 # Д-ЧЧ:ММ:СС
    nodes: 1
    cpus: 4
    gpus: 1
    node_type: type_a # или type_b, type_c, ...


my_charisma_stage: !CharismaStage &my_charisma_stage
  name: my-charisma-stage
  sif_input: charisma_sif
  stage: *my_container_stage


pipeline: !UnipPipeline
  name: my-project
  namespace: pu-username-pa-appname
  variables:
    - name: my_data
    - name: my_result
    - name: charisma_sif
  runs:
    - *my_charisma_stage
  connected_boxes:
    - name: user-box
      path: /userdata/
      default: true
      mount_s3_box:
        s3_box_name: users
```

## Сборка MLDev-пайплайна

В качестве результата работы пайплайна будет собран SIF-образ, который можно запускать на вычислительных узлах. Он собирается с помощью платформы Singularity, которую нужно установить. Инструкция по установке - https://docs.sylabs.io/guides/4.3/admin-guide/installation.html

Помимо определения самого эксперимента и общей настройки MLDev, для сборки пайплайна с `CharismaStage` нужно добавить дополнительные переменные окружения в `.mldev/config.yaml`

```yaml
environ:
  ... # остальные переменные
  UNIP_MLDEV_CHARISMA_OUTPUT: ./build/sif
  UNIP_MLDEV_CHARISMA_SSH_SECRET: charisma-ssh-credentials
  UNIP_MLDEV_CHARISMA_PIPELINE_SECRET: myapi-internal-cred
```

- `UNIP_MLDEV_CHARISMA_OUTPUT` - Локальный путь к папке, куда будет загружен SIF-образ
- `UNIP_MLDEV_CHARISMA_SSH_SECRET` - Название секрета с реквизитами доступа к cHARISMa в пространстве имён приложения
- `UNIP_MLDEV_CHARISMA_PIPELINE_SECRET` - Название внутреннего секрета, используемого API-компонентом пайплайна подключения к cHARISMa. В формате `{apicmp_name}-internal-cred`
  - Для доступа к пайплайну нужен соответствующий API-компонент. При создании API-компонента в пространстве имён приложения также создаются несколько объектов Secret с разными видами реквизитов. Их имена генерируются автоматически на основе имени API-компонента.


После этого сборку можно начать такой же командой, как для обычного MLDev эксперимента: `mldev run -f experiments/experiment-unip-pipeline.yaml`. Сборка SIF-образа может занимать много вычислительных ресурсов и оперативной памяти.

После завершения сборки в корневой папке проекта должна появиться следующая структура:

```
/build
├── containers
│   ├── my-charisma-stage.dockerfile
│   ├── my-charisma-stage.dockerignore
│   └── my-charisma-stage.sh
├── pipelines
│   └── my-project-qzv828.yaml
└── sif
    └── platform-reg.stratpro.hse.ru_my_lab_my-stage_0d00739.sif
```

Как и для обычного MLDev-пайплайна, создаются наборы файлов сборки контейнеров для каждого этапа в `build/containers/` и сгенерированный манифест `ExperimentPipeline` в `build/pipelines/`.

Помимо этого, собранный SIF-контейнер помещается в `build/sif/`.

Если в пайплайне предполагается несколько этапов, например, "обучить модель на суперкомпьютере, а затем построить отчёт о результатах обучения на обычных вычислительных ресурсах фреймворка", пайплайн будет разбит на [несколько частей](./split-pipeline.md). Этап с `CharismaStage` будет выделен в одну часть, а остальные этапы - в другую.

## Запуск ExperimentPipeline

Сгенерированные в `build/pipelines` манифесты нужно поместить в папку `app`, чтобы они подключились к фреймворку. При необходимости, в этих манифестах можно сделать дополнительные изменения вручную. Например, убрать сгенерированную уникальную часть имени пайплайна.

Сгенерированный SIF-контейнер нужно загрузить в любой ящик (DataBox) модуля через файловый API. При запуске с SIF-контейнером можно работать как с обычной переменной - передавать путь к нему в запросе или указывать заранее известный путь прямо в `ExperimentPipeline`.

Содержимое запроса запуска такое же, как для обычного пайплайна:

```json
{
  "inputs": [
      {
          "name": "charisma_sif",
          "data": "test1/inputs/image.sif",
          "datatype": "FILE",
          "content_type": "application/octet-stream",
          "shape": [
              0
          ]
      },
      {
          "name": "my_data",
          "data": "test1/inputs/my_data/",
          "datatype": "FILE",
          "content_type": "application/octet-stream",
          "shape": [
              0
          ]
      }
  ],
  "output_vars": [
      {
          "name": "my_result",
          "data": "test1/outputs/my_result/"
      }
  ]
}
```