User manual — the PlanarRT_X compute kernel (tmc_rtx.exe)

Program: Planar RT X-mode analyzer (the executable tmc_rtx.exe). The program's interface is in English — the English item names are given as in the program, with an explanation next to them. The captions on the screenshots are in Russian.

PlanarRT_X is the "companion" program to PlanarRT_H. Both are built from the same source code, so their interface (menu, toolbar, dialogs) is completely identical. Only the physics of the computation differs: H computes H-polarization, X computes the X-mode (see section 7). If you are already familiar with planar_rt_h.md, mastering X will be easy. Below is the full description with screenshots of the X program specifically.

1. Purpose of the program

PlanarRT_X is a compute kernel of the TMC Suite package for the electrodynamic computation of planar (two-dimensional) structures in the X-mode in the time domain. Like the H kernel, from a text template .tpl (the area topology, parameters, output data) the program "plays" the field over time and saves the results for viewing in the viewers:

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

The main difference from the H kernel is the internal algorithm: in the X-mode more field components are stored at each grid node, and the computation cycle consists of four sub-steps instead of two (details in section 7).

2. Launching the program and opening data

1. Launch the file tmc_rtx.exe (folder dist/win32/bin/). The main window opens.
2. Open a template: File → Open… (or the button, or Ctrl+O).
3. Choose a file with the .tpl extension. The file samples/SAMPLE_R/1/TEST.TPL works as a starting sample (it opens in both the H and X kernels).
4. The file name appears in the title: Planar RT X-mode analyzer - [TEST.TPL].

For studying the format the file src/kernels/PlanarRT_X/1.TPL is convenient — it is provided with detailed comments for all block types (see section 8.2). Note: to actually run it, the file planrt2.h it includes must be next to it; if that file is missing, use a ready sample for the computation (for example, TEST.TPL), and read 1.TPL as a syntax reference.

You can launch with a file from the command line: tmc_rtx.exe "path\to\file.tpl".

3. The main window

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

4. The toolbar

The buttons from left to right (numbered in the figure):

#	Button	Command (menu)	Shortcut	What it does
1		File → New	Ctrl+N	Create a new template.
2		File → Open	Ctrl+O	Open a .tpl.
3		Edit → Edit	Alt+F7	Open the .tpl in an external editor.
4		View → Output	Alt+Shift+F4	Show the output signal.
5		View → Field and topology	—	Show the field with the topology.
6		View → S-matrix	Ctrl+Shift+F4	Show the S-matrix.
7		View → Directional Pattern	Ctrl+Alt+F4	Show the radiation pattern.
8		View → Statistics	Shift+F4	The statistics window (section 6).
9		Run → Load first step	Shift+F5	Return to the first step.
10		Run → Run	F5	Compute to the end.
11		Run → Stop	Alt+F5	Stop the computation.
12		Run → Run Step	F8	One computation step.
13		Run → Load Step	Shift+F8	Re-read the current step.
14		Run → Skip Step	Ctrl+F6	Skip one step forward.
15		Run → Back Step	Alt+F6	One step back.
16		Config → Topology	F4	Output the topology.
17		Config → Field	Ctrl+F4	Output the field.
18		Config → Synchronization	—	Unavailable (the icon is gray).
19		Config → Directional Pattern	—	Configure/output the pattern.
20		Config → Sound	—	Sound (on/off, melody).
21		Config → AutoRun	—	Automatic start of the computation.
22		File → Print	Ctrl+P	Print the image.
23		Help → About	—	About the program.

5. The menus

5.1. File

New (Ctrl+N), Open… (Ctrl+O), Close, Save (Ctrl+S), Save As…, Print… (Ctrl+P), Print Preview, Print Setup…, the recent files list, Exit. Their purpose is as in any Windows program (create / open / save / print / exit).

5.2. Edit

• Edit (Alt+F7) — open the current .tpl in the external editor (set in Config → Editor).
• Undo / Cut / Copy / Paste — standard clipboard commands (unavailable in the current mode — gray).

5.3. View

5.4. Run

Run (F5), Load first step (Shift+F5), Run Step (F8), Load Step (Shift+F8), Skip Step (Ctrl+F6), Back Step (Alt+F6), Stop (Alt+F5). Computation control: run in full, step by step, navigation through steps, stop. (Stop is active only during a computation.)

5.5. Config

The Config → Viewer submenu — choosing external viewer programs:

Output signal (TMCROS), Field (FieldView), S-matrix (TMCGROUT), Directional Pattern (TMC_DN).

The Config → Color submenu — BackGround (the background color of the work area):

The Config → Format submenu — OutputDataFile (the format/precision of the numbers in the output file):

The Config → Sound submenu — On/Off (a check mark = on) and Melody:

5.6. Window

Cascade, Tile, Arrange Icons, the list of open documents (a check mark — the active one).

5.7. Help

About PlanRT_X… — information about the program version.

6. Dialog windows

6.1. About

Help → About PlanRT_X… or the button. Shows the version and developer information.

Note: the About window title may read "Planar RT H analyzer" (a resource shared with the H kernel), but the text inside clearly states: Planar RT X analyzer.

6.2. Statistics

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

The fields are the same as in the H kernel:

• Unit — units: Long, Time, Frequence, Angle.
• Delta - space discr / t0 - time discr — the space and time steps.
• Frequence, Wavelenght — the frequency and wavelength.
• NumNode, Memory MB — the number of nodes and the memory.
• Time / X size / Y size (min/max) — the computation intervals and area sizes.
• Accuracy — an accuracy estimate.
• Calculated value — derived ratios (lenght/Delta, Xsize/Wavelenght, T/t0, etc.).
• Step + the Prev. / Next buttons — step navigation.
• Error message — an error message (Error:no — no errors).
• Topology → Block + View block list — the model blocks.
• Output — the paths to the output files, the Field / Topology checkboxes, Data Format.
• The OK / Cancel buttons.

7. How the X-mode differs from H (for the user)

For the user the interface and the data format are the same as in the H kernel. What differs is what is computed "under the hood":

Practical consequences:

• The .tpl format is the same, and the first line of the file stays #TMC_RT_H (there is no separate #TMC_RT_X signature). So the same template can be opened by both the H and X kernels.
• The X kernel additionally understands, in the #TOPOLOGY section, blocks with the _Y suffix (RECT_STAT_Y, etc.).
• Because of the larger number of field components, an X computation requires more memory and time for the same grid — watch NumNode and Memory in the statistics window.
• The View → Directional Pattern item in the X-mode may give no result, since the accumulation of pattern data is disabled in the current version.

For the build only (not for the user of the finished program). The X kernel is compiled with six preprocessor macros (ELECTRON_Q___, ELECTRON_M___, CTMCRTH_INDANBLCK_FILEY, CTMCRTH_INDANBLCK_RECTSTATY, CTMCRTH_INDANBLCK_CIRCSTATY, CTMCRTH_INDANBLCK_POLYGSTTY), which are set only in the X-mode project properties. This does not affect working with an already-built tmc_rtx.exe in any way — details are in docs/build-guide/ and docs/api/kernels/planar_rt_x.md.

8. Input data: the .tpl template file

8.1. Extension and the general idea

The main input file is a text template .tpl. The first line is the signature #TMC_RT_H. Before the computation the file goes through preprocessing by the PREPR library (#include, #define, expression evaluation). The file structure is completely identical to the H kernel (an exhaustive breakdown is in planar_rt_h.md, section 7); below is the X kernel's own tutorial example.

Special characters: - # at the start of a line — a preprocessor directive (#include, #define, #STEP, #EOF); - ! at the start of a line — a comment (explanatory text, ignored); - ; — a parameter separator; - \\ at the end of a line — a continuation of a long line.

8.2. Walkthrough of the tutorial example 1.TPL

The file src/kernels/PlanarRT_X/1.TPL is provided with detailed comments and shows almost all the format's capabilities (it is a syntax reference example; to run it, it needs the included planrt2.h). Its structure:

#TMC_RT_H              ← signature
#include planrt2.h     ← included constants

#STEP                  ← the first computation step
  #PARM … #END_PARM        — parameters
  #TOPOLOGY … #END_TOPOLOGY — geometry (blocks)
  #LINK_LIST … #END_LINK    — block placement
  #OUTPUT … #END_OUTPUT     — output files
#END_STEP

#STEP … #END_STEP      ← the second step (there can be several)

#EOF                   ← end of file

A file may contain several #STEP sections — this is a sequence of computations (for example, different topology configurations), switched with the Prev./Next buttons in the statistics window and the Run menu commands.

8.3. The #PARM section (parameters)

 ANGLE_UNIT radian;     ! angle unit
 FREQ_UNIT GHz;         ! frequency unit
 LONG_UNIT mm;          ! length unit
 TIME_UNIT s;           ! time unit
 DELTA 0.35;            ! grid step Δ
 TIME -.0001; 0.0001;   ! time interval (from; to)
 X_MIN -10.0*2-4 ;      ! X boundaries (an expression is allowed)
 X_MAX ( + 500 . 0 ) ;
 Y_MIN (-5.0);          ! Y boundaries
 Y_MAX 300.0;
 FREQ 40.0;             ! operating frequency

Numbers can be given as expressions; spaces inside numbers/parentheses are allowed (( + 500 . 0 ) = 500.0).

8.4. The #TOPOLOGY section (geometry)

The geometry is described by blocks BLOCK n; … END_B. Inside a block there is one element. Element types (from the example's comments):

E(x,y) is the "material" of the element; it can be: - the keyword METAL (a perfect conductor), MAGNETIC (a magnetic — an open-circuit wall) or ABSORBER (an absorber); - an expression for an inhomogeneous medium, for example - ( x^2 + y^2 ) or - ( 3 - r ) (the ε distribution as a function of coordinates).

An expression sets the addition ε⁺ to the permittivity of vacuum, not ε itself. A medium with ε = 4 corresponds to writing 3, vacuum to 0, and a medium with ε = 0 to -1.

The first parameter of an input is the mode, not the signal shape. MAGNETIC — a plane wave (the input is narrower than half a wavelength); METAL or empty — the H₁₀ wave of a rectangular waveguide (wider than half but narrower than a full wavelength). The amplitude and phase are given by the optional parameters 6 and 7 as expressions in t and f; parameter 8 is the ε addition in the cross-section of the input. See tpl-guide.md, section 5.5, for details.

The full description of all primitives, including the plasma variants RECT_STAT_N / _B / _Y, is in tpl-guide.md.

An example block with explanatory comments (as in the file):

 BLOCK 1;
! a rectangle filled with the distribution ε = -(x²+y²)
! RECT_STAT E(x,y); x_min; x_max; y_min; y_max;
 RECT_STAT - ( x^2 + y^2 ) ; -1 ; 3 ; -2; 4;
 END_B

A moving element adds three numbers at the end — the velocities Vx, Vy (in LONG_UNIT/TIME_UNIT) and the angular velocity w (in ANGLE_UNIT/TIME_UNIT):

 BLOCK 3;
! a moving rectangle with velocity (Vx,Vy) and rotation w
 RECT_MOVE - ( x^2 + y^2 ) ; -1; 3; -2; 4; 1.0; -2; 10;
 END_B

The X kernel additionally recognizes blocks with the _Y suffix (RECT_STAT_Y, CIRCLE_STAT_Y, POLYGON_STAT_Y, FILE_Y).

8.5. The #LINK_LIST section (block placement)

! block n is placed at the point (x0, y0); coordinates in the units from #PARM
! T n; x0; y0;
 T 1; -1.0; -0.5;
 T 2; -1.0; -0.5;
 ...

Each line T <block number>; x0; y0; places the block at the coordinates (x0, y0) of the common computation area. That is, in #TOPOLOGY the shape of a block is set "locally", and in #LINK_LIST — where it stands.

8.6. The #OUTPUT section (output files)

 FILE out1;     ! base name of the output files
 FIELDS;        ! save the field distribution
 TOPOLOGY;      ! save the topology

In the second step of the example these lines are commented out (! TOPOLOGY, ! FIELD) — meaning that for the second step the field and topology are not output.

8.7. How to prepare your own data

1. Copy the example 1.TPL (and the included planrt2.h) into a separate folder.
2. In the #PARM section set the units, the DELTA step, the TIME interval, the area boundaries and the frequency.
3. Describe the geometry in #TOPOLOGY (the BLOCK … END_B blocks), using the moving elements *_MOVE and the inputs INPUT_X / INPUT_Y if needed.
4. Place the blocks in #LINK_LIST (T n; x0; y0;).
5. In #OUTPUT set the output file name and what to save.
6. Open the .tpl in the program and run the computation.

9. Output data

10. Typical scenarios

Open a computation and view the result: 1. File → Open… → select a .tpl. 2. Config → Topology (F4) — check the topology. 3. Run → Run (F5) — perform the computation. 4. View → Output / View → S-matrix — view the results.

Step-by-step computation with field observation: 1. Run → Load first step (Shift+F5). 2. Run → Run Step (F8) — one step at a time. 3. Config → Field (Ctrl+F4) — observe the field.

Multi-step template: if the file has several #STEP, switch between them with the Prev./Next buttons in the statistics window.

Resource check: View → Statistics (Shift+F4) — nodes, memory, accuracy (especially important for the X-mode because of the increased memory consumption).

11. Possible problems

12. Related programs and documents

• PlanarRT_H — the companion kernel (H-polarization). See planar_rt_h.md (which also has the exhaustive breakdown of the .tpl format).
• TMCROS (.t), TMCGROUT (.s), TMC_DN (pattern), FieldView (.ex, .tt) — the viewers.
• API documentation: docs/api/kernels/planar_rt_x.md; the data format: docs/api/libs/tmcindan.md.