{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e69c4107",
   "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": "b397acac",
   "metadata": {},
   "source": [
    "<img src=\"_static\\com_eye.png\" width=\"500\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ad5d18f",
   "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": "caf004b6",
   "metadata": {},
   "source": [
    "COM = 20 * log10 (A_signal / A_noise)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a43a5614",
   "metadata": {},
   "source": [
    "\n",
    "Keywords: **COM**, **signal integrity**, **virtual compliance**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e957849",
   "metadata": {},
   "source": [
    "## Perform imports\n",
    "Perform required imports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1c93c4ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import tempfile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4ded349e",
   "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",
    ")\n",
    "from pyedb.misc.downloads import download_file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af8ab517",
   "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": "2132b1b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_folder = tempfile.TemporaryDirectory(suffix=\".ansys\")\n",
    "\n",
    "thru = download_file(\n",
    "    directory=\"pyaedt/com_analysis\",\n",
    "    filename=\"SerDes_Demo_02_Thru.s4p\",\n",
    "    destination=temp_folder.name,\n",
    ")\n",
    "fext_2_9 = download_file(\n",
    "    directory=\"pyaedt/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=\"pyaedt/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=\"pyaedt/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": "2787c3b1",
   "metadata": {},
   "source": [
    "## Run COM analysis\n",
    "PyAEDT calls SPISim for COM analysis. For supported standardes, see the PyAEDT documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b48a0373",
   "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": "2c043b4d",
   "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": "9b412c8d",
   "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": "d56d1ed6",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(*com_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e24672d",
   "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": "5112006a",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(temp_folder.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6ed39f8",
   "metadata": {},
   "source": [
    "<img src=\"_static\\com_report.png\" width=\"800\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "711e1d58",
   "metadata": {},
   "source": [
    "## Run COM analysis on custom configuration file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "178a0a2a",
   "metadata": {},
   "source": [
    "### Export template configuration file in JSON format"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0622e602",
   "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": "e0db575e",
   "metadata": {},
   "source": [
    "Modify the custom JSON file as needed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f178316e",
   "metadata": {},
   "source": [
    "### Import configuration file and run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1fb1bada",
   "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": "fb3c94c5",
   "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": "c1113d07",
   "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": "5082f795",
   "metadata": {},
   "source": [
    "PyAEDT also supports the SPISim configuration file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ff690a32",
   "metadata": {},
   "outputs": [],
   "source": [
    "com_results = spi_sim.compute_com(standard=0, config_file=custom_cfg, port_order=\"EvenOdd\")  # Custom\n",
    "print(*com_results)"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}