Add docs

Author: marcin-golebiowski

src/SpiceSharpParser.CustomComponents/IdealDiodes/IdealDiodeEquation.cs

@@ -7,19 +7,35 @@ namespace SpiceSharpParser.CustomComponents.IdealDiodes
     /// <summary>
     /// LTspice-style idealized diode current law.
     /// </summary>
+    /// <remarks>
+    /// This helper owns only the local current law for one ideal diode cell. The
+    /// biasing behavior that calls it handles the external branch details such as
+    /// series resistance and the parallel/series diode multipliers.
+    ///
+    /// The current law is built from straight-line regions in slope/intercept
+    /// form: <c>I = g * V + b</c>. The off region uses <c>Roff</c> or simulator
+    /// <c>Gmin</c>, the forward region uses <c>Ron</c> after <c>Vfwd</c>, and the
+    /// optional reverse-breakdown region uses <c>Rrev</c> after <c>-Vrev</c>.
+    /// Optional epsilon parameters replace abrupt knees with a finite-width
+    /// conductance ramp so both current and conductance stay continuous for
+    /// Newton iteration.
+    /// </remarks>
     internal static class IdealDiodeEquation
     {
+        /// <summary>
+        /// Lowest fallback off-state conductance when neither <c>Roff</c> nor simulator <c>Gmin</c> supplies one.
+        /// </summary>
         private const double MinimumConductance = 0.0;
 
         /// <summary>
-        /// Evaluates the current and small-signal conductance for one ideal diode.
+        /// Evaluates the current and small-signal conductance for one ideal diode cell.
         /// </summary>
-        /// <param name="parameters">The ideal diode parameters.</param>
-        /// <param name="biasingParameters">The simulation biasing parameters.</param>
-        /// <param name="voltage">The voltage across one diode.</param>
-        /// <param name="area">The diode area multiplier.</param>
-        /// <param name="current">The output current.</param>
-        /// <param name="conductance">The output conductance.</param>
+        /// <param name="parameters">The effective model and instance parameters.</param>
+        /// <param name="biasingParameters">The simulation biasing parameters, used for the default off conductance.</param>
+        /// <param name="voltage">The local voltage across one diode cell.</param>
+        /// <param name="area">The diode area multiplier applied after the local equation is evaluated.</param>
+        /// <param name="current">The resulting local diode current, scaled by <paramref name="area" />.</param>
+        /// <param name="conductance">The resulting small-signal conductance, scaled by <paramref name="area" />.</param>
         public static void Evaluate(
             IdealDiodeParameters parameters,
             BiasingParameters biasingParameters,
@@ -28,32 +44,51 @@ public static void Evaluate(
             out double current,
             out double conductance)
         {
+            // Work in conductance because the solver needs dI/dV. Each operating
+            // region is represented as a line: current = slope * voltage + intercept.
             double onConductance = 1.0 / parameters.OnResistance;
 
+            // LTspice's ideal diode can omit Roff. In that case the off-state
+            // leakage follows the simulator's Gmin so the device still contributes
+            // the same numerical shunt used elsewhere during biasing.
             double offConductance = parameters.OffResistance.Given
                 ? 1.0 / parameters.OffResistance.Value
                 : Math.Max(biasingParameters.Gmin, MinimumConductance);
 
+            // Vfwd defaults to zero. With a zero threshold, the forward on-line is
+            // simply Ron through the origin.
             double forwardVoltage = parameters.ForwardVoltage.Given ? parameters.ForwardVoltage.Value : 0.0;
 
+            // Start from the off branch. Reverse breakdown and forward conduction
+            // may overwrite this below when the voltage lies in their region.
             current = offConductance * voltage;
             conductance = offConductance;
 
             if (parameters.ReverseVoltage.Given)
             {
+                // Reverse breakdown is a line through (-Vrev, 0):
+                // current = Grev * voltage + Grev * Vrev.
+                // If Rrev is omitted, LTspice-style behavior falls back to Ron.
                 double reverseVoltage = Math.Abs(parameters.ReverseVoltage.Value);
                 double reverseResistance = parameters.ReverseResistance.Given
                     ? parameters.ReverseResistance.Value
                     : parameters.OnResistance;
                 double reverseConductance = 1.0 / reverseResistance;
                 double reverseIntercept = reverseConductance * reverseVoltage;
+
+                // Roff/Gmin can tilt the off-line, so the true intersection is not
+                // always exactly -Vrev. Use the nominal knee only as a degenerate
+                // fallback when the two lines are effectively parallel.
                 double boundary = FindIntersection(
                     reverseConductance,
                     reverseIntercept,
                     offConductance,
                     0.0,
                     -reverseVoltage);
 
+                // Evaluate the reverse-to-off knee. With revepsilon omitted or
+                // zero this is a hard switch at the intersection; otherwise it is
+                // smoothed symmetrically around the boundary.
                 EvaluateTransition(
                     voltage,
                     boundary,
@@ -66,18 +101,29 @@ public static void Evaluate(
                     out conductance);
             }
 
+            // The forward on-line crosses zero current at Vfwd:
+            // current = Gon * voltage - Gon * Vfwd.
             double onIntercept = -onConductance * forwardVoltage;
+
+            // Find the voltage where the off-line and the forward on-line meet.
+            // This is close to Vfwd when Roff is large, but computing it keeps the
+            // model continuous for any legal Roff/Gmin.
             double forwardBoundary = FindIntersection(
                 offConductance,
                 0.0,
                 onConductance,
                 onIntercept,
                 forwardVoltage);
 
+            // Avoid a second transition evaluation in the normal off region. For
+            // smoothed knees, begin applying the blend at the start of the epsilon
+            // band so the partial-conduction region is not missed.
             double forwardWidth = parameters.ForwardEpsilon.Given ? parameters.ForwardEpsilon.Value : 0.0;
             double forwardStart = forwardBoundary - (Math.Max(forwardWidth, 0.0) / 2.0);
             if (voltage > forwardBoundary || (forwardWidth > 0.0 && voltage >= forwardStart))
             {
+                // Evaluate the off-to-forward knee using the same generic transition
+                // helper used for reverse breakdown.
                 EvaluateTransition(
                     voltage,
                     forwardBoundary,
@@ -90,12 +136,26 @@ public static void Evaluate(
                     out conductance);
             }
 
+            // Current limits are applied to the already-selected region. This keeps
+            // the normal piecewise law simple and lets the limiter scale the local
+            // derivative by the tanh derivative.
             ApplyCurrentLimits(parameters, ref current, ref conductance);
 
+            // Area behaves like parallel identical cells: both DC current and
+            // small-signal conductance scale linearly.
             current *= area;
             conductance *= area;
         }
 
+        /// <summary>
+        /// Finds where two line segments in <c>current = slope * voltage + intercept</c> form intersect.
+        /// </summary>
+        /// <param name="leftSlope">The slope of the first line.</param>
+        /// <param name="leftIntercept">The intercept of the first line.</param>
+        /// <param name="rightSlope">The slope of the second line.</param>
+        /// <param name="rightIntercept">The intercept of the second line.</param>
+        /// <param name="fallback">The voltage to use if the lines are nearly parallel.</param>
+        /// <returns>The intersection voltage.</returns>
         private static double FindIntersection(
             double leftSlope,
             double leftIntercept,
@@ -104,11 +164,27 @@ private static double FindIntersection(
             double fallback)
         {
             double denominator = leftSlope - rightSlope;
+
+            // Parallel or nearly parallel regions do not give a useful numerical
+            // knee. The caller provides the physically meaningful nominal boundary.
             if (Math.Abs(denominator) <= 1e-30)
                 return fallback;
+
             return (rightIntercept - leftIntercept) / denominator;
         }
 
+        /// <summary>
+        /// Evaluates either a hard or smoothed transition between two linear current regions.
+        /// </summary>
+        /// <param name="voltage">The voltage at which to evaluate the transition.</param>
+        /// <param name="boundary">The intersection voltage of the two unsmoothed lines.</param>
+        /// <param name="epsilon">The optional smoothing width around <paramref name="boundary" />.</param>
+        /// <param name="leftSlope">The slope used below the transition.</param>
+        /// <param name="leftIntercept">The intercept used below the transition.</param>
+        /// <param name="rightSlope">The slope used above the transition.</param>
+        /// <param name="rightIntercept">The intercept used above the transition.</param>
+        /// <param name="current">The evaluated current.</param>
+        /// <param name="conductance">The evaluated conductance.</param>
         private static void EvaluateTransition(
             double voltage,
             double boundary,
@@ -123,6 +199,8 @@ private static void EvaluateTransition(
             double width = epsilon.Given ? epsilon.Value : 0.0;
             if (width <= 0.0)
             {
+                // No smoothing requested: choose the line on the active side of
+                // the intersection and expose that line's slope as conductance.
                 if (voltage < boundary)
                 {
                     current = (leftSlope * voltage) + leftIntercept;
@@ -137,8 +215,11 @@ private static void EvaluateTransition(
                 return;
             }
 
+            // The epsilon value is the full width of the blend, centered on the
+            // natural intersection of the two lines.
             double start = boundary - (width / 2.0);
             double end = boundary + (width / 2.0);
+
             if (voltage <= start)
             {
                 current = (leftSlope * voltage) + leftIntercept;
@@ -153,6 +234,14 @@ private static void EvaluateTransition(
                 return;
             }
 
+            // Inside the smoothing band the conductance moves linearly from the
+            // left slope to the right slope. Current is the integral of that ramp,
+            // anchored to the left line at the start of the band:
+            //
+            // g(x) = leftSlope + slopeDelta * x / width
+            // I(x) = I(start) + leftSlope * x + slopeDelta * x^2 / (2 * width)
+            //
+            // where x is the distance from the start of the smoothing band.
             double distance = voltage - start;
             double slopeDelta = rightSlope - leftSlope;
             current = (leftSlope * start) + leftIntercept
@@ -161,8 +250,17 @@ private static void EvaluateTransition(
             conductance = leftSlope + (slopeDelta * distance / width);
         }
 
+        /// <summary>
+        /// Applies the optional forward or reverse current limiter to the selected current branch.
+        /// </summary>
+        /// <param name="parameters">The effective ideal diode parameters.</param>
+        /// <param name="current">The current to limit in place.</param>
+        /// <param name="conductance">The conductance to update in place with the limiter derivative.</param>
         private static void ApplyCurrentLimits(IdealDiodeParameters parameters, ref double current, ref double conductance)
         {
+            // Forward and reverse limits are independent. Select by the sign of the
+            // already-computed current so leakage, breakdown, and smoothed knees all
+            // feed into the same limiting law.
             if (current > 0.0 && parameters.ForwardCurrentLimit.Given)
             {
                 ApplyCurrentLimit(parameters.ForwardCurrentLimit.Value, ref current, ref conductance);
@@ -173,12 +271,21 @@ private static void ApplyCurrentLimits(IdealDiodeParameters parameters, ref doub
             }
         }
 
+        /// <summary>
+        /// Smoothly compresses current toward a symmetric magnitude limit.
+        /// </summary>
+        /// <param name="limit">The positive or negative limit magnitude.</param>
+        /// <param name="current">The current to limit in place.</param>
+        /// <param name="conductance">The conductance to update in place with the limiter derivative.</param>
         private static void ApplyCurrentLimit(double limit, ref double current, ref double conductance)
         {
             limit = Math.Abs(limit);
             if (limit <= 0.0)
                 return;
 
+            // I_limited = limit * tanh(I_raw / limit)
+            // dI_limited/dV = dI_raw/dV * (1 - tanh(I_raw / limit)^2)
+            // This gives a soft saturation without a derivative discontinuity.
             double normalized = current / limit;
             double limited = Math.Tanh(normalized);
             current = limit * limited;

src/docs/articles/ideal-diode.md

@@ -254,7 +254,122 @@ When the diode is reverse biased, `@D1[i]` is usually negative.
 ## Current Law
 
 The ideal diode current law is evaluated for one diode cell first. Instance
-scaling is applied after that. Define:
+scaling is applied after that.
+
+### Local Evaluation Algorithm
+
+The implementation for this section lives in `IdealDiodeEquation`. The method
+`Evaluate(...)` does not stamp the circuit matrix. It only evaluates the local
+current law for one ideal-diode cell and returns two values:
+
+| Output | Meaning |
+|--------|---------|
+| `current` | Local diode current at the present voltage |
+| `conductance` | Local small-signal derivative `di/dv` used by Newton iteration |
+
+The voltage `v` is positive from anode to cathode, and positive current flows in
+that same direction. The algorithm uses a line representation for each operating
+region:
+
+```text
+i(v) = slope * v + intercept
+```
+
+This representation matters because the solver needs both the current and its
+derivative. The line slope is already the small-signal conductance for that
+region.
+
+The local evaluation is:
+
+```text
+gon  = 1 / Ron
+goff = Roff was given ? 1 / Roff : max(simulation Gmin, 0)
+vf   = Vfwd was given ? Vfwd : 0
+
+current     = goff * v
+conductance = goff
+
+if Vrev was given:
+    vrev = abs(Vrev)
+    rrev = Rrev was given ? Rrev : Ron
+    grev = 1 / rrev
+
+    reverse line = grev * v + grev * vrev
+    off line     = goff * v
+    boundary     = intersection(reverse line, off line)
+
+    current, conductance =
+        transition(v, boundary, RevEpsilon, reverse line, off line)
+
+forward line = gon * v - gon * vf
+off line     = goff * v
+boundary     = intersection(off line, forward line)
+
+if v is past the forward boundary, or inside the forward smoothing window:
+    current, conductance =
+        transition(v, boundary, Epsilon, off line, forward line)
+
+if current > 0 and Ilimit was given:
+    apply tanh current limiter
+else if current < 0 and RevIlimit was given:
+    apply tanh current limiter
+
+current     = current * area
+conductance = conductance * area
+```
+
+The order is intentional. The off line is the default because most voltages are
+between reverse breakdown and forward conduction. Reverse breakdown is evaluated
+before forward conduction because it only applies on the negative-voltage side.
+The forward transition is evaluated last so positive forward conduction replaces
+the off result when the voltage reaches the forward knee.
+
+The transition helper is shared by both knees. It receives the line on the
+low-voltage side, the line on the high-voltage side, the boundary where the two
+unsmoothed lines intersect, and the optional smoothing width. For reverse
+breakdown, the low-voltage side is the reverse line and the high-voltage side is
+the off line. For forward conduction, the low-voltage side is the off line and
+the high-voltage side is the forward line.
+
+The boundary is computed by solving the two-line equation:
+
+```text
+leftSlope * v + leftIntercept = rightSlope * v + rightIntercept
+```
+
+or:
+
+```text
+v = (rightIntercept - leftIntercept) / (leftSlope - rightSlope)
+```
+
+If the two slopes are nearly equal, the code uses the nominal knee as a fallback:
+`-Vrev` for reverse breakdown or `Vfwd` for forward conduction. That avoids an
+unstable division when two regions are almost parallel.
+
+With no smoothing, the transition helper simply chooses one line. With smoothing,
+the epsilon value is treated as the full voltage width of the blend, centered on
+the boundary. The conductance ramps linearly from the left slope to the right
+slope, and the current is the integral of that ramp. This keeps both current and
+conductance continuous at the start and end of the smoothing window.
+
+Current limiting happens after the piecewise line and optional smoothing have
+selected a raw current. The limiter is based on `tanh`, so it approaches the
+limit smoothly and also scales the conductance by the derivative of the limiter.
+The sign of the raw current selects the limiter: positive current uses `Ilimit`,
+negative current uses `RevIlimit`, and zero current is left unchanged.
+
+Finally, `area` is applied to both current and conductance. Because this happens
+after current limiting, increasing `area` scales the limited current and the
+limited small-signal conductance as if multiple identical local cells were placed
+in parallel.
+
+The caller, `Biasing`, handles everything outside the local cell. It divides the
+internal diode voltage by `N` before calling `Evaluate(...)`, multiplies the
+equivalent branch current by `M`, scales the conductance by `M / N`, and stamps
+`Rs` as the series branch between the external and internal anode.
+
+The formulas below describe the same algorithm. Define:
 
 $$
 \begin{aligned}