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.
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.
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.
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.
flook consists intrinsically of 4 libraries:
- Lua library (
-llua), - fortran to Lua interface (
-lflu), see Thanks, - basic fortran Lua interaction layer (
-laotus), see Thanks, - flook (
-lflook).
However, two variants of linking is available.
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.
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.
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
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.
The flook license is MPL-2.0, please see the LICENSE file.
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.