{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d22b091b",
   "metadata": {},
   "source": [
    "# Import Ports\n",
    "This example shows how to import ports. In this example, we are going to\n",
    "\n",
    "- Download an example board\n",
    "- Create a configuration file\n",
    "  - Add a circuit port between two nets\n",
    "  - Add a circuit port between two pins\n",
    "  - Add a circuit port between two pin groups\n",
    "  - Add a circuit port between two coordinates\n",
    "  - Add a coax port\n",
    "  - Add a port reference to the nearest pin\n",
    "  - Add distributed ports\n",
    "- Import the configuration file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "870408f0",
   "metadata": {},
   "source": [
    "## Import the required packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0c7f677b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "from pathlib import Path\n",
    "import tempfile\n",
    "\n",
    "from ansys.aedt.core.downloads import download_file\n",
    "\n",
    "from pyedb import Edb\n",
    "\n",
    "AEDT_VERSION = \"2024.2\"\n",
    "NG_MODE = False\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5425dc24",
   "metadata": {},
   "source": [
    "Download the example PCB data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9076e32",
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_folder = tempfile.TemporaryDirectory(suffix=\".ansys\")\n",
    "file_edb = download_file(source=\"edb/ANSYS-HSD_V1.aedb\", destination=temp_folder.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd9539de",
   "metadata": {},
   "source": [
    "## Load example layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5a7b79ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "edbapp = Edb(file_edb, edbversion=AEDT_VERSION)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "908384e7",
   "metadata": {},
   "source": [
    "## Create an empty dictionary to host all configurations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "998064e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg = dict()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c157fe6",
   "metadata": {},
   "source": [
    "## Add a circuit port between two nets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "888c0372",
   "metadata": {},
   "source": [
    "Keywords\n",
    "\n",
    "- **name**. Name of the port.\n",
    "- **Reference_designator**. Reference designator of the component.\n",
    "- **type**. Type of the port. Supported types are 'circuit', 'coax'\n",
    "- **positive_terminal**. Positive terminal of the port. Supported types are 'net', 'pin', 'pin_group', 'coordinates'\n",
    "- **negative_terminal**. Negative terminal of the port. Supported types are 'net', 'pin', 'pin_group', 'coordinates',\n",
    "'nearest_pin'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9b34a96",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_1 = {\n",
    "    \"name\": \"port_1\",\n",
    "    \"reference_designator\": \"X1\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"positive_terminal\": {\"net\": \"PCIe_Gen4_TX2_N\"},\n",
    "    \"negative_terminal\": {\"net\": \"GND\"},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c3e9288",
   "metadata": {},
   "source": [
    "## Add a circuit port between two pins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f87e93e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_2 = {\n",
    "    \"name\": \"port_2\",\n",
    "    \"reference_designator\": \"C375\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"positive_terminal\": {\"pin\": \"1\"},\n",
    "    \"negative_terminal\": {\"pin\": \"2\"},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5554dd07",
   "metadata": {},
   "source": [
    "## Add a circuit port between two pin groups"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "79cc5b75",
   "metadata": {},
   "outputs": [],
   "source": [
    "pin_groups = [\n",
    "    {\"name\": \"U9_5V_1\", \"reference_designator\": \"U9\", \"pins\": [\"32\", \"33\"]},\n",
    "    {\"name\": \"U9_GND\", \"reference_designator\": \"U9\", \"net\": \"GND\"},\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ca9e7400",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_3 = {\n",
    "    \"name\": \"port_3\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"positive_terminal\": {\"pin_group\": \"U9_5V_1\"},\n",
    "    \"negative_terminal\": {\"pin_group\": \"U9_GND\"},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f3b1205",
   "metadata": {},
   "source": [
    "## Add a circuit port between two coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a63b6c7",
   "metadata": {},
   "source": [
    "Keywords\n",
    "\n",
    "- **layer**. Layer on which the terminal is placed\n",
    "- **point**. XY coordinate the terminal is placed\n",
    "- **net**. Name of the net the terminal is placed on"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6c762c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_4 = {\n",
    "    \"name\": \"port_4\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"positive_terminal\": {\"coordinates\": {\"layer\": \"1_Top\", \"point\": [\"104mm\", \"37mm\"], \"net\": \"AVCC_1V3\"}},\n",
    "    \"negative_terminal\": {\"coordinates\": {\"layer\": \"Inner6(GND2)\", \"point\": [\"104mm\", \"37mm\"], \"net\": \"GND\"}},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e06dcf2",
   "metadata": {},
   "source": [
    "## Add a coax port"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3b7031b",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_5 = {\"name\": \"port_5\", \"reference_designator\": \"U1\", \"type\": \"coax\", \"positive_terminal\": {\"pin\": \"AM17\"}}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6a308e5",
   "metadata": {},
   "source": [
    "## Add a port reference to the nearest pin"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "591ddc2a",
   "metadata": {},
   "source": [
    "Keywords\n",
    "\n",
    "- **reference_net**. Name of the reference net\n",
    "- **search_radius**. Reference pin search radius in meter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2a1a627",
   "metadata": {},
   "outputs": [],
   "source": [
    "port_6 = {\n",
    "    \"name\": \"port_6\",\n",
    "    \"reference_designator\": \"U15\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"positive_terminal\": {\"pin\": \"D7\"},\n",
    "    \"negative_terminal\": {\"nearest_pin\": {\"reference_net\": \"GND\", \"search_radius\": 5e-3}},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b27ed65b",
   "metadata": {},
   "source": [
    "## Add distributed ports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30286424",
   "metadata": {},
   "source": [
    "Keywords\n",
    "\n",
    "- **distributed**. Whether to create distributed ports. When set to True, ports are created per pin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5900366",
   "metadata": {},
   "outputs": [],
   "source": [
    "ports_distributed = {\n",
    "    \"name\": \"ports_d\",\n",
    "    \"reference_designator\": \"U7\",\n",
    "    \"type\": \"circuit\",\n",
    "    \"distributed\": True,\n",
    "    \"positive_terminal\": {\"net\": \"VDD_DDR\"},\n",
    "    \"negative_terminal\": {\"net\": \"GND\"},\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98474c7c",
   "metadata": {},
   "source": [
    "## Add setups in configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2f8b2ad9",
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg[\"pin_groups\"] = pin_groups\n",
    "cfg[\"ports\"] = [port_1, port_2, port_3, port_4, port_5, port_6, ports_distributed]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "902e2871",
   "metadata": {},
   "source": [
    "## Write configuration into as json file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86331bd0",
   "metadata": {},
   "outputs": [],
   "source": [
    "file_json = Path(temp_folder.name) / \"edb_configuration.json\"\n",
    "with open(file_json, \"w\") as f:\n",
    "    json.dump(cfg, f, indent=4, ensure_ascii=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9e71139",
   "metadata": {},
   "source": [
    "## Import configuration into example layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "888279b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "edbapp.configuration.load(config_file=file_json)\n",
    "edbapp.configuration.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc753400",
   "metadata": {},
   "source": [
    "## Review"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "743c386b",
   "metadata": {},
   "outputs": [],
   "source": [
    "edbapp.ports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eaff2fc1",
   "metadata": {},
   "source": [
    "## Save and close Edb\n",
    "The temporary folder will be deleted once the execution of this script is finished. Replace **edbapp.save()** with\n",
    "**edbapp.save_as(\"C:/example.aedb\")** to keep the example project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2527a911",
   "metadata": {},
   "outputs": [],
   "source": [
    "edbapp.save()\n",
    "edbapp.close()"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}