Running the Examples
Before you delve into the Schema Definition and the source code of the Mixer simulator, we suggest you run the three Project Models that we prepared to gain more insights from a simulation user's perspective. The three Project Models involve a simple mixer network, a solution to the Great Lakes problem from Chapra and Canale [Cha98], and a more complex mixer network with subassemblies.
Transient: is a simple mixer network to explore the capability of the simulator and how a transient input source with variable concentration is handled.
Lakes: is a model that provides the solution to the Great Lake problem in Chapra and Canale [Cha98].
Plant: demonstrates a more complex example with subassemblies.
We assume that you have the general knowledge about the SansGUI software and have gone through A Tour of SansGUI Examples in the SansGUI Getting Started guide.
The default simulator DLL in the sim directory was not built with the MATLAB libraries. If you have the MATLAB software installed, you can use the MATLAB engine in the simulator. You need to specify the Mixer Simulator DLL that is built with the MATLAB libraries:
Load the Project Model into the SansGUI Environment.
From the Object tab in the Left Pane, locate the SimControl.Cycle.Mixer_Default object.
Double click on the Default simulation control object icon or its name to obtain an Object Properties dialog.
In the Simulator Program Path attribute, right click on the Value cell to obtain a context menu.
Select Input Assistant from the context menu.
Click on the <File/Dir> button in the Input Assistant.
Use the File Locator dialog to find any of the four DLLs that were built with MATLAB libraries under the samples\Mixer subdirectory.
Mixer Simulator DLL with MATLAB Engine |
Language IDE |
Mixer_1_0\Release_MATLAB\Mixer_1_0.DLL |
MSVC++ Implementation |
Mixer_1_0\Trace_MATLAB\Mixer_1_0.DLL |
MSVC++ Implementation |
Mixer_1_0F\Release_MATLAB\Mixer_1_0F.DLL |
CVF Implementation |
Mixer_1_0F\Debug_MATLAB\Mixer_1_0F.DLL |
CVF Implementation |
Close the File Locator and the Input Assistant dialogs.
In the Object Properties dialog of the Default simulation control object, select Call MATLAB Engine in the Solver Type attribute.
Click OK to commit the changes.
Now the simulator DLL for the Project Model has been switched to incorporate the MATLAB engine.
Alternatively, you can copy any of the above DLLs over the Mix_1_0.DLL file under the sim subdirectory. This effectively installs the simulator with the MATLAB calling capability as default. The Simulator Program Path of each Project Model can then be left blank.
In this model, we configured three chemical mixers in a small network. The first mixer takes a constant input source and the second mixer takes a variable input source with a transient function. Both of them dispense their output to a third mixer, which then sends its output to a sink. An interesting experiment in this Project Model is related to a pipe that connects the first two mixers. In the first scenario, we simply shut the fluid flow off by having the flow rate 0. We then allow the mixture to be dispensed from the second mixer to the first by setting the flow rate to 2 in the second scenario.
Load the Transient.sgp Project Model into the SansGUI environment from the samples\Mixer subdirectory of the SansGUI installation directory.
Examine the configuration of the mixer network. Mixer-1 takes an input source with a constant concentration while Mixer-2 takes an input source with transient concentrations determined by a step function.
Double click on the Var-Source icon to find out the two input attributes: Initial Concentration and Steady State Concentration. The Steady State Concentration forms an asymptote for the actual concentrations through time, generated by a step function. More on this can be found in the Understanding Class Base.Source section.
To examine the flow rate of a pipe, simply double click on the pipe to obtain a Link Properties dialog. You can also list out all the pipe data by selecting the Component tab in the Left Pane, scroll down to reveal the Pipe class, and then single click on the Pipe class name or its icon. All the pipe data will be displayed in a Grid View in the Right Pane. The Flow Rates are not protected, meaning that you can change them right in the Grid View. The Concentrations, however, are protected because they are calculated results from the simulation.
The properties of any Mixer part can be examined by double clicking on it in the Canvas View. There are two reference objects associated with all the Mixer parts: a Reactor Table and a Constant Matrix. These are predefined in the distributed Object Library and you don't really need to change them. The Constant matrix and the constant vector in the Default reactor table will be used to store the constants in the linear equations. These constants are actually calculated from the input values and the model configuration at the beginning of a simulation run.
There are two additional matrices. One is used to store the inverse matrix of the original constant matrix and the other is used for scratch purposes during the calculation processes.
The Solver is a reference object that contains four object references: A Reactor Table, a Constant Matrix, an Inverse Matrix, and a Scratch Matrix. The object references of the reactor table and the constant matrix have to match those of the mixers and serve the same purposes.
Run simulation by clicking on the Run In-Process button in the Run toolbar.
Click on the Result View in the Bottom Pane to examine the results.
Click on the Plot Results button in the Run toolbar to see a chart of the concentrations in the mixers.
The concentration in Mixer-1 stays constant because its input from Mixer-2 was set to 0 (shut-off).
Examine the contents of the Constant and Inverse objects under the Matrix.Calculation class and the Default object under the Table.Reactor class.
Set the Flow Rate of the pipe from Mixer-2 to Mixer-1 (labeled M2-M1) to 2. Accordingly, set the Flow Rate of the output pipe from Mixer-2 (M2-M3) to 12 and the Flow Rate of the output pipe from Mixer-1 (M1-M3) to 2.
Before we run another simulation, make sure that you have reset the Current Time attribute in the simulation control object SimControl.Cycle.Mixer_Default to 0 and remove all part override values by selecting Edit>Clear Override Values from the pull-down menu. The Flow Rates of the pipes will not be cleared because they are input attributes (not of output or in/out scope).
Repeat the procedures above and observe the changes. The variable concentration from Mixer-2 now affects that of Mixer-1.
Select a different Solver Type (Naive Gauss Elimination, LU Decomposition, or Call MATLAB Engine) in the simulation control object and run the simulation again.
Change some of concentrations and flow rates in the model and run the simulation. Plot the results out and see if you can make sense out of the changes.
Create a new mixer below Mixer-2 and another variable source as its input. Connect the new input to the newly created mixer and then connect the new mixer to Mixer-3. The flow rate of the output pipe from Mixer-3 will have to be changed so that the mixture volume in Mixer-3 can stay constant.
The following exercises are reflect some of the more advanced ideas for simulation developers. You are encouraged to browse through them for the first time and come back here once you are familiar with the entire Mixer Example.
Run either the MSVC++ or CVF IDE and load the programming project into the environment. Locate the SG_xInit_Base_Container_Reactor function in either Base_Container_Reactor.c or Base_Container_Reactor.f and add code for checking the balance between all input flow rates and output flow rates. The sum of all input flow rates and the sum of all output flow rates should be the same so that the volume of the mixture in the reactor can stay constant. Add the code to right before the function returns. If the sums are different, send an error message out and return SG_R_STOP.
With the input and output balance checking in place, it will not be able to solve the Great Lakes problem to be shown next. We need to add an attribute with an on/off toggle to indicate whether checking or not checking the input/output balance is desirable.
Add another input attribute Time Constant to the variable source so that it is not hardwired in the simple lag for the first-order step response (originally coded to be 1 minute). The step response is implemented in the SG_xPreEval_Base_Source_Variable function in either Base_Source_Variable.c or Base_Source_Variable.f. You will need to update all the Object Libraries and Project Models with the new version in order to take advantage of this newly created attribute.
This example solves the problem of concentrations of chloride in the Great Lakes, taken from Problem 12.7 of Chapra and Canale's text [Cha98]. To model the direct input to each of the lakes, we use a constant source with the Flow Rate in its connecting pipe set to 1. Because the measuring units are not given, we assume that multiplying the concentration in the constant source and the unit flow rate (1) will yield the direct input. There is also no balancing between input flow rates and output flow rates; therefore, the balance checking mechanism you implemented in the above exercise will have to be turned off. This example does not involve transient conditions. Only one cycle is needed to calculate the results.
Load the Lakes.sgp Project Model into the SansGUI environment from the samples\Mixer subdirectory of the SansGUI installation directory.
Examine the model configuration in the Canvas View.
Click on the Component tab in the Left Pane and then click on the Source class to see all the direct inputs in the Grid View in the Right Pane.
Scroll down the Tree View and click on the Link class to see the Flow Rates of all the pipes. The direct inputs have their connecting pipes' Flow Rates set to 1.
Click on the Container class up on top to see the concentrations of all the lakes in a Grid View in the Right Pane. They are initially set to -1 to represent an unknown value.
While the concentrations associated with the lakes are displayed in the Grid View from the previous step, click on the Run In-Process button in the Run toolbar. The simulation will go through one cycle with the calculated concentrations for all the lakes updated in the Grid View.
You can also click on the Result View in the Bottom Pane to see the results.
Click on the Object tab in the Left Pane and scroll down to reveal the matrices.
Double click on the Matrix.Calculation_Constant object to open the Object Properties dialog to see the constant matrix for the simultaneous equations.
Do the same for the Table.Reactor_Default object. You can see the r-h-s constants and the solution vector.
If you used LU Decomposition or called MATLAB engine, double click on the Inverse matrix object to examine the inverse matrix of the original constant matrix.
One of the advantages of the SansGUI Modeling and Simulation Environment is that it can handle subassembly replication. In this example, we demonstrate a more complex model with three similar subassemblies: Cluster-1, Cluster-2, and Cluster-3. When we built the model, Cluster-1 was created first with three ports exported for connections at its parent assembly. Cluster-2 and Cluster-3 are copies of Cluster-1. They are created by the Clone Part menu selection from the Cluster-1's right-click context menu. The exported ports are uniquely numbered by the inner part number (1, 3 and 4) so that the pipe connections can be clearly identified.
Load the Plant.sgp Project Model into the SansGUI environment from the samples\Mixer subdirectory of the SansGUI installation directory.
Right click on Cluster-1 in the Canvas View in the Right Pane to obtain a context menu.
Select Parameters and Ports from the context menu. An Assembly Parameters and Ports dialog is displayed.
With the tabs at the bottom of the dialog, click on the Defined Ports tab.
The definitions of the ports from the subassembly are shown. They cannot be edited because the definitions are located in the exported ports in the subassembly.
Close the dialog by clicking on the Cancel button.
Right click again on the Cluster-1 part and select Open Subassembly from the context menu.
The Right Pane will now have two tabs, a TOP\Cluster-1 tab and a TOP tab.
The parts in Cluster-1 subassembly is shown. The exported ports are marked with a little square coming out from the associated parts.
Move the mouse pointer to one of the exported port and right click on it. Select Properties from the context menu. A Port Properties dialog is displayed. Take a look at the definition of the exported port in the dialog.
Close the Port Properties dialog.
You can examine the Concentrations of the components and the Flow Rates of the pipes by using the methods described in the previous examples.
Click on the Run In-Process button in the Run toolbar and let the simulation go through 50 cycles.
Once the simulation is ended, click on the Result View in the Bottom Pane to see the calculated results. Because there are variable sources involved, it simulated the system with transient conditions.
Click on the Plot Results button in the Run toolbar to get an X-Y plot in a dialog.
Select a rectangular area on the plot to zoom in. To do so, move your mouse pointer to a point on the chart to be the upper-left corner of the selection rectangle, click and hold the mouse button while dragging the mouse pointer to another point on the chart to be the lower-right corner of the rectangle. Once the mouse button is released, the selected rectangle will be zoomed to fill the entire charting area.
You can repeat the rectangle selection for multi-level zooming.
To go back to the original plot, right click on the chart and select Undo Zoom from the context menu.
You can examine the constant matrix, the inverse matrix and the reactor table to obtain the linear equations and their solution.
You can change a few input concentrations or flow rates to perform more simulation runs.
Before you start another simulation run, make sure that 1) you have reset the Current Time attribute to 0 located in SimControl.Cycle.Mixer_Default object under the Object tab and 2) select Edit>Clear Override Values from the pull-down menu. With these two operations, the residual values from the previous simulation run will not affect the results in the next run. In certain situations, however, resetting of the simulated time many not be desirable for each simulation run; therefore, we leave it as an option for the users.
Mixer Example for SansGUI Version 1.0
Copyright © 2001-2003 ProtoDesign, Inc. All rights reserved.