Merge pull request scikit-rf#1166 from Asachoo/NetworkConnect

A generalized/abstract Network connection method

doc/source/tutorials/Connecting_Networks.ipynb

@@ -145,11 +145,13 @@
    "metadata": {},
    "source": [
     "## Cascading Multi-port Networks\n",
-    "To make specific connections between multi-port Networks, two solutions are available, which mostly depends of the complexity of the circuit one wants to build:\n",
+    "To make specific connections between multi-port Networks, three solutions are available, which mostly depends of the complexity of the circuit one wants to build:\n",
     "\n",
     "* For reduced number of connection(s): the `connect()` function\n",
     "\n",
-    "* For advanced connections between many arbitrary N-port Networks, the `Circuit` object is more relevant since it allows defining explicitly the connections between ports and Networks. For more information, please refer to the [Circuit documentation](Circuit.ipynb). \n",
+    "* For intermediate complexity, where you might need to connect multiple Networks in parallel to the same intersection, we offer the `parallelconnect()` method. This method provides a balance between the simplicity of `connect()` and the flexibility of `Circuit` object. For more information, please refer to the [`paralleconnect()` documentation](../api/generated/skrf.network.paralleconnect.html#skrf.network.paralleconnect)\n",
+    "\n",
+    "* For more advanced connections between many arbitrary N-port Networks, the `Circuit` object is more relevant since it allows defining explicitly the connections between ports and Networks. For more information, please refer to the [Circuit documentation](Circuit.ipynb). \n",
     "\n",
     "As an example, terminating one of the port of an a 3-port Network, such as an ideal 3-way splitter:\n",
     "\n",
@@ -184,6 +186,23 @@
     "terminated_tee"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`parallelconnect()` method also could handle this situation with just a slight change in syntax.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "terminated_tee_par = rf.parallelconnect([tee, delayshort], [1, 0])\n",
+    "terminated_tee_par"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -217,6 +236,93 @@
     "rf.connect(tee, 1, line, 0)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Networks Connections from the Intersection Perspective\n",
+    "In the previous example, we briefly introduced the `parallelconnect()` method. In this section, We will detail the application scenarios of the `parallelconnect()` method with multiple examples and provide recommendations for comparing the three solutions.\n",
+    "\n",
+    "Firstly, let's consider the simplest example: inner-connecting any two ports within an N-port `Network`. This will result in an (N-2)-port `Network`.\n",
+    "\n",
+    "<img src=\"figures/networks_innerconnect_2_port.svg\" width=\"600\">\n",
+    "\n",
+    "Here, we can use the `innerconnect()` method to connect any two ports within the N-port `Network`\n",
+    "\n",
+    "```\n",
+    "# Innerconnect the m'th and n'th ports of the N-Port Network\n",
+    "inner_network = rf.innerconnect(nport_network, m, n)\n",
+    "```\n",
+    "\n",
+    "`parallelconnect()` method could handle inner-connect situation like this:\n",
+    "\n",
+    "```\n",
+    "inner_network_par = rf.parallelconnect(nport_network, [[m, n]])\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you anticipate the need to inner-connect more than 2 ports, the `innerconnect()` method will not suffice for this task. You'll need to look into using `tee` (`splitter`) or `Circuit` object to achieve your goal. However, `parallelconnect()` offers a straightforward solution for such cases,\n",
+    "\n",
+    "```\n",
+    "# An example of inner-connect a list of ports of a N-port Network\n",
+    "ports_list = [[m, n, ..., y, z]]\n",
+    "inner_network2_par = rf.parallelconnect(nport_network, ports_list)\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The second example involves connecting two multi-port Networks. As this cases has been previously demonstrated, we will not delve into it again here.\n",
+    "\n",
+    "Moving on, let's consider the parallel connection of multiple multi-port `Networks`. A common application of this is in the construction of a `T-type filter circuit`, figure taken from [electroniclinic.com](https://www.electroniclinic.com/filter-circuit-and-need-of-filters-in-electronics/#google_vignette)\n",
+    "\n",
+    "![T-type filter circuit](figures/t_type_filter.png)\n",
+    "\n",
+    "Let's ignore the specific details and just compare the three methods in implementing this example, you can use:\n",
+    "\n",
+    "```\n",
+    "# 1. Connect() method with tee\n",
+    "t_type_filter_ntwk = rf.connect(L1, 1, tee, 0)\n",
+    "t_type_filter_ntwk = rf.connect(t_type_filter_ntwk, 1, C, 0)\n",
+    "t_type_filter_ntwk = rf.connect(t_type_filter_ntwk, 2, L2, 0)\n",
+    "t_type_filter_ntwk\n",
+    "\n",
+    "# 2. Circuit object method\n",
+    "cnx = [\n",
+    "    [(port1, 0), (L1, 0)],\n",
+    "    [(port2, 0), (C , 1)],\n",
+    "    [(port3, 0), (L2, 1)],\n",
+    "    [(L1, 1), (C, 0), (L2, 0)]\n",
+    "]\n",
+    "t_type_filter_ckt = rf.Circuit(cnx)\n",
+    "t_type_filter_ntwk = t_type_filter_ckt.network\n",
+    "t_type_filter_ntwk\n",
+    "\n",
+    "# 3. Parallelconnect() method\n",
+    "t_type_filter_ntwk = rf.parallelconnect([L1, C, L2], [1, 0, 0])\n",
+    "t_type_filter_ntwk\n",
+    "```\n",
+    "\n",
+    "It can be seen that the `parallelconnect()` method can realize the construction of `T-type filter` circuit very clearly and concisely."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this section, we compared the `parallelconnect()` method and compared it with the `connect()/innerconnect()` method and the `Circuit` object for connecting `Networks` from an intersection perspective.\n",
+    "\n",
+    "The `parallelconnect()` method excels in handling multiple parallel connections with minimal effort, making it ideal for scenarios requiring simplicity and efficiency. In contrast, the `connect()/innerconnect()` method is better suited for simpler, sequential connections, while the `Circuit` object is for complex, multi-layered connections with greater control.\n",
+    "\n",
+    "From the intersection perspective, the `Circuit` object is best for managing complex networks with multiple intersections, a task that exceeds the capabilities of other methods, which are designed for single intersection scenarios. And `innerconnect()/connect()` methods are limited to handling connections between individual or pairs of Networks, `parallelconnect()` removes the restriction on the number of Networks and can efficiently establish connections for multiple Networks in a single line of code, making it particularly advantageous for complex circuits with parallel connections at multiple points."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},