feat(FXC-5013): Lumped element support for arbitrary RLC circuit

Author: George-Guryev-flxcmp

tests/test_components/test_lumped_element.py

@@ -8,7 +8,10 @@
 
 import tidy3d as td
 from tidy3d.components.geometry.utils import SnapBehavior, SnapLocation
-from tidy3d.components.lumped_element import network_complex_permittivity
+from tidy3d.components.lumped_element import (
+    Component,
+    network_complex_permittivity,
+)
 
 
 def test_lumped_resistor():
@@ -480,3 +483,297 @@ def test_very_small_lateral_width_snapping():
 
     # Should not raise division by zero error
     structure = element.to_structure(grid)
+
+
+# --- SPICE parser tests ---
+
+
+def test_parse_spice_value_no_suffix():
+    """Parse numeric values without scale suffix."""
+    parse = td.CircuitImpedanceModel._parse_spice_value
+    assert parse("50") == 50.0
+    assert parse("1.5") == 1.5
+    assert parse("1e-12") == 1e-12
+    assert parse("+2.5") == 2.5
+    assert parse("-3") == -3.0
+
+
+@pytest.mark.parametrize(
+    "s,expected",
+    [
+        ("1K", 1e3),
+        ("1k", 1e3),
+        ("2.5K", 2.5e3),
+        ("1M", 1e6),
+        ("1meg", 1e6),
+        ("1MEG", 1e6),
+        ("10m", 0.01),
+        ("1u", 1e-6),
+        ("1U", 1e-6),
+        ("1n", 1e-9),
+        ("1p", 1e-12),
+        ("1f", 1e-15),
+    ],
+)
+def test_parse_spice_value_scale_suffixes(s, expected):
+    """Parse values with ``K`` (kilo), ``M``/``MEG`` (mega), ``m`` (milli), ``u``, ``n``, ``p``, ``f``."""
+    assert td.CircuitImpedanceModel._parse_spice_value(s) == pytest.approx(expected)
+
+
+def test_parse_spice_value_invalid():
+    """Invalid value or suffix raises ``ValueError``."""
+    parse = td.CircuitImpedanceModel._parse_spice_value
+    with pytest.raises(ValueError, match="Empty value"):
+        parse("")
+    with pytest.raises(ValueError, match="Cannot parse"):
+        parse("abc")
+    with pytest.raises(ValueError, match="Unknown scale suffix"):
+        parse("1x")
+
+
+def test_parse_spice_file_no_source_port_from_first_element(tmp_path):
+    """With no voltage source, port is taken from the first element's nodes (``_parse_spice_file``)."""
+    netlist = """
+    * simple RC
+    R1 1 0 50
+    C1 1 0 1p
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    comp_list, port_plus, port_minus = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert len(comp_list) == 2
+    assert comp_list[0].element_type == "R"
+    assert comp_list[0].node_plus == "1"
+    assert comp_list[0].node_minus == "0"
+    assert comp_list[0].value == 50.0
+    assert comp_list[0].name == "R1"
+    assert comp_list[1].element_type == "C"
+    assert comp_list[1].value == 1e-12
+    assert port_plus == "1"
+    assert port_minus == "0"
+
+
+def test_parse_spice_file_single_voltage_source_defines_port(tmp_path):
+    """Single voltage source defines port nodes (``_parse_spice_file``)."""
+    netlist = """
+    V1 1 0 DC 0 AC 1
+    R1 1 0 50
+    C1 1 0 1p
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    comp_list, port_plus, port_minus = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert len(comp_list) == 2
+    assert port_plus == "1"
+    assert port_minus == "0"
+
+
+def test_parse_spice_file_comments_and_continuation(tmp_path):
+    """Comment lines and + continuation are handled."""
+    netlist = """
+    $ comment
+    * another comment
+    R1 1 0 50
+    C1 1 0
+    + 1p
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    comp_list, _, _ = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert len(comp_list) == 2
+    assert comp_list[1].value == 1e-12
+
+
+def test_parse_spice_file_scale_suffixes_in_netlist(tmp_path):
+    """Scale suffixes ``K``, ``M``, ``m``, ``p`` in netlist are parsed."""
+    netlist = """
+    R1 1 0 2K
+    C1 1 0 0.5p
+    L1 2 1 10n
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    comp_list, _, _ = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert comp_list[0].value == 2000.0
+    assert comp_list[1].value == 0.5e-12
+    assert comp_list[2].value == 10e-9
+
+
+def test_parse_spice_file_two_voltage_sources_raises(tmp_path):
+    """At most one voltage source is allowed."""
+    netlist = """
+    V1 1 0 DC 0
+    V2 2 0 DC 0
+    R1 1 0 50
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    with pytest.raises(ValueError, match="at most one voltage source"):
+        td.CircuitImpedanceModel._parse_spice_file(path)
+
+
+def test_parse_spice_file_no_rlc_raises(tmp_path):
+    """Netlist must contain at least one ``R``, ``C``, or ``L`` (``_parse_spice_file``)."""
+    netlist = """
+    V1 1 0 DC 0
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    with pytest.raises(ValueError, match="no R, C, or L"):
+        td.CircuitImpedanceModel._parse_spice_file(path)
+
+
+def test_parse_spice_file_component_line_too_short_raises(tmp_path):
+    """Malformed component line raises."""
+    netlist = """
+    R1 1 0
+    """
+    path = tmp_path / "circuit.cir"
+    path.write_text(netlist)
+    with pytest.raises(ValueError, match="Component line must have name"):
+        td.CircuitImpedanceModel._parse_spice_file(path)
+
+
+def _effective_admittance_from_component_list(
+    component_list: list[Component],
+    frequencies: np.ndarray,
+    port_plus_node: str = "1",
+    port_minus_node: str = "0",
+) -> np.ndarray:
+    """Compute one-port admittance from component list (same logic as ``from_component_list``)."""
+    return td.CircuitImpedanceModel._get_effective_admittance(
+        component_list, frequencies, port_plus_node=port_plus_node, port_minus_node=port_minus_node
+    )
+
+
+def test_effective_admittance_parallel_rc(tmp_path):
+    """Component list, SPICE (with and without voltage source), and analytical agree for parallel RC.
+
+    Circuit: ``R`` and ``C`` both between node 1 and 0. Port 1-0.
+    Analytical: ``Y = 1/R + j*omega*C``.
+    """
+    R, C = 50.0, 1e-12
+    component_list = [
+        Component(element_type="R", node_plus="1", node_minus="0", value=R, name="R1"),
+        Component(element_type="C", node_plus="1", node_minus="0", value=C, name="C1"),
+    ]
+    freqs = np.linspace(0.2e9, 8e9, 30)
+    port_plus, port_minus = "1", "0"
+    omega = 2 * np.pi * freqs
+    Y_analytical = 1.0 / R + 1j * omega * C
+
+    Y_from_list = _effective_admittance_from_component_list(
+        component_list, freqs, port_plus_node=port_plus, port_minus_node=port_minus
+    )
+    assert np.allclose(Y_from_list, Y_analytical, rtol=1e-14, atol=1e-20)
+
+    # SPICE without voltage source: port from first element
+    netlist = f"""
+    R1 1 0 {R}
+    C1 1 0 {C}
+    """
+    path = tmp_path / "parallel_rc.cir"
+    path.write_text(netlist)
+    comp_list_spice, port_plus_s, port_minus_s = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert port_plus_s == port_plus and port_minus_s == port_minus
+    Y_from_spice = _effective_admittance_from_component_list(
+        comp_list_spice, freqs, port_plus_node=port_plus_s, port_minus_node=port_minus_s
+    )
+    assert np.allclose(Y_from_list, Y_from_spice, rtol=1e-14, atol=1e-20)
+    assert np.allclose(Y_from_spice, Y_analytical, rtol=1e-14, atol=1e-20)
+
+    # SPICE with voltage source: port from V
+    netlist_v = f"""
+    V1 1 0 DC 0 AC 1
+    R1 1 0 {R}
+    C1 1 0 {C}
+    """
+    path_v = tmp_path / "with_v.cir"
+    path_v.write_text(netlist_v)
+    comp_list_spice_v, port_plus_v, port_minus_v = td.CircuitImpedanceModel._parse_spice_file(
+        path_v
+    )
+    assert port_plus_v == "1" and port_minus_v == "0"
+    Y_from_spice_v = _effective_admittance_from_component_list(
+        comp_list_spice_v, freqs, port_plus_node=port_plus_v, port_minus_node=port_minus_v
+    )
+    assert np.allclose(Y_from_list, Y_from_spice_v, rtol=1e-14, atol=1e-20)
+    assert np.allclose(Y_from_spice_v, Y_analytical, rtol=1e-14, atol=1e-20)
+
+
+def test_effective_admittance_series_rc(tmp_path):
+    """Component list, SPICE, and analytical agree for series RC.
+
+    Circuit: node 1 -- ``R`` -- node 2 -- ``C`` -- node 0. Port 1-0.
+    Analytical: ``Y = 1/(R + 1/(j*omega*C)) = j*omega*C / (1 + j*omega*R*C)``.
+    """
+    R, C = 50.0, 1e-12
+    component_list = [
+        Component(element_type="R", node_plus="1", node_minus="2", value=R, name="R1"),
+        Component(element_type="C", node_plus="2", node_minus="0", value=C, name="C1"),
+    ]
+    freqs = np.linspace(0.2e9, 8e9, 30)
+    port_plus, port_minus = "1", "0"
+    omega = 2 * np.pi * freqs
+    Y_analytical = (1j * omega * C) / (1.0 + 1j * omega * R * C)
+
+    Y_from_list = _effective_admittance_from_component_list(
+        component_list, freqs, port_plus_node=port_plus, port_minus_node=port_minus
+    )
+    assert np.allclose(Y_from_list, Y_analytical, rtol=1e-14, atol=1e-20)
+
+    # SPICE: use voltage source to define port 1-0 (no single element has both 1 and 0 in series RC)
+    netlist = f"""
+    V1 1 0 DC 0 AC 1
+    R1 1 2 {R}
+    C1 2 0 {C}
+    """
+    path = tmp_path / "series_rc.cir"
+    path.write_text(netlist)
+    comp_list_spice, port_plus_s, port_minus_s = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert port_plus_s == "1" and port_minus_s == "0"
+    Y_from_spice = _effective_admittance_from_component_list(
+        comp_list_spice, freqs, port_plus_node=port_plus_s, port_minus_node=port_minus_s
+    )
+    assert np.allclose(Y_from_list, Y_from_spice, rtol=1e-14, atol=1e-20)
+    assert np.allclose(Y_from_spice, Y_analytical, rtol=1e-14, atol=1e-20)
+
+
+def test_effective_admittance_series_rcl(tmp_path):
+    """Component list, SPICE, and analytical agree for ``L`` in parallel with (``R`` in series ``C``).
+
+    Circuit: ``L`` between 1-0, ``R`` between 1-2, ``C`` between 2-0. Port 1-0.
+    Analytical: ``Y = 1/(j*omega*L) + 1/(R + 1/(j*omega*C))``.
+    """
+    R, C, L = 50.0, 1e-12, 2e-9
+    component_list = [
+        Component(element_type="R", node_plus="1", node_minus="2", value=R, name="R1"),
+        Component(element_type="C", node_plus="2", node_minus="0", value=C, name="C1"),
+        Component(element_type="L", node_plus="1", node_minus="0", value=L, name="L1"),
+    ]
+    freqs = np.linspace(0.2e9, 8e9, 30)
+    port_plus, port_minus = "1", "0"
+    omega = 2 * np.pi * freqs
+    Y_L = 1.0 / (1j * omega * L)
+    Z_RC = R + 1.0 / (1j * omega * C)
+    Y_analytical = Y_L + 1.0 / Z_RC
+
+    Y_from_list = _effective_admittance_from_component_list(
+        component_list, freqs, port_plus_node=port_plus, port_minus_node=port_minus
+    )
+    assert np.allclose(Y_from_list, Y_analytical, rtol=1e-14, atol=1e-20)
+
+    netlist = f"""
+    L1 1 0 {L}
+    R1 1 2 {R}
+    C1 2 0 {C}
+    """
+    path = tmp_path / "series_rcl.cir"
+    path.write_text(netlist)
+    comp_list_spice, port_plus_s, port_minus_s = td.CircuitImpedanceModel._parse_spice_file(path)
+    assert port_plus_s == "1" and port_minus_s == "0", "port from first element (L1 1 0)"
+    Y_from_spice = _effective_admittance_from_component_list(
+        comp_list_spice, freqs, port_plus_node=port_plus_s, port_minus_node=port_minus_s
+    )
+    assert np.allclose(Y_from_list, Y_from_spice, rtol=1e-14, atol=1e-20)
+    assert np.allclose(Y_from_spice, Y_analytical, rtol=1e-14, atol=1e-20)

tidy3d/__init__.py

@@ -307,6 +307,7 @@
 # lumped elements
 from .components.lumped_element import (
     AdmittanceNetwork,
+    CircuitImpedanceModel,
     CoaxialLumpedResistor,
     LinearLumpedElement,
     LumpedElement,
@@ -567,6 +568,7 @@ def set_logging_level(level: str) -> None:
     "ChargeToleranceSpec",
     "ChebSampling",
     "ClipOperation",
+    "CircuitImpedanceModel",
     "CoaxialLumpedResistor",
     "CompositeCurrentIntegral",
     "CompositeCurrentIntegralSpec",