Running MPAS-Atmosphere


Given a CVT mesh, prepared using steps from Preparing Meshes, there are two main steps to running the MPAS-Atmosphere model:

  1. creating initial conditions (both real-data and idealized), using the init_atmosphere core

  2. running the model, using the atmosphere core


In general, an executable is run with mpiexec or mpirun, for example:

> mpiexec -n 8 atmosphere model

where 8 is the number of MPI tasks to be used. In any case where n > 1, there must exist a corresponding graph decomposition file, e.g., graph.info.part.8. For more on graph decomposition, see Graph Partitioning with METIS.



Creating Idealized Initial Conditions


Supported Idealized Test Cases

  • 1 : Jablonowski and Williamson baroclinic wave, no initial perturbation (Jablonowski and Williamson, 2006)

  • 2 : Jablonowski and Williamson baroclinic wave, with initial perturbation

  • 3 : Jablonowski and Williamson baroclinic wave, with normal-mode perturbation

  • 4 : squall line

  • 5 : super-cell

  • 6 : mountain wave


Note

No external data are required and the starting date/time is irrelevant to building the initial conditions file (init.nc) that will be used to run the model.



Steps to Create “init.nc” for Idealized Cases

  1. Include a grid.nc file, which contains the CVT mesh, in the working directory

  2. If running with more than one MPI task, include a graph.info.part.* file in the working directory (see Graph Partitioning with METIS)

  3. Compile MPAS with the init_atmosphere core specified

  4. Edit the namelist.init_atmosphere configuration file (described below)

  5. Edit the streams.init_atmosphere I/O configuration file (described below)

  6. Run init.atmosphere_model to create the initial condition file, init.nc


When the init.atmosphere_model executable is built, a default namelist, namelist.init_atmosphere, is created, which contains many parameters irrelevant to creating idealized conditions, and can be removed or ignored.



Required Namelist Parameters Specific to Idealized Cases

Formal explanations for all namelist parameters can be found in Appendix A.


&nhyd_model

config_init_case = 2

a number between 1 and 6 corresponding to the cases listed at the beginning of this section

config_start_time = ‘0000-01-01_00:00:00’

the starting time for the simulation

config_theta_adv_order = 3

advection order for theta

config_coef_3rd_order = 0.25

&dimensions

config_nvertlevels = 26

the number of vertical levels to be used in the model

&decomposition

config_block_decomp_file_prefix = ‘graph.info.part.’

if running in parallel this needs to match the grid decomposition file prefix

After editing namelist.init_atmosphere, make the following modifications to the XML I/O configuration file, streams.init_atmosphere. See details of the XML I/O configuration file format in Configuring Model Input and Output.

  • filename_template must be set to the name of the grid file in the “input” stream definition

  • filename_template must be set to name of the initial condition file to be created in the “output” stream definition




Creating Real-data Initial Conditions

The process of generating real-data initial conditions requires interpolation of the following.

  • static geographic data (e.g., topography, land cover, soil category, etc.)

  • surface fields such as soil temperature and SST

  • the atmospheric initial conditions valid at a specific date and time.


Two separate runs of the “init_atmosphere_model” program are required to create real-data initial conditions. They serve the following purposes.

  1. Interpolating Static Fields onto the Mesh (to create a static.nc file)

  2. Vertical Grid Generation and Initial Field Interpolation


Note

While it is possible to condense the two real-data initialization steps into a single run, running each step separately improves clarity and saves a significant amount of time when generating subsequent initial conditions, that is, when making initial conditions using the same mesh but different starting times.



Static Fields

To generate a static.nc file, download a set of static geographic data to a directory, which will be specified in the namelist.init_atmosphere file (described below) prior to running this interpolation step.

This run creates a netCDF file (static.nc), which is used in Vertical Grid Generation and Initial Field Interpolation to create dynamic initial conditions.


The following steps summarize the creation of *static.nc*:

  1. Download geographic data (described above)

  2. Compile MPAS with the init_atmosphere core specified

  3. Include a grid.nc file in the working directory

  4. Edit the namelist.init_atmosphere configuration file (described below)

  5. Edit the streams.init_atmosphere I/O configuration file (described below)

  6. Run init_atmosphere_model with only one MPI task specified to create static.nc

Important

It is critical that the initialization core is run serially; afterward, however, the steps described in Vertical Grid Generation and Initial Field Interpolation may be run with more than one MPI task.


Note

Although this step cannot be run in parallel and can take considerable time to complete, because the fields are static, this step need only be run once for a particular mesh. Once static.nc is generated, it can then be used repeatedly to generate initial condition files for different start times.



This initialization run makes use of the namelist.init_atmosphere namelist file. The default namelist.init_atmosphere file in the MPAS directory may be used as a starting point. Not every variable in this namelist is needed for any particular step, and therefore the following descriptions elaborate only on the immediately relevant variables. Formal explanations for all namelist parameters can be found in Appendix A.


&nhyd_model

config_init_case = 7

must be 7 - the real-data initialization case

&dimensions

config_nvertlevels = 1
config_nsoillevels = 1
config_nfglevels = 1
config_nfgsoillevels = 1

these dimensions should be set to 1 now, and their values become significant in Vertical Grid Generation and Initial Field Interpolation

&data sources

config_geog_data_path = ‘/path/to/WPS_GEOG/’

absolute path to static files obtained from the WRF download page

config_landuse_data = ‘MODIFIED_IGBP_MODIS_NOAH’

land use dataset selection

config_topo_data = ‘GMTED2010’

terrain dataset selection

config_vegfrac_data = ‘MODIS’

monthly vegetation fraction dataset selection

config_albedo_data = ‘MODIS’

monthly albedo dataset selection

config_maxsnowalbedo_data = ‘MODIS’

maximum snow albedo dataset selection

config_supersample_factor = 1

MODIS supersampling factor, generally only needed for meshes with grid distance < 6 km

&preproc_stages

config_static_interp = true
config_native_gwd_static = true
config_vertical_grid = false
config_met_interp = false
config_input_sst = false
config_frac_seaice = false

only the static_interp and native_gwd_static stages should be enabled

After editing namelist.init_atmosphere, make the following modifications to the XML I/O configuration file, streams.init_atmosphere.

  • filename_template must be set to the name of the SCVT grid file in the “input” stream definition

  • filename_template must be set to name of the static file to be created in the “output” stream definition.



Vertical Grid Generation and Initial Field Interpolation

The second step to create a real-data initial conditions file (init.nc) is to generate a vertical grid, who’s parameters will be specified in the namelist.init_atmosphere file, and to obtain an initial conditions dataset and interpolate it onto the model grid. While initial conditions could be obtained from many different data sources, here we assume the use of the WRF Preprocessing System (WPS) “intermediate” data files obtained from GFS data, using the WPS ungrib program. See detailed instructions for building the WPS and running the WPS, including the process for generating intermediate data files from GFS data.


The following steps summarize the creation of init.nc.

  • Include a WPS intermediate data file in the working directory

  • Include the static.nc file in the working directory (see Static Fields)

  • If running in parallel, include a graph.info.part./* file in the working directory (see Graph Partitioning with METIS)

  • Edit the namelist.init_atmosphere configuration file (described below)

  • Edit the streams.init_atmosphere I/O configuration file (described below)

  • Run init_atmosphere_model to create init.nc


This initialization run makes use of the namelist.init_atmosphere namelist file. The default namelist.init_atmosphere file in the MPAS directory may be used as a starting point. Not every variable in this namelist is needed for any particular step, and therefore the following descriptions elaborate only on the immediately relevant variables. Formal explanations for all namelist parameters can be found in Appendix A.


&nhyd_model

config_init_case = 7

must be 7

config_start_time = ‘2010-10-23_00:00:00’

time to process first-guess data

config_theta_adv_order = 3

advection order for theta

config_coef_3rd_order = 0.25

&dimensions

config_nvertlevels = 55

number of vertical levels to be used in MPAS

config_nsoillevels = 4

number of soil layers to be used in MPAS

config_nfglevels = 38

number of vertical levels in intermediate file

config_nfgsoillevels = 4

number of soil layers in intermediate file

&data sources

config_met_prefix = ‘FILE’

the prefix of the intermediate file to be used for initial conditions

config_use_spechumd = true

if available, use specific humidity rather than relative humidity

&vertical_grid

config_ztop = 30000.0

model top height (m)

config_nsmterrain = 1

number of smoothing passes for terrain

config_smooth_surfaces = true

whether to smooth zeta surfaces

config_blend_boundary_terrain = false

whether to blend terrain along domain boundaries; only for regional simulations

&preproc_stages

config_static_interp = false
config_native_gwd_static = false
config_vertical_grid = true
config_met_interp = true
config_input_sst = false
config_frac_seaice = true

only these three stages should be enabled

&decomposition

config_block_decomp_file_prefix = ‘graph.info.part.’

if running in parallel, this needs to match the grid decomposition file prefix


After editing namelist.init_atmosphere, make the following modifications to the XML I/O configuration file, streams.init_atmosphere.

  • filename_template must be set to the name of the static file in the “input” stream definition,

  • filename_template must be set to name of the initial condition file to be created in the “output” stream definition.




Running the Model

Having generated the model initial conditions, init.nc, as described in either Creating Idealized Initial Conditions or Creating Real-data Initial Conditions cases, the prerequisites to run the model are complete. This section discusses both running the model from a cold start and restarting the model from some point in a previous run.


Summary of Steps to Run the Model

  • Include an initial condition netCDF file (e.g., init.nc) in the working directory

  • (OPTIONAL) To periodically update the SST and sea-ice fields, include a surface netCDF file (e.g., surface.nc) in the working directory (see Model Options)

  • (OPTIONAL) If running a regional simulation, include lateral boundary conditions (LBC) netCDF files (e.g., lbc.YYYY-MM-DD_HH.mm.ss.nc) in the working directory

  • If running in parallel, include a graph decomposition file in the working directory (see Graph Partitioning with METIS)

  • If the MPAS directory has not been cleaned since running the initialization, run make clean with the atmosphere core specified

  • Compile MPAS with the atmosphere core specified

  • Edit the default namelist.atmosphere configuration file (described below)

  • Edit the streams.atmosphere I/O configuration file (described below)

  • Run the atmosphere_model executable



Required Namelist Parameters to Run the Model

Prior to running the model, the namelist file, namelist.atmosphere, must be configured. This file is automatically generated when the “atmosphere” core is built. This default namelist can serve as a starting point for any modifications made.

Below is a list of variables in namelist.atmosphere that pertain to model timestepping, explicit horizontal diffusion, and model restarts. A number of namelist variables are not listed here (specifications for dynamical core configuration, physics parameters, etc.) and Appendix B should be consulted for the purpose and acceptable values of these parameters.


nhyd_model

config_dt = 720.0

the model timestep; an appropriate value must be chosen relative to the grid cell spacing

config_start_time = ‘2010-10-23_00:00:00’

the model start time corresponding to init.nc

config_run_duration = ‘5_00:00:00’

the duration of the model run; for format rules see Appendix B

config_len_disp = 120000.0

the smallest cell-to-cell distance in the mesh, used for computing a dissipation length scale

&limited_area

config_apply_lbcs = false

must be set to true only if running a regional simulation

&decomposition

config_block_decomp_file_prefix = ‘graph.info.part.’

if running in parallel, this must match the prefix of the graph decomposition file

&restart

config_do_restart = false

if true, will select the appropriate restart.nc file generated from a previous run

&physics

config_sst_update = true

if updating sea-ice and SST with a surface.nc file, set to true and edit the “surface” stream in the streams.atmosphere file accordingly

config_physics_suite = ‘mesoscale_reference’


When running the model from a cold start, config_start_time should match the time that was used when creating init.nc. Edit the streams.atmosphere file to configure the model input and output. The following streams exist by default in the “atmosphere” core:

input

the stream used to read model initial conditions for cold-start simulations

restart

the stream used to periodically write restart files during model integration, and to read initial conditions when performing a restart model run

output

the stream responsible for writing model prognostic and diagnostic fields to history files

diagnostics

the stream responsible for writing (mostly) 2-d diagnostic fields, typically at higher temporal frequency than the history files

surface

the stream used to read periodic updates of sea-ice and SST from a surface update file created as described in Periodic SST and Sea-ice Updates

iau

the stream used to read analysis increments for the Incremental Analysis Update (IAU) scheme

lbc_in

the stream used to read lateral boundary updates for limited-area simulations, described in Regional Simulation

During a model run, restart files are created at an interval specified by the output_interval attribute in the definition of the “restart” stream. Running the model from a restart file is similar to running the model from init.nc. The required changes are

  • config_do_restart must be set to true

  • config_start_time must correspond to a restart file existing in the working directory