Calling the NAG Library from Microsoft C#

The DLLs from the NAG Library may be used from within a C# environment. To assist you in mapping between the Fortran-based FL Interface and C# types, zip files containing C# header files (flcsdnet.cs for use with 32-bit Windows Libraries, flcsdnet64.cs for use with 64-bit Windows Libraries, and flcsdnet64_linux.cs for use with 64-bit Linux Libraries) are provided.

If you wish to use a NAG Library routine, it is recommended that you access the declarations via one of the following options:

  1. The declarations of the NAG routines being used can be copied into your sources;
  2. The entire file can be added to your sources (in which case all the declared methods are available in a class NagLibrary.nag_declarations).
  3. The supplied file may be compiled eg with 
    csc /target:library /platform:x64 flcsdnet64.cs

    This will produce a .NET Library flcsdnet64.dll that can be referenced from any .NET language project (eg F# or C#) so avoiding the need to express the required declarations in those languages.

.NET Types

The NAG Library FL Interface uses the following data types as parameters. These are:

  • scalars of type DOUBLE PRECISION, INTEGER and COMPLEX*16;
  • arrays of type DOUBLE PRECISION, INTEGER and COMPLEX*16;
  • character strings and arrays of character strings;
  • function parameters, also known as callbacks, that are pointers to functions with particular signatures; and
  • C pointers, which use the derived type TYPE(C_PTR).

Our principal task here is to map these types to C#.

In C#, we distinguish between parameters as being passed either by reference or by value. In Fortran, all parameters are passed by reference only. Hence every scalar parameter to an FL Interface routine has to be qualified by the keyword ref. This does not apply to arrays as they are passed by reference in C#. The example programs below demonstrate this requirement.

There is one further consideration that we have to bear in mind as far as arrays are concerned. In Fortran, two-dimensional arrays are stored contiguously in memory by columns while in C# two-dimensional arrays of the type [,] are stored contiguously by rows. It follows, therefore, that before a two-dimensional C# array is passed to a Fortran routine as a parameter, it has to be transposed. See f07abfe.cs (32-bit) or f07abfe.cs (64-bit).

A complex number Z may be represented as an ordered pair of real numbers consisting of the real part of Z and the imaginary part of Z. In Fortran, this is exactly how a complex type is stored and so we may utilise this observation to pass information from and to C#. Specifically, we may use a C# double array to hold the real and imaginary parts (in that order) of complex numbers and pass this into the NAG DLL to represent a complex array or complex number. It might seem more elegant to define a structure with two double elements to represent the complex type, but we have found in practice that this works only for input data. We may pass complex data into the NAG DLL in this manner but cannot obtain information back from the DLL via this structure. See f07apfe.cs (32-bit) or f07apfe.cs (64-bit).

Character strings can be declared as the string type in C#. The strings have to have a fixed length and the length of the string has to be passed as an additional parameter. Character arrays in Fortran have contiguous storage and so cannot be represented as string arrays. We have found that we can mimic the Fortran character array using byte arrays. See g02eafe.cs (32-bit) or g02eafe.cs (64-bit).

Function parameters in Fortran map to the delegate type in C#. Array parameters in the delegate type require the use of the C# IntPtr type and the Marshall class. See e04ucae.cs (32-bit) or e04ucae.cs (64-bit).

Some routines use C pointers to specify handles and to access user workspace. The Fortran derived type TYPE(C_PTR) maps to ref IntPtr in C#. See e04fffe.cs (32-bit) or e04fffe.cs (64-bit).

Examples

We have provided C# classes based on NAG Fortran examples as shown in the NAG Library Manual to illustrate various parameter mappings. For example, a sample C# class calling e04uca can be found in e04ucae.cs. If there are particular routines whose signatures cannot be determined from the information we have provided please contact us.

Example 1
Parameter features: double scalars, simple callback
d01ahfe.cs (32-bit)     d01ahfe.cs (64-bit)
Example 2
Parameter features: double arrays, more involved callback
e04cbfe.cs (32-bit)     e04cbfe.cs (64-bit)
Example 3
Parameter features: double arrays, involved callback with 2-D double arrays
e04ucae.cs (32-bit)     e04ucae.cs (64-bit)
Example 4
Parameter features: 2-D double arrays, character string
f07abfe.cs (32-bit)     f07abfe.cs (64-bit)
Example 5
Parameter features: 2-D complex arrays, character string
f07apfe.cs (32-bit)     f07apfe.cs (64-bit)
Example 6
Parameter features: 2-D double arrays
g02dafe.cs (32-bit)     g02dafe.cs (64-bit)
Example 7
Parameter features: string array
g02eafe.cs (32-bit)     g02eafe.cs (64-bit)
Example 8
Parameter features: double scalar
s07aafe.cs (32-bit)     s07aafe.cs (64-bit)
Example 9
Parameter features: C pointers, custom class for callback
e04fffe.cs (32-bit)     e04fffe.cs (64-bit)

In addition to the above we have provided the following examples:

At a Windows command line prompt, most of these examples can easily be compiled using the C# compiler csc like this for 32-bit programs:

  csc /platform:x86 driver.cs

or like this for 64-bit programs:

  csc /platform:x64 driver.cs

where driver.cs is the name of one of the example programs. The exceptions are the E04FFF examples, which illustrate a different approach. For these, the header file needs to be specified on the command line as the declarations have not been copied to the source file. You can compile like this for the 32-bit variant:

  csc /platform:x86 flcsdnet.cs e04fffe.cs

or like this for 64-bit variant:

  csc /platform:x64 flcsdnet64.cs e04fffe.cs

Information on compiling and running the examples under Linux is also provided.

A zip file containing all these examples may also be downloaded: 32-bit C# examples or 64-bit C# examples.