rf-touchstone 0.0.4 → 0.0.5

package/.github/AI_USAGE_GUIDE.md

@@ -0,0 +1,585 @@
+# RF-Touchstone AI Usage Guide
+
+> **For AI Coding Assistants**: This guide helps you understand how to integrate and use the `rf-touchstone` library in user projects.
+
+## Quick Start
+
+### Installation
+
+**Via NPM/Yarn:**
+
+```bash
+npm install rf-touchstone
+# or
+yarn add rf-touchstone
+```
+
+**Via CDN:**
+
+```html
+<script src="https://unpkg.com/rf-touchstone"></script>
+<script>
+  const { Touchstone, abs, arg, pi } = window.Touchstone
+</script>
+```
+
+### Basic Import Pattern
+
+```typescript
+import { Touchstone } from 'rf-touchstone'
+// Optional math helpers from mathjs
+import { abs, arg, pi, complex } from 'rf-touchstone'
+```
+
+## Core Concepts
+
+### 1. **Touchstone Class** - Main API Entry Point
+
+The `Touchstone` class is the primary interface for working with .snp files.
+
+#### Creating Touchstone Objects
+
+**From URL (Browser or Node.js with fetch):**
+
+```typescript
+// Auto-detect nports from filename (.s2p → 2-port)
+const ts = await Touchstone.fromUrl('https://example.com/device.s2p')
+
+// Explicit nports if filename doesn't indicate
+const ts = await Touchstone.fromUrl('https://example.com/data.txt', 2)
+```
+
+**From File Object (Browser file input):**
+
+```typescript
+// In any framework with file input
+const handleFileUpload = async (file: File) => {
+  const touchstone = await Touchstone.fromFile(file)
+  // Use touchstone object
+}
+```
+
+**From Text Content (Universal - works in any environment):**
+
+```typescript
+import { Touchstone } from 'rf-touchstone'
+
+// Example S2P file content (could come from any source: upload, API, database, etc.)
+const s2pContent = `! 2-port S-parameter data
+# GHz S MA R 50
+1.0 0.50 -45 0.95 10 0.05 85 0.60 -30
+2.0 0.45 -60 0.90 15 0.10 80 0.55 -45
+3.0 0.40 -75 0.85 20 0.15 75 0.50 -60`
+
+// Parse the text content
+const touchstone = Touchstone.fromText(s2pContent, 2) // 2 = 2-port network
+
+// Now you can use the parsed data
+console.log(touchstone.frequency.f_scaled) // [1.0, 2.0, 3.0]
+console.log(touchstone.format) // 'MA'
+console.log(touchstone.parameter) // 'S'
+```
+
+### 2. **Accessing Touchstone Data**
+
+```typescript
+const ts = await Touchstone.fromUrl('device.s2p')
+
+// Frequency data
+const frequencies = ts.frequency.f_scaled // Array of numbers in specified unit
+const unit = ts.frequency.unit // 'Hz' | 'kHz' | 'MHz' | 'GHz'
+
+// Options line data
+const format = ts.format // 'RI' | 'MA' | 'DB'
+const parameter = ts.parameter // 'S' | 'Y' | 'Z' | 'G' | 'H'
+const impedance = ts.impedance // typically 50
+const nports = ts.nports // Number of ports (1, 2, 3, 4, etc.)
+
+// Network parameter matrix
+// IMPORTANT: matrix is 3D array [outPort][inPort][frequencyIndex]
+const matrix = ts.matrix // Complex number matrix
+```
+
+### 3. **Understanding Matrix Indexing** ⚠️ CRITICAL
+
+**Matrix Structure:**
+
+```typescript
+// matrix[i][j][k]
+// - i: Output port index (0 to nports-1) - where the signal exits
+// - j: Input port index (0 to nports-1) - where the signal enters
+// - k: Frequency point index (0 to numFrequencies-1)
+//
+// Sij = matrix[i-1][j-1][k] means: signal enters at port j, exits at port i
+```
+
+**Accessing S-parameters (consistent for ALL port counts):**
+
+```typescript
+// For 2-port network:
+const s11 = ts.matrix[0][0][freqIdx] // S11
+const s12 = ts.matrix[0][1][freqIdx] // S12
+const s21 = ts.matrix[1][0][freqIdx] // S21
+const s22 = ts.matrix[1][1][freqIdx] // S22
+
+// For 4-port network (same pattern):
+const s11 = ts.matrix[0][0][freqIdx] // S11
+const s21 = ts.matrix[1][0][freqIdx] // S21
+const s31 = ts.matrix[2][0][freqIdx] // S31
+const s41 = ts.matrix[3][0][freqIdx] // S41
+const s12 = ts.matrix[0][1][freqIdx] // S12
+// ... and so on
+
+// General pattern: Sij = ts.matrix[i-1][j-1][freqIdx]
+```
+
+### 4. **Format Conversion**
+
+To convert between formats (RI, MA, DB):
+
+```typescript
+const ts = await Touchstone.fromUrl('device.s2p')
+
+// Method 1: Change format and regenerate content
+ts.format = 'DB' // Change to Decibel/Angle
+const dbContent = ts.writeContent() // Generate new file content
+// Now you can save dbContent or parse it as a new Touchstone object
+
+// Method 2: Create new instance with different format
+const dbTs = Touchstone.fromText(dbContent, ts.nports)
+```
+
+### 5. **Writing Touchstone Content**
+
+```typescript
+const ts = await Touchstone.fromUrl('device.s2p')
+
+// Generate Touchstone file content in current format
+const content = ts.writeContent()
+
+// In Browser - Download as file
+const blob = new Blob([content], { type: 'text/plain' })
+const url = URL.createObjectURL(blob)
+const a = document.createElement('a')
+a.href = url
+a.download = 'modified-device.s2p'
+a.click()
+
+// In Node.js - Save to file
+import fs from 'fs/promises'
+await fs.writeFile('modified-device.s2p', content)
+```
+
+### 6. **Working with Complex Numbers**
+
+The library uses mathjs Complex type `{ re: number, im: number }`:
+
+```typescript
+import { abs, arg, pi } from 'rf-touchstone'
+
+// Get S11 at first frequency for 2-port
+const s11 = ts.matrix[0][0][0] // Complex { re: ..., im: ... }
+
+// Calculate magnitude
+const magnitude = abs(s11) // |S11|
+
+// Calculate phase (in radians)
+const phase = arg(s11) // ∠S11
+
+// Convert to dB
+const magnitudeDB = 20 * Math.log10(magnitude)
+
+// Convert phase to degrees
+const phaseDegrees = (phase * 180) / pi
+```
+
+## Common Use Cases
+
+### Example 1: File Upload in Browser (Vanilla JavaScript)
+
+```typescript
+import { Touchstone, abs, arg, pi } from 'rf-touchstone'
+
+// HTML: <input type="file" id="fileInput" accept=".s*p">
+const fileInput = document.getElementById('fileInput') as HTMLInputElement
+
+fileInput.addEventListener('change', async (event) => {
+  const file = (event.target as HTMLInputElement).files?![0]
+  if (!file) return
+
+  try {
+    const ts = await Touchstone.fromFile(file)
+
+    console.log(`${ts.nports}-Port Network`)
+    console.log(`Frequencies: ${ts.frequency.f_scaled.length}`)
+    console.log(`Unit: ${ts.frequency.unit}`)
+    console.log(`Format: ${ts.format}`)
+
+    // Access S11 at first frequency (works for any port count)
+    const s11 = ts.matrix[0][0][0]
+    console.log(`S11 Magnitude: ${abs(s11)}`)
+    console.log(`S11 Phase (deg): ${(arg(s11) * 180 / pi).toFixed(2)}`)
+
+  } catch (error) {
+    console.error('Error loading Touchstone file:', error)
+  }
+})
+```
+
+### Example 2: Format Converter (Node.js)
+
+```typescript
+import { Touchstone } from 'rf-touchstone'
+import fs from 'fs/promises'
+
+async function convertTouchstone(
+  inputPath: string,
+  outputPath: string,
+  targetFormat: 'RI' | 'MA' | 'DB'
+) {
+  // Read input file
+  const content = await fs.readFile(inputPath, 'utf-8')
+
+  // Determine nports from filename
+  const nports = Touchstone.parsePorts(inputPath)
+  if (nports === null) {
+    throw new Error(
+      `Cannot determine number of ports from filename: ${inputPath}`
+    )
+  }
+
+  // Parse the file
+  const ts = Touchstone.fromText(content, nports)
+
+  console.log(`Original format: ${ts.format}`)
+
+  // Convert format
+  ts.format = targetFormat
+  const convertedContent = ts.writeContent()
+
+  // Write output
+  await fs.writeFile(outputPath, convertedContent)
+
+  console.log(`Converted to ${targetFormat}`)
+}
+
+// Usage
+await convertTouchstone('input.s2p', 'output.s2p', 'DB')
+```
+
+### Example 3: S-Parameter Plotting (Any Framework)
+
+```typescript
+import { Touchstone, abs } from 'rf-touchstone'
+
+async function getPlotData(url: string) {
+  const ts = await Touchstone.fromUrl(url)
+
+  const numFreqs = ts.frequency.f_scaled.length
+  const frequencies = ts.frequency.f_scaled
+
+  // Extract S21 magnitude in dB for all frequencies (2-port network)
+  const s21_dB: number[] = []
+  for (let freqIdx = 0; freqIdx < numFreqs; freqIdx++) {
+    const s21 = ts.matrix[1][0][freqIdx] // S21 for 2-port
+    const magnitude = abs(s21)
+    s21_dB.push(20 * Math.log10(magnitude))
+  }
+
+  return {
+    frequencies,
+    s21_dB,
+    unit: ts.frequency.unit,
+  }
+}
+
+// Use with any chart library (Chart.js, D3, Plotly, etc.)
+const data = await getPlotData('https://example.com/device.s2p')
+console.log(data)
+// { frequencies: [...], s21_dB: [...], unit: 'GHZ' }
+```
+
+### Example 4: Data Analysis
+
+```typescript
+import { Touchstone, abs } from 'rf-touchstone'
+
+async function analyzeTouchstone(file: File) {
+  const ts = await Touchstone.fromFile(file)
+
+  if (ts.nports !== 2) {
+    throw new Error('This example is for 2-port networks only')
+  }
+
+  const numFreqs = ts.frequency.f_scaled.length
+
+  // Calculate insertion loss (S21)
+  let maxS21 = 0
+  for (let i = 0; i < numFreqs; i++) {
+    const mag = abs(ts.matrix[1][0][i]) // S21
+    if (mag > maxS21) maxS21 = mag
+  }
+  const insertionLoss_dB = -20 * Math.log10(maxS21)
+
+  // Calculate return loss (S11)
+  let maxS11 = 0
+  for (let i = 0; i < numFreqs; i++) {
+    const mag = abs(ts.matrix[0][0][i]) // S11
+    if (mag > maxS11) maxS11 = mag
+  }
+  const returnLoss_dB = -20 * Math.log10(maxS11)
+
+  return {
+    nports: ts.nports,
+    numFrequencies: numFreqs,
+    frequencyRange: {
+      min: ts.frequency.f_scaled[0],
+      max: ts.frequency.f_scaled[numFreqs - 1],
+      unit: ts.frequency.unit,
+    },
+    insertionLoss_dB: insertionLoss_dB.toFixed(2),
+    returnLoss_dB: returnLoss_dB.toFixed(2),
+    format: ts.format,
+  }
+}
+```
+
+### Example 5: Vue Component
+
+```vue
+<template>
+  <div>
+    <input type="file" @change="handleFileUpload" accept=".s*p" />
+    <div v-if="touchstone">
+      <h2>{{ touchstone.nports }}-Port Network</h2>
+      <p>Frequencies: {{ touchstone.frequency.f_scaled.length }}</p>
+      <p>Unit: {{ touchstone.frequency.unit }}</p>
+      <p>Format: {{ touchstone.format }}</p>
+      <button @click="convertToDb">Convert to dB</button>
+      <button @click="downloadFile">Download</button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Touchstone } from 'rf-touchstone'
+
+const touchstone = ref<Touchstone | null>(null)
+
+async function handleFileUpload(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0]
+  if (file) {
+    touchstone.value = await Touchstone.fromFile(file)
+  }
+}
+
+function convertToDb() {
+  if (touchstone.value) {
+    touchstone.value.format = 'DB'
+    // Re-parse to get converted matrix
+    const content = touchstone.value.writeContent()
+    touchstone.value = Touchstone.fromText(content, touchstone.value.nports!)
+  }
+}
+
+function downloadFile() {
+  if (touchstone.value) {
+    const content = touchstone.value.writeContent()
+    const blob = new Blob([content], { type: 'text/plain' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `converted.s${touchstone.value.nports}p`
+    a.click()
+  }
+}
+</script>
+```
+
+## TypeScript Types
+
+### Key Interfaces and Types
+
+```typescript
+// Touchstone class
+class Touchstone {
+  // Properties
+  nports?: number
+  frequency?: Frequency
+  format?: 'RI' | 'MA' | 'DB'
+  parameter?: 'S' | 'Y' | 'Z' | 'G' | 'H'
+  impedance: number | number[] // default: 50
+  matrix?: Complex[][][] // [outPort][inPort][freqIdx]
+  comments: string[]
+
+  // Static methods
+  static fromText(content: string, nports: number): Touchstone
+  static fromUrl(url: string, nports?: number): Promise<Touchstone>
+  static fromFile(file: File, nports?: number): Promise<Touchstone>
+  static getFilename(pathOrUrl: string): string
+  static parsePorts(filename: string): number | null
+
+  // Instance methods
+  readContent(content: string, nports: number): void
+  writeContent(): string
+  validate(): void
+}
+
+// Complex number (from mathjs)
+interface Complex {
+  re: number // Real part
+  im: number // Imaginary part
+}
+
+// Frequency class
+class Frequency {
+  unit: 'Hz' | 'kHz' | 'MHz' | 'GHz'
+  f_scaled: number[] // Frequency values in current unit
+
+  // Getters/setters for different units
+  f_Hz: number[]
+  f_kHz: number[]
+  f_MHz: number[]
+  f_GHz: number[]
+  f_THz: number[]
+
+  // Wavelength getters/setters
+  wavelength_m: number[]
+  wavelength_cm: number[]
+  wavelength_mm: number[]
+  wavelength_um: number[]
+  wavelength_nm: number[]
+}
+
+// Helper Functions (from mathjs)
+// These can be imported: import { abs, arg, pi } from 'rf-touchstone'
+function abs(x: Complex | number): number
+function arg(x: Complex): number // Returns phase in radians
+function complex(re: number, im: number): Complex
+function complex(obj: { r: number; phi: number }): Complex // Polar form
+const pi: number
+
+// Other available helpers:
+// add, multiply, pow, log10, round, range, index, subset
+```
+
+## Important Notes
+
+### Module Formats Support
+
+This library supports **multiple module formats** for maximum compatibility:
+
+- **UMD (Universal Module Definition)**: `dist/Touchstone.umd.js` - For direct browser `<script>` tags
+- **ESM (ES Modules)**: `dist/Touchstone.es.js` - For modern bundlers and `import` statements
+- **CJS (CommonJS)**: `dist/Touchstone.cjs.js` - For older Node.js projects using `require()`
+
+**Using in Browser (UMD):**
+
+Via CDN:
+
+```html
+<!-- Using unpkg -->
+<script src="https://unpkg.com/rf-touchstone"></script>
+
+<!-- Or using jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/rf-touchstone"></script>
+
+<script>
+  const { Touchstone, abs, arg } = window.Touchstone
+</script>
+```
+
+**Using in Modern Projects (ESM):**
+
+```typescript
+import { Touchstone } from 'rf-touchstone'
+```
+
+**Using in Legacy Node.js (CommonJS):**
+
+```javascript
+const { Touchstone } = require('rf-touchstone')
+```
+
+### Browser vs Node.js
+
+- `Touchstone.fromUrl()` works in both environments (uses `fetch`)
+- `Touchstone.fromFile()` is browser-only (uses `File` API)
+- For Node.js file reading, use `fs` and `Touchstone.fromText()`
+
+### Port Indexing
+
+**Matrix indexing is consistent for ALL port counts:**
+
+```typescript
+// General pattern: Sij = matrix[i-1][j-1][freqIdx]
+
+// For any N-port network:
+const s11 = matrix[0][0][freqIdx] // S11
+const s21 = matrix[1][0][freqIdx] // S21
+const s12 = matrix[0][1][freqIdx] // S12
+const s22 = matrix[1][1][freqIdx] // S22
+// etc.
+```
+
+### Memory Considerations
+
+Large .snp files (many ports/frequencies) create large matrices:
+
+- Processing in chunks
+- Not storing multiple copies simultaneously
+
+## Error Handling
+
+```typescript
+try {
+  const ts = await Touchstone.fromUrl('device.s2p')
+} catch (error) {
+  if (error instanceof Error) {
+    // Common errors:
+    // - Network errors (URL fetch failed)
+    // - Parse errors (invalid Touchstone format)
+    // - File not found
+    // - Could not determine nports
+    console.error('Failed to load Touchstone:', error.message)
+  }
+}
+```
+
+## Resources
+
+- **API Documentation**: https://panz2018.github.io/RF-Touchstone/api/modules
+- **GitHub**: https://github.com/panz2018/RF-Touchstone
+- **NPM**: https://www.npmjs.com/package/rf-touchstone
+
+## Common Patterns Summary
+
+```typescript
+// ✅ DO: Load from URL
+const ts = await Touchstone.fromUrl('file.s2p')
+
+// ✅ DO: Access matrix correctly (same for all port counts)
+const s21 = ts.matrix[1][0][freqIdx] // S21
+
+// ✅ DO: Convert format properly
+ts.format = 'DB'
+const dbContent = ts.writeContent()
+
+// ✅ DO: Iterate frequencies correctly
+for (let freqIdx = 0; freqIdx < ts.frequency.f_scaled.length; freqIdx++) {
+  const s11 = ts.matrix[0][0][freqIdx]
+  // process s11...
+}
+
+// ❌ DON'T: Use non-existent convertFormat method
+// const tsDB = ts.convertFormat('DB')  // This doesn't exist!
+
+// ❌ DON'T: Use wrong matrix indexing
+// const s11 = ts.matrix[freqIdx][0][0]  // WRONG!
+```
+
+---
+
+**Last Updated**: 2026-01-25
+**Library Version**: 0.0.5+

package/dist/Touchstone.es.js

@@ -8834,10 +8834,11 @@ class nu {
   frequency;
   /**
    * 3D array to store the network parameter data
-   * - The first dimension is the exits (output) port number
-   * - The second dimension is the enters (input) port number
-   * - The third dimension is the frequency index
-   * For example, data[i][j][k] would be the parameter from j+1 port to i+1 port at frequency index k
+   * - First dimension [i]: Output port index (0 to nports-1) - where signal exits
+   * - Second dimension [j]: Input port index (0 to nports-1) - where signal enters
+   * - Third dimension [k]: Frequency index
+   *
+   * For example: matrix[i][j][k] is the parameter from port j+1 to port i+1 at frequency k
    */
   _matrix;
   /**
@@ -8858,17 +8859,21 @@ class nu {
    *
    * @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)
+   * - 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:
-   * - 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
+   * @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
    *
-   * Special case for 2-port networks:
-   * - Indices are swapped to match traditional Touchstone format
-   * - matrix[0][1][k] represents S₁₂ (not S₂₁)
+   * // General pattern: Sij = matrix[i-1][j-1][freqIdx]
+   * // where i is the output port number, j is the input port number
+   * ```
    *
    * @returns The current network parameter matrix, or undefined if not set
    */

package/dist/touchstone.d.ts

@@ -46,17 +46,23 @@ export type TouchstoneImpedance = number | number[];
  *
  * @remarks
  * The matrix is a 3D array with the following dimensions:
- * - First dimension: output port index (0 to nports-1)
- * - Second dimension: input port index (0 to nports-1)
- * - Third dimension: frequency point index
+ * - 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
  *
  * For 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
+ * - `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
+ *   (signal enters at port 1, exits at port 2)
  *
- * Special case for 2-port networks:
- * - Indices are swapped to match traditional Touchstone format
- * - matrix[0][1][k] represents S₁₂ (not S₂₁)
+ * @example
+ * ```typescript
+ * // Access S21 (port 1 → port 2) at first frequency
+ * const s21 = touchstone.matrix[1][0][0]
+ *
+ * // Access S11 (port 1 → port 1, reflection) at first frequency
+ * const s11 = touchstone.matrix[0][0][0]
+ * ```
  */
 export type TouchstoneMatrix = Complex[][][];
 /**
@@ -249,10 +255,11 @@ export declare class Touchstone {
     frequency: Frequency | undefined;
     /**
      * 3D array to store the network parameter data
-     * - The first dimension is the exits (output) port number
-     * - The second dimension is the enters (input) port number
-     * - The third dimension is the frequency index
-     * For example, data[i][j][k] would be the parameter from j+1 port to i+1 port at frequency index k
+     * - First dimension [i]: Output port index (0 to nports-1) - where signal exits
+     * - Second dimension [j]: Input port index (0 to nports-1) - where signal enters
+     * - Third dimension [k]: Frequency index
+     *
+     * For example: matrix[i][j][k] is the parameter from port j+1 to port i+1 at frequency k
      */
     private _matrix;
     /**
@@ -267,17 +274,21 @@ export declare class Touchstone {
      *
      * @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)
+     * - 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:
-     * - 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
+     * @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
      *
-     * Special case for 2-port networks:
-     * - Indices are swapped to match traditional Touchstone format
-     * - matrix[0][1][k] represents S₁₂ (not S₂₁)
+     * // General pattern: Sij = matrix[i-1][j-1][freqIdx]
+     * // where i is the output port number, j is the input port number
+     * ```
      *
      * @returns The current network parameter matrix, or undefined if not set
      */

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "rf-touchstone",
   "type": "module",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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",
+  "browser": "dist/Touchstone.umd.js",
+  "unpkg": "dist/Touchstone.umd.js",
+  "jsdelivr": "dist/Touchstone.umd.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/Touchstone.umd.js",
       "import": "./dist/Touchstone.es.js",
       "require": "./dist/Touchstone.cjs.js"
     }
@@ -18,7 +22,8 @@
     "./src",
     "./readme.md",
     "./LICENSE.md",
-    "./coverage/coverage-badge.svg"
+    "./coverage/coverage-badge.svg",
+    "./.github/AI_USAGE_GUIDE.md"
   ],
   "license": "MIT",
   "author": "https://github.com/panz2018",

package/readme.md

@@ -2,6 +2,8 @@
 
 A Javascript/TypeScript library for reading, manipulating, and writing Touchstone files (.snp files) used in radio frequency (RF) and microwave engineering.
 
+<a href="https://deepwiki.com/panz2018/RF-Touchstone" target="_blank"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" align="right"></a>
+
 [![Tests](https://github.com/panz2018/RF-Touchstone/actions/workflows/test.yml/badge.svg?event=pull_request)](https://github.com/panz2018/RF-Touchstone/actions/workflows/test.yml)
 [![Coverage](coverage/coverage-badge.svg)](coverage/coverage-badge.svg)
 
@@ -35,12 +37,29 @@ RF-Touchstone currently supports versions 1.0 and 1.1 of the Touchstone specific
 
 ## Installation
 
+### Via NPM/Yarn
+
 ```bash
 npm install rf-touchstone
 # or
 yarn add rf-touchstone
 ```
 
+### Via CDN (Browser)
+
+```html
+<!-- Using unpkg -->
+<script src="https://unpkg.com/rf-touchstone"></script>
+
+<!-- Or using jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/rf-touchstone"></script>
+
+<script>
+  // Access via global variable
+  const { Touchstone } = window.Touchstone
+</script>
+```
+
 ## Quick Start
 
 ```typescript
@@ -83,6 +102,7 @@ This repository includes examples to demonstrate the usage of `rf-touchstone` in
 For detailed documentation, please visit:
 
 - [Project Website](https://panz2018.github.io/RF-Touchstone/)
+- [AI Usage Guide](https://github.com/panz2018/RF-Touchstone/blob/main/.github/AI_USAGE_GUIDE.md) - Comprehensive guide for AI coding assistants and developers integrating this library
 - [DeepWiki Documentation](https://deepwiki.com/panz2018/RF-Touchstone) - Interactive AI documentation that allows you to converse and ask questions about this repository
 - [Changelog](https://github.com/panz2018/RF-Touchstone/releases)
 

package/src/touchstone.ts

@@ -67,17 +67,23 @@ export type TouchstoneImpedance = number | number[]
  *
  * @remarks
  * The matrix is a 3D array with the following dimensions:
- * - First dimension: output port index (0 to nports-1)
- * - Second dimension: input port index (0 to nports-1)
- * - Third dimension: frequency point index
+ * - 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
  *
  * For 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
+ * - `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
+ *   (signal enters at port 1, exits at port 2)
  *
- * Special case for 2-port networks:
- * - Indices are swapped to match traditional Touchstone format
- * - matrix[0][1][k] represents S₁₂ (not S₂₁)
+ * @example
+ * ```typescript
+ * // Access S21 (port 1 → port 2) at first frequency
+ * const s21 = touchstone.matrix[1][0][0]
+ *
+ * // Access S11 (port 1 → port 1, reflection) at first frequency
+ * const s11 = touchstone.matrix[0][0][0]
+ * ```
  */
 export type TouchstoneMatrix = Complex[][][]
 
@@ -457,10 +463,11 @@ export class Touchstone {
 
   /**
    * 3D array to store the network parameter data
-   * - The first dimension is the exits (output) port number
-   * - The second dimension is the enters (input) port number
-   * - The third dimension is the frequency index
-   * For example, data[i][j][k] would be the parameter from j+1 port to i+1 port at frequency index k
+   * - First dimension [i]: Output port index (0 to nports-1) - where signal exits
+   * - Second dimension [j]: Input port index (0 to nports-1) - where signal enters
+   * - Third dimension [k]: Frequency index
+   *
+   * For example: matrix[i][j][k] is the parameter from port j+1 to port i+1 at frequency k
    */
   private _matrix: TouchstoneMatrix | undefined
 
@@ -483,17 +490,21 @@ export class Touchstone {
    *
    * @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)
+   * - 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:
-   * - 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
+   * @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
    *
-   * Special case for 2-port networks:
-   * - Indices are swapped to match traditional Touchstone format
-   * - matrix[0][1][k] represents S₁₂ (not S₂₁)
+   * // General pattern: Sij = matrix[i-1][j-1][freqIdx]
+   * // where i is the output port number, j is the input port number
+   * ```
    *
    * @returns The current network parameter matrix, or undefined if not set
    */