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

  1. Add a logical verbose to the group and write the file again. How is a logical written?
  2. Read a file whose group is called &settings with the group of the program. What does the read report?
  3. Put a value the program does not declare in the file, such as colour = 3. What happens, and is the value ignored?
  4. 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.

  1. 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.

  2. 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.

  3. 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 p

    Answer

    9

    The file names n, so the read replaces its value.

  4. 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.

  5. 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.

  6. 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.

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

  8. 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.

  9. 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.

  10. 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