MMMM AAAA RRRR IIII NNNN P.O. Box 28

6700 AA Wageningen The Netherlands

T +31 317 49 39 11 F +31 317 49 32 45

E info@marin.nl I www.marin.nl

External Fortran DLL

An aNySIM user interface extension.

User Manual

J.Wikkerink

September 2010

User Manual 1

CONTENTS Page

1 SUMMARY ............................................................................................................... 2

2 How does it work? .................................................................................................... 3

2.1 In short ................................................................................................................. 3

2.2 In more detail ....................................................................................................... 3

3 The interface ............................................................................................................. 4

4 External Fortran DLL for Marin users ....................................................................... 5

5 ExtFortranDLL module. ............................................................................................ 6

6 Building aNySIM with an external fortran DLL. ........................................................ 6

7 Example application ................................................................................................. 7

7.1 Description ........................................................................................................... 7

7.2 Running the example ........................................................................................... 8

User Manual 2

1 SUMMARY

aNySIMs user interface has been extended with an external Fortran DLL. The

functionality of the DLL can be defined by the user. This allows the user to add a force

module to aNySIM.

User Manual 3

2 HOW DOES IT WORK?

2.1 In short

the user interface functionality of aNySIM is used to communicate with the DLL through

a fixed functional interface. The DLL can be defined and compiled by the user as long as

the functional interface is kept intact.

2.2 In more detail DLL stands for ‘Dynamic Link Libraries’. The programs that call this file are connected to

it at run time, a process referred to simply as run-time dynamic linking. Unlike

conventional non-shared, static libraries. Static libraries are simply added to the calling

program when its executable is built at the linking phase.

The aNySIM user interface communicates with the external DLL called

ExtFortranDLL.dll. Via the ini file must be specified whether the DLL should be called at

the communication intervals or at the integration intervals. With respect to program

execution, this interface has three stages: init-, run- and close stage. For every stage a

interface has been defined by which the DLL is called.

The DLL is an indispensable component for aNySIM. The DLL supplied with the

installation is a dummy one: no functionality is defined by this DLL.

User Manual 4

3 THE INTERFACE

The signature for the init-stage interface function is:

subroutine FDLL_init(NBody, error)

integer, intent(in) :: NBody

integer, intent(out) :: error

This stage is suitable for reading the ini-file and initializing data structures. NBody

indicates the number of bodies participating in the simulation. Any error value other

than 0 returned to aNySIM will lead to program termination.

The signature for the run-stage interface functions are:

subroutine FDLL_updateState(bodyIndex, time, sfMotion, sfVeloc, sfAccel, efPosition,

lifMot, lifVel)

integer, intent(in) :: bodyIndex

real, intent(in) :: time

real, dimension(6), intent(in) :: sfMotion

real, dimension(6), intent(in) :: sfVeloc

real, dimension(6), intent(in) :: sfAccel

real, dimension(6), intent(in) :: efPosition

real, dimension(6), intent(in) :: lifMot

real, dimension(6), intent(in) :: lifVel

subroutine FDLL_calcForce()

subroutine FDLL_getForce(bodyIndex, force)

integer, intent(in) :: bodyIndex

real, dimension(6), intent(out) :: force

Every HCOM time step, FDLL_updateState is called by aNySIM. For every body, time

and state are provided. The state parameters supplied are: ship fixed motion, velocity

and acceleration, earth fixed position, and motion and velocity in the Lifsim or ship fixed

t0 system of coordinates. After providing state information, aNySIM calls

FDLL_calcForce. In calcForce, ExtFortranDLL has to calculated the force applied to

every body due to the ExtFortranDLL extension. FDLL_getForce must be used to

retrieve the calculated force.

The signature for the close-stage interface function is:

subroutine FDLL_close()

This final stage is suitable for writing of reports, closing files and freeing memory.

User Manual 5

4 EXTERNAL FORTRAN DLL FOR MARIN USERS

(The contents of this paragraph is applicable for internal Marin users only and is

applicable for aNySIM 10.1.0 only).

The aNySIM user interface which communicates at the HCOM time intervals is used to

communicate with the external DLL call ExtFortranDLL.dll. With respect to program

execution, this interface has three stages: init-, run- and close stage. The matching user

interface files ara Init_FextCom.f90, Run_FextCom.f90 en Close_FextCom.f90. For

every stage a interface has been defined by which the DLL is called from the matching

user interface procedure.

Marin users who want to use the External Fortran DLL must build their own aNySIM

executable on the Remote PC. The ‘buildaNySIM’ (or buildaNySIMPro) script on the

Remote PC can be used for compiling Init_FextCom.f90, Run_FextCom.f90 and

Close_FextCom.f90. This script will be used for preparing aNySIM for the

ExtFortranDLL.dll too

.

In order to have the buildaNySIM script perform its task for this particular application, the

following statements must be added to the .ini file:

[USERINTERFACE]

CommunicationInitSource = Init_FExtcom.f90

CommunicationRunSource = Run_FExtcom.f90

CommunicationCloseSource = Close_FExtcom.f90

LibrarySource = ExtFortranDLL.lib

ModuleSource = ExtFortranDLL.f90

As library source a .lib file is mentioned, instead of a .dll file. The .lib file, which is

generated by the Fortran compiler along with the .dll file, contains the interface

information required during the linking phase.

The folder ‘C:\Marin\aNySIM\build_dll’ contains the required files.

User Manual 6

5 EXTFORTRANDLL MODULE.

The functions implementing the interface in ExtFortranDLL.dll are part of the Fortran

module ExtFortranDLL. A module is the most suitable way of implementing a force

module in an external DLL. Data read from the ini-file in the init stage can be stored in

global variables with module scoop. During the run-stage that data is available easily

without passing via procedure parameters.

6 BUILDING ANYSIM WITH AN EXTERNAL FORTRAN DLL. The ‘BuildExtFortranDLL.bat’ script can be used to build the DLL. It requires

‘ExtFortranDLL.f90’ and ‘ExtFortranDLL.vfproj’ as input files. The script requires

Microsoft Visual Studio 2008 Professional Edition. Output files, among which

‘ExtFortranDLL.dll’ and ‘ExtFortranDLL.lib’, are placed in directory ‘Release’.

‘ExtFortranDLL.vfproj’ can also be opened with Visual Studio 2008 Professional Edition.

This opens the project and enables the DLL development and building.

Benefit of users who do not have Visual Studio Professional Edition available, there is a

build script for the free Visual Studio 2008 C++ Express Edition available. Note: there

may be restrictions for use, see www.microsoft.com for details. It’s called

‘BuildExtFortranDLLVSExpress.bat’ and requires ‘ExtFortranDLL.f90’ as input. Output

files, among which ‘ExtFortranDLL.dll’ and ‘ExtFortranDLL.lib’, are placed in the

directory of the ‘BuildExtFortranDLLVSExpress.bat’ and ‘ExtFortranDLL.f90’ file.

For a new DLL to develop and build, the files in the ‘build_dll\Files’ directory must be

copied to a chosen development directory. The file ‘ExtFortranDLL.f90’ is the Fortran file

by which de DLL functionality is defined. The file constains an example application (see

next chapter) between the ‘__EXAMPLE__’ pre-processor symbols. The statements not

between the pre-processor symbols are the DLL interface to aNySIM.

After a new DLL has been built, it must be copied to the bin directory to replace the

dummy DLL. Before replacing the dummy DLL, make a backup of it for future use.

Both build scripts require Visual Studio and Intel Fortran DLLs too. These DLLs are

retrieved from the Visual Studio and Intel Fortran installation directories (no user action

is required) and should not be present in the directory in which the build script resides.

Note: This excludes mml.dll, which is an essential part of aNySIM.

In order to build ‘ExtFortranDLL.dll’ with the scripts and ‘.vfproj’ provided, Microsoft

Visual Studio must be installed before the Intel Fortran compiler.

User Manual 7

7 EXAMPLE APPLICATION

7.1 Description

An example application has been build with a matching ini file. It can be found in the

‘ExtFortranDLL’ directory, a subdirectory of the ‘examples’ directory. It’s based on the

LiftCase example, which resides in the ‘LiftCase’ directory, also a subdirectory of

‘examples’

In the ini file a four body setup is defined. Body two and three are loads, body one an

four are floaters. Both floater body positions are fixed with a linear spring. In the LiftCase

example, the linear spring is calculated by the regular aNySIM spring function. In the

ExtFortranDLL example the linear spring constants of the Floaters are set to zero in the

ini file. The calculation executed by the regular spring functionality of aNySIM will result

in a spring force of zero Newton. In the ExtFortran DLL example the linear spring is

calculated by the DLL. The linear spring constants, which are hard coded, have the

same value as in the LiftCase example.

The DLL can be build with the ‘BuildExtFortranDLL.bat’ script. In order to actually use

the built DLL, is must be copied to the ‘bin’ directory. The code added for this example

(see ExtFortranDLL.f90) is surrounded by ‘#ifdef __EXAMPLE__ ... #endif __EXAMPLE’

statements. The example functionality can kept out by making the ‘#define

__EXAMPLE__’ statement (line 40) inactive. By commenting line 40, thanks to the

exclamation mark, the example code is not taken into account.

Via the ini file must be specified whether the DLL should be called at the communication

intervals or at the integration intervals:

[ExtFortranDLL]

Interval = Communication

Or

[ExtFortranDLL]

Interval = Integration

The forces calculated by the ExtFortranDLL can be written to the ouput file

(ExtFortranDLL.res) by using the ‘Fextcl’ and Fextil’ output aliases, as can be seen in

the output section of the ExtFortranDLL.ini file. In the ExtFortranDLL example also a

time trace is written to a file called ‘TimeTrace.txt’. By examining this .txt file the

difference of the two interval settings can be seen.

Finally, aNySIM can be run from the LiftCase and the ExtFortranDLL directories. Output

of both runs can be compared by plotting the results. Because of the resemblance of

both results, the External Fortran DLL concept has been demonstrated.

User Manual 8

7.2 Running the example

The following list shows in detail the steps required for running the example:

• Gather the required files in the example directory:

…\aNySIM\examples\ExtFortranDLL:

o Copy all the files from …\aNySIM\bin (so the aNySIM installation

remains unchanged)

o Copy all the files from …\aNySIM\build_dll\Files

• Delete ExtFortranDLL.dll in the example directory

• Build a new DLL with .bat file

• Make sure the newly build DLL is in the example directory (possibly you have to

move it)

• Open a command window in the exercise directory

• Run the simulation by issuing the following command:

.\anysim ExtFortranDLL.ini