Tutorial 0: Importing and initialization of the SIR 3S Toolkit

This tutorial demonstrates how to import the SIR 3S Toolkit and initialize instances of its classes.

SIR 3S Installation

SIR3S_SIRGRAF_DIR = r"C:\3S\SIR 3S\SirGraf-90-15-00-24_Quebec-Upd2" #change to local path

Imports

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

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.

from sir3stoolkit.core import wrapper

sir3stoolkit

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

The Toolkit has to be initialized with reference to a SIR 3S (SirGraf) installation using Initialize_Toolkit().

wrapper.Initialize_Toolkit(SIR3S_SIRGRAF_DIR)

[2026-10-14 14:40:21,347] INFO in sir3stoolkit.core.wrapper: [Initialization] Using provided SirGraf path: C:\3S\SIR 3S\SirGraf-90-15-00-24_Quebec-Upd2
[2026-10-14 14:40:21,347] INFO in sir3stoolkit.core.wrapper: [Initialization] Using provided SirGraf path: C:\3S\SIR 3S\SirGraf-90-15-00-24_Quebec-Upd2
[2026-10-14 14:40:21,378] INFO in sir3stoolkit.core.wrapper: [Initialization] Initializing toolkit with SirGraf path: C:\3S\SIR 3S\SirGraf-90-15-00-24_Quebec-Upd2
[2026-10-14 14:40:21,623] INFO in sir3stoolkit.core.wrapper: [Initialization] Sir3S_Toolkit.dll file version 90.15.10.0 (matches this sir3stoolkit version).

Sir3S_Toolkit.dll Version

Some sir3stoolkit versions require replacing the Sir3S_Toolkit.dll in the SirGraf directory with the one shipped in the package (see Releases). From sir3stoolkit 90.15.26 on, the DLL carries a file version, so Initialize_Toolkit() checks this automatically: it logs the file version of the DLL in the SirGraf directory (see above) and warns if it differs from the DLL shipped with the installed sir3stoolkit version. The file version can also be read with Get_Toolkit_Dll_File_Version() - by default from the SirGraf directory, or from any Sir3S_Toolkit.dll path. DLLs before 90.15.26 report 1.0.0.0.

wrapper.Get_Toolkit_Dll_File_Version()

'90.15.10.0'

Persisting the SirGraf Path

Hardcoding SIR3S_SIRGRAF_DIR in every script is repetitive. Instead, the path can be written once to the package’s config file via Write_SirGraf_Config_Path() - after that, Initialize_Toolkit() can be called with no argument at all and will resolve the path from that config file automatically (see its docstring for the full resolution order). Read_SirGraf_Config_Path() reads back what is currently configured, or None if nothing is set yet.

wrapper.Write_SirGraf_Config_Path(SIR3S_SIRGRAF_DIR)

[2026-10-14 14:40:21,655] INFO in sir3stoolkit.core.wrapper: [Initialization] Wrote SirGraf path to config file 'C:\Users\aUsername\3S\sir3stoolkit\src\sir3stoolkit\config.local.txt': 'C:/3S/SIR 3S/SirGraf-90-15-00-24_Quebec-Upd2'

wrapper.Read_SirGraf_Config_Path()

[2026-10-14 14:40:21,674] INFO in sir3stoolkit.core.wrapper: [Initialization] Using SirGraf path from config 'C:\Users\aUsername\3S\sir3stoolkit\src\sir3stoolkit\config.local.txt': 'C:/3S/SIR 3S/SirGraf-90-15-00-24_Quebec-Upd2'

'C:/3S/SIR 3S/SirGraf-90-15-00-24_Quebec-Upd2'

With the path persisted, Initialize_Toolkit() no longer needs SIR3S_SIRGRAF_DIR explicitly:

wrapper.Initialize_Toolkit()  # basePath omitted - resolved from the config file written above

[2026-10-14 14:40:21,690] INFO in sir3stoolkit.core.wrapper: [Initialization] Host application is 'python.exe', not 'SirGraf.exe'. Toolkit is attempted to be initialized inside a non-SirGraf process ...
[2026-10-14 14:40:21,694] INFO in sir3stoolkit.core.wrapper: [Initialization] Using SirGraf path from config 'C:\Users\aUsername\3S\sir3stoolkit\src\sir3stoolkit\config.local.txt': C:/3S/SIR 3S/SirGraf-90-15-00-24_Quebec-Upd2
[2026-10-14 14:40:21,696] INFO in sir3stoolkit.core.wrapper: [Initialization] Initializing toolkit with SirGraf path: C:/3S/SIR 3S/SirGraf-90-15-00-24_Quebec-Upd2
[2026-10-14 14:40:21,707] INFO in sir3stoolkit.core.wrapper: [Initialization] Sir3S_Toolkit.dll file version 90.15.10.0 (matches this sir3stoolkit version).

Initialization

The SIR 3S Toolkit contains two classes: SIR3S_Model (model and data) and SIR3S_View (interactive work in SIR Graf using the SIR Graf Python console). All SIR 3S Toolkit basis functionality is accessed via the methods of these classes. In this line of tutorials (0-49) we focus on SIR3S_Model.

s3s = wrapper.SIR3S_Model()

[2026-10-14 14:40:21,925] INFO in sir3stoolkit.core.wrapper: [Model Class Initialization] Initialization complete

s3s_view = wrapper.SIR3S_View()

[2026-10-14 14:40:22,001] INFO in sir3stoolkit.core.wrapper: Initialization complete

Next: Tutorial 1: Creating a new or opening an existing SIR 3S Model