TOUCHSTONE ISSUE RESOLUTION DOCUMENT (TSIRD) TSIRD ID#: 5.1 ISSUE TITLE: Per Port Reference Resistance on the Option Line REQUESTOR: Arpad Muranyi, Randy Wolff, Siemens EDA; Bob Ross, Teraspeed Labs DATE SUBMITTED: June 14, 2023; July 5, 2023 DATE REVISED: DATE ACCEPTED: September 15, 2023 -------------------------------------------------------------------------------- DEFINITION OF THE ISSUE: The Touchstone 2.0 specification supports only a single reference resistance value on the option line. Even though the [Reference] keyword in the Touchstone 2.0 specification provides a way to generate Touchtone files with per-port reference resistance values, there are Touchstone files in circulation in the industry which don't make use of any of the Touchstone 2.0 keywords, yet the per port reference resistance values appear on the option line using an unofficial syntax. In addition, this non-Touchstone-specification-compliant syntax is supported by some EDA tools. For these reasons it would be desirable to include this syntax in the Touchstone specification so that all EDA vendors could implement official support for such Touchstone files. -------------------------------------------------------------------------------- SOLUTION REQUIREMENTS: The Touchstone 2.1 specification must meet these requirements: Table 1: Solution Requirements Requirement Notes * The option line definition should include support for per port resistance * An internal designation of Version 1.1 is added in this document to define the per port reference resistance option line syntax and related rules * Version 2.1 is added to the title of this specification to distinguish it from Version 2.0 which did not support per port reference resistance on the option line * A corresponding Version 2.1 Touchstone parser is expected to be developed to be able to parse Version 1.1 files according to the Version 2.1 specification * Revert back to Version 2.0 wording for the general .ts extension suggestion * * This should be done without affecting the syntax and rules of the Version 1.0 and Version 2.1 portions of the specification Like Version 1.0, Version 1.1 is determined by the option line syntax, and NOT by an explicit version keyword Option line per port reference resistance values are only permitted in Version 1.1 files The [Version] keyword argument is 2.0 or 2.1, and it is noted that the rules are the same for [Version] 2.0 and 2.1 Change: all versions of Touchstone files of item 4. in GENERAL SYNTAX RULES AND GUIDELINES back to Touchstone 2.0 files. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- SUMMARY OF PROPOSED CHANGES: Extend the definition of the option line syntax and rules to support per port reference resistance on the option line. Use Version 1.1 in this document to describe the extended option line syntax and rules for files which would otherwise satisfy the Version 1.0 requirements. -------------------------------------------------------------------------------- PROPOSED CHANGES: Most changes are marked in Red in the original Touchstone Version 2.0 Specification, until the [Matrix Format] keyword. Additional changes were made with the "track changes" feature of Word turned on. Most changes associated with TSIRD3 and TSIRD4 are NOT included. Touchstone(R) File Format Specification Version 2.1 Ratified by the IBIS Open Forum TBD Update this information Copyright (C) 2009 by TechAmerica. This specification may be distributed free of charge, as long as the entire specification including this copyright notice remain intact and unchanged. Touchstone(R) is a registered trademark of Agilent Technologies, Inc. and is used with permission. TABLE OF CONTENTS TABLE OF CONTENTS 4 INTRODUCTION 5 GENERAL SYNTAX RULES AND GUIDELINES 6 FILE FORMAT DESCRIPTION 7 Introduction 7 Comment Lines 7 [Version] 8 Option Line 8 Option Line Examples 10 [Number of Ports] 10 [Two-Port Data Order] 11 [Number of Frequencies] 11 [Number of Noise Frequencies] 12 [Reference] 12 [Matrix Format] Error! Bookmark not defined. [Network Data] Error! Bookmark not defined. Single-Ended Network Parameter Data Error! Bookmark not defined. 1-port and 2-port Networks Error! Bookmark not defined. 3-port and 4-port Networks Error! Bookmark not defined. 5-port and Above Networks Error! Bookmark not defined. Introduction to Mixed-Mode Concepts Error! Bookmark not defined. [Mixed-Mode Order] Error! Bookmark not defined. Mixed-Mode Network Parameter Data Error! Bookmark not defined. [Noise Data] Error! Bookmark not defined. Noise Parameter Data Error! Bookmark not defined. [End] Error! Bookmark not defined. INFORMATION DESCRIPTION Error! Bookmark not defined. Introduction Error! Bookmark not defined. [Begin Information], [End Information] Error! Bookmark not defined. Information Keywords Error! Bookmark not defined. COMPATIBILITY NOTES Error! Bookmark not defined. APPENDIX A: Examples of Mixed-Mode Transformations Error! Bookmark not defined. Transformations Between Conventional and Mixed-Mode Matrices for a Pair of Ports Error! Bookmark not defined. S-parameters Error! Bookmark not defined. Y- and Z-parameters Error! Bookmark not defined. Mutual Transformations in Cases of Several Port Pairs Error! Bookmark not defined. INTRODUCTION A Touchstone file (also known as an SnP file) is an ASCII text file used for documenting the n-port network parameter data of an active device or passive interconnect network. While Touchstone files have been accepted as a defacto standard for the transfer of frequency dependent n-port parameters, no formal specification of the file format or syntax had been produced before Touchstone Version 2.0 was published in year 2009. That document, based upon information from Agilent Technologies, Inc. (the originator of Touchstone), was the first formal specification of the Touchstone file format and was intended for use with documents and specifications produced by the IBIS Open Forum. Version 2.0 was created based upon the original Agilent Technologies, Inc. documentation with added features in the style of IBIS (I/O Buffer Information Specification). Files written using the original syntax are compatible with the Version 2.0 specification and are referred to as Version 1.0 files, even though a Version 1.0 specification was never published. In this document Version 1.0 is an internal designation for files which use the option line syntax that supports at most a single reference resistance for all ports. Version 1.1 is an internal designation for files which use the option line syntax that supports different reference resistances for the ports. In this document, if no differences are noted by a Version 1.1 rule, the statements designated as Version 1.0 also apply for Version 1.1 files. Except for the [Version] string argument "2.1" added in this document, the syntax and rules for [Version] 2.1 files are identical with those published in the Touchstone Version 2.0 File Format Specification for [Version] 2.0 files. GENERAL SYNTAX RULES AND GUIDELINES The following are the general syntax rules and guidelines for a Touchstone file. * Touchstone files are case-insensitive. * Only US-ASCII + graphic characters (i.e., code values 20h through 7Eh), + tab characters (09h), and + line termination sequences, e.g., LF (0Ah), CR+LF (0Dh + 0Ah), or CR (0Dh), each encoded in 8 bits as defined in ISO/IEC 8859-1:1998 are permitted in a Touchstone file. * Comments are preceded by an exclamation mark (!). Comments may appear on a separate line or after the last data value on a line. Comments are terminated by a line termination sequence (i.e., multi-line comments are not allowed). * Touchstone filenames have traditionally used a file extension of ".snp", where n is the number of network ports of the device or interconnect being described. For example, a Touchstone file containing the network parameters for a 2-port device would be named "filename.s2p", while a Touchstone file containing the data for a 3-port network would be "filename.s3p", and so on. Not all operating systems may recognize filename extensions with variable contents or length as associated with the same type of file. To address this, the extension .s2p often has been applied to Touchstone files describing systems containing other than two ports. For the same reasons, the extension ".ts" is suggested for Touchstone 2.0 files. To preserve support of existing Touchstone files and ensure maximum compatibility across operating systems, the use of filename extensions other than those recommended here is permitted by this specification. For Version 2.1, the [Number of Ports] keyword and argument establish the expected number of ports defined in the file. * All angles are measured in degrees. * Scientific notation is allowed (e.g., 1.2345e-12). No minimum or maximum limits are placed on numerical precision on individual data points. * Keywords (as used in Version 2.1 files) shall be enclosed in square brackets, "[" and "]", and shall start in column 1 of the line. No space or tab is allowed immediately after the opening bracket "[" or immediately before the closing bracket "]". The keyword syntax, including spelling of words and placement of non-alphabetic characters, shall follow exactly what is documented in this specification. If used, only one space (" ") or dash ("-") character separates the parts of a multi-word keyword. * Arguments after keywords shall be separated from the closing bracket of the keyword by at least one whitespace character. Except where otherwise noted, this whitespace separation shall not include carriage return or line feed characters. * Blank lines are permitted. FILE FORMAT DESCRIPTION Introduction Touchstone data files consist of an "option line" followed by network parameters taken at specific frequencies. The option line specifies (among other things) the kind of n-port parameters the file contains (S-parameter, Z-parameter, etc.) and the format of the network data values (magnitude-phase, real-imaginary, etc.). Data is arranged into groups of n-port parameters preceded by the frequency at which the data was taken or derived. For each frequency, data for a 1-port or 2-port network is contained on a single data line while data for 3-port and above networks is arranged in a matrix row-wise order. The Touchstone format supports matrices of unlimited size. Some keywords are required to be in a particular order and placed at the beginning of the file. These are shown below: * [Version] 2.1 * # (option line) * [Number of Ports] The following keywords shall appear after [Number of Ports] and before [Network Data], but may appear in any order relative to each other. * [Two-Port Data Order] (required if a 2-port system is described) * [Number of Frequencies] (required) * [Number of Noise Frequencies] (required if [Noise Data] defined) * [Reference] (optional) * [Matrix Format] (optional) * [Mixed-Mode Order] (optional) * [Begin Information]/[End Information] (optional) The Touchstone data in Version 2.1 files is positioned under two required keywords in the order shown below. The network data is required and positioned after the required [Network Data] keyword. The [End] keyword marks the end of the file and is placed last. * [Network Data] * [Noise Data] (required only if [Number of Noise Frequencies] given) * [End] Network data represents either conventional n-port parameters (corresponding to what is referred to as single-ended port configuration) or mixed-mode parameters associated with differential port configurations. The mixed-mode parameters may be the generalized mixed-mode parameters if not all single-ended ports are combined into differential ports. A differential port is formed from two single-ended ports having the same "reference" terminal (also referred to as the "-" terminal). In addition to the above information (option lines, keywords, and network data), files that describe 2-port devices may also contain noise parameter data. Comment lines may be interspersed in the file as necessary. These keywords and data formats are described in detail in the following sections. Comment Lines Touchstone data files may include comments. Comments are preceded by an exclamation mark (!). Comments may appear on a separate line, or after the last data value on a line. Comments are terminated by a line termination sequence or character (i.e., multi-line comments are not allowed). The syntax rules for comments are identical for Version 1.0, Version 1.1, and Version 2.1 files. [Version] Rules for Version 1.0 and Version 1.1 files: The [Version] keyword is not permitted for Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: The [Version] keyword is required with a string argument of "2.1" or "2.0" (without the quotation marks). Note that except for the additional argument of "2.1" in the [Version] keyword, the syntax and rules are identical between [Version] 2.1 and 2.0 Touchstone files, so it does not make a difference which of these two arguments is used for the [Version] keyword in Touchstone files. Each Touchstone Version 2.1 file shall contain one [Version] keyword and argument. These shall precede all other non-comment, non-blank lines. Both the opening and closing brackets are required. The [Version] keyword is followed by one string argument. The argument shall be preceded by whitespace. The [Version] keyword provides information on the Version of the specification under which the file contents should be interpreted. Option Line For Version 1.0, Version 1.1, and Version 2.1 files: Each Touchstone file shall contain an option line (additional option lines after the first one shall be ignored). The option line is formatted as follows: # R where # marks the beginning of the option line. frequency unit specifies the unit of frequency. Legal values are Hz, kHz, MHz, and GHz. The default value is GHz. parameter specifies what kind of network parameter data is contained in the file. Legal values are: S for Scattering parameters, Y for Admittance parameters, Z for Impedance parameters, H for Hybrid-h parameters, G for Hybrid-g parameters. The default value is S. format specifies the format of the network parameter data pairs. Legal values are: 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 does not apply to noise parameters (refer to the "Noise Parameter Data" section later in this specification). The default value is MA. For Version 1.0 and Version 2.1 files: R n specifies the reference resistance in ohms, where n is a real, positive number. If R is omitted, the default reference resistance is 50 ohms for all ports. Note that for Version 2.1 files this is overridden by the [Reference] keyword, if exists, as described below. For Version 1.1 files: R n ... n specifies the reference resistances in ohms, where the character "R" is followed by n real, positive numbers. For Version 1.1 files, the character "R" shall be followed by as many values as the number of ports to serve as the per port reference resistance for each port, matched by order. In addition, for Version 1.1 files, "R" and the n values following it shall be placed at the end of the option line. Option line parameters are separated by one or more whitespace; the option line itself is terminated with a line termination sequence or character. If a parameter is missing, the default value is assumed. With the exception of the opening # (hash mark) character and the multi valued per port reference resistance parameter ( "R n...n"), option line parameters may appear in any order. Rules for Version 1.0 and Version 2.1 files: In summary, the option line should read: For 1-port files: # [Hz|kHz|MHz|GHz] [S|Y|Z] [DB|MA|RI] [R n] For 2-port files: # [Hz|kHz|MHz|GHz] [S|Y|Z|G|H] [DB|MA|RI] [R n] For 3-port and beyond files: # [Hz|kHz|MHz|GHz] [S|Y|Z] [DB|MA|RI] [R n] For mixed-mode files: # [Hz|kHz|MHz|GHz] [S|Y|Z] [DB|MA|RI] [R n] where the square brackets ("[", "]") indicate optional information; ...|...|...| means to select one of the choices; and n is replaced by a positive integer or floating-point number. Though specific cases are used for the units above and throughout this specification (e.g., "kHz"), Touchstone files are case-insensitive. The one and only one reference resistance value specified in the option line applies to the network data for all ports, if [Reference] is not present. Rules for Version 1.0 and Version 1.1 files: For Version 1.0 and Version 1.1 files, the option line shall precede any data lines and shall be the first non-comment, non-blank line in the file. The option line reference resistance defines the reference for the S-parameter data and the normalization used on G-, H-, Y-, and Z-parameter data in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: For Version 2.1 files, the option line shall follow the [Version] keyword and argument and precede the [Number of Ports] keyword and argument. For Version 2.1 files, the option line reference resistance defines the reference for the S-parameter data if the [Reference] keyword is not present. Network data for G-, H-, Y- and Z-parameters in Version 2.1 are not normalized. Therefore, the option line reference resistance and [Reference] keyword have no impact on G-, H-, Y-, or Z-parameter data in Version 2.1. S-parameters are, by definition, normalized with respect to the reference impedance(s) and in this respect there is no difference between the treatment of S-parameters in Version 1.0, Version 1.1, and Version 2.1files. If the [Mixed-Mode Order] keyword is present, mixed-mode network parameters are used in the file. Mixed-mode parameters are only supported for S-, Y-, and Z-parameter data. Rules for Version 1.0 and Version 2.1 files: Per the defaults above, an empty option line (a single hash mark without any non-comment characters following it) in a Version 1.0 file indicates that the file uses GHz units for frequency, single-ended S-parameters for the network data, magnitude-angle (MA) for the network data format and 50 ohms as the reference or normalization resistance. In a Version 2.1 file, the same defaults apply, except that no normalization is assumed on G-, H-, Y-, and Z-parameter data and the [Reference] keyword and argument(s) supersede the 50 ohm reference resistance assumption. Option Line Examples For Version 1.0 and Version 2.1 files: Minimum required option line example, using all default values: # Frequency in GHz, S-parameters in real-imaginary format, referenced to 100 ohms: # GHz S RI R 100 Different Ordering from the Previous Example: # S R 100 GHz RI Frequency in kHz, Y-parameters in real-imaginary format, normalized to 100 ohms: # kHz Y RI R 100 Frequency in Hz, Z-parameters in magnitude-angle format, normalized to 10 ohms: # Hz Z MA R 10 Frequency in kHz, H-parameters in real-imaginary format normalized to 1 ohm: # kHz H RI R 1 Frequency in MHz, G-parameters in decibel format normalized to 1 ohm: # MHz G DB R 1 For Version 1.1 files: Frequency in GHz, S-parameters in real-imaginary format, port 1 referenced to 0.1 ohm and port 2 referenced to 75 ohms. (Note that R n n n is positioned as the last option line entry): # S GHz RI R 0.1 75.0 [Number of Ports] Rules for Version 1.0 and Version 1.1 files: The [Number of Ports] keyword is not permitted in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: Each Touchstone Version 2.1 file shall contain one and only one [Number of Ports] keyword and argument. The [Number of Ports] keyword and argument define the number of single-ended ports represented by the network data in the file. The [Number of Ports] keyword is followed by a single positive integer argument, separated from the keyword by whitespace. The [Number of Ports] keyword is required for Version 2.1 files. It shall be the first keyword after the option line. Example 1 (Version 2.1): ! 4-port S-parameter data ! Data valid for 1.0, if [Version] and [Number of Ports] are removed [Version] 2.1 # GHz S MA R 50 [Number of Ports] 4 [Two-Port Data Order] Rules for Version 1.0 and Version 1.1 files: The [Two-Port Data Order] keyword is not permitted in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: The [Two-Port Data Order] keyword is required only when the argument for the [Number of Ports] keyword is 2. Otherwise, it is not permitted. When required, the [Two-Port Data Order] keyword and argument shall appear after the [Number of Ports] keyword and argument and before any network data. Multiple [Two-Port Data Order] keywords in the same file are not permitted. The [Two-Port Data Order] keyword, in brackets as shown, is followed by one of two string arguments separated from the keyword by whitespace: 12_21 or 21_12. The [Two-Port Data Order] keyword is used to signify the column ordering convention. The Version 1.0 and Version 1.1 convention for 2-port network data is N11, N21, N12, N22, where N11, N12, etc., represent pairs of data entries. However, some tools and users have adopted the convention N11, N12, N21, N22 (a more natural order consistent with all the other n-port ordering conventions). The keyword makes the ordering of 2-port network data explicit and unambiguous in and above files. [Number of Frequencies] Rules for Version 1.0 and Version 1.1 files: The [Number of Frequencies] keyword is not permitted in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: The [Number of Frequencies] keyword and argument specify the number of frequency points, and therefore blocks of network parameters, listed in the file. The [Number of Frequencies] keyword, in brackets as shown, shall be followed by an integer greater than 0. The [Number of Frequencies] is required in Version 2.1 files. [Number of Frequencies] shall appear after the [Number of Ports] keyword and before any network data. [Number of Frequencies] has no impact on noise parameters. Example 2 (Version 2.1): !1-port Z-parameter file, multiple frequency points [Version] 2.1 # MHz Z MA [Number of Ports] 1 [Number of Frequencies] 5 [Number of Noise Frequencies] Rules for Version 1.0 and Version 1.1 files: The [Number of Noise Frequencies] keyword is not permitted in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: The [Number of Noise Frequencies] keyword and argument specify the number of noise frequency points, and therefore blocks of noise parameters, listed in the file. The [Number of Noise Frequencies] keyword, in brackets as shown, shall be followed by an integer greater than 0. The [Number of Noise Frequencies] is required in Version 2.1 files only if noise parameter data is provided. [Number of Noise Frequencies] shall appear after the [Number of Ports] keyword and before any network data. Example 3 (Version 2.1): !2-port network, S-parameter and noise data !Default MA format, GHz frequencies, 50 ohm reference, S-parameters [Version] 2.1 # [Number of Ports] 2 [Two-Port Data Order] 21_12 [Number of Frequencies] 2 [Number of Noise Frequencies] 2 [Reference] Rules for Version 1.0 and Version 1.1 files: The [Reference] keyword is not permitted in Version 1.0 and Version 1.1 files. Rules for Version 2.1 files: The [Reference] keyword and associated argument(s) provide a per-port definition of the reference environment used for the S-parameter measurements in the network data. They shall appear only once in the file. The [Reference] keyword, in brackets as shown, shall be followed by one or more positive integer or floating-point numbers as arguments, separated from the keyword and each other by whitespace. [Reference] arguments shall not be mixed with arguments for any other keyword in the file. [Reference] and its arguments may span multiple lines. Each of the arguments is a real-valued impedance (i.e., a resistance) and is assumed to be ordered per port numerically starting at 1 and ending with the value listed under [Number of Ports] (e.g., if [Number of Ports] contains the value "5", five arguments are expected under [Reference], ordered starting with port 1's impedance and ending with port 5's impedance). The [Reference] keyword arguments assume and refer to single-ended ports. The units of the [Reference] argument impedances are ohms. [Reference] shall only appear after the [Number of Ports] keyword and before any network data. Note that complex and imaginary impedance values are not supported. [Reference] is optional. If [Reference] is not present, the reference impedances for the S-parameter data are assumed to be defined by the option line. If [Reference] is present, it shall contain an impedance argument for every port represented in the data (for example, a 4-port data file using [Reference] shall contain four [Reference] impedance arguments). The [Reference] keyword has no impact on G-, H-, Y-, or Z-parameter data. [Reference] arguments may begin on the line following the closing bracket of the keyword (in other words, after a line termination character or sequence). Example 4 (Version 2.1): ! 4-port S-parameter data ! Option line reference impedance is overridden by [Reference] ! Data cannot be represented using 1.0 syntax, ! but can be represented using 1.1 syntax ! 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 ADD NEW EXAMPLE FOR VERSION 1.1 FILE Example 4xx (Version 1.1): ! 4-port S-parameter data ! Per port reference provided using Version 1.1 syntax # GHz S MA R 0.01 0.01 50.0 50.0 In examples 4, 5 and 6, add the following line after: ! Data cannot be represented using 1.0 syntax ! but can be represented using 1.1 syntax