modify_case_namelists.py

modify_case_namelists.py#

Modifies key-value entries in eCLM case namelist files.

What it does#

The script rewrites individual namelist keys in one or more eCLM case namelist files. Only the keys targeted by the supplied options are changed; all other content is left untouched.

After modifying each file the script appends a comment block recording the timestamp and the full command that was run (suppressed with --no-changelog):

!#--------------------------------------------------------------------------------------------------------------------------
!# lnd_in:: Modified by modify_case_namelists.py on 2024-07-01 09:15:00
!# Command: modify_case_namelists.py --rundir /path/to/rundir --clm_inparm-finidat my_restart.nc
!#--------------------------------------------------------------------------------------------------------------------------

Files and option groups#

Options are organised by the file and namelist group they target. The prefix of each option flag identifies both:

Option prefix	File	Namelist group
`--megan-`	`drv_flds_in`	`&megan_emis_nl`
`--timemgr-`	`drv_in`	`&seq_timemgr_inparm`
`--infodata-`	`drv_in`	`&seq_infodata_inparm`
`--driver-`	`drv_in`	`&cime_driver_inst`
`--pes-`	`drv_in`	`&cime_pes`
`--esmf-`	`drv_in`	`&esmf_inparm`
`--pio-`	`drv_in`	`&pio_default_inparm`
`--prof-`	`drv_in`	`&prof_inparm`
`--cplflds-`	`drv_in`	`&seq_cplflds_inparm`
`--flux_mct-`	`drv_in`	`&seq_flux_mct_inparm`
`--clm_inparm-`	`lnd_in`	`&clm_inparm`
`--ndepdyn-`	`lnd_in`	`&ndepdyn_nml`
`--soilhydro-`	`lnd_in`	`&soilhydrology_inparm`
`--soilwater-`	`lnd_in`	`&soilwater_movement_inparm`
`--canopyhydro-`	`lnd_in`	`&clm_canopyhydrology_inparm`
`--atm2lnd-`	`lnd_in`	`&atm2lnd_inparm`
`--datm_nml-`	`datm_in`	`&datm_nml`
`--shr_strdata_nml-`	`datm_in`	`&shr_strdata_nml`
`--mosart_inparm-`	`mosart_in`	`&mosart_inparm`
`--modelio-`	`*_modelio.nml`	`&modelio`
`--pio_inparm-`	`*_modelio.nml`	`&pio_inparm`

Run python3 modify_case_namelists.py --help for the complete list of available keys within each group.

Usage#

# Set run period and CLM initial conditions
python3 modify_case_namelists.py \
    --rundir /path/to/rundir \
    --timemgr-start_ymd 20220101 \
    --timemgr-stop_ymd  20221231 \
    --clm_inparm-finidat my_restart.nc

# Change output directory in all modelio files
python3 modify_case_namelists.py \
    --rundir /path/to/rundir \
    --adapt lnd_modelio.nml atm_modelio.nml \
    --modelio-diro /scratch/logs

# Modify only lnd_in, skip the changelog comment
python3 modify_case_namelists.py \
    --rundir /path/to/rundir \
    --adapt lnd_in \
    --no-changelog \
    --clm_inparm-spinup_state 1

General options#

Option	Description
`-r`, `--rundir`	Directory containing the namelist files. Defaults to `.`
`-a`, `--adapt`	Which files to modify (space- or comma-separated). Default: `drv_in lnd_in datm_in mosart_in`
`-b`, `--backend`	Namelist backend: `re` (default, regexp-based) or `f90nml`
`--no-changelog`	Do not append the modification comment block to modified files

Commonly used keys#

Run period (--timemgr-)

Option	Namelist key	Description
`--timemgr-start_ymd`	`start_ymd`	Start date (`YYYYMMDD`)
`--timemgr-stop_ymd`	`stop_ymd`	Stop date (`YYYYMMDD`)
`--timemgr-stop_n`	`stop_n`	Run length (number of units)
`--timemgr-stop_option`	`stop_option`	Run length unit (`nyears`, `ndays`, …)
`--timemgr-restart_n`	`restart_n`	Restart interval (number)
`--timemgr-restart_option`	`restart_option`	Restart interval unit
`--timemgr-calendar`	`calendar`	Calendar type
`--timemgr-atm_cpl_dt`	`atm_cpl_dt`	ATM coupling time step (s)
`--timemgr-lnd_cpl_dt`	`lnd_cpl_dt`	LND coupling time step (s)

Land model (--clm_inparm-)

Option	Namelist key	Description
`--clm_inparm-finidat`	`finidat`	Initial conditions file
`--clm_inparm-fsurdat`	`fsurdat`	Surface data file
`--clm_inparm-fatmlndfrc`	`fatmlndfrc`	Domain file
`--clm_inparm-paramfile`	`paramfile`	CLM parameter file
`--clm_inparm-dtime`	`dtime`	CLM time step (s)
`--clm_inparm-spinup_state`	`spinup_state`	Spinup mode (0: normal, 1: AD, 2: post-AD)
`--clm_inparm-hist_nhtfrq`	`hist_nhtfrq`	History write frequency
`--clm_inparm-hist_mfilt`	`hist_mfilt`	Max frames per history file
`--clm_inparm-hist_fincl1`	`hist_fincl1`	History field list (Fortran list string)

DATM streams (--shr_strdata_nml-)

Option	Namelist key	Description
`--shr_strdata_nml-streams`	`streams`	Stream file list (Fortran list string)
`--shr_strdata_nml-domainfile`	`domainfile`	DATM domain file

Model I/O (--modelio-, --pio_inparm-)

Option	Namelist key	Description
`--modelio-diri`	`diri`	Input directory
`--modelio-diro`	`diro`	Output/log directory
`--modelio-logfile`	`logfile`	Log filename
`--pio_inparm-pio_typename`	`pio_typename`	PIO I/O type (`netcdf`, `pnetcdf`, …)
`--pio_inparm-pio_numiotasks`	`pio_numiotasks`	Number of PIO I/O tasks

Multi-value keys#

Some keys hold comma-separated Fortran list values (e.g. hist_fincl1, streams). Pass the entire Fortran list string as a single quoted argument:

--clm_inparm-hist_fincl1 "'SOILWATER_10CM', 'H2OSOI', 'SOILLIQ'"