f90nml

https://f90nml.readthedocs.io/en/latest/
Admin
f90nml is a Python module and command line tool for parsing, generating, and modifying Fortran...
Tokens:6,300
Snippets:101
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install f90nml from source

Source: https://f90nml.readthedocs.io/en/latest/index.html

Cloning the repository and installing locally from the source directory.

```bash
$ git clone https://github.com/marshallward/f90nml.git
$ cd f90nml
$ pip install .
```

--------------------------------

### Local user-level installation

Source: https://f90nml.readthedocs.io/en/latest/index.html

Methods for installing without root privileges using pip or setup.py.

```bash
$ pip install --user .
```

```bash
$ python setup.py install --user
```

```bash
$ python setup.py install --user --prefix=
```

--------------------------------

### Install pycodestyle

Source: https://f90nml.readthedocs.io/en/latest/_sources/contributing.rst.txt

Install the pycodestyle tool via pip to check code formatting.

```bash
$ pip install pycodestyle
```

--------------------------------

### Install f90nml via pip

Source: https://f90nml.readthedocs.io/en/latest/index.html

Standard installation method using the Python package manager.

```bash
$ pip install f90nml
```

--------------------------------

### Install f90nml on Arch Linux

Source: https://f90nml.readthedocs.io/en/latest/index.html

Installation via the Arch User Repository (AUR).

```bash
$ git clone https://aur.archlinux.org/python-f90nml.git
$ cd python-f90nml
$ makepkg -sri
```

--------------------------------

### Install f90nml with YAML support

Source: https://f90nml.readthedocs.io/en/latest/index.html

Installing the package with the optional YAML extras dependency.

```bash
$ pip install f90nml[yaml]
```

```bash
$ pip install --user .[yaml]
```

--------------------------------

### Namelist configuration file

Source: https://f90nml.readthedocs.io/en/latest/cli.html

The example config.nml file used for demonstration purposes.

```fortran
&config_nml
input = 'wind.nc'
steps = 864
layout = 8, 16      ! (X, Y)
visc = 1e-4         ! m2 s-1
use_biharmonic = .false.
/
```

--------------------------------

### Define Namelist with Vectors

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Example of a Fortran 90 namelist file containing vectors with explicit start indices.

```fortran
&vec_nml
    a = 1, 2, 3
    b(0:2) = 0, 1, 2
    c(3:5) = 3, 4, 5
    d(:,:) = 1, 2, 3, 4
/
```

--------------------------------

### Command line output example

Source: https://f90nml.readthedocs.io/en/latest/index.html

The resulting namelist content after applying command line modifications.

```fortran
&config_nml
   input = 'wind.nc'
   steps = 432
   layout = 8, 16
   visc = 1.0e-4
   use_biharmonic = .false.
/
```

--------------------------------

### Configure Default Start Index

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Adjust the default starting index for vectors to handle ambiguous namelist assignments.

```python
>>> parser = f90nml.Parser()
>>> parser.default_start_index = 1
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[1, 2, 3, 4, 5]
```

```python
>>> parser.default_start_index = 0
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[1, 2, None, 3, 4, 5]
```

--------------------------------

### Define a sample Fortran namelist

Source: https://f90nml.readthedocs.io/en/latest/index.html

Example content of a Fortran namelist file named sample.nml.

```fortran
&config_nml
   input = 'wind.nc'
   steps = 864
   layout = 8, 16
   visc = 1.0e-4
   use_biharmonic = .false.
/
```

--------------------------------

### Define Global Start Index

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Set an explicit start index for all vectors in the namelist.

```fortran
&idx_nml
   v(3:5) = 3, 4, 5
/
```

```python
>>> parser = f90nml.Parser()
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[3, 4, 5]
```

```python
>>> parser.global_start_index = 1
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[None, None, 3, 4, 5]
```

--------------------------------

### Access Vector Start Indices

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Retrieves the start index configuration for vectors within a loaded namelist.

```python
>>> import f90nml
>>> nml = f90nml.read('vec.nml')
>>> nml['vec_nml'].start_index
{'b': [0], 'c': [3], 'd': [None, None]}
```

--------------------------------

### Check f90nml version

Source: https://f90nml.readthedocs.io/en/latest/_sources/contributing.rst.txt

Use this to report the installed version of f90nml when submitting bug reports.

```python
>>> import f90nml
>>> f90nml.__version__
'1.1'
```

--------------------------------

### get(key, default=None)

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Retrieves a value from the namelist by key.

```APIDOC
## get(key, default=None)

### Description
Return the value for key if key is in the Namelist, else default.

### Parameters
- **key** (str) - Required - The key to look up.
- **default** (any) - Optional - The value to return if the key is not found.
```

--------------------------------

### Defining Vector Indexing in Fortran Namelists

Source: https://f90nml.readthedocs.io/en/latest/_sources/notes.rst.txt

Demonstrates how vector assignment in a namelist depends on the starting index defined in the Fortran source.

```fortran
&idx_nml
   v(1:2) = 5, 5
/
```

```fortran
integer, dimension :: v(1:4)  ! Read as v = (5, 5, -, -)
integer, dimension :: v(0:3)  ! Read as v = (-, 5, 5, -)
```

--------------------------------

### Define Namelist Indexing

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Example namelist file content demonstrating ambiguous array indices.

```fortran
&idx_nml
    v(3:5) = 3, 4, 5
    v = 1, 2
/
```

--------------------------------

### Defining Vector Indices in Namelists

Source: https://f90nml.readthedocs.io/en/latest/notes.html

Example of explicit vector indexing in a Fortran namelist.

```fortran
&idx_nml
   v(1:2) = 5, 5
/
```

--------------------------------

### Representing Derived Types in Namelists

Source: https://f90nml.readthedocs.io/en/latest/notes.html

Example of a Fortran namelist using nested derived types.

```fortran
&dtype_nml
   a%b%c = 1
/
```

--------------------------------

### Mapping Derived Types to Python Dictionaries

Source: https://f90nml.readthedocs.io/en/latest/notes.html

The resulting Python dictionary structure for the nested derived type example.

```python
nml = {
   'dtype_nml': {
      'a': {
         'b': {
            'c': 1
         }
      }
   }
}
```

--------------------------------

### Check Python version

Source: https://f90nml.readthedocs.io/en/latest/_sources/contributing.rst.txt

Use this to report the system's Python version and build details.

```python
>>> import sys
>>> print(sys.version)
3.6.8 (default, Apr 25 2019, 21:02:35)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-36)]
```

--------------------------------

### Use JSON as input

Source: https://f90nml.readthedocs.io/en/latest/cli.html

JSON and YAML files can be used as input, with format inferred by extension.

```bash
$ f90nml out.json
```

```fortran
&config_nml
    input = 'wind.nc'
    layout = 8, 16
    steps = 864
    use_biharmonic = .false.
    visc = 0.0001
/
```

--------------------------------

### Write Namelist to File

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Demonstrates how to write a loaded namelist object to a Fortran 90 file.

```python
>>> nml = f90nml.read('input.nml')
>>> nml.write('out.nml')
```

--------------------------------

### Run project tests

Source: https://f90nml.readthedocs.io/en/latest/_sources/contributing.rst.txt

Execute the test suite to ensure code changes do not break existing functionality.

```bash
$ python setup.py test
```

--------------------------------

### write(nml_path, force=False, sort=False)

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Writes the Namelist to a Fortran 90 namelist file.

```APIDOC
## write(nml_path, force=False, sort=False)

### Description
Write Namelist to a Fortran 90 namelist file.

### Parameters
- **nml_path** (str) - Required - The file path to write to.
- **force** (bool) - Optional - Whether to force the write.
- **sort** (bool) - Optional - Whether to sort the output.
```

--------------------------------

### Save to new file

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Redirect the output to a new file.

```bash
$ f90nml -v steps=432 config.nml out.nml
```

--------------------------------

### Check PEP8 compliance

Source: https://f90nml.readthedocs.io/en/latest/_sources/contributing.rst.txt

Run pycodestyle to verify that code changes adhere to PEP8 standards.

```bash
$ pycodestyle f90nml
```

--------------------------------

### f90nml.write

Source: https://f90nml.readthedocs.io/en/latest/_sources/usage.rst.txt

Writes a Namelist object to a file.

```APIDOC
## f90nml.write(nml, nml_path, force=False)

### Description
Writes the contents of a Namelist object to the specified file path.

### Parameters
- **nml** (Namelist) - Required - The Namelist object to write.
- **nml_path** (str) - Required - The destination file path.
- **force** (bool) - Optional - Whether to overwrite an existing file.
```

--------------------------------

### Display formatted namelist

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Display the contents of a namelist file in a formatted manner.

```bash
$ f90nml config.nml
```

```fortran
&config_nml
    input = 'wind.nc'
    steps = 864
    layout = 8, 16
    visc = 0.0001
    use_biharmonic = .false.
/
```

--------------------------------

### Write Namelist to Disk

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Save namelist data to a file, with options for overwriting and sorting keys.

```python
>>> with open(nml_path, 'w') as nml_file:
>>>     f90nml.write(nml, nml_file)
```

```python
>>> f90nml.write(nml, 'data.nml')
```

```python
>>> nml.write('data.nml')
```

```python
>>> nml.write('data.nml', force=True)
```

```python
>>> nml.write('data.nml', sort=True)
```

--------------------------------

### f90nml.read

Source: https://f90nml.readthedocs.io/en/latest/_sources/usage.rst.txt

Reads a Fortran namelist file and returns a Namelist object.

```APIDOC
## f90nml.read(nml_path)

### Description
Reads a Fortran namelist file from the specified path and returns a Namelist object containing the parsed data.

### Parameters
- **nml_path** (str) - Required - The file path to the namelist file.
```

--------------------------------

### Infer format from extension

Source: https://f90nml.readthedocs.io/en/latest/cli.html

The output format is automatically inferred from the file extension.

```bash
$ f90nml -g config_nml -v steps=432 config.nml out.json
```

```bash
$ f90nml -g config_nml -v steps=432 config.nml out.yaml
```

--------------------------------

### f90nml.parser.Parser.read

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Parses a Fortran namelist file and stores the contents.

```APIDOC
## f90nml.parser.Parser.read(nml_fname, nml_patch_in=None, patch_fname=None)

### Description
Parses a Fortran namelist file and returns the contents as a Namelist object.

### Parameters
- **nml_fname** (str) - Required - The path to the namelist file.
- **nml_patch_in** (dict) - Optional - A dictionary of values to patch into the namelist.
- **patch_fname** (str) - Optional - The path to a file containing patch values.

### Example
```python
parser = f90nml.Parser()
data_nml = parser.read('data.nml')
```
```

--------------------------------

### Patch Namelist Files

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Create a new namelist by applying a dictionary of changes to an existing file.

```python
>>> f90nml.patch('data.nml', nml_patch, 'patched_data.nml')
```

```python
>>> parser = f90nml.Parser()
>>> nml = parser.read('data.nml', nml_patch, 'patched_data.nml')
```

--------------------------------

### Parse Namelist String

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Parse a string containing Fortran namelist data.

```python
>>> parser = f90nml.Parser()
>>> data_nml = parser.reads('&data_nml x=1 y=2 /')
```

--------------------------------

### Read Fortran Namelist Files

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Parse namelist content from either a file object or a file path.

```python
>>> with open(nml_path) as nml_file:
>>>     nml = f90nml.read(nml_file)
```

```python
>>> nml = f90nml.read(nml_path)
```

```python
>>> parser = f90nml.Parser()
>>> nml = parser.read(nml_file)
```

--------------------------------

### Command line interface usage

Source: https://f90nml.readthedocs.io/en/latest/index.html

Modify namelist values directly from the shell.

```bash
$ f90nml config.nml -g config_nml -v steps=432
```

--------------------------------

### Configure Custom Comment Tokens

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Add non-standard comment tokens to the parser to support specific Fortran preprocessing.

```python
>>> parser = f90nml.Parser()
>>> parser.comment_tokens += '#'
>>> nml = parser.read('sample.nml')
```

--------------------------------

### Write to a file object

Source: https://f90nml.readthedocs.io/en/latest/index.html

Save the namelist object to an open file handle.

```python
with open('target.nml') as nml_file:
   nml.write(nml_file)
```

--------------------------------

### Modify and write a namelist

Source: https://f90nml.readthedocs.io/en/latest/index.html

Update values in the dictionary and save the changes to a new file.

```python
nml['config_nml']['steps'] = 432
nml.write('new_sample.nml')
```

--------------------------------

### Represented namelist dictionary

Source: https://f90nml.readthedocs.io/en/latest/index.html

The resulting Python dictionary structure after parsing the sample namelist.

```python
nml = {
    'config_nml': {
        'input': 'wind.nc',
        'steps': 864,
        'layout': [8, 16],
        'visc': 0.0001,
        'use_biharmonic': False
    }
}
```

--------------------------------

### Patch existing file

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Modify the file in-place while preserving comments.

```bash
$ f90nml -g config_nml -v steps=432 -p config.nml
```

```fortran
&config_nml
input = 'wind.nc'
steps = 432
layout = 8, 16      ! (X, Y)
visc = 1e-4         ! m2 s-1
use_biharmonic = .false.
/
```

--------------------------------

### f90nml.parser.Parser.reads

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Parses a Fortran namelist string and returns an equivalent Namelist object.

```APIDOC
## f90nml.parser.Parser.reads(nml_string)

### Description
Parses a string containing Fortran namelist data and returns a Namelist object.

### Parameters
- **nml_string** (str) - Required - The namelist data as a string.

### Example
```python
parser = f90nml.Parser()
data_nml = parser.reads('&data_nml x=1 y=2 /')
```
```

--------------------------------

### Convert to JSON

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Convert namelist data to JSON format.

```bash
$ f90nml -g config_nml -v steps=432 config.nml -f json
```

```json
{
    "config_nml": {
        "input": "wind.nc",
        "steps": 432,
        "layout": [
            8,
            16
        ],
        "visc": 0.0001,
        "use_biharmonic": false
    }
}
```

--------------------------------

### Representing Derived Types in f90nml

Source: https://f90nml.readthedocs.io/en/latest/_sources/notes.rst.txt

Shows how a nested Fortran namelist structure is represented as a nested dictionary in Python.

```fortran
&dtype_nml
   a%b%c = 1
/
```

```python
nml = {
   'dtype_nml': {
      'a': {
         'b': {
            'c': 1
         }
      }
   }
}
```

--------------------------------

### Read a namelist file

Source: https://f90nml.readthedocs.io/en/latest/index.html

Use the read function to parse a namelist file into a Python dictionary.

```python
import f90nml
nml = f90nml.read('sample.nml')
```

--------------------------------

### create_cogroup(group_name)

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Converts an existing namelist group to a cogroup.

```APIDOC
## create_cogroup(group_name)

### Description
Convert an existing namelist group to a cogroup.

### Parameters
- **group_name** (str) - Required - The name of the group to convert.
```

--------------------------------

### Apply a namelist patch

Source: https://f90nml.readthedocs.io/en/latest/index.html

Use the patch function to update specific values while preserving comments and formatting.

```python
patch_nml = {'config_nml': {'visc': 1e-6}}
f90nml.patch('sample.nml', patch_nml, 'new_sample.nml')
```

--------------------------------

### f90nml.patch

Source: https://f90nml.readthedocs.io/en/latest/_sources/usage.rst.txt

Patches an existing namelist file with new values.

```APIDOC
## f90nml.patch(nml_path, patch_dict, out_path=None)

### Description
Updates values in an existing namelist file based on a dictionary of changes.

### Parameters
- **nml_path** (str) - Required - Path to the original namelist file.
- **patch_dict** (dict) - Required - Dictionary containing the values to update.
- **out_path** (str) - Optional - Path to save the patched file; if not provided, the original file is overwritten.
```

--------------------------------

### Set multiple variables

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Update multiple variables using comma-separated values or repeated flags.

```bash
$ f90nml -g config_nml -v steps=432,date='19960101' config.nml
```

```bash
$ f90nml -g config_nml -v steps=432 -v date='19960101' config.nml
```

```fortran
&config_nml
    input = 'wind.nc'
    steps = 432
    layout = 8, 16
    visc = 0.0001
    use_biharmonic = .false.
    date = 19960101
/
```

--------------------------------

### Read from a file object

Source: https://f90nml.readthedocs.io/en/latest/index.html

Pass an open file object to the read function instead of a filename.

```python
with open('sample.nml') as nml_file:
    nml = f90nml.read(nml_file)
```

--------------------------------

### patch(nml_patch)

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Updates the namelist from another partial or full namelist.

```APIDOC
## patch(nml_patch)

### Description
Update the namelist from another partial or full namelist. This updates the values within a section rather than replacing the section entirely.

### Parameters
- **nml_patch** (dict) - Required - The namelist data to patch into the current object.
```

--------------------------------

### Implicit group selection

Source: https://f90nml.readthedocs.io/en/latest/cli.html

When the group is not specified, the first group in the file is assumed.

```bash
$ f90nml -v steps=432 config.nml
```

```text
f90nml: warning: Assuming variables are in group 'config_nml'.
&config_nml
    input = 'wind.nc'
    steps = 432
    layout = 8, 16
    visc = 0.0001
    use_biharmonic = .false.
/
```

--------------------------------

### add_cogroup(key, val)

Source: https://f90nml.readthedocs.io/en/latest/usage.html

Appends a duplicate group to the Namelist as a new group.

```APIDOC
## add_cogroup(key, val)

### Description
Append a duplicate group to the Namelist as a new group.

### Parameters
- **key** (str) - Required - The name of the group to add.
- **val** (any) - Required - The value associated with the group.
```

--------------------------------

### Modify namelist variables

Source: https://f90nml.readthedocs.io/en/latest/cli.html

Update specific variables within a namelist group.

```bash
$ f90nml -g config_nml -v steps=432 config.nml
```

```fortran
&config_nml
    input = 'wind.nc'
    steps = 432
    layout = 8, 16
    visc = 0.0001
    use_biharmonic = .false.
/
```
Tokens:
Raw