Skip to content

ElectronicStructureLibrary/flook

Repository files navigation

flook

Build Status

The fortran-Lua-hook library.

It allows abstraction of input files to be pure Lua files to enable configuration of internal variables through an embedded Lua interpreter.

Any valid Lua script can be executed from within any fortran application at points where the application creates Lua channels.

Its main usage is the ability to change run-time variables at run-time in order to optimize, or even change, the execution path of the parent program.

Usage

The API documentation of flook resides at documentation.

Imagine you have a program which has 3 distinct places where interaction might occur:

program main
call initialize()
call calculate()
call finalize()
end program

At each intermediate point one wishes to communicate with a scripting language.
flook lets you communicate fortran and Lua. For an elaborate example see Examples.

Downloading and installation

flook is part of the ESL-bundle which allows easy installation along side many other libraries that may also be required.
For manual installation, please read on.

Installing flook requires you to first fetch the library which is currently hosted at github at flook@git.

To fetch all required files do this

git clone https://github.com/ElectronicStructureLibrary/flook.git
ls -l

At this point you should see (at least) the following directories and files:

drwxr-xr-x 7 USER GROUP 4.0K Jun  5 17:57 aotus
-rw-r--r-- 1 USER GROUP 7.5K Jun  5 17:56 LICENSE
-rw-r--r-- 1 USER GROUP  667 Jun  5 17:56 Makefile
-rw-r--r-- 1 USER GROUP  298 Jun  5 17:56 README.md
drwxr-xr-x 2 USER GROUP 4.0K Jun  5 17:56 src

To compile flook you need a minimal setup.make file.
The content of setup.make, which should be located in the top directory, can be this minimal content (please correct tabulators to conform to Makefile standards):

CC = gcc
FC = gfortran
CFLAGS = -g
FFLAGS = -g
.f90.o:
    $(FC) -c $(FFLAGS) $(INC) $<
.F90.o:
    $(FC) -c $(FFLAGS) $(INC) $<
.c.o:
    $(CC) -c $(CFLAGS) $(INC) $<

The $(INC) is needed for internal reasons, (sorry about the quick mock-up)...

Type make and possibly make check to run the tests in the src/test directory.

Compiling the internal Lua package requires tweaking if you are using a different platform than linux.

PLATFORM = aix | bsd | c89 | freebsd | generic | linux | macosx | mingw | posix | solaris

where the makefile system will try and guess the correct platform. However, if the build fails due to the Lua library, then please supply PLATFORM with the correct platform in your setup.make file.

Lua

aotus is packaged together with Lua 5.3.0 and enables the direct compilation of Lua and the fortran bindings. However, if Lua gets updated or you wish to control your Lua environment you can use your local Lua installation.

By adding these flags to your setup.make

LUA_DIR = /path/to/lua/installation
INC += -I$(LUA_DIR)/include

an external library for the Lua environment will be used.

Linking

flook consists intrinsically of 4 libraries:

  1. Lua library (-llua),
  2. fortran to Lua interface (-lflu), see Thanks,
  3. basic fortran Lua interaction layer (-laotus), see Thanks,
  4. flook (-lflook).

However, two variants of linking is available.

Compiling for one link

flook can combine the libraries from 1. - 4. into one library.

To do this simply call make with this command

make liball

which creates libflookall.a in the top directory. With this library you only need to link one library.

To link flook to your program the following can be used in a Makefile

FLOOK_PATH  = /path/to/flook/parent
FLOOK_LIBS  = -L$(FLOOK_PATH) -lflookall -ldl
FLOOK_INC   = -I$(FLOOK_PATH)

For the sources that you compile you need to add $(FLOOK_INC) to the command line, whilst for linking the program you need $(FLOOK_LIBS) on the command line. Note that -ldl is a requirement for the Lua library, and per-see is more difficult to incorporate.

Direct linking

When compiling for one link does not work, the following method is less restrictive on the commands used.

In order to link to flook you can use this template (Makefile) for include statements and library linking (note that you should not switch the order of these statements):

FLOOK_PATH  = /path/to/flook/parent
FLOOK_LIBS  = -L$(FLOOK_PATH) -lflook
FLOOK_LIBS += -L$(FLOOK_PATH)/aotus/obj -laotus
FLOOK_LIBS += -L/path/to/lua/lib -llua -ldl
FLOOK_INC   = -I$(FLOOK_PATH)

For the sources that you compile you need to add $(FLOOK_INC) to the command line, whilst for linking the program you need $(FLOOK_LIBS) on the command line.

Examples

Several examples exists in the src/test directory where one is shown in the following example:

@include src/test/tst_exp_flook.f90

The above program is a fortran program which communicates with an embedded Lua environment. It communicates with Lua 6 times and allows retrieval of elements and changing the elements at each communication point.
The communicating Lua code looks like this:

@include src/test/tst_exp_flook.lua

Contributions, issues and bugs

I would advice any users to contribute as much feedback and/or PRs to further maintain and expand this library.

Please do not hesitate to contribute!

If you find any bugs please form a bug report/issue.

If you have a fix please consider adding a pull request.

License

The flook license is MPL-2.0, please see the LICENSE file.

Thanks

First, I owe Harald Klimach a big thanks for the creation of aotus for the Lua-Fortran embedment.

Second, I thank James Spencer for help regarding the aotus API.

Third, I thank ESL for hosting a workshop for me to participate and create the initial release.