TOUCHSTONE ISSUE RESOLUTION DOCUMENT (TSIRD) TSIRD ID#: 8 ISSUE TITLE: Option line changes REQUESTOR: Arpad Muranyi, Siemens EDA DATE SUBMITTED: March 20, 2024 DATE REVISED: DATE ACCEPTED: -------------------------------------------------------------------------------- DEFINITION OF THE ISSUE: Starting with Version 2.0, the format of Touchstone files was changed to follow the IBIS-like keyword style, except for the option line. However, the option line syntax is inconsistent with the keyword style syntax and poses challenges for future expansions of the specification. This proposal makes the option line optional and introduces three new keywords (and modifies the usage rules of the existing [Reference] keyword slightly) so that the information that was traditionally defined by the option line could be defined solely with keywords. -------------------------------------------------------------------------------- SOLUTION REQUIREMENTS: The Touchstone specification must meet these requirements: Table 1: Solution Requirements Requirement Notes * Make the option line optional in Version 3.0 If not present, none of its defaults are in effect * Allow a single reference argument (for all ports) in the [Reference] keyword Allow it only if the option line is not present * Make sure that the Usage Rules are consistent between all keywords Done by the Editorial Committee -------------------------------------------------------------------------------- SUMMARY OF PROPOSED CHANGES: Add three new keywords to define the option line parameters in keyword format: [Parameter Type] (required when the option line is not present), [Frequency Unit], [Complex Number Format] (required when the option line is not present, and the network data is in the frequency table format). Table 2: Touchstone Keywords Affected Specification Item New/Modified/Other Notes [Parameter Type] New Required when the option line is not present [Frequency Unit] New Required when the option line is not present, and the network data is in the frequency table format [Complex Number Format] New Required when the option line is not present, and the network data is in the frequency table format -------------------------------------------------------------------------------- PROPOSED CHANGES: Change the text of the existing Touchstone 2.1 specification throughout, as necessary, to make sure that the usage rules are consistent with the new keywords proposed in this TSIRD. Most notably, the option line is optional in Version 3.0 files. Insert the following text immediately after the "Option Line" heading (on pg. 6): Option Line For Version 3.0: The option line in Version 3.0 files is optional. If not present, i.e., there are no lines that begin with the # (hash mark) between the [Version] and [Number of Ports] keywords, none of its defaults shall be in effect. Replace the [Reference] keyword section on pg. 11 with the following: Keyword: [Reference] Required: Required, if the option line is not present, optional in Version 2.0 and 2.1, and illegal before Version 2.0. Description: The [Reference] keyword and associated argument(s) define the reference environment used for the S-parameter measurements in the network data. Usage rules: The [Reference] keyword shall appear in a file no more than once, and it shall be placed after the [Number of Ports] keyword and before the [Network Data], [Begin Pole-Residue Data], [Begin Common Poles Data] or [Begin Residues Data] keywords. The [Reference] keyword shall be followed by one or more positive integer or floating-point numbers as arguments, separated from the keyword and each other by whitespace. The arguments may span multiple lines and may begin on the line following the closing bracket of the keyword (in other words, after a line termination character or sequence). Each of the arguments is a real-valued impedance (i.e., a resistance) whose units are ohms. Note that complex and imaginary impedance values are not supported. The [Reference] keyword has no impact on G-, H-, Y-, or Z-parameter data. If the [Reference] keyword is not present, the reference resistance(s) for the S-parameter data are assumed to be defined by the option line. If the [Reference] keyword is present together with the option line, it shall contain a reference resistance argument for every port represented in the data. (For example, a 4-port data file using [Reference] shall contain four [Reference] resistance arguments). Note that in this case the option line is only allowed to contain a single reference resistance value, which is overridden by the per port reference resistance values in the [Reference] keyword. If the [Reference] keyword is present while the option line is not present, it shall be followed by either a single argument, or by as many arguments as the number of ports defined by the [Number of Ports] keyword. When the [Reference] keyword is followed by a single argument, it defines a common reference resistance for all ports. When the [Reference] keyword is followed by multiple arguments, it defines an independent reference resistance for each port. The arguments are assumed to be ordered per port numerically starting at 1 and ending with the value defined by the [Number of Ports] keyword. (For example, if [Number of Ports] contains the value "5", five arguments are expected under [Reference], ordered starting with port 1's reference resistance and ending with port 5's reference resistance). The [Reference] keyword arguments assume and refer to single-ended ports. Examples: ! Example for a Version 2.1 file with 4-port S-parameter data: ! The option line reference resistance of 50 Ohms is overridden by ! the per port reference resistances in the [Reference] keyword. ! This data cannot be represented using 1.0 syntax, but can be ! represented using 1.1 syntax (as shown in the next example). ! Note that the [Reference] keyword arguments appear on a separate ! line. [Version] 2.1 # GHz S MA R 50 [Number of Ports] 4 [Reference] 50 75 0.01 0.01 [Number of Frequencies] 1 ! Example for a Version 1.1 file with 4-port S-parameter data: ! Per port reference resistances are provided on the option line. # GHz S MA R 0.01 0.01 50.0 50.0 Add the following keywords to the Touchstone specification in the appropriate location: Keyword: [Parameter Type] Required: Required, if the option line is not present, otherwise illegal. Description: The [Parameter Type] keyword specifies what kind of network parameter data is contained in the file. Usage rules: The [Parameter Type] keyword shall be placed between the [Version] and the [Number of Ports] keyword, and shall be followed by a white space and one of the following single character arguments: S for Scattering parameters, Y for Admittance parameters, Z for Impedance parameters, H for Hybrid-h parameters, G for Hybrid-g parameters. Example: [Parameter Type] S Keyword: [Frequency Unit] Required: Required, if the option line is not present and the [Noise Data] and/or [Network Data] are present, otherwise illegal. Description: The [Frequency Unit] keyword specifies the unit of frequency. Usage rules: The [Frequency Unit] keyword shall be placed between the [Version] and the [Number of Ports] keyword, and shall be followed by a white space and one of the following arguments: Hz, kHz, MHz, GHz. Keywords which define their own unit of frequency are not affected by this keyword. Example: [Frequency Unit] MHz Keyword: [Complex Number Format] Required: Required, if the option line is not present and the [Noise Data] and/or [Network Data] are present, otherwise illegal. Description: The [Complex Number Format] keyword specifies the format of the network parameter data pairs. Usage rules: The [Complex Number Format] keyword shall be placed between the [Version] and the [Number of Ports] keyword, and shall be followed by a white space and one of the following arguments: DB for decibel-angle (decibel = 20 x log10|magnitude|) MA for magnitude-angle, RI for real-imaginary. Angles are given in degrees. Note that this format definition does not apply to noise parameters (refer to the "Noise Parameter Data" section later in this specification) and to keywords which define their own number format. Example: [Complex Number Format] RI Full Example: ! Example for a Version 3.0 file with 4-port S-parameter data: ! Note that the option line is replaced by the new keywords, and ! that the [Reference] keyword uses a single reference resistance ! argument of 50 Ohms for all ports (which is now permitted in ! Version 3.0). ! [Version] 3.0 [Parameter Type] S [Frequency Unit] MHz [Complex Number Format] MA [Number of Ports] 4 [Reference] 50 [Number of Frequencies] 100 -------------------------------------------------------------------------------- BACKGROUND INFORMATION/HISTORY: The concepts in this TSIRD are based on discussions in the IBIS Interconnect Task Group on this subject during the month of February 2024.