0
# Command Line Interface
1

2
Shell-based tool for namelist manipulation, format conversion, and integration with scientific computing workflows. The f90nml command line interface provides direct access to namelist functionality from shell scripts and batch processing environments.
3

4
## Capabilities
5

6
### Basic Command Structure
7

8
The f90nml command line tool provides a unified interface for namelist operations.
9

10
```bash { .api }
11
f90nml [OPTIONS] [INPUT_FILE] [OUTPUT_FILE]
12

13
# Core options:
14
-g, --group GROUP          # Specify namelist group to modify
15
-v, --variable VAR=VALUE   # Specify variable to add or modify
16
-p, --patch               # Modify existing namelist as patch
17
-f, --format FORMAT       # Specify output format (json, yaml, nml)
18
--version                 # Show version information
19
```
20

21
**Usage Examples:**
22

23
```bash
24
# Display help
25
f90nml --help
26

27
# Show version
28
f90nml --version
29

30
# Simple file reading (outputs to stdout)
31
f90nml input.nml
32
```
33

34
### Variable Modification
35

36
Modify individual variables within namelist groups directly from the command line.
37

38
```bash { .api }
39
f90nml INPUT_FILE -g GROUP_NAME -v VARIABLE=VALUE [OUTPUT_FILE]
40

41
# Multiple variables:
42
f90nml INPUT_FILE -g GROUP_NAME -v VAR1=VALUE1 -v VAR2=VALUE2
43
```
44

45
**Usage Examples:**
46

47
```bash
48
# Modify single variable
49
f90nml config.nml -g run_params -v timesteps=1000
50

51
# Modify multiple variables in same group
52
f90nml config.nml -g run_params -v timesteps=1000 -v dt=0.01
53

54
# Save to specific output file
55
f90nml input.nml -g physics -v gravity=9.81 modified.nml
56

57
# Modify different groups (requires multiple calls)
58
f90nml temp.nml -g group1 -v param1=100 temp2.nml
59
f90nml temp2.nml -g group2 -v param2=200 final.nml
60
```
61

62
### Format Conversion
63

64
Convert between namelist and other configuration formats for interoperability.
65

66
```bash { .api }
67
# Output formats:
68
f90nml INPUT_FILE -f json    # Convert to JSON
69
f90nml INPUT_FILE -f yaml    # Convert to YAML  
70
f90nml INPUT_FILE -f nml     # Keep as namelist (default)
71

72
# Input format auto-detected from extension:
73
# .json  -> JSON input
74
# .yaml  -> YAML input  
75
# .nml   -> Namelist input (default)
76
```
77

78
**Usage Examples:**
79

80
```bash
81
# Convert namelist to JSON
82
f90nml config.nml -f json > config.json
83

84
# Convert namelist to YAML
85
f90nml config.nml -f yaml > config.yaml
86

87
# Convert JSON back to namelist
88
f90nml config.json config.nml
89

90
# Convert with modification
91
f90nml input.nml -g params -v value=42 -f json > modified.json
92

93
# Pipeline processing
94
f90nml input.nml -f json | jq '.params.timesteps = 2000' | f90nml -f nml > output.nml
95
```
96

97
### Patch Mode Operations
98

99
Apply modifications while preserving original file structure, comments, and formatting.
100

101
```bash { .api }
102
f90nml INPUT_FILE -p -g GROUP -v VARIABLE=VALUE [OUTPUT_FILE]
103

104
# Patch mode preserves:
105
# - Original formatting and indentation
106
# - Comments and whitespace
107
# - Variable ordering
108
# - Only modifies specified values
109
```
110

111
**Usage Examples:**
112

113
```bash
114
# Patch single value (creates input.nml~)
115
f90nml config.nml -p -g run_config -v timesteps=2000
116

117
# Patch with specific output
118
f90nml config.nml -p -g run_config -v timesteps=2000 patched.nml
119

120
# Patch multiple variables
121
f90nml model.nml -p -g physics -v gravity=9.81 -v viscosity=1e-5 updated.nml
122

123
# Patch with format conversion
124
f90nml input.nml -p -g params -v debug=.true. -f json > patched.json
125
```
126

127
### Advanced Usage Patterns
128

129
Complex operations combining multiple features for workflow automation.
130

131
**Parameter Sweeps:**
132
```bash
133
# Script for parameter sweep
134
for timesteps in 100 500 1000 2000; do
135
    f90nml base.nml -g run_config -v timesteps=$timesteps run_${timesteps}.nml
136
done
137
```
138

139
**Configuration Management:**
140
```bash
141
# Create environment-specific configs
142
f90nml base.nml -g io -v output_dir="/scratch/prod" production.nml
143
f90nml base.nml -g io -v output_dir="/tmp/test" -g debug -v verbose=.true. test.nml
144
```
145

146
**Format Pipeline:**
147
```bash
148
# Convert, modify, convert back
149
f90nml config.nml -f json \
150
  | jq '.run_params.timesteps = 5000' \
151
  | f90nml -f nml > modified.nml
152
```
153

154
**Batch Processing:**
155
```bash
156
# Process multiple files
157
for file in configs/*.nml; do
158
    basename=$(basename "$file" .nml)
159
    f90nml "$file" -g params -v threads=8 "modified_${basename}.nml"
160
done
161
```
162

163
### Error Handling
164

165
Common error scenarios and their command line behavior:
166

167
```bash
168
# File not found
169
f90nml nonexistent.nml
170
# Output: f90nml: error: Cannot read file 'nonexistent.nml'
171
# Exit code: 1
172

173
# Invalid group name
174
f90nml config.nml -g nonexistent_group -v param=value
175
# Output: Adds new group 'nonexistent_group' with param=value
176

177
# Invalid variable syntax
178
f90nml config.nml -g params -v "invalid syntax"
179
# Output: f90nml: error: Variable must be in format 'NAME=VALUE'
180
# Exit code: 1
181

182
# Unsupported format
183
f90nml config.nml -f xml
184
# Output: f90nml: error: format must be one of: json, yaml, nml
185
# Exit code: 1
186

187
# Write permission error
188
f90nml config.nml -g params -v test=1 /read-only/output.nml
189
# Output: f90nml: error: Permission denied: '/read-only/output.nml'
190
# Exit code: 1
191
```
192

193
### Integration Examples
194

195
Real-world examples of command line integration with scientific workflows.
196

197
**HPC Job Submission:**
198
```bash
199
#!/bin/bash
200
#SBATCH --job-name=simulation
201
#SBATCH --ntasks=64
202

203
# Modify namelist for this job
204
f90nml base_config.nml \
205
  -g parallel -v nprocs=64 \
206
  -g io -v output_dir="$SCRATCH/run_$SLURM_JOB_ID" \
207
  job_config.nml
208

209
# Run simulation
210
mpirun -n 64 ./simulation job_config.nml
211
```
212

213
**Docker Configuration:**
214
```dockerfile
215
FROM scientific/base
216
COPY base_config.nml /app/
217
WORKDIR /app
218

219
# Configure at runtime
220
ENTRYPOINT ["sh", "-c", "f90nml base_config.nml -g runtime -v threads=$THREADS -g io -v data_dir=$DATA_DIR config.nml && ./simulation config.nml"]
221
```
222

223
**CI/CD Pipeline:**
224
```yaml
225
# .github/workflows/test.yml
226
steps:
227
  - name: Generate test configurations
228
    run: |
229
      f90nml base.nml -g test -v mode=fast -g io -v output_dir=./test_output fast_test.nml
230
      f90nml base.nml -g test -v mode=thorough -g io -v output_dir=./full_test thorough_test.nml
231
  
232
  - name: Run tests
233
    run: |
234
      ./run_tests.sh fast_test.nml
235
      ./run_tests.sh thorough_test.nml
236
```
237

238
**Configuration Templating:**
239
```bash
240
# generate_config.sh
241
#!/bin/bash
242
TEMPLATE="template.nml"
243
OUTPUT="$1"
244
ENVIRONMENT="$2"
245

246
case "$ENVIRONMENT" in
247
  "production")
248
    f90nml "$TEMPLATE" \
249
      -g runtime -v debug=.false. \
250
      -g io -v output_dir="/data/production" \
251
      -g performance -v optimization=high \
252
      "$OUTPUT"
253
    ;;
254
  "development")
255
    f90nml "$TEMPLATE" \
256
      -g runtime -v debug=.true. \
257
      -g io -v output_dir="/tmp/dev" \
258
      -g performance -v optimization=none \
259
      "$OUTPUT"
260
    ;;
261
esac
262
```
263

264
## Exit Codes
265

266
The command line tool uses standard exit codes for automation:
267

268
- **0**: Success
269
- **1**: General error (file not found, invalid syntax, etc.)
270
- **2**: Invalid command line arguments
271
- **3**: Permission denied
272
- **4**: Unsupported format or operation
273

274
## YAML Support
275

276
YAML format support requires the PyYAML library:
277

278
```bash
279
# Install with YAML support
280
pip install f90nml[yaml]
281

282
# Use YAML format
283
f90nml config.nml -f yaml > config.yaml
284
f90nml config.yaml -f nml > config.nml
285
```
286

287
Without PyYAML installed:
288
```bash
289
f90nml config.nml -f yaml
290
# Output: f90nml: error: YAML support requires PyYAML library
291
# Exit code: 1
292
```