The SFILE95 library — API documentation

TMC Suite package. A static library for working with binary S-files (scattering matrices). All signatures are taken from the sources in src/libs/SFILE95/ and the shared headers from src/Include/.

1. Purpose of the library

SFILE95 is a static library (StaticLibrary, UseOfMfc=false, built for win32 and x64) for working with S-files — binary scattering-matrix files of the TAMIC/TMC format.

An S-file is a file with the label "SMT" (Scattering MaTrix) of version 102, which stores the multi-frequency scattering matrix of a multiport: for each frequency point a complex S-matrix is written, as well as service information about the extrapolation grid, the number of inputs and the number of modes at the inputs.

The library provides:

• opening/closing and low-level reading/writing of S-file blocks;
• reading all frequency points of the S-matrix into memory (read_S_matrix);
• writing a single frequency point (save_S_matrix) with header formation at the first point;
• working with the global frequency table FREQUENCY (the frequency grid, the units Hz/KHz/MHz/GHz, the current point);
• merging and concatenating two multi-frequency S-matrices without duplicates, with sorting by frequency (Unite_two_S, S_add);
• saving/updating a separate column (input) of the S-matrix for a given frequency (save_S_matrix_element);
• importing S-matrix elements from HFSS and CST text files;
• maintaining offset tables of the frequency points inside the file;
• outputting a text table of the S-matrix (magnitude/phase, VSWR/losses) into a listing file (put_S_table).

2. Composition

The SFILE95.vcxproj build contains 13 .cpp files:

Legacy files outside the build (not documented)

The following files are present in the directory but are not included in SFILE95.vcxproj and are therefore not described in this documentation:

Read_s1.cpp, S_CUT.CPP, S_DB.CPP, STXTABLE.CPP, SREAD.CPP, WRTSLST.CPP, LISTING.CPP, OUTTRACE.CPP, MAIN_S.CPP, GTARGENV.CPP.

3. Structures and data types

The types _real, _complex, INT_1, WORD, DWORD are defined in external headers (typedef.h, complex1.h). In most builds _real is double (8 bytes), _complex is a pair of double (16 bytes), INT_1 is a one-byte integer type, WORD is 16 bits, DWORD is 32 bits.

3.1. S_INDEX (Postpro.h)

The extrapolation-grid index: file names and discretization steps along three axes.

typedef struct {
    char  *tpl_name;   // input-data file name (*.tpl)
    char  *S_name;     // S-matrix file name (*.s)
    double delta1;     // grid step along the X axis
    double delta2;     // grid step along the Y axis
    double delta3;     // grid step along the Z axis
} S_INDEX;

During extrapolation an array of extrapol_flag+1 S_INDEX elements is used.

3.2. INPUT_DATA (Postpro.h)

The description of the port structure of a multiport.

typedef struct {
    INT_1 num;                   // the number of inputs (ports)
    INT_1 array[MAX_INPUT_NUM];  // the number of modes on each input
    INT_1 dim;                   // the S-matrix dimension (the sum of modes over all inputs)
} INPUT_DATA;

MAX_INPUT_NUM is defined in the external header tmclimit.h.

3.3. S_HEADER (S_file.h)

The header of the offset table (a service structure).

typedef struct {
    WORD cPs;        // number of "pascal" strings in the file
    WORD cbSize;     // size of the offset table in bytes
    WORD cnFrqNum;   // number of frequencies
} S_HEADER;

3.4. S_OFFSET / _OFFSET (S_file.h)

One record of the offset table: the frequency and the position of the block in the file.

typedef struct {
    _real frq;       // frequency
    DWORD lOffset;   // offset (position) of the parameters block in the file
} _OFFSET;

typedef _OFFSET S_OFFSET;

3.5. S_OFFSET_TABLE (S_file.h)

The offset table as a whole.

typedef struct {
    WORD       cbSize;     // table size (bytes)
    WORD       cnFrqNum;   // number of frequencies
    S_OFFSET  *lpOffset;   // pointer to the array of S_OFFSET records
} S_OFFSET_TABLE;

3.6. INTERP_COEFF (S_file.h)

The coefficients of the spline interpolation over frequency.

typedef struct {
    _complex *lpxC0;   // function values
    _complex *lpxC1;   // 1st-degree spline coefficient
    _complex *lpxC2;   // 2nd-degree spline coefficient
    _complex *lpxC3;   // 3rd-degree spline coefficient
} INTERP_COEFF;

3.7. FREQUENCY (external frqdata.h)

The global frequency table. The header frqdata.h is not found in src/Include; the structure is reconstructed from the accesses in Frqdata.cpp.

The default values (from Frqdata.cpp): num = 0, max = 0, the array f is the static buffer frq_buff[FREQ_MAX_NUM], code = 3 (the current unit is GHz).

3.8. Constants (S_file.h)

4. Public functions

About the _far, _near, _fortran macros. These are memory-model and calling-convention attributes from old 16/32-bit code (Microsoft C / early Visual C++). In the modern 32/64-bit build they usually expand to nothing or to the standard calling convention and do not affect the semantics. For brevity these macros are omitted from the signatures below (a "clean" C prototype is shown). See the header S_file.h for the full prototypes with _far/_fortran.

4.1. Error handling — Errors.cpp

int put_error_messege(int err_num, ...)

Handling (output) of an error message.

• Parameters:
• err_num (int) — the error code (see section 5);
• ... — a variable number of arguments for message formatting.
• Return: always 0.
• Important: in this build the function is a stub — the entire body is commented out. No messages are output, and there is in fact no error handling. The return value is always 0 (see section 5 for the consequences).

4.2. The frequency table — Frqdata.cpp

All functions work with the single global static structure FREQUENCY frq.

int set_frequency(_real f0, _real df, int nf)

Set a uniform frequency grid: the first frequency, the step, the number of points.

• Parameters:
• f0 (_real) — the first frequency (in the current units; multiplied by unit[code]);
• df (_real) — the frequency step (in the current units);
• nf (int) — the number of points.
• Return: 0.

int set_frequency_arr(_real *ftmp, int nf)

Set the frequency grid directly from an array.

• Parameters:
• ftmp (_real*) — the array of frequency values (in the current units);
• nf (int) — the number of points.
• Return: 0.

_real get_frq_f0(int unit_flag)

Get the first frequency.

• Parameters: unit_flag (int) — if 1, the result is in the current units (divided by unit[code]); otherwise in the base units (Hz).
• Return: the value of the first frequency frq.f[0].

_real get_frq_df(int unit_flag)

Get the frequency step (f[1] - f[0]; when max == 1 returns 0).

• Parameters: unit_flag (int) — 1 → in the current units, otherwise in the base units.
• Return: the frequency step.

int get_frq_nf(void)

• Return: the number of grid points (frq.max).

int set_frq_nf(int nMax)

Set the number of points.

• Parameters: nMax (int) — the number of points; 0 < nMax <= FREQ_MAX_NUM is allowed.
• Return: 0 on success; -1 on a range violation (in which case put_error_messege(BAD_NF_PARM, ...) is called).

char* get_frq_item(int num)

• Parameters: num (int) — the unit index (0..3).
• Return: the unit string ("_Hz", "KHz", "MHz", "GHz").

char* get_current_frq_item(void)

• Return: the current-unit string (frq.item[frq.code]).

_real get_frq_unit(int num)

• Parameters: num (int) — the unit index (0..3).
• Return: the unit factor (1, 1e3, 1e6, 1e9).

void set_frq_item_num(int num)

Set the code of the current unit.

• Parameters: num (int) — the unit index (0..3).

int get_frq_item_code(void)

• Return: the code of the current unit (frq.code).

_real get_frq_element(int index)

• Parameters: index (int) — the point index.
• Return: the frequency value frq.f[index] (in base units).

void set_frq_element(_real fValue, int index)

Write a frequency by index as is (without unit conversion).

• Parameters: fValue (_real) — the value; index (int) — the point index.

void set_frq_element_unit(_real fValue, int index)

Write a frequency by index converting from the current units to base (multiplying by unit[code]).

• Parameters: fValue (_real) — the value in the current units; index (int) — the point index.

_real get_current_frq(void)

• Return: the value of the current frequency frq.f[frq.num].

double get_current_dbl_frq(void)

• Return: the current frequency cast to double (used when writing to the file).

int get_current_frq_num(void)

• Return: the index of the current frequency point (frq.num).

void set_current_frq_num(int num)

Set the index of the current frequency point.

• Parameters: num (int) — the index.

FREQUENCY* GetPointerToFrq(void)

• Return: a pointer to the global structure frq.

4.3. Low-level file work — S_file.cpp

FILE* Get_S_FILE(void)

• Return: the FILE* pointer to the open S-file (NULL if the file is not open).

void Set_PS_Number(int nNum)

Set the number of "pascal" strings in the header (stored in a static variable).

• Parameters: nNum (int) — the number of strings.

int Get_PS_Number(void)

• Return: the previously set number of "pascal" strings.

int Open_S_file(char *szFile, int nOpenMode)

Open an S-file.

• Parameters:
• szFile (char*) — the file name;
• nOpenMode (int) — the mode: S_RD (1) → opening "rb"; otherwise (S_WR) → "wb+" if the current frequency point == 0 (a new file), or "rb+" if != 0 (appending to an existing one).
• Return: 0 on success; -1 on error (put_error_messege(ERROR_OPEN_S, ...) is called).
• Note: on successful opening a BUFSIZ buffer is allocated via alloc_mem_err and assigned to the file via setbuf (if _NDP2 is not set).

void Close_S_file(void)

Close the S-file (fclose), null the pointer, free the I/O buffer.

int skip_string(void)

Skip one "pascal" string: reads the length (INT_1), then fseeks over the string length + the separator.

• Return: 0 on success; -1 on a read/seek error.

int write_S(void *ptr, size_t size)

Write a data block to the file (fwrite as a single element of size size).

• Parameters: ptr (void*) — the data; size (size_t) — the block size (bytes).
• Return: 0 on success; -1 on a write error.

int read_S(void *string, size_t size)

Read a data block from the file (fread as a single element of size size).

• Parameters: string (void*) — the receiving buffer; size (size_t) — the block size (bytes).
• Return: 0 on success; -1 on a read error.

4.4. Memory and service stubs — S_memf.cpp

void* alloc_mem_err(long size)

Allocate memory (malloc). On failure calls put_error_messege(FATAL_MEM_ALLOC_ERROR) (a stub).

• Parameters: size (long) — the block size (bytes).
• Return: a pointer to the block or NULL on failure.

int free_mem(void *mem_ptr)

Free memory (free).

• Parameters: mem_ptr (void*) — a pointer to the block.
• Return: 0.

int free_mem_null(void **ptr)

Free memory and null the pointer.

• Parameters: ptr (void**) — the address of the pointer; after the call *ptr == NULL.
• Return: 0.

void stat_messege(int num, char *mes)

An empty stub (the body is return;). It does nothing.

int get_comp_file_flag(void)

A stub. Always returns 0.

• Return: 0.
• Important: many branches (copy_S_matrix, disabling put_S_table) check this flag; since it is always 0, the corresponding logic is in fact inactive.

4.5. Reading the S-matrix — Read_s.cpp

int read_S_matrix(char *szFileName, S_INDEX **si, int *extrapol_flag, _complex ***sss, FREQUENCY *frq_out, INPUT_DATA **id)

Read all frequency points of the S-matrix from a file into memory.

• Parameters:
• szFileName (char*) — the S-file name;
• si (S_INDEX**) — output: the array of grid indices (extrapol_flag+1 elements), allocated inside;
• extrapol_flag (int*) — output: the extrapolation flag (0 — one grid, 1 — two, 2 — three);
• sss (_complex***) — output: the array of matrices by frequency (frq_out->max pointers to arrays of dim*dim complex values);
• frq_out (FREQUENCY*) — output: the filled frequency table;
• id (INPUT_DATA**) — output: the port structure.
• Return:
• 0 — success;
• -1 — a read error;
• -2 — a file-opening error;
• -3 — out of memory.
• Internal (static) functions: Read_TITLE, Read_GRID, read_string, read_CR — service ones, not exported.

void Free_GRID_Index(S_INDEX **si, int extrapol_flag)

Free the S_INDEX array (extrapol_flag+1 elements together with the file names).

• Parameters: si (S_INDEX**) — the address of the array; extrapol_flag (int) — the extrapolation flag.

void Free_S_read(_complex ***sss, int nFrqNum)

Free the array of matrices for nFrqNum frequency points.

• Parameters: sss (_complex***) — the address of the array; nFrqNum (int) — the number of frequency points.

4.6. Reading S-matrix elements (TMC / HFSS / CST) — S_remt.cpp

int read_S_matrix_element_TMC(...)

Read one S-matrix element from a TMC/TAMIC-format file (via read_S_matrix). Fills the array of complex values sss and the array of frequencies f1 (double) over nPoint points.

• Return: 0 on success, -1 on error.

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

Read one S-matrix element, automatically trying the formats in turn: first TMC, then HFSS, then CST.

• Parameters:
• in1, mod1 (int*) — the number of input 1 and mode 1;
• in2, mod2 (int*) — the number of input 2 and mode 2;
• filename (char*) — the file name;
• sss (_complex**) — output: the array of complex values (allocated inside);
• f1 (double**) — output: the array of frequencies;
• nPoint (int*) — output: the number of points.
• Return: always 0. The result is determined from *nPoint: a value <= 0 means failure (no format matched).

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

Read an S-matrix element from an HFSS text file.

• Parameters: similar to read_S_matrix_element.
• Return: 0/-1.

int SMatrixElementHFSS_InpMod(int *in1, int *mod1, int *in2, int *mod2, char *filename)

Determine the input/mode numbers for an element from an HFSS file.

• Return: the result code (see the implementation).

int SMatrixElementHFSS_ModMax(char *filename, int *pnInp)

Determine the maximum number of modes (for input *pnInp) in an HFSS file.

int SMatrixElementHFSS_InpMax(char *filename)

Determine the number of ports (inputs) in an HFSS file.

int ChooseString(char *pszBuf, char *pszIdentifInput, char *pszIdentifMode, int *pnInp, int *pnMod)

Parse a line of an HFSS file, extracting the port number and the mode number.

• Parameters:
• pszBuf (char*) — the line being parsed;
• pszIdentifInput (char*) — the input-identifier marker;
• pszIdentifMode (char*) — the mode-identifier marker;
• pnInp (int*) — output: the input number;
• pnMod (int*) — output: the mode number.

int SMatrixElementHFSS_FreqArray(int *in1, int *mod1, int *in2, int *mod2, char *filename, double **f1, _complex **sss, int *nPoint, int *nMatrixSize)

Form the array of frequencies and values for an element from an HFSS file (an aggregating function).

void SMatrixElementHFSS_FreqArrayCalculation(char *filename, double **f1, int *nPoint, int *nMatrixSize)

Count the number of points and the matrix size from an HFSS file.

void SMatrixElementHFSS_FreqArrayAllocation(double **f1, _complex **sss, int *nPoint)

Allocate memory for the arrays of frequencies and values.

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

Read the frequencies and values of an element from an HFSS file into the allocated arrays.

The CST analogues — read_S_matrix_element_CST(...) and SMatrixElementCST_*(...)

A fully analogous set of functions for importing S-matrix elements from CST text files.

Internal function: ChooseString1 — static, absent from the headers, used only inside S_remt.cpp. Not exported.

4.7. Saving a single column (input) — S_wemt.cpp

int save_S_matrix_element(int in1, char *filename, _complex *sss, double f1, int nInput)

Save one column of the S-matrix (corresponding to input in1) for the frequency f1.

• Parameters:
• in1 (int) — the input (column) number;
• filename (char*) — the S-file name;
• sss (_complex*) — the array of complex values of the column;
• f1 (double) — the frequency;
• nInput (int) — the number of inputs.
• Logic:
• if the file does not exist — a new matrix is created;
• if that frequency is not in the file — the data is written to the temporary file <filename>$ and merged with the main one via S_add;
• if the frequency already exists — the corresponding record is updated and the file is rewritten.
• Return: 0 on success; -1 on error.

4.8. The offset table — Sofftbl.cpp

int update_offset_table(_real frq, int num, int nTBL_Flag)

Write (update) an offset-table record for the frequency frq and move to the end of the file.

• Parameters:
• frq (_real) — the frequency value;
• num (int) — the frequency-point index (increased by 1 inside the function when writing the frequency counter);
• nTBL_Flag (int) — which table to update: OFF_TBL_MAIN (1) — the main one (skipped by 2 fewer "pascal" strings), OFF_TBL_APPR (2) — the interpolation-coefficient table.
• Return: 0 on success; -1 on a seek/write error.

4.9. Merging frequency grids — Unite_s.cpp

int Unite_two_S(FREQUENCY *frq_out1, INPUT_DATA *id1, _complex **sss1, FREQUENCY *frq_out2, INPUT_DATA *id2, _complex **sss2, FREQUENCY *frq_out, INPUT_DATA **id, _complex ***sss)

Merge two multi-frequency S-matrices into one: the frequency points are merged without duplicates, the result is sorted by frequency (qsort with the cmpgle comparator).

• Parameters:
• frq_out1, id1, sss1 — the first matrix (frequencies, port structure, array of matrices);
• frq_out2, id2, sss2 — the second matrix;
• frq_out (FREQUENCY*) — output: the merged frequency table;
• id (INPUT_DATA**) — output: the port structure of the result;
• sss (_complex***) — output: the array of result matrices.
• Return: 0 on success; -1 on error (the number of frequencies exceeded FREQ_MAX_NUM, or out of memory).

int cmpgle(const void *fs1, const void *fs2) — internal

A comparator for qsort: comparison of elements by frequency value (ascending). Used only inside Unite_s.cpp.

4.10. Writing the S-matrix — Write_s.cpp

int save_S_matrix(_complex *sss, INPUT_DATA *id, char *S_filename, S_INDEX *si, int extrapol_flag)

Write one frequency point of the S-matrix into a file.

• Parameters:
• sss (_complex*) — the scattering matrix (id->dim * id->dim complex values);
• id (INPUT_DATA*) — the port structure;
• S_filename (char*) — the S-file name;
• si (S_INDEX*) — the array of grid indices (extrapol_flag+1 elements);
• extrapol_flag (int) — the extrapolation flag (0/1/2).
• Logic:
• at the first point (get_current_frq_num() == 0) the number of "pascal" strings S_PS_NUMBER + 2*extrapol_flag is set and the header is written: the label/version (Write_TITLE), two TITLE strings (MAIN_LABEL, TWP_LABEL), the GRID string (Write_GRID), the .tpl/.s file names from si, two empty offset tables (the main one — for get_frq_nf() frequencies, and for the interpolation coefficients — for 0);
• then for each point: update_offset_table (records the position), writing the frequency (_real), writing INPUT_DATA (num, the array of modes, dim), a separator, the matrix, a separator.
• Return: 0 on success; -1 on error (on error put_error_messege(ERROR_WRITE_S, ...) is called).
• Internal (static) functions: Write_TITLE, Write_GRID, write_offset_table, write_string, write_CR — service ones, not exported.

4.11. Temporary file names and copying — Wrrd_s.cpp

void make_S_matrix_name(char *S_name, S_INDEX *si)

Form a temporary S-file name from the .tpl template name and the grid step. Fills the fields si->tpl_name, si->S_name, si->delta1..3.

• Parameters:
• S_name (char*) — the output name buffer;
• si (S_INDEX*) — the grid index (filled).
• Dependence of the delta1..3 values on the model:
• _MODEL_E, _MODEL_H — the step from get_data_const_delta;
• _MODEL_IC — the step from Get_Mesh_Size_X/Get_Mesh_Size_Y;
• _MODEL_M, _MODEL_W — zeros.

int copy_S_matrix(void)

Copy the temporary S-file into the output one, if get_comp_file_flag() is set.

• Return: 0.
• Important: in this build get_comp_file_flag() is a stub, always 0, so the function in fact copies nothing and simply returns 0.

4.12. Merging two S-files — Sadd.cpp

int S_add(char *filename, char *filename1)

Read two S-matrices from files, compare their grids (Compare_S_ind), merge them (Unite_two_S) and write the result into filename.

• Parameters:
• filename (char*) — the first file; the merge result is also written into it;
• filename1 (char*) — the second file.
• Return: 0 on success; -1 on error (incompatible grids or out of memory).

void Free_S(INPUT_DATA *id, S_INDEX **si, _real *f, _complex ***sss, int max, int extrapol_flag)

Free the memory allocated for a read S-matrix: id, the array of frequencies f, the matrices sss (via Free_S_read), the index si (via Free_GRID_Index).

• Parameters:
• id (INPUT_DATA*) — the port structure;
• si (S_INDEX**) — the grid index;
• f (_real*) — the array of frequencies;
• sss (_complex***) — the array of matrices;
• max (int) — the number of frequency points;
• extrapol_flag (int) — the extrapolation flag.

int Compare_S_ind(S_INDEX *si1, int extrapol_flag1, S_INDEX *si2, int extrapol_flag2)

Compare the grid parameters of two S-matrices: the extrapolation flags and the steps delta1/2/3.

• Parameters: si1/extrapol_flag1, si2/extrapol_flag2 — the indices and flags of the first and second matrices.
• Return: 0 if the grids are compatible; -1 if not.

4.13. Printing the S-matrix table — S_table.cpp

void put_S_table(_complex *lpxS, int inpnb, int *modnb)

Print a text table of the S-matrix (the magnitude and phase of the elements, as well as the VSWR or the losses in dB) into a listing file. Uses open_listing_file / l_printf / close_listing_file.

• Parameters:
• lpxS (_complex*) — the scattering matrix;
• inpnb (int) — the number of inputs;
• modnb (int*) — the array of mode counts per input.
• Note: if get_comp_file_flag() != 0, the function does nothing. Since in this build the flag is always 0, the table is always printed.

The parameter name in the external prototype (Postpro.h) is nInp_num (the number of inputs). In the implementation it may differ.

5. Error codes

The "S-matrix" section codes from Error1.h (the range 2300–2313):

Important note on the actual error handling

The function put_error_messege in this build is a stub (the entire body is commented out, it always returns 0). Therefore:

• no error messages are output to the user;
• the branches that rely on its return value execute as "success". In particular, in read_S_matrix the "not enough memory for all frequency points" branch (SMT_FRQ_MEMORY) is in fact treated as "continue" (the final ret_code = 0) rather than as a fatal error.

This should be taken into account when diagnosing: real error signaling is absent in the current build, and success/failure must be judged by the return values of the functions (-1, -2, -3, or by the output *nPoint).

6. The binary S-file format

The format is described in the header comment of the file Write_s.cpp (and implemented by the functions Write_TITLE, Write_GRID, write_offset_table, write_string, write_CR).

Notation: r — _real (8 bytes), c — complex (16 bytes), PS — a "pascal" string (a length byte, then the characters, ending with the separator 0x0A0D). The lengths are given for double precision (for single — divide by 2).

The overall file structure

The structure of the GRID "pascal" string

The structure of the offset table

Notes (from the source): 1. The dimensions of all real and complex vectors/matrices are given for the double-precision case; for single — divide by 2. 2. The type sizes are given for IBM-compatible machines. 3. A "pascal" string starts with a length byte and ends with the value 0x0A0D.

A note on the implementation: in fact Write_TITLE writes the version as 4 characters via sprintf("%3d", 102), and the "pascal"-string lengths and the PS counter are written as INT_1 (one byte) followed by a separator — this is consistent with the scheme, but the numeric lengths in the tables above are given according to the template comment. When in doubt, rely on the Write_s.cpp code.

7. Dependencies

Shared headers (src/Include/) used by SFILE95: typedef.h, tmclimit.h, frqdata.h, error1.h (Error1.h), s_file.h (S_file.h), proc_s.h, postpro.h (Postpro.h).

Complex-number math is included through complex1.h / tmc_lib.h — a connection with the complex library of TMC Suite is likely (an explicit #include in the .vcxproj dependencies is not confirmed).

No direct #includes from the TMCLibError, PREPR, exprint libraries were found in the SFILE95 sources.