User guide for user-wind-dll

A user defined DLL can be used to provide additional wind velocity on top of what is already defined by wind input in HAWC2. During simulation, HAWC2 calls the DLL with position as argument, and the DLL must provide the wind velocity in that position on return. Apart from the position, HAWC2 also parses time and user-specified arguments to the DLL - the user-specified arguments are defined in the same output block format as is used for type2_dlls and hawc_dlls and as regular output.

Htc file input

Application of the DLL is defined inside the begin wind block as shown below.

begin wind ;
  .
  begin user_wind_dll ;
    filename 2-test.dll;
    subroutine wind_dll_getwindspeed ;
    refsys 0   ; Reference coordinates for position (in) and velocity (in/out),
           ;  0=meteorological(default), 
           ;  1=global
    begin output ;
      general constant 1.0          ;  
      dll inpvec 1 1             ;
      constraint bearing1 shaft_rot 1 only 2 ;
      mbdy momentvec shaft 1 1 shaft only 3  ;
    end output ;
  end user_wind_dll ;
  .
end wind

The output arguments that can be used inside the begin output block are limited general, dll, constraint, and mbdy.

DLL interface definition

The DLL subroutine is called each iteration with these arguments: - time, (double). - position vector: Dependent on the key refsys in the user_wind_dll block (see above), the position vector provided is either meteorological or global coordinates, (double(3)). - Nof arguments in the begin output in the user_wind_dll block, (nargs, integer). - Argument vector defined in the begin output in the user_wind_dll block, (double(nargs)). - Wind velocity: On input, the vector contains the wind velocity contribution from the whatever is defined in the begin wind block, i.e. the sum of mean wind, wind shear, etc. On output, the vector must contain the extra(!!, NOT the total) wind contribution in the refsys coordinate system , (double(3))

The DLL subroutine interface is defined as follows:

interface
  subroutine user_wind_dll_call(time, pos, nargs, args, wsp)
  !dec$ attributes c :: user_wind_dll_call
  double precision  :: time     ! time
  double precision  :: pos(3)    ! position of lookup point (refsys coordinates)
  integer       :: nargs    ! nof user arguments (provided via dll output block)
  double precision  :: args(nargs) ! user arguments (provided via dll output block)
  double precision  :: wsp(3)    ! lookup windspeed, 
	                  !  on input : wind velocity in <pos> (refsys coord.)
	                  !  on output: user velocity contribution (refsys coord.)
  !dec$ attributes reference :: time, pos, nargs, args, wsp
  end subroutine
end interface

Note that the effect of tower shadow is applied after the call to the DLL.

FORTRAN example

subroutine wind_dll_getwindspeed(time,pos,nvar,var,wsp)
  !dec$ attributes c,dllexport, alias:"wind_dll_getwindspeed" :: wind_dll_getwindspeed
  !gcc$ attributes cdecl :: wind_dll_getwindspeed
  !gcc$ attributes dllexport :: wind_dll_getwindspeed
  ! variables
  integer nvar
  double precision time,pos(*),var(*),wsp(*)
  !dec$ attributes reference :: time, pos, var, wsp
    
  ! implementation
  print*,"nvar = ",nvar
  print*,"time = ",time
  print*,"pos = ", pos(1:3)
  print*,"wsp = ", wsp(1:3)
  wsp(1:3) = (/0.0, 0.0, 0.0/)  
end subroutine wind_dll_getwindspeed

The DLL can be built from the FORTRAN code above using the GNU compiler syntax:

gfortran -shared -static -o <file>.dll -fno-underscoring <file>.f90

C example

#include <stdio.h>
__declspec(dllexport) void wind_dll_getwindspeed(double* time, double* pos, int* nvar, double* var, double* wsp)
{
  int i;
  // implementation
  printf("nvar = %d\n", *nvar);
  printf("time = %f\n", *time);
  printf("pos = (%f, %f, %f)\n", pos[0], pos[1], pos[2]);
  printf("wsp = (%f, %f, %f)\n", wsp[0], wsp[1], wsp[2]);
  for (i = 0; i < 2; i++)
  {
    wsp[i] = 0.0;
  }
}

The DLL can be built from the C code above using the GNU compiler syntax: “‘ gcc -shared -static -o .dll .c