Fortran Usage Guide

Fortran usage of the Iguana C functions. More...

Detailed Description

Fortran usage of the Iguana C functions.

C functions

Iguana provides a set of C functions which are callable from Fortran:

• Each action function should have a corresponding C function
• Additional general C functions are used for starting, configuring, and stopping algorithms
• The Namespaces section below links to lists of C functions
  • They are organized into categories (C++ namespaces)
• the function names are all lowercase, and end in an underscore, to permit automatic binding to Fortran 77
  • To use a C function in Fortran, call it as a subroutine, but without the final underscore
  • use iso_c_binding data types for the arguments (see below), otherwise you may have subtle runtime problems
• The C functions do not have return values; instead, variables are passed by reference, and may be one of three kinds:
  • [in]: input parameter, will not be mutated
  • [out]: output parameter, will be mutated
  • [in,out]: both an input and an output parameter, will be mutated

The available C functions and their documentation, organized by C++ namespace, are listed at the bottom of this page in the Namespaces section.

For information about each algorithm and their action functions, see:

• Algorithms organized by Namespace
• Full List of Algorithms

iso_c_binding module

The iso_c_binding module is used to make sure the data type sizes are consistent between Fortran and C++. Here is a mapping of some common types to use for subroutine arguments:

C data type	Fortran data type
int	integer(c_int)
short	integer(c_short)
long	integer(c_long)
float	real(c_float)
double	real(c_double)
bool	logical(c_bool)
char	character(c_char)
char const*	character(kind=c_char, len=1024)
size_t	integer(c_size_t)
concurrent_key_t	integer(c_size_t)

Refer to the iso_c_binding documentation for more details.

Warning

For strings, char const* in C, make sure that the string that you pass from Fortran has the correct termination (c_null_char), even if it's a string literal; also make sure that it is big enough (len). For example, the C function

void iguana_example_function_(char const* str);

must be called in Fortran like this:

c     string variables need to be BOTH trimmed AND terminated:
      character*1024 str
      str = 'sample_string'
      call iguana_example_function(trim(str)//c_null_char)
 
c     string literals just need to be terminated:
      call iguana_example_function('sample_string'//c_null_char)

Note

concurrent_key_t is an Iguana-specific type used by iguana::ConcurrentParam objects; in Fortran, use integer(c_size_t).

How to call C functions from Fortran

For example, consider the following C function:

void iguana_example_function_(int* a, float* b);

To use this in Fortran:

c     use the ISO_C_BINDING module:
      use iso_c_binding
c     function arguments must be ISO_C_BINDING kinds:
      integer(c_int) a
      real(c_float) b
c     example function call:
      call iguana_example_function(a, b)

For complete examples, see Fortran examples

Building: linking to Iguana libraries

To use Iguana with your Fortran code, link against the installed iguana libraries; for example, if you use a Makefile, you may set the linking arguments to $(IGUANA_LIBS),

IGUANA_LIBS = $(shell pkg-config iguana --libs --maximum-traverse-depth 2)

then use $(IGUANA_LIBS) in your compilation options. If you need to link Iguana dependency libraries too, remove the --maximum-traverse-depth 2 argument.

Namespaces
namespace	iguana::bindings
	General iguana bindings.
namespace	iguana::bindings::clas12
	CLAS12 algorithm action function bindings.
namespace	iguana::bindings::physics
	Physics algorithm action function bindings.