From 00ae3888ee8e9f1ea98ae69be8fde8f445c9bc5e Mon Sep 17 00:00:00 2001 From: Ian Cleary Date: Wed, 22 Jul 2026 14:20:57 +0000 Subject: [PATCH 1/3] docs: clarify gainlineup agent usage --- AGENTS.md | 19 +++++++++++++++++++ CLAUDE.md | 19 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 46abb66..46d7609 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,25 @@ Rust crate for RF signal chain cascade analysis: gain, noise figure, P1dB, IP3/IMD3, dynamic range, and AM-AM/AM-PM modeling. +## Agent Usage + +Use `gainlineup` when the task describes an ordered RF chain: LNAs, filters, +attenuators, mixers, power amplifiers, gain compression, cascaded noise figure, +OIP3/IIP3, SFDR, dynamic range, or AM-AM/AM-PM behavior. Model each hardware +stage as a `Block`, create one `Input`, then call +`cascade_vector_return_vector` when intermediate stage outputs matter or +`cascade_vector_return_output` when only the final result matters. + +Do not use this crate for file-based S-parameter network analysis; use +`touchstone` for `.sNp` parsing and matrix/network-parameter work. Do not use it +for full radio-link BER/margin/orbit/Doppler questions; use `linkbudget` there. +Use `rfconversions` for standalone scalar conversions before building a chain. + +Keep the RF semantics straight: `gain_db` may be negative for losses, passive +losses should usually have matching positive `noise_figure_db`, P1dB and IP3 +fields are output-referred dBm values, and `Input::noise_temperature_k` is an +optional source/system temperature contribution rather than a block NF. + ## Commands ```bash diff --git a/CLAUDE.md b/CLAUDE.md index c7c995a..6676491 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,6 +4,25 @@ Rust crate for RF signal chain (gain lineup) cascade analysis. Models amplifiers, filters, attenuators, and mixers — cascading gain, noise figure (Friis equation), P1dB compression, IP3/IMD3, and dynamic range. Published on crates.io (v0.22.2). +## Agent Usage + +Use `gainlineup` when the task describes an ordered RF chain: LNAs, filters, +attenuators, mixers, power amplifiers, gain compression, cascaded noise figure, +OIP3/IIP3, SFDR, dynamic range, or AM-AM/AM-PM behavior. Model each hardware +stage as a `Block`, create one `Input`, then call +`cascade_vector_return_vector` when intermediate stage outputs matter or +`cascade_vector_return_output` when only the final result matters. + +Do not use this crate for file-based S-parameter network analysis; use +`touchstone` for `.sNp` parsing and matrix/network-parameter work. Do not use it +for full radio-link BER/margin/orbit/Doppler questions; use `linkbudget` there. +Use `rfconversions` for standalone scalar conversions before building a chain. + +Keep the RF semantics straight: `gain_db` may be negative for losses, passive +losses should usually have matching positive `noise_figure_db`, P1dB and IP3 +fields are output-referred dBm values, and `Input::noise_temperature_k` is an +optional source/system temperature contribution rather than a block NF. + ## Commands ```bash From 057daeccb2a8f537b826bd08e42e996e37449164 Mon Sep 17 00:00:00 2001 From: Ian Cleary Date: Wed, 22 Jul 2026 14:52:37 +0000 Subject: [PATCH 2/3] docs: surface crate selection guidance --- README.md | 16 ++++++++++++++++ src/lib.rs | 5 +++++ 2 files changed, 21 insertions(+) diff --git a/README.md b/README.md index 78cd1d4..51eb2be 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,22 @@ RF signal chain (gain lineup) analysis for receiver and transmitter design. `gainlineup` models an RF signal chain as a sequence of blocks (amplifiers, filters, attenuators, mixers) and cascades their effects on signal power, noise, and linearity. Think of it as a spreadsheet-style RF lineup — but in Rust, with proper Friis equation cascading. +## When To Use This Crate + +Use `gainlineup` for ordered RF hardware chains: LNAs, filters, attenuators, +mixers, power amplifiers, cascaded gain/noise figure, P1dB compression, +IP3/IMD3, SFDR, dynamic range, and AM-AM/AM-PM behavior. + +If the task starts from `.sNp` S-parameter files or network matrices, use +`touchstone`. If it is an end-to-end communication link question involving +path loss, C/No, Eb/No, BER, margin, orbit, Doppler, PFD, or modulation, use +`linkbudget`. Use `rfconversions` for standalone scalar conversions before +building a chain. + +Model each hardware stage as a `Block`. Negative `gain_db` represents loss, and +passive losses usually have matching positive `noise_figure_db`. P1dB and IP3 +fields are output-referred dBm values. + ## Quick Start ### 1. Define Your Input Signal diff --git a/src/lib.rs b/src/lib.rs index 1948f90..45a525d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,6 +7,11 @@ //! IP3, dynamic range, and compression through a chain of RF blocks (amplifiers, //! attenuators, filters, mixers, etc.). //! +//! Use `gainlineup` for ordered RF hardware chains. Use `touchstone` for `.sNp` +//! S-parameter files and network matrices, `linkbudget` for end-to-end radio +//! link performance, and `rfconversions` for standalone scalar RF conversions. +//! P1dB and IP3 fields on [`Block`] are output-referred dBm values. +//! //! # Quick Start //! //! ``` From 3ccbc52b4e94c5fb569912912f059a136b582f6c Mon Sep 17 00:00:00 2001 From: Ian Cleary Date: Sun, 2 Aug 2026 17:23:54 +0000 Subject: [PATCH 3/3] fix: satisfy newer clippy formatting lints --- src/cli.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/cli.rs b/src/cli.rs index 9053435..f216b04 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -298,7 +298,7 @@ impl Command { let output_html_path = if file_path_config.unix_absolute_path || file_path_config.windows_absolute_path { - let mut file_path_html = format!("{}.html", &file_path); + let mut file_path_html = format!("{}.html", file_path); // Remove the UNC prefix on Windows if present if file_path_config.windows_absolute_path && file_path_html.starts_with(r"\\?\") { @@ -306,9 +306,9 @@ impl Command { } file_path_html } else if file_path_config.relative_path_with_separators { - format!("{}.html", &file_path) + format!("{}.html", file_path) } else if file_path_config.bare_filename { - format!("./{}.html", &file_path) + format!("./{}.html", file_path) } else { panic!( "file_path_config must have one true value: {:?}",