rf-touchstone 0.0.0 → 0.0.1

package/dist/touchstone.d.ts

@@ -1,4 +1,26 @@
+import { abs } from 'mathjs';
+import { add } from 'mathjs';
+import { arg } from 'mathjs';
 import { Complex } from 'mathjs';
+import { complex } from 'mathjs';
+import { index } from 'mathjs';
+import { log10 } from 'mathjs';
+import { multiply } from 'mathjs';
+import { pi } from 'mathjs';
+import { pow } from 'mathjs';
+import { range } from 'mathjs';
+import { round } from 'mathjs';
+import { subset } from 'mathjs';
+
+export { abs }
+
+export { add }
+
+export { arg }
+
+export { Complex }
+
+export { complex }
 
 /**
  * Class representing frequency data in RF and microwave engineering
@@ -16,7 +38,7 @@ import { Complex } from 'mathjs';
  * freq.f_scale = [1.0, 2.0, 3.0];
  * ```
  */
-declare class Frequency {
+export declare class Frequency {
     /**
      * Internal storage for frequency unit
      * Defaults to 'Hz' as the base SI unit for frequency
@@ -377,40 +399,62 @@ declare class Frequency {
  * - GHz: Gigahertz (10⁹ Hz)
  * Touchstone standard doesn't support THz as the frequency unit in Touchstone file
  */
-declare type FrequencyUnit = (typeof FrequencyUnits)[number];
+export declare type FrequencyUnit = (typeof FrequencyUnits)[number];
 
 /**
  * Frequency units: 'Hz', 'kHz', 'MHz', 'GHz'
  * Touchstone standard doesn't support THz as the frequency unit in Touchstone file
  */
-declare const FrequencyUnits: readonly ["Hz", "kHz", "MHz", "GHz"];
+export declare const FrequencyUnits: readonly ["Hz", "kHz", "MHz", "GHz"];
+
+export { index }
+
+export { log10 }
+
+export { multiply }
+
+export { pi }
+
+export { pow }
+
+export { range }
+
+export { round }
+
+/**
+ * Speed of light in m/s
+ */
+export declare const SPEED_OF_LIGHT = 299792458;
+
+export { subset }
 
 /**
  * Touchstone class for reading and writing network parameter data in Touchstone format.
  * Supports both version 1.0 and 1.1 of the Touchstone specification.
  *
- * ## Overview
+ * @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:
+ * ##### 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
+ * #### File Structure
  *
  * A Touchstone file consists of several sections, each serving a specific purpose. Below is a breakdown of the structure:
  *
- * ### 1. Header Section
+ * ##### 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:
- *   ```
+ *   ```plaintext
  *   # GHz S MA R 50
  *   ```
  *   - `GHz`: Frequency unit (can be `Hz`, `kHz`, `MHz`, or `GHz`).
@@ -418,20 +462,26 @@ declare const FrequencyUnits: readonly ["Hz", "kHz", "MHz", "GHz"];
  *   - `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
+ * ##### 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:
- *   ```
+ *   ```plaintext
  *   <frequency> <N11> <N21> <N12> <N22>
  *   ```
  *
  * ---
  *
- * ## Examples
+ * #### References:
+ * - {@link https://ibis.org/touchstone_ver2.1/touchstone_ver2_1.pdf Touchstone(R) File Format Specification (Version 2.1)}
+ * - {@link https://books.google.com/books/about/S_Parameters_for_Signal_Integrity.html?id=_dLKDwAAQBAJ S-Parameters for Signal Integrity}
+ * - {@link https://github.com/scikit-rf/scikit-rf/blob/master/skrf/io/touchstone.py scikit-rf: Open Source RF Engineering}
+ * - {@link https://github.com/Nubis-Communications/SignalIntegrity/blob/master/SignalIntegrity/Lib/SParameters/SParameters.py SignalIntegrity: Signal and Power Integrity Tools}
  *
- * ### Example 1: Simple 1-Port S-Parameter File
+ * @example
+ *
+ * #### Example 1: Simple 1-Port S-Parameter File
  * ```plaintext
  * ! 1-port S-parameter file
  * # MHz S MA R 50
@@ -440,13 +490,14 @@ declare const FrequencyUnits: readonly ["Hz", "kHz", "MHz", "GHz"];
  * 300 0.707 -45
  * ```
  *
- * ---
- *
- * ## References:
- * - {@link https://ibis.org/touchstone_ver2.1/touchstone_ver2_1.pdf Touchstone(R) File Format Specification (Version 2.1)}
- * - {@link https://books.google.com/books/about/S_Parameters_for_Signal_Integrity.html?id=_dLKDwAAQBAJ S-Parameters for Signal Integrity}
- * - {@link https://github.com/scikit-rf/scikit-rf/blob/master/skrf/io/touchstone.py scikit-rf: Open Source RF Engineering}
- * - {@link https://github.com/Nubis-Communications/SignalIntegrity/blob/master/SignalIntegrity/Lib/SParameters/SParameters.py SignalIntegrity: Signal and Power Integrity Tools}
+ * #### Example 2: Simple 2-Port S-Parameter File
+ * ```plaintext
+ * ! 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
+ * ```
  */
 export declare class Touchstone {
     /**
@@ -585,6 +636,30 @@ export declare class Touchstone {
      * 2. Extracts frequency points
      * 3. Converts raw data into complex numbers based on format
      * 4. Stores the results in the matrix property
+     *
+     * @example
+     * ```typescript
+     * 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
+     * ```
      */
     readContent(string: string, nports: number): void;
     /**
@@ -625,6 +700,37 @@ export declare class Touchstone {
      * 1. Comments (if any)
      * 2. Option line with format, parameter type, and impedance
      * 3. 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 (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
+     * ```
      */
     writeContent(): string;
 }

package/package.json

@@ -1,18 +1,17 @@
 {
   "name": "rf-touchstone",
-  "private": false,
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "A Javascript/TypeScript library for reading, manipulating, and writing Touchstone files (.snp files) used in radio frequency (RF) and microwave engineering.",
   "main": "dist/Touchstone.cjs.js",
   "module": "dist/Touchstone.es.js",
   "types": "dist/touchstone.d.ts",
   "files": [
-    "dist",
-    "readme.md",
-    "development.md",
-    "LICENSE",
-    "coverage/coverage-badge.svg"
+    "./dist",
+    "./readme.md",
+    "./development.md",
+    "./LICENSE",
+    "./coverage/coverage-badge.svg"
   ],
   "license": "MIT",
   "author": "https://github.com/panz2018",
@@ -29,12 +28,15 @@
     "s6p",
     "frequency",
     "scattering",
-    "matrix"
+    "matrix",
+    "impedance"
   ],
+  "packageManager": "yarn@4.9.2",
   "scripts": {
     "test": "run-p --print-label lint format test:unit test:coverage build docs:md && run-s docs:build",
     "lint": "eslint . --fix",
-    "format": "prettier --write src/",
+    "format": "prettier --write .",
+    "test:watch": "vitest",
     "test:unit": "vitest run",
     "test:coverage": "vitest run --coverage && coverage-badges --source coverage/coverage-summary.json --output coverage/coverage-badge.svg",
     "build": "tsc && vite build && yarn pack",
@@ -44,30 +46,30 @@
     "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
-    "mathjs": "^14.5.0"
+    "mathjs": "^14.5.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.27.0",
+    "@eslint/js": "^9.28.0",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^22.15.21",
-    "@vitest/coverage-v8": "^3.1.4",
+    "@types/node": "^22.15.30",
+    "@vitest/coverage-v8": "^3.2.2",
     "coverage-badges-cli": "^2.1.0",
-    "eslint": "^9.27.0",
+    "eslint": "^9.28.0",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-prettier": "^5.4.0",
+    "eslint-plugin-prettier": "^5.4.1",
     "globals": "^16.2.0",
-    "happy-dom": "^17.4.7",
+    "happy-dom": "^17.6.3",
     "markdown-it-mathjax3": "^4.3.2",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.5.3",
-    "rollup-plugin-visualizer": "^5.14.0",
-    "typedoc": "^0.28.4",
-    "typedoc-plugin-markdown": "^4.6.3",
+    "rollup-plugin-visualizer": "^6.0.1",
+    "typedoc": "^0.28.5",
+    "typedoc-plugin-markdown": "^4.6.4",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1",
+    "typescript-eslint": "^8.33.1",
     "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.4",
     "vitepress": "^1.6.3",
-    "vitest": "^3.1.4"
+    "vitest": "^3.2.2"
   }
 }

package/readme.md

@@ -2,9 +2,13 @@
 
 A Javascript/TypeScript library for reading, manipulating, and writing Touchstone files (.snp files) used in radio frequency (RF) and microwave engineering.
 
-[![Tests](https://github.com/panz2018/RF-Touchstone/actions/workflows/Tests.yml/badge.svg)](https://github.com/panz2018/RF-Touchstone/actions/workflows/Tests.yml)
+[![Tests](https://github.com/panz2018/RF-Touchstone/actions/workflows/test.yml/badge.svg)](https://github.com/panz2018/RF-Touchstone/actions/workflows/test.yml)
 [![Coverage](coverage/coverage-badge.svg)](coverage/coverage-badge.svg)
 
+<!--
+[![React Example Tests](https://github.com/mjcaprani/rf-touchstone/actions/workflows/test-react-example.yml/badge.svg)](https://github.com/mjcaprani/rf-touchstone/actions/workflows/test-react-example.yml)
+-->
+
 ## Overview
 
 RF-Touchstone provides a complete solution for working with S-parameters and other network parameters in JavaScript/TypeScript environments. This library allows you to:
@@ -47,16 +51,24 @@ import { Touchstone } from 'rf-touchstone'
 
 // Read a Touchstone file
 const touchstone = new Touchstone()
-touchstone.readContent(fileContent, 2) // 2-port network
+touchstone.readContent(fileContent, 2) // assuming a 2-port network
 
 // Access data
-const frequencies = touchstone.getFrequencies()
-const sParameters = touchstone.getParameterMatrix()
+const frequencies = touchstone.frequency.f_scaled
+const sParameters = touchstone.matrix
 
 // Write back to Touchstone format
 const newContent = touchstone.writeContent()
 ```
 
+<!--
+## Examples
+
+This repository includes examples to demonstrate the usage of `rf-touchstone` in different contexts.
+
+- **[React Example](https://github.com/panz2018/RF-Touchstone/tree/main/examples/react)**: A simple standalone React application (using Vite and TypeScript) that showcases how to import and use `rf-touchstone` from npm to parse and display Touchstone file data. Includes comprehensive tests and a GitHub Action for CI.
+-->
+
 ## Documentation
 
 For detailed documentation, please visit: