Enhance LAPLACE source support in SpiceSharpParser

- Renamed UnsupportedLaplaceOptions to InvalidLaplaceOptions and updated test cases to reflect new validation rules for LAPLACE options.
- Added tests for multiplier and delay functionality in LAPLACE sources, ensuring correct scaling and validation.
- Implemented scaling of numerator coefficients in LaplaceTransferFunction based on multiplier.
- Updated LaplaceSourceParser to handle multiplier and delay options, enforcing single-instance constraints and proper error handling.
- Revised documentation to clarify supported LAPLACE syntax and options, including multiplier and delay usage.

Author: marcin-golebiowski

roadmap/laplace-pspice-feasibility.md

@@ -68,18 +68,20 @@ This approach keeps the implementation small, aligns with existing source-genera
 
 ## Current Status
 
-`E`-source and `G`-source `LAPLACE` support is implemented by SpiceSharpParser for canonical assignment, no-equals expression-pair, and equals-after-keyword expression-pair syntax. `F`, `H`, `B`, function-like `VALUE={LAPLACE(...)}`, delay, and `M=` support remain deferred.
+`E`-source and `G`-source `LAPLACE` support is implemented by SpiceSharpParser for canonical assignment, no-equals expression-pair, and equals-after-keyword expression-pair syntax. Constant `M=`, `TD=`, and `DELAY=` options are implemented for those supported voltage-controlled forms. `F`, `H`, `B`, function-like `VALUE={LAPLACE(...)}`, and explicit internal-state options remain deferred.
 
 Phase 1 grammar groundwork is implemented: expression-to-expression assignments such as `{V(in)} = {1/(1+s*tau)}` and `{V(in1,in2)} = {1/(1+s*tau)}` are preserved as `ExpressionAssignmentParameter`.
 
 Phase 2 transfer-function math is implemented: internal polynomial, rational-polynomial, transfer-function, and expression-parser types convert rational expressions in `s` into ascending numerator / denominator coefficients with focused validation and broad unit coverage.
 
 Phase 3 `E`-source mapping is implemented: canonical `Ename out+ out- LAPLACE {V(ctrl)}` `= {H(s)}` and `V(ctrl+,ctrl-)` forms map to `LaplaceVoltageControlledVoltageSource`, produce reader validation errors for semantic failures, and have OP / AC integration coverage.
 
-Phase 4 `G`-source mapping is implemented: canonical `Gname out+ out- LAPLACE {V(ctrl)}` `= {H(s)}` and `V(ctrl+,ctrl-)` forms map to `LaplaceVoltageControlledCurrentSource`, preserve the existing `G` current-source sign convention, reject unsupported `M=` / delay options, and have OP / AC integration coverage.
+Phase 4 `G`-source mapping is implemented: canonical `Gname out+ out- LAPLACE {V(ctrl)}` `= {H(s)}` and `V(ctrl+,ctrl-)` forms map to `LaplaceVoltageControlledCurrentSource`, preserve the existing `G` current-source sign convention, support constant `M=` / delay options, and have OP / AC integration coverage.
 
 Phase 5 syntax compatibility is implemented: `E` / `G` sources accept `LAPLACE {V(...)} = {H(s)}`, `LAPLACE {V(...)} {H(s)}`, and `LAPLACE = {V(...)} {H(s)}` as equivalent voltage-controlled forms, while known deferred `VALUE={LAPLACE(...)}` and `B`-source forms produce targeted reader diagnostics.
 
+Phase 6 option and transient verification is implemented: supported `E` / `G` Laplace forms accept one constant `M=` multiplier and either `TD=` or `DELAY=` as a constant non-negative runtime delay parameter. Transient first-order step-response tests cover undelayed `E` / `G` low-pass behavior; delayed transient response shape is not currently claimed.
+
 Adjacent features already exist:
 
 - `VALUE={expr}` behavioral sources.
@@ -168,7 +170,7 @@ Input-expression subset:
 - Alternative `E` / `G` Laplace syntax variants that omit `=` or put `=` directly after `LAPLACE`.
 - `VALUE={LAPLACE(...)}` / function-like ABM forms.
 - Non-rational transfer expressions.
-- Explicit delay syntax such as `TD=` or `DELAY=`.
+- Explicit internal-state syntax.
 - Initial-condition syntax for Laplace internal state.
 - Generated C# writer support, unless the MVP delivery explicitly includes writer parity.
 
@@ -476,16 +478,18 @@ Prefer parsing with the existing expression parser and accepting only the expect
 
 Do not silently ignore `M=`.
 
-Recommended MVP behavior: reject `M=` on Laplace sources with a clear diagnostic until tests define the intended semantics. `M=` is a multiplier for the effective source or device contribution, typically equivalent to multiple parallel instances or a scaled current/voltage contribution. If support is added for Laplace sources, multiply the transfer output by `M`, most likely by evaluating `M` to a finite constant and scaling the numerator coefficients.
+Implemented behavior: accept one `M=` assignment on supported `E` / `G` Laplace sources. Evaluate `M` as a finite constant and scale the numerator coefficients, equivalent to putting the multiplier directly in `H(s)`.
 
 ### Delay Policy
 
-The runtime supports `Delay`, but PSpice delay syntax for Laplace sources needs confirmation.
+The runtime exposes `Delay`; SpiceSharpParser accepts one constant non-negative delay assignment on supported `E` / `G` Laplace sources and maps it to the runtime delay parameter.
 
-MVP behavior:
+Implemented behavior:
 
-- Set `Delay = 0.0`.
-- Reject `TD=`, `DELAY=`, or trailing delay-like parameters with a clear diagnostic.
+- `TD=<expr>` and `DELAY=<expr>` are aliases.
+- The expression must evaluate to a finite non-negative constant in seconds.
+- Only one delay option may be used.
+- Bare forms such as `TD 1n` remain unsupported.
 
 ## Diagnostics
 
@@ -503,8 +507,12 @@ laplace transfer function is improper; numerator degree exceeds denominator degr
 laplace transfer function has singular DC gain
 laplace transfer coefficients must be constant expressions
 laplace transfer expression reserves symbol 's'; use a different parameter name
-laplace delay syntax is not supported yet
-laplace multiplier M is not supported yet
+laplace delay must be a finite constant expression
+laplace delay must be non-negative
+laplace delay can be specified only once
+laplace multiplier M must be a finite constant expression
+laplace multiplier M can be specified only once
+laplace options must use assignment syntax
 laplace syntax variant is recognized but not supported yet
 laplace function-like VALUE form is not supported yet; use E/G LAPLACE {V(...)} = {H(s)}
 laplace source supports only E and G voltage-controlled forms in this version
@@ -527,8 +535,8 @@ Good diagnostics are part of compatibility. A precise rejection is better than f
 | `E ... LAPLACE {V(n1,n2)} = {H(s)}` | Support | Keep |
 | `G ... LAPLACE {V(n)} = {H(s)}` | Support | Keep |
 | `G ... LAPLACE {V(n1,n2)} = {H(s)}` | Support | Keep |
-| `E` / `G ... LAPLACE {V(n)} {H(s)}` | Targeted unsupported diagnostic until canonical form is stable | Add recognizer that lowers to the same model |
-| `E` / `G ... LAPLACE = {V(n)} {H(s)}` | Targeted unsupported diagnostic until canonical form is stable | Add recognizer that lowers to the same model |
+| `E` / `G ... LAPLACE {V(n)} {H(s)}` | Support | Keep |
+| `E` / `G ... LAPLACE = {V(n)} {H(s)}` | Support | Keep |
 | `F` / `H` current-controlled forms | Targeted unsupported diagnostic | Map to built-in current-controlled Laplace entities |
 | `B` source Laplace forms | Targeted unsupported diagnostic | Investigate PSpice ABM syntax |
 | `VALUE={LAPLACE(...)}` function-like form | Targeted unsupported diagnostic | Investigate as source-level special form |
@@ -537,8 +545,8 @@ Good diagnostics are part of compatibility. A precise rejection is better than f
 | Non-rational functions of `s` | Reject | Likely keep rejected |
 | Singular DC gain (`1/s`) | Reject unless verified safe | Possible AC-only or IC-aware mode |
 | Improper transfer (`deg N > deg D`) | Reject | Allow only if proven safe for claimed analyses |
-| Explicit delay | Reject | Map after syntax and behavior tests |
-| Transient | Verify before documenting | Document verified subset |
+| Explicit delay | Support `TD=` / `DELAY=` assignments on `E` / `G` | Other delay-like forms remain unsupported |
+| Transient | Verified for undelayed first-order `E` / `G` low-pass step responses | Delayed transient shape not currently claimed |
 | Generated C# writer | Defer or include as final polish | Emit built-in Laplace entities |
 
 ### PSpice Variants to Investigate Later
@@ -606,7 +614,7 @@ The last recognizer is deliberate. If a user writes a known PSpice Laplace varia
 | Current-controlled | `F1 out 0 LAPLACE {I(Vsense)} = {H(s)}` | Later milestone | Runtime entities exist, but controlling-source parsing and PSpice compatibility need tests. |
 | Function-like `VALUE` | `E1 out 0 VALUE = {LAPLACE(V(in), H(s))}` | Investigate later | Must be handled as source-level Laplace, not a scalar expression function. |
 | `B` source ABM | `B1 out 0 V = {LAPLACE(V(in), H(s))}` | Investigate later | May require arbitrary input-expression lowering or custom behavior. |
-| Delay/options | `TD=...`, `DELAY=...` | Reject initially | Runtime has `Delay`; PSpice syntax and semantics need confirmation. |
+| Delay/options | `TD=...`, `DELAY=...`, `M=...` | Supported for `E` / `G` voltage-controlled forms | Values must be constant; only one delay option may be used. |
 
 ### Normalization Rules
 
@@ -669,7 +677,7 @@ Status: implemented for canonical `E` source syntax.
 
 ### Phase 4: `G` Source Mapping
 
-Status: implemented for canonical `G` source syntax. `M=`, delay options, `F`, and `H` remain deferred.
+Status: implemented for canonical `G` source syntax and constant `M=` / delay options. `F` and `H` remain deferred.
 
 1. Detect `LAPLACE` in `CurrentSourceGenerator.CreateCustomCurrentSource(...)`.
 2. Reuse the same source parser and transfer-function builder.
@@ -678,7 +686,7 @@ Status: implemented for canonical `G` source syntax. `M=`, delay options, `F`, a
 
 ### Phase 5: Syntax Compatibility Layer
 
-Status: implemented for `E` / `G` no-equals and equals-after-keyword voltage-controlled syntax. `VALUE={LAPLACE(...)}`, `B`, `F`, `H`, `M=`, and delay options remain diagnostic-only / deferred.
+Status: implemented for `E` / `G` no-equals and equals-after-keyword voltage-controlled syntax. `VALUE={LAPLACE(...)}`, `B`, `F`, and `H` remain diagnostic-only / deferred.
 
 1. Add `UnsupportedKnownVariantRecognizer` so common deferred forms receive targeted diagnostics.
 2. Add `NoEqualsExpressionPairRecognizer` for `LAPLACE {input} {transfer}` only after canonical tests pass.
@@ -750,7 +758,7 @@ Place near [src/SpiceSharpParser.Tests/Parsers](../src/SpiceSharpParser.Tests/Pa
 - Missing transfer expression.
 - Unsupported `F`, `H`, and `B` forms.
 - Unsupported arbitrary input expression.
-- Unsupported delay and `M=` parameters.
+- Supported `M=`, `TD=`, and `DELAY=` parameters plus invalid duplicate / non-finite / negative option diagnostics.
 
 ### Compatibility Matrix Tests
 

src/SpiceSharpParser.IntegrationTests/AnalogBehavioralModeling/LaplaceTests.cs

@@ -30,13 +30,14 @@ public static IEnumerable<object[]> RejectedLaplaceTransfers
             }
         }
 
-        public static IEnumerable<object[]> UnsupportedLaplaceOptions
+        public static IEnumerable<object[]> InvalidLaplaceOptions
         {
             get
             {
-                yield return new object[] { "M=2", "multiplier" };
-                yield return new object[] { "TD=1n", "delay" };
-                yield return new object[] { "DELAY=1n", "delay" };
+                yield return new object[] { "M=2 M=3", "only once" };
+                yield return new object[] { "TD=1n TD=2n", "only once" };
+                yield return new object[] { "TD=1n DELAY=2n", "only once" };
+                yield return new object[] { "TD=-1n", "non-negative" };
             }
         }
 
@@ -104,6 +105,25 @@ public void When_ELaplaceNoEqualsSyntaxRunsOp_Expect_DcGainNearOne()
             Assert.True(EqualsWithTol(1.0, export), $"Expected OP gain near 1, got {export}.");
         }
 
+        [Fact]
+        public void When_ELaplaceMultiplierRunsOp_Expect_DcGainScaled()
+        {
+            var model = GetSpiceSharpModel(
+                "E LAPLACE multiplier OP",
+                ".PARAM tau=1u",
+                "VIN in 0 1",
+                "ELOW out 0 LAPLACE {V(in)} = {1/(1+s*tau)} M=2",
+                "RLOAD out 0 1k",
+                ".OP",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(model);
+
+            double export = RunOpSimulation(model, "V(out)");
+            Assert.True(EqualsWithTol(2.0, export), $"Expected OP gain near 2, got {export}.");
+        }
+
         [Fact]
         public void When_ELaplaceLowPassRunsAcAtCutoff_Expect_ExpectedMagnitudeAndPhase()
         {
@@ -225,6 +245,26 @@ public void When_GLaplaceEqualsAfterKeywordSyntaxRunsOp_Expect_LoadVoltageWithCu
             Assert.True(EqualsWithTol(-1.0, export), $"Expected OP load voltage near -1, got {export}.");
         }
 
+        [Fact]
+        public void When_GLaplaceMultiplierRunsOp_Expect_LoadVoltageScaled()
+        {
+            var model = GetSpiceSharpModel(
+                "G LAPLACE multiplier OP",
+                ".PARAM gm=1m",
+                ".PARAM tau=1u",
+                "VIN in 0 1",
+                "GLOW out 0 LAPLACE {V(in)} = {gm/(1+s*tau)} M=2",
+                "RLOAD out 0 1k",
+                ".OP",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(model);
+
+            double export = RunOpSimulation(model, "V(out)");
+            Assert.True(EqualsWithTol(-2.0, export), $"Expected OP load voltage near -2, got {export}.");
+        }
+
         [Fact]
         public void When_GLaplaceLowPassRunsAcAtCutoff_Expect_ExpectedMagnitudeAndPhase()
         {
@@ -305,6 +345,97 @@ public void When_ELaplaceIsMixedWithExistingAbmSources_Expect_AllOutputs()
             Assert.True(EqualsWithTol(exports, new[] { 3.0, 4.0, 5.0, 2.0 }));
         }
 
+        [Fact]
+        public void When_ELaplaceDelayOptionsRunOp_Expect_ValidCircuit()
+        {
+            var tdModel = GetSpiceSharpModel(
+                "E LAPLACE TD OP",
+                "VIN in 0 1",
+                "ETD out 0 LAPLACE {V(in)} = {1/(1+s*1u)} TD=1n",
+                "RLOAD out 0 1k",
+                ".OP",
+                ".SAVE V(out)",
+                ".END");
+
+            var delayModel = GetSpiceSharpModel(
+                "E LAPLACE DELAY OP",
+                "VIN in 0 1",
+                "EDELAY out 0 LAPLACE {V(in)} = {1/(1+s*1u)} DELAY=1n",
+                "RLOAD out 0 1k",
+                ".OP",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(tdModel);
+            AssertNoValidationErrors(delayModel);
+            Assert.True(EqualsWithTol(1.0, RunOpSimulation(tdModel, "V(out)")));
+            Assert.True(EqualsWithTol(1.0, RunOpSimulation(delayModel, "V(out)")));
+        }
+
+        [Fact]
+        public void When_ELaplaceLowPassRunsTransient_Expect_FirstOrderStepResponse()
+        {
+            const double tau = 1e-6;
+            var model = GetSpiceSharpModel(
+                "E LAPLACE low-pass TRAN",
+                ".PARAM tau=1u",
+                "VIN in 0 PULSE(0 1 0 1n 1n 100u 200u)",
+                "ELOW out 0 LAPLACE {V(in)} = {1/(1+s*tau)}",
+                "RLOAD out 0 1k",
+                ".TRAN 50n 8u",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(model);
+
+            var exports = RunTransientSimulation(model, "V(out)");
+            AssertTransientPoint(exports, 1.0 * tau, FirstOrderStep(1.0), 0.06);
+            AssertTransientPoint(exports, 2.0 * tau, FirstOrderStep(2.0), 0.06);
+            AssertTransientPoint(exports, 5.0 * tau, FirstOrderStep(5.0), 0.04);
+        }
+
+        [Fact]
+        public void When_GLaplaceLowPassRunsTransient_Expect_FirstOrderStepResponseWithCurrentSourceSign()
+        {
+            const double tau = 1e-6;
+            var model = GetSpiceSharpModel(
+                "G LAPLACE low-pass TRAN",
+                ".PARAM tau=1u",
+                ".PARAM gm=1m",
+                "VIN in 0 PULSE(0 1 0 1n 1n 100u 200u)",
+                "GLOW out 0 LAPLACE {V(in)} = {gm/(1+s*tau)}",
+                "RLOAD out 0 1k",
+                ".TRAN 50n 8u",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(model);
+
+            var exports = RunTransientSimulation(model, "V(out)");
+            AssertTransientPoint(exports, 1.0 * tau, -FirstOrderStep(1.0), 0.06);
+            AssertTransientPoint(exports, 2.0 * tau, -FirstOrderStep(2.0), 0.06);
+            AssertTransientPoint(exports, 5.0 * tau, -FirstOrderStep(5.0), 0.04);
+        }
+
+        [Fact]
+        public void When_ELaplaceDelayedLowPassRunsTransient_Expect_NoRuntimeException()
+        {
+            var model = GetSpiceSharpModel(
+                "E LAPLACE delayed low-pass TRAN",
+                ".PARAM tau=1u",
+                "VIN in 0 PULSE(0 1 0 1n 1n 100u 200u)",
+                "ELOW out 0 LAPLACE {V(in)} = {1/(1+s*tau)} TD=2u",
+                "RLOAD out 0 1k",
+                ".TRAN 50n 8u",
+                ".SAVE V(out)",
+                ".END");
+
+            AssertNoValidationErrors(model);
+
+            var exception = Record.Exception(() => RunTransientSimulation(model, "V(out)"));
+            Assert.Null(exception);
+        }
+
         [Theory]
         [MemberData(nameof(InvalidLaplaceInputs))]
         public void When_ELaplaceInputIsInvalid_Expect_ReaderValidationError(
@@ -328,13 +459,13 @@ public void When_ELaplaceTransferIsRejected_Expect_ReaderValidationError(
         }
 
         [Theory]
-        [MemberData(nameof(UnsupportedLaplaceOptions))]
-        public void When_ELaplaceUnsupportedOptionIsUsed_Expect_ReaderValidationError(
+        [MemberData(nameof(InvalidLaplaceOptions))]
+        public void When_ELaplaceInvalidOptionIsUsed_Expect_ReaderValidationError(
             string option,
             string expectedMessage)
         {
             var model = GetSpiceSharpModel(
-                "E LAPLACE unsupported option",
+                "E LAPLACE invalid option",
                 "VIN in 0 1",
                 $"EBAD out 0 LAPLACE {{V(in)}} = {{1/(1+s)}} {option}",
                 "RLOAD out 0 1k",
@@ -345,21 +476,6 @@ public void When_ELaplaceUnsupportedOptionIsUsed_Expect_ReaderValidationError(
             AssertReaderErrorContains(model, expectedMessage);
         }
 
-        [Fact]
-        public void When_GLaplaceUnsupportedMultiplierIsUsed_Expect_ReaderValidationError()
-        {
-            var model = GetSpiceSharpModel(
-                "G LAPLACE unsupported multiplier",
-                "VIN in 0 1",
-                "GBAD out 0 LAPLACE {V(in)} = {1/(1+s)} M=2",
-                "RLOAD out 0 1k",
-                ".OP",
-                ".SAVE V(out)",
-                ".END");
-
-            AssertReaderErrorContains(model, "multiplier");
-        }
-
         [Fact]
         public void When_ValueLaplaceFunctionIsUsed_Expect_ReaderValidationError()
         {
@@ -432,5 +548,22 @@ private static void AssertReaderErrorContains(SpiceSharpModel model, string expe
             var messages = string.Join(Environment.NewLine, model.ValidationResult.Errors.Select(error => error.Message));
             Assert.Contains(expectedMessage, messages, StringComparison.OrdinalIgnoreCase);
         }
+
+        private static void AssertTransientPoint(
+            IReadOnlyList<Tuple<double, double>> exports,
+            double time,
+            double expected,
+            double tolerance)
+        {
+            var nearest = exports.OrderBy(export => Math.Abs(export.Item1 - time)).First();
+            Assert.True(
+                Math.Abs(nearest.Item2 - expected) <= tolerance,
+                $"Expected V(out) near {expected} at {time}, got {nearest.Item2} at {nearest.Item1}.");
+        }
+
+        private static double FirstOrderStep(double normalizedTime)
+        {
+            return 1.0 - Math.Exp(-normalizedTime);
+        }
     }
 }