module-content/docs/source/api_usage/3.4-Using-the-Configuration-File-API.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using the Configuration File API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction to the Configuration File API\n",
    "\n",
    "\n",
    "The Configuration File API is used to generate power system models that can be solved in GridLab-D or OpenDSS based on the original CIM XML model. The load profile and ZIP parameters can be modified from the nominal values prior to model creation and export.\n",
    "\n",
    "In the Application Components diagram (explained in detail with sample code in [GridAPPS-D Application Structure](../overview/2.4-GridAPPS-D-Application-Structure.ipynb)), the Configuration File API is used for configuring parallel simulations and exporting the power system model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![04-config-sim-export](images/3.4/04_config_sim_export.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API Syntax Overview\n",
    "\n",
    "__Application passes query to GridAPPS-D Platform__\n",
    "\n",
    "First, the application creates a query message for requesting information about the desired power system configuration in the format of a JSON string or equivalant Python dictionary object. The syntax of this message is explained in detail below.\n",
    "\n",
    "The application then passes the query through the Configuration File API to the GridAPPS-D Platform, which publishes it to a queue channel on the GOSS Message Bus. If the app is authenticated and authorized to pass queries, the query message is delivered to the Configuration Manager.\n",
    "\n",
    "__GridAPPS-D Platform responds to Application query__\n",
    "\n",
    "The Configuration Manager obtains the CIM XML file for the desired power system model and then converts it to the desired output format with all of the requested changes to the model. The Configuration File API then returns the desired information back to the application as a JSON message (for Y-Bus or partial models) or export the files to the directory specified in the "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Communication Channel\n",
    "\n",
    "All queries passed to the PowerGrid Models API need to use the correct communication channel, which is obtained using the [GridAPPS-D Topics library](../api_usage/3.1-API-Communication-Channels.ipynb). \n",
    "\n",
    "The PowerGrid Model API uses a `/queue/` channel to pull power system model info from the the Blazegraph Database. The base static string used is `goss.gridappsd.process.request.config`, which can be called using the `.CONFIG` method from the topics library.\n",
    "\n",
    "When developing in python, it is recommended to use the `.CONFIG` method. When using the STOMP client in GridAPPS-D VIZ, it is necessary to use the base static string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Structure of a Query Message\n",
    "\n",
    "Queries passed to Configuration File API are formatted as python dictionaries or equivalent JSON scripts wrapped as a python string. \n",
    "\n",
    "The accepted set of key-value pairs for the Configuration File API query message is\n",
    "\n",
    "```\n",
    "message = {\n",
    "    \"configurationType\": \"INSERT QUERY HERE\",\n",
    "    \"parameters\": {\n",
    "        \"key1\": \"value1\",\n",
    "        \"key2\": \"value2\"}        \n",
    "}\n",
    "```\n",
    "\n",
    "The components of the message are as follows:\n",
    "\n",
    "* `\"configurationType\":` -- Specifies the type of configuration file requested.\n",
    "\n",
    "\n",
    "* `\"parameters\":` -- Specifies any specific power system model parameters. Values depend on the particular configurationType.\n",
    "\n",
    "\n",
    "The usage of each of these message components are explained in detail with code block examples below. \n",
    "\n",
    "__Important__: Be sure to pay attention to placement of commas ( __,__ ) at the end of each JSON line. Commas are placed at the end of each line _except_ the last line. Incorrect comma placement will result in a JsonSyntaxException. \n",
    "\n",
    "All of the queries are passed to the Configuration API using the `.get_response(topic, message)` method for the GridAPPS-D platform connection variable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Specifying the configurationType\n",
    "\n",
    "Below are the possible `configurationType` key-value pairs that are used to specify the type of each query. Executable code block examples are provided for each of the requests in the subsections below.\n",
    "\n",
    "The first group of _configurationType_ key-value pairs are for queries for information related to the GridLab-D GLM files and settings:\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D All\"` -- [Export all GridLab-D files](#Export-all-GridLab-D-Files)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Base GLM\"` -- [Query for GridLab-D base GLM file](#Query-for-GridLab-D-Base-GLM-File)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Symbols\"` -- [Query for GridLab-D symbols file](#Query-for-GridLab-D-Symbols-File)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Simulation Output\"` -- [Query for available measurement types](#Query-for-GridLab-D-Measurement-Types)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "The second group of _configurationType_ key-value pairs are for queries for OpenDSS model files\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"DSS All\"` -- [Export all OpenDSS model files](#Export-all-OpenDSS-Files)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"DSS Base\"` -- [Query for OpenDSS version of power system model](#Query-for-OpenDSS-Base-File)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"DSS Coordinate\"` -- [Query for list of OpenDSS XY coordinates](#Query-for-OpenDSS-Coordinate-File)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"YBus Export\"` -- [Export Y-Bus matrix from OpenDSS](#Query-for-Y-Bus-Matrix)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "The third group of _configurationType_ are for queries for CIM dictionary and feeder index files:\n",
    "\n",
    "* `\"configurationType\": \"CIM Dictionary\"` -- [Query for python dictionary of CIM XML model](#Query-for-Model-Dictionary)\n",
    "\n",
    "\n",
    "* `\"configurationType\": \"CIM Feeder Index\"` -- [Query for python dictionary of model mRIDs](#Query-for-CIM-Feeder-Index)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying for GridLab-D Configuration Files\n",
    "\n",
    "This section outlines the details of key-value pairs for the possible queries associated with each value of the `queryMeasurement` key listed above for obtaining or exporting GridLAB-D Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Export all GridLab-D Files\n",
    "\n",
    "This API call generates all the GLM files necessary to solve the power system model in GridLab-D. The query returns a directory where the set of GLM files are located inside the GridAPPS-D docker container.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D All\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                \"directory\":                          output directory as string ,\n",
    "                \"simulation_name\":                    string ,\n",
    "                \"simulation_start_time\":              epoch time number ,\n",
    "                \"simulation_duration\":                number ,\n",
    "                \"simulation_id\":                      number ,\n",
    "                \"simulation_broker_host\":             string ,\n",
    "                \"simulation_broker_port\":             number ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"i_fraction\":                         number ,\n",
    "                \"p_fraction\":                         number ,\n",
    "                \"z_fraction\":                         number ,\n",
    "                \"load_scaling_factor\":                number ,\n",
    "                \"schedule_name\":                      string ,\n",
    "                \"solver_method\":                      string }\n",
    "                \n",
    "```\n",
    "\n",
    "The numeric values for the key-value pairs associated with `parameters` can be written as number or as strings. The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example: Export IEEE 13 node model with constant current loads to GLM files :__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"GridLAB-D All\",\n",
    "    \"parameters\": {\n",
    "        \"directory\": \"/tmp/gridlabdsimulation/\",\n",
    "        \"model_id\": model_mrid,\n",
    "        \"simulation_id\": \"12345678\",\n",
    "        \"simulation_name\": \"mysimulation\",\n",
    "        \"simulation_start_time\": \"1518958800\",\n",
    "        \"simulation_duration\": \"60\",\n",
    "        \"simulation_broker_host\": \"localhost\",\n",
    "        \"simulation_broker_port\": \"61616\",\n",
    "        \"schedule_name\": \"ieeezipload\",\n",
    "        \"load_scaling_factor\": \"1.0\",\n",
    "        \"z_fraction\": \"0.0\",\n",
    "        \"i_fraction\": \"1.0\",\n",
    "        \"p_fraction\": \"0.0\",\n",
    "        \"solver_method\": \"NR\" }\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 120)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.data.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![gridlab-d-all](images/3.4/GridLAB_D_All.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Note:__ The output directory is inside the GridAPPS-D Docker Container, not in your Ubuntu or Windows environment. To access the files, it is necessary to change directories to those inside the docker container.\n",
    "\n",
    "Open a new Ubuntu terminal and run:\n",
    "* `docker exec -it gridappsd-docker_gridappsd_1 bash`\n",
    "* `cd /tmp/gridlabdsimulation`\n",
    "* `ls -l`\n",
    "\n",
    "To copy the files to your regular directory, use the `docker cp` command. For help using docker, see [Docker Shortcuts](../installation/1.6-Docker-Shortcuts.ipynb) on working with Docker containers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![config-file-docker-directory](images/3.4/config_file_docker_directory.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for GridLab-D Base GLM File\n",
    "\n",
    "This API call generates a single GLM file that contains the entire power system model that can be solved in GridLab-D. The query returns the entire model GLM file wrapped in a python dictionary.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Base GLM\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"i_fraction\":                         number ,\n",
    "                \"p_fraction\":                         number ,\n",
    "                \"z_fraction\":                         number ,\n",
    "                \"load_scaling_factor\":                number ,\n",
    "                \"schedule_name\":                      string }\n",
    "                \n",
    "```\n",
    "\n",
    "The numeric values for the key-value pairs associated with `parameters` can be written as number or as strings. The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 1: Create GLM base file using nominal load values:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"GridLAB-D Base GLM\",\n",
    "    \"parameters\": {\"model_id\": model_mrid}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![GridLAB-D-Base-GLM](images/3.4/GridLAB_D_Base_GLM.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 2: Create GLM base file using all constant current loads and hourly load curve:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"GridLAB-D Base GLM\",\n",
    "    \"parameters\": {\n",
    "        \"model_id\": model_mrid,\n",
    "        \"load_scaling_factor\": \"1.0\",\n",
    "        \"z_fraction\": 0.0,\n",
    "        \"i_fraction\": 1.0,\n",
    "        \"p_fraction\": \"0.0\",\n",
    "        \"schedule_name\": \"ieeezipload\"}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![GridLAB-D-Base-GLM-2](images/3.4/GridLAB_D_Base_GLM_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for GridLab-D Symbols File\n",
    "\n",
    "This API call generates a python dictionary with all the XY coordinates used by GridLab-D when running a simulation.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Symbols\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"simulation_id\":                      number }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"GridLAB-D Symbols\",\n",
    "    \"parameters\": { \"model_id\": model_mrid }\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for GridLab-D Measurement Types\n",
    "\n",
    "This API call returns a list of device names and types of available measurement in the GridLab-D format (__not__ CIM classes or measurement mRIDs)\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"GridLab-D Simulation Output\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                 \"simulation_id\":                      number or string,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                 \"model_id\":                           mRID as string }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"GridLAB-D Simulation Output\",\n",
    "    \"parameters\": {\"simulation_id\": \"paste sim_id here\"}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![GridLAB-D-simulation-output](images/3.4/GridLAB_D_Simulation_Output.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying for OpenDSS Configuration Files\n",
    "\n",
    "\n",
    "This section outlines the details of key-value pairs for the possible queries associated with each value of the `queryMeasurement` key listed above for obtaining or exporting OpenDSS Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Export all OpenDSS Files\n",
    "\n",
    "This API call generates all the OpenDSS files necessary to solve the power system model in OpenDSS. The query returns a directory where the set of DSS files are located. \n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"DSS All\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                \"directory\":                          desired output directory as string ,\n",
    "                \"simulation_name\":                     string ,\n",
    "                \"simulation_start_time\":              epoch time number ,\n",
    "                \"simulation_duration\":                number ,\n",
    "                \"simulation_id\":                      number ,\n",
    "                \"simulation_broker_host\":             string ,\n",
    "                \"simulation_broker_port\":             number ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"i_fraction\":                         number ,\n",
    "                \"p_fraction\":                         number ,\n",
    "                \"z_fraction\":                         number ,\n",
    "                \"load_scaling_factor\":                number ,\n",
    "                \"schedule_name\":                      string ,\n",
    "                \"solver_method\":                      string }\n",
    "                \n",
    "```\n",
    "\n",
    "The numeric values for the key-value pairs associated with `parameters` can be written as number or as strings. The key-value pairs can be specified in any order.\n",
    "\n",
    "__Example: Export IEEE 13 node model with constant current loads to DSS files :__\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"DSS All\",\n",
    "    \"parameters\": {\n",
    "        \"directory\": \"/tmp/dsssimulation/\",\n",
    "        \"model_id\": model_mrid,\n",
    "        \"simulation_id\": \"12345678\",\n",
    "        \"simulation_name\": \"ieee13\",\n",
    "        \"simulation_start_time\": \"1518958800\",\n",
    "        \"simulation_duration\": \"60\",\n",
    "        \"simulation_broker_host\": \"localhost\",\n",
    "        \"simulation_broker_port\": \"61616\",\n",
    "        \"schedule_name\": \"ieeezipload\",\n",
    "        \"load_scaling_factor\": \"1.0\",\n",
    "        \"z_fraction\": \"0.0\",\n",
    "        \"i_fraction\": \"1.0\",\n",
    "        \"p_fraction\": \"0.0\",\n",
    "        \"solver_method\": \"NR\" }\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Note:__ The output directory is inside the GridAPPS-D Docker Container, not in your Ubuntu or Windows environment. To access the files, it is necessary to change directories to those inside the docker container.\n",
    "\n",
    "Open a new Ubuntu terminal and run:\n",
    "* `docker exec -it gridappsd-docker_gridappsd_1 bash`\n",
    "* `cd /tmp/dssdsimulation`\n",
    "* `ls -l`\n",
    "\n",
    "To copy the files to your regular directory, use the `docker cp` command. For help using docker, see [Docker Shortcuts](../installation/1.6-Docker-Shortcuts.ipynb) on working with Docker containers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for OpenDSS Base File\n",
    "\n",
    "This API call generates a single DSS file that contains the entire power system model that can be solved in OpenDSS. The query returns the entire model DSS file wrapped in a python dictionary.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"DSS Base\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"i_fraction\":                         number ,\n",
    "                \"p_fraction\":                         number ,\n",
    "                \"z_fraction\":                         number ,\n",
    "                \"load_scaling_factor\":                number ,\n",
    "                \"schedule_name\":                      string }\n",
    "                \n",
    "```\n",
    "\n",
    "The numeric values for the key-value pairs associated with `parameters` can be written as number or as strings. The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 1: Create OpenDSS base file using nominal load values:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"DSS Base\",\n",
    "    \"parameters\": {\"model_id\": model_mrid}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![dss-base](images/3.4/DSS_Base.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 2: Create OpenDSS base file using all constant current loads and hourly load curve:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "message = {\n",
    "    \"configurationType\": \"DSS Base\",\n",
    "    \"parameters\": {\n",
    "        \"model_id\": model_mrid,\n",
    "        \"load_scaling_factor\": \"1.0\",\n",
    "        \"z_fraction\": 0.0,\n",
    "        \"i_fraction\": 1.0,\n",
    "        \"p_fraction\": \"0.0\",\n",
    "        \"schedule_name\": \"ieeezipload\"}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![dss-base-2](images/3.4/DSS_Base_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for OpenDSS Coordinate File\n",
    "\n",
    "This API call generates a file with all the XY coordinates used by OpenDSS when plotting the feeder.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"DSS Coordinate\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"simulation_id\":                      number }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"DSS Coordinate\",\n",
    "    \"parameters\": {\"model_id\": model_mrid}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![dss-coordinate](images/3.4/DSS_Coordinate.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for Y-Bus Matrix\n",
    "\n",
    "This API call generates a Y-Bus matrix from __either__ the model mRID or the simulation id.\n",
    "\n",
    "__Note:__ The GridAPPS-D platform currently does not have an in-built topology processor, so the Y-Bus matrix is NOT updated during the simulation to reflect switching actions or transformer tap changes that happen in real time.  \n",
    "\n",
    "Real-time Y-bus matrix output will be available from the future Dynamic Y-bus Service from the GridAPPS-D App Toolbox.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"YBus Export\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OR\n",
    "                \"simulation_id\":                      number }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 1: Request Y-Bus for IEEE 13 node model using model mRID:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"YBus Export\",\n",
    "    \"parameters\": {\"model_id\": model_mrid}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ybus-export](images/3.4/YBus_Export.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 2: Request Y-Bus for IEEE 13 node model with all loads set as constant current using model mRID:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"YBus Export\",\n",
    "    \"parameters\": {\n",
    "        \"model_id\": model_mrid,\n",
    "        \"load_scaling_factor\": \"2.0\",\n",
    "        \"schedule_name\": \"ieeezipload\",\n",
    "        \"z_fraction\": \"0.4\",\n",
    "        \"i_fraction\": \"0.3\",\n",
    "        \"p_fraction\": \"0.3\" }\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ybus-export-3](images/3.4/YBus_Export_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Example 3: Obtain Y-Bus from simulation_id:__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "viz_simulation_id = \"paste id here\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "topic = \"goss.gridappsd.process.request.config\"\n",
    "\n",
    "message = {\n",
    "    \"configurationType\":\"YBus Export\",\n",
    "    \"parameters\":{\"simulation_id\": viz_simulation_id}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ybus-export-3](images/3.4/YBus_Export_3.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying for CIM Dictionary Files\n",
    "\n",
    "\n",
    "This section outlines the details of key-value pairs for the possible queries associated with each value of the `queryMeasurement` key listed above for obtaining or dictionaries of CIM objects used for file conversion."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for Model Dictionary\n",
    "\n",
    "This API generates a python dictionary which maps the CIM mRIDs of objects in the power system model to names of model objects used in other simulators.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"CIM Dictionary\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"simulation_id\":                      number }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "topic = \"goss.gridappsd.process.request.config\"\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"CIM Dictionary\",\n",
    "    \"parameters\":{\"model_id\": model_mrid}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message, timeout = 30)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![cim-dictionary](images/3.4/CIM_Dictionary.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query for CIM Feeder Index \n",
    "\n",
    "This API call returns a python dictionary of the available feeders in the Blazegraph database of power system models.\n",
    "\n",
    "Configuration File request key-value pair:\n",
    "\n",
    "* `\"configurationType\": \"CIM Feeder Index\"`\n",
    "\n",
    "The `parameters` key has a set of required values as well as some optional values:\n",
    "\n",
    "```\n",
    "\"parameters\": {     REQUIRED KEYS                   REQUIRED VALUES\n",
    "                \"model_id\":                           mRID as string ,\n",
    "                    OPTIONAL KEYS                  OPTIONAL VALUES\n",
    "                \"simulation_id\":                      number }\n",
    "                \n",
    "```\n",
    "The key-value pairs can be specified in any order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gridappsd import topics as t\n",
    "topic = t.CONFIG\n",
    "\n",
    "message = {\n",
    "    \"configurationType\": \"CIM Feeder Index\",\n",
    "    \"parameters\":{}\n",
    "}\n",
    "\n",
    "gapps.get_response(topic, message)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query can be passed through the STOMP client by specifying the `goss.gridappsd.process.request.config` topic and the same message without the python wrapping:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![cim-feeder-index](images/3.4/CIM_Feeder_Index.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![GridAPPS-D_narrow.png](../images/GridAPPS-D_narrow.png)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}