Inclusion functions of SAInt API

SAInt offers the ability to include or import network and scenario data through its application programming interface (API). The objective of this tutorial is to learn how to utilize SAInt API functions that streamline these inclusion operations. We will also learn how to create a new scenario with the SAInt API. Once the inclusion operations have been completed, we will run the simulation.

The network, scenario and import files used in this tutorial can be found in (C:\Users\...\Documents\encoord\SAInt-v3\Projects\ENET09_13\). Make a copy of this folder as necessary.

1. Import the electric network

Let’s get started by opening your preferred Python IDE and creating a new Python script. After creating the script, copy the tutorial’s files to your Python script directory. Then, we will import and load the electric network into memory using the importENET function. The function requires the path to the electric network import file as an argument. Copy the code below to your Python script and execute.

# Import ctypes package
from ctypes import *

# Path to the SAInt-API.dll file (located in the SAInt installation folder)
path = "C:\\Program Files\\encoord\\SAInt-v3\\SAInt-API.dll"

# Create a SAInt API DLL object
saint_dll = cdll.LoadLibrary(path)

# Import the electric network
saint_dll.importENET(
        "ENET09_13.xlsx"
        )

After the network is successfully imported from the network import file, the SAInt electric network file is automatically created in the same folder as the import file. In this case, the ENET_09_13.enet network file will be created into your Python script directory. The importENET function also loads the electric network into memory. If there is an error in the network import file, a log file detailing the error is automatically generated in the same folder.

Example 1. Logs from the importENET function

Network import of file ENET09_13.xlsx to network file C:\..\ENET09_13.enet completed successfully without errors

Network saved to C:\..\ENET09_13.enet!

Loading Electric Network model from file: C:\..\ENET09_13.enet

Electric Network loaded successfully.

2. Create a new electric DCUCOPF scenario

To create a new electric scenario using the SAInt API, the newESCE function can be used. This allows for greater flexibility and automation in scenario creation. The parameters of the newESCE function are listed below:

  • ScenarioName (str): Scenario name.

  • ScenarioType (str): SteadyACPF, SteadyACOPF, QuasiDynamicACPF, QuasiDynamicACOPF, SteadyDCPF, SteadyDCOPF, QuasiDynamicDCPF, QuasiDynamicDCOPF, or DCUCOPF.

  • StartTime (str): Start time in format "dd/MM/yyyy HH:mm".

  • EndTime (str): End time in format "dd/MM/yyyy HH:mm".

  • TimeStep (int): Time step (of time horizon) in seconds.

  • TimeHorizon (int): Time horizon in seconds. It is only used in DCUCOPF scenario. For other scenario types, a value of 0 must be used.

  • TimeLookAhead (int): Time horizon in seconds. It is only used in DCUCOPF scenario. For other scenario types, a value of 0 must be used.

  • TimeStepLookAhead (int): Time step look ahead in seconds. It is only used in DCUCOPF scenario. For other scenario types, a value of 0 must be used.

Add the code below to your Python script and execute.

# Create a new DCUCOPF scenario
saint_dll.newESCE(
        "PCM_5days",
        "DCUCOPF",
        "03/01/2022 00:00",
        "08/01/2022 00:00",
        3600,
        86400,
        86400,
        14400
        )

A new SAInt scenario file is created in the same folder as the linked network file. The name of the file is the same as scenario name. In this case, the PCM_5days.esce scenario file is created your Python script directory.

Example 2. Logs from the newESCE function

Electric scenario loaded and saved to file C:\..\PCM_5days.esce successfully!

3. Change scenario settings using API

The SAInt API has a range of classes and methods that can be used to access and modify different SAInt object properties. The explanation of all the classes and methods will be covered in future documentation. For now, we will use the Scenario class to change the solver of the newly created scenario. Add the code below to your Python script and execute.

# Import SolverType package
saint_dll.evalCmdStr(
    "from SAInt_API.Library import SolverType"
    )
# Change SolverType
saint_dll.evalCmdStr(
    "ENET.SCE.SolverType=SolverType.Gurobi"
    )

4. Include profiles to the new scenario

To include profiles to the new scenario, we will use the includeEPRF function. It takes path to the SAInt profile file as an argument. On the other hand, the importEPRF function can also be used to import profiles from an Excel import file into the scenario. The user has the flexibility to use any one of the functions based on the type of profile file. In this case, we will use the SAInt profile file to include profiles in the new scenario. Add the code below to your Python script and execute.

# Include scenario profiles
saint_dll.includeEPRF(
        "ENET09_13_ScenarioProfiles.prfl"
        )
Example 3. Logs from the includeEPRF function

Profile PRF_SOLARPARK added successfully to scenario PCM_5days of network ENET09_13

Profile PRF_WINDFARM added successfully to scenario PCM_5days of network ENET09_13

. . .

10 Profiles included successfully to file ENET09_13_ScenarioProfiles.prfl!

5. Import events to the new scenario

By using the importESCE, we can add events in the scenario, providing greater flexibility and automation in handling the events of the scenario. It takes the path to the events import Excel file as an argument. Add the code below to your Python script and execute.

# Import events into the scenario
saint_dll.importESCE(
        "ENET09_13_ScenarioEvents.xlsx"
        )
Example 4. Logs from the importESCE function

Electric Scenario Events imported successfully!

6. Change object properties

The SAInt API provides the ability to automate the process of modifying the parameters of various electric network objects through the paraimportENET function. This feature not only saves time and effort but also allows for running multiple simulations with different network configurations, leading to more informed decision making. The function takes path to the Excel parameter import file as an argument. In the parameter import file ENET09_13_ParaImport.xlsx (included in the attached zip folder), we are changing the following properties

  • Default maximum generation rate by turbination (PGMAXDEF) of hydro generator HYDROTURBINE to 100 [MW]

  • Switching off the hydro pumped storage PUMPSTORAGE using the InService property.

Let’s import the ENET09_13_ParaImport.xlsx file into the network to change the above-mentioned object properties. Add the code below to your Python script and execute it.

# Change network parameters
saint_dll.paraimportENET(
        "ENET09_13_ParaImport.xlsx"
        )
Example 5. Logs from the paraimportENET function

Parameter import of parameter import file inclusion\ENET09_13_ParaImport.xlsx to network file c:\..\ENET09_13.enet completed successfully without errors.

Network saved to c:\..\ENET09_13.enet!

7. Execute the simulation

Now that we have imported the electric network, created the new scenario, added the events and profiles to the scenario, and edit network object’s parameters, we are ready to execute the simulation. Add the code below to your Python script and execute it.

# Run electric simulation
saint_dll.showSIMLOG(True)
saint_dll.runESIM()
Example 6. Logs from the runESIM function

Starting simulation with …​

Electric network file: c:\..\ENET09_13.enet

Electric scenario file: c:\..\PCM_5days.esce

SAInt 3.2.10.3 - Starting DCUCOPF simulation at 07/02/2023 17:51:42

ConsecutiveRuns = 5 StepsTimeHorizon=24 StepsLookAhead=0

Scenario PCM_5days of type DCUCOPF has 120 steps of 60 minutes to 120 hours from 2022.01.03 00:00 to 2022.01.08 00:00

Solver = Gurobi GAP = 0.001 TimeLimit = 3600

…​

Simulation with 119 timesteps.

Total computing time [sec]: 50.017

DCUCOPF Simulation terminated.

DCUCOPF simulation completed successfully!