Execute Scenarios with the SAInt API

In this section, we’ll proceed with importing the SAInt Network, Profiles, and Events Import Excel Files into SAInt for simulation. We will continue with the triangle dataset and import files that were generated in the previous section:

If you are following along, ensure the presence of the following Excel files in your current working directory before proceeding:

  • network.xlsx

  • events.xlsx

  • profiles.xlsx

If any of these files do not exist, please revisit the previous sections.

1. Connect to the SAInt API

Before importing the Excel files into SAInt, a connection to the SAInt API must be established. We can use the pySAInt utility function set_dll to specify the path to the SAInt-API.dll file.

  • If you have a standard installation of SAInt, the set_dll function can automatically locate the dynamic link library (DLL) file in the SAInt installation directory.

  • For custom SAInt installation, you can manually specify the path to the DLL file.

import pysaint as ps

# Set the SAInt API DLL for standard installations
ps.utils.set_dll()

# For custom installations, manually specify the path as an argument:
# ps.utils.set_dll(path_to_dll='C:/Custom/Path/To/SAInt-API.dll')
python

Upon successful execution, the ps.utils.set_dll() method initializes the saint_dll attribute within pySAInt. Using this attribute, we can now directly call SAInt API methods thorugh ps.saint_dll.

# Confirm we have successfully connected to the SAInt-API dll
ps.saint_dll.evalCmdStr('API_Active')
python

2. Use the SAInt API to Import Data

Once the saint_dll attribute is initialized within pySAInt, we can now import the network, profiles, and events files from Excel into SAInt.

It is essential to follow a specific order when importing files into SAInt. The recommended sequence is as follows:

  • Import Network

  • Create a new SAInt scenario

  • Import Profiles

  • Import Events

In this section, we’ll focus solely on SAInt API methods related to electric networks and scenarios. Please consult the SAInt API documentation for information on all SAInt API methods.

2.1. Import Network

We can use the importENET method of SAInt API to import the SAInt Network Import Excel File. This method loads the import file and also creates the SAInt Network file in the same directory as the import file.

# Import the electric network into SAInt using Excel import file.
# Using the file in the current working directory
ps.saint_dll.importENET('network.xlsx')
python

2.2. Create a new SAInt scenario

After generating the SAInt network file, we can proceed to create a new SAInt scenario. This is achieved by utilizing the scenario properties defined within the triangle dataset and the newESCE method of SAInt API. This method will create the SAInt scenario file in the same directory as the SAInt network file.

We can use the properties of the REFERENCE scenario from our pySAInt dataset, using the get_scenario method. This method retrieves the scenario we defined, and we can access the properties using the props attribute of the scenario.

This helps keep things like the scenario StartTime and EndTime defined in only one place to minimize the possibility of errors.

 
# Retrieve the scenario from the pySAInt triangle dataset
reference_scenario = triangle.get_scenario(Name='REFERENCE')

# Access the properties of the reference scenario
scenario_props = reference_scenario.props
python

Now that we have got the REFERENCE scenario properties, we can use them to create a new SAInt scenario with the newESCE method of SAInt API:

# Create a new SAInt scenario
ps.saint_dll.newESCE(
  reference_scenario.Name,
  scenario_props['SceType'],
  scenario_props['StartTime'].strftime('%d/%m/%Y %H:%M'),
  scenario_props['EndTime'].strftime('%d/%m/%Y %H:%M'),
  scenario_props['TimeStep'].seconds,
  scenario_props['TimeHorizon'].seconds,
  scenario_props['TimeLookAhead'].seconds,
  scenario_props['TimeStepLookAhead'].seconds,
)
python

2.3. Import Profiles

After generating SAInt network and scenario files, we can add profiles to the scenario before importing events. This ensures that events referencing these profiles are correctly imported by the SAInt API, preventing import errors. For adding profiles, we can use the importEPRF method of SAInt API.

# Import profiles to the SAInt scenario using Excel import file.
# Using the file in the current working directory
ps.saint_dll.importEPRF('profiles.xlsx')
python

2.4. Import Events

After adding the profiles to the SAInt scenario, we can now add events to the SAInt scenario using the importESCE method of SAInt API.

# Import events to the SAInt scenario using Excel import file.
# Using the file in the current working directory
ps.saint_dll.importESCE('events.xlsx')
python

3. Execute a Scenario with the SAInt API

After generating SAInt network and scenario files, including profiles and events, we’re set to execute the scenario using the SAInt API. We can use the runESIM method of SAInt API for simulation. For simulation insights, we can use showSIMLOG method, which toggles the display of simulation logs based on a boolean argument (True or False).

# Choose to show simulation logs
ps.saint_dll.showSIMLOG(True)

# Execute scenario
ps.saint_dll.runESIM()
python