{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Case I/O"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "AMS supprots multiple case formats."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Still, first import the `ams` library and configure the logger level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "import ams"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "ams.config_logger(stream_level=20)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### AMS Execel"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Parsing input file \"/Users/jinningwang/work/ams/ams/cases/ieee14/ieee14_uced.xlsx\"...\n",
      "Input file parsed in 0.0644 seconds.\n",
      "All bus type are PQ, adjusted given load and generator connection status.\n",
      "System set up in 0.0023 seconds.\n",
      "-> Systen size:\n",
      "Base: 100 MVA; Frequency: 60 Hz\n",
      "14 Buses; 20 Lines; 5 Static Generators\n",
      "Active load: 2.24 p.u.; Reactive load: 0.95 p.u.\n",
      "-> Data check results:\n",
      "DCED: DCOPF, DCOPF2, ED, RTED\n",
      "DCUC: UC\n",
      "DED: DOPF\n",
      "PF: DCPF, PFlow\n"
     ]
    }
   ],
   "source": [
    "sp_xlsx = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'),\n",
    "                   setup=True,\n",
    "                   no_output=True,)\n",
    "\n",
    "sp_xlsx.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### AMS JSON"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Parsing input file \"/Users/jinningwang/work/ams/ams/cases/ieee14/ieee14.json\"...\n",
      "Input file parsed in 0.0013 seconds.\n",
      "Zero Line parameters detected, adjusted to default values: rate_c.\n",
      "All bus type are PQ, adjusted given load and generator connection status.\n",
      "System set up in 0.0024 seconds.\n",
      "-> Systen size:\n",
      "Base: 100 MVA; Frequency: 60 Hz\n",
      "14 Buses; 20 Lines; 5 Static Generators\n",
      "Active load: 2.24 p.u.; Reactive load: 0.95 p.u.\n",
      "-> Data check results:\n",
      "PF: DCPF, PFlow\n"
     ]
    }
   ],
   "source": [
    "sp_json = ams.load(ams.get_case('ieee14/ieee14.json'),\n",
    "                   setup=True,\n",
    "                   no_output=True,)\n",
    "\n",
    "sp_json.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### MATPOWER"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function mpc2system in module ams.io.matpower:\n",
      "\n",
      "mpc2system(mpc: dict, system) -> bool\n",
      "    Load an mpc dict into an empty AMS system.\n",
      "\n",
      "    Revised from ``andes.io.matpower.mpc2system``.\n",
      "\n",
      "    Note that `mbase` in mpc is converted to `Sn`, but it is not actually used in\n",
      "    MATPOWER nor AMS.\n",
      "\n",
      "    In converted AMS system, StaticGen idxes are 1-based, while the sequence follow\n",
      "    the order of the original MATPOWER data.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    system : ams.system.System\n",
      "        Empty system to load the data into.\n",
      "    mpc : dict\n",
      "        mpc struct names : numpy arrays\n",
      "\n",
      "    Returns\n",
      "    -------\n",
      "    bool\n",
      "        True if successful, False otherwise.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.io.matpower.mpc2system)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Parsing input file \"/Users/jinningwang/work/ams/ams/cases/matpower/case14.m\"...\n",
      "CASE14    Power flow data for IEEE 14 bus test case.\n",
      "Input file parsed in 0.0032 seconds.\n",
      "Zero Line parameters detected, adjusted to default values: rate_a, rate_b, rate_c.\n",
      "System set up in 0.0017 seconds.\n",
      "-> Systen size:\n",
      "Base: 100.0 MVA; Frequency: 60 Hz\n",
      "14 Buses; 20 Lines; 5 Static Generators\n",
      "Active load: 2.59 p.u.; Reactive load: 0.74 p.u.\n",
      "-> Data check results:\n",
      "DCED: DCOPF, DCOPF2\n",
      "DED: DOPF\n",
      "PF: DCPF, PFlow\n"
     ]
    }
   ],
   "source": [
    "sp_mp = ams.load(ams.get_case('matpower/case14.m'),\n",
    "                 setup=True,\n",
    "                 no_output=True,)\n",
    "\n",
    "sp_mp.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that AMS also supports PYPOWER format py-file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PSS/E RAW"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "AMS also supports PSS/E v32/v33 RAW format for power flow analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Parsing input file \"/Users/jinningwang/work/ams/ams/cases/ieee14/ieee14.raw\"...\n",
      "Input file parsed in 0.0043 seconds.\n",
      "Zero Line parameters detected, adjusted to default values: rate_c.\n",
      "All bus type are PQ, adjusted given load and generator connection status.\n",
      "System set up in 0.0022 seconds.\n",
      "-> Systen size:\n",
      "Base: 100.0 MVA; Frequency: 60.0 Hz\n",
      "14 Buses; 20 Lines; 5 Static Generators\n",
      "Active load: 2.24 p.u.; Reactive load: 0.95 p.u.\n",
      "-> Data check results:\n",
      "PF: DCPF, PFlow\n"
     ]
    }
   ],
   "source": [
    "sp_raw = ams.load(ams.get_case('ieee14/ieee14.raw'),\n",
    "                  setup=True,\n",
    "                  no_output=True,)\n",
    "\n",
    "sp_raw.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the meanwhile, AMS supports multiple output formats."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "xlsx file written to \"out.xlsx\"\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ams.io.xlsx.write(system=sp_xlsx,\n",
    "                  outfile='out.xlsx',)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "os.remove('out.xlsx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, JSON output formats can be achieved by using `ams.io.json.write`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As of v1.0.10, follo wrapper methods are provided for easy converting the case to different formats:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### MATPOWER MPC"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function to_mpc in module ams.system:\n",
      "\n",
      "to_mpc(self)\n",
      "    Export an AMS system to a MATPOWER dict.\n",
      "    Wrapper method for `ams.io.matpower.system2mpc`.\n",
      "\n",
      "    Returns\n",
      "    -------\n",
      "    dict\n",
      "        A dictionary representing the MATPOWER case.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    - In the `gen` section, slack generators are listed before PV generators.\n",
      "    - For uncontrolled generators (`ctrl.v == 0`), their max and min power\n",
      "      limits are set to their initial power (`p0.v`) in the converted MPC.\n",
      "    - In the converted MPC, the indices of area (`bus[:, 6]`) and zone (`bus[:, 10]`)\n",
      "      may differ from the original MPC. However, the mapping relationship is preserved.\n",
      "      For example, if the original MPC numbers areas starting from 1, the converted\n",
      "      MPC may number them starting from 0.\n",
      "    - The coefficients `c2` and `c1` in the generator cost data are scaled by\n",
      "      `baseMVA`.\n",
      "    - Unlike the XLSX and JSON converters, this implementation uses value providers\n",
      "      (`v`) instead of vin. As a result, any changes made through `model.set` will be\n",
      "      reflected in the generated MPC.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.system.System.to_mpc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### MATPOWER M-file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function to_m in module ams.system:\n",
      "\n",
      "to_m(self, outfile: str, overwrite: bool = None)\n",
      "    Export an AMS system to a MATPOWER M-file.\n",
      "    Wrapper method for `ams.io.matpower.write`.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    outfile : str\n",
      "        The output file name.\n",
      "    overwrite : bool, optional\n",
      "        If True, overwrite the existing file. Default is None.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    - In the `gen` section, slack generators are listed before PV generators.\n",
      "    - For uncontrolled generators (`ctrl.v == 0`), their max and min power\n",
      "      limits are set to their initial power (`p0.v`) in the converted MPC.\n",
      "    - In the converted MPC, the indices of area (`bus[:, 6]`) and zone (`bus[:, 10]`)\n",
      "      may differ from the original MPC. However, the mapping relationship is preserved.\n",
      "      For example, if the original MPC numbers areas starting from 1, the converted\n",
      "      MPC may number them starting from 0.\n",
      "    - The coefficients `c2` and `c1` in the generator cost data are scaled by\n",
      "      `baseMVA`.\n",
      "    - Unlike the XLSX and JSON converters, this implementation uses value providers\n",
      "      (`v`) instead of vin. As a result, any changes made through `model.set` will be\n",
      "      reflected in the generated MPC.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.system.System.to_m)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### AMS XLSX"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function to_xlsx in module ams.system:\n",
      "\n",
      "to_xlsx(self, outfile: str, overwrite: bool = None)\n",
      "    Export an AMS system to an Excel file.\n",
      "    Wrapper method for `ams.io.xlsx.write`.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    outfile : str\n",
      "        The output file name.\n",
      "    overwrite : bool, optional\n",
      "        If True, overwrite the existing file. Default is None.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.system.System.to_xlsx)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### AMS JSON"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function to_json in module ams.system:\n",
      "\n",
      "to_json(self, outfile: str, overwrite: bool = None)\n",
      "    Export an AMS system to a JSON file.\n",
      "    Wrapper method for `ams.io.json.write`.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    outfile : str\n",
      "        The output file name.\n",
      "    overwrite : bool, optional\n",
      "        If True, overwrite the existing file. Default is None.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.system.System.to_json)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PSS/E v33 RAW\n",
    "\n",
    "This method has not been fully benchmarked yet!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function to_raw in module ams.system:\n",
      "\n",
      "to_raw(self, outfile: str, overwrite: bool = None)\n",
      "    Export an AMS system to a v33 PSS/E RAW file.\n",
      "    Wrapper method for `ams.io.psse.write_raw`.\n",
      "\n",
      "    This method has not been fully benchmarked yet!\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    outfile : str\n",
      "        The output file name.\n",
      "    overwrite : bool, optional\n",
      "        If True, overwrite the existing file. Default is None.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(ams.system.System.to_raw)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ams",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.0"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}