Docs update

Author: marcin-golebiowski

roadmap/ltspice-compatibility-matrix.md

@@ -1,6 +1,6 @@
 ---
 title: LTspice Compatibility Matrix
-status: P3 Baseline + .FOUR Support Refresh + Custom Passives + Ideal Diodes + Golden Evidence + Include/Lib Path Evidence
+status: P3 Baseline + .FOUR Support Refresh + Custom Passives + Ideal Diodes + Golden Evidence + Include/Lib Path Evidence + Waveform Docs Refresh
 scope: SpiceSharpParser + SpiceSharp
 last_reviewed: 2026-07-04
 ---
@@ -58,7 +58,7 @@ Compatibility classes:
 | `PULSE(... Ncycles)` | Accepted in LTspice mode | Produces finite-cycle pulse waveform | TRAN supported | Analytic transient fixture | Invalid period or cycle count produces targeted `PULSE` diagnostic | Current parser/runtime | The eighth LTspice argument limits the waveform to `Ncycles` periods, then returns to the initial value. |
 | `SINE(... Ncycles)` | Accepted | Rejected in LTspice mode | Not runnable | None | Targeted LTspice `SINE` cycle-count diagnostic | Current parser/runtime | Finite-cycle waveform behavior is deferred. |
 | Independent source `tbl=(expr,x1,y1,...)` | Accepted in LTspice mode | Lowered to behavioral `table(...)` source | OP supported | Analytic fixture | Invalid form names `tbl` | Current parser/runtime | Parser shim uses the existing source/table expression path. |
-| Source `wavefile=<path> chan=<n> [amplitude=<value>]` | Accepted | Produces wave-file waveform | Existing wave-file behavior | Smoke/diagnostic fixture | Missing `chan` and missing file produce targeted validation | Current parser/runtime | Channel defaults are not inferred. |
+| Source `wavefile=<path> chan=<n> [amplitude=<value>]` | Accepted | Produces wave-file waveform | Existing wave-file behavior | Smoke/diagnostic fixture | Missing `wavefile`, missing `chan`, missing file, and invalid `chan` produce targeted validation | Current parser/runtime | Channel defaults are not inferred. |
 | Source `Rser`, `Cpar`, `load`, `R=<value>` | Accepted | Rejected in LTspice mode | Not runnable | None | Targeted LTspice source-option error names option | Current parser/runtime | Topology-changing source options are not synthesized. |
 | R/C model `tc=a[,b]` | Accepted | Lowered to `tc1` / `tc2` | Existing R/C model behavior | Read fixture | None expected in LTspice mode | Current parser/runtime | Parser shim only; coefficients beyond two are rejected. |
 | LTspice metadata/rating parameters `mfg`, `manufacturer`, `pn`, `part`, `desc`, `description`, `V`, `Irms`, `Ipk` | Accepted | Warning no-op in LTspice mode | No runtime effect | Diagnostic fixture | Default: existing parameter error. LTspice: warning names parameter. | Current parser/runtime | BOM/layout metadata is not used by SpiceSharpParser. |

roadmap/ltspice-netlist-compatibility-plan.md

@@ -213,7 +213,7 @@ Implemented P2 behavior:
 - Added six-argument `EXP(v1 v2 td1 tau1 td2 tau2)` source waveform support with argument-count and positive-tau diagnostics.
 - Added LTspice-mode finite-cycle `PULSE(... Ncycles)` support and targeted diagnostics for unsupported finite-cycle `SINE` arguments.
 - Added LTspice-mode `tbl=(expr,x1,y1,...)` independent-source lowering to the existing behavioral `table(...)` path.
-- Improved `wavefile=<path> chan=<n> [amplitude=<value>]` validation so missing `chan` and missing files produce targeted diagnostics.
+- Improved `wavefile=<path> chan=<n> [amplitude=<value>]` validation so missing `wavefile`, missing `chan`, missing files, and invalid `chan` values produce targeted diagnostics.
 - Added LTspice-mode targeted diagnostics for topology-changing source options `Rser`, `Cpar`, `load`, and `R=<value>`.
 
 Remaining follow-up:

src/SpiceSharpParser.IntegrationTests/LTspiceCompatibility/LTspiceCompatibilityP2Tests.cs

@@ -1,4 +1,5 @@
 using System;
+using System.IO;
 using System.Linq;
 using System.Text;
 using SpiceSharpParser.Common;
@@ -82,6 +83,52 @@ public void When_LtspiceSourceOptionChangesTopology_Expect_TargetedError(string
             AssertErrorContains(model.ValidationResult, optionName);
         }
 
+        [Theory]
+        [InlineData("V1 out 0 WAVE chan=1", "wavefile")]
+        [InlineData("V1 out 0 wavefile=\"missing.wav\"", "chan")]
+        [InlineData("V1 out 0 wavefile=\"missing.wav\" chan=1", "does not exist")]
+        public void When_LtspiceWaveFileSourceIsInvalid_Expect_TargetedError(string sourceLine, string expectedMessage)
+        {
+            var model = GetSpiceSharpModelWithCompatibility(
+                CompatibilityOptions.LTspice,
+                "LTspice P2 - invalid wavefile",
+                sourceLine,
+                "R1 out 0 1k",
+                ".tran 1n 6n",
+                ".save V(out)",
+                ".end");
+
+            Assert.True(model.ValidationResult.HasError);
+            AssertErrorContains(model.ValidationResult, "wavefile");
+            AssertErrorContains(model.ValidationResult, expectedMessage);
+        }
+
+        [Fact]
+        public void When_LtspiceWaveFileChannelIsInvalid_Expect_TargetedError()
+        {
+            var waveFilePath = Path.GetTempFileName();
+
+            try
+            {
+                var model = GetSpiceSharpModelWithCompatibility(
+                    CompatibilityOptions.LTspice,
+                    "LTspice P2 - invalid wavefile channel",
+                    $"V1 out 0 wavefile=\"{waveFilePath}\" chan=bad",
+                    "R1 out 0 1k",
+                    ".tran 1n 6n",
+                    ".save V(out)",
+                    ".end");
+
+                Assert.True(model.ValidationResult.HasError);
+                AssertErrorContains(model.ValidationResult, "wavefile");
+                AssertErrorContains(model.ValidationResult, "chan");
+            }
+            finally
+            {
+                File.Delete(waveFilePath);
+            }
+        }
+
         [Theory]
         [InlineData("V1 out 0 SINE(0 1 1k 0 0 0 3)", "SINE")]
         public void When_LtspiceWaveformHasCycleCount_Expect_TargetedError(string sourceLine, string waveformName)

src/docs/articles/current-source.md

@@ -13,7 +13,7 @@ I<name> <node+> <node-> [DC <dc_value>] [AC <mag> [<phase>]] [<waveform>] [M=<m>
 | `node+`, `node-` | Current flows from node+ through the source to node- |
 | `DC <value>` | DC current value |
 | `AC <mag> [phase]` | AC magnitude and phase |
-| `waveform` | Time-domain waveform (PULSE, SIN, PWL, SFFM, AM) |
+| `waveform` | Time-domain waveform (`PULSE`, `SIN` / `SINE`, `EXP`, `PWL`, `SFFM`, `AM`, wave-file input) |
 | `M=m` | Multiplier (equivalent to m parallel sources) |
 
 ## Examples
@@ -41,11 +41,15 @@ Current sources support the same waveform types as voltage sources:
 
 - `PULSE` — Rectangular pulse train
 - `SIN` / `SINE` — Sinusoidal
+- `EXP` — Exponential rise/fall
 - `PWL` — Piecewise linear
 - `SFFM` — Single-frequency FM
 - `AM` — Amplitude modulation
+- `wavefile=<path> chan=<n> [amplitude=<scale>]` / `WAVE` — Wave-file input
 
-See the [V — Voltage Source](voltage-source.md) article for waveform syntax details.
+See the [V — Voltage Source](voltage-source.md) article for waveform syntax,
+LTspice finite-cycle `PULSE`, unsupported finite-cycle `SINE`, wave-file
+diagnostics, and LTspice source-option notes.
 
 ## Behavioral Current Source
 

src/docs/articles/tran.md

@@ -62,9 +62,12 @@ Transient analysis is typically paired with time-domain sources:
 ```spice
 V1 IN 0 PULSE(0 5 0 10n 10n 500u 1m)
 V2 SIG 0 SIN(0 1 1k)
+V3 EDGE 0 EXP(0 5 1u 100n 10u 200n)
 ```
 
-See the individual waveform documentation for `PULSE`, `SIN`, `PWL`, `SFFM`, and `AM`.
+See the [voltage-source waveform documentation](voltage-source.md#waveform-types)
+for `PULSE`, `SIN` / `SINE`, `EXP`, `PWL`, `SFFM`, `AM`, wave-file input,
+and LTspice compatibility notes.
 
 ## MNA View
 

src/docs/articles/voltage-source.md

@@ -31,37 +31,73 @@ V1 IN 0 AC 1
 
 ## Waveform Types
 
+Waveforms can be written in function form, for example `PULSE(...)`, or as a
+waveform name followed by parameters, for example `PULSE 0 5 0 1n 1n 5u 10u`.
+The same waveform syntax is available on independent current sources.
+
 ### PULSE — Rectangular Pulse Train
 
 ```
 PULSE(<v1> <v2> <delay> <rise> <fall> <pulse_width> <period>)
+PULSE(<v1> <v2> <delay> <rise> <fall> <pulse_width> <period> <Ncycles>)
 ```
 
 ```spice
 V1 IN 0 PULSE(0 5 0 10n 10n 500u 1m)
+V2 GATE 0 PULSE(0 1 2n 1n 1n 3n 10n 2)
 ```
 
-### SIN — Sinusoidal
+The seven-argument form is the normal repeating pulse train. The eight-argument
+LTspice finite-cycle form is available only when `CompatibilityOptions.LTspice`
+is enabled. In that mode, `<Ncycles>` limits the source to that many periods and
+then returns it to `<v1>`. The period and cycle count must be positive.
+
+### SIN / SINE — Sinusoidal
 
 ```
 SIN(<offset> <amplitude> <frequency> [<delay> [<damping> [<phase>]]])
+SINE(<offset> <amplitude> <frequency> [<delay> [<damping> [<phase>]]])
 ```
 
 ```spice
 V1 IN 0 SIN(0 1 1k)
 V2 SIG 0 SIN(2.5 2.5 60 0 0 0)
 ```
 
+LTspice finite-cycle `SINE` arguments are recognized in LTspice compatibility
+mode, but they are not mapped yet and produce a targeted validation error.
+
+### EXP — Exponential Rise/Fall
+
+```
+EXP(<v1> <v2> <td1> <tau1> <td2> <tau2>)
+```
+
+```spice
+V1 IN 0 EXP(0 5 1u 100n 10u 200n)
+```
+
+`EXP` starts at `<v1>`, rises toward `<v2>` after `<td1>` with time constant
+`<tau1>`, and falls back toward `<v1>` after `<td2>` with time constant
+`<tau2>`. Both time constants must be positive.
+
 ### PWL — Piecewise Linear
 
 ```
-PWL(<t1> <v1> <t2> <v2> ... [repeat])
+PWL(<t1> <v1> <t2> <v2> ...)
+PWL file = "<path>"
 ```
 
 ```spice
 V1 IN 0 PWL(0 0 1m 5 2m 5 3m 0)
+V2 IN 0 PWL file = "Resources\pwl_reference.txt"
 ```
 
+Inline PWL data uses time/value pairs. File-backed PWL data reads a local text
+file with a header row followed by two numeric columns; spaces, commas,
+semicolons, and tabs are recognized from the first line. Broader LTspice PWL
+file and repeat variants are not claimed yet.
+
 ### SFFM — Single-Frequency FM
 
 ```
@@ -74,7 +110,44 @@ V1 IN 0 SFFM(0 1 1k 5 100)
 
 ### AM — Amplitude Modulation
 
-Available for amplitude-modulated waveforms.
+```
+AM(<amplitude> <offset> <modulation_freq> <carrier_freq> [<delay> [<carrier_phase> [<signal_phase>]]])
+```
+
+```spice
+V1 IN 0 AM(1 0 100 10k 0 0 0)
+```
+
+### Wave-File Input
+
+```
+wavefile=<path> chan=<n> [amplitude=<scale>]
+WAVE wavefile=<path> chan=<n> [amplitude=<scale>]
+```
+
+```spice
+V1 IN 0 wavefile="input.wav" chan=0 amplitude=0.5
+V2 IN 0 WAVE wavefile="input.wav" chan=1
+```
+
+Wave-file input converts the selected audio channel to a PWL waveform. The
+channel must be explicit; LTspice channel defaults are not inferred. Missing
+`wavefile=`, missing `chan=`, missing files, and invalid channel expressions
+produce targeted validation diagnostics.
+
+## LTspice Source Compatibility
+
+With `CompatibilityOptions.LTspice`, independent sources also support
+`tbl=(expr,x1,y1,...)`, which is lowered to the existing behavioral
+`table(...)` expression path:
+
+```spice
+V1 OUT 0 tbl=(V(IN), 0,0, 1,5)
+```
+
+Topology-changing LTspice source options such as `Rser`, `Cpar`, `load`, and
+`R=<value>` are recognized as unsupported and reported with targeted errors.
+They are not silently ignored or synthesized into extra components.
 
 ## Behavioral Voltage Source