How to implement same procedures for different numeric kinds

[milancurcic]

This question comes up in #34 and elsewhere. How to implement specific procedures that work on different kinds (sp, dp, qp, int8, int16, int32, int64) as well as characters, where the body of the procedure is the same (can be copy/pasted entirely without breaking it). Let's first just focus on this scenario, and we can consider more complex cases later.

I know of a few approaches:

1. Repeat the code, that is, implement all specific procedures explicitly. That's what I did in functional-fortran, see https://github.com/wavebitscientific/functional-fortran/blob/master/src/lib/mod_functional.f90. Repeating is fine if you do it once and forget about it. The upside is that you can see the specific code and it needs no extra tooling. The downside is combinatorial explosion if you have procedures that are to handle all combinations of types and kinds. Most procedures are rather simple (one or two arguments), and I ended up with > 3K lines of code for 23 generic procedures. Most work was in editing the argument types to specific procedures, and less work was in copy/pasting of the repeatable content. I don't recommend this approach for stdlib.

2. Approach 1 can be somewhat eased by explicitly typing out the interfaces, and using #include 'procedure_body.inc', defined in a separate file. Then your procedure body collapses to one line. This reduces the total amount of code, but not so much the amount of work needed, as most work is in spelling out the interfaces. This approach still doesn't need extra tooling as a C preprocessor comes with all compilers that I'm aware of.

3. Use a custom preprocessor or templating tool. For example, a function that returns a set of an array:

pure recursive function set(x) result(res)
  integer, intent(in) :: x(:) !! Input array
  integer, allocatable :: res(:)
  if(size(x) > 1)then
    res = [x(1), set(pack(x(2:), .not. x(2:) == x(1)))]
  else
    res = x
  endif
end function set

A template could look like this:

pure recursive function set(x) result(res)
  {int*, real*}, intent(in) :: x(:) !! Input array
  {int*, real*}, allocatable :: res(:)
  ... ! body omitted for brevity
end function set

or similar, where the custom preprocessor would spit out specific procedures for all integer and real kinds. Some additional or alternative syntax would be needed if you wanted all combinations of type kinds between arguments.

There may be tools that do this already, and I think @zbeekman mentioned one that he uses. In general, for stdlib I think this is the way to go because we are likely to see many procedures that support multiple arguments with inter-compatible type kinds. The downside (strong downside IMO) is that we're likely to introduce a tool dependency that also depends on another language. If the community agrees, we can use this thread to review existing tools and which would be most fitting for stdlib.

Let's say we pick a tool to do the templating for us, we have two choices:

a) Have user build specifics from templates. In this scenario, the user must install the templating tool in order to build stdlib. I think we should avoid this.
b) Use the templating tool as developers only, and maintain the pre-built specifics in the repo. This means that when we're adding new code that will work on many type kinds, we use the tool on our end to generate the source, and commit that source to the repo (alongside the templates in a separate, "for developers" directory).

Assuming we can find a fitting tool, I'm in favor of the 3b approach here. There may be other approaches I'm not aware of or forgot about. What do you think and any other ideas?

[certik]

Actually I propose 3c).

c) The git repository contains the templated code, depends on a 3rd party tool, and does not contain any autogenerated files. Then we created release tarballs automatically on a CI. A release tarball contains all the necessary generated files and the only dependencies are cmake (or make) and a Fortran compiler, and does not contain the git history, the templated files, nor any CI files and other things that are not needed to actually build the library. Users, as well as distributions (Debian, Ubuntu, Homebrew, Conda, Spack, etc.) only use the tarball, not the git repository.

I follow exactly this approach with LFortran, and it seems to work great. The advantage is that the git repository does not have autogenerated files, which greatly simplifies PRs (a simple diff versus hundreds of lines of modified autogenerated files) and makes it obvious how things should be modified --- so that people who want to contribute do not accidentally modify the autogenerated files, or forget to generate the files. Rather, the files are automatically generated using a CI, so they are always generated correctly.

[milancurcic]

Great! I didn't think of this and indeed it seems to me like the best way to go.

[zbeekman]

The best templating tool I have found is Jin2For. It uses Jinja2 templating which people may be familiar with from web technology stuff and is the templating back end for FORD. These are Python based, which is likely a language that Fortran developers may be familiar with. It can auto-generate default type aliases, kind info, and declarations by querying the compiler and enumerating ISO_Fortran_ENV's real_kinds, integer_kinds, logical_kinds and character_kinds array.

By providing a generic implementation for each intrinsic kind (where it is sensible to do this) the user doesn't need to care about setting dp, sp, rk, or whatever other convention you have for selecting kinds. Things just work™️. The downside is that compilers are not required to support all kinds, so you end up generating code specific to the kinds that a given compiler supports. This is not necessarily a bad thing, but it means that you may want to distribute different source versions tailored to different compilers. Since Fortran doesn't have a standard/interoperable ABI this is not really an issue at all, IMO.

[milancurcic]

I reviewed jin2for and I like its simplicity (a minimal and to the point tool) and the fact that it uses an existing templating language rather than inventing a new one. I think it's a good candidate.

[certik]

Let's try to use jin2for and see how it goes.

In general, I think the Fortran language itself should make it easier to write subroutines that operate on different kinds. This is something I would love to experiment with in LFortran in the future, and using jin2for is a solid starting point -- the future goal would be to simplify the syntax using (future) Fortran features.

[jvdp1]

I gave a try to jin2for with loadtxt/savetxt (see https://github.com/jvdp1/stdlib/blob/loadtxt_autogen/src/stdlib_experimental_io.F90 and other tests/loadtxt/*.F90 files).

I am not sure how it should be done with cases that involve both integer and real kinds. Should the pre-defined templates be used? If yes, how to use kinds defined as sp, dp, qp?

Anyway, jin2for seems to be a nice and useful tool, and the option 3c proposed by @certik seems to be a good approach (not implement in my branch).

[marshallward]

What are the disadvantages of using CPP for this? I am worried about deepening the necessity on external tools, which can hinder portability.

CPP is always almost always available and often baked into the compiler (I think it's literally a library inside gfortran). Another advantage of CPP is that the compiler is often aware of the step, and debugging can point directly to the template file, rather then a copy placed in some scratch directory for which the user is unaware.

We've used it in FMS for this task without much issue. Readability and debugging are the only major drawbacks, but this would be true fur any templating approach.

(I'm on the road right now but can supplement with links when I get a chance.)

[milancurcic]

As far as I understand CPP is more limited in what can be done with it. I'm surprised that you could do this with CPP alone.

In the scenario 3c, the external tool is required only of stdlib developers and not of end users, so I don't see much of a portability issue.

[marshallward]

This post outlines what we can do with FMS with CPP templating:

j3-fortran/fortran_proposals#4 (comment)

[milancurcic]

Thanks @marshallward, I just read the comment and the sources you linked and I agree, it does seem quite bloated and is likely to get more complicated when considering different combinations of argument types and kinds.

I think this illustrates well the downsides -- with CPP we can't loop, but only define/undefine macros and branch. There may be more esoteric stuff to it, but this is what I've seen.

@jvdp1 I looked at your templates and the code is quite clean and readable to my eyes. I like it. We probably shouldn't use the .F90 suffix here -- .F90 is still a valid Fortran source file, whereas these templates aren't. I think jin2for suggests .t90 suffix for templates.

[jvdp1]

I tried to implement the IO module with CPP template (see https://github.com/jvdp1/stdlib/tree/loadtxt_cpp/src ).
Honestly I was easier for me to use CPP (it passed the CI) than jin2for. I could also extend the IO module to integers using CPP. For these simple subroutines, using CPP is easy to implement. But using CPP could become quite difficult when combining multiple options.

@jvdp1 I looked at your templates and the code is quite clean and readable to my eyes. I like it. We probably shouldn't use the .F90 suffix here -- .F90 is still a valid Fortran source file, whereas these templates aren't. I think jin2for suggests .t90 suffix for templates.

@milancurcic I followed the syntax implemented by @zbeekman in one of his libraries. I agree that the .t90 suffix might be better.

[certik]

@jvdp1 thanks a lot for implementing both approaches. Here they are, side by side:

• CPP: https://github.com/jvdp1/stdlib/blob/7f246a2b75ed0e6f584e2f820776cf80530dd8e6/src/stdlib_experimental_io.F90 (165 lines + 42 lines in loadtxt.inc and 25 lines in savetxt.inc, total of 232 lines)
• jin2for: https://github.com/jvdp1/stdlib/blob/0ee94604f5b39283f6054d23be00547f4eaec51a/src/stdlib_experimental_io.F90 (149 lines)

It seems the jin2for version is a lot shorter. Am I right? Was it more difficult to implement because it is new, but as we (now) have an example how to use it, it will be perhaps even easier than CPP?

[jvdp1]

@certik jin2for is indeed less verbose, and I think less error prone in this example.
jin2for was more difficult because it was new (e.g., I couldn't extend the subroutines to support integers (as I did with CPP), but I didn't try hard to find the solution; @zbeekman may have some hints).
Both approaches have pros and cons (e.g., CPP passed the CI without any change to it, while it was not the case for jin2for).

[certik]

@jvdp1 we have to update our CI to support jin2for obviously. I would not hold it against it. :)