Frequently Asked Questions

Search the FAQs here:

General

How do I join the CAMxusers group?

The CAMx users group is an easy way for users to obtain and share information. To join the group, send an e-mail message to “camxdevel” at gmail dot com with the words “subscribe CAMxusers” in the BODY of the message (and the subject line). You will receive an invitation to join the Google Group along with additional information on how to use this service.

The CAMxusers group is meant for broadcasting useful information about CAMx and its pre- and post-processors to all users that join this group, or to ask about available datasets or issues that other users may have come across. It is not meant for asking how to run CAMx, how to prepare inputs, or why CAMx arrived at a particular prediction.

Please first refer to the CAMx User’s Guide or this FAQ page.

Is CAMx a suitable model for my study?

CAMx is suitable to address air pollution issues involving inert and chemically-derived compounds such as ozone, particulate matter and air toxics over a range of geographic scales (from individual plumes to urban areas to entire continents) and time periods (hourly to annual). CAMx treats complex chemical interactions among directly emitted emissions from anthropogenic and natural sources, and their chemical products. It is an open-source system that is computationally efficient and flexible. Meteorological fields are supplied to CAMx from separate weather prediction models. Emission inputs are supplied from external pre-processing systems. As a limited-area deterministic model, CAMx requires specification of initial conditions at the start of a simulation period, and boundary conditions at the edge of the modeling domain. These data can be derived using output from global chemical transport models.

Can CAMx simulate specific toxics, hazardous air pollutants (HAPs) or persistent organic pollutants (POPs) that are not included in the gas and PM species lists of the standard chemical mechanisms available in CAMx?

There are two optional capabilities in CAMx that can work together for such pollutants, and these are explained in the CAMx User’s Guide:

- RTRAC/RTCMC (Reactive Tracers and the Reactive Tracer Chemical Mechanism Compiler): This allows you to add specific species as reactive tracers separate from the usual oxidants and particles. The tracers will be emitted, transported, chemically reacted (e.g., with OH) and deposited.
- Surface model: This allows any subset of tracers that you define to deposit to the surface and later re-emit from the surface or be stored at the surface. A surface burden of such species will be tracked and output through the simulation.

How can I get older versions of the model?

We post all model versions publicly released over the past 5 years on the “Download CAMx” page; including source code, version-specific inputs, and User’s Guides. Contact us to request earlier versions. We post major updates usually once per year; special versions with minor updates and bug fixes may be posted more frequently.

Unless you have a compelling reason to use an older version of the model, we strongly recommend that you use the latest version to ensure that you take advantage of the latest enhancements and bug fixes. We cannot provide support for outdated versions of the model.

Do the CAMx developers offer training courses?

We do not conduct regularly scheduled CAMx training courses. We can provide tailored training by request to single institutions or a coordinated group of users, either at our office in the San Francisco Bay Area or at your location. Cost and duration depend on the level of training requested, preparation time and any travel. Training can range from a single day of lecture overview on the CAMx system, to multiple days of lecture and hands-on computer exercises using just the core model or including Probing Tools. We highly recommend that those participating in hands-on exercises are comfortable navigating and scripting in the Linux operating system. Contact us for more information and to arrange training.

Installing/Building CAMx

How do I build and install the CAMx model on my system?

CAMx is not distributed as an executable program, but instead as FORTRAN source code. You will need to build an executable program for your system using a FORTRAN compiler. Instructions in the Users’s Guide explain how to build the model using the Makefile supplied with the source code. CAMx is currently designed to be used in Unix/Linux environments.

Can CAMx run in the Windows OS?

CAMx can run in the Windows environment, but the Makefile distributed with CAMx that builds the CAMx executable does not currently support FORTRAN compilers for Windows. We plan to include this capability in future releases. You will need to edit the Makefile to include your Windows compiler, flags, and libraries. CAMx has been designed and developed for Unix/Linux environments, and its operation is controlled using Linux “shell scripts”; CAMx is not run from a Graphical User Interface (GUI). Therefore, CAMx is most easily applied in a Windows environment by running CAMx scripts within applications that emulate a Linux shell (e.g., Powershell).

When compiling CAMx using the Makefile, errors occur saying MPI or netCDF libraries are not found, or there are many unresolved externals and functions. How can I fix this?

If you do not have MPI or netCDF libraries installed on your system, you cannot use these features. Be sure to use the proper command-line Makefile options to compile CAMx without these features. Instructions in the Users’s Guide explain how to build the model using the Makefile supplied with the source code. Also, instructions on using the Makefile are printed to the screen by typing “make help” at the shell prompt.

Be sure that the Makefile variables defining the directory paths to all of the needed libraries are set properly. These variables include: “MPI_INST” and “NCF_INST” in the CAMx Makefile, and “MPI_INST” in the MPI utilities Makefile located in the MPI/util source code subdirectory.

If MPI or netCDF libraries are built and installed improperly or inconsistently, the CAMx compilation could fail. It is best to build and install them with the same compiler used to build CAMx to ensure optimal compatibility. We recommend ensuring that these libraries are installed properly by compiling and running a test program before attempting the CAMx build.

How can I build CAMx using FORTRAN or C compilers, or MPI libraries, that are not supported in the CAMx Makefile?

The CAMx Makefile supports the most widely-used FORTRAN compilers for Linux systems, including: Intel, Portland Group, Gnu, Sun Oracle, and Absoft for Mac OSX. In all cases the Makefile accesses the Gnu C compiler (gcc), which is available with all Linux installations. The Makefile supports the following MPI libraries: MPICH1-3, OpenMPI, and MVAPICH. If you have compilers or MPI libraries not supported by the CAMx Makefile, you will need to edit the Makefile to include your specific compilers, flags, and libraries.

Preparing Inputs

How can I get emission inventories for my area?

We do not distribute emission inventories. For the United States, emission inventories are available from the US Environmental Protection Agency (https://www.epa.gov/air-emissions-inventories/). For Europe, emission inventories are available from the European Monitoring and Evaluation Programme (EMEP; http://www.ceip.at/). For China, emission inventories are available from the MarcoPolo Inventory (http://www.marcopolo-panda.eu/products/toolbox/emission-data/) and more broadly for Asia, from the Regional Emissions Inventory in Asia (REAS; https://www.nies.go.jp/REAS/). Global emission inventories are available from the Emission Database for Global Atmospheric Research (EDGAR; http://edgar.jrc.ec.europa.eu/). Otherwise, contact your local environmental agency to inquire about local inventories for your area of interest.

What tools are available to format my emission inventory into CAMx input format?

Processors are needed to generate gridded, speciated, temporally-allocated (hourly) emission files for input to CAMx from raw emission inventory datasets. In the United States, the most common software tool is the Sparse Matrix Operator Kernel Emissions (SMOKE) processing system (https://www.cmascenter.org/smoke/). Alternatively, we maintain the Emissions Processing System, version 3 (EPS3); contact us for more information on obtaining and using EPS3. Both SMOKE and EPS3 require that raw emission inventory data be structured in very specific input formats and include very specific information, parameters and units. Otherwise, it is left to the user to develop processors that meet their specific needs. See the CAMx User’s Guide for information on required and optional emission variables and file formats used by CAMx.

How can I prepare CAMx inputs from meteorological models or regional/global analyses that are not supported by CAMx preprocessors?

We distribute meteorological interface preprocessors that are compatible with the output from these meteorological models: WRF, MM5 and RAMS. These programs also generate needed surface characteristic data for CAMx, including topography and land cover. For other sources of meteorological data, users can use these programs as a starting point and alter them accordingly to the specific data formats and variables available in their datasets. See the CAMx User’s Guide for information on required and optional meteorological variables and file formats used by CAMx.

It is expected that CAMx users will prepare high quality, mass consistent meteorological fields using advanced prognostic models so as to minimize mass, momentum and thermodynamic inconsistencies in the meteorological inputs. The practice of developing meteorological input fields using objective analysis or “diagnostic” approaches is highly discouraged.

Are there on-line libraries of global chemistry model datasets from which to develop boundary condition input files?

To our knowledge, the National Center for Atmospheric Research (NCAR) maintains the only on-line library of historical global chemistry model output available from which to generate regional model boundary conditions for CAMx and similar models. The library consists of output from the Model for Ozone and Related Chemical Tracers (MOZART; https://www2.acom.ucar.edu/gcm/mozart). Other global chemistry models must be run for the specific period of interest. We maintain boundary condition pre-processing programs that support output from MOZART and the GEOS-Chem global chemistry model (http://acmg.seas.harvard.edu/geos/).

If you are running a period that is not available in the MOZART library, we suggest that you analyze other year(s) and make monthly average boundary conditions as a surrogate for the missing period.

Running CAMx

I have successfully run WRFCAMx to generate met inputs for my application. But when I use them as inputs to CAMx, the model reports that the grids don’t match. What could be causing this?

There are many possible reasons. We list the most common causes below:

- The meteorological processing was not performed for the same size grid (x, y, z);
- The meteorological processing was not performed for the same grid resolution – especially for non-integer grid spacing (1.333… km), rounding errors may be causing CAMx to stop with this error;
- The meteorological processing did not consider the need for nested grid “buffer” cells;
- The meteorological processing was performed on a different map projection than is specified for the CAMx run.

Refer to the CAMx User’s Guide for more information on nested grid configurations and map projections.

How do I set the time zone in the CAMx.in file for the Eastern hemisphere.

CAMx expects time zones in the Western hemisphere to be set positive, and time zones in the Eastern hemisphere to be set negative. This is reverse of the standard global time convention (East is positive, West is negative).

What is the best way to run CAMx for a multiday simulation such as an entire month?

Although CAMx can simulate multiple days in a single run, we recommend running CAMx in a series of one-day simulations. Looping over multiple days is managed by Linux shell scripts through the use of “restart” files. An example shell script that runs the CAMx test case over 2 sequential days is available in the version-specific input files that are distributed with each model distribution. CAMx inputs can be created as a series of files, each containing data for a single day. These files can be easily managed by selecting a consistent naming convention that includes the calendar or Julian date.

CAMx stops with a message that it cannot find “CAMx.in”. Where do I get this file?

The “CAMx.in” file comprises the FORTRAN namelist that controls the CAMx run configuration. A template of this file is available with the source code; review and change settings according to your specifications and all I/O file path names. Linux shell scripting is the easiest way to develop CAMx.in files and to run the model for sequences of multiple days. An example shell script that runs the CAMx test case is available in the version-specific input files that are distributed with each model distribution. See the CAMx User’s Guide for more information on the CAMx.in namelist file.

CAMx stops with a message saying “error reading namelist” with other messages about changes to the namelist file. What is wrong?

The FORTRAN namelist requires very specific syntax, and most often errors are related to simple typographical errors. Check that your namelist does not contain variable misspellings, or is lacking (or including too many) single quotation marks or delimiting commas. As CAMx has evolved, certain namelist variables have been removed, so if you use an old namelist that contains variables that a newer version of the model does not recognize, this error will occur. A version-specific template of this file is available with the CAMx source code. See the CAMx User’s Guide for a full list of potential sources of error in reading the CAMx namelist file.

CAMx stops with a message saying “input record too long”. What is wrong?

This error is related to an inconsistency in the way CAMx expects to read FORTRAN “unformatted” (binary) input files. There are two ways to represent binary information: “big endian” and “little endian”. The difference between these is essentially the order of bits in a word, and which order is used depends on the computer chipset (see https://en.wikipedia.org/wiki/Endianness ).

The CAMx Makefile sets compiler flags consistently to use big endian for maximum platform portability. Therefore, use of the CAMx Makefile will by default result in the model reading and writing big endian binary files. CAMx can be compiled and run on machines that use either big or little endian binary representations, as long as the model and all of its pre- and post-processors are consistently compiled and run in the same way. If any component of the modeling system is compiled using the opposite binary representation, I/O files will not be properly read or written and will lead to this type of crash. (This is not the case with netCDF files, as they are platform-independent). If you get this error message, check for big endian / little endian consistency between your binary files and FORTRAN compiler options. See the CAMx User’s Guide for more information on FORTRAN binary bit representation and associated read errors.

CAMx stops unexpectedly before the specified end time, but no information on the cause is given. How can I get more information?

If CAMx stops because of a FORTRAN or system crash (for example, file read/write errors, segmentation faults, MPI/networking problem etc.) then a message is written to the standard output or standard error unit, which usually includes a system log file and/or the monitor screen. In the case of MPI, if such a crash occurs on one of the MPI nodes, then the standard error or output will be written locally on that node, and locating these errors may depend on how cluster resources and MPI jobs are managed. Look for the .out files on the individual nodes.

If CAMx stops because an error was trapped by the model itself (chemistry convergence issue, file not found, insufficient variable dimension, incompatible configuration settings, etc.) then a message is written to the standard output unit (log file or monitor screen) indicating that such error occurred and to review the “.out” file to identify the problem. Find the “.out” file in the location of all output generated by the model and look at the end of the file. The cause of the error should be adequately described, and in some cases a solution is suggested.

CAMx stops with a message saying it cannot find or read a file, but I see that it exists. What is wrong?

Carefully check that the file name specified in the CAMx.in namelist is properly spelled and that the directory path is spelled correctly and exists. Check that the computer that launches CAMx has access to any remote disks used for CAMx I/O. You may need to locally mount the remote drives to be able to access the data.

CAMx stops with a message saying that a dimension needs to be increased, but after changing the value in the code, CAMx stops with the same message. What is wrong?

Whenever you change a setting in the CAMx source code, it is necessary to recompile the program for the changes to be included in the CAMx executable. Always run “make clean” prior to compiling, which removes all intermediate objects and modules, to be sure that the entire model is re-compiled appropriately. Recompiling is not necessary if you change a setting in the CAMx.in namelist file.

CAMx stops with a message saying that a negative concentration was trapped during execution. What might cause this? Should I reduce the timestep?

CAMx automatically calculates the timestep length between I/O times (usually hourly) to ensure stable solutions for all transport algorithms (horizontal/vertical advection and diffusion) based on grid size, wind speeds and diffusivity values. It also determines much smaller timesteps necessary to ensure that all reaction solutions converge within allowed tolerances in the chemistry solver. If negative concentrations occur, or a chemical integration does not converge, error messages are written to the *.out message files, indicating where the problem occurs and the conditions that it is trying to solve. Check these error messages for any clues as to whether the data provided are problematic. Usually, there is no need to manually assert additional limits on the timestep to alleviate the problem.

Most often, this problem is caused by the data provided to the solvers, i.e., they are negative, too large/small to be resolved by single precision variables, or they are “not a number” (NaN) such as caused by divide by zero, etc. This can occur when bad data are read from the input files (emissions, meteorology, initial/boundary conditions), either generated by the pre-processor(s) or resulting from a file corruption. Carefully scan the input files at the hours bounding the time of the crash to find any invalid or problematic data. Review the screen output (standard output) from pre-processors to find any warning or error messages or other diagnostic information that indicate something went wrong.

I changed the NHGHT parameter in the camx.prm file to match the number of vertical layers in my CAMx run, but when I run the model I get this error message:

ERROR in READPHT:

ERROR: Reading photolysis rates file at line:

Does the rate file have the correct number of reactions?

Make sure the photolysis rate file matches the mechanism you are running.

What is wrong?

The parameter NHGHT does not represent the number of vertical layers in the CAMx modeling grid. Rather, it defines the number of levels in the photolysis rates file. Unless you specifically change the definition of levels in the photolysis rates pre-processor (TUV) you should leave NHGHT assigned to a value of 11.

CAMx completes successfully when I compile CAMx and run without Probing Tools (SA, DDM, PA, RTRAC), but when I re-compile CAMx to handle a large number of Probing Tool tracers, the compilation aborts with an error; or when I run CAMx that invokes a large Probing Tool application, it crashes with a segmentation fault. What is wrong?

Most often this is caused by a Probing Tool application that is too large to fit in available memory or that requires a tracer array size exceeding 2³¹ values (over 2 billion values or 8.6 GB). Carefully review the guidance comments in the Includes/CAMx.prm file on how to set the value of MXTRSP. Large Probing Tool configurations on large nested grids that track many source sectors and regions for many or all SA or DDM groups can easily result in massive array sizes. Consider condensing the Probing Tool configuration, or run CAMx separately for different groups of tracers.

The absolute maximum number of tracers you can run will depend on many factors, including how many grids, grid size (nx x ny x nz), number of regions, number of source categories and the number of tracer “families” you run. Often it is not necessary to run all tracer families (ozone, sulfate, nitrate, organics, primary), depending on your air quality problem.

When I run Source Apportionment, CAMx stops with an error saying that the sum of emissions over sectors does not match the main model emissions. What is the problem?

Source Apportionment requires that the sum of all emission sectors over all grids by species equal the total emissions supplied to the main model. This is to ensure accurate apportionment. In the case of a disagreement, it is important to review emission processing to be sure you are not double-counting or missing sector emissions. Be sure you are properly setting the “Leftover Group” flag in the CAMx namelist for your particular configuration. See the CAMx User’s Guide for more information.

I want to run ozone Source Apportionment with the APCA option (Anthropogenic Precursor Culpability Assessment). Are there any changes in setup from the standard Source Apportionment?

Please carefully review the Source Apportionment section of the CAMx User’s Guide before attempting a Source Apportionment run. APCA is an option for Ozone Source Apportionment (OSAT). For APCA, the most important constraint is that biogenic emissions be explicitly identified and tracked as one of the source categories, and that the biogenic 2-D surface emissions file be listed as the FIRST category for each grid in the simulation. CAMx assumes that the FIRST emissions category contains only biogenic emissions when running APCA. Category order is not important when running standard OSAT or particulate source apportionment (PSAT).

When I run Source Apportionment, I find strange results for certain point sources: for example, zero contributions near the source, but large contributions 100’s or 1000’s km away as if the source was misplaced in the grid. What happened?

This problem can occur if point source files used for Source Apportionment have the “point source region override” flags set for a specific source region configuration that does not match the current Source Apportionment configuration. If the source region definition is changed and you wish to use the “point source region override” flags in the point source files, you must be sure to reset those override values to be consistent with the new source region map, or turn off the “point source override” flag in the CAMx namelist. Otherwise, the original source region designation will point to new regions that identify a different part of the modeling domain, thereby artificially “re-locating” certain point sources to different grid locations.

Post-Processing

What CAMx species do I need to combine to represent total PM?

Using the standard “CF” aerosol option with the SOAP2 organic aerosol treatment:

PM2.5 = PSO4 + PNO3 + PNH4 + NA + PCL + PEC + POA + SOA1-4 + SOPA + SOPB + FCRS + FPRM (+ PFE + PMN + PK + PCA + PMG + PAL + PSI + PTI)

PM10 = PM2.5 + CCRS + CPRM

The PM2.5 species in parentheses represent 8 optional elemental species. The method by which to include them depends on how emissions are created to represent FPRM, FCRS and the elements. If the emitted mass of FCRS and FPRM is reduced by the mass of emitted elements, then sum all species (FPRM + FCRS + elements). However, if FCRS and FPRM were not reduced and represent all primary and crustal fine PM2.5 mass, then omit the elements from the summation.

The CAMx User’s Guide provides more information about the specific PM variables carried in CAMx.

How can I view CAMx inputs and output? What graphics tools are available that can read CAMx formats?

We do not develop, distribute, or endorse any particular graphics program. CAMx netCDF files (introduced in v6.50) are compatible with EPA’s Models-3 I/O API and can be read and processed directly by any graphics programs that are compatible with netCDF or I/O API.

EPA/CMAS have developed two GUI-driven graphics programs that can read CAMx FORTRAN binary files directly: PAVE (http://paved.sourceforge.net/) (no longer supported) and VERDI (https://www.cmascenter.org/verdi/). Other programs first require conversion of CAMx FORTRAN binary files to netCDF or I/O API formats (for example, using ncview, IDV, Panoply). We provide a FORTRAN post-processing program that converts to I/O API (camx2ioapi). Dr. Barron Henderson (US EPA) has developed a Python-based set of scripts that perform the same function, plus it contains many other file manipulation capabilities (http://pseudonetcdf.googlecode.com)

What tools are available to process Probing Tool output from Source Apportionment, Decoupled Direct Method, and Process Analysis?

We do not provide any specific programs to process Probing Tool output. We cannot anticipate the variety of purposes and configurations that may be developed to support the myriad of potential apportionment, sensitivity, or process-oriented analyses that are possible. It is best left to the user to develop specialized tools specific to their particular applications and project focus.