The TMCROS program — API documentation

TMC Suite package. A viewer of time characteristics (time-domain signals) and a "time → scattering matrix" transformation tool (Time-to-Scattering). All signatures are taken from the sources in src/viewers/Tmcrtout/ and the shared headers from src/Include/.

1. Purpose of the program

TMCROS (the output EXE — TMCROS.exe, the TMCROS.vcxproj project) is a graphical viewer of electrodynamic-computation results in the time domain: it builds 2D graphs of time signals of a multiport read from signal output files (.t — Rt-Signal), and can compute from them a scattering matrix at given frequencies (the "time → S-matrix" transform, the TtoS subsystem).

The program is built on the same MFC Document/View scheme (an MDI application) as the related frequency viewer TMCGROUT, and shares most of its source files and data model. The key differences of TMCROS:

• the X axis is time (n, s, ms, µs, ns, ps), not frequency;
• the Y axis is the time signal and quantities derived from it (the amplitude envelope, VSWR/losses/phase computed from the envelope);
• the data is read from signal files .t (not from S-files): the read_RT_output_signal function in CTMCGROUTDoc;
• the document has the extension .tos and the signature #TMCGROTS (TMCGROUT has .soc / #TMCGROUT);
• a Time-to-Scattering subsystem is added: the classes CTmcSMatrix, CTmcTtoS and the dialog CDialogTtoS, which convert a set of time signals into one S-file (.s) at given frequencies (the "To S-matrix" menu item);
• a second point buffer tmcgrwin1 is introduced in the view (a working copy for drawing, see §8).

TMCROS is positioned as a time (intermediate) viewer: it shows the signals and prepares an S-matrix from them, which is then viewed in TMCGROUT.

Coincidence of file names with TMCGROUT. The files TMCGROUT.cpp/.h, MainFrm, ChildFrm, TMCGROUTDoc, TMCGROUTView, TMCGROUTDIALOGView, DialogDoc, TmcGroutColorGraphDialog, TmcGrParColTypWid, TMCGrExpression are named the same as in TMCGROUT (historically TMCROS was made by copying the TMCGROUT project), but they contain different logic in the time-data and TtoS parts. Below, what is truly identical to TMCGROUT is described briefly with a reference; the differences are documented in full.

2. Project composition

The TMCROS.vcxproj build contains the following files (by <ClCompile>/<ClInclude>):

The file TmcGrParColTypWid1.cpp/.h (the class CTmcGrParColTypWid1) physically lies in the directory but is not included in TMCROS.vcxproj (absent from <ClCompile>/<ClInclude>) — it does not take part in the build. See §9.5.

Dependencies and build settings (TMCROS.vcxproj): - UseOfMfc = Static, CharacterSet = MultiByte, PlatformToolset = v145; the Win32 and x64 configurations (Debug/Release); - linking with the package libraries: SFILE95 (sfile95.lib — writing the S-matrix save_S_matrix_element), complex (complex.lib), exprint (exprint.lib — expression evaluation); - the output directory from build\ExeOutput.props → dist\<platform>\bin; - the shared headers from src/Include/: tmcgrviw.h, proc_s.h, s_file.h, typedef.h, complex1.h, TmcSMatrix.h, TmcTtoS.h, TMCGrExpression.h.

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

TMCROS uses the same data-model structures as TMCGROUT (TMC_GR_DOC1, TMC_GR_DOC, TMC_GR_VIEW, TMC_GR_WINDOW, TMC_GR_TYPE_X/Y). For the full field description, see tmcgrout.md, §3. Here the differences in field interpretation and the type constants specific to the time viewer are recorded.

3.1. Difference in the interpretation of the TMC_GR_DOC1 fields

In TMCROS the graph-structure fields are read from a signal file .t, so their physical meaning is different:

The other fields (nPoint, szGrapName, szGrapPodp, LineColor/Type/Width, piPoint[10], PointColor/Type/Width, OutFlag, LastWriteTime, pcExpr) — as in TMCGROUT.

3.2. X-axis type constants (time) — TMC_GROTS_TYPE_*

3.3. Y-axis type constants — TMC_GROTS_TYPE_*

The type array in CTMCGROUTView (gr_typY) presents 7 items to the user: Signal, Amplitude, WSVR, L dB, Phase in radian, Phase in gradus, Delta Phase (plus a terminator).

3.4. File/document constants — TMC_GROTS_*

The other constants (TMC_GROUT_MAXSTRING_BUF, TMC_GROUT_POINT_TYPE, TMC_VIEW_XSIZE/YSIZE, TMC_VIEW_SIZEMODE, the window identifiers TMC_GROUT_DOCFILE_ID_INIWND / …_INIWNDVWPRT) — shared with TMCGROUT.

4. The CTMCGROUTApp class

Purpose: the MFC application class. Identical to TMCGROUT in structure (see tmcgrout.md, §4), with a single difference:

• InitInstance() calls SetRegistryKey("TMCROS") (not "TMCGROUT") — the settings and the recent-files list (MRU) are stored in HKCU\…\TMCROS.

The rest: AfxOleInit(), Enable3dControls()/Static, LoadStdProfileSettings(9), registering CMultiDocTemplate (CTMCGROUTDoc+CChildFrame+CTMCGROUTView, the resource IDR_TMCGROTYPE), auto-opening the first existing file from the MRU when the command line is empty, restoring the window position from the profile (#INIWND), showing the window SW_RESTORE. Header: TMCGROUT.h · Base class: CWinApp · Global object: CTMCGROUTApp theApp; The nested class CAboutDlg (in TMCGROUT.cpp) — the "About" dialog.

5. The CMainFrame class

Identical to TMCGROUT (see tmcgrout.md, §5). The main MDI window with a toolbar and a 2-panel status bar; OnCreate, PreCreateWindow (WS_MAXIMIZE), OnDestroy (saving the window position to the registry under #INIWND). Header: MainFrm.h · Base class: CMDIFrameWnd.

6. The CChildFrame class

Identical to TMCGROUT (see tmcgrout.md, §6). The child MDI window, maximized by default (WS_MAXIMIZE). Header: ChildFrm.h · Base class: CMDIChildWnd.

7. The CTMCGROUTDoc class — the document

Purpose: the document data model: reads/writes the .tos file, loads time signals from .t files, stores the graph and appearance parameters. Header: TMCGROUTDoc.h · Base class: CDocument · Depends on: Tmcgrviw.h, proc_s.h, SFILE95.

The class structure (the fields and most methods) coincides with TMCGROUT (see tmcgrout.md, §7). Below are the differences specific to the time viewer.

7.1. An additional field

The other fields (grdoc, sGrDoc[16], bLossPoint, the colors scBackgoundColor/scGridColor/scAxiesColor/scTextColor/scPointColor, lfInitial, csEditorName, error[300], piProcInfo) — as in TMCGROUT. Note: the TMCROS version of the header lacks the fields dXAxiesUserUnit/csXAxiesUserName (a custom X-axis unit is not provided — the X axis is always time).

7.2. Reading data — the key difference

Instead of reading S-files via read_S_matrix_element (as in TMCGROUT), TMCROS reads a time signal with its own function:

void read_RT_output_signal(int *in1, int *mod1, int *in2, int *mod2, char *filename, _complex **sss, double **f1, int *nPoint, double *dFr)

What it does: reads the .t signal file and fills the time array *f1 and the signal-sample array *sss. How it works: 1. normalizes the address: *in1≥1, *mod1∈{0,1}, *in2=1, *mod2∈{0,1}; 2. the first pass — counts the number of data lines (lines starting with a space) → nPoint; in parallel it finds the #TMC_GROTS_Freq … line and reads the frequency into *dFr (by default 1e10); 3. allocates the memory sss[n], f1[n]; 4. the second pass — for each data line: f1[i] = gets_f1(ch) (the time), sss[i].x = gets_sss(ch, in1, mod1) (the signal sample for input in1, component mod1).

Errors: if the file cannot be opened or the data is empty, *nPoint=0; the calling ReadGraph1 writes Error_when_read_<name> into the caption.

Auxiliary methods for parsing a .t line

void ReadGraph1(int nGr, char *szFileName, int *nPoint, double **pFreq, _complex **pSmatr)

Difference from TMCGROUT: forms the absolute file path relative to the document directory and calls read_RT_output_signal (not read_S_matrix_element). When *nPoint<=0 it writes Error_when_read_<name> into szGrapPodp.

void ReadGraph1Expession(int nGr, char *szExpression)

Like TMCGROUT, but the "file" variables in the expression are .t signals (read via ReadGraph1 → read_RT_output_signal). Checks that the time grids coincide (IsFreqCorrect).

7.3. Document name and format — differences

7.4. The other methods

They coincide with TMCGROUT (see tmcgrout.md, §7): ReadDocFile, ReadGraphParameters, ReadGraphParametersDefault, WriteDocFile, AddGraphicsInDoc, IsDataModific, SetGraphColor, RunExeFile, DocFileNewData, DocFileDelData, ReadNGraph, ReadGraph, ReadInputModeFromFileName (if present), SetOneReadGraphParameters, SetDefaultLineColorWidthType, MakeRelatPathSFile, CalcNDirInPathName, SelectDirName, LastWriteTime, del_bl2, del_bl3, put_error_messege, CreatProc.

8. The CTMCGROUTView class — the view

Purpose: drawing the time graphs, interaction (mouse, menu, scaling, printing) and launching the TtoS dialog. Header: TMCGROUTView.h · Base class: CScrollView · Depends on: Tmcgrviw.h, complex1.h, DialogTtoS.h.

The structure coincides with TMCGROUT (see tmcgrout.md, §8); below are the differences.

8.1. Additional fields

8.2. Preparing the data for drawing — differences

void PrepareDoubleGraph(void)

What it does: fills the real points pPoint[j] for each visible graph, based on the time axis types. How it works: - X = time: pFreq[j], divided by the unit multiplier (GetXAxiesUnit: s→1, ms→1e3, µs→1e6, ns→1e9, ps→1e12; for nT — the point number); - Y — by nYType: - TMC_GROTS_TYPE_FULL — the signal sample pSmatr[j].x as is; - TMC_GROTS_TYPE_AMPL — the amplitude envelope r14, reconstructed from the local extrema of the signal (tracking a triple of adjacent samples r11,r12,r13 and the sign change of the derivative); - TMC_GROTS_TYPE_WSVR — (1+s)/(1−s) from the envelope s (with protection for |s|≈1); - TMC_GROTS_TYPE_LDB — −20·lg(envelope); - TMC_GROTS_TYPE_PHAS_R / PHAS_G — the phase (rad/deg), estimated from the moments of the signal's sign change and the frequency dFreq; - for expression graphs the value is taken from the CTMCGrExpression methods (GetExpressionValueL/K/SM). - in parallel it finds the X and Y min/max; with auto-scale on (nAFlagX/nAFlagY) it sets the window limits; it calls PutStatistics1().

The algorithm for reconstructing the envelope and phase from a time signal is scientific logic. The TMC_GR_TYPE_SFD branch is commented out in the code.

void PrepareLogGraph(void)

Converts the real points into logical ones (DoublXCordToLX/Y), counts nPointDraw, snaps points outside [Xmin,Xmax]. Afterwards it copies the result into tmcgrwin1 (re-creating its array for the number of graphs and nPointDraw).

double GetXAxiesUnit(void)

Returns the multiplier of the current time unit: s→1, ms→1e3, µs→1e6, ns→1e9, ps→1e12 (for nT it is handled separately). This differs from the frequency GetXAxiesUnit in TMCGROUT.

8.3. Drawing — differences

• OnDrawGraph(CDC*) makes 3 passes (OnDrawGraph1/2/3), but draws from tmcgrwin1 (not tmcgrwin).
• OnDraw: background → (on error — the text and exit) → zoom frame → grid → axes → graphs → OnDrawMouseScrol. On the first call (FlagResizeInit) it fits the viewport (OnViewResizectrlr).
• onDrowAxies/onDrawGrid/OnDrawLine/OnDrawPoint/OnDrawBackground/OnDrawMouseResize/VTextOut/SetRectOutXY/IvalidateRectView — as in TMCGROUT.

8.4. A new menu command — TtoS

afx_msg void OnEditTosmatrix() (the command ID_EDIT_TOSMATRIX, the "To S-matrix" item)

What it does: opens the CDialogTtoS dialog to convert the document's time signals into an S-file. How it works: 1. passes the document name (m_DocFileName = GetPathName()) and the current time limits (m_dTmin/m_dTmax = tmcgrwin.sGrWin.Xmin/Xmax) to the dialog; 2. by tmcgrwin.nXType sets the time-unit multiplier dlg.dTUnit and the label m_csTimeUnit (ps/ns/mks/ms/s; default — the unit, limits 0..1); 3. for each of the ≤20 graphs copies into the dialog the signal-file name (m_SFileName_<k>), the output flag (m_OutGrFlag_<k>) and the frequency (m_dXValue<k> = psGraph[k].dFreq); 4. shows the dialog; the export is performed inside the dialog (OnExportCharacteristics/OnOK).

8.5. Other handlers

The commands for scaling, mouse, colors, font, editor, file, auto-scale, Home/End scrolling, the timer (re-reading on file change) — as in TMCGROUT (see tmcgrout.md, §8). The "custom X unit" selection command is absent in TMCROS (the X axis is always time). The global functions PutTrace/PutStatistics (writing to the status bar) — see §11.

9. Dialogs

9.1. CTMCGROUTDIALOGView — the graph parameters

Header: TMCGROUTDIALOGView.h · Base class: CDialog · Resource: IDD_DIALOG1. Structurally as in TMCGROUT (see tmcgrout.md, §9.1): X/Y limits, auto-scale, X type (the time unit radio group), Y type (Signal/Amplitude/…), the point flag and size, the label formats, the document name. The difference — the X radio group corresponds to time units, not frequency.

9.2. CDialogDoc — the document graph table

Header: DialogDoc.h · Base class: CDialog · Resource: IDD_DIALOG2. Purpose: editing the document contents as a table of 20 rows (graph name, file name, inputs/modes np1/mod1, the output flag). Coincides with TMCGROUT, but: - contains an additional field double dTUnit — the time-unit multiplier; - the input/mode semantics refer to the columns of the time signal, not the S-matrix.

Fields: m_DocFileName; 20 each of m_GraphName*, m_SFileName_*, m_np1_*, m_mod1_*, m_OutGrFlag_*; m_AddCharacteristicsFlag (BOOL — "add" pressed); dTUnit. Methods: OnAddCharacteristics() — sets m_AddCharacteristicsFlag and closes the dialog; OnNotify (overridden).

The fields m_np2_*/m_mod2_* are absent from the TMCROS version of DialogDoc.h (unlike the TMCGROUT description) — only the first address np1/mod1 is set.

9.3. CDialogTtoS — the "time → S-matrix" transform (NEW, only in TMCROS)

Header: DialogTtoS.h · Base class: CDialog · Resource: IDD_DIALOG3 · Implementation: DialogTtoS.cpp. Purpose: to gather up to 20 signal files .t, set for each a frequency, a time range [Tmin,Tmax] and a time unit, and export the result — the reconstructed S-matrix — into a single S-file .s.

Fields (DDX): | Field | Type | Purpose | |-------|------|---------| | m_DocFileName | CString | The document file name (for building paths) | | dTUnit | double | The time-unit multiplier (set from the view) | | m_SFileName | CString | The name of the output S-file (.s); by default <document>.s | | m_SFileName_1..20 | CString | The names of the input .t signal files (up to 20) | | m_OutGrFlag_1..20 | BOOL | The "process this file" flag | | m_dXValue1..20 | double | The frequency (Hz) for the corresponding .t file | | m_dTmin, m_dTmax | double | The time range (in the current units) | | m_csTimeUnit | CString | The time-unit label (ps/ns/mks/ms/s) | | m_dXmin, m_dDx | double | The start frequency and step for auto-filling the frequencies (by default 1e10 and 1e8) | | m_csError | CString | The text of the last conversion error |

Methods: - INT_PTR DoModal() — before showing it builds the absolute paths: the output .s name = <document without extension>.s, and each non-empty m_SFileName_<k> is reduced to the form <document directory>\<name>; - void OnChangeSfilename() — choosing the output .s-file name via CFileDialog (the "Tamic S-matrix" filter, mask *.s); - void OnAddCharacteristics() — choosing an input .t file (CFileDialog, "Tamic Rt-Signal", mask *.t) and writing it into the first free cell m_SFileName_1..20; - void OnChangeSfiledelet() — deletes the file named m_SFileName from disk (remove); - void OnExportFillxvalue() — fills m_dXValue1..20 with an arithmetic progression: m_dXmin, +m_dDx, +2·m_dDx, …; - void OnExportCharacteristics() — the main action: for each k that has m_OutGrFlag_k and a non-empty name, calls CTmcTtoS::TtoS(m_SFileName_k, m_SFileName, m_dTmin*dTUnit, m_dTmax*dTUnit, m_dXValue_k); on error writes it into m_csError and stops; - void OnOK() — calls OnExportCharacteristics(), then CDialog::OnOK().

Errors/features: the input signals are converted in turn into one output S-file (each TtoS call appends a matrix row — see CTmcSMatrix::Save); the export stops at the first error.

9.4. CTmcGroutColorGraphDialog, CTmcGrParColTypWid

Identical to TMCGROUT (see tmcgrout.md, §9.3 and §9.4): setting the color/type/width of 16 lines and of a single line respectively. Headers TmcGroutColorGraphDialog.h, TmcGrParColTypWid.h.

9.5. CTmcGrParColTypWid1 (NOT in the build)

Header: TmcGrParColTypWid1.h · Base class: CDialog · Resource: IDD_DIALOGGRLINECOLORTYPEWIDTH1. An empty dialog stub (no fields or handlers, only DoDataExchange). Not included in TMCROS.vcxproj and does not take part in the build — left in the directory as an artifact.

10. The Time-to-Scattering (TtoS) subsystem

The conversion of a set of time signals into a scattering matrix at a given frequency. The idea: from two adjacent samples of the harmonic signal s(t)=A·sin(ωt+φ) the amplitude A and phase φ (the complex S) are reconstructed, averaged over all pairs of points in the range; the excited input determines the row of the S-matrix.

10.1. The CTmcTtoS class — the "file .t → file .s" wrapper

Header: src/Include/TmcTtoS.h · Implementation: TmcTtoS.cpp · Depends on: TmcSMatrix.h, tmcgrviw.h.

Fields (private): | Field | Type | Purpose | |-------|------|---------| | cSMatrix | CTmcSMatrix | The working conversion core | | csSFileName | CString | The output .s name | | csTFileName | CString | The input .t name | | csError | CString | The error text (by default "No error") | | dTmin, dTmax | double | The time range (seconds) | | dFreq | double | The frequency (Hz) at which S is reconstructed | | bIsError | BOOL | The error flag |

Methods: | Method | What it does | |--------|--------------| | void TtoS(CString csTfn, CString csSfn, double dTmin1, double dTmax1, double dFreq1) | The main public call: saves the parameters and performs TtoS() | | void TtoS(void) (private) | MakeSmatrixFromFileT() → SaveSmatrixToFileS() | | void MakeSmatrixFromFileT(void) | Reads the .t (cSMatrix.ReadTFile) and builds the S-matrix (cSMatrix.MakeSmatrix); transfers the core errors into csError | | void SaveSmatrixToFileS(void) | Saves the result into the .s (cSMatrix.Save(csSFileName, dFreq)) | | BOOL IsError(void) | The error flag | | CString& GetErrorMessage(void) | The error text | | void DeleteData(void) (private) | Reset of the fields and cSMatrix.DeleteData() |

10.2. The CTmcSMatrix class — the core of reconstructing S from a signal

Header: src/Include/TmcSMatrix.h · Implementation: TmcSMatrix.cpp · Depends on: typedef.h (_complex), proc_s.h, s_file.h (SFILE95 — save_S_matrix_element).

Fields (private): | Field | Type | Purpose | |-------|------|---------| | csTFileName, csSFileName | CString | The names of the input .t and the output .s | | csError | CString | The error text | | dTmin, dTmax | double | The time range | | dFreq | double | The reconstruction frequency (Hz) | | bIsError | BOOL | The error flag | | pcSmatrix | _complex* | The reconstructed row of the S-matrix (nInput elements) | | pdTsignal | double* | The signal samples of all inputs (nPoint*nInput*2) | | pdTime | double* | The time samples (nPoint) | | nInput | int | The number of inputs (signal columns) | | nPoint | int | The number of time points in the range | | nLineInSMatrix | int | The index of the excited input = the S-matrix row number (−1 — undefined) |

Public methods: | Method | What it does | |--------|--------------| | void ReadTFile(CString csTFile, double dTmin1, double dTmax1) / void ReadTFile(void) (private) | Reads the .t: checks Tmax>Tmin, counts nPoint (CalcNPoint) and nInput (CalcNInput), allocates the arrays (AllocTArray), reads the data (ReadTArray) | | void MakeSmatrix(void) | Reconstructs S: AllocSArray() → TtoS() → SetnLineInSMatrix() | | void Save(CString csSFileName1, double dFreq1) / void Save(CString csSFileName1) / void Save(void) (private) | Writes the S-matrix row into the .s via save_S_matrix_element(nLineInSMatrix+1, …, pcSmatrix, dFreq, nInput) | | BOOL IsError(void) / CString& GetErrorMessage(void) | The error flag and text | | void DeleteData(void) | Freeing the arrays and resetting the fields |

Private methods (the algorithm): | Method | Purpose | |--------|---------| | int CalcNPoint(void) | Counts the number of data lines in the range [Tmin,Tmax]; in parallel reads the frequency from #TMC_GROTS_Freq; requires >5 points | | int CalcNInput(void) | From the first data line determines the number of inputs: (numbers_in_line − 2)/3 | | double gets_f1(char *ch) | Reads the time from a line (sscanf "%d%lg") | | int gets_nNumbersInLine(char *ch) | Counts the number of "word" numbers in a line | | void AllocTArray(void) | Allocates pdTsignal[nPoint*nInput*2], pdTime[nPoint] | | void ReadTArray(void) | Reads the signal samples of all inputs in the time range (readTsignal/readTsignalOne) | | void readTsignal(double **pdTsign, char *ch) / int readTsignalOne(…) | Parsing one line: skipping the number and time, then nInput pairs (Re/Im of the signal) | | int skip_blank(char*) / int skip_number(char*) | Skipping spaces/a number | | void AllocSArray(void) | Allocates pcSmatrix[nInput], initializes with FLT_MAX | | void TtoS(void) | For all inputs calls TtoSOneInput | | void TtoSOneInput(int n) | Averages the complex S of input n over all pairs of adjacent points (TtoSOneInputOnePoint) | | BOOL TtoSOneInputOnePoint(_complex *acc, double s1, double t1, double s2, double t2) | From a pair (s,t) solves the system for A and φ of the harmonic A·sin(ωt+φ) at the frequency dFreq; adds A·(cosφ, sinφ) to the accumulator. Returns TRUE if the contribution was taken into account | | void SetnLineInSMatrix(void) | Finds the single excited input → nLineInSMatrix; an error if not exactly one is excited | | BOOL IsInputExcite(int n) | TRUE if input n has non-zero samples (the input is excited) | | void PutErrorMessage(char *ch) | Sets bIsError and the error text |

The .t signal file format (by the parsing code): the data lines start with a space and contain point_number time [for each input: number Re Im] …; the service line #TMC_GROTS_Freq <frequency> sets the frequency; the file signature is #TMC_GraphicsOutputSignalFile FormVer2.0 2000.

The math of reconstructing S from a signal (TtoSOneInputOnePoint, the averaging, the excited-input criterion) is a scientific algorithm; do not change it without agreement.

10.3. Known defects in the TtoS code (for reference)

In CTmcSMatrix::CalcNPoint() and CalcNInput(), on a file-open error the call sprintf("Can't open file {%s}", csTFileName); is made without a receiving buffer (the first argument is the format, not a buffer). This is an erroneous call (a potential failure). It is noted as a code defect.

11. The CTMCGrExpression class — expression graphs

Identical to TMCGROUT (see tmcgrout.md, §10). Parses an expression over several files ([name] variables), computes the value at a point via exprint (i1nte_atof_1). In TMCROS the "file variables" are .t signals, and the GetExpressionValue* methods are applied to the quantities reconstructed from the signal. Header: src/Include/TMCGrExpression.h · Implementation: TMCGrExpression.cpp.

12. Global functions (in TMCGROUTView.cpp)

As in TMCGROUT (see tmcgrout.md, §11). Declared in TMCGROUTView.h: void PutTrace(CString), void PutTrace(char*), void PutStatistics(CString), void PutStatistics(char*) — output into panels 0 and 1 of the status bar.