f90wrap

A specialized Python tool that automatically generates Python extension modules to interface with Fortran code, particularly code that uses derived types. f90wrap extends f2py capabilities by creating a simplified Fortran 90 interface layer that is then wrapped with f2py, combined with a higher-level Pythonic wrapper that makes the additional layer transparent to users.

Package Information

• Package Name: f90wrap
• Language: Python
• Installation: pip install f90wrap or conda install -c conda-forge f90wrap
• Dependencies: Python 3.8+, numpy (with f2py), Fortran compiler (gfortran 4.6+ or ifort 12+)

Core Imports

import f90wrap

For programmatic API usage:

from f90wrap import parser
from f90wrap import fortran
from f90wrap import transform
from f90wrap import f90wrapgen
from f90wrap import pywrapgen
from f90wrap import codegen
from f90wrap.runtime import FortranDerivedType, FortranModule, register_class

For command-line tools:

from f90wrap.scripts.main import main as f90wrap_main
from f90wrap.scripts.f90doc import main as f90doc_main
from f90wrap.scripts.f2py_f90wrap import main as f2py_f90wrap_main

Basic Usage

Command-line Usage

Generate Python wrappers for Fortran source files:

# Basic wrapper generation
f90wrap -m mymodule fortran_source.f90

# Compile with f2py
f2py -c -m _mymodule f90wrap_*.f90 *.o

# Enhanced f2py with f90wrap features
f2py-f90wrap -c -m _mymodule f90wrap_*.f90 *.o

# Generate documentation
f90doc fortran_source.f90

Programmatic Usage

import f90wrap.parser as parser
import f90wrap.fortran as fortran
import f90wrap.transform as transform

# Parse Fortran source files
args = ['source.f90']
tree = parser.read_files(args)

# Transform AST for wrapping
transform.transform_to_f90_wrapper(tree, {}, [], [], [])

# Use runtime classes in generated wrappers
from f90wrap.runtime import FortranDerivedType

class MyFortranType(FortranDerivedType):
    # Generated wrapper code would use this base class
    pass

Architecture

f90wrap follows a multi-stage compilation process:

1. Parsing Stage: Fortran source files are parsed into an Abstract Syntax Tree (AST)
2. Transformation Stage: AST is transformed to remove unwrappable elements and adapt for Python
3. Code Generation Stage: Simplified Fortran 90 wrappers and Python wrappers are generated
4. Compilation Stage: f2py compiles the Fortran wrappers into extension modules
5. Runtime Stage: Generated wrappers use runtime support classes for derived type handling

The design supports advanced Fortran features like derived types, optional arguments, and provides enhanced error handling and interrupt capabilities.

Capabilities

Command-line Tools

Three main command-line utilities for wrapper generation, documentation, and enhanced f2py compilation.

f90wrap -m MODULE F90_FILES [OPTIONS]
f90doc F90_FILES [OPTIONS]
f2py-f90wrap [F2PY_OPTIONS]

Command-line Tools

Fortran Parsing and AST

Comprehensive parsing of Fortran 90/95/2003/2008 source code into a structured Abstract Syntax Tree with support for modules, derived types, procedures, and interfaces.

def read_files(args, doc_plugin_filename=None): ...
class F90File(object): ...
class Fortran(object): ...  # Base AST node
class Module(Fortran): ...  # Module node
class Type(Fortran): ...    # Derived type node

Parsing and AST

AST Transformation

Powerful transformation system for adapting Fortran AST to be suitable for Python wrapping, including type conversions, intent handling, and code restructuring.

def transform_to_f90_wrapper(tree, types, callbacks, constructors, destructors, ...): ...
def transform_to_py_wrapper(tree, types): ...
class FortranTransformer(FortranVisitor): ...

AST Transformation

Code Generation

Flexible code generation framework for producing both Fortran wrapper code and Python wrapper code with customizable formatting and structure.

class CodeGenerator(object): ...
class F90WrapperGenerator(FortranVisitor, CodeGenerator): ...
class PythonWrapperGenerator(FortranVisitor, CodeGenerator): ...

Code Generation

Runtime Support

Runtime classes and utilities that provide the foundation for generated wrapper code, handling derived type management and Fortran-Python interoperability.

class FortranDerivedType(object): ...
class FortranDerivedTypeArray(object): ...
class FortranModule(object): ...
def register_class(object): ...

Runtime Support

Type Analysis and Utilities

Comprehensive type system analysis and utility functions for handling Fortran type conversions, kind mapping, and array processing.

def is_derived_type(typename): ...
def f2py_type(type, attributes=None): ...
def normalise_type(typename, kind_map): ...

Type System

Error Handling

f90wrap provides enhanced error handling capabilities:

• Runtime errors: Fortran routines can raise Python RuntimeError exceptions
• Interruption support: Fortran code can be interrupted with Ctrl+C
• Validation: Comprehensive validation of Fortran constructs during parsing and transformation

Performance Notes

• Generated wrappers maintain performance by using direct pointer passing for derived types
• Array handling is optimized for NumPy integration
• Minimal Python overhead for Fortran function calls
• Supports both allocatable and automatic arrays efficiently

Limitations

• Pointer arguments are not supported
• Arrays of derived types have limited support (1D fixed-length arrays only)
• Intent(out) arrays are converted to intent(in,out) for safety
• Some advanced Fortran 2008+ features may not be fully supported