Using the IronPython Script Manager

From DWSIM - Chemical Process Simulator
Jump to: navigation, search
WARNING: This tutorial is valid only for DWSIM version 3.x.
There is now a specific forum in the SourceForge Project Page for everything related to the Scripting features available in DWSIM. Click here to visit.


Introduction

The IronPython Script Manager allows the user to execute additional tasks in the simulation through the use of IronPython scripts, which have access to all objects in the flowsheet, the solver and the simulation itself. You can play with the objects in the flowsheet, do calculations using property packages, get data from external sources, run multiple cases while changing properties between runs and much more.

The script blocks can be associated with events in the flowsheet, i.e. they can run when a specific object is calculated or when an error occurs in the calculation. A script can also run when the simulation is opened, closed and saved.

Scriptmanager.jpg

Managing Scripts

To open the Script Manager, go to Scripts > Script Manager.

To insert a new script, click on the New button. To remove an existing script, close its window using the X button on the right of the tabstrip.

To save/update the scripts, click on the Save/Update button.

To execute/test the script, click on the Run Script button.

Linking Scripts to Events

To link a script to an event in the flowsheet, click on the Link checkbox in the Script Editor window. The following events are available for linking:

  • Simulation: Opened, Closed and Saved.
  • Solver: Calculation Started, Finished and Recycle Loop (raised when there are recycles in the flowsheet and the solver iterates through them to achieve convergence).
  • Remaining Objects in the flowsheet: Object Calculation Started, Finished and Error.

The scripts don't necessarily need to be associated with events. You can keep a collection of non-associated scripts and run them at your will using the Script Manager.

Objects Available to Scripts

All flowsheet objects can be manipulated by the scripts directly through its graphic object names. Some Intellisense is available for the Flowsheet, Solver, and remaining flowsheet objects. For instance, you can access all properties and methods of the Flowsheet object directly through the popup listbox:

Intellisense.jpg

For instance, you can access the properties of a Material Stream named "MAT-001" by directly typing "MAT_001" (replace "-" with "_" to avoid compilation errors) and then the dot (".") character to access its properties:


 MAT_001.ClearAllProps()

Script Examples

The examples below show how to do specific tasks using the internal functions available in the DWSIM namespace.

  • With IronPython, if you want to use functions avaiable in other .NET assemblies, use the "import clr" command followed by "clr.AddReference("myassembly") where "myassembly" is the name of the assembly you want to load:

 import clr
 clr.AddReference("System")

  • In IronPython, namespaces are separated by a dot (.), just like in C# and VB.NET. In IronRuby, the namespace separator is the double colon (::) .

Using the Script Tool to manipulate objects

Add/Remove

To add objects, use the AddObjectToSurface function available in the FormSurface Class inside the Flowsheet class.

The arguments for this function are:

AddObjectToSurface(type, xcord, ycord, tag)

type = the type of object to add (TipoObjeto Enumeration located in the Microsoft.MSDN.Samples.GraphicObjects namespace) link
xcord = x-coordinate of the object in the flowsheet
ycord = y-coordinate of the object in the flowsheet
tag = display name of the object in the flowsheet

To remove objects, use the DeleteObject function located in the Flowsheet class. The argument for this function is the display name of the object that you want to remove from the flowsheet:

DeleteObject(tag)

tag = display name of the object in the flowsheet

Complete example (IronPython)


 import clr
 import DWSIM
 # import all classes from the 'Microsoft.MSDN.Samples.GraphicObjects' namespace 
 from Microsoft.MSDN.Samples.GraphicObjects import *
 # add a material stream to the flowsheet
 Flowsheet.FormSurface.AddObjectToSurface(TipoObjeto.MaterialStream,20,20,"MAT-000")
 # add a valve to the flowsheet
 Flowsheet.FormSurface.AddObjectToSurface(TipoObjeto.Valve,50,20,"VALV-000")
 # remove the 'MAT-000' object from the flowsheet
 Flowsheet.DeleteObject("MAT-000")
 # remove the 'VALV-000' object from the flowsheet
 Flowsheet.DeleteObject("VALV-000")

Connect/Disconnect

Every object in the flowsheet is composed by its graphic representation (GraphicObject class) and by another class which inherits from the Unit Operation Base Class (or Stream class for Material and Energy streams). The GraphicObject instance is actually a property from the UO base class, so for a valve object named v1, its graphical representation and all its properties are stored in the v1.GraphicObject property.

To connect and disconnect objects one to/from another, you will need the references to their graphical representations in the flowsheet. You can do this in two ways:

- use the GetFlowsheetSimulationObject function

ms1 = Flowsheet.GetFlowsheetSimulationObject("MAT-000")
v1 = Flowsheet.GetFlowsheetSimulationObject("VALV-000")

This function returns a reference to the Base Class for the object of interest. After you get the reference, cast the GraphicObject property from it to a variable of the 'reference' type:

IronPython:


 x1 = clr.Reference[GraphicObject](ms1.GraphicObject)
 x2 = clr.Reference[GraphicObject](v1.GraphicObject)

Variables x1 and x2 now contain a reference to the graphicobject instance of the Material Stream "MAT-000" and Valve "VALV-000", respectively. Now, use the ConnectObject function to connect one graphic object to another.

Flowsheet.ConnectObject(x1,x2)

To disconnect two objects, use the DisconnectObject function:

Flowsheet.DisconnectObject(x1,x2)

Complete example (IronPython)


 import clr
 import DWSIM
 # import all classes from the 'Microsoft.MSDN.Samples.GraphicObjects' namespace 
 from Microsoft.MSDN.Samples.GraphicObjects import *
 # get a reference to the Base Class of the "MAT-000" object
 ms1 = Flowsheet.GetFlowsheetSimulationObject("MAT-000")
 # get a reference to the Base Class of the "VALV-000" object
 v1 = Flowsheet.GetFlowsheetSimulationObject("VALV-000")
 # get a reference to the graphical representation of the "MAT-000" object
 x1 = clr.Reference[GraphicObject](ms1.GraphicObject)
 # get a reference to the graphical representation of the "VALV-000" object
 x2 = clr.Reference[GraphicObject](v1.GraphicObject)
 # to connect one object to another:
 Flowsheet.ConnectObject(x1,x2)
 # to disconnect one object from the other:
 Flowsheet.DisconnectObject(x1,x2)

- use the GetFlowsheetGraphicObject function

ms1 = Flowsheet.GetFlowsheetGraphicObject("MAT-000")
v1 = Flowsheet.GetFlowsheetGraphicObject("VALV-000")

This function returns a reference to the GraphicObject property for the object of interest. Variables ms1 and v1 now contain a reference to the graphicobject instance of the Material Stream "MAT-000" and Valve "VALV-000", respectively. Use the ConnectObject function to connect one graphic object to another.

Flowsheet.ConnectObject(ms1,v1)

To disconnect two objects one from another, use the DisconnectObject function:

Flowsheet.DisconnectObject(ms1,v1)

Complete example (IronPython)


 import clr
 import DWSIM
 # import all classes from the 'Microsoft.MSDN.Samples.GraphicObjects' namespace 
 from Microsoft.MSDN.Samples.GraphicObjects import *
 # get a reference to the GraphicObject property of the "MAT-000" object
 ms1 = Flowsheet.GetFlowsheetSimulationObject("MAT-000")
 # get a reference to the GraphicObject property of the "VALV-000" object
 v1 = Flowsheet.GetFlowsheetSimulationObject("VALV-000")
 # to connect one object to another:
 Flowsheet.ConnectObject(ms1,v1)
 # to disconnect one object from another:
 Flowsheet.DisconnectObject(ms1,v1)

Referencing objects, getting and setting properties

Get a reference to a simulation object

IronPython:


 import clr
 from DWSIM import *
 from Microsoft.MSDN.Samples.GraphicObjects import *
 ms = Flowsheet.GetFlowsheetSimulationObject("ms1")

Get and set properties

You can get and set object properties if you know the code for the property that you want to work with. View the page Object Property Codes for a list of property codes for all flowsheet objects.

To work with properties in a script, get a reference to the object's Base Class using the GetFlowsheetSimulationObject function described above. Then, use the object's SetPropertyValue and GetPropertyValue functions to set and get property values, respectively.

GetPropertyValue(propname, [optional] usystem)

propname = property code
usystem = optional parameter - unit system used to return the property converted to the desired unit, default is SI. link 
SetPropertyValue(propname, value, [optional] usystem)

propname = property code
value = new value of the property to write
usystem = optional parameter - unit system used to write the property converted to the desired unit, default is SI. link 

To write component molar fractions in a Material Stream, iterate through all components in the mixture phase and write the values directly using:

IronPython:


 for c in ms.Fases["0"].Componentes.Values:
     c.FracaoMolar = 0.2

Alternatively, you can use the SetOverallComposition shortcut function of the Material Stream Base Class. It does just what you did above in the loop, making things a little easier on your side. All you have to do is to create an array with the compositions and pass it as an argument:

IronPython:


 from System import Array
 comp = Array[float]([0.2,0.2,0.2,0.2,0.2])
 ms.SetOverallComposition(comp)

If you want to print component's translated names, use, inside the loop:

print DWSIM.App.GetComponentName(c.Nome)

After specifying all required properties, call the calculator's CalculateObject routine passing the Flowsheet object and Nome property of the object (the unique ID of the object) as arguments:

Solver.CalculateObject(Flowsheet, ms.Nome)

Then you can get some calculated properties and print them into the console window, like this:

print DWSIM.App.GetPropertyName("PROP_MS_25")
print ms.GetPropertyValue("PROP_MS_25")

Complete example (IronPython)


 import clr
 from DWSIM import *
 from Microsoft.MSDN.Samples.GraphicObjects import *
 # get a reference to the base class object
 ms = Flowsheet.GetFlowsheetSimulationObject("ms1")
 # set some properties
 ms.SetPropertyValue("PROP_MS_0", 400)
 ms.SetPropertyValue("PROP_MS_1", 101325)
 ms.SetPropertyValue("PROP_MS_2", 100)
 
 # iterate through all components and set the molar fraction of each
 # (in this example, 5 components were pre-added to the simulation)
 for c in ms.Fases["0"].Componentes.Values:
 	print DWSIM.App.GetComponentName(c.Nome)
 	c.FracaoMolar = 0.2
 	print c.FracaoMolar
 
 # or use the SetOverallComposition function passing an array as argument
 from System import Array
 comp = Array[float]([0.2,0.2,0.2,0.2,0.2])
 ms.SetOverallComposition(comp)
 
 # calculate the object using the Solver
 Solver.CalculateObject(Flowsheet, ms.Nome)
 # get and print a property value and its name
 print DWSIM.App.GetPropertyName("PROP_MS_25")
 print ms.GetPropertyValue("PROP_MS_25")

Additional Information

DWSIM Application Programming Interface (API) Online Help

Useful Links

IronPython Documentation
Using the Python Standard Library
Python for Beginners
VBScript examples