The TMCGROUT program — API documentation

TMC Suite package. A viewer of scattering-matrix (S-parameter) frequency-response graphs: VSWR, losses (dB), the magnitude and phase of the S-matrix elements. All signatures are taken from the sources in src/viewers/Tmcgrout/ and the shared headers from src/Include/.

1. Purpose of the program

TMCGROUT (the output EXE — TMCGROUT.exe) is a graphical viewer of electrodynamic-computation results: it builds 2D frequency-response graphs of a multiport from data in S-files (scattering matrices, read by the SFILE95 library).

The program is built on the classic MFC Document/View scheme (an MDI — multiple-document-interface — application). Each document is a text file with the .soc extension (the TMCGROUT format) that describes a set of graphs: for each graph the S-file name, the input/mode numbers of the S-matrix element, and a caption are given. The program can:

• open .soc documents or .s/.s2p/.s4p/… scattering-matrix files directly (a .soc document is created automatically for them);
• build up to 20 graphs in one document, each with its own line color/type/width;
• for each graph choose the Y type (VSWR, losses in dB, magnitude |S|, phase in degrees/radians) and the X type (frequency in Hz/kHz/MHz/GHz or a custom unit);
• compute graphs from expressions over several S-files (the syntax {...[file]...}, parsing — the CTMCGrExpression class, evaluation — the exprint library);
• scale (zoom with the mouse and via the menu), auto-fit the X/Y limits, scroll Home/End;
• configure the colors (background, grid, axes, points, graphs), the label font;
• save the window and appearance parameters in the registry (HKCU\…\TMCGROUT) and in the .soc file itself;
• launch an external editor (by default winword.exe) for the document;
• watch the modification time of the files and re-read the data on change (a timer).

2. Project composition

The TMCGROUT.vcxproj build contains the following .cpp/.h files:

Dependencies: MFC (UseOfMfc — shared/static), the shared headers src/Include/ (Tmcgrviw.h, TMCGrExpression.h, Proc_s.h, complex1.h, inter.h, typedef.h), and the package libraries: SFILE95 (reading S-matrices — read_S_matrix_element), complex (cabsv, cphase), exprint (i1nte_atof_1 from inter.h — expression evaluation).

3. Common data structures (the Tmcgrviw.h header)

The program stores the graph data in structures declared in the shared header src/Include/Tmcgrviw.h. These structures are the basis of the TMCGROUT data model.

3.1. TMC_GR_DOC1 — one graph (in a document)

typedef struct {
    int        nPoint;       // the number of graph points
    double     dFreq;        // the frequency (for the time array)
    double    *pFreq;        // the array of frequencies
    _complex  *pSmatr;       // the array of complex values of the S-matrix element
    CTMCGrExpression *pcExpr;// a pointer to the expression class (if the graph is an expression)
    int        nInp1;        // the number of input 1
    int        nMod1;        // the mode number of input 1
    int        nInp2;        // the number of input 2
    int        nMod2;        // the mode number of input 2
    char      *szFileName;   // the full S-file name (with path)
    char      *szGrapName;   // the graph name (the S-file name or the expression text)
    char      *szGrapPodp;   // the graph caption in the legend
    int        LineColor;    // the line color (COLORREF)
    int        LineType;     // the line style (PS_SOLID/PS_DASH/…)
    int        LineWidth;    // the line width
    TMC_INT_POINT piPoint[TMC_GROUT_POINT_TYPE]; // 10 points of the marker shape
    int        PointColor;   // the marker color
    int        PointType;    // the marker style
    int        PointWidth;   // the marker width
    int        OutFlag;      // the flag for outputting the graph on screen (TRUE/FALSE)
    FILETIME   LastWriteTime;// the last write time of the S-file
} TMC_GR_DOC1;

3.2. TMC_GR_DOC — the whole document

typedef struct {
    int          nGraph;       // the number of graphs in the document
    TMC_GR_DOC1 *psGraph;      // the array of graphs
    BOOL         nAFlagX;      // auto-scale on X (TRUE — auto-fit)
    BOOL         nAFlagY;      // auto-scale on Y
    BOOL         PointDrawFlag;// whether to draw the point markers
    int          nYType;       // the Y-coordinate type (see the constants)
    int          nXType;       // the X-coordinate type
    double       Xmin, Xmax;   // the X limits
    double       Ymin, Ymax;   // the Y limits
    FILETIME     LastWriteTime;// the write time of the document file
} TMC_GR_DOC;

3.3. TMC_GR_VIEW, TMC_GR_WINDOW — the view data

TMC_GR_VIEW stores the points of one graph in two coordinate systems — the real one (pPoint, type TMC_POINT{double x,y}) and the logical screen one (piPoint, type TMC_INT_POINT{int nX,nY}).

typedef struct {
    int            nPoint;     // the number of points
    int            nPointDraw; // the number of actually drawn points (within the window)
    TMC_POINT     *pPoint;     // the real coordinates
    TMC_INT_POINT *piPoint;    // the logical (screen) coordinates
} TMC_GR_VIEW;

TMC_GR_WINDOW — the state of the view's drawing area: the real window sGrWin (TMC_GR_WINDOW_D — Xmin/Xmax/Ymin/Ymax, flags nAFlagX/nAFlagY), the integer viewport sGrView (TMC_GR_VIEWPORT — nXmin/nXmax/nYmin/nYmax), the axis types nXType/nYType, the number of graphs nGraph, the point flag PointDrawFlag, the array psGraph.

3.4. TMC_GR_TYPE_X, TMC_GR_TYPE_Y — the axis-type description

typedef struct { int nType; char pszXname[100]; } TMC_GR_TYPE_X;
typedef struct { int nType; char pszYname[100]; } TMC_GR_TYPE_Y;

A pair of "type code + axis-label text".

3.5. Graph-type constants (Tmcgrviw.h)

In addition, the header contains a set of #define identifiers for the sections of the document file (TMC_GROUT_DOCFILE_ID_Xmin, …_nXType, …_sDrawTextFont, etc.) — these are the text prefixes of the .soc-file lines by which CTMCGROUTDoc::SetOneReadGraphParameters recognizes the parameters.

4. The CTMCGROUTApp class

Purpose: the MFC application class. It initializes the program, registers the document template, opens the last file, restores the position of the main window. Header: TMCGROUT.h Base class: CWinApp.

Methods

CTMCGROUTApp()

The constructor. The significant initialization is moved to InitInstance.

BOOL InitInstance()

What it does: the application entry point. How it works: 1. AfxOleInit() — OLE/COM initialization (needed for Shell calls in CRecentFileList on Windows 7+; part of the fix for the crash-on-open bug); 2. SetRegistryKey("TMCGROUT") — store the settings and the recent-files list (MRU) in the registry HKCU, rather than in WINDIR\TMCGROUT.INI; 3. Enable3dControls(), LoadStdProfileSettings(9) — standard MFC initialization, loading the MRU (9 files); 4. registers CMultiDocTemplate (the document CTMCGROUTDoc + the child window CChildFrame + the view CTMCGROUTView, the resource IDR_TMCGROTYPE); 5. creates the main window CMainFrame; 6. if the command line is empty — iterates the MRU list and opens the first existing file; 7. restores the main-window position from the profile (the #INIWND key); 8. shows the window (SW_RESTORE). Returns: TRUE on success, FALSE on a window-creation error.

afx_msg void OnAppAbout()

Shows the modal "About" dialog (CAboutDlg, the resource IDD_ABOUTBOX).

Global object: CTMCGROUTApp theApp; — the single application instance.

The nested class CAboutDlg (declared in TMCGROUT.cpp) — a simple "About" dialog without handlers.

5. The CMainFrame class

Purpose: the main MDI window of the application. Contains the toolbar and the status bar. Header: MainFrm.h Base class: CMDIFrameWnd.

Fields

Methods

int OnCreate(LPCREATESTRUCT)

Creates the toolbar (IDR_MAINFRAME) and the status bar (2 separator indicators), enables docking and tooltips. Returns 0 on success, -1 on error.

BOOL PreCreateWindow(CREATESTRUCT& cs)

Sets the window style (maximized — WS_MAXIMIZE).

void OnDestroy()

On closing saves the main-window position (if SW_SHOWNORMAL) into the registry profile under the #INIWND key (the format "left right top bottom").

The status bar is filled by the global functions PutTrace/PutStatistics (see section 11).

6. The CChildFrame class

Purpose: the child MDI window in which the document view lives. Header: ChildFrm.h Base class: CMDIChildWnd.

BOOL PreCreateWindow(CREATESTRUCT& cs)

Sets the style of the child window (maximized by default — WS_MAXIMIZE). The class contains no other handlers.

7. The CTMCGROUTDoc class — the document

Purpose: the data model of one document: reads/writes the .soc file, loads the S-matrix data, stores the graph and appearance parameters. Header: TMCGROUTDoc.h Base class: CDocument. Depends on: Tmcgrviw.h, Proc_s.h, SFILE95 (read_S_matrix_element).

Fields (public)

Constructor / destructor

CTMCGROUTDoc()

Initializes grdoc with default values (0 graphs, X type = GHz, Y type = VSWR, limits 1..10 / 1..1.2, auto-scale on), the colors (background white, the rest black, points red), the font Times New Roman, the editor winword.exe; calls SetDefaultLineColorWidthType().

~CTMCGROUTDoc()

Frees the data via DocFileDelData().

Public methods

void ReadDocFile(void)

What it does: re-reads the whole document. How it works: forms the .soc name (MakeDocFileName), frees the old data (DocFileDelData), counts the graphs (ReadNGraph), allocates memory (DocFileNewData), reads each graph (ReadGraph), updates the timestamps (IsDataModific).

void ReadGraphParameters(void)

Reads the parameter lines from the .soc file (one at a time) via SetOneReadGraphParameters, then applies the point color (SetGraphColor).

void ReadGraphParametersDefault(void)

Reads the default graph parameters from the registry profile (the #TMCGROTS key); the lines are separated by the ¦ character (0xA6 in Windows-1251).

BOOL WriteDocFile()

What it does: writes the current document into the .soc file and duplicates the appearance parameters in the registry. Returns: FALSE on success, TRUE on error (an atypical inversion — note it!). Features: writes the signature #TMCGROUT, the parameters block (units, axis types, limits, flags, font, colors, the 16-line parameters), then one line per graph (name caption OutFlag inp1 mod1 inp2 mod2).

void AddGraphicsInDoc(char *szSFileName)

Appends a new graph line for the given S-file to the end of the .soc file (the path is made relative via MakeRelatPathSFile). The default element parameters are 1 1 1 1 1.

BOOL IsDataModific(void)

Compares the saved LastWriteTime of the document and of all displayed S-files with the current ones. If something changed — updates the timestamps and returns TRUE, otherwise FALSE.

void SetGraphColor(void)

Assigns the point color scPointColor to all graphs.

void RunExeFile(char *lpszNameExe)

Launches the external program lpszNameExe, passing it the document path as an argument (via CreatProc).

BOOL DocFileNewData(int n)

Allocates the array grdoc.psGraph for n graphs and initializes each with the template from sGrDoc[i % 16] (color, line type/width, marker shape); allocates name buffers (300 bytes each). Returns TRUE/FALSE (out of memory).

void DocFileDelData()

Frees all the dynamic fields of the graphs (pFreq, pSmatr, the names, pcExpr) and the array itself; zeroes the counter and error.

Private methods (helpers)

Note: when adding a file to the MRU, FALSE is deliberately passed (do not add the working path) to avoid a CInvalidArgException in CRecentFileList::Add (see the code comments — the crash-bug fix).

8. The CTMCGROUTView class — the view

Purpose: drawing the graphs and all interactive work (mouse, menu, scaling, printing). The largest class of the program. Header: TMCGROUTView.h Base class: CScrollView. Depends on: Tmcgrviw.h, complex1.h, SFILE95, complex, exprint.

Fields (private, main)

MFC overrides

Coordinate transformations

The window (the real Xmin..Xmax, Ymin..Ymax) the viewport (the logical pixels nXmin..nXmax, nYmin..nYmax). All four functions do a linear transformation with clamping of the result to the boundaries.

double LXCordToDoublX(int x) / double LYCordToDoublY(int y)

Logical coordinate → real X/Y (to determine what is under the cursor).

int DoublXCordToLX(double x) / int DoublYCordToLY(double y)

Real coordinate → logical (screen) X/Y (for drawing).

double GetXAxiesUnit(void)

Returns the multiplier of the current X unit: GHz→1e-9, MHz→1e-6, kHz→1e-3, Hz→1, custom→dXAxiesUserUnit.

Preparing the data for drawing

void ReadDocFileW(void)

Re-reads the document (pDoc->ReadDocFile), re-creates the array tmcgrwin.psGraph for the number of graphs and points.

void PrepareDoubleGraph(void)

What it does: fills the real points pPoint[j] for each visible graph. How it works: for each graph and point computes X by the axis type (dividing the frequency by 1e9/1e6/…), and Y by the type (VSWR =(1+r)/(1−r), losses =−20·lg|S|, magnitude |S|, phase in rad/deg; for expressions — via the CTMCGrExpression methods). In parallel it finds the minima/maxima and, if auto-scale is on (nAFlagX/nAFlagY), sets the window limits. Calls PutStatistics1().

void PrepareLogGraph(void)

Converts all the real points into logical ones (DoublXCordToLX/Y), counts nPointDraw — the number of points within the window; points outside [Xmin,Xmax] are "snapped" to the previous one.

void RedrawViewGr(void)

PrepareDoubleGraph → PrepareLogGraph → RedrawWindow.

Drawing (private)

Mouse handlers

Menu commands (afx_msg handlers)

Other private

9. Dialogs

9.1. The CTMCGROUTDIALOGView class — the graph parameters

Header: TMCGROUTDIALOGView.h · Base class: CDialog · Resource: IDD_DIALOG1. Purpose: display settings: X/Y limits, auto-scale, X-axis unit (radio buttons Hz/kHz/MHz/GHz/custom), Y type, the point flag and size, the label formats, the document file name.

Key fields (DDX): m_XMin/m_XMax/m_YMin/m_YMax (double — the limits), m_aXSFlag/m_aYSFlag (BOOL — auto-scale), m_XUnit/m_YUnit (int — the index of the X/Y type radio group), m_dXUnit (the custom-unit multiplier), m_csXUserName (the unit name), m_csXFormat/m_csYFormat (the axis format), m_DrawPoinFlag (draw points), m_dPointSize (0..100), m_LossPoint, m_szDatFileName. The flags m_Font/m_Color/m_ColorGrid/m_ColorAxies/m_ColorBackground/m_ColorGraphics signal which additional setting to open after closing.

Methods: - BOOL OnInitDialog() — enables/disables the fields depending on the flags (for example, the Xmin/Xmax fields are unavailable under auto-scale); - OnGrparXinghz/Xinhz/Xinkhz/Xinmhz/Xinhz2 — switching the X unit, activating the custom-unit fields when m_XUnit==4; - OnGrparAxsflag/Aysflag — lock the limits under auto-scale; - OnGrparPointflag — locks the point parameters; - OnDefaultGridFormat — sets the axis format %4.3lg; - OnOk2..OnOk7 — close the dialog, setting the corresponding flag (m_Font, m_Color, m_ColorGrid, m_ColorAxies, m_ColorBackground, m_ColorGraphics).

9.2. The CDialogDoc class — the document graph table

Header: DialogDoc.h · Base class: CDialog · Resource: IDD_DIALOG2. Purpose: editing the document contents as a table of 20 rows. For each row: the graph name (m_GraphName1..20), the S-file name (m_SFileName_1..20), the inputs/modes (m_np1_*, m_np2_*, m_mod1_*, m_mod2_* — 20 each), the output flag (m_OutGrFlag_1..20).

Fields: m_DocFileName (CString) — the document file name; m_AddCharacteristicsFlag (BOOL) — set if the user pressed "add". Methods: OnAddCharacteristics() — sets m_AddCharacteristicsFlag=TRUE and closes the dialog by OK.

The large number of identical fields (*_1..*_20) is a consequence of the fixed dialog layout of 20 rows; the semantics of all the fields are identical to the corresponding fields of TMC_GR_DOC1.

9.3. The CTmcGroutColorGraphDialog class — the colors of 16 graphs

Header: TmcGroutColorGraphDialog.h · Base class: CDialog · Resource: IDD_DIALOGBARCOLORH. Purpose: setting the color/type/width of the lines for 16 graphs at once; draws line samples.

Field: sGrDoc[16] (TMC_GR_DOC1) — the working copy of the 16-line parameters. Methods: - void SetGraphParam(TMC_GR_DOC1 *sGrDoc1) — copies the 16-line parameters into the dialog (called before showing); - void GetGraphParam(TMC_GR_DOC1 *sGrDoc1) — copies them back (after OK); - void OnPaint() — draws a sample of each of the 16 lines in the static fields IDC_STATICLEVEL1..16; - OnColorLevelAutoSet…OnColorLevelAutoSet16() — handlers of the 16 buttons, each calling ChangeGraphicsPar(n) for line n=0..15; - void ChangeGraphicsPar(int n) — opens the CTmcGrParColTypWid dialog for line n, applies the chosen color/type/width; - void OnGrapparcordefault() — reset to default (SetDefault); - void SetDefault(void) — fills sGrDoc[0..15] with default colors/shapes (like CTMCGROUTDoc::SetDefaultLineColorWidthType).

9.4. The CTmcGrParColTypWid class — the parameters of a single line

Header: TmcGrParColTypWid.h · Base class: CDialog · Resource: IDD_DIALOGGRPARALL. Purpose: choosing the color, style and width of a single graph line.

Fields: LineType (int — PS_SOLID/PS_DASH/PS_DOT/…), LineWidth (int), LineColor (COLORREF); the DDX fields m_Style (the style radio group), m_Width (the width radio group). Methods: - BOOL OnInitDialog() — sets the radio buttons from LineType/LineWidth; - void OnPaint() — draws a line sample in IDC_STATICLEVEL2; - void OnGrParamColor() — the CColorDialog for choosing the line color; - OnRadio1..OnRadio5() — style selection; for a non-solid style the width is forced to 1 (the width fields are locked); - void OnOK() — converts m_Style into LineType (0→PS_SOLID, 1→PS_DASH, 2→PS_DOT, …) and m_Width into LineWidth, closes the dialog.

10. The CTMCGrExpression class — expression graphs

Purpose: parsing and evaluation of a graph given by an expression over several S-files (for example, the difference of characteristics). Syntax: text with subexpressions in square brackets [file_name], with operators/functions between them (evaluated by the exprint library). Header: src/Include/TMCGrExpression.h (shared) · Implementation: TMCGrExpression.cpp. Depends on: complex1.h (complex), inter.h (exprint — i1nte_atof_1), Tmcgrviw.h.

Fields (private)

Constructor / methods

CTMCGrExpression(char *szExpression)

Saves the expression text, zeroes the fields.

char* InitData(void)

What it does: parses the expression and allocates memory. How it works: counts the number of variables (CalcNGraphExpession), allocates the arrays, splits the string into masks and variables (Init1Data). Returns: NULL on success, otherwise an error-description string ("Bad_Nvar_or_Bad_Bracket[]", "memory_allocation_error", "init_data_error").

int GetNVar(void) — the number of variables.

char* GetFileName(int n) — the name of the n-th file (or NULL out of bounds).

double** GetFreqArray(int n) / _complex** GetSMatrArray(int n) / int* GetNPoint(int n)

Return the address of the corresponding array element (to be filled externally via CTMCGROUTDoc::ReadGraph1); NULL for an incorrect n.

BOOL IsFreqCorrect(void)

Checks that all the variables have the same number of points and matching frequencies (with a relative accuracy of 1e-15). Returns TRUE/FALSE.

BOOL IsGraphDifferent(void)

TRUE if the second character of the expression is { (the special "difference" graph mode).

Computing the value at point nPoint

Each Y type has its own method; they all assemble the string "mask₀ (value₁) mask₁ (value₂) …" and evaluate it via i1nte_atof_1 (exprint): | Method | What it substitutes | |--------|---------------------| | double GetExpressionValue(int n) | Substitutes the frequency {f=(…)} (initialization) | | double GetExpressionValueSM(int n) | The magnitude cabsv(S) | | double GetExpressionValueL(int n) | The losses −20·lg|S| | | double GetExpressionValueK(int n) | The VSWR (1+|S|)/(1−|S|) (with protection for |S|≈1) | | double GetExpressionValueSFR(int n) | The phase, radians (with "unwrapping" via GetCPhase) | | double GetExpressionValueSFD(int n) | The phase, degrees | | double GetExpressionValueSFR_User/SFD_User(int n) | The phase without unwrapping (via GetCPhase_User) |

Return: a real value; on an evaluation error they set IsError=TRUE and return 0.

double GetCPhase(int i, int nPoint) (private)

Returns the "unwrapped" (continuous) phase of variable i at point nPoint: sums the transitions through 2π.

double GetCPhase_User(int i, int nPoint) (private)

Returns the "raw" phase cphase(S) without unwrapping.

void DeleteData(void) / BOOL Init1Data(void) / int CalcNGraphExpession(void) (private)

Freeing the memory / filling the masks and variables / counting the number of variables by the brackets.

11. Global functions (in TMCGROUTView.cpp)

Declared in TMCGROUTView.h, they write text to the status bar of the main window.

Also, Tmcgrviw.h declares auxiliary global path functions (MakeRelatPathFile, MakeFullPathFile, SelectDirName, CalcNDirInPathName, RunExeFileG, CreatProcG) — their implementation may be in other modules of the package.

12. The .soc document file format

A text file. The first line is the signature #TMCGROUT. Then: - parameter lines of the form #Key value (recognized by SetOneReadGraphParameters by the prefixes from Tmcgrviw.h): the units and the X-axis name, the point flags, the axis types, the limits Xmin/Xmax/Ymin/Ymax, the auto-scale flags, the editor name, the font, the colors (text/background/axes/grid/points) and the 16-line parameters; - comments — lines starting with ! (or the part of a line after !); - graph lines: file_name [caption] [OutFlag] inp1 mod1 inp2 mod2. A name in curly braces {…} means an expression graph.

The appearance parameters are duplicated into the registry HKCU\…\#TMCGROTS (to be used as "defaults" in new documents), where the lines are separated by the ¦ character (0xA6).