GeoStudio

Add-In Upgrade Guide

 Copyright © 2007, 2008, 2009, 2012, 2017 by GEO-SLOPE International, Ltd.
All rights reserved. No part of this work may be reproduced or transmitted in any form or by any
means, electronic or mechanical, including photocopying, recording, or by any information
storage or retrieval system, without the prior written permission of GEO-SLOPE International,
Ltd.
Printed in Canada.

GEO-SLOPE International Ltd

1200, 700 6th Ave SW
Calgary, Alberta, Canada T2P 0T8
E-mail: [email protected]
Web: http://www.geo-slope.com

2
 Table of Contents
1 Overview..................................................................4

2 Upgrading Add-Ins for GeoStudio 2018...................4

2.1 Add-In compiled for “Any CPU”....................................................4
2.2 Changing the Referenced Assembly............................................4
2.3 Updating Add-in Code for the New API........................................4
2.3.1 Gsi.DeepContext and Gsi.ShallowContext ................5
2.3.2 More context types in the finite element mesh ..........5
2.3.3 ID replaced by Gsi.ResultContext.ID .........................6
2.3.4 Units of input time is in Seconds................................6
2.3.5 Add-In Calculate method invocation ..........................6
2.4 Changed DataParamType Names ...............................................7
2.4.1 Gsi.DataParamType Cross-Reference ......................7

3
1 Overview
GeoStudio 2018 represents a major release of the GeoStudio Finite Element solver, with a
number of changes that will affect existing Add-Ins built for GeoStudio versions prior to
GeoStudio 2018. Existing Add-Ins will not work as is and will require upgrading due to changes
to the Add-In APIs and how Add-In code is compiled.
This document provides Add-In developers with an overview of what has changed, and
instructions to upgrade them for GeoStudio 2018.

2 Upgrading Add-Ins for GeoStudio 2018

2.1 Add-In compiled for “Any CPU”

Previous versions of GeoStudio solvers were compiled in 32-bit only, which meant Add-Ins also
had to be compiled in 32-bit in order for them to be run in compatible execution environment.
GeoStudio 2018 now supports 32-bit and 64-bit solvers, and will automatically run in 64-bit on
64-bit Windows OS. In order to avoid compiling 2 versions of Add-Ins to support separate 32 and
64 bit environments, AddIn code must now be compiled for AnyCPU and the same compiled
Add-In will work in both 32 and 64 bit environment.

2.2 Changing the Referenced Assembly

In GeoStudio 2018, the add-in assembly (previously named MNGSRV.DLL) has been renamed
to Gsi.MngSrv.dll to signify that old add-ins are not compatible with the new API. Add-ins with
references to the old assembly will no longer work. Add-ins that were written prior to GeoStudio
2018 must be rebuilt against the new assembly and have their former references to
MNGSRV.DLL removed.
To do this from Visual Studio, open your add-in project and navigate to the Solution Explorer.
Expand your project node and the References node below it. If your project had referenced the
old assembly it will be visible in the list as MNGSRV. To remove it, right click over the
assembly’s node to bring up the context menu and select “Remove”. If the assembly does not
appear in this list then the project never referenced it and it does not need to be removed. Nor
should it be necessary to add a reference to the new assembly in this case.
If the old assembly was removed then your add-in will likely require the new one to function. To
add it, right click over the References node under your project to bring up the context menu and
select “Add Reference…” to open a dialog. In the “Add Reference” dialog choose “Browse” in
the left pane. This will display recently referenced assemblies. At the bottom left press the
“Browse” button. This opens the file selection dialog. From there navigate to the install directory
of GeoStudio. This is usually “C:\Program Files\GEO-SLOPE\GeoStudio 9\Bin” or “C:\Program
Files (x86)\GEO-SLOPE\GeoStudio 9\Bin” depending on your installation. From that directory
select Gsi.MngSrv.dll and press the “Add” button. It should then appear in your project’s list of
references.

4
2.3 Updating Add-in Code for the New API
Several API changes have occurred in GeoStudio 2018 which will break old add-ins. To compile
them against the new assembly successfully, you may be required to make several changes.

2.3.1 Gsi.DeepContext and Gsi.ShallowContext

If you had a class which inherited from Gsi.Function then you will need to replace it with either
Gsi.DeepContext or Gsi.ShallowContext. The former class no longer exists. Choosing between
deep or shallow function contexts will depend on the requirements of your add-in. A shallow
context is more efficient if it is suitable to your situation but will not always be appropriate. A
deep context is functionally equivalent to the former class but may consume more resources than
required for its purpose.
You may simply rename all Gsi.Function to Gsi.DeepContext to start with to get your existing
Add-Ins working.
See the GeoStudio Add-Ins Programming Guide and Reference for a more detailed explanation.

2.3.2 More context types in the finite element mesh

Prior to GeoStudio 2018, an Add-In object would only run in a single context of either Node,
Gauss Point or Slice. In other words, when you write your Add-In logic you always know by
default what context it is running in, e.g., a Seep “VolWC versus MatricSuction” Add-In would
always run at Gauss Point context.
The new GeoStudio 2018 Finite Element solver introduces additional Element and Element Node
contexts, such that an Add-In object may now run in different contexts at different times. For
example, a material hydraulic conductivity function Add-In may be called at a Gauss Point, at an
Element or at an Element Node.
Existing Add-Ins will compile and run without adding the new Gsi.ResultContext API to your
code, but be aware that it may behave differently. For example, if an Add-In is intended to run at
a Gauss Point, then the Add-In should be restricted to Gauss Point context using the
Gsi.ResultContext.Type API as shown below.
You may write an Add-In with separate logic that runs in separate contexts and that is perfectly
fine, as long as the code is restricted to run in their respective and intended context.

// Example of a function object that reads the elevation

// of the current node/gauss point/slice, and outputs the
// product of elevation and pressure.

public class TestDataParamFunction : Gsi.DeepContext

{
public double Calculate(double pressure)
{
double contextId = 0.0;
double elevation = 0.0;
// This addin may be called at a node, gauss point,
// element or element node context
try
{
switch (Gsi.ResultContext.Type())

5
 {
Comment [AP]: I added this to the
case Gsi.ResultType.Nodes:
sample code as Ron Coutts had some
case Gsi.ResultType.Gauss:
initial problems with understanding that
case Gsi.ResultType.Elements:
the Add-In may be called from the UI (on-
case Gsi.ResultType.ElementNodes:
demand) without a result context which
contextId = Gsi.ResultContext.ID();
throws an exception
elevation = GetParam(Gsi.DataParamType.eElevation);
break; Comment [AP]: Ron had problems
understanding why the Add-In was being
default: called more than once within a timestep,
// Catch cases of unexpected context and it was due to the integration.
break;
}
}
catch
{
// Catch cases of invalid GetParam or
// missing Result Context Type (Add-In is called
// from UI when painting boundary conditions)
// Return a max double value to indicate the problem
return Double.MaxValue;
}
return elevation * pressure;
}
}

2.3.3 ID replaced by Gsi.ResultContext.ID

The existing ID property has been replaced by the new Gsi.ResultContext.ID to group the context
ID with the context type. It retains its meaning and represents the node number, gauss point
number, element number, element node number or slice number, depending on the associated
context.
Any Add-In using the ID property must be renamed to use Gsi.ResultContext.ID.

2.3.4 Units of input time is in Seconds

Prior to GeoStudio 2018, an Add-In with input time (for example, PWP vs Time) was always
specifed in user selectable Engineering Units for time in the “Set Units and Scale” dialog.
With the introduction of user selectable Display Units in GeoStudio 2018 which is separate from
the consistent internal Engineering Units used in the solvers, Add-In input time parameter is now
always specified in Engineering Units of seconds.
Any Add-In with logic that uses input time must be updated to always handle input time units in
seconds.

2.3.5 Add-In Calculate method invocation

An Add-In that returns a rate based value (for example a ‘q’ or ‘Q’ boundary condition) between
the previous and current time steps may be called more than once within the time step, as it is
necessary to integrate the rate based value to obtain the mass or energy that is to be added to the
domain over the time step.
This behaviour should be taken into consideration when writing Add-In Calculate methods.

6
 1. If the Add-In simply returns an instantaneous value based on the input time, say the Comment [AP]: I deleted this section as
Water Rate at time x, then it is a straightforward calculation that can be invoked for any we now support custom parameters
input time value.
2. If the Add-In has additional functionality, for example accumulating the Water Mass at
each time step, then it will be necessary to enclose the accumulation logic in conditional
code to make sure it is only called at the time step (and not at the various integration
points between previous and current time step)
Note that even though an Add-In may be called multiple times within a time step for integration
purposes, the overall time spent invoking the Add-In is still a small fraction of the total solve
time.

2.4 Changed DataParamType Names

There are a number of data parameter types that have been added, removed, or renamed in
GeoStudio 2018. Those used by your add-in will need to be changed for it to compile and run
successfully against the new assembly. These names all exist under the Gsi.DataParamType
namespace and have an “e” prefix. Below is a cross-reference table of the data parameters that
have been renamed. Parameters that were removed have no equivalent in GeoStudio 2018 and are
not listed below. Parameters that have not been renamed also do not appear in this list.

2.4.1 Gsi.DataParamType Cross-Reference

Version 8 Version 9

eTotalHead eWaterTotalHead

ePressureHead eWaterPressureHead

eXGradient eWaterGradientX

eYGradient eWaterGradientY

eXYGradient eWaterGradient

eXConductivity eWaterConductivityX

eYConductivity eWaterConductivityY

ePWP eWaterPressure

eXThermalUnitFlux eHeatFluxX

7
eYThermalUnitFlux eHeatFluxY

eXYThermalUnitFlux eHeatFlux

eXLiqVel eWaterFluxX

eYLiqVel eWaterFluxY

eXYLiqVel eWaterFlux

eXVapVel eVapourFluxX

eYVapVel eVapourFluxY

eXYVapVel eVapourFlux

eAirHead eAirTotalHead

eAirFlux eAirMassRate

eAirCumFlux eAirCumulativeMass

eAirXVelocity eAirFluxX

eAirYVelocity eAirFluxY

eAirXYVelocity eAirFlux

eAirXGradient eAirGradientX

eAirYGradient eAirGradientY

eAirXYGradient eAirGradient

eAirXConductivity eAirConductivityX

eAirYConductivity eAirConductivityY

eAirContent eAirConductivity

8
eWaterFlux eWaterRate

eWaterCumFlux eWaterCumulativeVolume

eThermalFlux eHeatRate

eThermalCumFlux eHeatCumulativeTransfer

eGasFlux eGasRate

eMassFlux eSoluteMassRate

eMassCumFlux eSoluteCumulativeMass

eXThermalGradient eThermalGradientX

eYThermalGradient eThermalGradientY

eXYThermalGradient eThermalGradient

e1DGaussID eBeamGaussNum

eWaterUnitFlux eWaterFlux

eMassUnitFlux eSoluteMassFlux

eSourceConcentration eConcentration

eRootDepth eRootDepthMagnitude

eGasUnitFlux eGasFlux

eAirCumVolFlux eAirCumulativeVolume

eAirVolFlux eAirRate

eElementNumFromGauss2D eParentElementId

eLocalRgnFromGauss2D eRelativeId

9
eXFinalConductivity eWaterPrevIterConductivityX

eAirUnitFlux eAirFlux

eAirIterations eAirIterationCount

eHeatIterations eHeatIterationCount

eWaterIterations eWaterIterationCount

eLambdaWaterCoupledAir eWaterCoupledAirLambda

eLambdaWaterCoupledHeat eWaterCoupledHeatLambda

eLambdaAirCoupledHeat eAirCoupledHeatLambda

eLambdaAirCoupledWater eAirCoupledWaterLambda

eStoredHeadForcing eHeatStoredForcing

eStoredWaterForcing eWaterStoredForcing

eStoredAirForcing eAirStoredForcing

eStoredSoluteForcing eSoluteStoredForcing

eSoluteIterations eSoluteIterationCount

eGasIterations eGasIterationCount

eStoredGasForcing eGasStoredForcing

eDissolvedGasConcentration eGasDissolvedConcentration

eDissolvedGasXXDispersionCoef eGasDissolvedXXDispersiveCoef

eDissolvedGasYYDispersionCoef eGasDissolvedYYDispersiveCoef

eDissolvedGasXYDispersionCoef eGasDissolvedXYDispersionCoef

10
eDissolvedGasPeclet eGasDissolvedPeclet

eDissolvedGasCourant eGasDissolvedCourant

eDissolvedGasPecletX eGasDissolvedPecletX

eDissolvedGasPecletY eGasDissolvedPecletY

eDissolvedGasCourantX eGasDissolvedCourantX

eDissolvedGasCourantY eGasDissolveCourantY

eDissolvedGasDiffCoeff eGasDissolvedDiffusionCoefficient

11