paramrf 0.35.0__tar.gz → 0.35.3__tar.gz

{paramrf-0.35.0 → paramrf-0.35.3}/CONTEXT.md

@@ -45,13 +45,25 @@ on a value overrides a field's default; scales never multiply.
 
 `prf.update` returns a copy of a model with the parts a **selector** picks
 replaced. A selector is a parameter name, a glob over names, a sequence of
-names, or a callable. A **validated update** (a name → value mapping,
-`value=`, `fixed=`) goes through each parameter's constructor; a **structural
-update** (a new node, `fn=`) bypasses validation. `prf.replace` is the plain
+names, or a callable. A **validated update** (a name → value mapping
+entry, `value=`, `fixed=`) goes through each parameter's constructor; a
+**structural update** (a new node, `fn=`, or a mapping entry whose value is a
+`Model`, keyed by sub-model name) bypasses validation. In a mapping the tier is
+decided per entry by the value's type. `prf.replace` is the plain
 dataclass field replace, not an update.
 
 *Avoid:* "set values", "with values"; "update" for an optimiser step.
 
+### Derived model
+
+A model computed from a **base** model and **new parameters** by a function,
+`f(base, **new)`, built with `prf.derived` (ADR-0003). The base and the new
+parameters are held once; the base keeps its names and each new parameter is
+named by its keyword. Used to derive a more complete model from a nominal one
+(a wet section, a cut) and, by nesting, to share a parameter across parts.
+
+*Avoid:* "tie with new parameters", "shared parameter" as a separate concept.
+
 ### Parameter values
 
 `prf.param_values`: a name-keyed dict of arrays in one space, the form values

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.0
+Version: 0.35.3
 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.3}/docs/adr/0002-parameter-api.md

@@ -85,6 +85,7 @@ replaced. Exactly one form says what with:
 
 ```python
 prf.update(model, {'L1.L': 3.0, 'C1.C': 2.0})      # parameter values by name
+prf.update(model, {'east': wet(model.east), 'west': wet(model.west)})  # sub-models by name
 prf.update(model, 'L1.L', value=3.0)               # parameter fields on a selection
 prf.update(model, 'cable.*', fixed=True)           # fixed state
 prf.update(model, 'cascade[1]', Short())           # a new sub-model or node
@@ -98,19 +99,26 @@ It replaces `with_values`, `with_free`, `with_fixed`, `Module.map`,
 
 - **Selectors** are parameter names, `fnmatch` globs over them, sequences of
   names, or callables, resolved by the #133 resolver.
-- **Two tiers, set by the form.** The mapping, `value=` and `fixed=` forms go
+- **Two tiers, set by the form, or per entry in a mapping.** The `value=` and
+  `fixed=` forms, and mapping entries whose value is an array or `Param`, go
   through each parameter's constructor: they validate bounds and keep the prior,
-  constraint, scale, name and metadata. The node and `fn=` forms are
-  structural: they bypass converters and validation, and the docstring says so.
+  constraint, scale, name and metadata. The node and `fn=` forms, and mapping
+  entries whose value is a `Model`, are structural: they bypass converters and
+  validation, and the docstring says so.
 - **The mapping form** is recognised only as the second positional argument
-  with every key a string. Its values may be arrays or `Param` objects. Any
+  with every key a string. A value that is an array or `Param` is keyed by a
+  parameter name, and `space=` applies to it. A value that is a `Model` is keyed
+  by a sub-model name (`'cascade[1]'`, a named module's name) and replaces that
+  sub-model as the node form does (amended by #168, so several sub-models can be
+  replaced in one call). One mapping may mix both; a model for a parameter name,
+  or a value for a sub-model name, raises. Any
   other second argument is a selector, and a form mismatch raises an error that
   lists the forms.
 - **`fixed=`** is additive. `fixed=False` frees a parameter even if it was
   created fixed, and parameters the selector does not match are untouched.
   "Only these free" is `update(update(m, '*', fixed=True), names, fixed=False)`.
-- **Value forms keep the jit cache key.** The mapping, `value=` and `space=`
-  forms never change the treedef, or any leaf's dtype, shape or `weak_type`
+- **Value forms keep the jit cache key.** Mappings of values only, and the
+  `value=` and `space=` forms, never change the treedef, or any leaf's dtype, shape or `weak_type`
   (decision 10). Changing `fixed=`, or any structural form, changes the model's
   structure, and recompiling is expected.
 - **Not an optimiser step.** In fitting, "updates" also means Optax gradient
@@ -122,7 +130,8 @@ anything name-based.
 
 `prf.tie(model, target, source, fn=identity)` stays a separate verb. A tie is
 not a replacement: its target is recomputed from its source every time the
-model is unwrapped.
+model is unwrapped. A relation that needs a quantity the model does not yet hold
+is a derived model (`prf.derived`, ADR-0003), not a tie.
 
 ### 4. Reading: `prf.params` and `prf.param_values`
 

paramrf-0.35.3/docs/adr/0003-derived-models.md

@@ -0,0 +1,80 @@
+# ADR-0003: Derived models add parameters by deriving from a whole base
+
+Status: accepted (2026-09)
+
+## Context
+
+Users constrain parameters by relations such as "this part is computed from
+those". `prf.tie` (ADR-0002) covers this only when every source already exists
+in the model. It fails when the relation needs a quantity that has no home.
+
+The driving case (#167): a coaxial cable of total length L is wet for its first
+w and dry for the rest. The model is `wet ** dry`, but neither section can hold
+L. L must stay a parameter with its own prior, possibly a joint lab prior with
+the cable's geometry and material, and must not drift as w changes. w is a new
+parameter with its own prior. Several parts may share one such parameter (one
+water level on both arms of a balun).
+
+## Decision
+
+`prf.derived` turns a function `f(base, **new)` returning a model into a
+constructor of a **derived model**: a `pmrf.Model` (`pmrf.models.Derived`, an
+`AbstractBuilder`) that holds the base and the new parameters once and calls
+`f` on their unwrapped values whenever the model is used. `f` is a static field,
+so models derived with one function share a jit cache entry.
+
+### The base stays whole
+
+The derived model holds the base model itself, not parameters extracted from
+it. This is what makes two things work with no extra machinery:
+
+- **Joint priors.** A `Probabilistic` prior over the base (length with
+  geometry) is still in the tree, over the same parameters, under the same
+  names, and scores unchanged.
+- **Sharing with no ties.** `f` uses the base's geometry in both sections; it
+  is one parameter because it is stored once. No tie is needed to keep the wet
+  and dry sections consistent.
+
+### Naming rule
+
+- The base's parameters keep exactly the names they have on the base. The
+  wrapper is transparent to the name resolver, and the base's own name moves to
+  the derived model (unless `name=` is given), so a container prefixes as usual.
+- Each new parameter is named by its keyword; a keyword that clashes with a
+  base name raises.
+- Nothing produced inside `f` is named: it is not in the tree.
+
+A values dict saved from a fit of the base therefore applies unchanged to the
+derived model.
+
+### Sharing by nesting
+
+A parameter shared by several parts is a new parameter of a derived model at
+the level that owns them. Its `f` derives each part, passing the same value,
+and puts them back with the multi-model `prf.update` mapping form (#168). A
+derived model can be the base of another; names accumulate flat. There is no
+separate "shared parameter" concept.
+
+## Rejected options
+
+- **A tie with new parameters** (`tie(..., new={...})` and other tie-centric
+  designs). L ends up separate from the geometry and material, so no joint prior
+  covers them, and the dry section needs extra ties to share the geometry.
+- **A separate "add parameters" function** followed by a tie. Two steps for one
+  idea, and the added parameters have no relation to the model until tied, with
+  the same joint-prior problem.
+- **Reparametrising a parameter in place** (replace L by a function of new
+  parameters). The relation is not a function of one parameter: it replaces
+  part of the model's structure (one section becomes two), and L loses its prior.
+- **Builder classes.** They work, but an engineer should not need a class for
+  a one-off constraint, and topology code had to reach into the class.
+  `prf.derived` is a builder whose class is generated from a function.
+
+## Consequences
+
+- `tie` is unchanged.
+- `f` must be pure and its output's structure must not depend on parameter
+  values, as for `AbstractBuilder.build`. It should be defined once at module
+  level; a lambda made on every call recompiles.
+- A non-model return is only detected when the model is used, since calling
+  `f` eagerly at construction would repeat the work at every nesting level.

{paramrf-0.35.0 → paramrf-0.35.3}/docs/api/index.rst

@@ -31,6 +31,7 @@ Working with Parameters
    pmrf.log_prior
    pmrf.update
    pmrf.tie
+   pmrf.derived
 
 
 Main Modules

{paramrf-0.35.0 → paramrf-0.35.3}/docs/core_concepts/parameter_names.rst

@@ -40,9 +40,49 @@ Models are immutable, so :func:`pmrf.update` returns a changed copy rather than
 
 **Structural changes** replace a part of the model outright, either with a new sub-model or parameter, or with the result of a function applied to the old part. These put exactly what they are given in place, without validation. An exact name can select a whole sub-model here, whereas a glob only ever matches parameters.
 
+A dictionary passed to :func:`pmrf.update` can hold both kinds. Each entry is decided by its value: a :class:`pmrf.Model` keyed by a sub-model name is a structural change, unvalidated, while an array or parameter keyed by a parameter name is a value change. For example, ``prf.update(system, {'east_coax': new_east, 'west_coax': new_west})`` replaces two sub-models in one call. A model given for a parameter name, or a value given for a sub-model name, raises an error.
+
 The distinction matters for performance. RF methods such as :meth:`pmrf.Model.s` are compiled just-in-time, and the compiled code is only reused while the model's structure is unchanged. Changing a parameter's value keeps that structure, so it never triggers a recompile. Fixing or freeing a parameter, making a structural change, or swapping in a parameter with a different constraint or scale all change the structure, and so recompile. On a large circuit this can take noticeably longer than an evaluation, so value changes should be preferred inside loops.
 
 Tied Parameters
 ~~~~~~~~~~~~~~~
 
 Rather than setting a parameter once, :func:`pmrf.tie` derives it from another parameter. The target is removed from the model's parameters and is recomputed from its source every time the model is evaluated, so it follows the source through updates, optimization and sampling. Because it is no longer a parameter, it also no longer has a name. The tie function receives and returns physical values, and derivatives with respect to the source include the path through the tie.
+
+Derived Models
+~~~~~~~~~~~~~~
+
+A tie can only relate parameters that already exist. Sometimes a relation needs a quantity the model has no place for. Take a coaxial cable of total length ``L`` that is wet for its first ``w``: the model is a wet section cascaded with a dry one, but neither section can hold ``L``, and ``L`` should keep its own prior (perhaps a joint lab prior with the cable's geometry) rather than drift as ``w`` changes.
+
+:func:`pmrf.derived` handles this by starting from the nominal model and deriving a more complete one. It turns a function ``f(base, **new)`` into a constructor: the base model and the new parameters are held once, and ``f`` is called on them whenever the model is used.
+
+.. code-block:: python
+
+    @prf.derived
+    def wet(cable, wet_length, wet_ep_r):
+        wet = prf.replace(cable, length=wet_length,
+                          dielectric=prf.replace(cable.dielectric, ep_r=wet_ep_r))
+        dry = prf.replace(cable, length=cable.length - wet_length)
+        return wet ** dry
+
+    coax = wet(coax, wet_length=prf.Random(Uniform(0, 20), scale=1e-3),
+               wet_ep_r=prf.Random(Uniform(1, 80)))
+
+The result is an ordinary :class:`pmrf.Model` with the same port count, so it can be cascaded, wrapped, tied and fitted like any other. Its parameters are the base's, under exactly the names they had on the base, plus one per keyword (``wet_length`` and ``wet_ep_r``). The cable's geometry is used by both sections but is still one parameter, and a values dictionary saved from a fit of the dry cable applies unchanged. Nothing built inside ``f`` is named, and the derived model takes the base's name, so inside a named container everything is prefixed as usual.
+
+Like a tie function, ``f`` receives physical values. Inside it, use :func:`pmrf.replace` to change fields of the object in hand, and :func:`pmrf.update` to change parts reached by name. ``f`` must be pure and must return a model whose structure does not depend on parameter values. It is part of the model's static structure, so define it once at module level: a lambda created anew on every call recompiles.
+
+A parameter shared by several parts is expressed by deriving at the level that owns it. A derived model can be the base of another, and names accumulate flat, so one water level for both arms of a balun is:
+
+.. code-block:: python
+
+    @prf.derived
+    def wet_balun(system, wet_length):
+        return prf.update(system, {
+            'east_coax': wet(system.east_coax, wet_length=wet_length, wet_ep_r=80.0),
+            'west_coax': wet(system.west_coax, wet_length=wet_length, wet_ep_r=80.0),
+        })
+
+    balun = wet_balun(balun, wet_length=prf.Random(Uniform(0, 20), scale=1e-3))
+
+Here ``prf.params(balun)`` holds a single ``wet_length``, and changing it changes both cables. The reasoning behind this design is recorded in ADR-0003.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.0
+Version: 0.35.3
 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.3}/paramrf.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ docs/_templates/autosummary/function.rst
 docs/_templates/autosummary/module.rst
 docs/adr/0001-line-modelling-architecture.md
 docs/adr/0002-parameter-api.md
+docs/adr/0003-derived-models.md
 docs/agents/domain.md
 docs/agents/issue-tracker.md
 docs/agents/triage-labels.md
@@ -115,6 +116,7 @@ pmrf/models/adapters/base.py
 pmrf/models/adapters/bridge.py
 pmrf/models/adapters/callable.py
 pmrf/models/adapters/delegated.py
+pmrf/models/adapters/derived.py
 pmrf/models/adapters/static.py
 pmrf/models/adapters/wrapped.py
 pmrf/models/components/__init__.py
@@ -211,8 +213,10 @@ 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_derived.py
 tests/test_models/test_interconnected.py
 tests/test_models/test_lines.py
 tests/test_models/test_lines_skrf_matrix.py

{paramrf-0.35.0 → paramrf-0.35.3}/pmrf/__init__.py

@@ -46,6 +46,7 @@ except PackageNotFoundError:
 from pmrf.models import (
     Model as Model,
     is_model as is_model,
+    derived as derived,
 )
 from pmrf.modules.base import Module as Module, is_module as is_module
 from pmrf.frequency import Frequency as Frequency
@@ -125,6 +126,7 @@ __all__ = [
     # Base/Core
     "Model",
     "is_model",
+    "derived",
     "Module",
     "is_module",
     "Frequency",

{paramrf-0.35.0 → paramrf-0.35.3}/pmrf/models/__init__.py

@@ -198,6 +198,11 @@ from pmrf.models.adapters.wrapped import (
     Wrapped as Wrapped,
 )
 
+from pmrf.models.adapters.derived import (
+    Derived as Derived,
+    derived as derived,
+)
+
 # Compatibility re-exports. Parameter-aware wrappers live under ``pmrf.modules``.
 from pmrf.modules import Tied as Tied, Probabilistic as Probabilistic
 

{paramrf-0.35.0 → paramrf-0.35.3}/pmrf/models/adapters/__init__.py

@@ -7,7 +7,7 @@ This includes scikit-rf Networks, EM simulation software, and generic Equinox mo
 """
 
 from pmrf.models.adapters import base
-from pmrf.models.adapters import bridge, static, callable, delegated, wrapped
+from pmrf.models.adapters import bridge, static, callable, delegated, derived, wrapped
 
 __all__ = [
     "base",
@@ -15,6 +15,7 @@ __all__ = [
     "static",
     "callable",
     "delegated",
+    "derived",
     "wrapped",
 ]
 

paramrf-0.35.3/pmrf/models/adapters/derived.py

@@ -0,0 +1,144 @@
+"""Models derived from an existing model with new parameters."""
+
+import copy
+import functools
+from typing import Any, Callable
+
+from pmrf.models.base import Model
+from pmrf.models.adapters.delegated import AbstractBuilder
+from pmrf.utils import field
+
+
+class Derived(AbstractBuilder):
+    """A model computed by a function from a base and new named parameters.
+
+    Built by :func:`derived`, which documents the contract. The base and the new
+    parameters are held once, as ``operands = (base, new)``, and ``fn(base, **new)``
+    is called on their unwrapped values whenever the model is used. Parameter names
+    see through this wrapper: the base's names are unchanged and each new parameter
+    is named by its keyword.
+    """
+
+    #: The base, and the new parameters keyed by keyword.
+    operands: tuple[Any, dict[str, Any]]
+
+    #: The function building the model from the base and the new parameters.
+    fn: Callable[..., Model] = field(static=True, kw_only=True)
+
+    def build(self) -> Model:
+        base, new = self.operands
+        model = self.fn(base, **new)
+        if not isinstance(model, Model):
+            raise TypeError(
+                f"The derived function {getattr(self.fn, '__qualname__', self.fn)!r} must "
+                f"return a pmrf.Model; got {type(model).__name__}."
+            )
+        return model
+
+
+def _unnamed(node: Any) -> Any:
+    """Returns `node` without its own name, so its parameters keep their names below it."""
+    if getattr(node, 'name', None) is None:
+        return node
+    node = copy.copy(node)
+    object.__setattr__(node, 'name', None)
+    return node
+
+
+def derived(fn: Callable[..., Model]) -> Callable[..., Derived]:
+    """
+    Turns a function of a base model and new parameters into a derived model constructor.
+
+    A derived model starts from a nominal model and derives a more complete one that
+    captures some artifact (a wet section, degraded copper, a cut). The decorated
+    function is called as ``f(base, **new)``: exactly one positional base (a model,
+    or any collection of models and parameters) and keyword arguments that are the
+    new parameters (a :class:`pmrf.Param`, or anything :func:`pmrf.as_param`
+    accepts). It returns a :class:`pmrf.Model` that holds the base and the new
+    parameters once, and calls `fn` on them whenever the model is used.
+
+    `fn` receives the base and the new parameters as the model is unwrapped, so
+    parameters arrive as physical values, as for :func:`pmrf.tie`. It must return a
+    :class:`pmrf.Model`, must be pure, and its output's structure and port count must
+    not depend on parameter values. Inside `fn`, use :func:`pmrf.replace` for fields
+    of the object in hand and :func:`pmrf.update` for parts reached by name.
+
+    **Names.** The base's parameters keep the names they have on the base, and each
+    new parameter is named by its keyword. Nothing produced inside `fn` is named. The
+    derived model takes the base's name unless ``name=`` is passed, so a container
+    prefixes both as usual. A derived model can be the base of another, and names
+    accumulate flat; a parameter shared by several parts is expressed by deriving at
+    the level that owns it.
+
+    `fn` is a static part of the model: two models derived with the same function
+    share a jit cache entry. Define it once at module level; a lambda created on every
+    call recompiles.
+
+    Parameters
+    ----------
+    fn : Callable
+        ``fn(base, **new) -> Model``.
+
+    Returns
+    -------
+    Callable
+        ``constructor(base, *, name=None, **new) -> Derived``.
+
+    Raises
+    ------
+    TypeError
+        On a call with other than one positional base or with no new parameters, or
+        (when the model is used) if `fn` does not return a model.
+    ValueError
+        If a keyword clashes with a parameter name of the base.
+
+    Examples
+    --------
+    A coaxial cable of total length ``L`` that is wet for its first ``wet_length``:
+
+    .. code-block:: python
+
+        @prf.derived
+        def wet(cable, wet_length, wet_ep_r):
+            wet = prf.replace(cable, length=wet_length,
+                              dielectric=prf.replace(cable.dielectric, ep_r=wet_ep_r))
+            dry = prf.replace(cable, length=cable.length - wet_length)
+            return wet ** dry
+
+        coax = wet(coax, wet_length=prf.Random(Uniform(0, 20), scale=1e-3),
+                   wet_ep_r=prf.Random(Uniform(1, 80)))
+        prf.params(coax)   # the cable's names, plus 'wet_length' and 'wet_ep_r'
+    """
+    from pmrf.parameters import as_param, params
+
+    @functools.wraps(fn)
+    def constructor(*args, name: str | None = None, **new) -> Derived:
+        if len(args) != 1:
+            raise TypeError(
+                f"{fn.__name__}() takes exactly one positional base and new parameters as "
+                f"keywords, e.g. {fn.__name__}(model, wet_length=...); got {len(args)} "
+                "positional arguments."
+            )
+        if not new:
+            raise TypeError(f"{fn.__name__}() needs at least one new parameter as a keyword.")
+        base = args[0]
+        clashes = sorted(set(new) & set(params(base)))
+        if clashes:
+            raise ValueError(
+                f"{fn.__name__}(): new parameter names {clashes} clash with parameters of "
+                "the base. Choose different keywords."
+            )
+        coerced = {}
+        for key, value in new.items():
+            value = as_param(value)
+            if value.name is not None:
+                value = _unnamed(value)
+            coerced[key] = value
+        if name is None:
+            name = getattr(base, 'name', None)
+        return Derived((_unnamed(base), coerced), fn=fn, name=name)
+
+    return constructor
+
+
+__all__ = ["Derived", "derived"]

{paramrf-0.35.0 → paramrf-0.35.3}/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