NAMELIST I/O
A namelist is a named group of variables and a file format for them. One write statement produces a file that names every value, one read statement takes it back, and a person can edit the file between the two without a program to help: the form was designed for configuration, and it is the shortest way to give a Fortran program parameters it reads at start-up.
A NAMELIST group
namelist /config/ steps, dt, tol, title declares a group called config that holds four variables. The declaration comes after the variables themselves, and it is the only place the group is defined: every read and write names the group, not the variables.
The file namelist.f90 writes the group, echoes the file as text, and reads it back:
program namelist_demo
implicit none
integer :: u, ios
character(len=80) :: line
integer :: steps
real :: dt, tol
character(len=20) :: title
namelist /config/ steps, dt, tol, title
steps = 100
dt = 0.01
tol = 1.0e-6
title = "run one"
open (newunit=u, file="cfg.nml", status="replace", action="write")
write (u, nml=config)
close (u)
open (newunit=u, file="cfg.nml", status="old", action="read")
do
read (u, '(a)', iostat=ios) line
if (ios /= 0) exit
print '(a,a)', "| ", trim(line)
end do
close (u)
open (newunit=u, file="cfg.nml", status="old", action="read")
read (u, nml=config, iostat=ios)
close (u)
print *, "ios :", ios
print *, "steps :", steps
print *, "dt :", dt
print *, "tol :", tol
print *, "title : [", trim(title), "]"
end program namelist_demo
gfortran -Wall -Wextra -std=f2018 namelist.f90 -o namelist
./namelist
| &CONFIG
| STEPS=100 ,
| DT= 9.99999978E-03,
| TOL= 9.99999997E-07,
| TITLE="run one ",
| /
ios : 0
steps : 100
dt : 9.99999978E-03
tol : 9.99999997E-07
title : [run one]
The group opens with &CONFIG and closes with a slash, and each line is one variable with its value and a trailing comma. The name is upper case because that is how gfortran writes it, and the values look strange because 0.01 is not exactly representable in a 32-bit real: the file holds the decimal form of the value that is actually stored, which is why reading it back gives the same number and not a rounded one.
Writing the file
write (u, nml=config) is the whole write: no format, no list. That makes it the natural way to save a set of parameters at the end of a run and read them again at the start of the next, and it is what a program writes when it wants a configuration file a person can look at without a manual.
The file is not meant to be a general data format. Its layout varies between compilers, its numbers are written in the compiler form, and a value of a derived type is written only when the compiler supports the whole component tree. For a program that reads its own file on the same compiler, none of that matters.
Reading it back
read (u, nml=config) matches the names in the file to the variables of the group and takes the values in any order. A name that is not in the group is an error, a variable that is not in the file keeps the value it had, and the read stops at the slash. That last rule is what makes a namelist a configuration language rather than a data dump: a file may name one parameter and leave the rest to the program.
A file edited by hand
The program below writes a namelist file with a plain formatted write, then reads it as a namelist. The file names only two of the four variables, and the other two keep what the program set before the read.
program edit_demo
implicit none
integer :: u, steps
real :: dt, tol
character(len=20) :: title
namelist /config/ steps, dt, tol, title
steps = 100
dt = 0.01
tol = 1.0e-6
title = "run one"
open (newunit=u, file="edit.nml", status="replace", action="write")
write (u, '(a)') "&config"
write (u, '(a)') " steps = 250"
write (u, '(a)') " title = 'edited run'"
write (u, '(a)') "/"
close (u)
open (newunit=u, file="edit.nml", status="old", action="read")
read (u, nml=config)
close (u)
print *, "steps :", steps
print *, "dt :", dt
print *, "tol :", tol
print *, "title : [", trim(title), "]"
end program edit_demo
gfortran -Wall -Wextra -std=f2018 edit.f90 -o edit
./edit
steps : 250
dt : 9.99999978E-03
tol : 9.99999997E-07
title : [edited run]
Steps and the title came from the file; dt and tol are the values the program assigned before the read, printed in the same form as the written file because the number is the same. A message such as steps = 250 is the whole syntax: a name, an equals sign and a value, so a person can edit a run without opening the source.
What a namelist cannot do
A namelist has no notion of a required value: a file that names nothing is a valid read and every variable keeps its program value, so a program that must have a parameter tests it after the read. A group name that does not match stops the read with an error, and a name inside the group that the program does not know is an error too, which is the one case where a typo is reported rather than ignored.
Arrays belong in a group as a whole, and a read may give part of an array with a repeat count or a subscript. What the form cannot express is a structure: there are no sections, no includes and no conditions. A configuration that needs those is a file of records parsed by hand, or a format of the previous lessons, and the namelist stays the tool for a flat set of parameters.
Exercises
- Add a logical verbose to the group and write the file again. How is a logical written?
- Read a file whose group is called &settings with the group of the program. What does the read report?
- Put a value the program does not declare in the file, such as colour = 3. What happens, and is the value ignored?
- Write a file that names only dt and read it. Which of the four variables change?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does a NAMELIST declaration do?
Answer
Names a group of variables that a read or write can transfer as a unit
The group is the unit of a namelist transfer.
-
What does
write (u, nml=config)write?Answer
The whole group, with the name and value of each variable
NML= writes the group in the namelist form.
-
What does this program print?
program p implicit none integer :: u, n namelist /g/ n n = 5 open (newunit=u, file="g.nml", status="replace", action="write") write (u, "(a)") "&g" write (u, "(a)") " n = 9" write (u, "(a)") "/" close (u) open (newunit=u, file="g.nml", status="old", action="read") read (u, nml=g) close (u) print *, n end program pAnswer
9
The file names n, so the read replaces its value.
-
What happens to a variable of the group that the file does not name?
Answer
It keeps the value the program gave it
A namelist read only assigns the names it finds.
-
How does a namelist record group begin and end?
Answer
It begins with &name and ends with a slash
The ampersand introduces the group and the slash closes it.
-
What happens when the group name in the file does not match the group of the program?
Answer
The read fails with a nonzero status or an error
The group name is what the read looks for.
-
Why does the written file show 9.99999978E-03 for the value 0.01?
Answer
The file holds the decimal form of the stored 32-bit value, which is not exactly 0.01
A real32 stores an approximation and the file writes that value.
-
What is a namelist best for?
Answer
A flat set of parameters that a person may edit between runs
The form is a small configuration language.
-
What does a namelist read do with a name in the file that the group does not declare?
Answer
It is an error
An unknown name inside the group stops the read.
-
Which statement writes a namelist group?
Answer
WRITE (unit, NML=group)
The NML= specifier names the group.
The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev