<a name="top"></a>

Coretran

An easy to follow library to make Fortran easier in general with wrapped interfaces, sorting routines, kD-Trees, and other algorithms to handle scientific data and concepts. The library contains core fortran routines and object-oriented classes.

Citation

Please see the metadata in the citation.cff file!

Why coretran?

I used Fortran extensively during my PhD to solve very large systems of equations with application to the inversion of geophysical data for 3D subsurface physical property models. I developed algorithms that utilized random point clouds in space, structured rectilinear, triangular, and voronoi meshes, and the unstructured versions of these. Fortran has relatively little modern and freely available source code, compared to other languages, which have easy to use libraries that perform these types of operations.

I struggled as a beginner coming in to Fortran because the basic functions that handle numbers were not readily available. It was frustrating that I had to write (and then duplicate) my own error checking when allocating memory or opening a file. What also frustrated me was when I had to write the same function/subroutine multiple times for different input types like integers or real numbers.

I wonder, how many people have written their own function as basic as computing a mean of some numbers?

This was initially the driving motivation for me to develop this library. The simple fact that Fortran does not have these basic functions readily available, and that any user starting from scratch would have to write their own. I humbly hope that this library will help to alleviate this issue, by providing functions/subroutines with complexities that range from the most basic to the more advanced, but all in pure Fortran. The effect is hopefully similar to a Python user who has immediate access to amazing packages such as numpy and scipy.

The code comes with a complete set of source code documentation that is easily generated into html pages. These docs also contain working examples on how to run each function and subroutine within the library. Also included in the docs are the references to papers or online material that I used.

This library is written using modern Fortran standards with modules, sub modules, and object oriented derived types.

The code can be compiled easily across platforms using CMake.

Compiler Support

Read the source documentation

---

Main features | Documentation | Compiling | An example of coretran

---

Main features

All functions and subroutines are interfaces, they work no matter the input type whether it real, or integer etc. where it makes sense.

Getting Ready for Compiling and Creating the Documentation

There are three aspects that we need to address

1. Installing a Fortran compiler to create the libraries
2. Installing the software build tool that compiles the codes in the correct order, so you don't have to!
3. Install Python and the software to generate the source code documentation locally (optional! You could just go here)

Installing the GNU fortran compiler <a name="gfortran"></a>

To compile my library, I have been using gfortran version 6.3.0 because of the use of submodules and other 2008 standards. I you want to use Intel's fortran compiler you will need ifort version 17+

* Linux

If you work in Linux you should be well versed in installing packages on your system. At the time of writing this I am running on Ubuntu 16.04 LTS.

* Mac

On a Mac, I use Brew to manage my libraries/programs. So type "brew install gcc" and you should be golden.

* Windows

Windows is a little trickier but it is still easy! The easiest way I have found is to use MinGW. There is a good tutorial on installing mingw here. I will summarize below.

Go to MinGW - Downloads, and click on "Mingw-builds" in the table to redirect to sourceforge. This will download the installer.

When you run the installer, choose the following

• Version: 6.3.0 (minimum) you may choose higher
• Architecture: x86_64
• Threads: posix
• Exception: sjlj
• Build revision: The highest number

You should change the Destination Folder so that the path does not contain any spaces.

Add an environment variable called "MinGW_Home" and point it to the bin directory in your chosen destination folder. e.g. "C:\programs\mingw-w64\x86_64-6.3.0-posix-sjlj-rt_v5-rev1\mingw64\bin"

I don't require MSYS to build my library so you can stop here if you like. I do however suggest making an alias to the MinGW32-make executable, this is optional, so later in these instructions simply replace "make" with "mingw32-make" if you choose not to do this.

<a name="makeAlias"></a> Go to the bin directory in your installation folder, on my system it is "C:\programs\mingw-w64\x86_64-6.3.0-posix-sjlj-rt_v5-rev1\mingw64\bin" and create a file called "make.bat"

Edit the file with a text editor and add the following single line "mingw32-make %*" This allows you to use the command "make" on windows which we will need later to build to library.

Compilation <a name="compile"></a>

The library can be compiled with any custom approach you choose, however to make life easier, I have included instructions on how to use cmake to generate makefiles. Cmake allows you to easily build the same source code on Windows, OSX, and Linux with no changes. I always found make files cumbersome on Windows so Cmake made my life very easy. The portability of Cmake to multiple architectures was the driving reason for me choosing it, plus Cmake can handle the newer, more modern, aspects of Fortran 2003, 2008+, and handles source code dependencies very well.

• Compilation : CMAKE: an open-source, cross-platform family of tools designed to build, test and package software

Installing Cmake

The installation of cmake should be quite easy. Similar to the section above on installing gfortran.

On a Mac, I simply use brew again.

On windows, you should be able to download the installation binary from their website.

Compiling the coretran library

To compile the coretran library, navigate to the root directory and create a new folder "build".

Change directory to build and type

cmake [-D options] [-G option] ../src

There are a number of extra options you can pass through to this cmake command. Each option follows a -D flag.

• -D

  • -DCMAKE_BUILD_TYPE=

    • DEBUG will add all debugging flags, tracebacks, and array bound checking. This is great for development.
    • RELEASE will turn of the less efficient checks, and will compile with higher levels of optimization. This is great for production runs once everything is debugged.

  • -DCMAKE_Fortran_COMPILER=

    • If cmake does not use the compiler you need, you can specify the path to the compiler you want. I had some issues on OSX with the intel compiler and gfortran both installed. Using -G "Unix Makefiles" would always detect the intel compiler. To force cmake to use gfortran, I used -DCMAKE_Fortran_COMPILER=/usr/local/Cellar/gcc/6.2.0/bin/gfortran (Remember I used brew to install gfortran, and that the version number might change!)
    • Even if you type "which gfortran" and it shows the correct one, cmake may still detect a lower version system level gcc/gfortran. If you encounter build errors such as "unclassifiable statement", cmake is probably using too old a version of gfortran. In this case, explicitly specify the gfortran to use with this option.

  • -DBUILD_SHARED_LIBS=

    • ON this is the default option and will build shared libraries.
    • OFF this will build static libraries.

  • -DCMAKE_INSTALL_PREFIX=

    • This allows you to specify an install directory after you compile the library. e.g. -DCMAKE_INSTALL_PREFIX=/path/to/dir will put all compiled modules in an include folder, and compiled libraries in a lib folder. Additionally, the lib folder will contain a folder called "cmake" that contains a cmake config file for coretran. If you append the lib/cmake folder to an environment variable called "CMAKE_LIBRARY_PATH" you will be able to use "find_package(coretran REQUIRED CONFIG)" in your own cmake project to make linking to coretran very easy.

Cmake can generate makefiles for a multitude of different compilers. The -G option allows you to specify which compiler you wish to generate a makefile for.

• -G

  If you type

  cmake -h
  

  You will see not only the man pages for cmake, but also a list of generators e.g.

  Generators
  
  The following generators are available on this platform:
  Unix Makefiles                  = Generates standard UNIX makefiles.
  Ninja                           = Generates build.ninja files.
  Xcode                           = Generate Xcode project files.
  CodeBlocks - Ninja              = Generates CodeBlocks project files.
  CodeBlocks - Unix Makefiles     = Generates CodeBlocks project files.
  CodeLite - Ninja                = Generates CodeLite project files.
  CodeLite - Unix Mak