Repository files navigation

This function parser module is intended for applications where a set ofmathematical fortran-style expressions is specified at runtime and isthen evaluated for a large number of variable values. This is done bycompiling the set of function strings into byte code, which isinterpreted efficiently for the various variable values.

This code is a modernized version offparser (v1.1), a Fortran 95 function parser (v1.1) byRoland Schmehl. The function parser concept is based on a C++ class library written by Juha Nieminenwarp@iki.fi available fromhere. The original code has been updated to Fortran 2008 by Jacob Williams. Development continues onGitHub.

The library can be built with theFortran Package Manager using the providedfpm.toml file like so:

fpm build --release

By default, the library is built with double precision (real64) real values. Explicitly specifying the real kind can be done using the following preprocessor flags:

For example, to build a single precision version of the library, use:

fpm build --profile release --flag "-DREAL32"

To usefortran_function_parser within your fpm project, add the following to yourfpm.toml file:

[dependencies]fortran_function_parser = {git="https://github.com/jacobwilliams/fortran_function_parser.git" }

Or, to use a specific version:

[dependencies]fortran_function_parser = {git="https://github.com/jacobwilliams/fortran_function_parser.git",tag ="1.1.0" }

The latest API documentation can be foundhere. This was generated from the source code usingFORD.

In all program units where you want to use the function parseryou must import the module by:

use function_parser

This command imports only 3 public types:fparser,fparser_array, andlist_of_errors, which are explained in the following. The remainder of themodule is hidden to the calling program.

A single function stringfuncstr can be parsed (checked and compiled) intobytecode by calling thefparser class method subroutineparse:

call me%parse(funcstr, var, case_sensitive)

The variable names as they appear in the stringfuncstr have to be passedin the one-dimensional string arrayvar (zero size ofvar is acceptable).The number of variables is implicitly passed by the dimension of this array.For some notes on the syntax of the function string see below.

To parse an array of function strings, you can use thefparser_array classmethodparse in a similar manner.

The function value is evaluated for a specific set of variable valuesby calling thefparser class method subroutineevaluate:

call me%evaluate(val, res)

The variable values are passed in the one-dimensional arrayval which musthave the same dimension as arrayvar.

To evaluate an array of function strings, you can use thefparser_array classmethodevaluate in a similar manner.

To free the memory and destroy a variable of typefparser orfparser_array,use thedestroy method:

call me%destroy()

Errors can be reported by both theparse andevaluateclass methods. To check for errors, use theerror method, and to print them use theprint_errors method:

if (me%error())then     me%print_errors(output_unit)end if

An error in the function parsing step leads to a detailed error message(type and position of error). An error during function evaluation returns a function value of 0.0.

Although they have to be passed as array elements of the same declaredlength (Fortran restriction), the variable names can be of arbitraryactual length for the parser. By default, parsing for variables is case insensitive,but case sensitive evaluation is also an option.

The syntax of the function string is similar to the Fortran convention.Mathematical Operators recognized are+,-,*,/,** or alternatively^,whereas symbols for brackets must be().

The function parser recognizes the (single argument) Fortran intrinsicfunctions:

• abs,acos,asin,atan,atan2,ceiling,cos,cosh,exp,floor,gamma,hypot,log,log10,max,min,mod,modulo,sign,sin,sinh,sqrt,tan,tanh

In addition, the following zero-argument function:

• pi -- Returns the value of$\pi$

And the three-argument function:

• if -- Logical comparision function. The syntax is:if(expression, value if true, value if false), where 0.0 is false, and any other real value is true.

Parsing for functions is always case INsensitive.

Operations are evaluated in the correct order:

• () expressions in brackets first
• -A unary minus (or plus)
• A**B A^B exponentiation (A raised to the powerB)
• A*B A/B multiplication and division
• A+B A-B addition and subtraction

The function string can contain integer or real constants. To be recognizedas explicit constants these must conform to the format

[+|-][nnn][.nnn][e|E|d|D[+|-]nnn]

wherennn means any number of digits. The mantissa must contain at leastone digit before or following an optional decimal point. Valid exponentidentifiers are 'e', 'E', 'd' or 'D'. If they appear they must be followedby a valid exponent.

There are various other expression parsers out there written in Fortran:

flowchart TBfparser[<a href='http://fparser.sourceforge.net'>fparser</a>]fparser-->FortranParser[<a href='https://github.com/jacopo-chevallard/FortranParser'>FortranParser</a>]fparser-->fortran_function_parser[<a href='https://github.com/jacobwilliams/fortran_function_parser'>fortran_function_parser</a>]fortran_parser-->fortran_script[<a href='https://github.com/sdm900/fortran_script'>fortran_script</a>]ffp[<a href='http://www.labfit.net/functionparser.htm'>Fortran Function Parser</a>]feq-parse[<a href='https://github.com/FluidNumerics/feq-parse'>feq-parse</a>]fortran_parser[<a href='https://github.com/sdm900/fortran_parser'>fortran_parser</a>]M_calculator[<a href='https://github.com/urbanjost/M_calculator'>M_calculator</a>]M_calculator-->compute[<a href='https://github.com/urbanjost/compute'>compute</a>]

• fparser -- Original Fortran 95 function parser by Roland Schmehl.
• FortranParser -- Another refactoring of the originalfparser code by Jacopo Chevallard.
• Fortran Function Parser -- An entirely different code by Wilton and Ivomar, 10/01/2007 (GitHub mirrorhere).
• feq-parse -- Fortran Equation Parser from FluidNumerics.
• fortran_parser -- Fortran Equation Parser from Stuart Midgley.
• M_calculator -- Parse Fortran-like double precision scalar expressions from urbanjost

• Application of Modern Fortran to Spacecraft Trajectory Design and Optimization (AIAA 2018-1451) describes a method of constructing a Fortran expression parser using binary syntax trees.
• Dynamic Eval for Fortran Suggestion to add dynamic expression evaluation to the Fortran language (don't hold your breath).