Add nested function syntax support for .MEAS statements and update documentation

Author: marcin-golebiowski

src/SpiceSharpParser.IntegrationTests/DotStatements/MeasTests.cs

@@ -1310,5 +1310,86 @@ public void MeasSimulationNamePopulated()
             Assert.Single(results);
             Assert.False(string.IsNullOrEmpty(results[0].SimulationName));
         }
+
+        // =====================================================================
+        // Group I: Nested function syntax — mag(V()), db(V()), etc.
+        // =====================================================================
+
+        [Fact]
+        public void NestedMagVoltageEqualsVM()
+        {
+            // mag(V(OUT)) should produce the same result as VM(OUT)
+            var model = GetSpiceSharpModel(
+                "MEAS Nested mag(V()) vs VM()",
+                "V1 IN 0 AC 1",
+                "R1 IN OUT 1e3",
+                "C1 OUT 0 1e-9",
+                ".AC DEC 10 1k 100MEG",
+                ".MEAS AC gain_vm MAX VM(OUT)",
+                ".MEAS AC gain_mag MAX mag(V(OUT))",
+                ".END");
+
+            RunSimulations(model);
+
+            Assert.True(model.Measurements.ContainsKey("gain_vm"));
+            Assert.True(model.Measurements.ContainsKey("gain_mag"));
+
+            double vmResult = model.Measurements["gain_vm"][0].Value;
+            double magResult = model.Measurements["gain_mag"][0].Value;
+
+            Assert.True(model.Measurements["gain_vm"][0].Success);
+            Assert.True(model.Measurements["gain_mag"][0].Success);
+            Assert.True(EqualsWithTol(vmResult, magResult));
+        }
+
+        [Fact]
+        public void NestedDbVoltageEqualsVDB()
+        {
+            // db(V(OUT)) should produce the same result as VDB(OUT)
+            var model = GetSpiceSharpModel(
+                "MEAS Nested db(V()) vs VDB()",
+                "V1 IN 0 AC 1",
+                "R1 IN OUT 1e3",
+                "C1 OUT 0 1e-9",
+                ".AC DEC 10 1k 100MEG",
+                ".MEAS AC max_db_vdb MAX VDB(OUT)",
+                ".MEAS AC max_db_nested MAX db(V(OUT))",
+                ".END");
+
+            RunSimulations(model);
+
+            Assert.True(model.Measurements.ContainsKey("max_db_vdb"));
+            Assert.True(model.Measurements.ContainsKey("max_db_nested"));
+
+            double vdbResult = model.Measurements["max_db_vdb"][0].Value;
+            double nestedResult = model.Measurements["max_db_nested"][0].Value;
+
+            Assert.True(model.Measurements["max_db_vdb"][0].Success);
+            Assert.True(model.Measurements["max_db_nested"][0].Success);
+            Assert.True(EqualsWithTol(vdbResult, nestedResult));
+        }
+
+        [Fact]
+        public void NestedRealImagPhaseVoltage()
+        {
+            // real(V(OUT)), imag(V(OUT)), phase(V(OUT)) should match VR, VI, VP
+            var model = GetSpiceSharpModel(
+                "MEAS Nested real/imag/phase",
+                "V1 IN 0 AC 1",
+                "R1 IN OUT 1e3",
+                "C1 OUT 0 1e-9",
+                ".AC DEC 10 1k 100MEG",
+                ".MEAS AC max_vr MAX VR(OUT)",
+                ".MEAS AC max_real MAX real(V(OUT))",
+                ".END");
+
+            RunSimulations(model);
+
+            Assert.True(model.Measurements["max_vr"][0].Success);
+            Assert.True(model.Measurements["max_real"][0].Success);
+            Assert.True(EqualsWithTol(
+                model.Measurements["max_vr"][0].Value,
+                model.Measurements["max_real"][0].Value));
+        }
     }
 }

src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/Controls/Common/ExportFactory.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Linq;
 using SpiceSharp.Simulations;
 using SpiceSharpParser.Common;
@@ -13,6 +14,23 @@ namespace SpiceSharpParser.ModelReaders.Netlist.Spice.Readers.Controls.Common
 {
     public class ExportFactory : IExportFactory
     {
+        private static readonly Dictionary<string, string> WrapperSuffixes = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            { "mag", "M" },
+            { "db", "DB" },
+            { "phase", "P" },
+            { "ph", "P" },
+            { "real", "R" },
+            { "re", "R" },
+            { "imag", "I" },
+            { "im", "I" },
+        };
+
+        private static readonly HashSet<string> BaseExportNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "V", "I",
+        };
+
         public Export Create(
             Parameter exportParameter,
             IReadingContext context,
@@ -22,8 +40,9 @@ public Export Create(
             if (exportParameter is BracketParameter bp)
             {
                 string type = bp.Name;
+                bool caseSensitive = context.ReaderSettings.CaseSensitivity.IsFunctionNameCaseSensitive;
 
-                if (mapper.TryGetValue(type, context.ReaderSettings.CaseSensitivity.IsFunctionNameCaseSensitive, out var exporter))
+                if (mapper.TryGetValue(type, caseSensitive, out var exporter))
                 {
                     return exporter.CreateExport(
                         exportParameter.Value,
@@ -32,6 +51,25 @@ public Export Create(
                         context.EvaluationContext.GetSimulationContext(simulation),
                         context.ReaderSettings.CaseSensitivity);
                 }
+
+                // Support nested function syntax: mag(V(out)) → VM(out), db(I(R1)) → IDB(R1), etc.
+                if (WrapperSuffixes.TryGetValue(type, out var suffix)
+                    && bp.Parameters.Count == 1
+                    && bp.Parameters[0] is BracketParameter inner
+                    && BaseExportNames.Contains(inner.Name))
+                {
+                    string flatType = inner.Name.ToUpper() + suffix;
+
+                    if (mapper.TryGetValue(flatType, caseSensitive, out var flatExporter))
+                    {
+                        return flatExporter.CreateExport(
+                            exportParameter.Value,
+                            flatType,
+                            inner.Parameters,
+                            context.EvaluationContext.GetSimulationContext(simulation),
+                            context.ReaderSettings.CaseSensitivity);
+                    }
+                }
             }
 
             if (exportParameter is ReferenceParameter rp)

src/docs/articles/meas.md

@@ -562,7 +562,20 @@ For AC analysis, standard `V(node)` is a complex number, so you need specific ex
 .MEAS AC bw_db WHEN VDB(out)=-3
 ```
 
-> **Note:** The nested function syntax `mag(V(out))` is **not** supported. Use `VM(out)`, `VDB(out)`, etc. instead.
+Both the prefix syntax and nested function syntax are supported:
+
+| Prefix Syntax | Nested Syntax | Description |
+|---------------|---------------|-------------|
+| `VM(out)` | `mag(V(out))` | Voltage magnitude |
+| `VDB(out)` | `db(V(out))` | Voltage in decibels |
+| `VP(out)` | `phase(V(out))` or `ph(V(out))` | Voltage phase |
+| `VR(out)` | `real(V(out))` or `re(V(out))` | Voltage real part |
+| `VI(out)` | `imag(V(out))` or `im(V(out))` | Voltage imaginary part |
+| `IM(R1)` | `mag(I(R1))` | Current magnitude |
+| `IDB(R1)` | `db(I(R1))` | Current in decibels |
+| `IP(R1)` | `phase(I(R1))` | Current phase |
+
+The nested syntax also works in `.PRINT`, `.PLOT`, `.SAVE`, and `.WAVE` statements.
 
 ---
 
@@ -649,6 +662,5 @@ C1 OUT 0 1u
 
 ## Known Limitations
 
-- `mag(V(out))` nested function syntax is not supported — use `VM(out)` instead
 - PARAM measurements must be declared **after** the measurements they reference (results are computed in declaration order, not via dependency resolution)
 - When a threshold crossing is not found in the data, the measurement returns `Success = false` and `Value = NaN` rather than raising an error