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, 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

Usage

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)

If the C function has a string parameter (char const*), make sure that the string that you pass has the correct termination (c_null_char), even if it's a string literal; 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)

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.

Collaboration diagram for Fortran Usage Guide:

Namespaces
namespace	iguana
	General, top-level namespace for algorithms and infrastructure. For algorithms and bindings, see its sub-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.