0
# f90wrap
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: f90wrap
7
- **Language**: Python
8
- **Installation**: `pip install f90wrap` or `conda install -c conda-forge f90wrap`
9
- **Dependencies**: Python 3.8+, numpy (with f2py), Fortran compiler (gfortran 4.6+ or ifort 12+)
10

11
## Core Imports
12

13
```python
14
import f90wrap
15
```
16

17
For programmatic API usage:
18

19
```python
20
from f90wrap import parser
21
from f90wrap import fortran
22
from f90wrap import transform
23
from f90wrap import f90wrapgen
24
from f90wrap import pywrapgen
25
from f90wrap import codegen
26
from f90wrap.runtime import FortranDerivedType, FortranModule, register_class
27
```
28

29
For command-line tools:
30

31
```python
32
from f90wrap.scripts.main import main as f90wrap_main
33
from f90wrap.scripts.f90doc import main as f90doc_main
34
from f90wrap.scripts.f2py_f90wrap import main as f2py_f90wrap_main
35
```
36

37
## Basic Usage
38

39
### Command-line Usage
40

41
Generate Python wrappers for Fortran source files:
42

43
```bash
44
# Basic wrapper generation
45
f90wrap -m mymodule fortran_source.f90
46

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

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

53
# Generate documentation
54
f90doc fortran_source.f90
55
```
56

57
### Programmatic Usage
58

59
```python
60
import f90wrap.parser as parser
61
import f90wrap.fortran as fortran
62
import f90wrap.transform as transform
63

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

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

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

74
class MyFortranType(FortranDerivedType):
75
    # Generated wrapper code would use this base class
76
    pass
77
```
78

79
## Architecture
80

81
f90wrap follows a multi-stage compilation process:
82

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

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

91
## Capabilities
92

93
### Command-line Tools
94

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

97
```bash { .api }
98
f90wrap -m MODULE F90_FILES [OPTIONS]
99
f90doc F90_FILES [OPTIONS]
100
f2py-f90wrap [F2PY_OPTIONS]
101
```
102

103
[Command-line Tools](./command-line.md)
104

105
### Fortran Parsing and AST
106

107
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.
108

109
```python { .api }
110
def read_files(args, doc_plugin_filename=None): ...
111
class F90File(object): ...
112
class Fortran(object): ...  # Base AST node
113
class Module(Fortran): ...  # Module node
114
class Type(Fortran): ...    # Derived type node
115
```
116

117
[Parsing and AST](./parsing-ast.md)
118

119
### AST Transformation
120

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

123
```python { .api }
124
def transform_to_f90_wrapper(tree, types, callbacks, constructors, destructors, ...): ...
125
def transform_to_py_wrapper(tree, types): ...
126
class FortranTransformer(FortranVisitor): ...
127
```
128

129
[AST Transformation](./transformation.md)
130

131
### Code Generation
132

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

135
```python { .api }
136
class CodeGenerator(object): ...
137
class F90WrapperGenerator(FortranVisitor, CodeGenerator): ...
138
class PythonWrapperGenerator(FortranVisitor, CodeGenerator): ...
139
```
140

141
[Code Generation](./code-generation.md)
142

143
### Runtime Support
144

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

147
```python { .api }
148
class FortranDerivedType(object): ...
149
class FortranDerivedTypeArray(object): ...
150
class FortranModule(object): ...
151
def register_class(object): ...
152
```
153

154
[Runtime Support](./runtime.md)
155

156
### Type Analysis and Utilities
157

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

160
```python { .api }
161
def is_derived_type(typename): ...
162
def f2py_type(type, attributes=None): ...
163
def normalise_type(typename, kind_map): ...
164
```
165

166
[Type System](./type-system.md)
167

168
## Error Handling
169

170
f90wrap provides enhanced error handling capabilities:
171

172
- **Runtime errors**: Fortran routines can raise Python `RuntimeError` exceptions
173
- **Interruption support**: Fortran code can be interrupted with Ctrl+C
174
- **Validation**: Comprehensive validation of Fortran constructs during parsing and transformation
175

176
## Performance Notes
177

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

183
## Limitations
184

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