Fix portless sub-netlists and internal-port handling (#95, #96)

- Filter out sub-netlists with no ports in circuit() to prevent errors
  during construction of hierarchical netlists.
- Change default behavior for ports on internal connection nodes: drop
  them instead of auto-converting to probes. Add on_internal_port flag
  to circuit() with modes "warn" (default), "ignore", and "as_probes".
- Update and add tests for both fixes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: flaport

src/sax/circuits.py

@@ -28,6 +28,18 @@
 __all__ = ["circuit", "draw_dag", "get_required_circuit_models"]
 
 
+def _filter_portless_subnets(
+    netlist: sax.RecursiveNetlist,
+) -> sax.RecursiveNetlist:
+    """Remove sub-netlists that have no ports (except the top-level entry)."""
+    top_level_name = next(iter(netlist))
+    return {
+        name: flatnet
+        for name, flatnet in netlist.items()
+        if name == top_level_name or flatnet.get("ports", {})
+    }
+
+
 @overload
 def circuit(
     netlist: dict[str, Any],
@@ -37,6 +49,7 @@ def circuit(
     top_level_name: str = "top_level",
     ignore_impossible_connections: bool = False,
     probes: dict[str, str] | None = None,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.SDictModel, sax.CircuitInfo]: ...
 
 
@@ -50,6 +63,7 @@ def circuit(
     top_level_name: str = "top_level",
     ignore_impossible_connections: bool = False,
     probes: dict[str, str] | None = None,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.SDictModel, sax.CircuitInfo]: ...
 
 
@@ -63,6 +77,7 @@ def circuit(
     top_level_name: str = "top_level",
     ignore_impossible_connections: bool = False,
     probes: dict[str, str] | None = None,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.SDenseModel, sax.CircuitInfo]: ...
 
 
@@ -76,6 +91,7 @@ def circuit(
     top_level_name: str = "top_level",
     ignore_impossible_connections: bool = False,
     probes: dict[str, str] | None = None,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.SCooModel, sax.CircuitInfo]: ...
 
 
@@ -88,6 +104,7 @@ def circuit(
     top_level_name: str = "top_level",
     ignore_impossible_connections: bool = False,
     probes: dict[str, str] | None = None,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.Model, sax.CircuitInfo]:
     """Create a circuit function for a given netlist.
 
@@ -113,6 +130,10 @@ def circuit(
             connection and exposes forward and backward traveling wave ports.
             For a probe named "X" at instance port "inst,port", two new circuit
             ports are created: "X_fwd" and "X_bwd". Defaults to None.
+        on_internal_port: How to handle top-level ports that map to internal
+            connection nodes. ``"warn"`` (default) drops them with a warning,
+            ``"ignore"`` drops them silently, ``"as_probes"`` converts them
+            to measurement probes (legacy behaviour).
 
     Returns:
         Tuple containing:
@@ -158,13 +179,14 @@ def waveguide(length=10.0, neff=2.4, wl=1.55):
     )
     patch_netlist_array_instances(recnet)
     recnet = sax.into[sax.RecursiveNetlist](recnet)
-    recnet, auto_probes = extract_port_probes(recnet)
+    recnet, auto_probes = extract_port_probes(recnet, on_internal_port)
     if auto_probes:
         probes = {**(probes or {}), **auto_probes}
     if probes:
         recnet = expand_probes(recnet, probes)
         models = {"_ideal_probe": ideal_probe, **(models or {})}
     recnet = resolve_array_instances(recnet)
+    recnet = _filter_portless_subnets(recnet)
     recnet = remove_unused_instances(recnet)
     _validate_netlist_ports(recnet)
     dependency_dag = _create_dag(recnet, models, validate=True)

src/sax/netlists.py

@@ -4,7 +4,7 @@
 
 import warnings
 from copy import deepcopy
-from typing import cast, overload
+from typing import Literal, cast, overload
 
 import networkx as nx
 from natsort import natsorted
@@ -656,37 +656,46 @@ def _expand_probes_recursive(  # noqa: C901
 @overload
 def extract_port_probes(
     netlist: sax.Netlist,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.Netlist, dict[str, str]]: ...
 
 
 @overload
 def extract_port_probes(
     netlist: sax.RecursiveNetlist,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.RecursiveNetlist, dict[str, str]]: ...
 
 
 def extract_port_probes(
     netlist: sax.AnyNetlist,
+    on_internal_port: Literal["warn", "ignore", "as_probes"] = "warn",
 ) -> tuple[sax.AnyNetlist, dict[str, str]]:
-    """Extract ports on internal nodes and convert them to probes.
+    """Handle ports that map to internal connection nodes.
 
     When a netlist port maps to an instance port that is already part of a
-    connection (in ``connections`` or ``nets``), it is removed from ports and
-    returned as a probe instead.  A warning is issued for each such port.
+    connection (in ``connections`` or ``nets``), the behaviour depends on
+    *on_internal_port*:
+
+    * ``"warn"`` (default) — drop the port and emit a warning.
+    * ``"ignore"`` — drop the port silently.
+    * ``"as_probes"`` — convert the port to a probe (creating ``_fwd`` /
+      ``_bwd`` ports), matching the legacy behaviour.
 
     Args:
         netlist: The netlist to inspect (flat or recursive).
+        on_internal_port: How to handle ports on internal nodes.
 
     Returns:
-        A tuple of (modified_netlist, probes) where *probes* maps the original
-        port name to the instance port string, ready to pass to
-        :func:`expand_probes`.
+        A tuple of (modified_netlist, probes) where *probes* maps original
+        port names to instance port strings.  The dict is empty unless
+        *on_internal_port* is ``"as_probes"``.
     """
     # Handle recursive netlist: only inspect the top-level
     if (recnet := sax.try_into[sax.RecursiveNetlist](netlist)) is not None:
         top_level_name = next(iter(recnet))
         top_level = recnet[top_level_name]
-        modified_top, probes = extract_port_probes(top_level)
+        modified_top, probes = extract_port_probes(top_level, on_internal_port)
         result: sax.RecursiveNetlist = {
             top_level_name: modified_top,
             **{k: v for k, v in recnet.items() if k != top_level_name},
@@ -711,14 +720,26 @@ def extract_port_probes(
     probes: dict[str, str] = {}
     for port_name, instance_port in list(ports.items()):
         if instance_port in internal_ports:
-            warnings.warn(
-                f"Port '{port_name}' maps to internal node '{instance_port}' "
-                f"which is already part of a connection. "
-                f"It will be interpreted as a probe (creating '{port_name}_fwd' "
-                f"and '{port_name}_bwd' ports).",
-                stacklevel=2,
-            )
-            probes[port_name] = instance_port
+            if on_internal_port == "as_probes":
+                warnings.warn(
+                    f"Port '{port_name}' maps to internal node "
+                    f"'{instance_port}' which is already part of a "
+                    f"connection. It will be interpreted as a probe "
+                    f"(creating '{port_name}_fwd' and "
+                    f"'{port_name}_bwd' ports).",
+                    stacklevel=2,
+                )
+                probes[port_name] = instance_port
+            elif on_internal_port == "warn":
+                warnings.warn(
+                    f"Port '{port_name}' maps to internal node "
+                    f"'{instance_port}' which is already part of a "
+                    f"connection. It will be dropped. Use the probes= "
+                    f"argument of circuit() to explicitly create "
+                    f"measurement probes.",
+                    stacklevel=2,
+                )
+            # "ignore" falls through — just delete silently
             del ports[port_name]
 
     net["ports"] = ports

src/tests/test_circuit.py

@@ -60,6 +60,65 @@ def test_1port_circuit() -> None:
     assert ("in", "in") in result
 
 
+def test_circuit_with_portless_subnetlist() -> None:
+    """Test that a sub-netlist without a 'ports' key is filtered out (#95)."""
+    netlist = {
+        "top_level": {
+            "instances": {
+                "wg": {"component": "waveguide"},
+            },
+            "connections": {},
+            "ports": {
+                "in": "wg,in0",
+                "out": "wg,out0",
+            },
+        },
+        # Sub-netlist with no "ports" key at all
+        "unused_sub": {
+            "instances": {
+                "x": {"component": "waveguide"},
+            },
+            "connections": {},
+        },
+    }
+
+    models = {"waveguide": sax.models.straight}
+    circuit, _ = sax.circuit(netlist, models)
+    result = circuit()
+    assert set(sax.get_ports(result)) == {"in", "out"}
+
+
+def test_circuit_with_empty_ports_subnetlist() -> None:
+    """Test that a sub-netlist with 'ports': {} is filtered out (#95)."""
+    netlist = {
+        "top_level": {
+            "instances": {
+                "wg": {"component": "waveguide"},
+            },
+            "connections": {},
+            "ports": {
+                "in": "wg,in0",
+                "out": "wg,out0",
+            },
+        },
+        # Sub-netlist with empty ports dict
+        "unused_sub": {
+            "instances": {
+                "x": {"component": "waveguide"},
+            },
+            "connections": {},
+            "ports": {},
+        },
+    }
+
+    models = {"waveguide": sax.models.straight}
+    circuit, _ = sax.circuit(netlist, models)
+    result = circuit()
+    assert set(sax.get_ports(result)) == {"in", "out"}
+
+
 if __name__ == "__main__":
     print(test_circuit())
     print(test_1port_circuit())
+    print(test_circuit_with_portless_subnetlist())
+    print(test_circuit_with_empty_ports_subnetlist())