Basic functions of SAInt API

This tutorial will focus on functions that are used to load an existing electric network and scenario into the memory and execute an electric simulation using the SAInt API. The objective is to learn on how to import the SAInt API dynamic link library (DLL) object into Python and execute a simulation using an existing network and scenario.

Please refer to the API reference section for additional details on the functions described in this tutorial.

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. Create a DLL object in Python

Let’s get started by opening your preferred Python IDE and creating a new directory and a new Python script. Once the new Python script is created, the first step to start using the SAInt API is to import SAInt’s dynamic link library (DLL) into your Python environment. We will use the Python ctypes module, which provides C-compatible data types and allows function calls from a DLL object. Add the following expression to your Python script and execute.

Change the path to the DLL or the files accordingly to your SAInt installation and the location where the data are saved.

 
# 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)

2. Load the electric network

Copy the network and scenario files to your Python script directory. Then, we will use the openENET function to load the electric network file ENET09_13.enet. It takes the path to the SAInt electric network file as an argument. Add the following expression to your Python script and execute.

For more information on the electric model used in this tutorial, please take some time to go through the readme file included in the tutorial folder.

 
# Load the electric network
# CHANGE the path to the network file to match your folder
saint_dll.openENET(
        "C:\\Work\\API Beginner\\Basic\\ENET09_13.enet"
        )
Example 1. Log of the openENET function.

2025-07-10 10:41:37 [INFO] Loading Electric Network model from file: C:\Work\API Beginner\Basic\ENET09_13.enet
2025-07-10 10:41:47 [INFO] Electric Network loaded successfully
1

3. Load the electric scenario

After successfully loading the electric network, the next step is to open the electric scenario file PCM_DCUCOPF_5.esce using the openESCE function by passing the path to the SAInt electric scenario file as an argument. Add the following expression to your Python script and execute.

# Load the electric scenario
# CHANGE the path to the scenario file to match your folder
saint_dll.openESCE(
        "C:\\Work\\API Beginner\\Basic\\PCM_DCUCOPF_5.esce"
        )
Example 2. Log of the openESCE function.

2025-07-10 10:43:51 [INFO] Loading Electric Scenario from file: C:\Work\API Beginner\Basic\PCM_DCUCOPF_5.esce.
2025-07-10 10:43:52 [INFO] Electric Scenario loaded successfully
2025-07-10 10:43:52 [INFO] Attempting to load Electric Scenario results.
2025-07-10 10:43:52 [INFO] No scenario solution file available for Electric Scenario
1

When loading a scenario, SAInt attempts to load, if available, a solution file for the scenario as well.

4. Display simulation logs

The SAInt API allows displaying or hiding simulation logs in the output window using the showSIMLOG function. The simulation logs can help check the simulation status and relevant information. However, if desired, the user can hide the simulation logs' display, which can save computation time, especially when simulating large networks. It takes either True or False as an argument. Add the following expression to your Python script and execute.

# Choose to display simulation logs
saint_dll.showSIMLOG(True)
Example 3. Logs from the showSIMLOG function.

2025-07-10 10:46:12 [INFO] Simulation log will be displayed!
1

5. Execute the simulation

The SAInt API has a range of functions to execute simulations depending on the type of energy network, e.g., use runESIM for running an electric simulation. Add the following expression into your Python script and execute.

# Run electric simulation
saint_dll.runESIM()
Example 4. Partial log for the runESIM function.

2025-07-10 10:46:40 [INFO] Starting simulation with …​
2025-07-10 10:46:40 [INFO] Electric network file: C:\Work\API Beginner\Basic\ENET09_13.enet
2025-07-10 10:46:40 [INFO] Electric scenario file: C:\Work\API Beginner\Basic\PCM_DCUCOPF_5.esce
2025-07-10 10:46:41 [INFO] SAInt 3.7.14.5 - Starting DCUCOPF simulation at 10/07/2025 10:46
2025-07-10 10:46:41 [INFO] Scenario: PCM_DCUCOPF_5 | InitialState: NONE
2025-07-10 10:46:41 [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 10:46:41 [INFO] Scenario PCM_DCUCOPF_5 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 10:46:41 [INFO] Global events: DECOUPLEHYDRO: False | INCLUDELOSS: False | NOASVC: False | NOCONSTR: False | NODROP: True | NOLASTHOR: False | NOLINECAP: False | REVON: True
2025-07-10 10:46:42 [INFO] Successfully read encrypted (PIOEK) HiddenData.
2025-07-10 10:46:42 [INFO] Successfully decrypted the Hidden Data using PIODK.
2025-07-10 10:46:42 [INFO] There are 1 isolated network area(s).
2025-07-10 10:46:43 [INFO] Isonet isolated area with ENO.NODE1 setting voltage angle has no demand
2025-07-10 10:46:43 [INFO] Starting consecutive run no. 1 from 03/01/2022 00:00 to 05/01/2022 00:00
2025-07-10 10:46:43 [INFO] There are 1 isolated network area(s).
Set parameter LogToConsole to value 1
2025-07-10 10:46:43 [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 343 iterations and 0.01 seconds (0.00 work units)
Optimal objective 1.231561235e+05
2025-07-10 10:46:48 [INFO] Optimization solved in: 0.01 [s]
2025-07-10 10:46:48 [INFO] Integrals over 120.0 hours with 1 hour steps
2025-07-10 10:46:48 [INFO] Total Energy Generation
2025-07-10 10:46:48 [INFO] XGEN 2,727.24 [MWh] share = 8.9 [%]
2025-07-10 10:46:48 [INFO] FGEN 15,477.35 [MWh] share = 50.4 [%]
2025-07-10 10:46:48 [INFO] HGEN 9,061.80 [MWh] share = 29.5 [%]
2025-07-10 10:46:48 [INFO] PV 1,211.03 [MWh] share = 3.9 [%]
2025-07-10 10:46:48 [INFO] WIND 1,587.94 [MWh] share = 5.2 [%]
2025-07-10 10:46:48 [INFO] PHSTR (discharge) 656.02 [MWh] share = 2.1 [%]
2025-07-10 10:46:48 [INFO] ESTR (discharge) 0.00 [MWh] share = 0.0 [%]
2025-07-10 10:46:48 [INFO] EPS (supply) 0.00 [MWh] share = 0.0 [%]
2025-07-10 10:46:48 [INFO] Total Energy Generation 30,721.37 [MWh]
2025-07-10 10:46:48 [INFO] Total Energy Demand
2025-07-10 10:46:48 [INFO] EDEM 30,718.35 [MWh] share = 100.0 [%]
2025-07-10 10:46:48 [INFO] PHSTR (charge) 3.02 [MWh] share = 0.0 [%]
2025-07-10 10:46:48 [INFO] ESTR (charge) 0.00 [MWh] share = 0.0 [%]
2025-07-10 10:46:48 [INFO] EPS (demand) 0.00 [MWh] share = 0.0 [%]
2025-07-10 10:46:48 [INFO] Total Energy Demand 30,721.37 [MWh]
2025-07-10 10:46:48 [INFO] Generation - Demand 0.00 [MWh]
2025-07-10 10:46:49 [INFO] Total Energy Not Supplied (total PNS)
2025-07-10 10:46:49 [INFO] EDEM.PNS 0.00 [MWh] (0.0 [%] of total demand)
2025-07-10 10:46:49 [INFO] XGEN.PNS 0.00 [MWh]
2025-07-10 10:46:49 [INFO] PV.PNS 0.00 [MWh]
2025-07-10 10:46:49 [INFO] WIND.PNS 0.00 [MWh]
2025-07-10 10:46:49 [INFO] ASVC.PNS 0.00 [MWh]
2025-07-10 10:46:49 [INFO] Total Cost - Breakdown
2025-07-10 10:46:49 [INFO] GEN.VOMCost 106,023.16 [$]
2025-07-10 10:46:49 [INFO] ESTR.VOMCost 0.00 [$]
2025-07-10 10:46:49 [INFO] PHSTR.VOMCost 1,476.04 [$]
2025-07-10 10:46:49 [INFO] EPS.VOMCost 0.00 [$]
2025-07-10 10:46:49 [INFO] ASVC.ASVCCost 0.00 [$]
2025-07-10 10:46:49 [INFO] FGEN.StartUpCost 0.00 [$] (NumberOfStartUps: 0)
2025-07-10 10:46:49 [INFO] FGEN.ShutDownCost 0.00 [$] (NumberOfShutDowns: 1)
2025-07-10 10:46:49 [INFO] FUEL.FuelCost 544,535.38 [$]
2025-07-10 10:46:49 [INFO] EBR.HurdleCost 0.00 [$]
2025-07-10 10:46:49 [INFO] Total Production Cost 652,034.58 [$]
2025-07-10 10:46:49 [INFO] Penalty Costs (Note: This list is not exhaustive)
2025-07-10 10:46:49 [INFO] EDEM (curtailment) 0.00 [$]
2025-07-10 10:46:49 [INFO] ASVC (curtailment) 0.00 [$]
2025-07-10 10:46:49 [INFO] ECNSTR (violation) 0.00 [-]
2025-07-10 10:46:49 [INFO] Optimization with 5 consecutive run(s).
2025-07-10 10:46:49 [INFO] Total computing time [sec]: 7.746
2025-07-10 10:46:49 [INFO] DCUCOPF simulation completed.
2025-07-10 10:46:50 [INFO] DCUCOPF simulation completed successfully!
32