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 the folder .\Scripting\API Beginner of the archive for the tutorial data available from the section "TUTORIAL DOWNLOADS" of the category "Model Ready Datasets" of the community Forum.

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
# CHANGE the path to the Excel file to match your folder
saint_dll.importENET(
        "C:\\Work\\API Beginner\\Inclusion\\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. Log of the importENET function.

2025-07-10 11:01:58 [INFO] Network import of file C:\Work\API Beginner\Inclusion\ENET09_13.xlsx to network file C:\Work\API Beginner\Inclusion\ENET09_13.enet completed successfully without errors
2025-07-10 11:01:58 [INFO] Loading Electric Network model from file: C:\Work\API Beginner\Inclusion\ENET09_13.enet
2025-07-10 11:01:59 [INFO] Electric Network loaded successfully
0

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. Log of the newESCE function.

2025-07-10 11:04:45 [INFO] Using the DateTime format: dd/MM/yyyy HH:mm.
2025-07-10 11:04:46 [INFO] Electric scenario loaded and saved to file C:\Work\API Beginner\Inclusion\PCM_5days.esce successfully!
1

SAInt uses the same location where the network linked to the scenario is saved.

3. Change and check solver settings using the API

The SAInt API has a range of classes and methods that can be used to access and modify different aspects of the simulation or optimization problem, along with aspects of the solver. As an example, we will change the optimization problem type in our DCUCOPF optimization. Valid values are the string "LP" or "MIP". Add the code below to your Python script and execute.

# Change OptimizationProblemType
saint_dll.SetOptimizationProblemType("LP")

saint_dll.SetOptimizationProblemType("MIP")

Keep the problem type to "MIP" for this tutorial.
Example 3. Log of the SetOptimizationProblemType method.

>>> saint_dll.SetOptimizationProblemType("LP")
2025-07-10 11:45:38 [INFO] OptimizationProblemType was set to LP.
1
>>> saint_dll.SetOptimizationProblemType("MIP")
2025-07-10 11:48:07 [INFO] OptimizationProblemType was set to MIP.
1
>>>

As we are addressing a DCUCOPF optimization problem, SAInt is using the Gurobi solver and allows to interact with the solver for setting a set of options. An example is the following where do do retrieve and display the value of the setting "relative MIP gap". Add the code below to your Python script and execute.

# Allows for proper translation of strings
saint_dll.evalCmdStr.restype = c_wchar_p

# Access RelativeMipGap
print(f"Relative Mip Gap: {saint_dll.evalCmdStr('ENET.SCE.RelMipGap')}")
Example 4. Log of the evaluation of the expression ENET.SCE.RelMipGap.

Relative Mip Gap: 0.001

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
# CHANGE the path to the profile file to match your folder
saint_dll.includeEPRF(
        "C:\\Work\\API Beginner\\Inclusion\\ENET09_13_ScenarioProfiles.prfl"
        )
Example 5. Log of the includeEPRF function.

2025-07-10 11:21:52 [INFO] Profile PRF_SOLARPARK added successfully to scenario PCM_5days of network ENET09_13_2
2025-07-10 11:21:52 [INFO] Profile PRF_WINDFARM added successfully to scenario PCM_5days of network ENET09_13_2
…​
2025-07-10 11:21:52 [INFO] Profile PRF_COAL_PRICES added successfully to scenario PCM_5days of network ENET09_13_2
2025-07-10 11:21:52 [INFO] 10 Profiles included successfully to file C:\Work\API Beginner\Inclusion\ENET09_13_ScenarioProfiles.prfl!
1

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
# CHANGE the path to the Excel file to match your folder
saint_dll.importESCE(
        "C:\\Work\\API Beginner\\Inclusion\\ENET09_13_ScenarioEvents.xlsx"
        )
Example 6. Log of the importESCE function.

2025-07-10 11:22:57 [INFO] 14 lines parsed successfully
2025-07-10 11:22:57 [INFO] Electric Scenario Events imported successfully!
100

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 the path to the Excel parameter import file as an argument. In the parameter import file ENET09_13_ParaImport.xlsx, we want to change the following properties

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

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

Open the file ENET09_13_ParaImport.xlsx and edit its content. As provided with the tutorial´s files, the syntax of the parameters import file is on purpose wrong. If not fixed, the Python interpreter will stop working!

Edit the content of the cells to match the following table and save the file.

Column A

Column B

Column C

HGEN.HYDROTURBINE.PMAXDEF

100

[MW]

PHSTR.PUMPSTORAGE.InService

FALSE

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

# Change network parameters
# CHANGE the path to the Excel file to match your folder
saint_dll.paraimportENET(
        "C:\\Work\\API Beginner\\Inclusion\\ENET09_13_ParaImport.xlsx"
        )
Example 7. Log of the paraimportENET function.

2025-07-10 12:22:27 [INFO] 2 lines parsed successfully from a of total 2
2025-07-10 12:22:27 [INFO] Parameter import of parameter import file C:\Work\API Beginner\Inclusion\ENET09_13_ParaImport.xlsx to network file C:\Work\API Beginner\Inclusion\ENET09_13.enet completed successfully without errors
2025-07-10 12:22:28 [INFO] Network saved to C:\Work\API Beginner\Inclusion\ENET09_13.enet!
1

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 8. Log of the runESIM function.

2025-07-10 12:24:22 [INFO] Simulation log will be displayed!
2025-07-10 12:24:22 [INFO] Starting simulation with …​
2025-07-10 12:24:22 [INFO] Electric network file: C:\Work\API Beginner\Inclusion\ENET09_13.enet
2025-07-10 12:24:22 [INFO] Electric scenario file: C:\Work\API Beginner\Inclusion\PCM_5days.esce
2025-07-10 12:24:22 [INFO] SAInt 3.7.14.5 - Starting DCUCOPF simulation at 10/07/2025 12:24
2025-07-10 12:24:23 [INFO] Scenario: PCM_5days | InitialState: NONE
2025-07-10 12:24:23 [INFO] Time: StartTime: 01/03/2022 00:00:00 | EndTime: 01/08/2022 00:00:00 | TimeWindow: 120 [h] | TimeHorizon: 24 [h] | TimeLookAhead: 24 [h] | StepsTimeHorizon: 24 | StepsLookAhead: 6 | NumberOfConsecutiveRuns: 5
2025-07-10 12:24:23 [INFO] Scenario PCM_5days of type DCUCOPF has 120 steps of 60 minutes to 120 hours from 03/01/2022 00:00 to 08/01/2022 00:00
2025-07-10 12:24:23 [INFO] Global events: DECOUPLEHYDRO: False | INCLUDELOSS: False | NOASVC: False | NOCONSTR: False | NODROP: True | NOLASTHOR: False | NOLINECAP: False | REVON: True
2025-07-10 12:24:23 [INFO] Successfully read encrypted (PIOEK) HiddenData.
2025-07-10 12:24:23 [INFO] Successfully decrypted the Hidden Data using PIODK.
2025-07-10 12:24:23 [INFO] There are 1 isolated network area(s).
2025-07-10 12:24:23 [INFO] Isonet isolated area with ENO.NODE1 setting voltage angle has no demand
2025-07-10 12:24:23 [INFO] Starting consecutive run no. 1 from 03/01/2022 00:00 to 05/01/2022 00:00
2025-07-10 12:24:23 [INFO] There are 1 isolated network area(s).
Set parameter LogToConsole to value 1
2025-07-10 12:24:23 [INFO] Solver: Gurobi | Model: MIP | RelativeMIPGap = 0.001 | TimeLimit = 3600 [s]
Gurobi Optimizer version 11.0.2 build v11.0.2rc0 (win64 - Windows 11.0 (22631.2))
…​
…​
Solved in 285 iterations and 0.00 seconds (0.00 work units)
Optimal objective 1.284385851e+05
2025-07-10 12:24:26 [INFO] Optimization solved in: 0 [s]
2025-07-10 12:24:26 [INFO] Integrals over 120.0 hours with 1 hour steps
2025-07-10 12:24:26 [INFO] Total Energy Generation
2025-07-10 12:24:26 [INFO] XGEN 2,727.24 [MWh] share = 8.8 [%]
2025-07-10 12:24:26 [INFO] FGEN 15,893.79 [MWh] share = 51.4 [%]
2025-07-10 12:24:26 [INFO] HGEN 9,374.17 [MWh] share = 30.3 [%]
2025-07-10 12:24:26 [INFO] PV 1,211.03 [MWh] share = 3.9 [%]
2025-07-10 12:24:26 [INFO] WIND 1,587.94 [MWh] share = 5.1 [%]
2025-07-10 12:24:26 [INFO] PHSTR (discharge) 0.00 [MWh] share = 0.0 [%]
2025-07-10 12:24:26 [INFO] ESTR (discharge) 155.61 [MWh] share = 0.5 [%]
2025-07-10 12:24:26 [INFO] EPS (supply) 0.00 [MWh] share = 0.0 [%]
2025-07-10 12:24:26 [INFO] Total Energy Generation 30,949.77 [MWh]
2025-07-10 12:24:26 [INFO] Total Energy Demand
2025-07-10 12:24:26 [INFO] EDEM 30,718.35 [MWh] share = 99.3 [%]
2025-07-10 12:24:26 [INFO] PHSTR (charge) 0.00 [MWh] share = 0.0 [%]
2025-07-10 12:24:26 [INFO] ESTR (charge) 231.42 [MWh] share = 0.7 [%]
2025-07-10 12:24:26 [INFO] EPS (demand) 0.00 [MWh] share = 0.0 [%]
2025-07-10 12:24:26 [INFO] Total Energy Demand 30,949.77 [MWh]
2025-07-10 12:24:26 [INFO] Generation - Demand 0.00 [MWh]
2025-07-10 12:24:26 [INFO] Total Energy Not Supplied (total PNS)
2025-07-10 12:24:26 [INFO] EDEM.PNS 0.00 [MWh] (0.0 [%] of total demand)
2025-07-10 12:24:26 [INFO] XGEN.PNS 0.00 [MWh]
2025-07-10 12:24:26 [INFO] PV.PNS 0.00 [MWh]
2025-07-10 12:24:26 [INFO] WIND.PNS 0.00 [MWh]
2025-07-10 12:24:26 [INFO] ASVC.PNS 0.00 [MWh]
2025-07-10 12:24:26 [INFO] Total Cost - Breakdown
2025-07-10 12:24:26 [INFO] GEN.VOMCost 108,093.79 [$]
2025-07-10 12:24:26 [INFO] ESTR.VOMCost 0.00 [$]
2025-07-10 12:24:26 [INFO] PHSTR.VOMCost 0.00 [$]
2025-07-10 12:24:26 [INFO] EPS.VOMCost 0.00 [$]
2025-07-10 12:24:26 [INFO] ASVC.ASVCCost 0.00 [$]
2025-07-10 12:24:26 [INFO] FGEN.StartUpCost 0.00 [$] (NumberOfStartUps: 0)
2025-07-10 12:24:26 [INFO] FGEN.ShutDownCost 0.00 [$] (NumberOfShutDowns: 0)
2025-07-10 12:24:26 [INFO] FUEL.FuelCost 564,048.68 [$]
2025-07-10 12:24:26 [INFO] EBR.HurdleCost 0.00 [$]
2025-07-10 12:24:26 [INFO] Total Production Cost 672,142.48 [$]
2025-07-10 12:24:26 [INFO] Penalty Costs (Note: This list is not exhaustive)
2025-07-10 12:24:26 [INFO] EDEM (curtailment) 0.00 [$]
2025-07-10 12:24:26 [INFO] ASVC (curtailment) 0.00 [$]
2025-07-10 12:24:26 [INFO] ECNSTR (violation) 0.00 [-]
2025-07-10 12:24:26 [INFO] Optimization with 5 consecutive run(s).
2025-07-10 12:24:26 [INFO] Total computing time [sec]: 3.373
2025-07-10 12:24:26 [INFO] DCUCOPF simulation completed.
2025-07-10 12:24:26 [INFO] DCUCOPF simulation completed successfully!
32