Numerically accurate budgeting of the forcing terms in the governing equations of a numerical weather prediction model is hard to achieve. Because individual budget terms are generally 2 to 3 orders of magnitude larger than the resulting tendency, exact closure of the budget can only be achieved if the contributing terms are calculated consistently with the model numerics.

We present WRFlux, an open-source software that allows precise budget evaluation for the WRF model and, in comparison to existing similar tools, incorporates new capabilities. WRFlux transforms the budget equations from the terrain-following grid of the model to the Cartesian coordinate system, permitting a simplified interpretation of budgets obtained from simulations over non-uniform orography. WRFlux also decomposes the resolved advection into mean advective and resolved turbulence components, which is useful in the analysis of large-eddy simulation output. The theoretical framework of the numerically consistent coordinate transformation is also applicable to other models. We demonstrate the performance and a possible application of WRFlux with an idealized simulation of convective boundary layer growth over a mountain range. We illustrate the effect of inconsistent approximations by comparing the results of WRFlux with budget calculations using a lower-order advection operator and two alternative formulations of the coordinate transformation. With WRFlux, the sum of all forcing terms for potential temperature, water vapor mixing ratio, and momentum agrees with the respective model tendencies to high precision. In contrast, the approximations lead to large residuals: the root mean square error between the sum of the diagnosed forcing terms and the actual tendency is 1 to 3 orders of magnitude larger than with WRFlux.

Budget analysis for variables of a numerical weather prediction model is a widely used tool when examining physical processes in the atmospheric
sciences. Energy and mass budgeting has been used, for instance, to understand the governing dynamics of thermally driven circulations in the mountain
boundary layer

Large competing forcing terms adding up to a relatively small total tendency make the budget calculation particularly error-prone

For the WRF model

Even if the equations in the numerical model are cast in flux form, some authors use the advective form in budget analyses as they find it easier to
interpret

By design, the budget computation method of

Furthermore, budget analysis is more intuitively carried out in the Cartesian coordinate system, while numerical weather prediction models generally adopt a curvilinear terrain-following system. For budget diagnostics in simulation domains with non-uniform orography, accurate computation of the coordinate transformation between the terrain-following and the Cartesian system is therefore mandatory. This is mainly an issue when tendencies resulting from flux derivatives in a particular spatial direction, such as the vertical derivative of the resolved turbulent flux, are inspected.

Some numerical weather prediction models, e.g., WRF, adopt a mass-based vertical coordinate. Because the atmospheric mass in a model column generally varies during integration, the height of the vertical levels changes with time. Thus, time derivatives on constant model levels and at constant height are not equal. This also needs to be accounted for if one wishes to compute the total model tendency in the Cartesian coordinate system accurately. When looking at the instantaneous tendencies between individual model time steps, this effect can usually be neglected. However, if the budget is averaged over a time interval, the distance between the vertical levels can change considerably.

The decomposition into mean and turbulent components and the coordinate transformation to the Cartesian coordinate system were implemented, e.g., by

In this study, we present WRFlux, an open-source budget calculation tool for WRF that yields a closed budget, a consistent transformation to the Cartesian coordinate system, and decomposition into mean and turbulent components. WRFlux allows us to output time-averaged resolved and subgrid-scale fluxes and other tendency components for potential temperature, water vapor mixing ratio, and momentum for the Advanced Research WRF (ARW) dynamical core.

The paper is organized as follows. First, we summarize the theoretical foundation of the approach in Sect.

The flux-form conservation equation for a variable

Equation (

The transformation of Eq. (

Many atmospheric models use a coordinate system of the form

Examples of generalized vertical coordinates include terrain-following coordinates and pressure-based coordinates. WRF, for instance, uses a hybrid
terrain-following vertical coordinate based on hydrostatic pressure

Inserting Eqs. (

This form of the conservation equations is typically used in numerical weather prediction models. The horizontal and temporal derivatives are taken on
constant

For a budget calculation tool, taking the derivatives on constant

Using Eq. (

The second term on the left-hand side and the second term in square brackets are the correction terms that account for the derivatives being natively
computed on constant

As will be pointed out in Sect.

Solving for

Dividing by

Using the product rule and the commutativity of partial derivatives, one can show that Eq. (

Dividing Eq. (

The correction terms in Eq. (

Instead of Eq. (

For numerical reasons, WRF uses potential temperature perturbation as a prognostic variable. The perturbation is computed with respect to a constant
base state, as

So far we looked at the budget equations in flux form. This form corresponds to the tendency of

To compute the advective form in a numerically consistent way, we can use the components of the flux-form equation and the mass tendencies from
Eq. (

In the Cartesian coordinate system correction terms for the mass tendency components are introduced analogously to the correction terms in
Eq. (

WRF uses C grid staggering

On the right-hand side, the operator

For Eq. (

Although the momentum variables are staggered differently from the thermodynamic variables, their discretized equations can be derived analogously. We do not state them here for brevity.

In Eq. (

In the first one the corrections for the horizontal derivatives are built by taking the horizontal flux and staggering it horizontally and vertically
to the grid of the vertical flux:

This is analogous to the implementation of subgrid-scale diffusion in WRF.

The second one adopts a different discretization in the horizontal correction term that is closer to the one in Eq. (

The impact of the approximate budget calculations (Eqs.

After introducing the discretizations of the precise budget equation (Eq.

The decomposition of the resolved flux then reads

We use the density-weighted average, also known as Hesselberg or Favre averaging

The correction flux used in the horizontal corrections in Eq. (

We implemented the theoretical framework of the previous section in a diagnostic package for WRF: WRFlux. The main features of WRFlux are as follows.

Budget components are retrieved for potential temperature, water vapor mixing ratio, and momentum, including tendencies from the acoustic time step, subgrid-scale diffusion (from all available subfilter-scale models and planetary boundary layer schemes), physical parameterizations, and numerical diffusion and damping.

The subgrid-scale and resolved fluxes and all budget components except for advection are averaged in time during model integration over a
user-specified time window. The optional spatial averaging and computation of advective tendencies with decomposition into mean advective and
resolved turbulent is done in the post-processing. The resolved turbulent component is calculated using Eq. (

The vertical velocity is recalculated with Eq. (

This modification is available as a namelist option starting from WRF version 4.3. See

To close the budget for both the perturbation

The mean advective tendencies, the total advective tendencies, and the final model tendency can be transformed to the advective form using the
components of the time-averaged continuity equation in Eqs. (

Dry

Map-scale factors are taken care of as described in

Before each update of WRFlux, an automated test suite is carried out that checks the output of WRFlux for consistency using idealized test simulations with a large number of different namelist settings. Details about the tests can be found in the documentation of WRFlux. The latest version of WRFlux, version 1.3, is based on WRF-ARW version 4.3. WRFlux is easy to install, and new releases of WRF are continuously integrated. The post-processing tool is written in Python.

We demonstrate the capabilities of WRFlux with a simulation of the diurnal evolution of the convective boundary layer over mountainous terrain using
WRFlux version 1.2.1. The model setup, i.e., the initial conditions, terrain specification, grid spacing, land surface properties, and the choice of
the subfilter-scale model, follows

WRF's hybrid terrain-following coordinate is used. There are 140 vertical levels with a vertical grid spacing ranging approximately from 8

Implicit Rayleigh damping

The boundary layer evolution is driven by a simplified radiation scheme as in

The model is initialized at rest with the lapse rate

Since no microphysics scheme is activated and the simplified radiation scheme only affects the surface energy balance, the heat budget in the
atmosphere only consists of resolved advection and subgrid-scale diffusion. For general applications, other grid-resolved and parameterized physics
terms are possible and categorized as additional budget components. We calculate full-

Cross sections of total turbulence (trb

The budget components are divided by mean density to obtain tendencies of the form

We quantify the budget closure with the root-mean-square error of the sum of all forcing terms

The averaging is over all grid points and 30 min averaging intervals. Following

We start with a short overview of the individual heat budget components in the example simulation for the averaging period between 3.5 and 4

Profiles of turbulence

Cross sections of total

Profiles of total

Figure

The total tendency in the mass-based terrain-following coordinate system shows somewhat different structures with stronger warming throughout the
domain (Fig.

Since we use the equations in flux form, Figs.

As shown above, a budget equation typically consists of large competing forcing terms that add up to a relatively small total tendency. To illustrate
this, instead of looking at the decomposition into total turbulence and mean advective tendencies as in Fig.

We compare the budget obtained with WRFlux (Eq.

Profiles of resolved turbulence

Scatterplots of the right-hand side (

The different formulations for the horizontal flux derivatives (Sect.

NRMSE (Eq.

To quantify the differences, we plot the right-hand side (forcing) of Eq. (

We also tested two other approximations: using WRF's prognostic vertical velocity in the resolved vertical flux instead of the one recalculated with
Eq. (

To compare our results to

We developed a computational method to accurately diagnose the advective and turbulence components of the budgets of prognostic variables in a numerical weather prediction model. The method is based on a numerically consistent implementation of the transformation from a coordinate system with a generalized vertical coordinate, such as a terrain-following coordinate system, to the Cartesian coordinate system. The partitioning of the advective tendency into horizontal and vertical components is different in the two coordinate systems, and thus the coordinate transformation is helpful when investigating the horizontal and vertical components separately. We illustrated this by assessing the local heat budget in a simulation of a convective boundary layer over an idealized 2D mountain ridge. The slope flow layer is subject to vertical resolved and subgrid-scale turbulent heating from the ground and turbulent cooling due to vertical entrainment. Close to the surface, the sum of the potential temperature tendencies due to resolved horizontal and vertical advection is about 2 orders of magnitude smaller than the individual components. Adding the subgrid-scale diffusion yields a total tendency that is another 3 orders of magnitude smaller.

The circumstance of large and counteracting budget components adding up to a relatively small total tendency makes the budget calculation sensitive to approximations. While the sum of all forcing terms in WRFlux agrees to very high precision with the actual model tendency, we could show that approximations based on a lower-order advection operator or a numerically inconsistent formulation of the coordinate transformation lead to large residuals in the budget and noticeable differences in the tendency profiles. When looking at cross-section plots, the differences between the budget calculation methods are hardly noticeable. Nevertheless, a budget analysis tool that yields large residuals is unreliable. In general, if the residual is large, we do not know whether the individual forcing terms are more or less reliable and only the sum is erroneous or whether the forcing terms are not trustworthy either due to approximations or software bugs. Therefore, a closed budget as achieved by WRFlux is essential. This requires the budget calculations to be consistent with the model numerics.

WRFlux expands the approach of

the reasons for the unclosed surface energy balance often reported in field studies

the evolution of thermal updrafts in mountainous terrain that are subject to lateral and vertical turbulent entrainment

the exchange of heat and moisture between the boundary layer of a valley and the free troposphere

A conceivable extension for WRFlux is the inclusion of further budget variables, such as the mixing ratios of other water species or of a passive tracer.

The Jacobian matrix of the transformation from the Cartesian coordinate system

The inverse of

WRFlux is available at

The post-processed,

MG developed the theoretical framework and the software package, ran and analyzed the example simulation, and prepared the paper. StS and MWR supervised the work and reviewed and edited the paper extensively. StS acquired the funding and administers the project.

The contact author has declared that neither they nor their co-authors have any competing interests.

Publisher's note: Copernicus Publications remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

The computational results presented have been achieved using the Vienna Scientific Cluster (VSC).

We would like to thank Lukas Umek, Alexander Gohm, and Wiebke Scholz for their suggestions and the many fruitful discussions and Lukas Umek for providing his code (published in

This research has been supported by the Austrian Science Fund (grant no. P30808-N32).

This paper was edited by James Kelly and reviewed by three anonymous referees.