Getting Started

Getting Started

This page describes the common manual workflow. Start with Building if atmosphere_model, init_atmosphere_model, and build_tables are not available. To build a contained runtime and launch one of the three bounded demonstrations, use the separate Docker workflow.

1. Obtain the examples

Clone the wiki to obtain the configuration files exactly as documented:

git clone https://github.com/NCAR/CheMPAS-A.wiki.git

The clone contains only documentation and declarative example inputs. The examples/ tree has no executables or automation. Docker build and run assets reside in the public CheMPAS-A source repository rather than the wiki clone.

2. Create a run directory

An atmosphere run directory normally contains:

atmosphere_model
LANDUSE.TBL
namelist.atmosphere
streams.atmosphere
stream_list.atmosphere.output
<initial-condition>.nc
<graph>.part.<MPI-ranks>
<MICM mechanism>.yaml
<TUV-x configuration>.json
data/                         # MUSICA TUV-x data, when TUV-x is enabled
<MIEM configuration>.yaml     # when emissions are enabled
<inventory>.nc                # when emissions are enabled

Copy or link LANDUSE.TBL from src/core_atmosphere/physics/physics_wrf/files/LANDUSE.TBL. File names in the directory must match the supplied namelist, streams, MICM, TUV-x, and MIEM files exactly.

TUV-x paths in the example JSON files are relative to a directory named data. Use the data directory from the pinned MUSICA source:

ln -s /path/to/MUSICA/configs/tuvx/data data

3. Match the decomposition

For N MPI ranks, the decomposition prefix in namelist.atmosphere must resolve to a file ending in .part.N. For example, the x1.40962 examples use:

config_block_decomp_file_prefix = 'x1.40962.graph.info.part.'
x1.40962.graph.info.part.8

Chemistry currently supports exactly one local MPAS block on each MPI task. Leave the supplied examples on automatic block decomposition and do not request a multi-block layout.

4. Launch the model

The model reads its files from the current working directory:

mpiexec -n 8 ./atmosphere_model

This command is illustrative; use the rank count for the staged partition. Check log.atmosphere.0000.out for the source revision, enabled chemistry components, runtime-injected fields, mesh validation, and final completion.

5. Know which clock is valid

MIEM requires a Gregorian model calendar and inventory timestamps that cover the full run without extrapolation. Idealized non-emissions cases may retain the conventional MPAS year-zero clock. The initial-condition xtime, config_start_time, inventory xtime, and streams must agree.

6. Start with the smallest relevant case

• Use mountain-wave or baroclinic-wave ABBA to check runtime tracer registration and transport.
• Use Chapman + NOx to check TUV-x photolysis.
• Use the global emissions experiment to check prescribed upper O3 and one or two MIEM inventories.

Before interpreting science output, complete the reproducibility checklist.