Abstract parts cleanup (#496)

Follow-on to #495, cleans up some of the abstract_parts modules.
- Breaks ZenerDiode out of Diode
- Deprecates LedDriver abstract class, removes subclasses dependence on
this base class by inlining code. Non-backwards compatible (though
trivially fixable), refinements will break.
- Breaks up PowerConverters into LinearRegulator,
SwitchingVoltageRegulator
- Moves the BuckConverterPowerPath, BoostConverterPowerPath,
BuckBoostConverterPowerPath into circuits
- Moves some of the resistor application circuits into the circuits
package, especially the functional protection circuits as opposed to
type-wrappers

Author: ducky64

edg/abstract_parts/Diode.py

@@ -1,6 +1,5 @@
 from typing import Any, Dict
 from typing_extensions import override
-from deprecated import deprecated
 
 from ..electronics_interfaces import *
 from .PartsTable import PartsTableColumn, PartsTableRow
@@ -144,113 +143,3 @@ def _row_generate(self, row: PartsTableRow) -> None:
         self.assign(self.actual_current_rating, row[self.CURRENT_RATING])
         self.assign(self.actual_voltage_drop, row[self.FORWARD_VOLTAGE])
         self.assign(self.actual_reverse_recovery_time, row[self.REVERSE_RECOVERY])
-
-
-@abstract_block
-class ZenerDiode(KiCadImportableBlock, BaseDiode, DiscreteSemiconductor):
-    """Base class for untyped zeners
-
-    TODO power? capacitance? leakage current?
-    """
-
-    @override
-    def symbol_pinning(self, symbol_name: str) -> Dict[str, BasePort]:
-        assert symbol_name in ("Device:D_Zener", "Device:D_Zener_Small")
-        return {"A": self.anode, "K": self.cathode}
-
-    def __init__(self, zener_voltage: RangeLike) -> None:
-        super().__init__()
-
-        self.zener_voltage = self.ArgParameter(zener_voltage)
-
-        self.actual_zener_voltage = self.Parameter(RangeExpr())
-        self.actual_power_rating = self.Parameter(RangeExpr())
-
-    @override
-    def contents(self) -> None:
-        super().contents()
-
-        self.description = DescriptionString(
-            "zener voltage=",
-            DescriptionString.FormatUnits(self.actual_zener_voltage, "V"),
-            " <b>of spec:</b>",
-            DescriptionString.FormatUnits(self.zener_voltage, "V"),
-            "\n",
-            "power=",
-            DescriptionString.FormatUnits(self.actual_power_rating, "W"),
-        )
-
-
-@non_library
-class TableZenerDiode(PartsTableSelector, ZenerDiode):
-    ZENER_VOLTAGE = PartsTableColumn(Range)
-    POWER_RATING = PartsTableColumn(Range)  # tolerable power
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(*args, **kwargs)
-        self.generator_param(self.zener_voltage)
-
-    @override
-    def _row_filter(self, row: PartsTableRow) -> bool:
-        return super()._row_filter(row) and row[self.ZENER_VOLTAGE].fuzzy_in(self.get(self.zener_voltage))
-
-    @override
-    def _row_generate(self, row: PartsTableRow) -> None:
-        super()._row_generate(row)
-        self.assign(self.actual_zener_voltage, row[self.ZENER_VOLTAGE])
-        self.assign(self.actual_power_rating, row[self.POWER_RATING])
-
-
-class ProtectionZenerDiode(Protection):
-    """Zener diode reversed across a power rail to provide transient overvoltage protection (and become an incandescent
-    indicator on a reverse voltage)"""
-
-    def __init__(self, voltage: RangeLike):
-        super().__init__()
-
-        self.pwr = self.Port(
-            VoltageSink(voltage_limits=RangeExpr()),
-            [Power, InOut],
-        )
-        self.gnd = self.Port(Ground(), [Common])
-
-        self.voltage = self.ArgParameter(voltage)
-
-    @override
-    def contents(self) -> None:
-        super().contents()
-        self.diode = self.Block(ZenerDiode(zener_voltage=self.voltage))
-        self.connect(self.pwr.net, self.diode.cathode)
-        self.connect(self.gnd.net, self.diode.anode)
-        self.assign(self.pwr.voltage_limits, (0, self.diode.actual_zener_voltage.lower()))
-
-
-@deprecated("Use AnalogClampResistor, which should be cheaper and cause less signal distortion")
-class AnalogClampZenerDiode(Protection, KiCadImportableBlock):
-    """Analog overvoltage protection diode to clamp the input voltage"""
-
-    def __init__(self, voltage: RangeLike):
-        super().__init__()
-
-        self.diode = self.Block(ZenerDiode(zener_voltage=voltage))
-
-        self.gnd = self.Port(Ground(), [Common])
-        self.signal_in = self.Port(AnalogSink(), [Input])
-        self.signal_out = self.Port(
-            AnalogSource(
-                voltage_out=self.signal_in.link().voltage.intersect(
-                    self.gnd.link().voltage + (0, self.diode.actual_zener_voltage.upper())
-                ),
-                signal_out=self.signal_in.link().signal,
-            ),
-            [Output],
-        )
-        self.assign(self.signal_in.current_draw, self.signal_out.link().current_drawn)
-
-        self.connect(self.signal_in.net, self.signal_out.net, self.diode.cathode)
-        self.connect(self.gnd.net, self.diode.anode)
-
-    @override
-    def symbol_pinning(self, symbol_name: str) -> Dict[str, Port]:
-        assert symbol_name == "edg_importable:AnalogClampZenerDiode"
-        return {"IN": self.signal_in, "OUT": self.signal_out, "GND": self.gnd}

edg/abstract_parts/LedDriver.py

@@ -4,6 +4,7 @@
 from deprecated import deprecated
 
 
+@deprecated("LED API is not stabilized")
 @abstract_block
 class LedDriver(PowerConditioner, Interface):
     """Abstract current-regulated high-power LED driver.
@@ -30,6 +31,7 @@ def __init__(self, *args: Any, ripple_limit: FloatLike = float("inf"), **kwargs:
         self.ripple_limit = self.ArgParameter(ripple_limit)
 
 
+@deprecated("LED API is not stabilized")
 class LedDriverPwm(BlockInterfaceMixin[LedDriver]):
     """LED driver mixin with PWM input for dimming control."""
 

edg/abstract_parts/LinearRegulator.py

@@ -0,0 +1,63 @@
+from typing_extensions import override
+
+from ..electronics_interfaces import *
+from .Resettable import Resettable
+from .VoltageRegulator import VoltageRegulator
+
+
+@abstract_block_default(lambda: IdealLinearRegulator)
+class LinearRegulator(VoltageRegulator):
+    """Structural abstract base class for linear regulators, a voltage regulator that can produce some
+    output voltage lower than its input voltage (minus some dropout) by 'burning' the excess voltage as heat.
+
+    Compared to switching converters like buck and boost converters, linear regulators usually have lower
+    complexity, lower parts count, and higher stability. However, depending on the application, they are
+    typically less efficient, and at higher loads may require thermal design considerations."""
+
+
+@abstract_block
+class VoltageReference(LinearRegulator):
+    """Voltage reference, generally provides high accuracy but limited current"""
+
+
+class IdealLinearRegulator(Resettable, LinearRegulator, IdealModel):
+    """Ideal linear regulator, draws the output current and produces spec output voltage limited by input voltage"""
+
+    @override
+    def contents(self) -> None:
+        super().contents()
+        effective_output_voltage = self.output_voltage.intersect((0, self.pwr_in.link().voltage.upper()))
+        self.gnd.init_from(Ground())
+        self.pwr_in.init_from(VoltageSink(current_draw=self.pwr_out.link().current_drawn))
+        self.pwr_out.init_from(VoltageSource(voltage_out=effective_output_voltage))
+        self.reset.init_from(DigitalSink())
+
+
+@non_library
+class LinearRegulatorDevice(Block):
+    """Abstract base class that provides a default model with common functionality for a linear regulator chip.
+    Does not include supporting components like capacitors.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        # these device model parameters must be provided by subtypes
+        self.actual_dropout = self.Parameter(RangeExpr())
+        self.actual_quiescent_current = self.Parameter(RangeExpr())
+
+        self.gnd = self.Port(Ground(), [Common])
+        self.pwr_in = self.Port(
+            VoltageSink(voltage_limits=RangeExpr(), current_draw=RangeExpr()),  # parameters set by subtype
+            [Power, Input],
+        )
+        self.pwr_out = self.Port(
+            VoltageSource(voltage_out=self.RangeExpr(), current_limits=RangeExpr()),  # parameters set by subtype
+            [Output],
+        )
+        self.assign(self.pwr_in.current_draw, self.pwr_out.link().current_drawn + self.actual_quiescent_current)
+
+        self.require(
+            self.pwr_out.voltage_out.lower() + self.actual_dropout.upper() <= self.pwr_in.link().voltage.lower(),
+            "excessive dropout",
+        )