0
# f90nml
1
2
A comprehensive Python module and command line tool for parsing, writing, and modifying Fortran 90 namelist files. f90nml converts Fortran namelist files into Python dictionary-like objects, enabling seamless integration with Python workflows for scientific computing and configuration management.
3
4
## Package Information
5
6
- **Package Name**: f90nml
7
- **Language**: Python
8
- **Installation**: `pip install f90nml`
9
- **PyPI**: https://pypi.org/project/f90nml/
10
11
## Core Imports
12
13
```python
14
import f90nml
15
```
16
17
For advanced configuration:
18
19
```python
20
from f90nml import Parser, Namelist
21
```
22
23
## Basic Usage
24
25
```python
26
import f90nml
27
28
# Read a namelist file
29
nml = f90nml.read('input.nml')
30
31
# Access values like a dictionary
32
print(nml['config_nml']['steps'])
33
print(nml['config_nml']['use_biharmonic'])
34
35
# Modify values
36
nml['config_nml']['steps'] = 1000
37
nml['config_nml']['visc'] = 1.0e-5
38
39
# Write back to file
40
nml.write('output.nml')
41
42
# Parse namelist string directly
43
nml_str = '&data_nml x=1 y=2 /'
44
nml = f90nml.reads(nml_str)
45
46
# Create patch to modify existing file while preserving formatting
47
patch = {'config_nml': {'steps': 500, 'visc': 2.0e-4}}
48
f90nml.patch('input.nml', patch, 'patched.nml')
49
```
50
51
## Architecture
52
53
f90nml uses a layered architecture designed for flexibility and precision:
54
55
- **Core Functions**: High-level interface for common operations (read, write, patch)
56
- **Namelist Objects**: Dictionary-like containers with Fortran-specific formatting controls
57
- **Parser**: Configurable parsing engine handling Fortran syntax variations and edge cases
58
- **Tokenizer**: Low-level lexical analysis for Fortran namelist syntax
59
- **Type Conversion**: Bidirectional conversion between Fortran and Python data types
60
61
This design enables f90nml to handle complex Fortran namelist features like derived types, multidimensional arrays, start indices, and comment preservation while providing a Pythonic interface.
62
63
## Capabilities
64
65
### Core Parsing and Writing
66
67
High-level functions for reading, writing, and modifying Fortran namelist files with automatic type conversion and format detection.
68
69
```python { .api }
70
def read(nml_path):
71
"""
72
Parse a Fortran namelist file and return its contents.
73
74
Args:
75
nml_path: str or file-like object - Path to namelist file or file object
76
77
Returns:
78
Namelist: Dictionary-like object containing namelist data
79
"""
80
81
def reads(nml_string):
82
"""
83
Parse a Fortran namelist string and return its contents.
84
85
Args:
86
nml_string: str - String containing Fortran namelist data
87
88
Returns:
89
Namelist: Dictionary-like object containing namelist data
90
"""
91
92
def write(nml, nml_path, force=False, sort=False):
93
"""
94
Save a namelist to disk using file path or file object.
95
96
Args:
97
nml: Namelist or dict - Namelist data to write
98
nml_path: str or file-like object - Output file path or file object
99
force: bool - Overwrite existing files (default: False)
100
sort: bool - Sort namelist keys alphabetically (default: False)
101
"""
102
103
def patch(nml_path, nml_patch, out_path=None):
104
"""
105
Create a new namelist based on input namelist and reference dict.
106
107
Args:
108
nml_path: str - Path to original namelist file
109
nml_patch: dict - Dictionary of values to patch
110
out_path: str, optional - Output file path (default: adds ~ suffix)
111
112
Returns:
113
Namelist: Patched namelist object
114
"""
115
```
116
117
[Core Parsing and Writing](./core-parsing.md)
118
119
### Namelist Objects and Formatting
120
121
Dictionary-like container objects with extensive formatting controls for Fortran-compliant output generation.
122
123
```python { .api }
124
class Namelist(OrderedDict):
125
"""Representation of Fortran namelist in Python environment."""
126
127
def __init__(self, *args, default_start_index=None, **kwds): ...
128
def write(self, nml_path, force=False, sort=False): ...
129
def patch(self, nml_patch): ...
130
def todict(self, complex_tuple=False): ...
131
132
# Formatting properties
133
column_width: int
134
default_start_index: int
135
end_comma: bool
136
indent: str
137
uppercase: bool
138
logical_repr: dict
139
```
140
141
[Namelist Objects and Formatting](./namelist-objects.md)
142
143
### Advanced Parser Configuration
144
145
Configurable parsing engine for handling Fortran syntax variations, custom comment tokens, and complex array indexing.
146
147
```python { .api }
148
class Parser:
149
"""Fortran namelist parser with configurable options."""
150
151
def __init__(self): ...
152
def read(self, nml_fname, nml_patch_in=None, patch_fname=None): ...
153
def reads(self, nml_string): ...
154
155
# Configuration properties
156
comment_tokens: str
157
default_start_index: int
158
global_start_index: int
159
row_major: bool
160
sparse_arrays: bool
161
strict_logical: bool
162
```
163
164
[Advanced Parser Configuration](./parser-configuration.md)
165
166
### Utility Functions and Advanced Components
167
168
Low-level utility functions for type conversion, array indexing, and tokenization that provide the foundation for f90nml's robust processing capabilities.
169
170
```python { .api }
171
# Type conversion functions
172
def pyfloat(v_str): ...
173
def pycomplex(v_str): ...
174
def pybool(v_str, strict_logical=True): ...
175
def pystr(v_str): ...
176
177
# Multidimensional array indexing
178
class FIndex:
179
def __init__(self, bounds, first=None): ...
180
def __next__(self): ...
181
182
# Low-level tokenization
183
class Tokenizer:
184
def __init__(self): ...
185
def parse(self, line): ...
186
```
187
188
[Utility Functions and Advanced Components](./utility-functions.md)
189
190
### Command Line Interface
191
192
Shell-based tool for namelist manipulation, format conversion, and integration with scientific computing workflows.
193
194
```bash { .api }
195
f90nml input.nml -g group_name -v variable=value
196
f90nml input.nml -f json > output.json
197
f90nml input.nml -p patch_file.nml -o output.nml
198
```
199
200
[Command Line Interface](./command-line.md)
201
202
## Types
203
204
```python { .api }
205
class Namelist(OrderedDict):
206
"""Dictionary-like container for namelist groups and variables."""
207
208
def __init__(self, *args, default_start_index=None, **kwds): ...
209
def write(self, nml_path, force=False, sort=False): ...
210
def patch(self, nml_patch): ...
211
def todict(self, complex_tuple=False): dict
212
213
class Parser:
214
"""Configurable Fortran namelist parser."""
215
216
def __init__(self): ...
217
def read(self, nml_fname, nml_patch_in=None, patch_fname=None): Namelist
218
def reads(self, nml_string): Namelist
219
220
class Cogroup(list):
221
"""List of Namelist groups which share a common key."""
222
223
def __init__(self, nml, key, *args, **kwds): ...
224
def update(self, args): ...
225
keys: list
226
227
class NmlKey(str):
228
"""String containing internal key for duplicate key handling."""
229
230
def __new__(cls, value='', *args, **kwargs): ...
231
232
class FIndex:
233
"""Column-major multidimensional index iterator."""
234
235
def __init__(self, bounds, first=None): ...
236
def __next__(self): tuple
237
238
class Tokenizer:
239
"""Fortran namelist tokenizer for lexical analysis."""
240
241
def __init__(self): ...
242
def parse(self, line): list
243
244
# Type conversion functions
245
pyfloat(v_str: str) -> float
246
pycomplex(v_str: str) -> complex
247
pybool(v_str: str, strict_logical: bool = True) -> bool
248
pystr(v_str: str) -> str
249
```