Tutorial 2: Creating a new or opening an existing SIR 3S model

This tutorial demonstrates how to create new SIR 3S models or open already existing ones.

SIR 3S Installation

[2]:

SIR3S_SIRGRAF_DIR = r"C:\3S\SIR 3S Entwicklung\SirGraf-90-15-00-16_Quebec_x64" #change to local path

Imports

Note: The SIR 3S Toolkit requires the Sir3S_Toolkit.dll included in SIR 3S installations (version Quebec and higher).

[3]:

import sir3stoolkit

The core of sir3stoolkit is a Python wrapper around basic functionality of SIR 3S, offering a low-level access to the creation, modification and simulation of SIR 3S models. In the future pure python subpackages may be added.

[4]:

from sir3stoolkit.core import wrapper

[5]:

sir3stoolkit

[5]:

<module 'sir3stoolkit' from 'C:\\Users\\aUsername\\3S\\sir3stoolkit\\src\\sir3stoolkit\\__init__.py'>

The wrapper package has to be initialized with reference to a SIR 3S (SirGraf) installation.

[6]:

wrapper.Initialize_Toolkit(SIR3S_SIRGRAF_DIR)

Initialization

The SIR 3S Toolkit contains two classes: SIR3S_Model (model and data) and SIR3S_View (depiction in SIR Graf). All SIR 3S Toolkit functionality is accessed via the methods of these classes.

[7]:

s3s = wrapper.SIR3S_Model()

Initialization complete

[8]:

s3s_view = wrapper.SIR3S_View()

Initialization complete

Create a new model

First we can check the different network types that can be created with SIR 3S. For simplicity we just create a network with type undefined.

[9]:

network_types = [item for item in dir(s3s.NetworkType) if not (item.startswith('__') and item.endswith('__'))]
print(network_types)

['DistrictHeating', 'Gas', 'Steam', 'Undefined', 'Water']

We are using the NewModel() function of SIR3S_Model() to create a new db3 file.

[10]:

dbFilePath=r"Toolkit_Tutorial2_NewModel.db3"

[11]:

s3s.NewModel(dbName=dbFilePath,
             providerType=s3s.ProviderTypes.SQLite,
             namedInstance="",
             netType=s3s.NetworkType.Undefined,
             modelDescription="Tutorial New Model",
             userID="",
             password="")

New model is created with the model identifier: M-1-0-1

Now the model has been created and is opened. All SIR 3S Toolkit operations now apply to this model until the model is closed or another one is opened. If there already existed a model file with this path and name, a new model with the same name but incremented model identifier is created.

To check whether the modle is responsive, we can use the GetNetworkType() function.

[12]:

print(s3s.GetNetworkType())

NetworkType.Undefined

As no changes have been made, we close the model without saving changes using the CloseModel() function.

[13]:

s3s.CloseModel(saveChangesBeforeClosing=False)

[13]:

True

Open an exisiting model

We use the function OpenModel() to open an existing SIR 3S model via the SIR 3S Toolkit.

[14]:

dbFilePath=r"Toolkit_Tutorial2_OpenModel.db3"

[15]:

s3s.OpenModel(dbName=dbFilePath,
              providerType=s3s.ProviderTypes.SQLite,
              Mid="M-1-0-1",
              saveCurrentlyOpenModel=False,
              namedInstance="",
              userID="",
              password="")

Model is open for further operation

Now the model has been opened and the previous one has been closed without saving it. All SIR 3S Toolkit operations now apply to this model until another one is opened.

[16]:

print(s3s.GetNetworkType()) # to check that the correct model is responsive, model we are trying to open was created with type District Heating

NetworkType.DistrictHeating

As no changes have been made, we close the model without saving changes using the CloseModel() function.

[17]:

s3s.CloseModel(saveChangesBeforeClosing=False)

[17]:

True

Open an existing XML Model

We use the function OpenModelXml to open an existing SIR 3S model in XML format via the SIR 3S Toolkit.

This XML SIR 3S file was exported via SIR 3S based on the .db3 file opened above.

[18]:

dbFilePath=r"Toolkit_Tutorial2_OpenModel.xml"

[19]:

s3s.OpenModelXml(dbFilePath, False)

Model is open for further operation

[20]:

print(s3s.GetNetworkType()) # to check that the correct model is responsive, model we are trying to open was created with type District Heating

NetworkType.DistrictHeating

[21]:

s3s.CloseModel(saveChangesBeforeClosing=False)

[21]:

True

Next: Tutorial 3: Accessing and modifying model data