paramrf 0.35.0__tar.gz → 0.35.2__tar.gz

{paramrf-0.35.0 → paramrf-0.35.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.0
+Version: 0.35.2
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf

{paramrf-0.35.0 → paramrf-0.35.2}/paramrf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.0
+Version: 0.35.2
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf

{paramrf-0.35.0 → paramrf-0.35.2}/paramrf.egg-info/SOURCES.txt

@@ -211,6 +211,7 @@ tests/test_materials/test_surface_impedance.py
 tests/test_math/test_bessel.py
 tests/test_models/test_adapters.py
 tests/test_models/test_circuit_nodal.py
+tests/test_models/test_circuit_port_order.py
 tests/test_models/test_circuit_scattering.py
 tests/test_models/test_current_distribution.py
 tests/test_models/test_interconnected.py

{paramrf-0.35.0 → paramrf-0.35.2}/pmrf/models/composite/interconnected/circuit/circuit.py

@@ -48,18 +48,26 @@ class Circuit(Model):
     of nodes. Each node connects one or more ports of the constituent models 
     to form a composite network.
 
+    The external ports follow `Port` declaration order: scanning `connections`
+    node by node, left to right, the first `Port` found is port 0. This holds for
+    every solver, nested or flattened.
+
     Parameters
     ----------
     connections : list[list[tuple[Model, int]]]
         A list representing the nodes of the circuit. Each node is a list of
         tuples, where each tuple contains a model and the integer
         index of the port to connect to that node.
-    flatten: bool, default=True
+    flatten: bool, default=False
         Flattens sub-circuits and sub-cascades to perform a single solve.
-        Defaults to True.
-    solver : AbstractCircuitSolver, default=GlobalScatteringCircuitSolver()
+    solver : AbstractCircuitSolver, default=GlobalMNACircuitSolver()
         The circuit solver to use. Available solvers can be found in :mod:`pmrf.models`.
 
+    Raises
+    ------
+    ValueError
+        If two `Port`\\ s share a net, or a `Port` shares a net with a `Ground`.
+
     Examples
     --------
     Create a two-port PI-CLC network. External nodes are defined using `Port`, 
@@ -75,8 +83,8 @@ class Circuit(Model):
     >>> 
     >>> # Create the connections list
     >>> connections = [
-    ...     [(p0, 0), (C1, 1), (L, 1)],         # Node 0 -> Port 1
-    ...     [(p1, 0), (C2, 1), (L, 0)],         # Node 1 -> Port 2
+    ...     [(p0, 0), (C1, 1), (L, 1)],         # Node 0 -> Port 0
+    ...     [(p1, 0), (C2, 1), (L, 0)],         # Node 1 -> Port 1
     ...     [(ground, 0), (C1, 0), (C2, 0)],    # Node 2 -> Ground
     ... ]
     >>> 
@@ -149,6 +157,34 @@ class Circuit(Model):
             
         self.circuit = models
         self.indexed_connections = indexed_connections
+        self._validate_port_nets()
+
+    def _validate_port_nets(self):
+        """Ensures every `Port` has a net to itself that is not grounded."""
+        global_net_map = compute_unique_nets(self.circuit, self.indexed_connections)
+
+        net_to_port = {}
+        ground_nets = set()
+        offset = 0
+        port_idx = 0
+        for model in self.circuit:
+            if isinstance(model, Ground):
+                ground_nets.update(global_net_map[offset : offset + model.nports].tolist())
+            elif isinstance(model, Port):
+                net = int(global_net_map[offset])
+                label = f"Port {port_idx} ('{getattr(model, 'name', None) or 'unnamed'}')"
+                if net in net_to_port:
+                    raise ValueError(
+                        f"{net_to_port[net]} and {label} are connected to the same net. "
+                        "Each Port must be on its own net."
+                    )
+                net_to_port[net] = label
+                port_idx += 1
+            offset += model.nports
+
+        for net, label in net_to_port.items():
+            if net in ground_nets:
+                raise ValueError(f"{label} is connected to a Ground net. A Port cannot be grounded.")
 
     def expand(self):
         internal_ports = [comp for comp in self.circuit if isinstance(comp, Port)]
@@ -209,14 +245,14 @@ class Circuit(Model):
         global_net_map = compute_unique_nets(self.circuit, self.indexed_connections)
         
         ground_nets = set()
-        ext_nets = set()
+        ext_nets = []  # In `Port` declaration order, which fixes the external port order
         offset = 0
         for model in self.circuit:
             nets = global_net_map[offset : offset + model.nports]
             if isinstance(model, Ground):
                 ground_nets.update(nets)
             elif isinstance(model, Port):
-                ext_nets.update(nets)
+                ext_nets.extend(nets)
             offset += model.nports
             
         unique_all_nets = np.unique(global_net_map)
@@ -243,7 +279,7 @@ class Circuit(Model):
         r_idx_mapped = mapping[_safe_cat(r_idx)]
         c_idx_mapped = mapping[_safe_cat(c_idx)]
         
-        ext_active = np.array([n for n in ext_nets if n not in ground_nets], dtype=int)
+        ext_active = np.array(ext_nets, dtype=int)
         int_active = np.setdiff1d(active_nets, ext_active)
 
         return NodalRepresentation(
@@ -723,6 +759,14 @@ def flatten_hierarchy(connections: list[list[tuple[Model, int]]]) -> list[list[t
             group.sort(key=lambda x: (model_discovery_order[id(x[0])], x[1]))
             valid_groups.append(group)
             
-    valid_groups.sort(key=lambda g: (model_discovery_order[id(g[0][0])], g[0][1]))
+    # Nets holding a top-level `Port` come first, in `Port` declaration order, since
+    # the flat circuit's external port order is the order its `Port`s first appear.
+    def group_order(group):
+        port_orders = [model_discovery_order[id(m)] for m, _ in group if isinstance(m, Port)]
+        if port_orders:
+            return (0, min(port_orders), 0)
+        return (1, model_discovery_order[id(group[0][0])], group[0][1])
+
+    valid_groups.sort(key=group_order)
 
     return valid_groups

{paramrf-0.35.0 → paramrf-0.35.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "paramrf"
-version = "0.35.0"
+version = "0.35.2"
 description = "Parametric radio frequency modeling"
 readme = "README.rst"
 authors = [

paramrf-0.35.2/tests/test_models/test_circuit_port_order.py

@@ -0,0 +1,168 @@
+# tests/test_models/test_circuit_port_order.py
+"""
+A `Circuit` orders its external ports by `Port` declaration: the first `Port` found
+scanning `connections` node by node, left to right, is port 0. This must hold for
+every solver and must not depend on how internal components are wired.
+"""
+import pytest
+import numpy as np
+
+from pmrf.frequency import Frequency
+from pmrf.models import (
+    Circuit, Port, Ground, Resistor, Capacitor, Inductor,
+    GlobalScatteringCircuitSolver,
+    HierarchicalScatteringCircuitSolver,
+    SequentialScatteringCircuitSolver,
+    GlobalNodalCircuitSolver,
+    GlobalMNACircuitSolver,
+)
+
+SOLVERS = [
+    GlobalScatteringCircuitSolver,
+    HierarchicalScatteringCircuitSolver,
+    SequentialScatteringCircuitSolver,
+    GlobalNodalCircuitSolver,
+    GlobalMNACircuitSolver,
+]
+
+Z0 = 50.0
+
+
+@pytest.fixture
+def freq():
+    return Frequency(start=1.0, stop=10.0, npoints=3, unit='GHz')
+
+
+def _y_to_s(Y, z0=Z0):
+    """Independent reference: S = (I - z0 Y)(I + z0 Y)^-1 for a real, uniform z0."""
+    eye = np.eye(Y.shape[0])
+    return (eye - z0 * Y) @ np.linalg.inv(eye + z0 * Y)
+
+
+# Asymmetric two-port: node A has a 10 Ω shunt, node B a 1000 Ω shunt, with a 5 Ω
+# series resistor between them. Nodal Y written down by hand, ordered (A, B).
+R_A, R_B, R_SERIES = 10.0, 1000.0, 5.0
+Y_AB = np.array([
+    [1 / R_A + 1 / R_SERIES, -1 / R_SERIES],
+    [-1 / R_SERIES, 1 / R_B + 1 / R_SERIES],
+])
+S_AB = _y_to_s(Y_AB)
+
+
+def _asymmetric_two_port(solver, a_first: bool, series_flipped: bool, **kwargs):
+    shunt_a, shunt_b, series = Resistor(R=R_A), Resistor(R=R_B), Resistor(R=R_SERIES)
+    port_a, port_b, ground = Port(), Port(), Ground()
+
+    series_a, series_b = ((series, 1), (series, 0)) if series_flipped else ((series, 0), (series, 1))
+    node_a = [(port_a, 0), (shunt_a, 0), series_a]
+    node_b = [(port_b, 0), (shunt_b, 0), series_b]
+    nodes = [node_a, node_b] if a_first else [node_b, node_a]
+
+    return Circuit(
+        nodes + [[(ground, 0), (shunt_a, 1), (shunt_b, 1)]],
+        solver=solver,
+        **kwargs,
+    )
+
+
+def test_asymmetric_two_port_reference_values():
+    # Values quoted in issue #165, as a guard on the hand-written reference.
+    assert np.isclose(S_AB[0, 0], -0.7122, atol=1e-4)
+    assert np.isclose(S_AB[1, 1], -0.5833, atol=1e-4)
+
+
+@pytest.mark.parametrize("series_flipped", [False, True])
+@pytest.mark.parametrize("a_first", [True, False])
+@pytest.mark.parametrize("solver_cls", SOLVERS)
+def test_ports_follow_declaration_order(solver_cls, a_first, series_flipped, freq):
+    circuit = _asymmetric_two_port(solver_cls(), a_first, series_flipped)
+    expected = S_AB if a_first else S_AB[::-1, ::-1]
+
+    s = circuit.s(freq, z0=Z0)
+
+    np.testing.assert_allclose(s, np.broadcast_to(expected, s.shape), atol=1e-8)
+
+
+def _kron_reduce(Y, keep):
+    """Independent reference: eliminate every node not in `keep` by Schur complement."""
+    keep = np.asarray(keep)
+    drop = np.setdiff1d(np.arange(Y.shape[0]), keep)
+    return Y[np.ix_(keep, keep)] - Y[np.ix_(keep, drop)] @ np.linalg.solve(
+        Y[np.ix_(drop, drop)], Y[np.ix_(drop, keep)]
+    )
+
+
+@pytest.mark.parametrize("flatten", [False, True])
+@pytest.mark.parametrize("solver_cls", SOLVERS)
+def test_nested_circuit_ports_follow_declaration_order(solver_cls, flatten, freq):
+    # The inner circuit has its series element's port indices swapped.
+    inner = _asymmetric_two_port(solver_cls(), a_first=True, series_flipped=True)
+
+    # The outer circuit adds a 3 Ω series resistor on A and a 2 Ω one on B. The
+    # resistor on B is declared first, so it is discovered before either `Port`,
+    # but port A is still the first `Port` declared.
+    r_ta, r_tb = 3.0, 2.0
+    t_a, t_b = Resistor(R=r_ta), Resistor(R=r_tb)
+    port_a, port_b = Port(), Port()
+    outer = Circuit([
+        [(t_b, 0), (inner, 1)],
+        [(t_a, 0), (inner, 0)],
+        [(port_a, 0), (t_a, 1)],
+        [(port_b, 0), (t_b, 1)],
+    ], solver=solver_cls(), flatten=flatten)
+
+    # Nodes (A, B, port A, port B), by hand.
+    Y = np.zeros((4, 4))
+    Y[:2, :2] = Y_AB
+    for i, j, R in [(0, 2, r_ta), (1, 3, r_tb)]:
+        Y[np.ix_([i, j], [i, j])] += np.array([[1, -1], [-1, 1]]) / R
+    expected = _y_to_s(_kron_reduce(Y, keep=[2, 3]))
+
+    s = outer.s(freq, z0=Z0)
+
+    np.testing.assert_allclose(s, np.broadcast_to(expected, s.shape), atol=1e-8)
+
+
+def test_ports_sharing_a_net_raise():
+    shunt, ground = Resistor(R=R_A), Ground()
+    port_a, port_b = Port(name="port_a"), Port(name="port_b")
+
+    with pytest.raises(ValueError, match="port_a.*port_b"):
+        Circuit([
+            [(port_a, 0), (port_b, 0), (shunt, 0)],
+            [(ground, 0), (shunt, 1)],
+        ])
+
+
+def test_port_sharing_a_net_with_ground_raises():
+    shunt, ground = Resistor(R=R_A), Ground()
+    port_a, port_b = Port(name="port_a"), Port(name="port_b")
+
+    with pytest.raises(ValueError, match="port_b.*Ground"):
+        Circuit([
+            [(port_a, 0), (shunt, 0)],
+            [(ground, 0), (shunt, 1), (port_b, 0)],
+        ])
+
+
+@pytest.mark.parametrize("solver_cls", SOLVERS)
+def test_pi_clc_docstring_example_matches_skrf(solver_cls, freq):
+    skrf = pytest.importorskip("skrf")
+
+    # Exactly the `Circuit` docstring example: `(L, 1)` on the first node.
+    C1, C2 = Capacitor(C=2e-12), Capacitor(C=1.5e-12)
+    L = Inductor(L=3e-9)
+    p0, p1, ground = Port(), Port(), Ground()
+    pi_clc = Circuit([
+        [(p0, 0), (C1, 1), (L, 1)],
+        [(p1, 0), (C2, 1), (L, 0)],
+        [(ground, 0), (C1, 0), (C2, 0)],
+    ], solver=solver_cls())
+
+    # Port 1 is the C1 side.
+    media = skrf.media.DefinedGammaZ0(frequency=freq.to_skrf(), z0_port=Z0)
+    expected = (
+        media.shunt_capacitor(2e-12) ** media.inductor(3e-9) ** media.shunt_capacitor(1.5e-12)
+    ).s
+
+    np.testing.assert_allclose(pi_clc.s(freq, z0=Z0), expected, atol=1e-8)