RF Touchstone

---

RF Touchstone / touchstone / Touchstone

Class: Touchstone

Defined in: src/touchstone.ts:172

Touchstone class for reading and writing network parameter data in Touchstone format. Supports both version 1.0 and 1.1 of the Touchstone specification.

Remarks

Overview

The Touchstone file format (also known as .snp files) is an industry-standard ASCII text format used to represent the n-port network parameters of electrical circuits. These files are commonly used in RF and microwave engineering to describe the behavior of devices such as filters, amplifiers, and interconnects.

A Touchstone file contains data about network parameters (e.g., S-parameters, Y-parameters, Z-parameters) at specific frequencies.

Key Features:

• File Extensions: Traditionally, Touchstone files use extensions like .s1p, .s2p, .s3p, etc., where the number indicates the number of ports. For example, .s2p represents a 2-port network.
• Case Insensitivity: Touchstone files are case-insensitive, meaning keywords and values can be written in uppercase or lowercase.
• Versioning: Only version 1.0 and 1.1 are supported in this class

---

File Structure

A Touchstone file consists of several sections, each serving a specific purpose. Below is a breakdown of the structure:

1. Header Section

• Comment Lines: Lines starting with ! are treated as comments and ignored during parsing.
• Option Line: Line starting with # defines global settings for the file, such as frequency units, parameter type, and data format. Example:

  # GHz S MA R 50

  • GHz: Frequency unit (can be Hz, kHz, MHz, or GHz).
  • S: Parameter type (S, Y, Z, H, or G).
  • MA: Data format (MA for magnitude-angle, DB for decibel-angle, or RI for real-imaginary).
  • R 50: Reference resistance in ohms (default is 50 ohms if omitted).

2. Network Data

The core of the file contains the network parameter data, organized by frequency. Each frequency point is followed by its corresponding parameter values.

• Single-Ended Networks: Data is arranged in a matrix format. For example, a 2-port network might look like this:

  <frequency> <N11> <N21> <N12> <N22>

---

References:

• Touchstone(R) File Format Specification (Version 2.1)
• S-Parameters for Signal Integrity
• scikit-rf: Open Source RF Engineering
• SignalIntegrity: Signal and Power Integrity Tools

Example

Example 1: Simple 1-Port S-Parameter File

! 1-port S-parameter file
# MHz S MA R 50
100 0.99 -4
200 0.80 -22
300 0.707 -45

Example 2: Simple 2-Port S-Parameter File

! Sample S2P File
# HZ S RI R 50
! Freq S11(real) S11(imag) S21(real) S21(imag) S12(real) S12(imag) S22(real) S22(imag)
1000000000 0.9 -0.1 0.01 0.02 0.01 0.02 0.8 -0.15
2000000000 0.8 -0.2 0.02 0.03 0.02 0.03 0.7 -0.25

Constructors

Constructor

new Touchstone(): Touchstone

Returns

Touchstone

Properties

comments

comments: string[] = []

Defined in: src/touchstone.ts:176

Comments in the file header with "!" symbol at the beginning of each row

---

frequency

frequency: undefined | Frequency

Defined in: src/touchstone.ts:351

Frequency points

Accessors

format

Get Signature

get format(): undefined | "RI" | "MA" | "DB"

Defined in: src/touchstone.ts:219

Get the Touchstone format

Returns

undefined | "RI" | "MA" | "DB"

Set Signature

set format(format): void

Defined in: src/touchstone.ts:192

Set the Touchstone format: MA, DB, RI, or undefined

• RI: real and imaginary, i.e. $A+j\cdot B$
• MA: magnitude and angle (in degrees), i.e. $A\cdot e^{j\cdot \frac{\pi }{180}\cdot B}$
• DB: decibels and angle (in degrees), i.e. ${10}^{\frac{A}{20}}\cdot e^{j\cdot \frac{\pi }{180}\cdot B}$

Throws

Will throw an error if the format is not valid

Parameters

format

undefined | null | "RI" | "MA" | "DB"

Returns

void

---

parameter

Get Signature

get parameter(): undefined | null | string

Defined in: src/touchstone.ts:271

Get the type of network parameter

Returns

undefined | null | string

Set Signature

set parameter(parameter): void

Defined in: src/touchstone.ts:239

Set the type of network parameter

• S: Scattering parameters
• Y: Admittance parameters
• Z: Impedance parameters
• H: Hybrid-h parameters
• G: Hybrid-g parameters

Throws

Will throw an error if the parameter is not valid

Parameters

parameter

undefined | null | string

Returns

void

---

impedance

Get Signature

get impedance(): TouchstoneImpedance

Defined in: src/touchstone.ts:309

Get the Touchstone impedance. Default: 50Ω

Returns

TouchstoneImpedance

Set Signature

set impedance(impedance): void

Defined in: src/touchstone.ts:288

Set the Touchstone impedance. Default: 50Ω

Throws

Will throw an error if the impedance is not valid

Parameters

impedance

TouchstoneImpedance

Returns

void

---

nports

Get Signature

get nports(): undefined | null | number

Defined in: src/touchstone.ts:344

Get the ports number

Returns

undefined | null | number

Set Signature

set nports(nports): void

Defined in: src/touchstone.ts:324

Set the ports number

Throws

Will throw an error if the number of ports is not valid

Parameters

nports

undefined | null | number

Returns

void

---

matrix

Get Signature

get matrix(): undefined | null | TouchstoneMatrix

Defined in: src/touchstone.ts:398

Gets the current network parameter matrix (3D array). Represents the S/Y/Z/G/H-parameters of the network.

Remarks

Matrix Structure:

• First dimension [i]: Output (exit) port number (0 to nports-1)
• Second dimension [j]: Input (enter) port number (0 to nports-1)
• Third dimension [k]: Frequency point index

Example:

• matrix[i][j][k] represents the parameter from port j+1 to port i+1 at frequency k
• For S-parameters: matrix[1][0][5] is S₂₁ at the 6th frequency point

Special case for 2-port networks:

• Indices are swapped to match traditional Touchstone format
• matrix[0][1][k] represents S₁₂ (not S₂₁)

Returns

undefined | null | TouchstoneMatrix

The current network parameter matrix, or undefined if not set

Set Signature

set matrix(matrix): void

Defined in: src/touchstone.ts:370

Sets the network parameter matrix.

Remarks

This setter provides a way to directly assign the network parameter matrix. Setting to undefined or null will clear the existing matrix data.

Parameters

matrix

The 3D complex matrix to store, or undefined/null to clear

undefined | null | TouchstoneMatrix

Returns

void

Methods

readContent()

readContent(string, nports): void

Defined in: src/touchstone.ts:444

Reads and parses a Touchstone format string into the internal data structure.

Parameters

string

string

The Touchstone format string to parse

nports

number

Number of ports in the network

Returns

void

Throws

If the option line is missing or invalid

Throws

If multiple option lines are found

Throws

If the impedance specification is invalid

Throws

If the data format is invalid or incomplete

Remarks

The method performs the following steps:

1. Parses comments and option line
2. Extracts frequency points
3. Converts raw data into complex numbers based on format
4. Stores the results in the matrix property

Example

import { Touchstone, Frequency } from 'rf-touchstone';

const s1pString = `
! This is a 1-port S-parameter file
# MHz S MA R 50
100 0.99 -4
200 0.80 -22
300 0.707 -45
`;

const touchstone = new Touchstone();
touchstone.readContent(s1pString, 1);

console.log(touchstone.comments); // Outputs: [ 'This is a 1-port S-parameter file' ]
console.log(touchstone.format); // Outputs: 'MA'
console.log(touchstone.parameter); // Outputs: 'S'
console.log(touchstone.impedance); // Outputs: 50
console.log(touchstone.nports); // Outputs: 1
console.log(touchstone.frequency?.f_scaled); // Outputs: [ 100, 200, 300 ]
console.log(touchstone.matrix); // Outputs: the parsed matrix data

---

validate()

validate(): void

Defined in: src/touchstone.ts:628

Validates the internal state of the Touchstone instance. Performs comprehensive checks on all required data and matrix dimensions.

Returns

void

Throws

If any of the following conditions are met:

• Number of ports is undefined
• Frequency object is not initialized
• Frequency points array is empty
• Network parameter type is undefined
• Data format is undefined
• Network parameter matrix is undefined
• Matrix dimensions don't match with nports or frequency points

Remarks

This method performs two main validation steps:

1. Essential Data Validation:

   • Checks existence of all required properties
   • Ensures frequency points are available

2. Matrix Dimension Validation:

   • Verifies matrix row count matches port number
   • Ensures each row has correct number of columns
   • Validates frequency points count in each matrix element

---

writeContent()

writeContent(): string

Defined in: src/touchstone.ts:718

Generates a Touchstone format string from the internal data structure.

Returns

string

The generated Touchstone format string

Throws

If any required data is missing

Throws

If the matrix dimensions are invalid

Remarks

The generated string includes:

1. Comments (if any)
2. Option line with format, parameter type, and impedance
3. Network parameter data in the specified format

Example

import { Touchstone, Frequency } from 'rf-touchstone';
import { complex } from 'mathjs';

const touchstone = new Touchstone();

// Set properties and matrix data (using simplified complex number representation for example)
touchstone.comments = ['Generated by rf-touchstone'];
touchstone.nports = 1;
touchstone.frequency = new Frequency();
touchstone.frequency.unit = 'GHz';
touchstone.frequency.f_scaled = [1.0, 2.0];
touchstone.parameter = 'S';
touchstone.format = 'MA';
touchstone.impedance = 50;
touchstone.matrix = [
  [ // Output port 1
    [complex(0.5, 0.1), complex(0.4, 0.2)] // S11 at each frequency
  ]
];

const s1pString = touchstone.writeContent();
console.log(s1pString);
// Expected output (approximately, due to floating point precision):
// ! Generated by rf-touchstone
// # GHz S MA R 50
// 1 0.5099 11.3099
// 2 0.4472 26.5651