Overview of IREP¶

The Intermediate Representation (or IR or IREP) is a tool to simplify reading some kinds of external program input, a means to organize the input into native language structures, and a way to share those structures among program modules written in either C/C++ or Fortran. It can handle several varieties of Plain Old Data and has mechanisms to extend its abilities beyond POD. It requires access to a Lua 5.1 interpreter, C and Fortran compilers, and follows standards for those languages. A reader for tables written in the Lua programming language is included.

Introduction¶

Nested Tables¶

The IR includes a Structure macro to allow nested C/C++ and Fortran structures:

IREP                    C/C++            Fortran
__________________________________________________
Beg_struct(irt_T1)      ...              ...
  Structure(irt_T2,x)   irt_T2 x;        type(irt_T2) :: x
End_struct(irt_T1)      ...              ...

Nested structures follow C ordering rules: irt_T2 must be declared before irt_T1, etc. After the IR has been defined and compiled, and after data has been read from the Lua input file into the IR, the host code can gaccess data using native language operations:

-- First, set the value by reading the Lua table.
material[1].EOS.table.number = 1018

// Later, read the value from C/C++.
int n = material[1].EOS.table.number; // 1018

! Or read the value from Fortran.
integer :: n
n = material(1)%EOS%table%number ! 1018

Notice that the example above uses index 1 for all three languages. This is a consequence of the way that the material table was declared in the IREP. See the discussion of the Vir_wkt0m macro in the IREP man page that accompanies this paper for more information.

Reading Data into the IR¶

The compiled data store in the IR is independent of any means to load or change its values. We provide a Lua table reader for that purpose. If the IR data store defines a top-level structure named material, as in the example above, we expect the Lua input to contain a global table also named material, and call this a well known table (WKT). The elements of the Lua table must match the elements of the IR structure. Whenever the Lua reader reaches a leaf node in its table, it looks up the address of the matching IR element, and places the value at that memory location.

Designing the User Interface¶

Lua tables and Lua variables can be quite different from C/C++ or Fortran structures and variables. Here are some Lua idioms that are difficult to model in the IR data store:

Polymorphic element values: Lua is happy to allow both x=1 and x="one" (at different times) in the same table. This is hard to do in the IR, because C/C++ and Fortran variables can’t change type. One place where we do allow polymorphic elements is our implementation of callback functions:
```
f = 3
f = { 1, 2, 3 } -- max len is 9 elements
f = function() return 3 end
```
We frequently use constant callback functions, so it is convenient to allow scalar or array values in place of a true Lua function, as shown in the first two examples above. Callback functions require some special handling already, so this case does not present much extra trouble for the Lua reader. In general, however, it’s a good idea to limit polymorphic elements in the user interface.
Lua tables with both record and array parts:
```
a = { 3,2,1, x=4 }
```
That is, a[1] == 3, and a.x == 4. There is no easy way to handle this case with the IR, because a is neither a vector, nor is it a structured type. It’s some of both. Don’t do this, or use an ir_reference if you must.
Lua arrays with mixed types:
```
a = { 3,2,1, "liftoff" }
```
In this case, a is a vector, but its elements don’t have any single type. Arrays in C/C++ and Fortran cannot have elements of more than one type. So don’t do this either.

In designing the user interface, we can choose, case by case, whether to let the constraints imposed by the IR also constrain or shape the Lua interface. By its nature, the IR rewards simplicity in user interface design.

Some usage notes¶

The `ir_read` and `ir_exists` functions¶

In addition to defining IR input data, the host code is responsible for reading the well known tables. The function provided for this task is ir_read. For example, in C, we might read the materials table:

int n = ir_read(L, "materials");
if (n != 0) {
    printf("ERROR: %d\n", n);
    exit(1);
}

ir_read returns the total number of errors it encountered. For well known tables that may be optional, the ir_exists function is provided to allow the host code to query whether a given table element is in the Lua state before attempting to read it.

Strings¶

Sharing strings between Fortran and C/C++ is easier than it once was. That said, reading strings from the IR requires extra care for both languages. Strings are stored in the IR as an array of characters, NULL terminated. The max length is part of the original declaration, and it includes the NULL character. The IR provides convenience functions and macros to simplify some common operations:

std::string myfoo(IR_STR(t.c));    // C++: Declare/initialize.
character(len=64) :: myfoo         ! Fortran: Declare scalar.
myfoo = trim(fstr(IR_STR(t.c))) ! Initialize it.