Add CircuitBuilder, StandardValues, and NetlistLinter for enhanced SPICE netlist handling

- Implemented CircuitBuilder for programmatic construction of SPICE netlists, allowing for easy addition and modification of circuit components, sources, and analyses.
- Introduced StandardValues utility to provide standard electronic component value series (E12, E24, E96) and methods for snapping calculated values to the nearest standard value.
- Developed NetlistLinter for pre-simulation structural validation of SpiceSharp circuit models, detecting common errors such as missing models, duplicate components, and ensuring DC paths to ground.

Author: marcin-golebiowski

src/SpiceSharpParser.Tests/Analysis/WaveformAnalyzerTests.cs

@@ -0,0 +1,188 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using SpiceSharpParser.Analysis;
+using Xunit;
+
+namespace SpiceSharpParser.Tests.Analysis
+{
+    public class WaveformAnalyzerTests
+    {
+        [Fact]
+        public void Average_SineWave_ReturnsOffset()
+        {
+            // Full cycle of sine with DC offset of 2
+            var data = new List<(double Time, double Value)>();
+            for (int i = 0; i <= 1000; i++)
+            {
+                double t = i / 1000.0;
+                data.Add((t, 2.0 + Math.Sin(2 * Math.PI * t)));
+            }
+
+            double avg = WaveformAnalyzer.Average(data);
+            Assert.InRange(avg, 1.99, 2.01);
+        }
+
+        [Fact]
+        public void RMS_SineWave_ReturnsExpected()
+        {
+            // RMS of sin(t) = amplitude / sqrt(2)
+            double amplitude = 3.0;
+            var data = new List<(double Time, double Value)>();
+            for (int i = 0; i <= 10000; i++)
+            {
+                double t = i / 10000.0;
+                data.Add((t, amplitude * Math.Sin(2 * Math.PI * t)));
+            }
+
+            double rms = WaveformAnalyzer.RMS(data);
+            double expected = amplitude / Math.Sqrt(2);
+            Assert.InRange(rms, expected * 0.99, expected * 1.01);
+        }
+
+        [Fact]
+        public void PeakToPeak_ReturnsCorrectRange()
+        {
+            var data = new List<(double Time, double Value)>
+            {
+                (0, 1), (1, 5), (2, -3), (3, 2),
+            };
+
+            double pp = WaveformAnalyzer.PeakToPeak(data);
+            Assert.Equal(8, pp, 6);
+        }
+
+        [Fact]
+        public void PeakToPeak_WithWindow_FiltersCorrectly()
+        {
+            var data = new List<(double Time, double Value)>
+            {
+                (0, 100), (1, 1), (2, 5), (3, 2), (4, -100),
+            };
+
+            double pp = WaveformAnalyzer.PeakToPeak(data, fromTime: 0.5, toTime: 3.5);
+            Assert.Equal(4, pp, 6); // 5 - 1
+        }
+
+        [Fact]
+        public void RiseTime_StepResponse_ReturnsCorrectTime()
+        {
+            // Simulate a step response: 0 to 1 with a linear ramp from t=1 to t=3
+            var data = new List<(double Time, double Value)>();
+            for (int i = 0; i <= 100; i++)
+            {
+                double t = i * 0.05; // 0 to 5
+                double v = t < 1.0 ? 0.0 : (t > 3.0 ? 1.0 : (t - 1.0) / 2.0);
+                data.Add((t, v));
+            }
+
+            double rt = WaveformAnalyzer.RiseTime(data);
+            // 10% of range = 0.1, 90% = 0.9
+            // Time at 0.1 = 1.0 + 0.1*2 = 1.2
+            // Time at 0.9 = 1.0 + 0.9*2 = 2.8
+            // Rise time = 2.8 - 1.2 = 1.6
+            Assert.InRange(rt, 1.5, 1.7);
+        }
+
+        [Fact]
+        public void SettlingTime_ReturnsCorrectTime()
+        {
+            // Step response that overshoots then settles at 1.0
+            var data = new List<(double Time, double Value)>
+            {
+                (0, 0), (1, 1.3), (2, 0.95), (3, 1.02), (4, 0.99), (5, 1.0),
+            };
+
+            double st = WaveformAnalyzer.SettlingTime(data, 1.0, 0.05); // ±5%
+            Assert.InRange(st, 2, 4); // Should settle around t=2-3
+        }
+
+        [Fact]
+        public void Overshoot_ReturnsCorrectPercentage()
+        {
+            var data = new List<(double Time, double Value)>
+            {
+                (0, 0), (1, 1.2), (2, 1.0),
+            };
+
+            double os = WaveformAnalyzer.Overshoot(data, 1.0);
+            Assert.Equal(20.0, os, 6);
+        }
+
+        [Fact]
+        public void InterpolateAt_LinearData_ReturnsCorrectValue()
+        {
+            var data = new List<(double X, double Y)>
+            {
+                (0, 0), (1, 10), (2, 20),
+            };
+
+            Assert.Equal(5, WaveformAnalyzer.InterpolateAt(data, 0.5), 6);
+            Assert.Equal(15, WaveformAnalyzer.InterpolateAt(data, 1.5), 6);
+        }
+
+        [Fact]
+        public void FindCrossing_ReturnsCorrectX()
+        {
+            var data = new List<(double X, double Y)>
+            {
+                (0, 0), (1, 2), (2, 4), (3, 2), (4, 0),
+            };
+
+            double crossing = WaveformAnalyzer.FindCrossing(data, 3.0, occurrence: 1);
+            Assert.InRange(crossing, 1.4, 1.6); // 3.0 is between (1,2) and (2,4)
+        }
+
+        [Fact]
+        public void BandwidthFrom3dBPoints_LowPassFilter_ReturnsCorrectBW()
+        {
+            // Simulate a low-pass filter response: flat at 0dB, rolling off at 1kHz
+            var data = new List<(double Freq, double GainDb)>();
+            for (double f = 1; f <= 100000; f *= 1.1)
+            {
+                double gainDb = -10 * Math.Log10(1 + Math.Pow(f / 1000, 2));
+                data.Add((f, gainDb));
+            }
+
+            double bw = WaveformAnalyzer.BandwidthFrom3dBPoints(data);
+            Assert.InRange(bw, 900, 1100); // Should be ~1kHz
+        }
+
+        [Fact]
+        public void FFT_PureSine_HasSinglePeak()
+        {
+            // Generate a 100Hz sine sampled at 1kHz for 1 second
+            var data = new List<(double Time, double Value)>();
+            int samples = 1024;
+            double sampleRate = 1000.0;
+            for (int i = 0; i < samples; i++)
+            {
+                double t = i / sampleRate;
+                data.Add((t, Math.Sin(2 * Math.PI * 100 * t)));
+            }
+
+            var spectrum = WaveformAnalyzer.FFT(data);
+            Assert.True(spectrum.Count > 0);
+
+            // Find peak (excluding DC)
+            var peak = spectrum.Skip(1).OrderByDescending(s => s.Magnitude).First();
+            Assert.InRange(peak.Frequency, 95, 105); // Should be near 100Hz
+        }
+
+        [Fact]
+        public void THD_PureSine_NearZero()
+        {
+            var data = new List<(double Time, double Value)>();
+            int samples = 4096;
+            double sampleRate = 10000.0;
+            for (int i = 0; i < samples; i++)
+            {
+                double t = i / sampleRate;
+                data.Add((t, Math.Sin(2 * Math.PI * 100 * t)));
+            }
+
+            double thd = WaveformAnalyzer.THD(data, 100);
+            Assert.InRange(thd, 0, 1.0); // Should be near 0% for pure sine
+        }
+    }
+}

src/SpiceSharpParser.Tests/Builder/CircuitBuilderTests.cs

@@ -0,0 +1,135 @@
+using SpiceSharpParser.Builder;
+using Xunit;
+
+namespace SpiceSharpParser.Tests.Builder
+{
+    public class CircuitBuilderTests
+    {
+        [Fact]
+        public void ToNetlist_SimpleRC_GeneratesValidNetlist()
+        {
+            var netlist = CircuitBuilder.Create("RC Filter")
+                .VoltageSource("V1", "in", "0", dc: 5)
+                .Resistor("R1", "in", "out", 1000)
+                .Capacitor("C1", "out", "0", 1e-6)
+                .OP()
+                .Save("V(out)")
+                .ToNetlist();
+
+            Assert.Contains("RC Filter", netlist);
+            Assert.Contains("V1", netlist);
+            Assert.Contains("R1 in out 1k", netlist);
+            Assert.Contains("C1 out 0 1u", netlist);
+            Assert.Contains(".OP", netlist);
+            Assert.Contains(".SAVE V(out)", netlist);
+            Assert.Contains(".END", netlist);
+        }
+
+        [Fact]
+        public void Build_SimpleRC_ParsesSuccessfully()
+        {
+            var model = CircuitBuilder.Create("RC OP Test")
+                .VoltageSource("V1", "in", "0", dc: 10)
+                .Resistor("R1", "in", "out", 1000)
+                .Resistor("R2", "out", "0", 1000)
+                .OP()
+                .Save("V(out)")
+                .Build();
+
+            Assert.NotNull(model);
+            Assert.False(model.ValidationResult.HasError);
+            Assert.NotNull(model.Circuit);
+            Assert.True(model.Simulations.Count > 0);
+        }
+
+        [Fact]
+        public void SetValue_ModifiesComponent()
+        {
+            var builder = CircuitBuilder.Create("Test")
+                .VoltageSource("V1", "in", "0", dc: 5)
+                .Resistor("R1", "in", "out", 1000)
+                .Resistor("R2", "out", "0", 2000);
+
+            var netlistBefore = builder.ToNetlist();
+            Assert.Contains("R1 in out 1k", netlistBefore);
+
+            builder.SetValue("R1", 2200);
+            var netlistAfter = builder.ToNetlist();
+            Assert.Contains("R1 in out 2.2k", netlistAfter);
+        }
+
+        [Fact]
+        public void RemoveComponent_RemovesFromNetlist()
+        {
+            var builder = CircuitBuilder.Create("Test")
+                .VoltageSource("V1", "in", "0", dc: 5)
+                .Resistor("R1", "in", "out", 1000)
+                .Resistor("R2", "out", "0", 2000);
+
+            builder.RemoveComponent("R1");
+            var netlist = builder.ToNetlist();
+            Assert.DoesNotContain("R1", netlist);
+            Assert.Contains("R2", netlist);
+        }
+
+        [Fact]
+        public void AC_GeneratesCorrectStatement()
+        {
+            var netlist = CircuitBuilder.Create("AC Test")
+                .VoltageSource("V1", "in", "0", ac: 1)
+                .Resistor("R1", "in", "out", 1000)
+                .Capacitor("C1", "out", "0", 1e-9)
+                .AC("DEC", 10, 1, 1e6)
+                .Save("VDB(out)")
+                .ToNetlist();
+
+            Assert.Contains(".AC DEC 10 1 1MEG", netlist);
+        }
+
+        [Fact]
+        public void Tran_WithMaxStep_GeneratesCorrectStatement()
+        {
+            var netlist = CircuitBuilder.Create("Tran Test")
+                .VoltageSourceSine("V1", "in", "0", 0, 1, 1000)
+                .Resistor("R1", "in", "out", 1000)
+                .Capacitor("C1", "out", "0", 1e-6)
+                .Tran(1e-6, 1e-3, maxStep: 1e-5)
+                .Save("V(out)")
+                .ToNetlist();
+
+            Assert.Contains(".TRAN 1u 1m 0 10u", netlist);
+        }
+
+        [Fact]
+        public void BJT_GeneratesCorrectLine()
+        {
+            var netlist = CircuitBuilder.Create("BJT Test")
+                .VoltageSource("VCC", "vcc", "0", dc: 12)
+                .Resistor("RC", "vcc", "out", 4700)
+                .Resistor("RB", "vcc", "base", 100000)
+                .BJT("Q1", "out", "base", "0", "2N3904")
+                .ModelRaw(".MODEL 2N3904 NPN(BF=200 IS=1e-14)")
+                .OP()
+                .Save("V(out)")
+                .ToNetlist();
+
+            Assert.Contains("Q1 out base 0 2N3904", netlist);
+            Assert.Contains(".MODEL 2N3904 NPN(BF=200 IS=1e-14)", netlist);
+        }
+
+        [Fact]
+        public void Meas_GeneratesCorrectStatement()
+        {
+            var netlist = CircuitBuilder.Create("Meas Test")
+                .VoltageSource("V1", "in", "0", ac: 1)
+                .Resistor("R1", "in", "out", 1000)
+                .Capacitor("C1", "out", "0", 1e-9)
+                .AC("DEC", 100, 1, 1e9)
+                .Save("VDB(out)")
+                .Meas("AC", "f3dB", "WHEN VDB(out) = -3")
+                .ToNetlist();
+
+            Assert.Contains(".MEAS AC f3dB WHEN VDB(out) = -3", netlist);
+        }
+    }
+}