Программа PlanarRT_H — API-документация

Пакет TMC Suite. Счётное ядро для электродинамического расчёта планарных структур в H-поляризации (скалярная задача) во временно́й области. Выходной файл: tmc_rth.exe. Язык документации: русский. Все сигнатуры приведены по исходникам из src/kernels/PlanarRT_H/ и общим заголовкам из src/Include/.

Примечание про общий код H и X. PlanarRT_H и PlanarRT_X — это две копии одной кодовой базы (папки src/kernels/PlanarRT_H/ и src/kernels/PlanarRT_X/). Бо́льшая часть файлов в копиях побайтно идентична, но вычислительное ядро различается по содержимому (см. planar_rt_x.md, §2): в X-копии методы тактов 2/3 добавлены прямо в код, без условной компиляции. Содержательно различаются файлы: - TmcRTHRectNode.cpp/.h — 4 подшага вместо 2, массивы большего размера; - TmcRTHNodeDiel.cpp/.h — структура узла без rUo, методы тактов 2/3, блоки *_STAT_Y; - PlanRT_H.cpp — единственное отличие: SetRegistryKey("PlanarRT_H") SetRegistryKey("PlanarRT_X") (раздел реестра настроек).

Остальные файлы (PlanRT_HView.cpp, TmcDialogStatistics.cpp) различаются только пробельными символами. Данная документация описывает H-вариант (2 подтакта на цикл 1T).

---

1. Назначение программы

PlanarRT_H (tmc_rth.exe) — счётное ядро пакета TMC Suite, выполняющее электродинамический расчёт планарных (двумерных) структур в поляризации H (скалярная задача — одна компонента поля H_z).

Ядро решает задачу распространения электромагнитных волн в двумерном пространстве с произвольным распределением диэлектрической проницаемости (ε), магнитной проницаемости (μ) и проводимости (σ) на основе уравнений Максвелла в конечно-разностной формулировке во временно́й области.

Программа построена по схеме MFC Document/View (MDI). Каждый документ — это .tpl-шаблон (template), описывающий топологию расчётной области, параметры расчёта и выходные данные. Программа умеет:

• читать .tpl-шаблоны (с препроцессингом через библиотеку PREPR);
• строить расчётную сетку (nX × nY узлов) и присваивать каждому узлу диэлектрические параметры;
• выполнять пошаговый или полный расчёт (Run Step / Run All) в отдельном рабочем потоке;
• записывать выходные данные: временно́е описание сигнала (.t), распределение поля (.ex), топологию (.tt), S-матрицу (.s);
• экспортировать данные для расчёта диаграммы направленности (ExportToDirectionalPatter, реализация — CFieldIntegrated библиотеки TMCIndan);
• воспроизводить звуковые эффекты при завершении шага/расчёта (настраиваемые мелодии);
• запускать внешние вьюверы (TMCROS — сигнал, TMCGROUT — S-матрица, FieldView — поле, TMC_DN — диаграмма направленности) и внешний редактор.

H-поляризация — скалярная задача: на каждом узле сетки хранится одно значение поля. Алгоритм использует 2 подтакта на каждый временно́й цикл 1T (в X-моде — 4, см. planar_rt_x.md).

---

2. Состав проекта

Файл проекта: PlanRT_H.vcxproj (имя проекта PlanRT_H, цель <TargetName>tmc_rth</TargetName>).

Кросс-проектные файлы (компилируются как часть проекта, подтверждено в .vcxproj):

Зависимости (AdditionalDependencies): sfile95.lib, prepr.lib, exprint.lib, TMCIndan.lib, TMCLibError.lib.

Препроцессорные определения: WIN32;_WINDOWS;DEBUG__1 (плюс _DEBUG/NDEBUG по конфигурации). Дополнительных макросов X-моды у H-проекта нет.

Общие заголовки из src/Include/ (перечислены в .vcxproj как ClInclude, но физически находятся в общем каталоге и документируются отдельно):

Файлы вне сборки (legacy). В каталоге src/kernels/PlanarRT_H/ физически присутствуют, но НЕ включены в PlanRT_H.vcxproj (нет ни ClCompile, ни ClInclude):

---

3. Ключевые типы и константы (заголовок src/Include/Typerth.h)

3.1. Точность вычислений

//#define _PREC_DOUBLE          // выключено
#define _PREC_FLOAT             // включено: точность float

#ifdef _PREC_FLOAT
#define _real float             // базовый тип точности
#endif

#define _ELEM_VAL_RTH_REAL      // включено: элемент поля — вещественный
//#define _ELEM_VAL_RTH_INT     // выключено: целочисленный вариант (с множителем 1024*1024)

#ifdef _ELEM_VAL_RTH_REAL
#define _ELEM_VAL_RTH _real     // тип элемента поля = float
#define _ELEM_VAL_RTH_MULT 1
#endif

Также в Typerth.h выбран вариант сборки _VERSION_PROF___ (закомментированы _VERSION_DEMO___ и _VERSION_EDUC___).

3.2. Физические константы

ELECTRON_Q___ и ELECTRON_M___ — это константы, а не переключатели режима. Подробнее об их роли в X-моде и о макросах проекта X — planar_rt_x.md, §2.

3.3. Типы узлов (nType)

Значения поля nType структуры узла и блока (совпадают со значениями nType класса CTmcRTH_Input библиотеки TMCIndan):

3.4. Глобальные функции Typerth.h (реализация — PL_GLFUN.CPP)

3.5. Глобальные функции Pl_iofor.h (реализация — Pl_iofor.cpp)

Форматы текстового вывода (по умолчанию заданы константами FORMAT_OUT_FILE_*):

---

4. Структуры данных узлов (TmcRTHNodeDiel.h)

4.1. sTmcRTHNodeDielOne — узел (H-поляризация, 2 такта)

struct STMCRTH_NODEDIELONE
{
    _ELEM_VAL_RTH rU;       // падающее напряжение на диэлектрике (такт 0)
    _ELEM_VAL_RTH rU_Cur;   // текущее напряжение
    _ELEM_VAL_RTH rU_Cur1;  // напряжение такта «текущий+1»
    _ELEM_VAL_RTH rUo;      // рассеянное напряжение (для входов)
    _real rY;               // проводимость узла
    int   nNodeGlobal;      // номер узла в глобальной топологии
    int   nType;            // тип узла (см. §3.3)
};
typedef struct STMCRTH_NODEDIELONE sTmcRTHNodeDielOne;

В H-варианте — 4 компоненты напряжения (rU, rU_Cur, rU_Cur1, rUo). В X-варианте — 8 (rU..rU3, rU_Cur..rU_Cur3), а поле rUo отсутствует (см. planar_rt_x.md, §3.1).

4.2. sTmcRTH_DielNodeList — односвязный список узлов

struct STMCRTH_DIELNODELIST
{
    STMCRTH_DIELNODELIST * pcDielNodeNextList;  // следующий элемент списка
    sTmcRTHNodeDielOne   * pcNodeDielOne;       // узел
};
typedef struct STMCRTH_DIELNODELIST sTmcRTH_DielNodeList;

---

5. Класс CTmcRTHRectNode — вычислительное ядро

Назначение: управление расчётной сеткой, выполнение шагов расчёта во временно́й области, рассеяние, возбуждение входов, запись выходных файлов и расчёт S-матрицы. Заголовок: TmcRTHRectNode.h · Базовый класс: CWnd Зависит от: Typerth.h, TmcRTHNodeDiel.h, TmcLibError.h, TmcRTH_Indan.h, TmcRTH_IndanParam.h

5.1. Поля (private)

Выделение массивов (InitNodeArray): запрашивается 2*nNumNode + 32 элементов (по 2 значения на узел плюс запас), после чего рабочий указатель смещается так, чтобы адрес был кратен 32 — выравнивание для эффективного доступа. В X-варианте — 6*nNumNode + 32 (по 6 значений на узел).

5.2. Публичные методы

Примечание к названию: ExportToDirectionalPatter — так в коде (без конечной n); внутренняя функция TMCIndan называется ExportToDirectionalPattern.

5.3. Приватные методы

Чтение и инициализация:

Расчётный цикл:

Вывод:

5.4. Алгоритм одного цикла 1T (H-поляризация, 2 подтакта)

Точная последовательность из RunKernel1T() (TmcRTHRectNode.cpp:537):

Подтакт 0:
  RunExciteInputs();          // возбуждение входов
  RunScatteringNode();        // рассеяние на узлах
  RunBlockNode();             // обработка блоков
  PutField( 0 );              // запись поля
  DistributionIntegrated(0);  // накопление для ДН
  nTCurrent++;  dTCurrent += dT;

Подтакт 1:
  RunExciteInputs1();
  RunScatteringNode1();
  RunBlockNode1();
  PutField( 1 );
  DistributionIntegrated(1);
  nTCurrent++;  dTCurrent += dT;

Счётчик nTCurrent увеличивается внутри каждого подтакта на 1 (итого +2 за цикл 1T). По завершении главного цикла RunKernel вызывает PutSmatrix().

В X-моде: 4 подтакта (+4 за цикл), вызовы DistributionIntegrated закомментированы (см. planar_rt_x.md, §4).

---

6. Класс CTmcRTHNodeDiel — блоки топологии

Назначение: представление одного блока топологии (прямоугольник, круг, полигон; диэлектрик, металл, магнетик, поглотитель, вход) — список его узлов, проводимости, возбуждение входов. Заголовок: TmcRTHNodeDiel.h · Базовый класс: CWnd

6.1. Поля (private)

6.2. Публичные методы

В X-варианте дополнительно: ExciteInputs2/3, RunBlockNode2/3 (см. planar_rt_x.md, §5).

6.3. Приватные методы (по типам блоков)

Все методы Set* принимают CTmcRTH_BlockList *pcNextBlockList (описание блока) и CTmcRTH_IndanParam &cParam (параметры), возвращают CTmcLibError&; SetRect/SetRectFile дополнительно принимают CString csCurrentPath, методы входов — CTmcRTH_IndanOutput *cOut.

Вспомогательные приватные методы:

6.4. Формат .eps-файла (распределение ε)

Константы формата определены в начале TmcRTHNodeDiel.h:

#define TMC_RTH_EPSFILE_EXT_   "eps"
#define TMC_RTH_EPSFILE_ID_    "#TamicRTH_planar_DistributionDielectricPermeability_File_V2.00 2000"
#define TMC_RTH_EPSFILE_TYPE_  "#TopologyPrimitiv "
#define TMC_RTH_EPSFILE_Delta_ "#dDelta "
#define TMC_RTH_EPSFILE_XMIN_  "#Xmin "
#define TMC_RTH_EPSFILE_YMIN_  "#Ymin "
#define TMC_RTH_EPSFILE_NX_    "#nX "
#define TMC_RTH_EPSFILE_NY_    "#nY "
#define TMC_RTH_EPSFILE_NPoint_ "#nPoint "
#define TMC_RTH_EPSFILE_NAccur_ "#nAccuracy "
#define TMC_RTH_EPSFILE_NdFrmt_ "#sNodeFormat "
#define TMC_RTH_EPSFILE_VlFrmt_ "#sValueFormat "

Файл начинается с идентификатора #TamicRTH_planar_..., далее — параметры сетки (#dDelta, #Xmin, #Ymin, #nX, #nY, число точек, точность, форматы узла/значения), затем данные.

Точная раскладка. Заголовок — текстовый, каждая строка завершается парой байт 13, 10 (CR LF). Пробел после метки значим. Порядок и смысл полей (сверено с авторским описанием Tamic\TMC\DISTR\MANUALS\RT_HPLANAR\FormEps.doc, 1999, и с кодом TmcRTHNodeDiel.cpp:6811 — запись, :7227 — чтение):

Далее — бинарный массив из #nPoint записей. Каждая запись:

Итого размер массива — #nPoint * (#nAccuracy + 4) байт: 12 байт на точку для двойной точности, 8 — для одинарной.

Записывается не «чистая» ε, а взвешенное значение. В TmcRTHNodeDiel.cpp:6837–6847 поле rY инициализируется единицей, затем делится пополам на каждой границе примитива (i == 0, i == nY-1, j == 0, j == nX-1 — то есть у рёбер коэффициент 0.5, в углах 0.25) и лишь потом умножается на CalcEps(x, y). Не интерпретируйте содержимое как ε напрямую.

Совместимость float double. Читатель сверяет #nAccuracy с sizeof(_real) и при несовпадении конвертирует (TmcRTHNodeDiel.cpp:7354 и ветка case 4: — чтение во float с расширением до _real). Поэтому .eps, созданные старой одинарной сборкой, читаются текущей двойной. Допустимы только значения 4 и 8 — иначе ошибка nAccuracy = %d != 4 and != 8.

---

7. Класс CPlanRT_HDoc — документ

Назначение: управление расчётом (через cRectNode), запуск внешних программ, хранение настроек. Заголовок: PlanRT_HDoc.h · Базовый класс: CDocument

7.1. Поля (private)

7.2. Настройки в реестре

Раздел задаётся в InitInstance: SetRegistryKey("PlanarRT_H"). Имена параметров — константы в PlanRT_HDoc.h:

7.3. Методы

Управление расчётом:

Флаги вывода и звука (делегируют cRectNode): GetTopologyFlag(), GetSoundEffect(), GetFieldFlag(), GetSinchronizationFieldOutput(), PutTopology(), SetSoundFlag(int), OnOffSoundEffects(), SetOutFieldOutFlag(int), SetOutSinchrFieldOutFlag(int), OnOffSinchronizationFieldOutput(), OnOffFieldOutput().

Внешние программы:

Переопределения MFC: OnNewDocument(), Serialize(CArchive&), OnCloseDocument(), CanCloseFrame(CFrameWnd*).

---

8. Класс CPlanRT_HView — вид

Назначение: обработчики меню/тулбара, отрисовка фона окна документа. Заголовок: PlanRT_HView.h · Базовый класс: CScrollView

8.1. Поля (private)

Приватные методы: OnDrawBackground(CDC*), ReadData(), WriteFile().

8.2. Команды меню (обработчики afx_msg)

Меню Run:

Меню View:

Меню Config:

Прочее: OnEditEdit (открыть .tpl в редакторе), OnFileSaveAs, OnClose, OnDestroy, публичный Stop(void).

Обработчики OnUpdate* (доступность пунктов меню): OnUpdateConfigSinchronization, OnUpdateViewField, OnUpdateConfigSound, OnUpdateViewTopology, OnUpdateViewField1, OnUpdateRunRun, OnUpdateRunRestartall, OnUpdateRunStartstep, OnUpdateRunRestartstep, OnUpdateRunSkipstep, OnUpdateRunBackstep, OnUpdateRunStop, OnUpdateFileClose, OnUpdateConfigAutorun, OnUpdateViewDirectionalpattern.

Переопределения MFC: OnDraw(CDC*), PreCreateWindow, DestroyWindow, OnInitialUpdate, OnPreparePrinting, OnBeginPrinting, OnEndPrinting.

---

9. Диалоги

В сборку входят пять диалоговых классов (подтверждено по PlanRT_H.vcxproj). Класс CTmcErrorMessage в сборку не входит — см. §2, «Файлы вне сборки».

9.1. CTmcRTH_DialogBlock — информация о блоке топологии

Назначение: просмотр параметров одного блока топологии (тип, координаты вершин, выражение ε, скорости движения) с навигацией «предыдущий/следующий блок». Заголовок: TmcRTH_DialogBlock.h · Базовый класс: CDialog · Ресурс: IDD_TMC_RTH_TOPBLOCK

Поля (public):

Поля DDX (обмен с элементами диалога):

Методы:

9.2. CTmcRTH_DialogFormatOutFile — формат выходных данных

Назначение: настройка printf-форматов столбцов выходных текстовых файлов (см. §3.5). Заголовок: TmcRTH_DialogFormatOutFile.h · Базовый класс: CDialog · Ресурс: IDD_TMC_CONFIG_OUTFFORMAT

Поля (public): BOOL IsSetDefaultFormat — признак сброса к форматам по умолчанию.

Поля DDX:

Методы:

9.3. CTmcDialogStatistics — статистика расчёта

Назначение: сводка по текущему шагу расчёта: число узлов/блоков, память, физические параметры, размеры области в длинах волн, точность. Заголовок: TmcDialogStatistics.h · Базовый класс: CDialog · Ресурс: IDD_TMC_STATISTICS

Поля (public): CString csAccuracy (точность); int nFlagStep (флаг шага). Поля (private): CTmcRTH_BlockList * pcBlockList — блок для окна информации.

Поля DDX:

Методы:

Известный баг: кнопка статистики не работает в новых версиях H и X (окно не вызывается, приложение закрывается, при компиляции — предупреждения). См. ISSUES.md.

9.4. CTmcSoundEffProp — свойства звуковых эффектов

Назначение: контейнер-вкладка (PropertySheet) настроек двух мелодий уведомлений. Заголовок: TmcSoundEffProp.h · Базовый класс: CPropertySheet (DECLARE_DYNAMIC)

Поля (public): CTmcSoundMel1 cMelody1, CTmcSoundMel1 cMelody2 — две страницы мелодий (см. §9.5).

Методы:

9.5. CTmcSoundMel1 — страница мелодии

Назначение: страница настройки одной мелодии: интервал и 12 нот. Заголовок: TmcSoundMel1.h · Базовый класс: CPropertyPage (DECLARE_DYNCREATE) · Ресурс: IDD_TMC_SOUND_MELODY1

Поля (public): CString csMelodyName — имя мелодии.

Поля DDX:

Методы:

---

10. Формат входного файла (.tpl)

Секции шаблона (разбираются методами Read*Section через библиотеку TMCIndan; детальное описание формата — docs/api/libs/tmcindan.md):

Перед разбором файл проходит препроцессинг библиотекой PREPR (макроподстановки, промежуточный файл $$vr$$s.prc).

---

11. Форматы выходных файлов

Файлы .dop — это документы вьювера TMC_DN (диаграммы направленности); ядро напрямую .dop не пишет — экспорт данных для ДН выполняет CFieldIntegrated::ExportToDirectionalPattern (TMCIndan, см. docs/api/libs/tmcindan.md).

Запись выходных файлов реализована в подсистеме CTmcRTH_IndanOutput библиотеки TMCIndan.

---

//#define _PREC_DOUBLE          // off
#define _PREC_FLOAT             // on: float precision

#ifdef _PREC_FLOAT
#define _real float             // the base precision type
#endif

#define _ELEM_VAL_RTH_REAL      // on: the field element is real
//#define _ELEM_VAL_RTH_INT     // off: the integer variant (with the factor 1024*1024)

#ifdef _ELEM_VAL_RTH_REAL
#define _ELEM_VAL_RTH _real     // the field element type = float
#define _ELEM_VAL_RTH_MULT 1
#endif

struct STMCRTH_NODEDIELONE
{
    _ELEM_VAL_RTH rU;       // the incident voltage on the dielectric (tact 0)
    _ELEM_VAL_RTH rU_Cur;   // the current voltage
    _ELEM_VAL_RTH rU_Cur1;  // the "current+1" tact voltage
    _ELEM_VAL_RTH rUo;      // the scattered voltage (for inputs)
    _real rY;               // the node conductance
    int   nNodeGlobal;      // the node number in the global topology
    int   nType;            // the node type (see §3.3)
};
typedef struct STMCRTH_NODEDIELONE sTmcRTHNodeDielOne;

struct STMCRTH_DIELNODELIST
{
    STMCRTH_DIELNODELIST * pcDielNodeNextList;  // the next list element
    sTmcRTHNodeDielOne   * pcNodeDielOne;       // the node
};
typedef struct STMCRTH_DIELNODELIST sTmcRTH_DielNodeList;

Sub-step 0:
  RunExciteInputs();          // input excitation
  RunScatteringNode();        // scattering at the nodes
  RunBlockNode();             // block handling
  PutField( 0 );              // field writing
  DistributionIntegrated(0);  // accumulation for the RP
  nTCurrent++;  dTCurrent += dT;

Sub-step 1:
  RunExciteInputs1();
  RunScatteringNode1();
  RunBlockNode1();
  PutField( 1 );
  DistributionIntegrated(1);
  nTCurrent++;  dTCurrent += dT;

#define TMC_RTH_EPSFILE_EXT_   "eps"
#define TMC_RTH_EPSFILE_ID_    "#TamicRTH_planar_DistributionDielectricPermeability_File_V2.00 2000"
#define TMC_RTH_EPSFILE_TYPE_  "#TopologyPrimitiv "
#define TMC_RTH_EPSFILE_Delta_ "#dDelta "
#define TMC_RTH_EPSFILE_XMIN_  "#Xmin "
#define TMC_RTH_EPSFILE_YMIN_  "#Ymin "
#define TMC_RTH_EPSFILE_NX_    "#nX "
#define TMC_RTH_EPSFILE_NY_    "#nY "
#define TMC_RTH_EPSFILE_NPoint_ "#nPoint "
#define TMC_RTH_EPSFILE_NAccur_ "#nAccuracy "
#define TMC_RTH_EPSFILE_NdFrmt_ "#sNodeFormat "
#define TMC_RTH_EPSFILE_VlFrmt_ "#sValueFormat "