User manual — the PlanarRT_H compute kernel (tmc_rth.exe)

Program: Planar RT H analyzer (the executable tmc_rth.exe). The program's interface is in English — the manual gives the English item names as in the program, with a Russian/English explanation next to them. The captions on the screenshots are in Russian.

1. Purpose of the program

PlanarRT_H is a compute kernel of the TMC Suite package. It performs the electrodynamic computation of planar (two-dimensional) structures in H-polarization in the time domain: from a given topology (metal, absorbers, dielectrics, inputs) the program computes step by step how the electromagnetic field propagates and scatters.

In simple terms: you describe a "map" of the computation area in a text template file .tpl, and the kernel "plays" a wave through it over time and saves the results:

• the time signal at the inputs (.t) — later viewed in the TMCROS viewer;
• the scattering S-matrix (.s) — viewed in the TMCGROUT viewer;
• the field distribution (.ex, .ey, .hz, .em, .ef) and the topology (.tt) — viewed in the FieldView viewer.

Thus PlanarRT_H is a "data generator": it computes, and separate viewer programs draw the result. (The companion kernel PlanarRT_X does the same for the X-mode — see planar_rt_x.md.)

2. Launching the program and opening data

1. Launch the file tmc_rth.exe (folder dist/win32/bin/). The main window opens (see the figure above).
2. Open a computation template file: menu File → Open… (or the button on the toolbar, or Ctrl+O).
3. In the file-selection dialog choose a file with the .tpl extension (for example, samples/SAMPLE_R/1/TEST.TPL).
4. After opening, the file name appears in the window title: Planar RT H analyzer - [TEST.TPL].

You can also launch the program with a file at once, by dragging the .tpl onto the program icon or by giving the file path as a command-line argument: tmc_rth.exe "path\to\file.tpl".

3. The main window

The main window consists of five zones (shown with frames in the figure in section 1):

4. The toolbar

The toolbar duplicates the most useful menu items. The buttons from left to right are numbered:

#	Button	Command (menu)	Shortcut	What it does
1		File → New	Ctrl+N	Create a new (empty) template.
2		File → Open	Ctrl+O	Open an existing .tpl file.
3		Edit → Edit	Alt+F7	Open the current .tpl in an external text editor for editing.
4		View → Output	Alt+Shift+F4	Show the output signal (the time-domain result).
5		View → Field and topology	—	Show the field distribution together with the topology.
6		View → S-matrix	Ctrl+Shift+F4	Show the scattering S-matrix.
7		View → Directional Pattern	Ctrl+Alt+F4	Show the radiation pattern.
8		View → Statistics	Shift+F4	Open the computation statistics window (see section 6).
9		Run → Load first step	Shift+F5	Load the first step (return to the start of the computation).
10		Run → Run	F5	Run the computation from the current step to the last.
11		Run → Stop	Alt+F5	Stop a running computation. (Active only during a computation.)
12		Run → Run Step	F8	Compute one current step.
13		Run → Load Step	Shift+F8	Load (re-read) the current step.
14		Run → Skip Step	Ctrl+F6	Skip one step forward without output.
15		Run → Back Step	Alt+F6	Go one step back.
16		Config → Topology	F4	Output (draw) the model topology.
17		Config → Field	Ctrl+F4	Output (draw) the field.
18		Config → Synchronization	—	Synchronization. In the current version this item is unavailable (the icon is gray).
19		Config → Directional Pattern	—	Configure/output the radiation pattern.
20		Config → Sound	—	Sound accompaniment (on/off, melody).
21		Config → AutoRun	—	Automatic start of the computation.
22		File → Print	Ctrl+P	Print the current image.
23		Help → About	—	About the program (version).

Tip: hovering the cursor over a button in the program itself shows its English name as a tooltip, and a short description appears in the status bar.

5. The menus

5.1. File

5.2. Edit

5.3. View

5.4. Run

5.5. Config

The Config → Viewer submenu — choosing external viewer programs for each kind of data:

• Output signal — the output-signal viewer (TMCROS);
• Field — the field viewer (FieldView);
• S-matrix — the S-matrix viewer (TMCGROUT);
• Directional Pattern — the radiation-pattern viewer (TMC_DN).

The Config → Color submenu — color settings:

• BackGround — the background color of the work area.

The Config → Format submenu — the output-file format:

• OutputDataFile — configure the format (number-printing precision) of the output data file.

The Config → Sound submenu — sound accompaniment:

• On/Off — turn the sound on/off (a check mark = on);
• Melody — choose the melody.

5.6. Window

5.7. Help

6. Dialog windows

6.1. About

Invoked via Help → About PlanRT_H… or the button. Shows the name, version and developer information.

6.2. Statistics

Invoked via View → Statistics (Shift+F4) or the button. The window shows the parameters of the computation grid and the current computation.

Main fields:

• Parameters → Unit — units of measurement: Long (length, e.g. mm), Time (ns), Frequence (GHz), Angle (radian).
• Delta - space discr — the spatial discretization step (Δ).
• t0 - time discr — the time step.
• Frequence — the operating frequency.
• Wavelenght — the wavelength.
• NumNode — the number of grid nodes; Memory MB — the amount of memory used.
• Time (min / max) — the time interval of the computation.
• X size / Y size (min / max) — the dimensions of the computation area.
• Accuracy — an accuracy estimate (as a percentage).
• Calculated value — derived quantities: lenght / Delta, Xsize / Wavelenght, Ysize / Wavelenght, T / t0, Time / t0, Time / T.
• Step — the current step number, the Prev. / Next buttons for switching steps.
• Error message — an error message (Error:no — no errors).
• Topology → Block — the block number; View block list — the list of blocks.
• Output → Signal / Field / Topology — the paths to the output files; the Field / Topology checkboxes; Data Format — the data format (for example, Float Professional).
• The OK (apply) and Cancel (cancel) buttons.

6.3. Choosing the external editor (Config → Editor)

The Config → Editor command opens the standard file-selection window in which you specify the executable (.exe) of the external text editor. After that the Edit → Edit (Alt+F7) command will open the current .tpl in it.

7. Input data: the .tpl template file

7.1. What it is and its extension

The program's main input file is a text template with the .tpl extension (text template). It describes: the units of measurement, the grid and time parameters, the topology (the geometry of the metal, absorbers, dielectrics, inputs), the links between blocks, and which output files to create.

How to write your own .tpl from scratch — the methodology (drawing → the "box" → decomposition into blocks → choosing the grid step) and the complete reference of the input language with every keyword, figures of the primitives and examples: tpl-guide.md. Below is only a short walkthrough of a working example.

Before the computation the file goes through preprocessing by the PREPR library (#include and #define are expanded, expressions are evaluated). That is, a .tpl can be written "programmatically": with included files and named constants.

7.2. Accompanying files

Often the .tpl itself is short and only includes header files .h:

• .tpl — the main file (the entry point); it sets the signature, the includes, and the call of the computation macro;
• .h — included files with constants (#define) and large blocks of topology (macros);
• .eps — a file with the distribution of the permittivity ε (if an inhomogeneous medium is used).

7.3. Walkthrough of an example

Consider the working example samples/SAMPLE_R/1/TEST.TPL:

#TMC_RT_H
#include horns.h
#include cir_quas.h

Wozmush    3.141592653589/8; quasi0; 40.0;

#EOF

Line by line:

Comments and special characters: - lines starting with # are preprocessor directives (#include, #define, #STEP, #EOF, etc.); - lines starting with ! are comments (explanatory text, ignored during parsing); - \\ at the end of a line is a continuation (joining) of a long macro line; - @ ( … ) and @\\ are service wrappers of PREPR preprocessor expressions; - a semicolon ; separates parameters within commands.

7.4. The constants file (horns.h)

Contains only named constants — they are convenient to change without touching the geometry:

#define L_box   @ ( 412.00)      // length of the computation area along X
#define W_box   @ ( 300.00)      // width of the computation area along Y
#define W_input @ (   8.00)      // input width
#define W_delta @ (   0.6)       // grid step Δ
#define a2      @ ( 20 )         // horn geometric dimensions …
#define apert   @ ( 39 )         // aperture
#define alfa    @ ( 7.36/180*3.141593 )   // angle (in radians)
...

Each #define Name @ ( Expression ) sets a constant. Expressions may use arithmetic and previously declared constants (for example, a1 is defined through W_input, h through apert, W_input, th).

7.5. The computation-step file (cir_quas.h)

Here the Wozmush macro is defined, which expands into the full block **`#STEP …

END_STEP`**. Inside there are four sections:

The #PARM … #END_PARM section — computation parameters:

The #TOPOLOGY … #END_TOPOLOGY section — the model geometry. It consists of blocks:

 BLOCK 1;                         // block number
 POLYGON_STAT METAL;              // element type and material
   L   0;   a1/2;                 // polygon vertices (coordinates L x; y;)
   L   a2;  a1/2;
   L   a2;  a1/2+W_delta;
 END_B                            // end of the block

The topology element types that appear in the example:

Materials: METAL (a perfect conductor), MAGNETIC (a magnetic — an open-circuit wall), ABSORBER (an absorber). Instead of a material an expression may be given (for an inhomogeneous medium), for example in block 20: CIRCLE_STAT amp*cos(tpg*r0*(f-f0+sdvig__))/exp(...); — it sets the perturbation distribution as a function of the coordinates r, f (radius, angle) and the parameter sdvig__.

An expression sets the addition ε⁺ to the permittivity of vacuum, not ε itself. A plate with ε = 4 corresponds to writing 3. Hence the construct (W_eps-1) found throughout the author's task files.

INPUT_X is an input along the Y axis, not "along the X axis". The name refers to the axis along which the excitation travels, while the extent of the input is given along the perpendicular axis. See tpl-guide.md, section 5.5, for details.

The #LINK_LIST … #END_LINK section — the block links and the symmetry plane:

 T 1; 0.0; W_box/2;     // block 1 is placed at the point (x0=0.0, y0=W_box/2)
 ...
 T 20; R_vessel+l+a2; W_box/2;

The line T <block number>; x0; y0; places the block with the given number at the coordinates (x0, y0) (in the units from the #PARM section). That is, in #TOPOLOGY a block is described "in its own" coordinate system, and in #LINK_LIST it is assigned a position in the common computation area.

The #OUTPUT … #END_OUTPUT section — which output files to create:

 FILE filename__;                              // base name of the output files (= quasi0)
 FIELD_DISTRIBUTION_M filename__; freq__; 7; 8; // save the field distribution at the freq frequency, steps 7 and 8

7.6. How to prepare your own data

1. Copy the working example (TEST.TPL + horns.h + cir_quas.h) into a separate folder.
2. In horns.h change the constants for your task (the area dimensions L_box/W_box, the step W_delta, the horn geometry, etc.).
3. If needed, edit the topology in cir_quas.h (the BLOCK … END_B blocks).
4. In the .tpl set the launch parameters: the shift, the output file name, the frequency.
5. Open the .tpl in the program and run the computation (section 8).

For editing it is convenient to configure the external editor (Config → Editor) and open the file directly from the program with the Edit → Edit (Alt+F7) command.

8. Output data

After the computation the kernel creates files (the names are built from the base name given in the #OUTPUT section):

All file names are built from the base name given by the FILE line in the #OUTPUT section. The list has been verified against the code (src/libs/TMCIndan/TmcRTH_IndanOutput.cpp, lines 194–204).

The extension .tf appears in the author's 2000 manual and in the list of formats FieldView opens (*.tf;*.AMP;*.FAZ;*.ex). The current code does not write it — it is a historical extension of version 2.0p.

The kernel does not write the radiation-pattern files (.dop for TMC_DN) directly — the data for the pattern is exported by a separate subsystem; see the API documentation docs/api/libs/tmcindan.md.

9. Typical scenarios

Open a ready computation and view the result: 1. File → Open… → select a .tpl. 2. Config → Topology (F4) — make sure the topology is drawn correctly. 3. Run → Run (F5) — perform the computation. 4. View → Output (Alt+Shift+F4) — view the output signal; View → S-matrix — the S-matrix.

Step-by-step computation (to observe the field): 1. Run → Load first step (Shift+F5) — go to the start. 2. Run → Run Step (F8) — compute one step; repeat. 3. Config → Field (Ctrl+F4) — observe the field distribution at each step. 4. Run → Back Step / Skip Step — move back/forward through the steps.

Check the grid and memory parameters before a long computation: - View → Statistics (Shift+F4) — view the number of nodes, the memory used, the Δ and t0 steps, and the accuracy estimate.

10. Possible problems

11. Related programs and documents

• TMCROS — viewing the time signal (.t). See tmcros.md.
• TMCGROUT — viewing the S-matrix (.s). See tmcgrout.md.
• TMC_DN — viewing the radiation pattern. See tmc_dn.md.
• FieldView — viewing the field and topology (.ex, .tt).
• PlanarRT_X — the companion kernel for the X-mode. See planar_rt_x.md.
• The kernel API documentation: docs/api/kernels/planar_rt_h.md; the data format: docs/api/libs/tmcindan.md.