Welcome to the Engineering Video Series.
This tutorial introduces how to develop add-in functions for any type of analyses in the GeoStudio product suite.
This tutorial is based on materials provided in the GeoStudio Add-In Developer's Kit on the GEO-SLOPE website.
Let's get started by reviewing a few terms related to the development of computer programs.
In computer programming, a field is a variable.
A method is a set of operations that fulfill a particular objective.
A parameter, also referred to as an argument, is a value passed between methods.
The method passing the value is referred to as the calling method.
A class is a declaration of what a specific instance of the class can do.
A class has both properties and behaviors, which are defined by the included fields and methods.
An individual instance of a class is called an object.
An example of an object is a boundary condition applied to a specific node at a specific time.
Now that we have reviewed these general terms, let's consider what in an add-in function is.
In general, an add-in function is a user defined relationship.
This relationship may follow the form: y=F(x) where the value of 'y' is determined based on
the value of 'x' given the add-in function 'F'.
An add-in function can be used in place of an internal GeoStudio function.
Internal GeoStudio functions include material property functions and boundary condition functions.
Add-ins are incorporated into any GeoStudio analysis as a supplemental function run by the solver.
The purpose of using an add-in function in GeoStudio is to specify an alternative to
boundary condition functions or material properties functions.
Boundary condition add-in functions are applied to geometry items such as points or lines.
An example of an add-in function that could be developed for a boundary condition is a function
specifying the total head in a reservoir that changes with time over the simulated period.
Material properties functions are applied to regions.
An alternative material function could be implemented with an add-in function
if the simulated soil exhibits changing strength over time or distance.
An add-in function can also replace the existing constitutive models for stress-strain relationships in SIGMA/W.
For example, if the Elastic-Plastic and Modified Cam Clay methods do not fit the simulated scenario.
This is an example of a more sophisticated add-in function.
The add-in is called by a method within the GeoStudio solver.
First, the GeoStudio solver automatically passes the 'x' value to the add-in.
This is the parameter or argument being passed into the method.
The add-in may also request more data from the solver above its current context, such as the current elevation being solved for.
With this information, the add-in function determines 'y' and returns it to the solver.
Note, that the data type of the 'x' and 'y' variables depends on the GeoStudio function the add-in is replacing.
An add-in function follows the general format illustrated on the right. The key elements of an add-in are:
The name of the add-in or the declaration of a class.
The method or function of the add-in, which must be called 'calculate' and is the portion of the code that determines the value of 'y' based on the inputs.
And a return command, which can be used to send the 'y' variable back to the GeoStudio solver.
Both the class and the calculation method must be 'public' in order for the GeoStudio solver to see them when scanning an add-in.
When a variable name or field is declared as 'public', this field will appear in the GeoStudio Define View under KeyIn Functions.
An add-in function can be created in two general ways.
First of all, the add-in code can be written in a text editor, like Notepad.
This method is better for simple add-in functions where it is not difficult to find errors and debug the code.
The second method of creating add-in code is in an integrated development environment, like Microsoft Visual Studio.
This method is better for complex add-in functions where there are many steps or functions in the same code file.
Add-ins can be written in any Common Language Runtime coding language, like F#, C#, and C++.
The generated code must be converted to the appropriate format in order to be called by GeoStudio.
A computer language compiler is used for the conversion.
A compiler is a computer program that transforms source code written in the source language
into another computer language called the target language.
All Windows-based computers include a compiler installed with Microsoft's .NET runtime.
This means that no additional program is required to compile an add-in file.
Compiled code containing an add-in function is called an 'assembly'.
The assembly is stored in a 'dynamic link library' file, which is in the machine language.
We will now review how to create an add-in function in Notepad and compile the code into the correct format.
Here is a simple add-in written in Notepad. The purpose of this function is to generate a sine curve
which could be used as a boundary condition in many of the GeoStudio products.
As you can see here, the name of the add-in is 'SineCurve'.
Below this is a list of variables that have been declared as 'public'.
All public variables can be seen as fields in the GeoStudio analysis when this add-in is selected.
This means that the values for the initial amplitude, maximum amplitude, and wavelength
used in the sine function, can all be specified in the GeoStudio analysis.
Below the public variables, is the 'Calculate' method called by the GeoStudio solver.
First, the variable that will be returned to the solver is declared.
For simplicity, this variable was called 'y'.
Any other variables that will be used to calculate the value of 'y' may also be declared here.
Note, that these variables do not include the word 'public' and therefore, will not be visible in the GeoStudio analysis.
The value of 'y' is then calculated given the value of 'x' and the specified variables.
The resulting 'y' value is returned to the solver.
As you can see, some basic knowledge of code development is required for building add-ins.
However, there are many example add-in functions provided in the Add-In Software Development Kit on the GEO-SLOPE website.
We will save the add-in as a code script file by going to 'Save As' and adding the '.cs' extension to the end of the file name.
We are now ready to compile the code.
The Add-In Developers Kit on the GEO-SLOPE website includes a simple program that runs a C# compiler.
I have already downloaded the Developer's Kit from the website.
The program is called 'gsaddin' and contains the appropriate settings for creating an add-in assembly file from a code script file.
I will copy and paste this program into the folder containing my SineCurve code script file.
When I open the 'gsaddin' program, I see the location where the compiled file will be saved at the top of the command window.
Below this is the prompt 'AddIn Name'.
When I type 'SineCurve' and hit Enter, the code script SineCurve file will be compiled into a dynamic link library file.
When I hit Enter again, the command window disappears and I can see that the newly compiled
SineCurve code with the extension '.dll', for dynamic link library, has appeared in my add-in functions folder.
Note, that the code script file you wish to compile must be saved in the same location as the compiler program 'gsaddin'.
I will now demonstrate how to access an add-in function from a GeoStudio analysis.
Here we have a TEMP/W analysis that has been developed to evaluate the depth of frost
penetration due to changes in surface temperature around a newly installed culvert.
I will first go to Edit > Options in order to make sure that the GeoStudio analysis is retrieving add-in functions from the desired location.
The add-in folder shown here is where I saved the SineCurve file, so I do not need to change this location. However, if the SineCurve file was
saved in a different location, I can click on Browse to find the folder containing my add-in functions.
I will be using the SineCurve function to specify the boundary condition at the ground surface.
In order to do so, I will go to KeyIn > Boundary Conditions.
A ground surface boundary condition was previously established with a constant temperature of 0° C.
I will now change this boundary condition so that it is a function.
I will click on the '…' symbol to open the KeyIn Thermal Boundary Functions window.
I will click on 'Add' and select 'New' to create a new boundary condition function.
I will name the boundary condition function 'Sinusoidal Ground Temperature'.
I will then select 'Add-In Function' from the list of function types.
A 'Select' button appears, allowing me to choose the add-in I wish to use for the boundary condition function.
The SineCurve add-in is listed in the browser window.
I will select it and press 'OK'.
As soon as the SineCurve add-in is selected, three fields appear at the bottom of the window.
These are the three fields that were declared 'public' in the SineCurve code.
I can now specify values for each of these fields.
After entering values for each field, the sinusoidal temperature trend that will be applied
to the ground surface is illustrated in the graph window.
I will now close the Thermal Boundary Functions window and will make sure that the
'Sinusoidal Ground Temperature' function is selected for the boundary function.
As you can see, this boundary condition has already been applied to the top of the modelled domain.
We are now ready to solve the analysis.
Once the analysis has finished solving, I can check that the sinusoidal temperatures were applied to the ground surface by going to
Draw > Graph. I've already created a plot of temperature over time at the ground surface nodes.
As you can see, the simulated temperatures follow the boundary condition function that was created using the SineCurve add-in function.
In summary, add-in functions can replace internal GeoStudio functions allowing for greater flexibility for specifying material behavior and boundary
conditions, particularly when the material or boundary condition varies dynamically with the analysis state.
Add-in functions can range in complexity from very simple to highly involved functions.
Add-ins can be written in any CLR language. The code is then compiled into the machine language
so it can be called by the GeoStudio solver.
The developed add-in functions are accessible from any Geo-Studio analysis when they are
placed in the specified directory as demonstrated in this video.
We have now reached the end of this tutorial. Note, that not all the powerful capabilities of add-in functions have been discussed here.
Please see the Add-In Software Development Kit available on the GEO-SLOPE website for more information.
Thank you for watching.