Class: Touchstone

Represents a Touchstone file parser and generator. Supports reading, manipulating, and writing Touchstone (.snp) files following version 1.0 and 1.1 specifications.

Remarks

Overview

The Touchstone file format (typically with .snp extensions) is an industry-standard ASCII format for representing n-port network parameters. It is widely used in Electronic Design Automation (EDA) and by measurement equipment (like VNAs) to describe the performance of RF and microwave components.

Key Features:

File Extensions: .s1p, .s2p, ... .sNp indicate a network with N ports.
Case Insensitivity: Keywords and identifiers are case-insensitive.
Versions: Full support for version 1.0 and 1.1. Version 2.0 is not currently supported.

Touchstone File Structure

A file consists of a header (comments and option line) followed by network data.

1. Header Section

Comment Lines: Lines starting with ! are stored in the comments array.
Option Line: The line starting with # sets the global context. Example: # GHz S MA R 50
- GHz: Frequency unit (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).
  - RI: $A + j \cdot B$
  - MA: $A \cdot e^{j \cdot \frac{π}{180} \cdot B}$
  - DB: $10^{\frac{A}{20}} \cdot e^{j \cdot \frac{π}{180} \cdot B}$
- R 50: Reference resistance in ohms (default is 50 ohms if omitted).

2. Network Data Section

Data is listed frequency by frequency. For a 2-port network, the format is: <frequency> <N11> <N21> <N12> <N22> (where each NXx is a pair of values based on the format).

References:

Example

Parsing a local file string

typescript

import { Touchstone } from 'rf-touchstone';

const content = `
! Simple 1-port S-parameter data
# MHz S RI R 50
100 0.9 -0.1
200 0.8 -0.2
`;
const ts = Touchstone.fromText(content, 1);
console.log(ts.parameter); // 'S'
console.log(ts.frequency.unit); // 'MHz'

Constructors

Constructor

new Touchstone(): Touchstone

Returns

Touchstone

Properties

name

name: string | undefined

Defined in: src/touchstone.ts:350

Name of the Touchstone file (without extension). Used as default filename when saving and as legend label in plots. Automatically set when using fromUrl() or fromFile(), can be manually provided in fromText() or set directly.

Example

typescript

const ts = await Touchstone.fromUrl('http://example.com/network.s2p')
console.log(ts.name) // 'network'

comments

comments: string[] = []

Defined in: src/touchstone.ts:355

Array of comment strings extracted from the Touchstone file header (lines starting with !).

frequency

frequency: Frequency | undefined

Defined in: src/touchstone.ts:530

Frequency metadata and point array.

Accessors

format

Get Signature

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

Defined in: src/touchstone.ts:398

Get the Touchstone format

Returns

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

Set Signature

set format(format): void

Defined in: src/touchstone.ts:371

Sets the Touchstone data format.

RI: Real and Imaginary, i.e., $A + j \cdot B$
MA: Magnitude and Angle (degrees), i.e., $A \cdot e^{j \cdot \frac{π}{180} \cdot B}$
DB: Decibel and Angle (degrees), i.e., $10^{\frac{A}{20}} \cdot e^{j \cdot \frac{π}{180} \cdot B}$

Throws

Error if the format is invalid.

Parameters

format

The target format (RI, MA, or DB).

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

Returns

void

parameter

Get Signature

get parameter(): string | null | undefined

Defined in: src/touchstone.ts:450

Get the type of network parameter

Returns

string | null | undefined

Set Signature

set parameter(parameter): void

Defined in: src/touchstone.ts:418

Sets the type of network parameters.

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

Throws

Error if the parameter type is invalid.

Parameters

parameter

The target parameter type (S, Y, Z, G, or H).

string | null | undefined

Returns

void

impedance

Get Signature

get impedance(): TouchstoneImpedance

Defined in: src/touchstone.ts:488

Get the Touchstone impedance. Default: 50Ω

Returns

TouchstoneImpedance

Set Signature

set impedance(impedance): void

Defined in: src/touchstone.ts:467

Sets the reference impedance (resistance) in Ohms. Default: 50Ω

Throws

Error if the impedance value is invalid.

Parameters

impedance

TouchstoneImpedance

A single number for all ports, or an array of numbers (one per port).

Returns

void

nports

Get Signature

get nports(): number | null | undefined

Defined in: src/touchstone.ts:523

The number of ports in the network.

Returns

number | null | undefined

Set Signature

set nports(nports): void

Defined in: src/touchstone.ts:503

Sets the number of ports for the network.

Throws

Error if the value is not a positive integer.

Parameters

nports

The integer number of ports (must be >= 1).

number | null | undefined

Returns

void

matrix

Get Signature

get matrix(): TouchstoneMatrix | null | undefined

Defined in: src/touchstone.ts:579

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 port index (0 to nports-1) - where the signal exits
Second dimension [j]: Input port index (0 to nports-1) - where the signal enters
Third dimension [k]: Frequency point index

Example

typescript

// For any N-port network (2-port, 4-port, etc.):
const s11 = touchstone.matrix[0][0][freqIdx] // S11: port 1 → port 1
const s21 = touchstone.matrix[1][0][freqIdx] // S21: port 1 → port 2
const s12 = touchstone.matrix[0][1][freqIdx] // S12: port 2 → port 1
const s22 = touchstone.matrix[1][1][freqIdx] // S22: port 2 → port 2

// General pattern: Sij = matrix[i-1][j-1][freqIdx]
// where i is the output port number, j is the input port number

Returns

TouchstoneMatrix | null | undefined

The current network parameter matrix, or undefined if not set

Set Signature

set matrix(matrix): void

Defined in: src/touchstone.ts:547

Directly sets the network parameter matrix.

Parameters

matrix

The 3D complex matrix to assign.

TouchstoneMatrix | null | undefined

Returns

void

Methods

getFilename()

static getFilename(pathOrUrl): string

Defined in: src/touchstone.ts:163

Utility to extract a filename from a URL or a file path string.

Parameters

pathOrUrl

string

The URL or string representation of a path.

Returns

string

The filename part of the string.

Throws

Error if the filename cannot be determined.

getBasename()

static getBasename(filenameOrPath): string

Defined in: src/touchstone.ts:207

Extracts the basename from a filename or path by removing the file extension.

Parameters

filenameOrPath

string

The filename or full path to process.

Returns

string

The basename without extension.

Remarks

This method intelligently handles both simple filenames and full paths. If a path separator is detected (/ or ), it first extracts the filename, then removes any file extension.

Example

typescript

// Works with simple filenames
Touchstone.getBasename('myfile.s2p') // 'myfile'
Touchstone.getBasename('data.txt') // 'data'
Touchstone.getBasename('document.pdf') // 'document'

// Also works with full paths
Touchstone.getBasename('/path/to/network.s2p') // 'network'
Touchstone.getBasename('C:\\data\\test.s3p') // 'test'
Touchstone.getBasename('https://example.com/file.txt') // 'file'

// Files without extension remain unchanged
Touchstone.getBasename('noextension') // 'noextension'

parsePorts()

static parsePorts(filename): number | null

Defined in: src/touchstone.ts:228

Determines the number of ports based on the file extension (e.g., .s2p -> 2).

Parameters

filename

string

The filename or URL to inspect.

Returns

number | null

The number of ports, or null if it cannot be determined.

fromText()

static fromText(content, nports, name?): Touchstone

Defined in: src/touchstone.ts:244

Creates a Touchstone instance from a raw text string.

Parameters

content

string

The raw text content of the Touchstone file

nports

number

The number of ports

name?

string

Optional name for this Touchstone object (used for plotting legends and default save filename)

Returns

Touchstone

A new Touchstone instance

fromUrl()

static fromUrl(url, nports?): Promise<Touchstone>

Defined in: src/touchstone.ts:263

Async helper to fetch, parse, and return a Touchstone instance from a URL.

Parameters

url

string

The URL of the Touchstone file.

nports?

The expected number of ports. If null, it attempts to parse from the URL.

number | null

Returns

Promise<Touchstone>

A promise resolving to a Touchstone instance.

Throws

Error if the fetch fails, or the number of ports cannot be determined.

fromFile()

static fromFile(file, nports?): Promise<Touchstone>

Defined in: src/touchstone.ts:300

Reads a File object (typical in browser environments), parses it, and returns a Touchstone instance.

Parameters

file

File

The HTML5 File object to read.

nports?

The expected number of ports. If null, it attempts to parse from the filename.

number | null

Returns

Promise<Touchstone>

A promise resolving to a Touchstone instance.

Throws

Error if reading fails or the number of ports cannot be determined.

readContent()

readContent(string, nports): void

Defined in: src/touchstone.ts:624

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:

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

Example

typescript

import { Touchstone } 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 = Touchstone.fromText(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:824

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:

Essential Data Validation:
- Checks existence of all required properties
- Ensures frequency points are available
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:915

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:

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

Example

typescript

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

const touchstone = new Touchstone();

// Set properties and matrix data
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

Class: Touchstone ​

Remarks ​

Overview ​

Key Features: ​

Touchstone File Structure ​

1. Header Section ​

2. Network Data Section ​

References: ​

Example ​

Parsing a local file string ​

Constructors ​

Constructor ​

Returns ​

Properties ​

name ​

Example ​

comments ​

frequency ​

Accessors ​

format ​

Get Signature ​

Returns ​

Set Signature ​

Throws ​

Parameters ​

format ​

Returns ​

parameter ​

Get Signature ​

Returns ​

Set Signature ​

Throws ​

Parameters ​

parameter ​

Returns ​

impedance ​

Get Signature ​

Returns ​

Set Signature ​

Throws ​

Parameters ​

impedance ​

Returns ​

nports ​

Get Signature ​

Returns ​

Set Signature ​

Throws ​

Parameters ​

nports ​

Returns ​

matrix ​

Get Signature ​

Remarks ​

Example ​

Returns ​

Set Signature ​

Parameters ​

matrix ​

Returns ​

Methods ​

getFilename() ​

Parameters ​

pathOrUrl ​

Returns ​

Throws ​

getBasename() ​

Parameters ​

filenameOrPath ​

Returns ​

Remarks ​

Example ​

parsePorts() ​

Parameters ​

filename ​

Returns ​

fromText() ​

Parameters ​

content ​

nports ​

Class: Touchstone

Remarks

Overview

Key Features:

Touchstone File Structure

1. Header Section

2. Network Data Section

References:

Example

Parsing a local file string

Constructors

Constructor

Returns

Properties

name

Example

comments

frequency

Accessors

format

Get Signature

Returns

Set Signature

Throws

Parameters

format

Returns

parameter

Get Signature

Returns

Set Signature

Throws

Parameters

parameter

Returns

impedance

Get Signature

Returns

Set Signature

Throws

Parameters

impedance

Returns

nports

Get Signature

Returns

Set Signature

Throws

Parameters

nports

Returns

matrix

Get Signature

Remarks

Example

Returns

Set Signature

Parameters

matrix

Returns

Methods

getFilename()

Parameters

pathOrUrl

Returns

Throws

getBasename()

Parameters

filenameOrPath

Returns

Remarks

Example

parsePorts()

Parameters

filename

Returns

fromText()

Parameters

content

nports