rf-touchstone 0.0.2 → 0.0.4

package/dist/frequency.d.ts

@@ -1,15 +1,14 @@
 /**
- * Frequency units: 'Hz', 'kHz', 'MHz', 'GHz'
- * Touchstone standard doesn't support THz as the frequency unit in Touchstone file
+ * Supported frequency units in the Touchstone specification.
+ * Note: THz is not officially supported as a file header unit in Touchstone v1.x/v2.x.
  */
 export declare const FrequencyUnits: readonly ["Hz", "kHz", "MHz", "GHz"];
 /**
- * Type definition for frequency units
- * - Hz: Hertz (cycles per second)
- * - kHz: Kilohertz (10³ Hz)
- * - MHz: Megahertz (10⁶ Hz)
- * - GHz: Gigahertz (10⁹ Hz)
- * Touchstone standard doesn't support THz as the frequency unit in Touchstone file
+ * Type representing the frequency unit.
+ * - Hz: Hertz ($10^0$ Hz)
+ * - kHz: Kilohertz ($10^3$ Hz)
+ * - MHz: Megahertz ($10^6$ Hz)
+ * - GHz: Gigahertz ($10^9$ Hz)
  */
 export type FrequencyUnit = (typeof FrequencyUnits)[number];
 /**
@@ -25,19 +24,29 @@ export declare const FREQUENCY_MULTIPLIERS: Record<FrequencyUnit | 'THz', number
  */
 export declare const WAVELENGTH_MULTIPLIERS_TO_M: Record<string, number>;
 /**
- * Class representing frequency data in RF and microwave engineering
+ * Represents frequency data and provides utility methods for unit conversion and wavelength calculation.
  *
  * @remarks
- * The Frequency class manages frequency-related data, including:
- * - Frequency unit management
- * - Storage of frequency points
- * - Unit conversion capabilities
+ * The `Frequency` class is designed to handle frequency points commonly used in RF, microwave,
+ * and high-speed digital engineering. It maintains an internal unit and a set of frequency points,
+ * allowing for seamless conversion between different frequency and wavelength units.
+ *
+ * ##### Key Features:
+ * - **Unit Awareness**: Keeps track of whether frequencies are defined in Hz, MHz, GHz, etc.
+ * - **Automatic Conversion**: Automatically scales frequency points when the `unit` property is changed.
+ * - **Wavelength Utilities**: Provides getters and setters for wavelength ($\lambda = c/f$) in various metric units.
  *
  * @example
+ * #### Basic Usage
  * ```typescript
+ * import { Frequency } from 'rf-touchstone';
+ *
  * const freq = new Frequency();
  * freq.unit = 'GHz';
- * freq.f_scale = [1.0, 2.0, 3.0];
+ * freq.f_scaled = [1.0, 2.0, 5.0];
+ *
+ * console.log(freq.f_Hz); // [1e9, 2e9, 5e9]
+ * console.log(freq.wavelength_mm); // [299.79, 149.90, 59.96]
  * ```
  */
 export declare class Frequency {
@@ -47,28 +56,15 @@ export declare class Frequency {
      */
     private _unit;
     /**
-     * Sets the frequency unit for the instance
-     *
-     * @param newUnit - The frequency unit to set
-     * @throws {Error} If the provided unit is not one of the supported frequency units
+     * Sets the frequency unit. If frequency points already exist, they will be
+     * automatically rescaled to the new unit.
      *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'MHz'; // Sets unit to Megahertz
-     * ```
+     * @param newUnit - The target frequency unit (Hz, kHz, MHz, or GHz).
+     * @throws Error if the provided unit is invalid.
      */
     set unit(newUnit: FrequencyUnit);
     /**
-     * Gets the current frequency unit
-     *
-     * @returns The current frequency unit
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * console.log(freq.unit); // Outputs: 'Hz'
-     * ```
+     * Gets the current frequency unit.
      */
     get unit(): FrequencyUnit;
     /**
@@ -78,33 +74,14 @@ export declare class Frequency {
      */
     private _f_scaled;
     /**
-     * Array of frequency points in the current frequency unit
-     * Each element represents a discrete frequency point for measurement or analysis
-     *
-     * @param value - Array of frequency points
-     * @throws {Error} If the input is not an array
-     * @throws {Error} If any element in the array is not a number
-     * @throws {Error} If the array contains negative frequencies
+     * Sets the array of frequency points in the current frequency unit.
      *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [1.0, 1.5, 2.0]; // Sets frequency points in GHz
-     * ```
+     * @param value - Array of numerical frequency points.
+     * @throws Error if the input is not a non-negative number array.
      */
     set f_scaled(value: number[]);
     /**
-     * Gets the array of frequency points
-     * @returns Array of frequency points in the current unit
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'MHz';
-     * freq.f_scaled = [100, 200, 300];
-     * console.log(freq.f_scaled); // Outputs: [100, 200, 300]
-     * ```
+     * Gets the array of frequency points in the current unit.
      */
     get f_scaled(): number[];
     /**
@@ -114,139 +91,49 @@ export declare class Frequency {
      */
     private _getFrequencyInTargetUnit;
     /**
-     * Private helper method to set frequency values from a source unit.
-     * @param values - Array of frequency points in the source unit.
-     * @param sourceUnit - The key of the source frequency unit in FREQUENCY_MULTIPLIERS.
+     * Internal helper to set frequency values from a source unit.
+     * @param values - Array of frequency points.
+     * @param sourceUnit - The source frequency unit key.
      */
     private _setFrequencyFromTargetUnit;
     /**
-     * Gets frequency points in Hz
-     * @returns Array of frequency points in Hz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [1, 2, 3]; // 1 GHz, 2 GHz, 3 GHz
-     * console.log(freq.f_Hz); // Outputs: [1e9, 2e9, 3e9]
-     * ```
+     * Gets the frequency points in Hertz (Hz).
      */
     get f_Hz(): number[];
     /**
-     * Sets frequency points assuming input is in Hz
-     * @param values - Array of frequency points in Hz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'MHz';
-     * freq.f_Hz = [1e9, 2e9, 3e9]; // Sets frequencies as 1 GHz, 2 GHz, 3 GHz
-     * console.log(freq.f_scaled); // Outputs: [1000, 2000, 3000] (in MHz)
-     * ```
+     * Sets the frequency points in Hertz (Hz).
      */
     set f_Hz(values: number[]);
     /**
-     * Gets frequency points in kHz
-     * @returns Array of frequency points in kHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'Hz';
-     * freq.f_scaled = [1000, 2000, 3000]; // 1 kHz, 2 kHz, 3 kHz
-     * console.log(freq.f_kHz); // Outputs: [1, 2, 3]
-     * ```
+     * Gets the frequency points in Kilohertz (kHz).
      */
     get f_kHz(): number[];
     /**
-     * Sets frequency points assuming input is in kHz
-     * @param values - Array of frequency points in kHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'Hz';
-     * freq.f_kHz = [1, 2, 3]; // Sets frequencies as 1 kHz, 2 kHz, 3 kHz
-     * console.log(freq.f_scaled); // Outputs: [1000, 2000, 3000] (in Hz)
-     * ```
+     * Sets the frequency points in Kilohertz (kHz).
      */
     set f_kHz(values: number[]);
     /**
-     * Gets frequency points in MHz
-     * @returns Array of frequency points in MHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [0.1, 0.2, 0.3]; // 0.1 GHz, 0.2 GHz, 0.3 GHz
-     * console.log(freq.f_MHz); // Outputs: [100, 200, 300]
-     * ```
+     * Gets the frequency points in Megahertz (MHz).
      */
     get f_MHz(): number[];
     /**
-     * Sets frequency points assuming input is in MHz
-     * @param values - Array of frequency points in MHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_MHz = [100, 200, 300]; // Sets frequencies as 100 MHz, 200 MHz, 300 MHz
-     * console.log(freq.f_scaled); // Outputs: [0.1, 0.2, 0.3] (in GHz)
-     * ```
+     * Sets the frequency points in Megahertz (MHz).
      */
     set f_MHz(values: number[]);
     /**
-     * Gets frequency points in GHz
-     * @returns Array of frequency points in GHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'MHz';
-     * freq.f_scaled = [1000, 2000, 3000]; // 1000 MHz, 2000 MHz, 3000 MHz
-     * console.log(freq.f_GHz); // Outputs: [1, 2, 3]
-     * ```
+     * Gets the frequency points in Gigahertz (GHz).
      */
     get f_GHz(): number[];
     /**
-     * Sets frequency points assuming input is in GHz
-     * @param values - Array of frequency points in GHz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'MHz';
-     * freq.f_GHz = [1, 2, 3]; // Sets frequencies as 1 GHz, 2 GHz, 3 GHz
-     * console.log(freq.f_scaled); // Outputs: [1000, 2000, 3000] (in MHz)
-     * ```
+     * Sets the frequency points in Gigahertz (GHz).
      */
     set f_GHz(values: number[]);
     /**
-     * Gets frequency points in THz
-     * @returns Array of frequency points in THz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [1000, 2000, 3000]; // 1000 GHz, 2000 GHz, 3000 GHz
-     * console.log(freq.f_THz); // Outputs: [1, 2, 3]
-     * ```
+     * Gets the frequency points in Terahertz (THz).
      */
     get f_THz(): number[];
     /**
-     * Sets frequency points assuming input is in THz
-     * @param values - Array of frequency points in THz
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_THz = [1, 2, 3]; // Sets frequencies as 1 THz, 2 THz, 3 THz
-     * console.log(freq.f_scaled); // Outputs: [1000, 2000, 3000] (in GHz)
-     * ```
+     * Sets the frequency points in Terahertz (THz).
      */
     set f_THz(values: number[]);
     /**
@@ -262,133 +149,44 @@ export declare class Frequency {
      */
     private _setWavelengthFromTargetUnit;
     /**
-     * Gets wavelength in meters
-     * @returns Array of wavelength values in meters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [1, 2, 3]; // Frequencies in GHz
-     * console.log(freq.wavelength_m); // Outputs: Wavelengths in meters
-     * ```
+     * Gets the wavelength in meters (m).
      */
     get wavelength_m(): number[];
     /**
-     * Sets wavelength in meters. Converts to frequency and stores.
-     * @param values - Array of wavelength values in meters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.wavelength_m = [0.3, 0.15, 0.1]; // Wavelengths in meters
-     * console.log(freq.f_scaled); // Outputs: Frequencies in GHz
-     * ```
+     * Sets the wavelength in meters (m).
+     * Note: Changing wavelengths will update the underlying frequency points.
      */
     set wavelength_m(values: number[]);
     /**
-     * Gets wavelength in centimeters
-     * @returns Array of wavelength values in centimeters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [10, 20, 30]; // Frequencies in GHz
-     * console.log(freq.wavelength_cm); // Outputs: Wavelengths in centimeters
-     * ```
+     * Gets the wavelength in centimeters (cm).
      */
     get wavelength_cm(): number[];
     /**
-     * Sets wavelength in centimeters. Converts to frequency and stores.
-     * @param values - Array of wavelength values in centimeters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.wavelength_cm = [30, 15, 10]; // Wavelengths in centimeters
-     * console.log(freq.f_scaled); // Outputs: Frequencies in GHz
-     * ```
+     * Sets the wavelength in centimeters (cm).
      */
     set wavelength_cm(values: number[]);
     /**
-     * Gets wavelength in millimeters
-     * @returns Array of wavelength values in millimeters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [100, 200, 300]; // Frequencies in GHz
-     * console.log(freq.wavelength_mm); // Outputs: Wavelengths in millimeters
-     * ```
+     * Gets the wavelength in millimeters (mm).
      */
     get wavelength_mm(): number[];
     /**
-     * Sets wavelength in millimeters. Converts to frequency and stores.
-     * @param values - Array of wavelength values in millimeters
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.wavelength_mm = [300, 150, 100]; // Wavelengths in millimeters
-     * console.log(freq.f_scaled); // Outputs: Frequencies in GHz
-     * ```
+     * Sets the wavelength in millimeters (mm).
      */
     set wavelength_mm(values: number[]);
     /**
-     * Gets wavelength in micrometers
-     * @returns Array of wavelength values in micrometers
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.f_scaled = [1000, 2000, 3000]; // Frequencies in GHz
-     * console.log(freq.wavelength_um); // Outputs: Wavelengths in micrometers
-     * ```
+     * Gets the wavelength in micrometers (μm).
      */
     get wavelength_um(): number[];
     /**
-     * Sets wavelength in micrometers. Converts to frequency and stores.
-     * @param values - Array of wavelength values in micrometers
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'GHz';
-     * freq.wavelength_um = [300000, 150000, 100000]; // Wavelengths in micrometers
-     * console.log(freq.f_scaled); // Outputs: Frequencies in GHz
-     * ```
+     * Sets the wavelength in micrometers (μm).
      */
     set wavelength_um(values: number[]);
     /**
-     * Gets wavelength in nanometers
-     * @returns Array of wavelength values in nanometers
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'THz';
-     * freq.f_scaled = [100, 200, 300]; // Frequencies in THz
-     * console.log(freq.wavelength_nm); // Outputs: Wavelengths in nanometers
-     * ```
+     * Gets the wavelength in nanometers (nm).
      */
     get wavelength_nm(): number[];
     /**
-     * Sets wavelength in nanometers. Converts to frequency and stores.
-     * @param values - Array of wavelength values in nanometers
-     *
-     * @example
-     * ```typescript
-     * const freq = new Frequency();
-     * freq.unit = 'THz';
-     * freq.wavelength_nm = [300, 150, 100]; // Wavelengths in nanometers
-     * console.log(freq.f_scaled); // Outputs: Frequencies in THz
-     * ```
+     * Sets the wavelength in nanometers (nm).
      */
     set wavelength_nm(values: number[]);
 }

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import { abs, add, arg, log10, index, multiply, pi, pow, round, subset } from 'mathjs';
 /**
  * Creates a complex value or converts a value to a complex value.
  *
@@ -19,6 +18,7 @@ export declare const range: {
     (start: number | import('mathjs').BigNumber, end: number | import('mathjs').BigNumber, includeEnd?: boolean): import('mathjs').Matrix;
     (start: number | import('mathjs').BigNumber | import('mathjs').Unit, end: number | import('mathjs').BigNumber | import('mathjs').Unit, step: number | import('mathjs').BigNumber | import('mathjs').Unit, includeEnd?: boolean): import('mathjs').Matrix;
 };
-export { abs, add, arg, log10, index, multiply, pi, pow, round, subset };
+export { abs, add, arg, log10, index, multiply, pi, pow, round, subset, } from 'mathjs';
+export type { Complex } from 'mathjs';
 export * from './frequency';
 export * from './touchstone';