Общее описание

Сервис для запуска модели Граль. Модель Граль предназначена для расчёта рассеивания частиц в зависимости от внешних факторов среды, включая погодные условия, рельеф и параметры источника выбросов. Данный модуль построен на свободно-распространяемой модели GRAL/GRAMM, которая основана на модели рассеивания Лагранжа.

Условия функционирования сервиса

Сервис предусматривает однопользовательскую работу, что в свою очередь означает что в данный момент времени с ней может работать только один пользователь, при этом нельзя запускать одновременно несколько расчетов, а также производить изменение параметров расчета во время его выполнения. Расчет модели может занимать продолжительное время. Исходные данные для расчета модели размещаются в определенной папке проекта, которая в свою очередь смонтирована с докер-контейнером для взаимодействия. Результаты расчетов также сохраняются на диске в папке аналогичным образом. В сервисе клиентская часть не предусмотрена, поэтому для взаимодействия с пользователем предусмотрены пакетные скрипты Работа осуществляется в следующем режиме:

1. Работа осуществляется на локальном компьютере после развертывания сервиса.
2. Подготовить исходные данные для расчета
3. Для запуска расчета необходимо из консоли (командной строки) локального компьютера запустить соответствующий скрипт, внутри которого содержится запрос к сервису
4. Дождаться завершения (может занимать продолжительное время). До завершения расчета никаких действий больше не производится.
5. После завершения расчета будет выдано сообщение об успешном выполнении расчета
6. Использовать результаты расчета из соответствующей папки

Общие требования, подготовительная работа

Модель Граль построена с использованием библиотеки .NET framework. C целью обеспечения ее функционирования необходимо наличие соответствующего окружения, поэтому сервис реализован в виде docker-контейнера построенного на docker-образе Mono, включающий в себя все необходимые библиотеки. Данный docker-образ предварительно должен быть сформирован сценарием, который описан в Dockerfile проекта. Для того чтобы приступить к работе необходимо произвести установку на локальной машине Docker, Docker Compose или Docker Engine не ниже версии 25.

Сборка

Установка проекта производится путем клонирования проекта на локальный компьютер из git-репозитория При первоначальной установке проекта необходимо выполнить сборку docker-образа. Сборка выполняется единожды, а также при каждом внесении изменения в Dockerfile. Процесс в зависимости от производительности вашего компьютера может занимать продолжительное время. Для сборки необходимо из каталога $HOME компьютера выполнить следующее:

docker compose build
docker compose build --progress=plain # применяется для логирования процесса сборки, используется для анализа если при сборке произошла ошибка

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

docker image ls

После чего должен быть выведен список имеющихся docker-образов, в списке должен быть образ со следующим именем и тэгом:

1. gral:mono-6.12.0.182_python-3.10 # Версия mono 6.12.0.182 с установленным дополнительно Python 3.10

Запуск

Для создания и запуска docker-контейнера из каталога $HOME выполнить следующее:

docker compose up -d

Проверка работы

После запуска убедиться что docker-контейнер успешно был создан и запущен для этого из каталога $HOME выполнить следующее:

docker compose ps

После чего вы должны увидеть следующее:

NAME           IMAGE                              COMMAND                  SERVICE        CREATED          STATUS          PORTS
internal-app   gral:mono-6.12.0.182_python-3.10   "uvicorn App.app:app…"   internal-app   11 seconds ago   Up 10 seconds   0.0.0.0:5000->80/tcp

Затем проверить работу запустив соответствующий скрипт в зависимости от OC вашего локального компьютера

Останов сервиса и уничтожение docker-контейнера

Для останова и уничтожения docker-контейнера из каталога $HOME выполнить следующее:

docker commpose down

Просмотр журнала работы сервиса

В сервисе отсутствует обратная связь от библиотеки .NET Framework, чтобы мониторить ссотояние вычислений моделей GRAL/GRAMM необходимо из каталога $HOME выполнить следующее:

docker compose logs

После чего в консоль будет выведен журнал работы.

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

Все скрипты находятся в папке scripts

Наименование	ОС	Описание
get_status.bat	Windows	Проверка состояния готовности сервиса. В случае готовности сервиса к работе выдается сообщение об успешном выполнении
get_status.sh	Ubuntu
post_emission.bat	Windows	Симуляция значения выбросов. Данный запрос формирует csv файл. Он сохраняется в DEVICE_PROJECTPATH с именем csvfile_emissoins.csv. По завершении выдается сообщение об успешном выполнении
post_emission.sh	Ubuntu
post_config-gral.bat	Windows	Задание конфигурации для модели Gral. Файл с конфигурацией лежит в каталоге ./config-gral.json. По завершении выдается сообщение об успешном выполнении
post_config-gral.sh	Ubuntu
get_grammfile.bat	Windows	Запуск расчета негидростатической мезомасштабной модели поля ветра GRAMM. Данные для расчета берутся из файлов проекта. Результатом выполнения модели GRAMM будут такие файлы, как ggeom.asc, windfeld.txt и landuse.asc.По завершении выдается сообщение об успешном выполнении
get_grammfile.sh	Ubuntu
get_gralfile.bat	Windows	Запуск расчета модели GRAL. Данные для расчета берутся из файлов проекта. Результатом выполнения будет формирование out/gralfile.zip. По завершении выдается сообщение об успешном выполнении
get_gralfile.sh	Ubuntu
get_gralwz.bat	Windows	Запуск расчета модели GRAL. Данные для расчета берутся из файлов проекта. Результатом будет сохранен в proj/Computation. По завершении выдается сообщение об успешном выполнении
get_gralwz.sh	Ubuntu
post_svg.bat	Windows	Создание карты рассеивания на основе изображения карты (в формате png) и файла с результатами работы модели Gral. Данные для запроса в svg.json. В случае успешного выполнения формируется файл proj/out.svg. По завершении выдается сообщение об успешном выполнении
post_svg.sh	Ubuntu

Исходные данные для расчета модели

Описание файла с данными конфигурации, значения указанные в колонке Пример содержатся в файле конфигурации config-gral.json

Наименование параметра	Описание	тип данных	значение по умолчанию	пример
max_proc	Количество потоков для расчета	Integer(1)	4	8
pps	Количество в шт/с маркированных частиц для отслеживания их траекторий (Сильно влияет на производительность)	Integer(1)	100	200
disp_time	Время распыления маркированных частиц	Integer (1)	3600	1800
mode	Тип расчета: 0 – скоротечный расчет (несколько часов) 1 – стандартный расчет	Integer (1)	1	1
meteo_input	Тип файла входных данных погодных условий 0 - inputzr.dat 1 – meteo.all 2 – elimaeki.prn 3 – SONIC.dat 4 - meteopgt.all	Integer(1)	4	4
receptors	Наличие приемников в каждом узле расчетной сетки (!!!Значительно влияет на производительность) 0 – создание приемников 1 – без приемников	Integer (1)	0	0
surface_roughness	Жесткость поверхности – определяет коэффициенты расчета внутри комплекса GRAL	Float (1)	0.2	0.3
lat	Широта для которой будет введена поправка внутри комплекса GRAL	Integer(1)	57	57
z	Высота над землей в [м] для фиксирования расчетных данных	Float(1)	5	10
starting_weather	Номер погодных условия для начала расчета	Integer (1)	1	3
buildings	Наличие зданий в расчете 0 – нет зданий 1 – есть здания	Integer (1)	0	1
soundplan	Определяет вид выходных файлов для расчетов со зданиями 0 – не активирован 1 – активирован -2 – запись высот зданий	Integer (1)	0	0
compress	Сжатие выходных данных compressed – производить сжатие выходных файлов	String (1)	compressed	compressed
wait	Ожидание ввода клавиши после расчета для завершения программы расчета	String (1)	No	WaitForKeyStroke
ASCii	Наличие дополнительных файлов вывода	Integer (1)	1	1
adaptive_surface	Включение адаптивной жесткости поверхности в [м]. Значение отличное от 0 задает максимум	Float (1)	0	1.1
radius_surrounding	Радиус дополнительных расчетов вокруг зданий	Float (1)	0	1.1
online	Включение online функций при расчетах 0 – выключены 1 – включены	Integer (1)	1	1
source_groups	Номера групп источников для обрачотки	Integer (1)	0	1
name	Имя точечного источника	String (1)	""	Stack1
x	Широта точечного источника в координатах МСК-хх	Float (1)	0	513435
y	Долгота точечного источника в координатах МСК-хх	Float(1)	0	2236807
Q	Количество выбросов точечного источника в [кг/ч]	Float(1)	0	0.416
H	Высота точечного источника в [м]	Float(1)	0	41
diam	Диаметр точечного источника в [м]	Float(1)	0	1.1
exit_velocity	Скорость ЗВ при выбросе из источника в [м/с]	Float(1)	0	11.2
temp	Температура ЗВ при выбросе из источника [К]	Float(1)	0	541
pollutants	Тип загрязняющего вещества в сокращении	String(1)	'SO2'	'NO'
atmosphere_stability	Тип стабильности при моделировании погодных условий	String(1)	annual_cycle	annual_cycle
RH	Относительная влажность в [%]	Float(1)	80	70
days	Количество дней для моделирования (отсчет начинается с 00:00)	Integer(1)	0	5
dlat	Шаг расчетной сетки по широте в системе МСК-хх (прим. 1 единица МСК-хх равна смещению в 1м.)	Integer(1)	0	10
dlon	Шаг расчетной сетки по долготе в системе МСК-хх (прим. 1 единица МСК-хх равна смещению в 1м.)	Integer(1)	0	10
dz	Расстояние между вертикальными слоями в [м]	Integer(1)	0	2
min_lat	Нижняя граница расчетной области в системе МСК-хх	Integer(1)	0	512700
max_lat	Верхняя граница расчетной области в системе МСК-хх	Integer(1)	0	513830
min_lon	Левая граница расчетной области в системе МСК-хх	Integer(1)	0	2236670
max_lon	Правая граница расчетной области в системе МСК-хх	Integer(1)	0	2237470
target_day	Дата начала расчета	Timestamp(1)	-1	"2019-12-25"

Данные расчета модели

Данные содержатся в файлах папки proj/Computation

Модель	Наименование файла папки	Описание
GRAMM	ggeom.asc
GRAMM	windfeld.txt
GRAMM	landuse.asc
	csvfile_weather.csv

Описание выходных сообщений

Наименование	Описание
Выполнено успешно	{"status":200}

Отработка аварийных ситуаций

Под аварийной ситуацией понимается состояние программы когда один или все ее компоненты не отвечают.

Возможные варианты сбоев и способы их устранения

Наименование	Описание	Действия администратора
Нет ответа от сервиса	При запуске скрипта выходит сообщение: curl: (52) Empty reply from server	Убедитесь, что контейнер с сервисом запущен, для чего выполните команду как показано в проверки работы. В случае если контейнер отсутствует произведите запуск

Термины и сокращения

Наименование	Описание
docker-контейнер	Контейнер Docker — это формат пакетирования, который позволяет упаковать весь код и зависимости приложения в стандартный формат, чтобы приложение могло быстро и надежно запускаться в разных вычислительных средах.
docker-образ	Docker-образ — это read-only шаблон. Например, образ может содержать операционку Ubuntu c Apache и приложением на ней. Образы используются для создания контейнеров.
$HOME	Обозначение каталога который содержит склонированный из репозитория проект
git-репозиторий	Репозиторий Git — это виртуальное хранилище проекта. В нем можно хранить версии кода для доступа по мере необходимости
.NET Framework	программная платформа, выпущенная компанией Microsoft в 2002 году. Основой платформы является общеязыковая среда исполнения Common Language Runtime (CLR), которая подходит для различных языков программирования. Функциональные возможности CLR доступны в любых языках программирования, использующих эту среду. В настоящее время .NET Framework развивается в виде .NET.