4.1. Назначение и область применения

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

Документ рассчитан на разработчиков пользовательских моделей, администраторов поставки, сопровождающих библиотек и QA-специалистов. Для первого подключения достаточно пройти разделы 2-10. Разделы 11-14 используются при разработке моделей на конкретных языках и при разборе ошибок.

4.2. Как пользоваться руководством

  1. Определите, что именно включается: библиотека расчетных моделей, отдельная модель, Python-объект или комплект, содержащий несколько сущностей.

  2. Сверьте комплект поставки по разделу 5: без DLL, XML-паспортов, служебных описаний и теста подключение считается неполным.

  3. Разместите файлы по структуре раздела 6 и выполните ручную или автоматизированную регистрацию по разделам 8-9.

  4. Проверьте plugin_repository.xml, потому что именно там связываются пользовательский паспорт, путь к библиотеке и имя вызываемой процедуры.

  5. Выполните минимальный расчетный тест и зафиксируйте результат в TestReport или принятом внутреннем формате.

4.3. Роли и ответственность

Роль

Основные действия

Контроль результата

Ра зработчик

Формулирует модель, пишет код, готовит DLL/скрипт, XML-паспорта, справку и тест.

Имена модели, DLL, procedure, портов, параметров и рабочих переменных согласованы.

Адми нистратор / сопро вождающий

Размещает файлы в DINAMA, обновляет sysarm.xml и plugin_repository.xml, запускает armdoc/arm или утвержденный скрипт.

Библиотека видна, путь к DLL корректен, procedure указывает на экспортируемую функцию.

QA

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

Результат зафиксирован в TestReport; ошибки возвращены разработчику.

Release Manager

Принимает артефакты после QA и включает их в выпускной поток.

В выпуск попадает проверенный комплект, а не локальная отладочная копия.

4.4. Ключевые понятия

Понятие

Краткое объяснение

PRADIS

Расчетный комплекс, расширяемый пользовательскими моделями и объектами.

DINAMA

Каталог или среда поставки, где размещаются исполняемые библиотеки, XML-описания и служебные файлы.

Библиотека моделей

Группа моделей, поставляемая как общий исполняемый и описательный комплект.

Модель

Расчетный элемент, вызываемый решателем; формирует силовые вклады, рабочие величины и производные.

Объект

Пользовательский объект, связанный с XML-паспортом и, в предоставленных материалах, с Python-реализацией.

XML-паспорт

Файл описания библиотеки, модели или объекта для интерфейса: имя, порты, параметры, символ, описание.

DLL

Исполняемая библиотека с программной реализацией модели или набора моделей.

DEF-файл

Файл объявления экспортируемых процедур при сборке DLL.

sysarm.xml

Общий список разделов и библиотек, отображаемых в DINAMA.

plugin_r epository.xml

Файл связи между паспортом модели, путем к DLL и именем вызываемой процедуры.

armdoc / arm

Инструменты регистрации, упомянутые в исходных материалах; точный синтаксис нужно сверить с целевой версией.

4.5. Состав комплекта поставки

Разработчик передает не один файл, а комплект, достаточный для сборки, регистрации, отображения, запуска и проверки модели. Неполный комплект приводит к тому, что модель может быть видна в интерфейсе, но не запускаться, или запускаться без воспроизводимого теста.

Компонент

Назначение

Что проверить

DLL

Скомпилированная библиотека моделей.

Имя и разрядность соответствуют PRADIS/DINAMA; путь совпадает с library.

Исходный код

Основа сопровождения и повторной сборки.

Код соответствует передаваемой DLL.

DEF-файл

Описание экспортируемых процедур.

Имена совпадают с procedure.

XML-паспорт библиотеки

Описание состава библиотеки.

Содержит все модели и объекты поставки.

XML-паспорт модели

Порты, параметры, рабочие переменные, символ, описание.

Согласован с кодом и использует корректную кодировку.

.for-описание

Служебное описание модели, упомянутое в исходных схемах.

Точная роль требует проверки для целевой версии.

Python-файл

Реализация объекта или Python-модели.

Путь размещения и API вызова подтверждены.

Справка

Поясняет назначение, параметры, ограничения и тест.

Пользователь понимает, когда применять модель.

Минимальный тест

Проверяет подключение и базовую физику модели.

Есть ожидаемый результат и диагностические сценарии.

4.6. Структура каталогов DINAMA

DINAMA/

plugin/ DLL пользовательских библиотек

plugin/python/pradis/<LibraryName>/ Python-реализации объектов или моделей

sysarm/

plugin_repository.xml связь модели, DLL и procedure

XML/

sysarm.xml общий список разделов и библиотек

<LibraryName>/

<LibraryName>.xml паспорт библиотеки

Model/<NameModel>.xml паспорт модели

Object/<NameObject>.xml паспорт объекта

Уточнение. Пути Python-плагинов, назначение .for-файлов, NEWOBJECT.sch, ПГО и ПРВП нужно сверить с актуальной поставкой. В этом руководстве они описаны только в объеме, подтвержденном предоставленными фрагментами.

4.7. Типовой маршрут: есть новая модель

  1. Проверить постановку задачи: физический смысл, порты, параметры, единицы измерения, ограничения и ожидаемый результат.

  2. Собрать или получить готовую DLL библиотеки модели либо подготовить Python-файл, если целевой механизм использует Python.

  3. Подготовить XML-паспорт библиотеки и XML-паспорта моделей или объектов.

  4. Разместить DLL в DINAMA/plugin; Python-файлы разместить в подтвержденном каталоге Python-плагинов.

  5. Разместить паспорта в DINAMA/sysarm/XML/<LibraryName> и подпапках Model/Object.

  6. Обновить sysarm.xml и выполнить регистрацию через armdoc/arm или утвержденный скрипт.

  7. Проверить plugin_repository.xml: путь library, имя procedure, имя модели и фактическую DLL.

  8. Открыть PRADIS/DINAMA и убедиться, что библиотека, модель, порты, параметры и символ отображаются корректно.

  9. Запустить минимальный расчетный пример и диагностические сценарии.

  10. Зафиксировать результат QA в TestReport или принятой внутренней форме.

4.8. Ручное включение библиотеки моделей

Ручной способ удобен при первичном подключении, локальной отладке и разборе ошибок автоматизации. Он показывает, какие файлы участвуют в процессе и какие связи должны появиться.

** Исполнитель**

Действия

Разработчик

Компилирует библиотеку; проверяет экспорт procedure; передает DLL, XML-паспорта, служебные описания, справку и минимальный тест.

Администратор

Копирует DLL в DINAMA/plugin; размещает XML в DINAMA/sysarm/XML/<LibraryName>; добавляет раздел библиотеки в sysarm.xml; обновляет или проверяет plugin_repository.xml.

QA

Проверяет видимость модели, соответствие параметров и портов паспорту, запуск минимального расчета и диагностические сообщения.

4.9. Автоматизированное включение библиотеки моделей

Автоматизированный способ использует armdoc/arm или заменяющие их скрипты. Он снижает объем ручной работы, но не отменяет проверку результата.

  1. Сложить <LibraryName>.xml, <NameModel>.xml, служебные описания и сопутствующие файлы в общую рабочую папку.

  2. Выполнить команды вида armdoc -a <LibraryName> и armdoc -a <NameModel> или утвержденный скрипт регистрации.

  3. Проверить, что обновлены sysarm.xml, паспорт библиотеки и папка Model.

  4. Выполнить команды вида arm + <NameModel> и arm ! <NameModel> или эквивалентную процедуру связи.

  5. Проверить plugin_repository.xml и путь к DLL.

  6. Запустить минимальную расчетную схему.

Важно. Если armdoc создал путь вида ../plugin/<NameModel>, а фактическая реализация находится в общей библиотеке NEWLIBRARY.dll, путь нужно заменить на ../plugin/NEWLIBRARY. Иначе PRADIS будет искать библиотеку по имени модели, а не по имени общей DLL.

4.10. XML-паспорта библиотеки, модели и объекта

XML-паспорт нужен для того, чтобы PRADIS/DINAMA мог показать пользователю библиотеку, модель, порты, параметры, описание и символ. Сам по себе паспорт не гарантирует запуск расчета: запуск зависит от корректной связи с исполняемым кодом.

Фрагмент

Назначение

Контроль

<module> / <library>

Описание раздела или библиотеки.

Имя совпадает с каталогом <LibraryName>.

<model>

Отдельная расчетная модель.

name, module, image, ext, par, wrk согласованы с кодом.

<description>

Русское и английское описание.

Текст понятен пользователю и не противоречит справке.

<nod elist>/<node>

Порты модели.

Номера, имена и типы соответствуют реализации.

< parameterlist >/<parameter>

Параметры модели.

Типы base.*, default и единицы согласованы с кодом.

<worklist>

Рабочие переменные.

Показаны только реально используемые величины.

<statelist>

Состояния модели.

Заполнен только при реальном использовании состояний.

<image2d>

Графический символ.

.PortSym соответствует номерам из nodelist.

<object>

Пользовательский объект.

Паспорт связан с Python-файлом или другим подтвержденным механизмом реализации.

4.11. plugin_repository.xml: связь модели с исполняемым кодом

plugin_repository.xml является ключевым местом связи между пользовательским описанием и исполняемым кодом. XML-паспорт может позволить интерфейсу показать модель, но расчет не запустится, если связь с DLL или procedure задана неверно.

<!– Условный пример для проверки структуры, не нормативный XML-формат –>

<component model=»NameModel»>

<library>../plugin/NEWLIBRARY</library>

<procedure>NAMEMODEL</procedure>

</component>

  • library должен указывать на фактическую DLL без подмены имени модели на имя библиотеки.

  • procedure должен совпадать с экспортируемой процедурой в DLL или с подтвержденным именем Python-адаптера.

  • Имя модели в паспорте, имя записи в plugin_repository.xml и имя процедуры должны быть проверены как единая цепочка.

  • После любой автоматической генерации plugin_repository.xml нужно открыть и проверить вручную или автоматическим тестом.

4.12. Добавление объекта

Объект отличается от расчетной модели тем, что в предоставленных материалах он связан не только с XML-описанием, но и с Python-реализацией. Поэтому проверяется пара: паспорт объекта и соответствующий .py-файл.

  1. Подготовить <NameObject>.xml.

  2. Подготовить <NameObject>.py или другой файл реализации, если целевой механизм отличается.

  3. Разместить XML-паспорт в DINAMA/sysarm/XML/<LibraryName>/Object.

  4. Добавить запись об объекте в паспорт библиотеки.

  5. Разместить Python-файл в DINAMA/plugin/python/pradis/<LibraryName> или другом подтвержденном каталоге.

  6. Проверить соответствие имени XML-паспорта, имени Python-файла и записи библиотеки.

  7. Открыть PRADIS/DINAMA и выполнить минимальную проверку загрузки объекта.

Уточнение. В исходной схеме упоминается NEWOBJECT.sch и вопрос о генерации .py. Механизм генерации или связи нужно подтвердить отдельно перед включением в нормативную инструкцию.

4.13. Сквозной пример SV2K

SV2K используется как учебный пример связи паспорта с кодом. Модель описывает идеально упругую 2-D связь между двумя точками по поступательным степеням свободы. Параметры pA и pB задают начальные координаты, K задает коэффициент жесткости, а WRK хранит продольное усилие и начальную длину.

Данные паспорта

Фрагмент реализации

Смысл

Port1, Port2 type=base.XY

X1, X2, X3, X4

Две точки по две поступательные степени свободы.

pA, pB

PAR(1)..PAR(4) / PAR[0]..PAR[3]

Начальные координаты точек A и B.

K

PAR(5) / PAR[4]

Коэффициент жесткости.

wrk=2

WRK(1), WRK(2) / WRK[0], WRK[1]

Продольное усилие и сохраненная начальная длина.

Проверки параметров

NEWINT или initialize()

Однократная проверка длины и допустимости K.

Диагностика

CODE/NAME или ModelStatus

Сообщение о невозможности продолжить расчет.

K = PAR(5)

U = LT - L

WRK(1) = K * U

I(1..4) = проекции осевого усилия на степени свободы

Y(1..16,1) = производные сил по перемещениям

4.14. Разработка модели на Fortran

Обновлено. Fortran-раздел используется как базовый ориентир по расчетному контракту: массивы I, Y, X1..X4, PAR, WRK и COMMON-блоки связывают модель с вычислительным ядром.

4.14.1. Интерфейс

SUBROUTINE SV2K (I, Y, X1, X2, X3, X4, PAR, WRK)

** Аргумент**

Назначение

I

Вектор силовых вкладов модели. Для 2D-связи используются четыре компоненты.

Y

Элементы якобиана, то есть производные сил по перемещениям.

X1, X2

Текущие перемещения точки A по X и Y.

X3, X4

Текущие перемещения точки B по X и Y.

PAR

Параметры модели: pA, pB и K.

WRK

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

4.14.2. Алгоритм

  1. При NEWINT=1 проверить начальную длину и жесткость K.

  2. Сохранить начальную длину L в WRK.

  3. На каждом вызове вычислить текущие координаты точек A и B.

  4. Найти текущую длину LT, направление связи, деформацию U=LT-L и усилие N=K*U.

  5. Записать силовые вклады в I и элементы якобиана в Y.

  6. При вырождении длины вернуть диагностическое состояние через CODE и NAME.

Проверить. Состав COMMON-блоков приведен по учебному примеру. Перед выпуском официального шаблона нужно сверить актуальный состав переменных и соглашение вызова с целевой версией PRADIS.

4.15. Разработка модели на C

Новое. C-раздел показывает, как отразить Fortran-совместимый вызов в виде C-функции: указатели на массивы, нумерация с нуля, экспорт имени и доступ к COMMON-областям через внешние символы.

void SV2K_C(double *I, double *Y, double *X1, double *X2,

double *X3, double *X4, double *PAR, double *WRK);

Что проверить

Почему важно

Имя SV2K_C экспортируется из DLL

Иначе модель может отображаться, но не запускаться.

procedure совпадает с экспортом

Регистратор должен связать паспорт с фактической процедурой.

library указывает на нужную DLL

Иначе будет вызвана не та реализация или загрузка завершится ошибкой.

Разрядность DLL совпадает с PRADIS

32/64-битная несовместимость приводит к ошибке загрузки.

Индексация PAR/WRK переведена корректно

Fortran PAR(1) соответствует C PAR[0].

COMMON-структуры сверены

Ошибки выравнивания или имен символов могут повреждать память.

LIBRARY NEWLIBRARY

EXPORTS

SV2K_C

Проверить. Соглашение вызова C ABI, регистр имени, нижние подчеркивания, cdecl/stdcall, имена COMMON-символов и упаковку структур нужно брать из официального C-шаблона или актуальной сборки PRADIS.

4.16. Разработка модели или объекта на Python

Уточнение. Python-реализация в исходных материалах разделена на расчетную часть и адаптер. Расчетная логика может тестироваться автономно, но точный API подключения к PRADIS/DINAMA должен быть подтвержден отдельно.

Часть

Назначение

S V2KPy.initialize

Однократная проверка параметров и сохранение начальной длины.

SV2KPy.calculate

Основной расчет сил, якобиана, рабочего вектора и статуса.

ModelStatus

Учебная форма диагностического результата: код, имя модели и сообщение.

ca lculate(context)

Предполагаемый адаптер, который должен быть заменен на официальный API PRADIS/DINAMA.

co ntext.parameters

Условный источник пользовательских параметров pA, pB, K.

context.nodes

Условный источник текущих перемещений портов Port1 и Port2.

  1. Подготовить Python-файл с расчетным классом и адаптером вызова.

  2. Подготовить XML-паспорт модели или объекта.

  3. Разместить Python-файл в каталоге, предусмотренном для пользовательских Python-объектов или Python-моделей.

  4. Разместить XML-паспорт в соответствующем XML-каталоге DINAMA.

  5. Обновить sysarm.xml или другую структуру регистрации, если это требуется целевой версией.

  6. Проверить связь имени модели, Python-файла и XML-паспорта.

  7. Запустить автономный тест расчетной логики и минимальный интеграционный тест PRADIS/DINAMA.

Проверить. В предоставленных материалах нет подтвержденной сигнатуры Python-модели PRADIS. Поэтому calculate(context), context.parameters, context.nodes и context.constants являются учебным адаптером, а не нормативным API.

4.17. Тестирование после включения

Область

Что проверить

Интерфейс

Библиотека видна в нужном разделе; модель отображается с корректным названием, описанием, портами, параметрами и символом.

Регистрация

sysarm.xml содержит раздел библиотеки; <LibraryName>.xml содержит модель; plugin_repository.xml содержит корректные library и procedure.

Расчет

Минимальная расчетная схема строится и запускается; простой тест дает ожидаемый результат.

Диагностика

Некорректные параметры возвращают понятное диагностическое сообщение или код состояния.

Регрессия

Стандартные тесты PRADIS проходят после добавления новой библиотеки.

4.17.1. Минимальный тест SV2K

Параметр

Значение

Ожидаемый смысл

pA

(0, 0)

Начальная точка A.

pB

(1, 0)

Начальная точка B, начальная длина L=1 м.

K

1000 Н/м

Жесткость связи.

Перемещение B по X

0.001 м

Растяжение на 1 мм.

Ожидаемое усилие

около 1 Н

N = K * U = 1000 * 0.001.

Диагностика

K<0 и нулевая длина

Модель возвращает диагностическое состояние.

4.18. Типовые ошибки и диагностика

Симптом

Вероятная причина

Что проверить

Модель не видна

Не обновлен sysarm.xml или паспорт библиотеки.

Раздел <LibraryName>, запись модели в <LibraryName>.xml.

Модель видна, но не запускается

Неверная связь с DLL.

plugin_repository.xml, library, procedure.

Ошибка загрузки DLL

DLL отсутствует или несовместима.

DINAMA/plugin, зависимости, разрядность, экспорт имен.

Параметры неверны

Ошибка XML-паспорта.

parameterlist, типы base.*, default, UTF-8.

Порты или символ неверны

Ошибка nodelist или image2d.

Номера портов, .PortSym, image.

Python-объект не найден

Не совпадают XML и .py или неверен путь.

Object/<Name>.xml и plugin/python/pradis/ <LibraryName>/<Name>.py.

Расчет плохо сходится

Не заполнен или несогласован якобиан.

Y в Fortran/C или формат jacobian в Python API.

Диагностика не работает

Неверные CODE/NAME, COMMON или адаптер статуса.

COMMON-блоки, ModelStatus, обработку ошибок.

4.19. Процесс разработки, QA и выпуска

N

Исполнитель

Действие

Контроль

1

PM

Создает задачу и назначает разработчика.

Есть формальное задание.

2

Разработчик

Готовит код, паспорта, справку и тесты.

Комплект готов к проверке.

3

Разработчик

Передает изменения на QA.

QA получает воспроизводимый материал.

4

QA

Обновляет TestPlan и выполняет проверку.

Есть согласованный сценарий.

5

QA

Формирует TestReport.

Результат OK/NotOK зафиксирован.

6

Ответственный

При успешной проверке включает комплект в dev/выпускной поток.

Ф ункциональность попадает в управляемую поставку.

Уточнение. Если в организации используется GitLab CI, Nexus, Redmine или иной pipeline, раздел нужно синхронизировать с фактическим процессом. Исходные материалы подтверждают общий маршрут: разработка, артефакты, QA, TestReport, решение о выпуске.

4.20. Требования к справке новой модели

  • Назначение модели и область применения.

  • Порты: имя, тип, физический смысл.

  • Параметры: имя, тип, единицы, значение по умолчанию, ограничения.

  • Рабочие переменные и состояния, если они доступны пользователю.

  • Пример подключения в расчетной схеме.

  • Ожидаемый результат и простой верификационный тест.

  • Ограничения, особые случаи и диагностические сообщения.

  • Версия библиотеки или дата редакции, если это принято в поставке.

4.21. Контрольные списки

4.21.1. Для разработчика

  • Постановка задачи описана: физический смысл, параметры, ограничения.

  • Сигнатура модели соответствует ожидаемому интерфейсу PRADIS.

  • Порты и параметры XML-паспорта согласованы с индексами PAR или именами Python-параметров.

  • Рабочий вектор WRK согласован с атрибутом wrk паспорта.

  • В коде есть проверки начальной длины, допустимости K и других ограничений.

  • Заполняются силовые вклады I и элементы якобиана Y, если они требуются расчетным API.

  • Подготовлены XML-паспорт, справка, минимальный тест и ожидаемый результат.

  • Для C проверены экспорт имени, ABI, разрядность и COMMON-структуры.

  • Для Python подтверждены путь размещения и официальный API адаптера.

4.21.2. Для администратора

  • DLL размещена в DINAMA/plugin.

  • XML-паспорта размещены в DINAMA/sysarm/XML/<LibraryName>.

  • Python-файлы, если они есть, размещены в подтвержденном каталоге.

  • sysarm.xml содержит раздел библиотеки.

  • plugin_repository.xml содержит корректный путь library и procedure.

  • Автоматическая регистрация проверена вручную или тестом.

4.21.3. Для QA

  • PRADIS/DINAMA запускается без ошибок загрузки новой библиотеки.

  • Библиотека и модель видны в интерфейсе.

  • Порты, параметры, значения по умолчанию и символ соответствуют паспорту.

  • Минимальный расчет запускается и дает ожидаемый результат.

  • Ошибочные параметры вызывают диагностическое состояние.

  • Регрессионные тесты PRADIS не нарушены.

  • Результат проверки зафиксирован.

4.22. Сведения, требующие уточнения перед нормативным выпуском

Тема

Что требует проверки

Влияние

Целевая версия PRADIS/DINAMA

Какая версия является целевой для руководства.

Критично для выпуска.

armdoc / arm

Официальный синтаксис команд и пример .bat-файла.

Критично для разделов регистрации.

plugin_r epository.xml

Актуальный формат обязательных полей и связь с armctlg.

Критично для запуска модели.

.for-файл

Исходник, паспорт старого формата или вход для armdoc.

Желательно уточнить.

COMMON-блок

Актуальный состав переменных для целевой версии PRADIS.

Критично для Fortran/C шаблонов.

C ABI

Соглашение вызова, регистр имени, подчеркивания, cdecl/stdcall.

Критично для C-моделей.

Python API

Официальная сигнатура вызова Python-модели или объекта.

Критично для P ython-раздела.

Каталоги Python

Где размещаются Python-файлы и их XML-паспорта.

Критично для установки.

NEWOBJECT.sch

Назначение и механизм связи с Python-объектами.

Желательно уточнить.

ПГО/ПРВП

Включать в это руководство или вынести отдельно.

Лучше вынести в отдельный документ.

Формат теста

Официальный формат минимальной расчетной схемы.

Желательно добавить в приложение.

4.23. ПРИЛОЖЕНИЕ - Пример структуры комплекта

Package/

NEWLIBRARY.dll

NewLibrary.cpp

NewLibrary.def

LibraryName.xml

NameModel1.xml

NameModel1.for

NameModel2.xml

NameModel2.for

help/

NameModel1.html

tests/

minimal_case/

objects/

NEWOBJECT.xml

NEWOBJECT.py

DLL размещается в DINAMA/plugin. XML-паспорта библиотеки, моделей и объектов размещаются в DINAMA/sysarm/XML. Справка и тесты используются для проверки и сопровождения. Если объект реализован на Python, его .py-файл размещается в подтвержденном каталоге Python-плагинов библиотеки.

4.24. Глоссарий

Термин

Описание

ПГО

Постпроцессорный графический объект; в исходных материалах отмечен как продвинутая тема.

ПРВП

Пользовательская процедура вывода/постобработки; точная трактовка требует сверки с документацией.

TestPlan

План тестирования новой модели или библиотеки.

TestReport

Отчет о результатах проверки.

Nexus

Хранилище артефактов сборки, если используется в процессе организации.

GitLab CI

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

Redmine

Система задач и фиксации статусов, если используется в процессе организации.