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
```