Simgua allows you add new functionality to the application or to automate a repetitive task using Visual Basic code. This support is similar to the macro support you might find in Microsoft Word or Excel. Simgua macros are developed using the Visual Basic programming language: exactly the same language and syntax used to develop your model equations. Word and Excel also use Visual Basic, but Simgua’s variant of the language is more powerful than Microsoft’s. For instance, full inheritance for object-oriented programming is supported by Simgua and Simgua does not require the use of get or set keywords.
Developing macros can be a complicated task. They allow you to interact with every aspect of Simgua and to modify every property of your models. Here are some possibilities of features that could be implemented with Macros:
· An optimization algorithm to automatically try different model configurations and see which yielded the best results
· Export or Import algorithms that allow you to import data sources or export your results or the model itself into custom formats
· Automatic model construction based on programmatic conditions
· Advanced data analysis algorithms implementing custom statistics
· Elimination of repetitive tasks that must be carried out many times
The Visual Basic programming language used in Simgua macros is very rich and extremely powerful with many different ways of implementing the same feature. To ease your entry into macro development, Simgua includes a “Recording” function. To access it, simple create a new macro and click the large “Record” button. Now, as you interact with Simgua and change your models, the macro commands for your actions will automatically be inserted into your macro. You can see what the specific commands are that can recreate your actions and then you can replay them without needing to write a single line of code on your own.
The best way to get your feet wet with Simgua macros is to take a look at some samples. The following are a few basic examples of Simgua macros that will illustrate the basic approach to writing macros.
This classic example program pops up a simple message on your computer screen that says “Hello World”. It is the epitome of simplicity using Simgua and takes just one line:
MsgBox “Hello World”
The MsgBox function displays the string (a small chunk of text enclosed in quotes) passed to it in a small window. Most methods in macros can be used with or without parentheses. Thus, the above could also be written as the following.
MsgBox(“Hello World”)
One thing to note is that the Simgua macro language is what is known as a “strongly typed” language. That means that because the MsgBox method expects you to pass it a string, you cannot pass it any other data type and trust it to be converted into a string. So for instance the following would result in an error:
MsgBox(6)
6 by itself is a numeric data type which the MsgBox method does not know how to handle. The correct way to write this would be:
MsgBox(“6”)
This example runs a simulation of the currently opened model. It then displays a message box with the average value over the course of the simulation of the stock called “Population” that was in the original model.
dim res as Results
dim average as double
res=FrontModelWindow.Run.Results
average=mean(res.values(FrontModelWindow.Item("Population")))
Msgbox "Average Value of 'Population': "+str(average)
The first two lines of this macro define variables that are later used to store values during the macro processing. The third line accesses the Simgua model window that is foremost in the application (in front of all the other model windows). It then calls the ModelWindow class’s Run function to run a simulation. The Run function returns an object of an AnalysisWindow class that represents a standard Simgua analysis window. The AnalysisWindow class contains a property called Results that contains the numerical results of the simulation.
The second-to-last line calculates the mean for the primitive called “Population” in the model. We locate an instance of that primitive using the ModelWindow class’s Item property which takes a primitive name and returns a reference to the first primitive found in the model with the same name. The Results class’s Values function returns an array of all the values that the primitive takes on over the course of the simulation. Lastly we display the average of these values using a message box. The variable average is a numeric data type so we must convert it to a string using the str method before we can display it with MsgBox.
This sample iterates through all primitives in the model and adds a copyright string to each primitive’s Info property. Note that EOL is a constant representing an end-of-line or return character.
dim p as Primitive
FrontModelWindow.InsertUndoPoint
for each p in FrontModelWindow.Root.Flatten
p.Info = p.Info+EOL+"Copyright (c) Focused Systems"
next
FrontModelWindow.Layout
Since we are going to be changing the state of the model, it is good practice to allow the user to undo our changes. We do this by calling the InsertUndoPoint method on the model window that we will be changing.
Simgua models are stored in a tree structure where there are two basic node types. These types are Standard nodes, which stocks, parameters, displays, and flows are all examples of; and Container nodes, which folders and components are. Container nodes hold both Standard nodes and other Container nodes in a hierarchical manner. The Root object of the ModelWindow points to the root container node of the entire model. The Flatten method can be called on any container object to return an array of all the primitives within the container. We iterate through each of the primitives using a for-loop and we change the primitives’ info property. Lastly, we must tell Simgua to update its user interface by calling the Layout method on the model window. Simgua could update the user interface automatically but to improve performance, we have left that task in the hands of the macro developer.
Using Simgua macros there are many different ways to implement the same function. Here is a second (and lengthier) way of implementing the above routine. In this second sample, recursion with functions is used to walk through the model’s hierarchy rather than using the Flatten function.
FrontModelWindow.InsertUndoPoint
Sub AddCopyright(c as container)
dim i as integer
for i=0 to c.count-1
c.item(i).info=c.item(i).info+EOL+"Copyright (c) Focused Systems"
if c.item(i) isa container then
AddCopyright(container(c.item(i)))
end if
next
End Sub
AddCopyright(FrontModelWindow.root)
FrontModelWindow.Layout
This example automates the creation of a large number of stocks connected by flows. Such models can be used to simulate many things including, for instance, rivers where each stock represents one small section of the river. This example illustrates the use of looping and prompting the user to enter values.
FrontModelWindow.InsertUndoPoint
dim i as integer
dim segments() as stock
dim segmentCount as integer = Read("How many Segments?", 10)
for i=1 to segmentCount
segments.append FrontModelWindow.CreateStock("Segment "+str(i))
next
for i=1 to ubound(segments)
dim connect as flow = FrontModelWindow.CreateFlow("Connection "+str(i))
connect.Rate="[Alpha]"
connect.Alpha=segments(i-1)
connect.Omega=segments(i)
next
FrontModelWindow.Layout
Hopefully these examples have given you a taste of what can
be accomplished with Simgua macros. This functionality is so powerful that many
of Simgua’s features are implemented with macros. For instance, the Risk
Assessment analysis functionality of Simgua is completely written with a macro.
How can see how these more advanced features work by holding down your
computer’s Shift key when you run the macro analysis (for risk assessment, this
is when you press the “Assess Risk” button in the risk assessment window). The
macro source code will then be copied to your computer’s clipboard for you to
study.
| Global Methods |
|---|
| Sub beep() |
| Plays the computer's "beep" sound. |
| Function ExecuteMacro(name as string, opts as Dictionary = nil) as dictionary |
| Executes another macro specified by name. Opts is a set of options that can be passed to the macro. Returns a dictionary containing the macro's Returns dictionary. Returns nil if the macro could not be found. |
| Function Rand() as double |
| Returns a random number between 0 and 1. |
| Sub SetRandSeed(seed as double) |
| Sets the seed for Simgua's random number generator. This generator only affects values generator for the currently running macro. |
| Function GetClipboard() as string |
| The contents of the computer's clipboard. |
| Sub SetClipboard(text as string) |
| Sets the contents of the computer's clipboard. |
| Function ConsoleText() as string |
| The contents of the macro's console. |
| Sub MsgBox(msg as string) |
| Opens up a simple message box displaying msg. |
| Sub Quit() |
| Quits Simgua. |
| Function OperatingSystem() as string |
| The name of the user's operating system. Either: "Macintosh", "Windows", or "Linux". |
| Sub ShowUrl(location as string) |
| Opens the user's web browser and displays the specified url. |
| Function Download(location as string) as string |
| Downloads the specified web site and returns its contents as a string. |
| Sub Speak(phrase as string, interrupt as Boolean = false) |
| Speaks phrase using your computer's speech synthesizer. If interrupt is true, any new speak commands will replace ongoing speak commands, otherwise speak commands will be queued.. |
| Function NormalCDF(x as double, mean as double, sigma as double) As double |
| The Normal Distribution cumulative density function. |
| Function LognormalCDF(x as double, mean as double, sigma as double) As double |
| The Lognormal Distribution cumulative density function. |
| Function GammmaCDF(x as double, shape as double, scale as Double) As Double |
| The Gamma Distribution cumulative density function. |
| Sub Write(text as string) |
| Writes text to the console. |
| Sub WriteLn(text as string) |
| Writes text to the console and appends a new line to it. |
| Sub WritePrefBoolean(key as string, value as boolean) |
| Saves a boolean as a preference value. This value can be restored in later runs of the macro. Make sure the key is unique to your macro as other macros may overwrite it. |
| Sub WritePrefDouble(key as string, value as double) |
| Saves a double as a preference value. This value can be restored in later runs of the macro. Make sure the key is unique to your macro as other macros may overwrite it. |
| Sub WritePrefInteger(key as string, value as integer) |
| Saves a integer as a preference value. This value can be restored in later runs of the macro. Make sure the key is unique to your macro as other macros may overwrite it. |
| Sub WritePrefString(key as string, value as string) |
| Saves a string as a preference value. This value can be restored in later runs of the macro. Make sure the key is unique to your macro as other macros may overwrite it. |
| Function ReadPrefBoolean(key as string, default as boolean) As boolean |
| Restores a previously saved preference value. |
| Function ReadPrefDouble(key as string, default as double) As double |
| Restores a previously saved preference value. |
| Function ReadPrefInteger(key as string, default as integer) As integer |
| Restores a previously saved preference value. |
| Function ReadPrefString(key as string, default as string) As string |
| Restores a previously saved preference value. |
| Function Ticks() as integer |
| The number of ticks (1/60 of a second) since the computer started operating. Can be used to implement timers. |
| Sub Delay(seconds as double) |
| Pauses the execution of the macro for the specified time. |
| Function read(msg as string, default as string) as string |
| Requests the user to input a string. Msg is a prompt displayed to the user. |
| Function read(msg as string, default as double) as double |
| Requests the user to input a number. Msg is a prompt displayed to the user. |
| Function read(msg as string, default as boolean) as boolean |
| Requests the user to input a boolean. Msg is a prompt displayed to the user. |
| Function execute(cmd as string) as string |
| Executes a shell command and returns the results. Note that the shell behaves differently on Macintosh, Windows and Linux and you should check the OperatingSystem property if you are developing a cross-platform macro. |
| Function microseconds(count as double, units as string) as double |
| Returns count specified in the units units in microseconds. |
| Function baseTime(count as double, units as string) as double |
| Returns count specified in the units units in microseconds. |
| Function seconds(microseconds as double) as double |
| Converts microseconds to seconds. |
| Function minutes(microseconds as double) as double |
| Converts microseconds to minutes. |
| Function hours(microseconds as double) as double |
| Converts microseconds to hours. |
| Function days(microseconds as double) as double |
| Converts microseconds to days. |
| Function weeks(microseconds as double) as double |
| Converts microseconds to weeks. |
| Function months(microseconds as double) as double |
| Converts microseconds to months. |
| Function years(microseconds as double) as double |
| Converts microseconds to years. |
| Function LOWESS(x() as double, y() as double, smoothness as Double = 0.25, iterations as integer = 0) as double() |
| LOWESS is a robust algorithm for smoothing data series. This function returns the smoothed y values for the given set of X and Y data. |
| Function Mean(values() as double) as double |
| Calculates the mean of a set of numbers. |
| Function StdDev(values() as double, isPopulation as boolean = false) as double |
| Calculates the standard deviation of a set of numbers. |
| Function Correlation(x() as double, y() as double) as double |
| Calculates the correlation between two sets of numbers. |
| Function Max(values() as double) as double |
| Returns the maximum value from an array of numbers. |
| Function Min(values() as double) as double |
| Returns the minimum value from an array of numbers. |
| Function NewModelWindow(show as boolean = true) as ModelWindow |
| Creates a new model window and returns an object pointing to it. If show is true, the window will be immediately shown; otherwise it will be initially hidden. |
| Function OpenModelWindow(file as folderitem) as ModelWindow |
| Opens a Simgua model file. An object pointing to the new model window is returned. Pass a folderitem with a path of "". To open a selection dialogue. |
| Function NewModel() as Model |
| Creates a new model and returns an object pointing to it. This is a "silent" model that will not create a new window in the Simgua user interface. |
| Function OpenModel(file as folderitem) as Model |
| Opens a Simgua model file. An object pointing to the new model is returned. This is a "silent" model that will not create a new window in the Simgua user interface. |
| Function NewDataWindow(show as boolean = true) as DataWindow |
| Creates a new data window and returns an object pointing to it. If show is true, the window will be immediately shown; otherwise it will be initially hidden. |
| Function Selection() as Primitive |
| The currently selected primitive in the foremost model window. Should be compared to nil to determine if there really is a selection. |
| Function GetWindow(name as string, suppressWarning as boolean = false) as Window |
| Returns a window based on its name. It is recommended that you test the result of this function against nil to make sure the window was actually found. If suppressWarning is false and the window could not be found an error message will be displayed. |
| Function ModelWindowCount() as integer |
| The total number of model windows currently open. |
| Function GetModelWindow(index as integer) as ModelWindow |
| The model window specified by the parameter index. The foremost model window is at index 0. |
| Function FrontModelWindow() as ModelWindow |
| The foremost model window. |
| Function AnalysisWindowCount() as integer |
| The total number of analysis windows currently open. |
| Function GetAnalysisWindow(index as integer) as AnalysisWindow |
| The analysis window specified by the parameter index. The foremost analysis window is at index 0. |
| Function FrontAnalysisWindow() as AnalysisWindow |
| The foremost analysis window. |
| Function GetOpenFolderitem() as FolderItem |
| Opens a file selection dialog and allows the user to select a Folderitem. If the user cancels the selection nil is returned. |
| Class Window |
|---|
| The Window class allows you to interact with and manipulate windows within Simgua. All window classes inherit from this class. Do not create new windows using the new operator. You must use the appropiate function to create windows; for instance: NewModelWindow(). |
| Sub Show() |
| Brings the window to the front of all windows in Simgua and makes it visible. |
| Sub Hide() |
| Makes the window invisible. |
| Sub Close() |
| Closes the window. |
| Function Width() as integer |
| The width of the window in pixels. |
| Function Height() as integer |
| The height of the window in pixels. |
| Sub SetSize(w as integer, h as integer) |
| Sets both the width and height of the window in one step. |
| Sub SetLocation(l as integer, t as integer) |
| Sets both the left and top positions of the window in one step. |
| Function Left() as integer |
| The left position of the window in pixels. |
| Function Top() as integer |
| The top position of the window in pixels. |
| Function Title() as string |
| The window's title. |
| Class DataWindow |
|---|
| The Data Window Class allows you to create and interact with windows to display data and text to users of Simgua. Each data window may have one or more frames that are displayed as tabs in the window. Each frame contains data. |
| Sub AddTableFrame(name as string) |
| Adds a tabular data frame to the window. |
| Sub AddTextFrame(name as string) |
| Adds a textual data frame to the window. |
| Sub AddChartFrame(name as string, xAxis as string = "", yAxis as string = "", xLog as boolean = false, yLog as boolean = false, threeDimensional as boolean=false) |
| Adds a scatterplot or bar chart frame to the window. |
| Sub AddPieChartFrame(name as string, ThreeDimensional as boolean = false) |
| Adds a pie chart frame to the window. |
| Sub AddSurfaceChartFrame(name as string, xAxis as string="", yAxis as string="", zAxis as string = "", filled as boolean=false) |
| Adds a surface chart frame to the window for plotting three-dimensional data. If filled is set the surface will be solid, otherwise it will be displayed as a wireframe. |
| Function FrameCount() as integer |
| The count of frames in the window. |
| Function Frame(index as integer) as Frame |
| Returns a frame from the window. The first frame has an index of 0. |
| Sub ClearFrames() |
| Clears all the frames from the window. |
| Class Frame |
|---|
| The frame class contains data. Each frame class is owned by a Data Window. |
| Function Text() as string |
| The text of a textual frame. |
| Sub SetCell(row as integer, column as integer, text as string, bold as boolean = false) |
| Sets the contents of cell in a tabular frame. The cell can be set to be bolded. |
| Sub ClearTable() |
| Clears a table in a tabular frame. |
| Sub AddSeries(name as string, xVals() as double, yVals() as double, col as Uint64 = -1, xVals2() as double=nil, yVals2() as double=nil) |
| Adds a data scatterplot series to a chart frame. Each data series should have a unique name. Col is the color of the data series in a four-byte hexadecimal notation (&h00ff0000 is pure red, &h0000ff00 is pure green, &h000000ff is pure blue, and &hAAff0000 is a partially transparent red). A value of -1 for the color means a default color will be chosen. If a second pair of x and y values are supplied, then the area between the two lines is filled. |
| Sub AddBarSeries(name as string, values() as double, col as Uint64 = -1) |
| Adds a bar chart series to a chart frame. |
| Sub SetChartLabels(labels() as string) |
| Sets the x labels for a scatter or bar chart. |
| Sub SetData(values() as double, labels() as string) |
| Sets the data for a pie chart. |
| Sub SetData(xVals() as double, yVals() as double, zVals() as double) |
| Sets the data for a surface chart. |
| Sub ClearChart() |
| Clears a chart in a chart frame. |
| Class ModelWindow |
|---|
| The model window is the main window of the Simgua user interface. The ModelWindow Class allows you to interact with this type of window. Use NewModelWindow to create a new ModelWindow. |
| Function Run() as AnalysisWindow |
| Runs the simulation of the model. Returns an Analysis Window containing the results of the analysis. This function does not return until the analysis is complete. |
| Function RunSilently() as Results |
| Runs the simulation of the model without displaying an analysis window. A results object containing the results of the simulation is returned. This function does not return until analysis is complete. |
| Sub Layout(justData as boolean = false) |
| Updates the display of information in the main window. Redraws the model diagram and regenerates the model library browser. If justData is true then only the values of primitives are updated. |
| Function Selected() as Primitive |
| The currently selected primitive in the model. |
| Function SelectedIndex() as integer |
| The selected primitive based on an index. |
| Function Save() as boolean |
| Saves the model. Returns true if successful (i.e. the user did not cancel the save). |
| Function SaveAs(destination as folderitem) as boolean |
| Saves the model to a specified location on your hard disk. Returns true if successful. |
| Sub ExportEquations(destination as folderitem) |
| Exports the equations of your model to a specified location on your hard disk. |
| Sub ExportAllComponents(destination as folderitem) |
| Exports all the components in your model to a specified folder on your hard disk. |
| Function Root() as Container |
| The base container within the model. All other primitives within the model are enclosed in this container. This container is not visible in the standard Simgua user interface. |
| Function GetState() as string |
| Returns a string representing the entire state of a model. Can be used to save models to text files. |
| Sub LoadState(data as string, selectIndex as integer = -1) |
| Loads a model from a string. Also sets the currently selected primitive after the state is loaded. |
| Sub InsertUndoPoint() |
| Creates an undo point in a model window. This is used by Simgua's Undo/Redo system and allows for the user to undo your model actions. This should be called at the start of your macro if you are making any modifications to the model. |
| Function Settings() as Setting |
| The model's Settings primitive. |
| Function Item(name as string) as Primitive |
| Finds a primitive in the model based on its name. If more than one primitive in the model have the same name, only the first one is returned. It is recommended that you test the result of this function against nil to make sure the primitive was actually found. |
| Sub Move(item as Primitive, newParent as Primitive) |
| Moves the primitive item to primitive newParent. |
| Sub Delete(item as Primitive, StripReferences as boolean = true) |
| Deletes the primitive item from the model. StripReferences should almost always be set to true. If it is set to false, the primitive will have no parent but can still be referenced in other primitives. This is an unstable condition. |
| Function Count() as integer |
| The count of primitives at the root level of the model. |
| Function Item(index as integer) as Primitive |
| Returns a primitive from the root level of the model. The first primitive has an index of 0. |
| Function CreateStock(name as string) as Stock |
| Creates a new stock at the root level of the model and returns the new primitive. |
| Function CreateFlow(name as string) as Flow |
| Creates a new flow at the root level of the model and returns the new primitive. |
| Function CreateLink(name as string) as Link |
| Creates a new link at the root level of the model and returns the new primitive. |
| Function CreateParameter(name as string) as Parameter |
| Creates a new parameter at the root level of the model and returns the new primitive. |
| Function CreateDisplay(name as string) as Display |
| Creates a new display at the root level of the model and returns the new primitive. |
| Function CreateConverter(name as string) as Converter |
| Creates a new converter at the root level of the model and returns the new primitive. |
| Function CreateCodeVault(name as string) as CodeVault |
| Creates a new code vault at the root level of the model and returns the new primitive. |
| Function CreateMaterial(name as string) as Material |
| Creates a new material at the root level of the model and returns the new primitive. |
| Function CreateComponent(name as string) as Component |
| Creates a new component at the root level of the model and returns the new primitive. |
| Function CreateFolder(name as string) as Folder |
| Creates a new folder at the root level of the model and returns the new primitive. |
| Class Model |
|---|
| The Model Class represents a single Simgua model. It is like the ModelWindow Class, but no actual window is created. Use the NewModel method to generate it. |
| Function RunSilently() as Results |
| Runs the simulation of the model without displaying an analysis window. A results object containing the results of the simulation is returned. This function does not return until analysis is complete. |
| Function Item(name as string) as Primitive |
| Finds a primitive in the model based on its name. If more than one primitive in the model have the same name, only the first one is returned. It is recommended that you test the result of this function against nil to make sure the primitive was actually found. |
| Function Root() as Container |
| The base container within the model. All other primitives within the model are enclosed in this container. This container is not visible in the standard Simgua user interface. |
| Function Settings() as Setting |
| The model's Settings primitive. |
| Class AnalysisWindow |
|---|
| The AnalysisWindow Class allows you to interact with and manipulate Simgua analysis windows. |
| Function Results() as Results |
| Returns a results object containing the results from the simulation. |
| Function AnalysisMode() as integer |
| The analysis mode. A mode of 0 means to create a new window, 1 to erase the data set in the current window, and 2 to add a new data series to the current window. |
| Function ConsoleText() as string |
| The analysis window's console text. |
| Function DisplayCount() as integer |
| The number of displays shown in the analysis window. |
| Function Display(index as integer) as Display |
| The specified display from the analysis window. The first display has an index of 0. |
| Function SelectedDisplay() as Display |
| The selected display in the analysis window. |
| Function SelectedIndex() as integer |
| The index of the currently selected display. The first display has an index of 0. |
| Sub ExportExcel(destination as folderitem) |
| Exports the analysis as an Excel document to the specified folderitem. |
| Sub PrintReport(showDialogue as boolean = false) |
| Prints the report. If showDialogue is true, then a printer dialogue is shown. If it is false, no dialogue is shown and printing starts automatically. |
| Class Results |
|---|
| The Results Class allows you to access calculated values after a simulation. A result object may have multiple "frames". This will occur when the analysis mode was set to add new simulations to a currently opened results window. One frame is created for each new simulation run. The oldest frame has a value of 0 with newer frames having higher values. A frame value of -1 in function calls indicates the newest frame. |
| Function Frames() as integer |
| The total number of frames in the results object. |
| Function Periods(frame as integer = -1) as integer |
| The number of periods in the results. This is the length of the simulation divided by the time step. |
| Function Value(item as Primitive, period as integer, frame as integer = -1) as double |
| The calculated value for a primitive at a specific period. |
| Function LastValue(item as Primitive, frame as integer = -1) as double |
| The calculated value for a primitive at the end of the simulation. |
| Function Values(item as primitive, frame as integer = -1) as double() |
| The calculated values for a primitive as an array |
| Function Time(period as integer, frame as integer = -1) as double |
| The simulation time for a specific period. |
| Function Times(frame as integer =-1) as double() |
| The simulation times as an array. |
| Function ErrorCount() as integer |
| Returns the total number of errors that occurred in the last simulation run (the topmost frame). |
| Function Error(index as integer) as ModelError |
| Returns an error from the last simulation run (the topmost frame). The first error has an index of 0. |
| Sub SaveDisplayPicture(d as display, width as integer, height as integer, f as folderitem) |
| Saves a picture of a display to the specified folderitem. The type of the display must be a chart type. The file type is determined from the extension. PNG, BMP, GIF, and JPG are supported. |
| Function DisplayCSV(d as display) as string |
| Returns a CSV string representing the results of the analysis for a specific display. |
| Function Console(frame as integer=-1) as string |
| Returns the contents of the console that the model has written to using the write function. |
| Class ModelError |
|---|
| The ModelError Class reports on errors the occurred during an attempt to run a simulation. This class has the following properties: myPrimitive which is the primitive where the error occurred, myProperty which is the property where the error occurred, ErrorNumber which is the number of the error which occurred, ErrorMessage which is the description of the error which occurred, and LineNumber which is the line number of the error which occurred. |
| Class Primitive |
|---|
| The Primitive Class is the parent class of all primitive classes. It contains properties shared by all primitives. |
| Function Parent() as Container |
| The immediate container which encloses the primitive. |
| Function BackgroundColor() as color |
| The background color of the primitive. |
| Function ForegroundColor() as color |
| The foreground color of the primitive. |
| Function Name() as string |
| The primitive's name. |
| Function Shape() as string |
| Sets the shape of the primitive. Shapes include: "none", "box", "ellipse", "diamond", "triangle", "trapezium", "parallelogram", "hexagon", "octagon". "File" indicates the shape is a picture, and should be combined with the Image property. |
| Function Image() as string |
| The image used by primitive. This is a Mime64 encoded PNG. The image is only shown if the primitive's shape is set to "file". |
| Function Info() as string |
| The primitive's info string that contains an arbitrary textual description. |
| Sub Delete(newSelectionIndex as integer = -1) |
| Deletes the primitive from the model. If newSelectionIndex is non-negative that primitive is selected after the specified primitive is deleted. |
| Function Enabled() as boolean |
| Whether the primitive is enabled or not. |
| Class Setting |
|---|
| The Setting Class allows you to configure settings used when running the simulation. Each model has one settings object. |
| Function TimeUnits() as String |
| The time units of the simulation. Either: "seconds", "minutes", "hours", "days", "weeks", "months", and "years". |
| Function TimeStart() as double |
| The simulation start time in the model's base time units. |
| Function TimeStep() as double |
| The simulation time step in the model's base time units. |
| Function TimeLength() as double |
| The length of the simulation. |
| Function Order() as integer |
| The order of the simulation algorithm. Either 1, 2, or 4. |
| Function Throttle() as boolean |
| Whether or not the simulation is throttled to a certain speed. |
| Function ThrottleRate() as double |
| The rate of throttling in Throttle is true. Units are microseconds of simulation time per one second of real time. |
| Function BeforeStart() as string |
| The code for the model's Before Start macro. |
| Function OnStart() as string |
| The Visual Basic code for the model's On Start property. |
| Function OnStep() as string |
| The Visual Basic code for the model's On Step property. |
| Function OnFinish() as string |
| The Visual Basic code for the model's On Finish property. |
| Function AfterFinish() as string |
| The code for the model's After Finish macro. |
| Function DimensionCount() as integer |
| Returns the total number of dimensions that are attached to the Settings object. All model dimensions for arrays are stored in the Settings object. |
| Sub AddDimension(n as string) |
| Adds a dimension to the settings object where n is the name of the new dimension. |
| Function Dimension(index as integer) as Dimension |
| Returns a dimension object from the setting. The index of the first dimension in the setting is 0. |
| Sub RemoveDimension(index as integer) |
| Removes a dimension object from the setting. The index of the first dimension in the setting is 0. |
| Class Dimension |
|---|
| The Dimension class also you to modify the dimensions used in Simgua arrays. |
| Function Name() as string |
| The name of the dimension. |
| Function Count() as integer |
| The number of elements in the dimension. |
| Function Element(index as integer) as string |
| The name of an element in the dimension. The first element has an index of 0. |
| Sub Remove(index as integer) |
| Removes an element from the dimension. The first element has an index of 0. |
| Sub Add(n as string) |
| Adds an element to the dimension. |
| Class Container |
|---|
| The Container Class is the parent class for both the Folder and Component Classes. It contains methods shared by both Simgua Container and Component primitives. Note that for a primitive to exist, it must be defined somewhere in your model (i.e. it must be a child of a container). If a primitive is not a child of a container, then if does not exist even if you have an object referencing it in your macro. |
| Function Item(name as string, recursive as boolean = true) as Primitive |
| Locates a primitive by its name in the container. If recursive is true, subcontainers of the container are also searched for the primitive. Otherwise only the primary container is searched. It is recommended that you test the result of this function against nil to make sure the primitive was actually found. |
| Function Expanded() as boolean |
| Whether or not the container appears expanded in the library browser. |
| Function Count() as integer |
| The count of items in the container. Only includes items immediately contained by the container. Does not include children of the container's children. |
| Function Item(index as integer) as Primitive |
| The item in the container specified by index. |
| Sub Remove(index as integer) |
| Removes the item specified by index from the container. If the item is not reference elsewhere in the model, this also deletes the primitive. |
| Sub Remove(p as primitive) |
| Removes the primitive from the container. If the primitive is not reference elsewhere in the model, this also deletes the primitive. |
| Sub Insert(index as integer, p as primitive) |
| Insert the primitive into the container at the specified index. |
| Sub Move(index as integer, p as primitive) |
| Moves the primitive to a new location. First removes the primitive from its current location and then inserts it into the container at the specified index. Removing and inserting the primitive on your own is risky as the primitive could become dereferenced. |
| Sub Append(p as primitive) |
| Adds the primitive to the container. |
| Function Flatten() as Primitive() |
| Returns a list of all the primitives in the container as an array. Flatten recursively walks through the entire contents of the container. |
| Function CreateStock(name as string) as Stock |
| Creates a new stock and adds it to the container. The new primitive is returned by this method. |
| Function CreateFlow(name as string) as Flow |
| Creates a new flow and adds it to the container. The new primitive is returned by this method. |
| Function CreateLink(name as string) as Link |
| Creates a new link and adds it to the container. The new primitive is returned by this method. |
| Function CreateParameter(name as string) as Parameter |
| Creates a new parameter and adds it to the container. The new primitive is returned by this method. |
| Function CreateDisplay(name as string) as Display |
| Creates a new display and adds it to the container. The new primitive is returned by this method. |
| Function CreateConverter(name as string) as Converter |
| Creates a new converter and adds it to the container. The new primitive is returned by this method. |
| Function CreateCodeVault(name as string) as CodeVault |
| Creates a new code vault and adds it to the container. The new primitive is returned by this method. |
| Function CreateMaterial(name as string) as Material |
| Creates a new material and adds it to the container. The new primitive is returned by this method. |
| Function CreateComponent(name as string) as Component |
| Creates a new component and adds it to the container. The new primitive is returned by this method. |
| Function CreateFolder(name as string) as Folder |
| Creates a new folder and adds it to the container. The new primitive is returned by this method. |
| Class Folder |
|---|
| The Folder Class inherits from the Container Class. It represents a Simgua Folder primitive. |
| Function GroupVisually() as Boolean |
| Whether to group the folder's items in the diagram display. |
| Class Component |
|---|
| The Component class allows you to manipulate Simgua Component primitives. It inherits from the Container Class. |
| Sub Export(destination as Folderitem) |
| Exports the component to a file on your hard disk. |
| Function Variables() as string |
| The variables that the user has set to calibrate the component. |
| Function GetEncapsulated() as boolean |
| The current encapsulation state of the component. |
| Sub SetEncapsulated(encapsulated as boolean, password as string = "") |
| Set the encapsulation station of the component. If encapsulating, then an empty ("") password will mean that the component is not password-protected. When unencapsulating, password must be equal to the password used to encapsulate the component otherwise unencapsulation fails. |
| Function CalibrationPage() as string |
| The HTML of the component's calibration page. |
| Function BeforeStart() as string |
| The code of the component's BeforeStart macro. |
| Function OnStart() as string |
| The visual basic code of the component's On Start property. |
| Function OnStep() as string |
| The Visual Basic code of the component's On Step property. |
| Function OnFinish() as string |
| The Visual Basic code of the component's On Finish property. |
| Function AfterFinish() as string |
| The code of the component's After Finish macro. |
| Function ExposedCount() as integer |
| The count of exposed primitives. |
| Function ExposedItem(index as integer) as Primitive |
| The exposed item specified by index. |
| Sub AddExposedItem(p as Primitive) |
| Exposes a primitive. |
| Sub RemoveExposedItem(p as Primitive) |
| Unexposes a primitive. |
| Function ResourceCount() as integer |
| Returns the number of resources embedded within the component. |
| Function ResourceName(index as integer) as String |
| Returns the name of an embedded resource. The first resource has an index of 0. |
| Sub RemoveResource(index as integer) |
| Removes an embedded resource. The first resource has an index of 0. |
| Sub EmbedResource(resource as Folderitem) |
| Embeds a resource in the component. |
| Class Valued |
|---|
| The Valued Class is a convenience class that allows you to easily get a set a primitive's value. It inherits from the Primitive Class. Stock, Flow, Converter and Parameter Classes all inherit from it. |
| Function Value() as string |
| The value of the primitive. |
| Function MakeArray(d as dimension) as ValuedArray |
| Converts the valued primitive into an array. Returns the ValuedArray object resulting from this conversion. D is the initial dimension for the array but more may be added to the array folder. |
| Function MaximumConstraintType() as Integer |
| Whether the primitive has a maximum constraint. 0 means no constraint; 1 means "equal to"; 2 means "less than or equal to". |
| Function MaximumConstraint() as double |
| The maximum value the primitive may take on. |
| Function MinimumConstraintType() as Integer |
| Whether the primitive has a minimum constraint. 0 means no constraint; 1 means "equal to"; 2 means "greater than or equal to". |
| Function MinimumConstraint() as double |
| The minimum value of the primitive. |
| Function Units() as string |
| The primitive's units. Example: "Kilograms^1,Meters^1,Seconds^-1" means Kilograms*Meters/Seconds. |
| Function OverrideUnits() as boolean |
| Whether to force the primitive's units when they do not match. |
| Sub GetLiveChecks(byref checkNames() as string, byref checkCodes() as string) |
| Returns the primitive's live checks as two arrays containing the names of the checks and the code for the checks. |
| Sub SetLiveChecks(checkNames() as string, checkCodes() as string) |
| Sets the primitive's live checks using two arrays containing the names of the checks and the code for the checks. |
| Class ValuedArray |
|---|
| The ValuedArray Class represents Valued primitives which have been converted into Arrays. |
| Function Master() as Valued |
| Returns a reference to the original Valued primitive that was converted into the array. Changing properties of this primitive will change the properties of all the primitive's clones. |
| Function Clone(ParamArray keys as String) as Valued |
| Returns a reference to one of the clones of the master. You pass a listing of strings representing the elements in the dimensions used to specify the clone. |
| Function Count() as Integer |
| Returns the number of dimensions applied to the ValuedArray. |
| Function Dimension(index as integer) as dimension |
| Returns one of the dimensions that is applied to the ValuedArray. The first dimension has an index of 0 |
| Sub Apply(d as dimension) |
| Applies a dimension to the ValuedArray. |
| Sub Remove(index as integer) |
| Removes one of the dimensions from the ValuedArray. The first dimension has an index of 0. |
| Function UnArray() as Valued |
| Converts the ValuedArray back to a regular primitive. Removes all dimensions. Returns the original primitive object. |
| Class Parameter |
|---|
| The Parameter Class represents Simgua Parameter primitives and allows you to interact with them. |
| Function Value() as string |
| The parameter's equation. |
| Class Stock |
|---|
| The Stock Class gives you access to methods to interact with and manipulate Simgua Stock primitives. |
| Function InitialValue() as string |
| The equation used to calculate the initial value of the stock. |
| Function SerializedType() as string |
| The serialization type for the stock. Can take on one of the following values: "not" for no serialization, "volume" for volume serialization, and "delay" for PDF serialization. |
| Function Volume() as double |
| The volume of the stock used for volume serialization. |
| Function PDFType() as string |
| The PDF type used for PDF serialization. Can take on one of the following values: "Fixed Delay", "Gamma Distribution Delay", "Normal Distribution Delay", "Lognormal Distribution Delay", and "Custom PDF Delay". |
| Function FixedDelay() as double |
| The stock's fixed delay. Units are microseconds. |
| Function ExponentialRate() as double |
| The stock's scale factor for the exponential distribution. Units are in microseconds. |
| Function NormalMean() as double |
| The stock's mean for the normal distribution. Units are in microseconds. |
| Function NormalStdDev() as double |
| Returns stock's standard deviation for the normal distribution. Units are in microseconds. |
| Function LognormalMean() as double |
| The stock's mean for the lognormal distribution. Units are in microseconds. |
| Function LogNormalStdDev() as double |
| The stock's standard deviation for the lognormal distribution. Units are in microseconds. |
| Function GammaScaleFactor() as double |
| The stock's gamma distribution scale factor. Units are in microseconds. |
| Function GammaShapeFactor() as double |
| The stock's gamma distribution shape factor. |
| Function CustomPDF() as string |
| The stock's custom PDF. |
| Function CustomPDFUnits() as string |
| The units used for the stock's custom PDF. One of: "seconds", "minutes", "hours", "days", "weeks", "months", and "years". |
| Class Connection |
|---|
| The Connection Class is the parent for both the Flow and Link Classes. It contains functions to handle connecting primitives. |
| Function Alpha() as Primitive |
| The alpha of the connection. |
| Function Omega() as Primitive |
| The omega of the connection. |
| Class Flow |
|---|
| The Flow Class represents a Simgua Flow primitive. It inherits from the Connection Class. |
| Function Rate() as string |
| The flow's equation. |
| Function Per() as double |
| The flow's per value in microseconds. |
| Function TimeIndependent() as boolean |
| Whether or not the flow's rate is time independent. |
| Function OnlyPositiveFlows() as boolean |
| Whether or not only positive flows are allowed. |
| Function Transformer() as boolean |
| Whether or not the flow is a transformer flow. |
| Function Primary() as string |
| The primary flow for transformer flows. Can be either: "inflow", or "outflow". |
| Function OutflowRate() as string |
| The flow's outflow equation. |
| Class Link |
|---|
| The Link Class represents a Simgua Link primitive. It inherits from the Connection Class and has no additional methods. |
| Class Converter |
|---|
| The Converter Class represents a Simgua Converter primitive. |
| Function Input() as Variant |
| The source of the input primitive. Will either return a primitive or a string representing units of time: "seconds", "minutes", "hours", "days", "weeks", "months", and "years". |
| Function Interpolation() as integer |
| The converter's interpolation method used to fill in between specified data points. Possible values are 0 - No interpolation and 1 - Linear interpolation. |
| Function Type() as integer |
| The converter's type. Possible values are 0 - Discrete and 1 - Continuous. |
| Function Tolerance() as double |
| The tolerance percentage for extending discrete converters. |
| Function Count() as integer |
| The number of input - output pairs in the source. |
| Sub Add(InputVal as double = 0, outputVal as double = 0) |
| Add a new input-output pair. |
| Sub Remove(index as integer) |
| Removes the specified input-output pair. The first pair has an index of 0. |
| Function InputVal(index as integer) as double |
| The specified input value. |
| Function OutputVal(index as integer) as double |
| The specified output value. |
| Sub LoadCSV(data as string) |
| Loads Converter primitive data from a CSV string. |
| Class CodeVault |
|---|
| The CodeVault Class allows you to interact with Simgua Code Vault primitives. |
| Function Code() as string |
| The Code Vault's code. |
| Class Material |
|---|
| The Material Class allows you to interact with Simgua Material primitives. |
| Sub SetUnitConversion(targetUnits as string, scalingFactor as double) |
| Sets the scaling factor used to convert the material's units to other units. The form for targetUnits has the following pattern: "Meters^2,Kilograms^1,Seconds^-1" for "(Meters^2*Kilograms)/Seconds". |
| Sub GetUnitConversion(byref targetUnits as string, byref scalingFactor as double) |
| Gets the scaling factor used to convert the material's units to other units. The form for targetUnits has the following pattern: "Meters^2,Kilograms^1,Seconds^-1" for "(Meters^2*Kilograms)/Seconds". |
| Function GetCall() as string |
| The code for the primitive's GetCall property. |
| Function OnStep() as string |
| The code for the primitive's OnStep property. |
| Sub AddSubMaterial(name as string, combinationMethod as string, index as integer = -1) |
| Adds a submaterial to the material. CombinationMethod can either be "average" or "summation". Non-negative indexes will insert the submaterial into the material at certain location, otherwise they are appended as the last submaterial. |
| Function SubMaterialCount() as integer |
| The total number of submaterials. |
| Sub RemoveSubMaterial(name as string) |
| Removes a submaterial from the material. |
| Sub RemoveSubMaterial(index as integer) |
| Removes a submaterial from the material. The first submaterial has an index of 0. |
| Class Display |
|---|
| The Display Class allows you to interact with Simgua Display primitives. |
| Function AutoAddPrimitives() as boolean |
| Whether or not primitives are automatically added to the display as they are created. |
| Function TimeUnits() as string |
| The time units for the display. TimeUnits can be: "seconds", "minutes", "hours", "days", "weeks", "months", or "years". |
| Function Type() as string |
| The type of the display. Type can be "Tabular", "Steady State", "Scatterplot", or "Time Series". |
| Function Count() as integer |
| The number of primitives shown in the display. |
| Function Item(index as integer) as Primitive |
| The specified primitive that is shown in the display. The first primitive in the display has an index of 0. |
| Sub Add(p as primitive) |
| Adds the specified primitive to the display. |
| Sub Remove(p as primitive) |
| Removes the specified primitive the display. |
| Function Title() as string |
| The title of the display's chart. |
| Function XAxisLabel() as string |
| The label of the chart's x-axis. |
| Function YAxisLabel() as string |
| The label of the chart's y-axis. |
| Function YAxis2Label() as string |
| The label of the chart's secondary y-axis. |
| Function LegendPosition() as string |
| The position of the chart's legend. Can take on one of the following values: "do not show", "upper left", "upper right", "lower right", "lower left", "top", or "bottom". |
| Function WhiteonBlack() as boolean |
| Whether or not the chart is displayed as white on black instead of black on white. |
| Function Chart3D() as boolean |
| Whether or not the chart is displayed with 3D styling. |
| Function VerticalGridlines() as boolean |
| Whether or not vertical gridlines are displayed on the chart. |
| Function HorizontalGridlines() as boolean |
| Whether or not horizontal gridlines are displayed on the chart. |
| Function LogYAxis() as boolean |
| Whether or not the y-axis is displayed with a logarithmic scale. |
| Function LogYAxis2() as boolean |
| Whether or not the secondary y-axis is displayed with a logarithmic scale. |
| Function LogXAxis() as boolean |
| Whether or not the x-axis is displayed with a logarithmic scale. |
| Sub GetCustomAxes(byref useXMax as boolean, byref XMax as double, byref useXMin as boolean, byref XMin as double, byref useYMax as boolean, byref YMax as double, byref useYMin as boolean, byref YMin as double, byref useY2Max as boolean, byref Y2Max as double, byref useY2Min as boolean, byref Y2Min as double) |
| Returns the status of the custom axis boundaries for a chart. |
| Function Series(index as integer) as SeriesStyle |
| The SeriesStyle for a primitive specified by its index. The first primitive has an index of 0. |
| Function Series(p as primitive) as SeriesStyle |
| Returns a SeriesStyle for a primitive. |
| Class SeriesStyle |
|---|
| The SeriesStyle Class allows you to configure the properties for a specific data series in a Simgua chart. |
| Function Coloring() as color |
| The color of the series. |
| Function UseYAxis2() as boolean |
| Whether the series should use the secondary y-axis. |
| Function Smoothed() as boolean |
| If true, the series's line is smoothed. This may create artifacts if there are extreme changes in line slope. |
| Function ShowTrendEquation() as boolean |
| Whether to show the trendline equation. |
| Function ShowConfidenceBand() as boolean |
| Whether to show the confidence band for the trendline. |
| Function ConfidenceBand() as double |
| The size of the confidence band. Confidence ranges from 0 to 1, not-inclusive, and is a probability. |
| Function LineSize() as double |
| The line width of the series. |
| Function LineStyle() as string |
| The styling of the series's line. Can be one of the following: "solid", "dotted", "dashed", "dotted dashed", or "alternative dashed". |
| Function PointSize() as double |
| The point size for data points in the series. |
| Function PointStyle() as integer |
| The style of data points for the series. PointStyle take one of the following values: 1 (square), 2 (diamond), 3 (triangle), 4 (right facing triangle), 5 (left facing triangle), 6 (upside down triangle), or 7 (circle). |
| Function TrendlineType() as string |
| The type of the series trendline. TrendlineType can take on one of the following values: "No Trendline", "Linear Trendline", "Logarithmic Trendline", "Exponential Trendline", "2nd Order Polynomial", "3rd Order Polynomial", "4th Order Polynomial", or "5th Order Polynomial". |
| Class Folderitem |
|---|
| The Folderitem Class allows you to interact with your computer's file system. You can create, delete and edit file using this class. |
| Sub Constructor() |
| Constructs a folderitem pointing to the macro file. |
| Sub Constructor(path as string, type as string = "shell") |
| Constructs a folderitem pointing to path. Type represents the type of path you passed to the method and can either be "shell" path or an "absolute" path. The path is generally platform dependent. |
| Function AbsolutePath() as string |
| Returns the absolute path of the folderitem. |
| Function ShellPath() as String |
| Returns the shell path to the folderitem. |
| Function Child(name as string) as FolderItem |
| Returns a child folderitem of a directory. |
| Function Count() as integer |
| Returns the count of folderitems in a directory. |
| Function Item(index as integer) as FolderItem |
| Returns the specified item from a directory. The first item has an index of 0. |
| Function Parent() as FolderItem |
| Returns the parent directory of a folderitem. |
| Function Exists() as boolean |
| Returns whether the folderitem exists or not. |
| Sub Delete() |
| Deletes a folderitem. |
| Function Directory() as boolean |
| Returns whether the folderitem is a directory. |
| Sub CreateasDirectory() |
| Creates a folderitem as a directory. |
| Function Read() as string |
| Open a folderitem and reads its contents as a string. |
| Function Write(text as string) as boolean |
| Writes a string to a text file. Returns true if successful. If the file does not exist, it will be created. If the file does exist, it will be replaced. |
| Function Name() as string |
| The name of the folderitem. |
| Class Dictionary |
|---|
| The Dictionary Class provides a table of key-value pairs used to store data in any easy to access method. Dictionaries are also known as associative arrays or hash tables. A Dictionary can store anything that can be converted to and from a String. It can also be used to store primitives. |
| Function Value(key as Variant, default as Variant = "[SMGNIL]") as Variant |
| The value associated with a specific key. If the key is not found then default is returned. |