Синтез радиоизображений

Инструкции по синтезу радиоизображений, полученных Сибирским Радиодогелиографом с помощью программного обеспечения, разработанного в радиоастрофизическом отдлеле ИСЗФ СО РАН.

Синтез радиоизображений с помощью пакета srh_synth

Установка пакета srh_synth на свой компьютер

ПО для синтеза радиоизображений СРГ написано на языке программирования Python 3, поэтому прежде чем его использовать, вам необходимо установить интерпретатор этого языка.

Если вы синтезируете изображения на одном из серверов отдела радиоастрофизики ИСЗФ СО РАН, то Продолжите чтение инструкции с раздела Синтез радиоизображений, так как у вас уже установлены все необходимые пакеты.

Установка Python 3 в Linux

В большинстве популярных дистрибутивов Linux Интерпретор Python 3 обычно установлен по умолчанию. Проверить установлен ли Python на вашей машине можно, запустив следующую команду в терминале:

python --version

или

python3 --version

Если Python установлен, то вы команда выведет версию установленного Интерпретатора. Мы рекомендуем использовать Python 3.10 или более свежую версию. Если же в вашей системе Python 3 не установлен, то установите его с помощью менеджера пакетов вашего дистрибутива. Например, в Ubuntu для этого нужно в терминале выполнить следующую команду.

sudo apt install python3

Установка Python 3 в Windows

Интерпретатор языка Python не входит в состав операционной системы Windows, поэтому его предётся устанавливать отдельно. Это можно сделать двумя способами.

  1. Установить "чистый" интерпретатор Python запустив инсталятор, скачанный с официального сайта Python .
  2. Установить Python в составе менеджера пакетов Anaconda и Miniconda. В первом случае вместе с интерпретаром языка будут также установлен большой набор пакетов предназначенных для научных вычислений и визуализации данных. В случае же Miniconda будет установлен только интерпретатор языка Python и менеджер пакетов conda.

Создание виртуального окружения

Мы рекомендуем установливать ПО для синтеза радиоизображений в отдельном виртуальном окружении (virtual environment), чтобы избужать конфликта зависимостей. В случае, если вы планируете использовать Python только для синтеза радиоизображений, этот шаг можно пропустить.

TO BE DONE

Установка пакета srh_synth

Пакетsrh_synth в текущей версии использует часть функций универсального пакета srhimages и устанавливается вместе с ним командой:

pip install -U "srhimages[anfinogentov] @ git+https://git.iszf.irk.ru/fedenev/srhimages"

Альтернативно можно установить пакет srhimages с полным набором опций.

pip install -U "srhimages[all] @ git+https://git.iszf.irk.ru/fedenev/srhimages"

Тогда вместе с пакетом srh_synth будет доступен также и код для синтеза изображений srhdata, разрабатываемый Марией Глоба. Если вы используете виртуальное окружение, то перед запуском команд установки его нужно активировать.

Синтез радиоизображений

Синтез радиоизображений состоит из двух этапов:

  1. Калибровка коэффициентов усиления антенн - функция srh_synth.srh_calib
  2. Синтез изображений - функция srh_synth.srh_synth В начале работы необходимо импортировать импортировать эти функции.
from srh_synth import srh_synth, srh_calib

Калибровка коэффицентов усиления антенн

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

Примеры команд для калибровки:

Калибровка для частот 6 и 6.4 ГГц для одного момента времени 2024-06-01 03:00:

calibrations = srh_calib("2024-06-01 03:00", frequency = [6000, 6400])

Калибровка наблюдений за весь день для частоты 6 ГГц:

calibrations = srh_calib("2024-06-01 00:00","2024-06-01 12:00", frequency = [6000])

Калибровка наблюдений за два часа для частоты 16 ГГц:

calibrations = srh_calib("2024-06-01 02:00","2024-06-01 04:00", frequency = [16000])

Калибровка наблюдений за весь день для частоты 3 ГГц с сохранением калибровок в файл 'calib.json':

calibrations = srh_calib("2024-06-01 00:00","2024-06-01 12:00", frequency = [3000], write_to= 'calib.json')

Калибровка данных решётки 6-12 ГГЦ для одного момента времени 2024-06-01 03:00:

calibrations = srh_calib("2024-06-01 03:00", frequency = 'SRH0612')

Полный список параметров функции srh_calib:

Возвращаемое значение: Функция srh_calib возвращает словарь, в котором находятся результаты калибровки разобранные по частотным каналам и отсорторированные по времени. Данную переменную нужно использовать для синтеза изображений.

Синтез радиозображений

После выполнения калибровки можно приступать непосредственно к построению изображений.

Примеры команд синтеза рад иоизображений

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

srh_synth("2024-06-01 03:00", frequency = [6000, 6400], calibrations=calibrations)

Синтез серии изображений на одной часоте для заданного интервала времени с временным разрешением 60 секунд, используя калибровки из файла 'calib.json':

srh_synth("2024-06-01 02:30", "2024-06-01 03:30", frequency=[3000], cadence=60, calibrations='calib.json')

Синтез изображений для заданного интервала времени c накоплением 30 секунд и временным разрешением 300 секунд. Изображения сохраняться в папку "srh20240601", имена сохранённых файлов будут напечатаны в консоли:

files = srh_synth("2024-06-01 03:00", int_time=30, cadence=300, calibrations=calibrations, out_dir='srh20240601')
print(files)

Полный список параметров функции srh_synth:

Возвращаемое значение: Функция srh_synth возвращает список имен файлов синтезированных изображений.

Синтез радиоизображений с помощью пакета srhdata

Универсальный пакет для синтеза изображений srhimages

Программа srhimages предоставляет функции для синтеза радиоизображений из данных Сибирского Радиогелиографа (SRH).

Установка

Код Сергея Анфиногентова работает на python 3.10 до 3.12, код Марии Глобы - только на 3.10! Поэтому желательно устанавливать именно 3.10. Для расчётов на удалённых машинах может быть допустимо установить любую версию питона. При расчётах через Dask желательно так же использовать 3.10. На Windows на данный момент пока что работает только код Сергея Анфиногентова.

conda env create -n srhsynth python=3.10
conda activate srhsynth

pip install -U "srhimages[all] @ git+https://git.iszf.irk.ru/fedenev/srhimages"
# или [globa], [anfinogentov] вместо [all], чтобы выбрать только конкретный расчётный код

Если производится свежая установка с использованием расчётного кода Марии Глобы, то требуется обновить данные CASA:

python3 -m casaconfig --update-all

Использование уже установленного окружения на сервере ИСЗФ

conda activate /opt/miniconda3/envs/srhsynth/

Интерфейс командной строки

srhimages create_synth_tasks --help
srhimages run_computation --help

Использование в своих скриптах

import srhimages

help(srhimages.create_synth_tasks)
help(srhimages.run_computation)

Обратите внимание, что если запуск кода происходит через Python скрипт .py, то требуется запускать расчёты следующим образом:

import srhimages

if __name__ == "__main__":
    # srhimages.run_computation(.....)
    pass

Этот костыль связан с особым механизмом работы систем параллельных расчётов в Python. При запуске кода в Jupyter, скорее всего, это не понадобится.

Описание команд и принципы работы

Расчётные задачи

Программа работает в парадигме так называемых расчётных задач ("tasks"). Каждая из задач представляет собой Python-словарь или его JSON-представление и описывает, из каких данных (сырых файлов и сканов внутри них) должно получиться итоговое изображение, куда оно будет сохранено и с какими параметрами синтезировано.

Актуальная спецификация формата расчётной задачи есть в исходном коде в формате jsonschema. Спецификация API для работы с амплитудно-фазовыми калибровками антенн находится в репозитории badary-services.

Интерфейс программы:

  1. server_calibrate(task_list, algorithm, save_to=None, search_window="15min")

    • Назначение: Обрабатывает список некалиброванных задач, чтобы назначить им калибровки, предоставленные командой SRH и находящиеся на API-сервере.

    • Аргументы:

      • task_list: Список задач для вычисления или путь к файлу JSON с списком задач.
      • algorithm: "globa" или "anfinogentov".
      • save_to (необязательно): Путь к файлу JSON для сохранения списка задач.
      • search_window (необязательно): Временное окно (-search_window/2, +search_window/2), в котором серверная калибровка считается допустимой для использования. По умолчанию: "15min".

    • Возвращает:

      • calibrated_tasks: Список задач с доступным объектом ["gains"] в каждой из них, если соответствующие серверные калибровки были найдены, в противном случае – задачи, которые были переданы изначально.

  2. create_synth_tasks(time1, time2=None, cadence="15min", frequencies="all", resample_from=None, save_to=None, average_width=20, average_unit="scans", average_position="after", average_mode = "visibilities", output_polarizations="IV", naxis=512, cdelt=4.9, clean_disk=True, compressed=True, smooth_gains=False)

    • Назначение: Создает список (некалиброванных) задач по синтезу радиоизображений с телескопа.

    • Аргументы:

      • time1 (str): Время начала наблюдения в формате 'ГГГГ-ММ-ДД ЧЧ:ММ:СС'.
      • time2 (str или None, опционально): Время окончания в том же формате.
      • cadence (str, опционально): Временной интервал между каждым наблюдением в формате "NNmin" или "NNs". По умолчанию "15min".
      • frequencies (list(int) или str, опционально): Список частот для наблюдения в МГц или "all" в виде строки, или диапазон вида "3000-5000", или список вида [3000, "6000-8000", "SRH1224"].
      • resample_from (list или str): Список задач или путь к файлу, содержащему список задач в формате JSON, откуда брать калибровки. Доступные частоты в списке resample должны совпадать с запрошенными пользователем частотами.
      • save_to (str, опционально): Путь к json файлу для сохранения списка задач.
      • average_width (int или float, опционально): Количество сканов или секунд для усреднения. По умолчанию 20.
      • average_unit (str, опционально): Может быть 'scans' или 'seconds'. По умолчанию 'scans'.
      • average_position (str, опционально): Временное окно для усреднения. Может быть 'after', 'before' или 'center'. По умолчанию 'after'.
      • average_mode (str, опционально): Режим усреднения. Может быть 'visibilities', 'gridding' или 'images'. По умолчанию 'visibilities'.
      • output_polarizations (str, опционально): Может быть 'IV' или 'RL'.
      • naxis (int, опционально): Количество пикселей вдоль каждой оси выходного изображения. По умолчанию 512.
      • cdelt (float, опционально): Размер каждого пикселя в угловых секундах. По умолчанию 4.9 для СРГ.
      • clean_disk (bool, опционально): Флаг для включения/выключения очистки "грязного" изображения. По умолчанию True.
      • compressed (bool, опционально): Флаг для включения/выключения сжатия FITS выходного изображения. По умолчанию True.
      • smooth_gains (bool, опционально): Предпочтение сплайн-интерполяции калибровок вместо ближайших соседей при передискретизации. Используйте True для калибровок за весь день.

    • Возвращает:

      • Список задач синтеза (каждая задача – Python dict), например, для отправки на кластер или для локального вычисления.

  3. run_computation(task_list, algorithm, cache_dir="./images/raw/", out_dir="./images/out/", ftp_server="https://ftp.rao.istp.ac.ru", n_threads=5, calibrate="prefer_server", progress_save_to=None, calibrations_search_window="15min", skip_postprocessing=False, skip_images=False, input_dir=None, cluster_object="local", run_id=None)

Возвращает:

Примечание:

Пример использования

Простой случай нескольких изображений в течение дня
import srhimages

time1, time2 = "2024-06-01 02:00:00", "2024-06-01 02:00:05"
frequencies = [2800, 3000]

task_list = srhimages.create_synth_tasks(time1, time2, cadence="3s", frequencies=frequencies,\
    save_to="synth_1.json",
    average_width=5, average_unit="seconds", average_mode = "visibilities", average_position="after",\
    output_polarizations = "IV", naxis=512, cdelt=4.9, clean_disk=True, compressed=True)

if __name__ == "__main__":
    results = srhimages.run_computation("./synth_1.json", "globa", progress_save_to="./results.json")

# результаты появятся в каталоге ./images/out
Обработка солнечной вспышки

Здесь требуется уже откалибровать данные на достаточно большом интервале времени, поскольку во время вспышки резко снижается вклад коротких баз радиотелескопа. Поэтому расчёт будет проходить в 2 этапа:

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

import srhimages

freq_list = [3000, "5500-6200"]
time1, time2 = "2024-02-06 02:10:00", "2024-02-06 04:00:00"

calib_tasks = srhimages.create_synth_tasks(time1, time2, cadence="5min",\
    frequencies=freq_list, save_to="calibs.json")

# в файле calibs.json появятся задания для вычисления первоначальных калибровок

if __name__ == "__main__":
    computed_calibrations = srhimages.run_computation("calibs.json", "globa",\
    progress_save_to="calibs_ready.json", skip_images=True)

    # параметр skip_images нужен, потому что
    # нам нужны только калибровки, а не сами изображения

# если всё хорошо, то в файле calibs_ready.json будут готовые калибровки.

Второй этап. Когда у нас уже имеются постобработанные калибровки, то можно на их основе посчитать картинки с максимальным временным разрешением. cadence="0s" означает, что используется максимально возможное временное разрешение. Список частот должен быть тем же самым, на котором шла калибровка. Параметр resample_from означает, что для новых заданий берутся уже посчитанные калибровки и переносятся на новую сетку по времени. smooth_gains означает, что интерполяция коэффициентов усиления антенн на нужный кадр будет производиться с помощью сплайна, а не ближайшего соседа. Эта настройка рекомендуется, когда временное разрешение финальных изображений чаще, чем разрешение калибровок.

synth_tasks = srhimages.create_synth_tasks(time1, time2, cadence="0s", frequencies=freq_list,\
    resample_from="calibs_ready.json", smooth_gains=True, save_to="synth.json")

if __name__ == "__main__":
    results = srhimages.run_computation("synth.json", "globa",\
        progress_save_to="synth_progress.json")

В списке выполненных (или невыполненных) задач, который появится в переменной results или в файле synth_progress.json, будут уже прописаны полные пути к полученным изображениям

Загрузка калибровок на сервер

from srhimages.calibrations import CalibrationsApi
import json

with open("synth_2.json", "r") as fp:
    calibrated_tasks = json.load(fp)

cal_api = CalibrationsApi(password="...")

for task in calibrated_tasks:
    cal_api.create(task["gains"])