cape.filecntl.namelist2: Fortran namelists with repeat sections

This is a module built off of the cape.filecntl.FileCntl module customized for manipulating Fortran namelists. Such files are split into sections which are called “name lists.” Each name list has syntax similar to the following.

$FLOINP
    FSMACH = 4.0,
    ALPHA = 1.0,
    BETA = 0.0,
    $END

and this module is designed to recognize such sections. The main feature of this module is methods to set specific properties of a namelist file, for example the Mach number or CFL number.

The difference between this module and cape.filecntl.namelist.Namelist is that this module can support multiple namelists with the same title. This is particularly important for Overflow, which has GRDNAM, BCINP, and other sections defined for each structured grid. These modules should be combined as the differing namelist syntaxes are actually part of one file convention.

This function provides a class Namelist2 that can both read and set values in the namelist. The key functions are

The conversion from namelist text to Python is handled by Namelist2.ConvertToText(), and the reverse is handled by Namelist2.ConvertToVal(). Conversions cannot quite be performed just by the Python functions print() and eval() because delimiters are not used in the same fashion. Some of the conversions are tabulated below.

Namelist

Python

val = "text"

val = "text"

val = 'text'

val = 'text'

val = 3

val = 3

val = 3.1

val = 3.1

val = .false.

val = False

val = .true.

val = True

val = .f.

val = False

val = .t.

val = True

val = 10.0 20.0

val = [10.0, 20.0]

val = 1, 100

val = [1, 100]

val(1) = 1.2

val = [1.2, 1.5]

val(2) = 1.5

val = _mach_

val = "_mach_"

In most cases, the Namelist will try to interpret invalid values for any namelist entry as a string with missing quotes. The reason for this is that users often create template namelist with entries like _mach_ that can be safely replaced with appropriate values using sed commands or something similar.

See also:

class cape.filecntl.namelist2.Namelist2(fname='overflow.inp')

File control class for Fortran namelists with duplicate sections

Call:
>>> nml = Namelist2()
>>> nml = Namelist2(fname)
Inputs:
fname: str

Name of namelist file to read, defaults to 'overflow.inp'

Outputs:
nml: cape.filecntl.namelist2.Namelist2

Namelist file control instance

nml.ibeg: np.ndarray[int]

Indices of lines starting each namelist/section

nml.iend: np.ndarray[int]

Indices of lines ending each namelist/section

nml.Groups: np.ndarray[str]

List of namelist/section/group titles

Versions:

  • 2016-02-01 @ddalle: Version 1.0

ApplyDict(opts)

Apply a whole dictionary of settings to the namelist

Call:
>>> nml.ApplyDict(opts)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Old-style namelist inerface

opts: dict

Dictionary of namelist options

Versions:

  • 2016-02-01 @ddalle: Version 1.0

ConvertToText(v)

Convert a scalar value to text to write in the namelist file

Call:
>>> val = nml.ConvertToText(v)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

File control instance for old-style Fortran namelist

v: str | int | float | list

Evaluated value of the text

Outputs:
val: str | unicode

Text of the value from file

Versions:

  • 2015-10-16 @ddalle: Version 1.0

ConvertToVal(val)

Convert text to Python based on a series of rules

Call:
>>> v = nml.ConvertToVal(val)
Inputs:
nml: cape.filecntl.namelist.Namelist

File control instance for fun3d.nml

val: str | unicode

Text of the value from file

Outputs:
v: str | int | float | bool | list

Evaluated value of the text

Versions:

  • 2015-10-16 @ddalle: Version 1.0

  • 2016-01-29 @ddalle: Added boolean shortcuts, .T.

GetGroupByName(grp, igrp=0)

Get index of group with a specific name

Call:
>>> i = nml.GetGroupByName(grp, igrp=0)
Inputs:
nml: cape.name.ist2.Namelist2

Interface to namelist with repeated lists

grp: str

Name of namelist group

igrp: {0} | int

If multiple matches, return match number igrp

Outputs:
i: int | np.ndarray[int]

Group index of requested match

Versions:

  • 2016-01-31 @ddalle: Version 1.0

GetKeyFromGroupIndex(igrp, key, i=None)

Get the value of a key from a specific section

Call:
>>> v = nml.GetKeyFromGroupIndex(igrp, key, i=i)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

key: str

Name of the key to search for

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Outputs:
v: str | int | float | list

Evaluated value of the text for this key

Versions:

  • 2016-01-29 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Added parameter index

GetKeyFromGroupName(grp, key, igrp=0, i=None)

Get the value of a key from a section by group name

Call:
>>> v = nml.GetKeyFromGroupName(grp, key, igrp=0, i=None)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Old-style Fortran namelist interface

grp: str

Group name to search for

key: str

Name of key to search for

igrp: int

If multiple sections have same name, use match number igrp

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Outputs:
v: any

Converted value

Versions:

  • 2016-01-31 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Added parameter index

GetKeyFromLine(line, key, i=None)

Read the value of a key from a line

Call:
>>> q, val = nml.GetKeyFromLine(line, key, i=None)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

line: str

A line of text that may or may not contain the value of key

key: str

Name of key

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Outputs:
q: bool

Whether or not the key was found in the line

val: str | float | int | bool

Value of the key, if found

Versions:

  • 2016-01-29 @ddalle: Version 1.0

  • 2016-01-30 @ddalle: Case-insensitive

  • 2016-08-29 @ddalle: Added index capability

InsertGroup(igrp, grp)

Insert a group as group number igrp

Call:
>>> nml.InsertGroup(igrp, grp)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

igrp: int

Index of location at which to insert group

grp: str

Name of the group to insert

Versions:

  • 2016-02-01 @ddalle: Version 1.0

PopLine(line)

Read the left-most key from line and return rest of line

Call:
>>> txt, key, val, i = nml.PopLine(line)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

line: str

One line of namelist text

Outputs:
txt: str

Remaining text in line after first key has been read

key: str

Name of first key read from line

val: None | str

Raw (unconverted) value of key

i: {None} | ':" | int

Vector index if specified

Versions:

  • 2016-01-29 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Version 1.1

    • Add indices, e.g. BCPAR(2)

ReadGroupIndex(igrp)

Read group igrp and return a dictionary

The output is a dict such as the following

{'FSMACH': '0.8', 'ALPHA': '2.0'}

If a parameter has an index specification, such as "PAR(2) = 1.0", the dictionary will have the following format for such keys.

{'PAR': {2: 1.0}}

Call:
>>> d = nml.ReadGroupIndex(igrp)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

igrp: int

Group index to read

Outputs:
d: dict[str]

Raw (uncoverted) values of the dict

Versions:

  • 2016-01-29 @ddalle: Version 1.0

ReadKeysFromLine(line)

Read zero or more keys from a single text line

Call:
>>> d = nml.ReadKeysFromLine(line)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

line: str

One line from a namelist file

Outputs:
d: dict[str]

Unconverted values of each key

Versions:

  • 2016-01-29 @ddalle: Version 1.0

SetKeyInGroupIndex(igrp, key, val, i=None)

Set the value of a key in a group by index

If the key is not set in the present text, add it as a new line. The contents of the file control’s text (in nml.lines) will be edited, and the list indices will be updated if a line is added.

Call:
>>> nml.SetKeyInGroupIndex(igrp, key, val, i=None)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

File control instance for old-style Fortran namelist

igrp: int

Index of namelist to edit

key: str

Name of key to alter or set

val: any

Value to use for key

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Versions:

  • 2015-01-30 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Added index capability

SetKeyInGroupName(grp, key, val, igrp=0, i=None)

Set the value of a key from a group by name

Call:
>>> nml.SetKeyInGroupName(grp, key, val, igrp=0, i=None)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Old-style Fortran namelist interface

grp: str

Group name to search for

key: str

Name of key to search for

val: any

Converted value

igrp: int

If multiple sections have same name, use match number igrp

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Versions:

  • 2015-01-31 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Added index capability

SetKeyInLine(line, key, val, i=None)

Set the value of a key in a line if the key is already in the line

Call:
>>> q, line = nml.SetKeyInLine(line, key, val, i=None)
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

line: str

A line of text that may or may not contain the value of key

key: str

Name of key

val: str | float | int | bool

Value of the key, if found

i: {None} | ":" | int

Index to use in the namelist, e.g. “BCPAR(i)”

Outputs:
q: bool

Whether or not the key was found in the line

line: str

New version of the line with key reset to val

Versions:

  • 2016-01-29 @ddalle: Version 1.0

  • 2016-08-29 @ddalle: Added index capability

UpdateNamelist()

Update the line indices for each namelist

Call:
>>> nml.UpdateNamelist()
Inputs:
nml: cape.filecntl.namelist2.Namelist2

Interface to namelist with repeated lists

Versions:

  • 2016-01-29 @ddalle: Version 1.0