{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# OpenDSS COM/classic APIs\n",
    "\n",
    "*Main concepts of the classic OpenDSS APIs*\n",
    "\n",
    "This document is intended to expose some concepts that are typically overlook by many users when using the classic OpenDSS API.\n",
    "\n",
    "Traditionally, all OpenDSS interfaces and bindings use the same concepts of interaction with the DSS engine. That includes most of the projects developed under DSS-Extensions, \n",
    "\n",
    "On DSS-Extensions, an alternative API is being developed to complement and/or provide a difference experience. Currently, the main results are represented in the [AltDSS-Python](https://dss-extensions.org/AltDSS-Python/) project.\n",
    "\n",
    "To avoid generating confusion, we will use the term \"classic API\" to indicate a set of APIs that follow the concepts developed in the official OpenDSS COM implementation, and \"Alt\" or alternative API for whatever is being developed in AltDSS-Python and similar projects, such as `dss.hpp`.\n",
    "\n",
    "OpenDSS has models for many electric components and controllers, plus general data classes. Besides those, there are several interfaces to interact with specific aspects of the engine. The [official documentation](https://opendss.epri.com/opendss_documentation.html) and other training material usually covers those in detail.\n",
    "\n",
    "## API Hierarchy\n",
    "\n",
    "The API tree as seen from walking from the main interface class `IDSS`, which is exposed from `OpenDSSengine.DSS` in the COM interface, is as follows. \n",
    "\n",
    "For EPRI's OpenDSS implementation, the API materialize in the `OpenDSSengine.DSS` COM object exposes the OpenDSS engine, which is a global singleton in the engine side. That means that the same engine is exposed even if you create another COM object. On DSS-Extensions, the default instance is also created by default for compatibility with the global singleton, but users can create multiple engines by using the `dss.NewContext()` method.\n",
    "\n",
    "Items marked with \"API Extension\" are not present in the COM API, but available as extras on DSS-Extensions.\n",
    "\n",
    "- dss (`IDSS`)\n",
    "    - (dss.)ActiveClass (`IActiveClass`): Manipulate DSS classes directly. For example, if a class doesn't have a dedicated API, this can be used to access the element properties. This is the same as \"dss.ActiveCircuit.ActiveClass\".\n",
    "    - (dss.)DSSProgress (`IDSSProgress`): Manipulate the progress status, GUI etc. *Using this is uncommon.* Not fully supported on DSS-Extensions without custom callbacks.\n",
    "    - (dss.)DSSim_Coms (`IDSSimComs`): Using this is uncommon. Also exposed as \"dss.ActiveCircuit.DSSim_Coms\".\n",
    "    - (dss.)Error (`IError`): The error interface lists error numbers and descriptions. On the official OpenDSS, users need to check this manually if `AllowForms` is disabled. On DSS-Extensions, most errors are directly mapped to errors or exceptions, depending on the programming language.\n",
    "    - (dss.)Events (`IDSSEvents`): The event interface allows using event callbacks that are triggered in certain points of the solution process. *Using this is uncommon.*\n",
    "    - (dss.)Executive (`IDSS_Executive`): Lists the available commands and options, help strings. Allow manipulating options. *Using this is uncommon.*\n",
    "    - (dss.)Parser (`IParser`): Parsing utilities. Using this is uncommon.\n",
    "    - (dss.)Text (`IText`): Pass DSS commands and get results from the DSS engine.\n",
    "    - (dss.)ZIP (`IZIP`) (**API Extension**): Allow loading circuits from ZIP files, without extracting files to the disk.\n",
    "    - (dss.)ActiveCircuit (`ICircuit`): this is effectively the same as `Circuits` (omitted). Contains many properties and methods to access the circuit state, plus the interfaces below.\n",
    "        - ***General engine and circuit operations***\n",
    "        - (dss.ActiveCircuit.)CtrlQueue (`ICtrlQueue`): Inspect or manipulate the control event queue.\n",
    "        - (dss.ActiveCircuit.)Parallel (`IParallel`): OpenDSS Parallel-machine features. *Using this is uncommon.* On DSS-Extensions, prefer native multithreading couple with `dss.NewContext()` instead.\n",
    "        - (dss.ActiveCircuit.)ReduceCkt (`IReduceCkt`): Circuit reduction operations.\n",
    "        - (dss.ActiveCircuit.)Topology (`ITopology`): Get general information like loops and isolated elements; iterate over the circuit graph. Requires an EnergyMeter.\n",
    "        - (dss.ActiveCircuit.)Settings (`ISettings`): Exposes some of the settings for the circuit, some for the whole engine. Some more options/settings are also directly in the main `IDSS` class.\n",
    "        - (dss.ActiveCircuit.)Solution (`ISolution`): Solution manipulation, including settings and general state.\n",
    "        - ***Bus operations***\n",
    "        - (dss.ActiveCircuit.)ActiveBus (`IBus`): Manipulate a specific bus. This is effectively the same as `Buses` (omitted).\n",
    "        - ***Base element operations***\n",
    "        - (dss.ActiveCircuit.)ActiveCktElement (`ICktElement`): This is effectively the same as `ActiveElement` and `CktElements` (omitted).\n",
    "            - (dss.ActiveCircuit.ActiveCktElement.)Properties (`IDSSProperty`): Manipulate the DSS properties of the active element.\n",
    "        - (dss.ActiveCircuit.)ActiveClass (`IActiveClass`): Same as \"dss.ActiveClass\".\n",
    "        - (dss.ActiveCircuit.)ActiveDSSElement (`IDSSElement`)\n",
    "            - (dss.ActiveCircuit.ActiveDSSElement.)Properties (`IDSSProperty`)\n",
    "        - (dss.ActiveCircuit.)PDElements (`IPDElements`)\n",
    "        - ***Dedicated interfaces for specific elements***\n",
    "        - (dss.ActiveCircuit.)CNData (`ICNData`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)CapControls (`ICapControls`)\n",
    "        - (dss.ActiveCircuit.)Capacitors (`ICapacitors`)\n",
    "        - (dss.ActiveCircuit.)Fuses (`IFuses`)\n",
    "        - (dss.ActiveCircuit.)GICSources (`IGICSources`)\n",
    "        - (dss.ActiveCircuit.)Generators (`IGenerators`)\n",
    "        - (dss.ActiveCircuit.)Isources (`IISources`)\n",
    "        - (dss.ActiveCircuit.)LineCodes (`ILineCodes`)\n",
    "        - (dss.ActiveCircuit.)LineGeometries (`ILineGeometries`) (**API Extension**) \n",
    "        - (dss.ActiveCircuit.)LineSpacings (`ILineSpacings`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)Lines (`ILines`)\n",
    "        - (dss.ActiveCircuit.)LoadShapes (`ILoadShapes`)\n",
    "        - (dss.ActiveCircuit.)Loads (`ILoads`)\n",
    "        - (dss.ActiveCircuit.)Meters (`IMeters`)\n",
    "        - (dss.ActiveCircuit.)Monitors (`IMonitors`)\n",
    "        - (dss.ActiveCircuit.)PVSystems (`IPVSystems`)\n",
    "        - (dss.ActiveCircuit.)Reactors (`IReactors`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)Reclosers (`IReclosers`)\n",
    "        - (dss.ActiveCircuit.)RegControls (`IRegControls`)\n",
    "        - (dss.ActiveCircuit.)Relays (`IRelays`)\n",
    "        - (dss.ActiveCircuit.)Sensors (`ISensors`)\n",
    "        - (dss.ActiveCircuit.)Storages (`IStorages`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)SwtControls (`ISwtControls`)\n",
    "        - (dss.ActiveCircuit.)TSData (`ITSData`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)Transformers (`ITransformers`)\n",
    "        - (dss.ActiveCircuit.)Vsources (`IVsources`)\n",
    "        - (dss.ActiveCircuit.)WireData (`IWireData`) (**API Extension**)\n",
    "        - (dss.ActiveCircuit.)XYCurves (`IXYCurves`)\n",
    "\n",
    "*The projects [OpenDSSDirect.jl](https://dss-extensions.org/OpenDSSDirect.jl/) and [OpenDSSDirect.py](https://dss-extensions.org/OpenDSSDirect.py/) follow a slightly different organization (see also [Python APIs](https://dss-extensions.org/python_apis)), but the concepts listed below still apply.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General layout\n",
    "\n",
    "Internally, OpenDSS uses object-oriented concepts and, in the API, different classes in the inheritance tree are exposed by different interface classes.\n",
    "\n",
    "For a more complete view of the classes, as implemented in AltDSS/DSS C-API, see [this class diagram](_static/GVClasses.svg), generated from the Pascal code.\n",
    "\n",
    "A simplified diagram for the Load object follows. In the actual source code, there is `TLoad` and `TLoadObj`. The first one is the container/manager class, while the second is the actual individual object.\n",
    "\n",
    "<center>\n",
    "\n",
    "```mermaid\n",
    "classDiagram\n",
    "  TDSSObject <|-- TDSSCktElement\n",
    "  TDSSCktElement <|-- TPCElement\n",
    "  TPCElement <|-- TLoadObj\n",
    "```\n",
    "\n",
    "</center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the classic API, there is no direct inheritance, instead the components of the class hierarchy are exposed as separate interfaces. That is, the `ILoads` interface (exposed as `dss.ActiveCircuit.Loads`) does not expose inherited methods and properties from the base interfaces and, consequently, a user could be required to use multiple interfaces in order to access all required properties or methods.\n",
    "\n",
    "Referring to hierarchy listed in the previous section, for loads one could use:\n",
    "\n",
    "- (dss.ActiveCircuit.)Loads (`ILoads`): Exposes load-specific data and state, somewhat equivalent to the `TLoadObj` in the class diagram, but `ILoads` mixes elements from multiple classes.\n",
    "- (dss.ActiveCircuit.)ActiveCktElement (`ICktElement`): This would be equivalent to `TDSSCktElement` in the diagram.\n",
    "- (dss.ActiveCircuit.)ActiveDSSElement (`IDSSElement`): This would be equivalent to `TDSSObject` in the diagram.\n",
    "\n",
    "Note that `TPCElement` is not exposed in a dedicated interface, but there is (dss.ActiveCircuit.)PDElements for `TPDElement`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The \"Active...\" paradigm\n",
    "\n",
    "**What is activation?** In the context of OpenDSS, activation usually means select a certain object for manipulation at certain collections. The paradigm is used both in the classic API and in the internal code of OpenDSS, although the implementation on DSS-Extensions has been slowly moving away from that concept for the internal code.\n",
    "\n",
    "One important aspect to consider is that each class with a dedicated tracks an active object, and activating one object from the dedicated interfaces also activates it in the parent interfaces. \n",
    "\n",
    "**There is one exception.** The Lines API, as implemented in EPRI's OpenDSS distribution, does not track the lines by itself. Instead, it relies on the more general \"ActiveCktElement\". Unfortunately, any operation that changes the active circuit element then results in the Lines interface losing track of the current line. This was changed on DSS-Extensions to make the Lines API work like the other APIs, but there is a compatibility flag that could be used if required.\n",
    "\n",
    "For example, activating a Load by name (`dss.ActiveCircuit.Loads.Name = \"target_load_name\"`), iteration (`dss.ActiveCircuit.Loads.First`, `dss.ActiveCircuit.Loads.Next`) or index (`dss.ActiveCircuit.Loads.idx = a_valid_integer_index`) would through the Loads interface:\n",
    "\n",
    "- Sets the target as the active load in the Loads interface.\n",
    "- **Does not** set \"ActiveDSSClass\" to the Load class.\n",
    "- Sets the target as the active circuit element (\"ActiveCktElement\").\n",
    "- Sets the target as the active DSS object (\"ActiveDSSElement\").\n",
    "\n",
    "**But** activating a Load from a more general interface does not activate it on all interfaces.\n",
    "\n",
    "Using `dss.ActiveCircuit.SetActiveElement(\"Load.target_load_name\")` or the `Select` DSS command (`dss.Text.Command = \"Select Load.target_load_name\"`):\n",
    "\n",
    "- **Does not** set the target as the active load in the Loads interface.\n",
    "- Sets \"ActiveDSSClass\" to the Load class.\n",
    "- Sets the target as the active circuit element (\"ActiveCktElement\").\n",
    "- Sets the target as the active DSS object (\"ActiveDSSElement\").\n",
    "\n",
    "`SetActiveElement` is specific to circuit elements, other general elements like LoadShape and Spectrum objects cannot be used with it. The `Select` DSS command, on the other hand, can be used with any DSS object.\n",
    "\n",
    "If \"ActiveDSSClass\" is set to the Load class, activating an element (`dss.ActiveCircuit.ActiveClass.Name = \"target_load_name\"`):\n",
    "\n",
    "- **Does not** set the target as the active load in the Loads interface.\n",
    "- The \"ActiveDSSClass\" is kept as the Load class.\n",
    "- Sets the target as the active circuit element (\"ActiveCktElement\").\n",
    "- Sets the target as the active DSS object (\"ActiveDSSElement\").\n",
    "\n",
    "Important takeaways:\n",
    "\n",
    "- Only when activating the element through the dedicated interfaces activates it there.\n",
    "- Most ways to activate elements sets \"ActiveCktElement\" and \"ActiveDSSElement\". A user can only interact with element at a time through the more general interfaces.\n",
    "- With the exception of Lines in EPRI's official OpenDSS, one can safely use the dedicated interfaces to access some of the data/state. For example, it is safe to use the Loads interface and the Transformers interface in succession without reactivating the elements.\n",
    "- The PDElements interface uses the current ActiveCktElement, so anything that changes that will affect the PDElements interface too.\n",
    "- Other DSS commands can iterate through the internal collections and can change the active elements to point to something else.\n",
    "\n",
    "Since what is activated changes depending on the method used, if the object has a dedicated collection interface, it is recommended that users activate the object through this interface. Sometimes it also useful to activate the collection class using `dss.Circuit.SetActiveClass(\"load\")` or equivalent to complement it, especially for classes that do not expose all relevant properties.\n",
    "\n",
    "The \"ActiveDSSClass\" interface does not track the active element as a dedicated reference. Instead, it uses the current \"ActiveDSSObject\", which can lead to some ill-defined scenarios. For example, it the \"Capacitor\" class is set active and then a Load is activated, the \"ActiveClassName\" can still be help as \"Capacitor\", but the element name return from \"ActiveDSSClass.Name\" is the Load name. See the code snippets for an example.\n",
    "\n",
    "### Buses\n",
    "\n",
    "Like the DSS objects, only a single bus can be activated and references cannot be help since the bus interfaces always reference to the active bus.\n",
    "\n",
    "### Code snippets\n",
    "\n",
    "Here are some code snippets in Python for illustration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If you wish to use comtypes and the official COM DLL, uncomment this block and comment the others in this cell.\n",
    "# import comtypes.client\n",
    "# dss = comtypes.client.CreateObject(\"OpenDSSengine.DSS\")\n",
    "\n",
    "# If you wish to use win32com and the official COM DLL, uncomment this block and comment the others in this cell.\n",
    "# import win32com.client\n",
    "# dss = win32com.client.gencache.EnsureDispatch(\"OpenDSSengine.DSS\")\n",
    "\n",
    "# If you wish to use DSS-Python, uncomment this block and comment the others in this cell.\n",
    "from dss import dss"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Download the examples\n",
    "from dss.examples import download_repo_snapshot\n",
    "BASE_PATH = download_repo_snapshot('.', repo_name='electricdss-tst', use_version=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "CIRCUIT_DSS = BASE_PATH / 'Version8/Distrib/EPRITestCircuits/ckt24/master_ckt24.dss'\n",
    "assert CIRCUIT_DSS.exists()\n",
    "dss.Text.Command = f\"redirect '{CIRCUIT_DSS}'\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's create a function to print what's active:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_active(dss):\n",
    "    print(f\"{dss.ActiveCircuit.Loads.Name=}\")\n",
    "    print(f\"{dss.ActiveCircuit.ActiveClass.ActiveClassName=}\")\n",
    "    print(f\"{dss.ActiveCircuit.ActiveClass.Name=}\")\n",
    "    print(f\"{dss.ActiveCircuit.ActiveDSSElement.Name=}\")\n",
    "    print(f\"{dss.ActiveCircuit.ActiveCktElement.Name=}\")\n",
    "    print(f\"{dss.ActiveCircuit.ActiveBus.Name=}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Initially, the last element that was created is kept active:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='EnergyMeter'\n",
      "dss.ActiveCircuit.ActiveClass.Name='fdr_05410'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='EnergyMeter.fdr_05410'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='EnergyMeter.fdr_05410'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's activate something else: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='EnergyMeter'\n",
      "dss.ActiveCircuit.ActiveClass.Name='cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Capacitor.cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Capacitor.cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "_  = dss.ActiveCircuit.Capacitors.First\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Activating the first capacitor, we can see that the previous active load is kept, but the ActiveCktElement has changed.\n",
    "\n",
    "Let's also activate the Capacitor class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Capacitor'\n",
      "dss.ActiveCircuit.ActiveClass.Name='cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Capacitor.cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Capacitor.cap_g2100pl6500'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "dss.ActiveCircuit.SetActiveClass(\"Capacitor\")\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use this `clear_active` function to make the effects unambiguous:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def clear_active(dss):\n",
    "    _  = dss.ActiveCircuit.Capacitors.First\n",
    "    dss.ActiveCircuit.SetActiveClass(\"Capacitor\")\n",
    "    dss.ActiveCircuit.Loads.Name = 'other_feeders'\n",
    "    dss.ActiveCircuit.SetActiveBusi(0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's activate one of the loads."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['278071200', '559661200', '928661200', '931661200', '475882200', '710035200', '942206200', '306450100', '804302100', '805302100']\n"
     ]
    }
   ],
   "source": [
    "print(dss.ActiveCircuit.Loads.AllNames[:10])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using either `SetActiveElement` or `select Load.{target_name}` leave the previous Load active in the dedicated interface. If users are not aware of this, they can inspect the incorrect object through the Loads interface:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Load'\n",
      "dss.ActiveCircuit.ActiveClass.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "clear_active(dss) # just to make the effects more obvious, not used in real life\n",
    "dss.ActiveCircuit.SetActiveElement('Load.805302100')\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Load'\n",
      "dss.ActiveCircuit.ActiveClass.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveBus.Name='g2000sk5500_n274137_sec_3'\n"
     ]
    }
   ],
   "source": [
    "clear_active(dss) # just to make the effects more obvious, not used in real life\n",
    "dss.Text.Command = 'select Load.805302100'\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='other_feeders'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Load'\n",
      "dss.ActiveCircuit.ActiveClass.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "clear_active(dss) # just to make the effects more obvious, not used in real life\n",
    "dss.ActiveCircuit.SetActiveClass(\"Load\")\n",
    "dss.ActiveCircuit.ActiveClass.Name = \"805302100\"\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And using the dedicated interface:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Capacitor'\n",
      "dss.ActiveCircuit.ActiveClass.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "clear_active(dss) # just to make the effects more obvious, not used in real life\n",
    "dss.ActiveCircuit.Loads.Name = \"805302100\"\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, using both the dedicated interface and the ActiveClass interface, everything is set to the target object. Unless they are using all the related interfaces, users don't need to do this (there is an overhead), but they should be aware of the behavior."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Load'\n",
      "dss.ActiveCircuit.ActiveClass.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='Load.805302100'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "clear_active(dss) # just to make the effects more obvious, not used in real life\n",
    "dss.ActiveCircuit.Loads.Name = \"805302100\"\n",
    "dss.ActiveCircuit.SetActiveClass(\"Load\")\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some commands will iterate over the elements and change the active elements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dss.ActiveCircuit.Loads.Name='805302100'\n",
      "dss.ActiveCircuit.ActiveClass.ActiveClassName='Load'\n",
      "dss.ActiveCircuit.ActiveClass.Name='fdr_05410'\n",
      "dss.ActiveCircuit.ActiveDSSElement.Name='EnergyMeter.fdr_05410'\n",
      "dss.ActiveCircuit.ActiveCktElement.Name='EnergyMeter.fdr_05410'\n",
      "dss.ActiveCircuit.ActiveBus.Name='sourcebus'\n"
     ]
    }
   ],
   "source": [
    "dss.Text.Command = 'export yprim'\n",
    "print_active(dss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Performance\n",
    "\n",
    "Although the previous examples use names for activating objects, it is recommended to activate by index whenever possible, since it is faster, especially on DSS-Extensions. Rerun the cell below on your machine to get an idea, but beware that the performance profile may change on high CPU loads. When in doubt, experiment with some variations on scenarios closer to actual workloads.\n",
    "\n",
    "After a circuit is populated, the indices are stable and can be cached. The performance profile for activating elements by name might get better in future releases of both DSS-Extensions engine (AltDSS/DSS C-API) and the official OpenDSS distribution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "Loads = dss.ActiveCircuit.Loads\n",
    "SetActiveElement = dss.ActiveCircuit.SetActiveElement\n",
    "CktElements = dss.ActiveCircuit.CktElements\n",
    "Text = dss.Text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "393 ns ± 6.03 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit Loads.Name = \"805302100\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('805302100', 10, 6079)"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Loads.Name, Loads.idx, SetActiveElement(\"Load.805302100\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "152 ns ± 3.59 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit Loads.idx = 10"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "213 ns ± 0.835 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit CktElements(6079)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "512 ns ± 2.19 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit SetActiveElement(\"Load.805302100\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.36 µs ± 1.65 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit Text.Command = \"select Load.805302100\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Caching indices\n",
    "\n",
    "Here's an example of caching in Python:\n",
    "- Create simple dicts mapping the names to the indices\n",
    "- Use those to map names to indices\n",
    "- Use the indices in the API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 5.85 ms, sys: 128 µs, total: 5.98 ms\n",
      "Wall time: 5.31 ms\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "cename_to_idx = {n: i for (i, n) in zip(range(1, dss.ActiveCircuit.NumCktElements), dss.ActiveCircuit.AllElementNames)}\n",
    "loadname_to_idx = {n: i for (i, n) in zip(range(1, dss.ActiveCircuit.Loads.Count), dss.ActiveCircuit.Loads.AllNames)}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "240 ns ± 1.87 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit CktElements(cename_to_idx['Load.805302100'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "169 ns ± 6.5 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit Loads.idx = loadname_to_idx['805302100']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Comparing the runtime numbers, one can notice that activating using `Loads.idx` using the index from the dict is a lot faster than using the names directly.\n",
    "\n",
    "There are many reasons for that, including:\n",
    "- String are the most compute-intensive types to pass through the API, involving potential encoding conversions, copies, etc.\n",
    "- Python dicts are quite optimized.\n",
    "- Python string can cache hashes.\n",
    "\n",
    "Again, testing in a real script is important in order to decide if this kind of mechanism is worth the extra code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Alternative API\n",
    "\n",
    "As noted in the introduction, an alternative API is being developed on \n",
    "on DSS-Extensions to complement and/or provide a difference experience. Currently, the main results are represented in the [AltDSS-Python](https://dss-extensions.org/AltDSS-Python/) project (check the link for more information)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run \"pip install altdss\" if you don't have it installed.\n",
    "from altdss import altdss\n",
    "altdss(f\"\"\"\n",
    "    redirect '{CIRCUIT_DSS}'\n",
    "    solve mode=snapshot\n",
    "\"\"\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's grab a load:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "load = altdss.Load['805302100']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With this reference, we don't need to worry about what is the active element as in the classic API.\n",
    "\n",
    "Moreover, the alternative API tries to encapsulate all relevant methods in this object, reproducing some aspects of the internal OpenDSS class hierarchy, as shown in the diagram in the section \"General layout\".\n",
    "\n",
    "Here, we can see that the Load type incorporates both a `CircuitElementMixin` and a `PCElementMixin`, besides base `DSSObj` and the actual `Load`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(altdss.Load.Load,\n",
       " altdss.DSSObj.DSSObj,\n",
       " dss._cffi_api_util.Base,\n",
       " altdss.CircuitElement.CircuitElementMixin,\n",
       " altdss.PCElement.PCElementMixin,\n",
       " object)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import inspect\n",
    "inspect.getmro(type(load))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One can access the common methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([-227.06921598-89.7899522j,    0.         +0.j       ]),\n",
       " array([-21.73555919-3.70169494j,  21.73555919+3.70169494j]),\n",
       " 22.048516476228425,\n",
       " array([5.2678514+1.11109385j, 0.       +0.j        ]))"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load.Voltages(), load.Currents(), load.MaxCurrent(1), load.Powers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Interact with all DSS properties specific to the loads:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(<Connection.wye: 0>,\n",
       " <Spectrum.defaultload>,\n",
       " 'g2000sk5500_n274137_sec_3.2',\n",
       " 5.195630864681321)"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load.Conn, load.Spectrum, load.Bus1, load.kW"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And use the API Extensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Name': '805302100',\n",
       " 'Phases': 1,\n",
       " 'kV': 0.24,\n",
       " 'Bus1': 'g2000sk5500_n274137_sec_3.2',\n",
       " 'Status': 'Variable',\n",
       " 'Model': 4,\n",
       " 'CVRWatts': 0.8,\n",
       " 'CVRVars': 3.0,\n",
       " 'Conn': 'wye',\n",
       " 'VMinpu': 0.7,\n",
       " 'Yearly': 'ls_phaseb',\n",
       " 'AllocationFactor': 1.6463,\n",
       " 'XfkVA': 3.22035118,\n",
       " 'PF': 0.98}"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import json\n",
    "json.loads(load.to_json())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although using names are still valid as an option in many parts of the Alt API, objects can also be manipulated directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "defaultload\n"
     ]
    }
   ],
   "source": [
    "# this is just the name of the associated spectrum object as string\n",
    "print(load.Spectrum_str)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([ 1.,  3.,  5.,  7.,  9., 11., 13.]),\n",
       " array([  0., 180., 180., 180., 180., 180., 180.]))"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# This is the actual object\n",
    "spec = load.Spectrum\n",
    "spec.Harmonic, spec.Angle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0.677  , 0.6256 , 0.6087 , 0.5833 , 0.58028, 0.6025 , 0.657  ,\n",
       "       0.7477 , 0.832  , 0.88   , 0.94   , 0.989  , 0.985  , 0.98   ,\n",
       "       0.9898 , 0.999  , 1.     , 0.958  , 0.936  , 0.913  , 0.876  ,\n",
       "       0.876  , 0.828  , 0.756  ])"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load.Daily = 'default'\n",
    "load.Daily.PMult"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, this Alt API allows manipulating batches of objects and other features:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3], dtype=int32)"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "loads_3ph = altdss.Load.batch(Phases=3)\n",
    "loads_3ph.Phases()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1.47390882e-01+3.20781834e-02j 1.47458379e-01+3.21332307e-02j\n",
      " 1.47771846e-01+3.23898394e-02j ... 7.76960599e+03+9.88751954e+02j\n",
      " 7.76960408e+03+9.88739143e+02j 0.00000000e+00+0.00000000e+00j]\n"
     ]
    }
   ],
   "source": [
    "print(loads_3ph.Powers())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "The classic API implements the \"active object\" paradigm, requiring some attention to avoid using the wrong data, especially when multiple objects are involved.\n",
    "\n",
    "The time profile of some activation-related methods and functions may be important for performance critical code.\n",
    "\n",
    "On DSS-Extensions, an alternative API is being developed to provide a different experience, perhaps complementary since it exposes all DSS objects and can be used together with the classic API, as shown in DSS-Python and OpenDSSDirect.py.\n",
    "\n",
    "The classic API will be supported on DSS-Extensions as long as required, either to allow better compatibility with EPRI's OpenDSS, or to allow long-term support of existing third-party software that depend on this API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}