======================= Running MPAS-Atmosphere ======================= | Given a CVT mesh, prepared using steps from `Preparing Meshes <./preparing_meshes.html>`_, there are two main steps to running the MPAS-Atmosphere model: #. creating initial conditions (both real-data and idealized), using the *init_atmosphere* core #. running the model, using the *atmosphere* core | In general, an executable is run with *mpiexec* or *mpirun*, for example: .. code-block:: > 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 <./preparing_meshes.html#graph-partitioning-with-metis>`_. | | .. _idealized: 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 --------------------------------------------- #. Include a *grid.nc* file, which contains the CVT mesh, in the working directory #. If running with more than one MPI task, include a *graph.info.part.\** file in the working directory (see `Graph Partitioning with METIS <./preparing_meshes.html#graph-partitioning-with-metis>`_) #. `Compile MPAS <./building_mpas.html>`__ with the *init_atmosphere* core specified #. 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 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 <./appA_init_namelist.html>`_. | **&nhyd_model** .. csv-table:: :width: 80% :widths: 40, 40 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** .. csv-table:: :width: 80% :widths: 40, 40 config_nvertlevels = 26, the number of vertical levels to be used in the model | **&decomposition** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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 <./configuring_io.html>`_. * *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 | | | .. _real-data: 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. #. Interpolating Static Fields onto the Mesh (to create a *static.nc* file) #. :ref:`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: Static Fields ------------- To generate a *static.nc* file, `download a set of static geographic data <./../../download/get_sources_wps_geog.html>`_ 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 :ref:`Vertical Grid Generation and Initial Field Interpolation` to create dynamic initial conditions. | **The following steps summarize the creation of *static.nc*:** #. Download geographic data (described above) #. `Compile MPAS <./building_mpas.html>`__ with the *init_atmosphere* core specified #. Include a *grid.nc* file in the working directory #. Edit the *namelist.init_atmosphere* configuration file (described below) #. Edit the *streams.init_atmosphere* I/O configuration file (described below) #. 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 :ref:`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 <./appA_init_namelist.html>`_. | **&nhyd_model** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_init_case = 7, must be 7 - the real-data initialization case | **&dimensions** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_nvertlevels = 1 |br| config_nsoillevels = 1 |br| config_nfglevels = 1 |br| config_nfgsoillevels = 1, these dimensions should be set to 1 now/, and their values become significant in :ref:`Vertical Grid Generation and Initial Field Interpolation` | **&data sources** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_static_interp = true |br| config_native_gwd_static = true |br| config_vertical_grid = false |br| config_met_interp = false |br| config_input_sst = false |br| 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: 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 :ref:`Static Fields`) * If running in parallel, include a *graph.info.part./** file in the working directory (`see Graph Partitioning with METIS <./preparing_meshes.html#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 <./appA_init_namelist.html>`_. | **&nhyd_model** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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 <./model_options.html#regional-simulation>`__ | **&preproc_stages** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_static_interp = false |br| config_native_gwd_static = false |br| config_vertical_grid = true |br| config_met_interp = true |br| config_input_sst = false |br| config_frac_seaice = true, only these three stages should be enabled | **&decomposition** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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: Running the Model ================= Having generated the model initial conditions, *init.nc*, as described in either :ref:`idealized` or :ref:`real-data` 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 <./model_options.html>`_) * (OPTIONAL) If running a `regional simulation <./model_options.html#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 <./preparing_meshes.html#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 <./building_mpas.html#compiling-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 <./appB_init_namelist.html>`_ should be consulted for the purpose and acceptable values of these parameters. | **nhyd_model** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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 <./appB_init_namelist.html>`_ config_len_disp = 120000.0, the smallest cell-to-cell distance in the mesh/, used for computing a dissipation length scale | **&limited_area** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_apply_lbcs = false, must be set to true only if running a `regional simulation <./model_options.html#regional-simulation>`__ | **&decomposition** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_block_decomp_file_prefix = 'graph.info.part.', if running in parallel/, this must match the prefix of the graph decomposition file | **&restart** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / config_do_restart = false, if true/, will select the appropriate *restart.nc* file generated from a previous run | **&physics** .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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: .. csv-table:: :width: 80% :widths: 40, 40 :escape: / 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 <./model_options.html#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 <./model_options.html#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 | | | | | .. rst-class:: horizbuttons-next-m * `Next: Model Options -> <./model_options.html>`_ |