{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "69f25fc5",
   "metadata": {},
   "source": [
    "# Channel Operating Margin (COM)\n",
    "This example shows how to use PyAEDT for COM analysis.\n",
    "These standards are supported:\n",
    "\n",
    "- 50GAUI_1_C2C\n",
    "- 100GAUI_2_C2C\n",
    "- 200GAUI_4\n",
    "- 400GAUI_8\n",
    "- 100GBASE_KR4\n",
    "- 100GBASE_KP4"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffd85c00",
   "metadata": {},
   "source": [
    "<img src=\"_static\\com_eye.png\" width=\"500\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9331c43e",
   "metadata": {},
   "source": [
    "## What is COM?\n",
    "\n",
    "- COM was developed as part of IEEE 802.3bj, 100GBASE Ethernet.\n",
    "- COM is a figure of merit for an S-parameter representing a high-speed SerDes channel.\n",
    "- COM is the ratio between eye height and noise."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25119d10",
   "metadata": {},
   "source": [
    "```math\n",
    "COM = 20 * log10 (A_signal / A_noise)\n",
    "```\n",
    "\n",
    "Keywords: **COM**, **signal integrity**, **virtual compliance**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "525d89c3",
   "metadata": {},
   "source": [
    "## Perform imports\n",
    "Perform required imports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d1d5f44e",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import tempfile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "49b9d64e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ansys.aedt.core.visualization.post.spisim import SpiSim\n",
    "from ansys.aedt.core.visualization.post.spisim_com_configuration_files import \\\n",
    "    com_parameters\n",
    "from pyedb.misc.downloads import download_file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28a01c32",
   "metadata": {},
   "source": [
    "## Create temporary directory and download example files\n",
    "\n",
    "Create a temporary directory where downloaded data or\n",
    "dumped data can be stored.\n",
    "If you'd like to retrieve the project data for subsequent use,\n",
    "the temporary folder name is given by ``temp_folder.name``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38604e8b",
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_folder = tempfile.TemporaryDirectory(suffix=\".ansys\")\n",
    "\n",
    "thru = download_file(\n",
    "    directory=\"com_analysis\",\n",
    "    filename=\"SerDes_Demo_02_Thru.s4p\",\n",
    "    destination=temp_folder.name,\n",
    ")\n",
    "fext_2_9 = download_file(\n",
    "    directory=\"com_analysis\",\n",
    "    filename=\"FCI_CC_Long_Link_Pair_2_to_Pair_9_FEXT.s4p\",\n",
    "    destination=temp_folder.name,\n",
    ")\n",
    "fext_5_9 = download_file(\n",
    "    directory=\"com_analysis\",\n",
    "    filename=\"FCI_CC_Long_Link_Pair_5_to_Pair_9_FEXT.s4p\",\n",
    "    destination=temp_folder.name,\n",
    ")\n",
    "next_11_9 = download_file(\n",
    "    directory=\"com_analysis\",\n",
    "    filename=\"FCI_CC_Long_Link_Pair_11_to_Pair_9_NEXT.s4p\",\n",
    "    destination=temp_folder.name,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f119c603",
   "metadata": {},
   "source": [
    "## Run COM analysis\n",
    "PyAEDT calls SPISim for COM analysis. For supported standardes, see the PyAEDT documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "538e029d",
   "metadata": {},
   "source": [
    "Set ``port_order=\"EvenOdd\"`` when the S-parameter has this port order:\n",
    "\n",
    "1 - 2\n",
    "\n",
    "3 - 4\n",
    "\n",
    "Set ``port_order=\"Incremental\"`` when the S-parameter has this port order:\n",
    "\n",
    "1 - 3\n",
    "\n",
    "2 - 4"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d2d7c91",
   "metadata": {},
   "outputs": [],
   "source": [
    "spi_sim = SpiSim(thru)\n",
    "com_results = spi_sim.compute_com(\n",
    "    standard=1,  # 50GAUI-1-C2C\n",
    "    port_order=\"EvenOdd\",\n",
    "    fext_s4p=[fext_5_9, fext_5_9],\n",
    "    next_s4p=next_11_9,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "021e12e2",
   "metadata": {},
   "source": [
    "## Print COM values\n",
    "There are two COM values reported by the definition of the standard:\n",
    "\n",
    "- Case 0: COM value in dB when big package is used.\n",
    "- Case 1: COM value in dB when small package is used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64fbb058",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(*com_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67441daf",
   "metadata": {},
   "source": [
    "## View COM report\n",
    "A complete COM report is generated in the temporary folder in HTML format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b90da6c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(temp_folder.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f2e64bc",
   "metadata": {},
   "source": [
    "<img src=\"_static\\com_report.png\" width=\"800\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a88e9c1b",
   "metadata": {},
   "source": [
    "## Run COM analysis on custom configuration file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32d4866d",
   "metadata": {},
   "source": [
    "### Export template configuration file in JSON format"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b592a63f",
   "metadata": {},
   "outputs": [],
   "source": [
    "custom_json = os.path.join(temp_folder.name, \"custom.json\")\n",
    "spi_sim.export_com_configure_file(custom_json, standard=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87d8c7b7",
   "metadata": {},
   "source": [
    "Modify the custom JSON file as needed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9096890c",
   "metadata": {},
   "source": [
    "### Import configuration file and run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb21cbac",
   "metadata": {},
   "outputs": [],
   "source": [
    "com_results = spi_sim.compute_com(\n",
    "    standard=0,  # Custom\n",
    "    config_file=custom_json,\n",
    "    port_order=\"EvenOdd\",\n",
    "    fext_s4p=[fext_5_9, fext_5_9],\n",
    "    next_s4p=next_11_9,\n",
    ")\n",
    "print(*com_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3033e8f0",
   "metadata": {},
   "source": [
    "## Export SPISim supported configuration file\n",
    "You can use the exported configuration file in the SPISim GUI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f861ec09",
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "com_param = com_parameters.COMParametersVer3p4()\n",
    "com_param.load(custom_json)\n",
    "custom_cfg = os.path.join(temp_folder.name, \"custom.cfg\")\n",
    "com_param.export_spisim_cfg(custom_cfg)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3b581d0",
   "metadata": {},
   "source": [
    "PyAEDT also supports the SPISim configuration file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1e867a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "com_results = spi_sim.compute_com(\n",
    "    standard=0, config_file=custom_cfg, port_order=\"EvenOdd\"\n",
    ")  # Custom\n",
    "print(*com_results)"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}