TOUCHSTONE ISSUE RESOLUTION DOCUMENT (TSIRD) TSIRD ID#: 4.1 ISSUE TITLE: [End] Keyword Corrections and Other Editorial Changes REQUESTOR: Michael Mirmak, Intel Corp. DATE SUBMITTED: March 2, 2022 DATE REVISED: July 20, 2022 DATE ACCEPTED: September 9, 2022 DEFINITION OF THE ISSUE: One glaring omission from the current Touchstone 2.0 specification is any statement regarding whether [End] is to be considered required.  Unlike [Matrix Format], [End] is never explicitly identified as optional either in its own keyword definition section, or in the listing of keywords at the start of the specification.  In addition, none of the examples in the Touchstone 2.0 specification actually shows [End], except the example under the [End] keyword definition itself (unfortunately, even Example 20 for [End] still does not pass the tschk2 parser, in that [Two-Port Data Order] is required, yet is missing). The TSCHK2 parser, however, will throw error “E2209: expected to find the [End] keyword” if the [End] keyword is missing from an otherwise-legal Touchstone 2.0 file. The specification text should be modified to note that [End] is required for Touchstone 2.0 files.  The complete examples in the document should be modified to include [End] and any other missing keywords necessary to pass parser syntax checks. Additional adjustments are made in the text to clarify the number formats acceptable for different kinds of network data. Note that no parser changes should be needed as a result of these specification corrections. SOLUTION REQUIREMENTS: The Touchstone specification must meet these requirements: Table 1: Solution Requirements Requirement Notes 1. All specification examples, if complete, should be parsable without errors 2. All examples should be optimally readable 3. Requirements for keywords should be explicit, including the placement of the keyword relative to other keywords SUMMARY OF PROPOSED CHANGES: For review purposes, the proposed changes are summarized as follows: Table 2: Touchstone Keywords Affected Specification Item New/Modified/Other Notes Ensure [End] is present in all complete examples and clarify the [End] requirement in Version 2.0 Modified text but no new rules This applies to eight total examples; new text is added before Example 20. Remove any redundant keyword data in examples Modified text but no new rules Example 16 contains two options lines Add other required keywords to complete examples Modified text but no new rules Two examples were missing the [Two-Port Data Order] keyword Correct any typographical errors in examples or rules Modified text but no new rules Example 12 had a misplaced closing bracket; the initial summary of [Two-Port Data Order] was missing the word “Data” Add leading zeroes and spaces to floating point numbers for readability Modified text but no new rules Add note regarding number formatting, including leading zeroes being optional Modified text but no new rules Clarify colon usage in formatting of Example 15 Modified text but no new rules PROPOSED CHANGES: All page numbers refer to the PDF version of the Touchstone 2.0 specification.  In addition to the specific changes noted below, all instances of the phrase “50 ohm reference” should be changed to “50-ohm reference” throughout the document. Similarly, any instances of “1 ohm reference” should be changed to “1-ohm reference”. ---------- The text on page 5 should be changed to: Version 2.0 adds to the above several additional keywords. Several of the keywords have a particular order and are placed at the beginning of the file. These are shown below. • [Version] 2.0 (required) • # (option line; required) • [Number of Ports] (required) 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] is defined) • [Reference] (optional) • [Matrix Format] (optional) • [Mixed-Mode Order] (optional) • [Begin Information]/[End Information] (optional) Touchstone 2.0 data is positioned under two required keywords in the order shown below. 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]    (required) • [Noise Data]         (required only if [Number of Noise Frequencies] is given) • [End]                    (required) ---------- The text on pages 11 and 12 should be changed to: Example 5 (Version 2.0): ! 4-port S-parameter data ! Default impedance is overridden by the [Reference] keyword arguments ! Data cannot be represented using 1.0 syntax [Version] 2.0 # GHz S MA R 50 [Number of Ports] 4 [Number of Frequencies] 1 [Reference] 50 75 0.01 0.01 [Matrix Format] Full [Network Data] 5.00000 0.60 161.24 0.40 -42.20 0.42 -66.58 0.53 -79.34 ! row 1 0.40 -42.20 0.60 161.20 0.53 -79.34 0.42 -66.58 ! row 2 0.42 -66.58 0.53 -79.34 0.60 161.24 0.40 -42.20 ! row 3 0.53 -79.34 0.42 -66.58 0.40 -42.20 0.60 161.24 ! row 4 [End] Example 6 (Version 2.0): ! 4-port S-parameter data ! Default impedance is overridden by the [Reference] keyword arguments ! Note that [Reference] arguments are split across two lines ! Data cannot be represented using 1.0 syntax [Version] 2.0 # GHz S MA R 50 [Number of Ports] 4 [Number of Frequencies] 1 [Reference] 50 75 0.01 0.01 [Matrix Format] Lower [Network Data] 5.00000 0.60 161.24                             ! row 1 0.40 -42.20 0.60 161.20                         ! row 2 0.42 -66.58 0.53 -79.34 0.60 161.24             ! row 3 0.53 -79.34 0.42 -66.58 0.40 -42.20 0.60 161.24 ! row 4 [End] Example 7 (Version 2.0): ! 1-port Z-parameter file, multiple frequency points [Version] 2.0 # MHz Z MA [Number of Ports] 1 [Number of Frequencies] 5 [Reference] 20.0 [Network Data] ! freq magZ11 angZ11 100 74.25 -4 200 60 -22 300 53.025 -45 400 30 -62 500 0.75 -89 [End] ---------- The following text should be added to page 13, immediately before the sentence beginning “Note that data is represented…”: Frequency points and the data that follows them may be in integer, floating point or scientific notation. If in floating point format, a single leading zero (i.e., a zero before the decimal point) may be present or omitted. ---------- The text on page 14 should be changed to: Example 10 (Version 2.0): ! 1-port Z-parameter file, multiple frequency points [Version] 2.0 # MHz Z MA [Number of Ports] 1 [Number of Frequencies] 5 [Reference] 20.0 [Network Data] ! freq magZ11 angZ11 100 74.25 -4 200 60 -22 300 53.025 -45 400 30 -62 500 0.75 -89 [End] ---------- The text on page 15 should be changed to: Example 12 (Version 2.0): ! 2-port H-parameter file, single frequency point [Version] 2.0 # kHz H MA R 1 [Number of Ports] 2 [Two-Port Data Order] 21_12 [Number of Frequencies] 1 [Matrix Format] Full [Network Data] ! freq magH11 angH11 magH21 angH21 magH12 angH12 magH22 angH22 2 0.95 -26 3.57 157 0.04 76 0.66 -14 [End] ---------- The text on pages 18 and 19 should be changed to: The following is a more detailed example illustrating the Full data matrix format for a 10-port network. The Y-parameter data is in magnitude-angle format and is for a single frequency. Port numbers are separated by the colon character (:), for clarity only. Example 15 (Version 1.0): # frequency_unit Y MA R impedance freq magY1:1 angY1:1 magY1:2 angY1:2 magY1:3 angY1:3 magY1:4 angY1:4 ! 1st row magY1:5 angY1:5 magY1:6 angY1:6 magY1:7 angY1:7 magY1:8 angY1:8 magY1:9 angY1:9 magY1:10 angY1:10 magY2:1 angY2:1 magY2:2 angY2:2 magY2:3 angY2:3 magY2:4 angY2:4 ! 2nd row magY2:5 angY2:5 magY2:6 angY2:6 magY2:7 angY2:7 magY2:8 angY2:8 magY2:9 angY2:9 magY2:10 angY2:10 magY3:1 angY3:1 magY3:2 angY3:2 magY3:3 angY3:3 magY3:4 angY3:4 ! 3rd row magY3:5 angY3:5 magY3:6 angY3:6 magY3:7 angY3:7 magY3:8 angY3:8 magY3:9 angY3:9 magY3:10 angY3:10 magY4:1 angY4:1 magY4:2 angY4:2 magY4:3 angY4:3 magY4:4 angY4:4 ! 4th row magY4:5 angY4:5 magY4:6 angY4:6 magY4:7 angY4:7 magY4:8 angY4:8 magY4:9 angY4:9 magY4:10 angY4:10 magY5:1 angY5:1 magY5:2 angY5:2 magY5:3 angY5:3 magY5:4 angY5:4 ! 5th row magY5:5 angY5:5 magY5:6 angY5:6 magY5:7 angY5:7 magY5:8 angY5:8 magY5:9 angY5:9 magY5:10 angY5:10 magY6:1 angY6:1 magY6:2 angY6:2 magY6:3 angY6:3 magY6:4 angY6:4 ! 6th row magY6:5 angY6:5 magY6:6 angY6:6 magY6:7 angY6:7 magY6:8 angY6:8 magY6:9 angY6:9 magY6:10 angY6:10 magY7:1 angY7:1 magY7:2 angY7:2 magY7:3 angY7:3 magY7:4 angY7:4 ! 7th row magY7:5 angY7:5 magY7:6 angY7:6 magY7:7 angY7:7 magY7:8 angY7:8 magY7:9 angY7:9 magY7:10 angY7:10 magY8:1 angY8:1 magY8:2 angY8:2 magY8:3 angY8:3 magY8:4 angY8:4 ! 8th row magY8:5 angY8:5 magY8:6 angY8:6 magY8:7 angY8:7 magY8:8 angY8:8 magY8:9 angY8:9 magY8:10 angY8:10 magY9:1 angY9:1 magY9:2 angY9:2 magY9:3 angY9:3 magY9:4 angY9:4 ! 9th row magY9:5 angY9:5 magY9:6 angY9:6 magY9:7 angY9:7 magY9:8 angY9:8 magY9:9 angY9:9 magY9:10 angY9:10 ! 10th row magY10:1 angY10:1 magY10:2 angY10:2 magY10:3 angY10:3 magY10:4 angY10:4 magY10:5 angY10:5 magY10:6 angY10:6 magY10:7 angY10:7 magY10:8 angY10:8 magY10:9 angY10:9 magY10:10 angY10:10 ---------- The text on pages 22 and 23 should be changed to: Example 16 (Version 2.0): ! 6-port component shown; note that all five ports are used in some ! relationship [Version] 2.0 # MHz Y RI R 50 [Number of Ports] 6 [Number of Frequencies] 1 [Reference] 50 75 75 50 0.01 0.01 [Mixed-Mode Order] D2,3 D6,5 C2,3 C6,5 S4 S1 [Network Data] 5.00 8.0 9.0 2.0 -1.0 3.0 -2.0 1.0 3.0 1.0 0.1 0.2 -0.2 2.0 -1.0 7.0 7.0 1.8 -2.0 -1.0 -1.0 -0.5 0.5 0.2 -0.1 3.0 -2.0 1.8 -2.0 5.8 6.0 1.2 0.8 0.9 0.7 0.3 -0.5 1.0 3.0 -1.0 -1.0 1.2 0.8 6.3 8.0 2.0 -0.5 1.5 0.6 1.0 0.1 -0.5 0.5 0.9 0.7 2.0 -0.5 4.7 -6.0 -1.0 2.0 0.2 -0.2 0.2 -0.1 0.3 -0.5 1.5 0.6 -1.0 2.0 5.5 -7.0 [End] ---------- The text on page 23 should be changed to: Example 17 (Version 2.0): ! 2-port network, S-parameter and noise data ! Default MA format, GHz frequencies, 50.0-ohm reference, S-parameters [Version] 2.0 # [Number of Ports] 2 [Two-Port Data Order] 21_12 [Number of Frequencies] 2 [Number of Noise Frequencies] 2 [Reference] 50 25.0 [Network Data] 2 0.95 -26 3.57 157 0.04 76 0.66 -14 22 0.60 -144 1.30 40 0.14 40 0.56 -85 [Noise Data] 4 0.7 0.64 69 19 18 2.7 0.46 -33 20 [End] ---------- The text on page 24 should be changed to: In both Version 1.0 and Version 2.0, each noise parameter frequency and associated data shall be grouped into a single line, terminated with a line termination sequence or character. As in Version 2.0 [Network Data], noise data and their associated frequency points may be in integer, floating point or scientific notation. If in floating point format, a single leading zero (i.e., a zero before the decimal point) may be present or omitted. ---------- The text on pages 24 and 25 should be changed to: Example 19 (Version 2.0): ! 2-port network, S-parameter and noise data ! Default MA format, GHz frequencies, 50.0-ohm reference, S-parameters [Version] 2.0 # [Number of Ports] 2 [Number of Frequencies] 2 [Number of Noise Frequencies] 2 [Reference] 50 25.0 [Two-Port Data Order] 12_21 [Network Data] ! NETWORK PARAMETERS 2 0.95 -26 3.57 157 0.04 76 0.66 -14 22 0.60 -144 1.30 40 0.14 40 0.56 -85 [Noise Data] ! NOISE PARAMETERS 4 0.7 0.64 69 19 18 2.7 0.46 -33 20 [End] ---------- The text on page 25 should be changed to: Rules for Version 2.0 Files: The [End] keyword defines the end of the Touchstone 2.0 file. Non-comment text appearing after the [End] keyword should be treated as an error. The [End] keyword is required for Version 2.0 files. It shall be the last keyword in the file. Example 20 (Version 2.0): ! 2-port network, S-parameter and noise data ! Default MA format, GHz frequencies, 50.0-ohm reference, S-parameters [Version] 2.0 # [Number of Ports] 2 [Number of Frequencies] 2 [Number of Noise Frequencies] 2 [Reference] 50 25.0 [Two-Port Data Order] 12_21 [Network Data] ! NETWORK PARAMETERS 2 0.95 -26 3.57 157 0.04 76 0.66 -14 22 0.60 -144 1.30 40 0.14 40 0.56 -85 [Noise Data] ! NOISE PARAMETERS 4 0.7 0.64 69 19 18 2.7 0.46 -33 20 [End] BACKGROUND INFORMATION/HISTORY: Many, if not all, of these errors can be explained by the specification having been issued before a parser was actually available. Version 4.1 of this TSIRD is issued to: - Use the new TSIRD 1.0 template - Remove a line regarding red font and strikethrough - Add a statement regarding parser changes not being needed as a result of the specification changes Leading zeroes were added in 4.1 after review by the IBIS Open Forum on March 11, 2022. Similarly, the new text regarding numeric formatting was added as a result of suggestions in the same meeting. Additional changes were made due to suggestions in the July 20, 2022 IBIS Interconnect Task Group meeting. Beyond the additional material required by the TSIRD 1.0 template, nearly all changes in 4.1 from 4 are indicated using highlighting. Some spacing adjustments in examples have been made for readability. BIRD Template, Rev. 1.3 Touchstone Specification Change Template, Rev. 1.0 2 1