module-content/docs/source/installation/1.5-Using-GridAPPS-D-Viz.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using the GridAPPS-D Viz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing the GridAPPS-D Viz\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Start the Platform using the `./run.sh` and `./run-gridappsd.sh` scripts as explained in [Running GridAPPS-D](1.4-Running-GridAPPS-D.ipynb). After the Platform is running, open your browser and navigate to [localhost:8080](http://localhost:8080) for desktop installations and `your.server.ip.address:8080` for cloud installations.\n",
    "\n",
    "You should see a splash screen with login options for various user roles. The default username and password combinations are available in the [GOSS core security config file](https://github.com/GRIDAPPSD/GOSS-GridAPPS-D/blob/master/gov.pnnl.goss.gridappsd/conf/pnnl.goss.core.security.userfile.cfg)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![splash-screen](images/1.5/01_login.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `./run-gridappsd.sh` script inside the GridAPPS-D docker container has not been started or has been interrupted, you will see a server connection error when attempting to log in: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![login-error](images/1.5/02_login_error.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After logging in, there are two menus in the top left and right corners. On the left is the main menu for using the VIZ features. On the right is the settings menu."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![menus](images/1.5/menus.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The settings menu contains options for changing the color theme from dark to light, the time zone used, and level of logging detail."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![settings-menu](images/1.5/settings_menu.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![light-theme](images/1.5/light_theme.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On the left is the main menu, which has options for creating simulations, comparing simulations, exploring the databases, and passing API calls through the STOMP client. Each of these will be explained in detail below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![main-menu](images/1.5/main_menu.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a Simulation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a simulation from the GridAPPS-D VIZ, select `Configure New Simulation` from the main menu:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![config-new-sim](images/1.5/config_sim_1.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Power System Configuration\n",
    "\n",
    "The first tab provides a set of menu options to select the desired distribution feeder on which the simulation will run. Detailed descriptions of the available test feeders inlcuded by default are provided in [Available Models in Default \n",
    "Installation](../api_usage/3.3-Using-the-PowerGrid-Models-API.ipynb#Available-Models-in-Default-Installation)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![select-feeder](images/1.5/config_system_config.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simulation Configuration\n",
    "\n",
    "The next tab provides several options for specifying \n",
    "\n",
    "* simulation start time (which determines weather and load data used)\n",
    "* simulation duration in seconds\n",
    "* simulator used\n",
    "* real-time \n",
    "    * If checked, 1 sec of clock time equals 1 sec of simulation time\n",
    "    * If unchecked, the simulation runs as fast as possible (used for generating AI training data)\n",
    "* simulation name\n",
    "* model configuration\n",
    "\n",
    "The model creation configuration textbox enables modification of the model from the default configuration, inlcuding opening/closing switches, changing DER setpoints, and changing the load profile. Details of the syntax for custom configurations is explained in [Simulation Configuration Settings](../api_usage/3.5-Creating-Running-Simulation-API.ipynb#Simulation-Configuration)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![simulation-config](images/1.5/config_sim_config.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Application Configuration\n",
    "\n",
    "The application configuration tab enables selection of which app should run during the simulation. The GridAPPS-D VIZ allows for selection of just one app at a time. Two or more apps may be run simultaneously by starting the simulation through the Simulation API and specifying the desired apps using the [Application Configuration Settings](../api_usage/3.5-Creating-Running-Simulation-API.ipynb#Application-Configuration)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![app-config](images/1.5/config_app_config.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Test Manager Configuration\n",
    "\n",
    "The Test Manager is used to create realistic operational events during the course of the simulation, including faults, communication outages, and custom event scripts.\n",
    "\n",
    "The GridAPPS-D Viz provides a graphic interface for building TestManager event scripts, which are described in detail in [Test Manager Configuration](../api_usage/3.5-Creating-Running-Simulation-API.ipynb#Test-Manager-Configuration).\n",
    "\n",
    "For large models (such as the IEEE 8500 node and 9500 node test systems), it may take several seconds for the model dictionary to load. While the power system model is being queried, a splashscreen will be displayed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![test-manager](images/1.5/config_test_dict.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Communication outages\n",
    "\n",
    "The first option is to create communication outages for both SCADA measurements and equipment control commands by clicking the `CommOutage` radio button.\n",
    "\n",
    "Equipment control commands can be blocked by specifying an Input Outage with options for\n",
    "\n",
    "* start time\n",
    "* end time\n",
    "* all equipment (outages all commands for all equipment if checked)\n",
    "* equipment type\n",
    "* equipment name\n",
    "* affected phases\n",
    "* CIM control attribute\n",
    "\n",
    "To add an Input Outage, specify the desired options, click the `+` button, and then click the `Add event` button at the bottom of the page. The speficied outages will then be displayed on the right side under the `CommOutage` tab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![comm-input-outage](images/1.5/config_test_input_outage.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Measurement sensor outages can be created with an Output Outage with options for \n",
    "\n",
    "* all measurements (all sensors outages if checked)\n",
    "* equipment type\n",
    "* equipment name\n",
    "* affected phases\n",
    "* measurement type (voltage, apparent power, position)\n",
    "\n",
    "To add an Output Outage,  specify the desired options, click the `+` button, and then click the `Add event` button at the bottom of the page. The speficied outages will then be displayed on the right side under the `CommOutage` tab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![config-input-outage](images/1.5/config_test_output_outage.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Equipment Faults\n",
    "\n",
    "The next option is to create a fault on any class of equipment in the model by clicking the `Fault` radio button. Options will appear to select the \n",
    "\n",
    "* equipment type\n",
    "* equipment name\n",
    "* phases to be faulted\n",
    "* type of fault\n",
    "* start time\n",
    "* end time\n",
    "* fault impedance\n",
    "\n",
    "After setting the values, click the `Add event` button. The fault will be displayed on the right side of the screen under the `Fault` tab.\n",
    "\n",
    "When the simulation reaches the event start time, the logical fault simulator traces the fault up to first upstream switch and opens that switch to clear the fault.\n",
    "\n",
    "__Note: The GridLAB-D logical fault simulator currently may not process faults in meshed networks correctly and fail to open the appropriate set of switches to clear the fault. This is a known bug with a workaround to open the appropriate switches using a custom Test Manager event file.__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![config-test-fault](images/1.5/config_test_fault.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Custom Event Files\n",
    "\n",
    "Custom event messages can be written in format of a CIM Difference Message. The format of custom event files is explained in [Scheduled Command Events](../api_usage/3.5-Creating-Running-Simulation-API.ipynb#Scheduled-Command-Events).\n",
    "\n",
    "Event files can be uploaded by clicking the cloud-shaped button and selecting the desired files to be uploaded from your local machine. Click `Open` to upload each file. The custom event will then be displayed under the `Command` tab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![custom-event](images/1.5/config_test_upload.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.5. Service Configuration\n",
    "\n",
    "The last tab is the GridAPPS-D service configuration. This enables selection of particular services that should be run along with the simulation, such as the Sensor Simulator or DNP3 service."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![service-config](images/1.5/config_test_service.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After selecting all desired simulation parameters, click `Submit` to start the simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running a Simulation with VIZ\n",
    "\n",
    "After clicking `Submit`, the GridAPPS-D VIZ will generate a new oneline diagram for the desired feeder. Large models, such as the IEEE 8500 and 9500 node test systems, will take several seconds to load. A splashscreen will be displayed while the oneline diagram is being created."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sim-loading-oneline](images/1.5/sim_loading_oneline.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The oneline diagram will then appear in the main window under the `Simulation` tab.\n",
    "\n",
    "Across the tab are three more tabs for events loaded into the simulation, applications configured to run, and SCADA alarms received during the simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simulation Tab\n",
    "\n",
    "The Simulation Tab contains options for viewing and controlling equipment in the feeder model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![simulation-tab](images/1.5/sim_simulation_tab.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Starting, Pausing, and Stopping a Simulation\n",
    "\n",
    "To start the simulation, click the start button shown above. A \"Simulation is starting\" message will be displayed while the CIM model is imported, converted, and configured to run with the specified simulation parameters.\n",
    "\n",
    "After the simulation starts, a unique simulation ID will be created and displayed in the top left corner. This ID is used by applications to communicate with the correct simulation (as multiple simulations may be running simulateously).\n",
    "\n",
    "The simulation may be paused or stopped using the pause and stop button in the top right corner of the simulation window."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sim-tab-2](images/1.5/sim_simulation_tab_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Viewing equipment names\n",
    "\n",
    "To view the names of devices in the feeder, zoom in using the mouse wheel and hover over the desired piece of equipment. Its name will be displayed below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![view-equip-name](images/1.5/sim_view_equip_name.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Opening and Closing Switches\n",
    "\n",
    "Closed switches are displayed as a red breaker square. Open switches are green.\n",
    "\n",
    "To open or close a switch, left-click on the square and select the desired state from the menu. Click `Apply` "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![select-switch](images/1.5/sim_select_switch.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![open-switch](images/1.5/sim_open_switch.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Events Tab\n",
    "\n",
    "The Events Tab shows events that were created using the TestManager and are scheduled to occur over the course of the simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![events-tab](images/1.5/sim_events_tab.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Alarms Tab\n",
    "\n",
    "The GridAPPS-D Alarms service monitors the GOSS Message Bus and generates alarms for common equipment control actions, including\n",
    "\n",
    "\n",
    "* Switch open/close\n",
    "\n",
    "* Capacitor open/close\n",
    "\n",
    "* Regulator tap change\n",
    "\n",
    "\n",
    "The Alarms Tab is the last one in the top ribbon and diplays a notification with the number of new alarms that have not been viewed:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![post-event-alarms](images/1.5/sim_post_event.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the Alarms Tab is a table indicating the piece of equipment for which the alarm occured, the time of the alarm, and source of the action. \n",
    "\n",
    "Alarms created by events defined in the TestManager (such as fault events and scheduled command events) appear as being created by testmanager1:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![alarm-tab](images/1.5/sim_alarms_tab.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alarms can be acknowledged and removed from the table by clicking the check mark button on the far left of each row.\n",
    "\n",
    "The alarm location can be viewed by clicking on the magnifying glass button. This will switch to the Simulation tab and the particular piece of equipment will be highlighted with an expanding circle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![alarms-tab](images/1.5/sim_alarm_view_alarm.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating Stripchart Plots\n",
    "\n",
    "GridAPPS-D contains a set of basic plotting features for common power system parameters\n",
    "\n",
    "New plots can be added by cliking the trendline button to the right of the pause and stop buttons."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sim-open-plots](images/1.5/sim_open_plot.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A pop-up dialog will appear to select the desired plots with several options:\n",
    "\n",
    "* Created plots -- edit custom plots that have already been created\n",
    "* Plot name -- custom text string that will be displayed as plot title\n",
    "* Component type -- Power (`VA`), Tap (`Pos`), or Voltage (`PNV`) measurement type\n",
    "* Magnitude / Angle\n",
    "    * Apparent power & acos(power factor) for power measurements\n",
    "    * Voltage magnitude & phase angle for voltage measurements\n",
    "* Component -- Component name, type to search\n",
    "* Phases -- Any combination of A, B, and C phases to plot\n",
    "\n",
    "Be sure to click the `Add component` button before clicking `Done`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![images-create-plot](images/1.5/sim_create_plot.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After clicking the `Done` button, the new custom plots will appear in the right-hand pane of the window."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sim-plot-results](images/1.5/sim_plot_results.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternate plot colors are available by switching from the theme from dark to light:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![plots-light-theme](images/1.5/plots_light_theme.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![gridappsd-logo](../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
}