The TMC_DN program — API documentation

TMC Suite package. A viewer of radiation patterns (RP) of antenna arrays: computation and building of the radiation pattern from a description of the radiator array, as well as computation of directivity/aperture efficiency, pattern deviations, and the "time → S-matrix" transform. All signatures are taken from the sources in src/viewers/DiaNapGr/, the RP computation core from src/viewers/DiaNapr/ (c2DArray, cIzl) and the shared headers from src/Include/.

1. Purpose of the program

TMC_DN (sources — the folder src/viewers/DiaNapGr/, the output EXE — TMC_DN.exe) is a graphical viewer and calculator of radiation patterns of antenna arrays.

The program is built on the same MFC Document/View (MDI) codebase as TMCGROUT (the classes CTMCGROUTApp, CMainFrame, CChildFrame, CTMCGROUTDoc, CTMCGROUTView have the same names), but is extended to work with radiation patterns:

• reads text .dat files with a description of the antenna array (the frequency, the number of radiators, the coordinates/amplitudes/phases of each radiator, the pattern expression of a single element);
• from this description computes the radiation pattern of the array (coherent summation of the radiators' fields over the angle) — the c2DArray class;
• computes the integral characteristics: the directivity (Knd, in ratio and dB) and the aperture efficiency (Kip);
• builds a 2D graph of the pattern (as TMCGROUT builds frequency responses), shows the directivity/aperture efficiency in the status bar;
• computes the pattern in a background thread with a progress window (the classes CThreadCalcDirPat, the function ReadDocFileW_Thread1) — computing a large array is lengthy;
• can introduce random deviations into the radiator parameters (cDeviation, c2DArray::MakeDeviation) and compute the pattern of a deviated array relative to the required pattern (CDeviatDirPat, c2DArray::OptimizationInit/SaveDeviationDirectionalPattern);
• contains a utility for converting a time signal into an S-matrix (CDialogTtoS, CTmcTtoS, CTmcSMatrix) — code shared with TMCROS.

Everything related to drawing, axes, colors, scaling, the document format is arranged the same way as in TMCGROUT (see tmcgrout.md, sections 3, 7–9, 11–12). Below, precisely the differences and additions of TMC_DN are documented in detail, while the common part is given with references.

2. Project composition

The TMC_DN.vcxproj build contains files from src/viewers/DiaNapGr/ plus the RP computation core from src/viewers/DiaNapr/:

The bold entries mark the files and classes specific to TMC_DN (absent from TMCGROUT). The c2DArray class is included via the relative path ..\DiaNapr\c2DArray.h.

Dependencies: MFC; the shared headers src/Include/ (Tmcgrviw.h, Proc_s.h, complex1.h, typedef.h, expr.h, TmcTtoS.h, TmcSMatrix.h, TMCGrExpression.h); the package libraries: SFILE95, complex, exprint (i1nte_atof_1, expr_set_angle, expr_get_error from expr.h — evaluating the element pattern expression).

3. The RP computation architecture (difference from TMCGROUT)

In TMCGROUT graph i is taken from an S-file. In TMC_DN a parallel array of RP objects is added:

// a field of CTMCGROUTDoc
c2DArray * pcDirectionalPattern;   // an array [grdoc.nGraph] — one RP object per graph
int        nGraphCurrent;          // the index of the RP being computed right now

The data flow:

.dat (array description)
      │  c2DArray::ReadData → cIzl[]            (reads the radiators)
      ▼
c2DArray::CalculateDiagrNapr                    (computes pdRealDN[], pdImageDN[] by angle)
      │  + NormirovkaDiagrNapr (directivity/aperture efficiency, normalization)
      ▼
CTMCGROUTView (draws it as an ordinary graph; the amplitude scale × GetdMax)

The computation is launched in a separate thread ReadDocFileW_Thread1 (via AfxBeginThread), and the modal window CThreadCalcDirPat shows the progress by the field c2DArray::iN (the current angle) and nGraphCurrent (the current RP out of the total).

4. The c2DArray class — the antenna-array model and RP computation

Purpose: stores the description of the antenna array (a set of cIzl radiators), computes its radiation pattern by angle, computes the directivity/aperture efficiency, reads/writes .dat files, supports deviations and comparison with the required pattern. Header: src/viewers/DiaNapr/c2DArray.h Implementation: src/viewers/DiaNapr/c2DArray.cpp Depends on: cIzl.h, windows.h, typedef.h, expr.h (exprint — i1nte_atof_1), standard math.

The physical model (how the computation works)

The array field in the direction dAngle (a planar problem, the angle in radians) is a coherent sum over all radiators:

Re = Σ aᵢ·cos( φᵢ + (2π·f·cᵢ/c₀)·cos(dAngle − αᵢ) )
Im = Σ aᵢ·sin( φᵢ + (2π·f·cᵢ/c₀)·cos(dAngle − αᵢ) )

where for radiator i: aᵢ is the amplitude (accounting for the element's own pattern and the angular range), φᵢ is the phase, (xᵢ,yᵢ) are the coordinates, cᵢ=√(xᵢ²+yᵢ²) is the distance from the origin, αᵢ=atan2(yᵢ,xᵢ), f is the frequency (Hz), c₀ = 299792458 m/s is the speed of light. The pattern amplitude at a point: |field| = √(Re²+Im²), the phase: atan2(Im,Re).

This is scientific computation code. Do NOT change the formulas without the author's permission.

Fields (private, main)

Constructor / destructor

c2DArray()

Initializes the fields (no radiators, nAngle=400, the isotropic element "1."), allocates the angular arrays (InitAngle), sets the exprint angle mode to radians (expr_set_angle(EXPR_RADIAN)).

~c2DArray()

Deletes the temporary and output files (if they were created), frees all the arrays (DeleteAngle, DeleteData).

Public methods — computation and RP access

void CalculateDiagrNapr(char *szInputFileName, char *szOutputFileName)

What it does: the full "file to file" cycle: reads the array (ReadData), computes the pattern (CalculateDiagrNapr()), writes the result (WriteData).

void CalculateDiagrNapr(void)

What it does: computes the pattern for an already-loaded array. How it works: for each angle pdAngle[iN] computes Re/Im (CalculateRealDN/CalculateImageDN), for an isotropic element (szOneExpression=="1.") — directly, otherwise multiplies by the element-expression value (via i1nte_atof_1); writes the amplitude into pdRealDN, the phase into pdImageDN; then normalizes (NormirovkaDiagrNapr). For large arrays, if there is an up-to-date cache, it reads it (ReadDataFromTempFile). The field iN is updated as it goes — the progress window reads it. Errors: on an expression-evaluation error it sets bIsError=TRUE, the text from expr_get_error().

int GetnAngle(void) — the number of angular points of the pattern.

double GetdAngle(int i) — the angle of the i-th point (rad); 0.0 on out of bounds/error.

double GetdAmplitudeDiagrNapr(int i) — the pattern amplitude at the i-th point; 0.0 on error.

double GetdMax(void) — the maximum of the pattern amplitude (the scale factor dMax).

double GetKnd(void) / double GetKnd_dB(void) — the directivity in ratio / in dB (10·lg(Knd)).

double GetKip(void) / double GetKip_dB(void) — the aperture efficiency in ratio / in dB.

int GetnIzl(void) — the number of radiators.

double GetdFreqGHz(void) — the frequency in GHz.

BOOL IsCalculateKip(void) — TRUE if the array is "large" (nIzl > nMaxTemporary) — then "emitted power" is computed instead of the aperture efficiency.

BOOL IsError(void) / char* GetError(void) — the error flag and text.

void ResizeAngle(double dAngleMin, double dAngleMax)

Rebuilds the angle grid to the range [dAngleMin, dAngleMax] (rad), recomputes the pattern and rewrites the output file.

Public methods — array I/O and editing

void ReadData(char *szFileName1)

Loads the array from a .dat. Format: the line Frequence = … Ghz;, the line N = …; (the number of radiators), the element-pattern expression line, then one line per radiator: i X = … mm; Y = … mm; Amplitude = …; Faza = … degree; [FiMin = … degree; FiMax = … degree; expression]. The coordinates are converted to meters, the phases and angles to radians.

void SaveData(char *pszFile)

Saves only the array description (without the computed pattern) into the file pszFile.

void SaveDeviationDirectionalPattern(char *pszFileName)

Computes the pattern and writes a three-column file: angle (deg) · required pattern · computed pattern — for comparing a deviated array with the reference.

void GetIzl(int i, double *dXmm, double *dYmm, double *dAmpl, double *dFazaDegree)

Returns the parameters of radiator i: the coordinates (mm), the amplitude, the phase (deg).

void SetIzl(int i, double dXcoord_mm, double dYcoord_mm, double dAmplitud, double dFaza_gradus)

Sets the parameters of radiator i.

double GetRealIzl(int i) / double GetImageIzl(int i)

The Re/Im of the complex excitation of radiator i: a·cos(φ) / a·sin(φ).

void SetdFrequence(double dFrequenceGHz) — sets the frequency (input in GHz, stored in Hz).

void SetOneExpression(char *ch) / void SetszOneExpression(char *ch) / char* GetOneExpression(void)

Set/get the element pattern expression text. (SetOneExpression additionally checks the length; SetszOneExpression — without a check.)

char* GetOneExpression(void) — the current element expression.

void SetNPointForNormirovka(int nPoint) — the number of integration points during normalization.

Public methods — deviations and optimization

void MakeDeviation(char *szSourceFile, char *szDistinationFile, double dXmm, double dYmm, double dAmplProcent, double dFazaDegree)

What it does: reads the array from szSourceFile, introduces random deviations into each radiator (coordinates ±dXmm/dYmm mm, amplitude ±dAmplProcent %, phase ±dFazaDegree deg — a uniform distribution via GetRnd), saves the result into szDistinationFile.

void OptimizationInit(char *szFileRequiDirPat, int nIzl1)

Reads the required pattern file (two columns: angle in degrees, amplitude) into pdRequiredDN, allocates the array for nIzl1 radiators. Used in CDeviatDirPat.

double GetOptimPurposeFunction(void)

The optimization objective function: recomputes the pattern and returns the sum of the absolute deviations Σ|pdRealDN[i] − pdRequiredDN[i]|.

Key private methods

5. The cIzl class — one array radiator

Purpose: stores the parameters of one antenna-array radiator and computes its own (element) radiation pattern. Header: src/viewers/DiaNapr/cIzl.h Implementation: src/viewers/DiaNapr/cIzl.cpp Depends on: typedef.h, expr.h (exprint).

Fields (private)

Element pattern type constants (cIzl.h)

Methods

double GetdAmplituda(double dAngle)

What it does: the element amplitude in the direction dAngle accounting for its own pattern: dGetDirectionalPatternEmitter(dAngle) · dAmplituda. If the amplitude ≈ 0 — returns 0.

double dGetDirectionalPatternEmitter(double dAngle)

What it does: the value of the element's own pattern in the direction dAngle. How it works: if the angle is outside [Fimin,Fimax] — FLT_MIN; for ALL→1, SIN→sin(dAngle), COS→cos(dAngle); for an arbitrary one — substitutes the angle f and evaluates the expression via i1nte_atof_1.

BOOL bIsAngleInDiapazon(double dAngle)

TRUE if the angle falls into the visibility range [Fimin,Fimax] (with reduction of the angles to two forms via dAnglePrived/dAnglePrived1).

Setters/getters

SetdAmplituda/GetdAmplituda, SetdFaza/GetdFaza, SetdXcoordinata/GetdXcoordinata, SetdYcoordinata/GetdYcoordinata, SetdFimin/GetdFimin, SetdFimax/GetdFimax, SetcsEmitterDirectPat/GetcsEmitterDirectPat (two setter overloads — for char* and CString&; on setting, the element pattern type is recognized).

cIzl& operator=(cIzl& cIzl1)

Full copying of all the radiator fields.

Private void dAnglePrived(double& dAngle) / dAnglePrived1(double& dAngle)

Reduction of the angle to the range (−π,π] and (0,2π] respectively (via atan2(sin,cos)).

6. Additions in CTMCGROUTDoc (differences from TMCGROUT)

The TMC_DN document is CTMCGROUTDoc (the header TMCGROUTDoc.h), as in TMCGROUT (see tmcgrout.md, section 7), but with additions for the pattern:

Additional fields

Additional structures (in TMCGROUTDoc.h)

DN variants of the graph/document structures (with the _DN suffix) are declared: TMC_GR_DOC1_DN and TMC_GR_DOC_DN. They repeat TMC_GR_DOC1/TMC_GR_DOC (see tmcgrout.md, section 3), adding the field bIsReduceElMagnAnalysis (whether to account for the elements' angular range). The document field grdoc has the type TMC_GR_DOC_DN.

The rest (reading/writing .soc, the graph and appearance parameters, colors, font) — is identical to TMCGROUT.

7. Additions in CTMCGROUTView (background RP computation)

The TMC_DN view is CTMCGROUTView (the header TMCGROUTView.h), the common drawing/mouse/menu — as in TMCGROUT (see tmcgrout.md, section 8). The differences:

An additional field

void ReadDocFileW_Thread(void)

What it does: re-reads the document and re-creates the point buffers from the background thread; at the end it sets bIsDataCalculate=TRUE, recomputes and redraws the graph. It is launched by the thread wrapper function:

UINT ReadDocFileW_Thread1( LPVOID pParam ); // (CTMCGROUTView*)pParam -> ReadDocFileW_Thread()

void OnEditTosmatrix()

A menu command — opens the CDialogTtoS dialog ("time → S-matrix").

Drawing the RP amplitude

In OnDrawGraph*/PrepareDoubleGraph the point amplitude is scaled to the pattern maximum: pSmatr[j].x · pcDirectionalPattern[i].GetdMax(). In the status bar (PutStatistics1) the directivity and aperture efficiency are output (or "Emitted Power" for large arrays).

void OnDestroy()

Before closing it waits for completion of the background computation: while bIsDataCalculate==FALSE, it re-shows the progress window CThreadCalcDirPat.

8. The CThreadCalcDirPat class — the RP computation progress window

Purpose: a modal window with two progress bars, showing the course of the background computation of the radiation patterns. Header: ThreadCalcDirPat.h · Base class: CDialog · Resource: IDD_READDATA_THREAD.

Fields (DDX)

Methods

BOOL OnInitDialog()

Starts the update timer (100 ms).

void OnTimer(UINT_PTR nIDEvent)

By the timer reads the progress from c2DArray::iN of the current RP and nGraphCurrent of the document, updates the percentages, progress bars, the number of radiators and the timer. When the last RP is computed (or on error) — closes the dialog (EndDialog(0)).

INT_PTR DoModal()

Remembers the start time (ltime_start) and shows the dialog.

9. Deviation dialogs (specific to TMC_DN)

9.1. The cDeviation class — introducing random deviations

Header: cDeviation.h · Base class: CDialog · Resource: IDD_DIALOGMAKEDEVIAT. Purpose: to take a source array file and create a file with randomly deviated radiator parameters.

Fields (DDX): m_csFileFrom (the source .dat), m_csFileTo (the output .dat), m_dXdev/m_dYdev (the coordinate spread, mm), m_dAmpDev (the amplitude spread, %), m_dFazaDev (the phase spread, deg). Methods: - OnButtonsource() — choosing the source file; - OnButtondistination() — choosing the output file and calling MakeDeviation(); - OnOK() — perform the deviation and close; - BOOL MakeDeviation(void) (private) — calls c2DArray::MakeDeviation(...); on error shows a message.

9.2. The CDeviatDirPat class — the pattern of a deviated array vs. the required one

Header: DeviatDirPat.h · Base class: CDialog · Resource: IDD_DIALOGCALCDEVIAT. Purpose: to compute the pattern for an amplitude/phase distribution and save it next to the required pattern (the comparison file .dev).

Fields (DDX): m_csDistrAmplFaza (the .dat amplitude/phase distribution file), m_csRequireDirPat (the .opt required-pattern file), m_csFileDevDirPat (the output .dev). Methods: - OnButtondistramplfaza() / OnButtonrequrdirectpattern() / OnButtondeviatdirpattern() — choosing the files (the last button launches the computation); - OnOK() — perform the computation and close; - BOOL CalculateDeviationDirectionalPattern(void) (private) — reads the distribution (c2DArray::ReadData), initializes the required pattern (OptimizationInit), transfers the radiators (GetIzl/SetIzl), saves the comparison (SaveDeviationDirectionalPattern).

9.3. Additions in CDialogDoc

The document table dialog CDialogDoc (see tmcgrout.md, §9.2) in TMC_DN gets two additional buttons: - OnAddMakedeviation() — opens the cDeviation dialog; - OnAddMakedeviation2() — opens the CDeviatDirPat dialog.

CDialogDoc also contains the field dTUnit (double) and includes cDeviation.h.

10. The "time → S-matrix" utility and other classes

10.1. CDialogTtoS, CTmcTtoS, CTmcSMatrix

This subsystem is shared with TMCROS and described in detail in tmcros.md. In brief:

• CTmcSMatrix (TmcSMatrix.h, TmcSMatrix.cpp) — reads a .t time-signal file, builds S-matrix elements from it (ReadTFile, MakeSmatrix, Save).
• CTmcTtoS (TmcTtoS.h, TmcTtoS.cpp) — a high-level wrapper: TtoS(csTfn, csSfn, dTmin, dTmax, dFreq) performs the full "signal file → S-file" cycle via CTmcSMatrix.
• CDialogTtoS (DialogTtoS.h, DialogTtoS.cpp, the resource IDD_DIALOG3) — the conversion-settings dialog (the S-file name, the time window Tmin..Tmax, the frequency, up to 20 X points), called from CTMCGROUTView::OnEditTosmatrix.

10.2. CTmcGrParColTypWid1

Header: TmcGrParColTypWid1.h · Resource: IDD_DIALOGGRLINECOLORTYPEWIDTH1. An empty dialog stub (no fields or handlers). The purpose is unclear — likely dead code / a duplicate of CTmcGrParColTypWid (the same note is in TMCROS).

10.3. Classes shared with TMCGROUT

CTMCGROUTApp, CMainFrame, CChildFrame, CTMCGROUTDIALOGView, CTmcGroutColorGraphDialog, CTmcGrParColTypWid, CTMCGrExpression, the global PutTrace/PutStatistics — see tmcgrout.md, sections 4–6, 9–11. The only application difference — the registry key "TMC_DN" instead of "TMCGROUT" in InitInstance.