User Input Variables

Overview

A flexible file-based interface is provided to pass user inputs to the cgcam code. Prior to a cgcam run, the user edits the input file to reflect the desired behavior and then cgcam reads this file upon execution. By default, cgcam will read input from the file cgcam.inp [1] and, in this case, an execution command like 'mpirun -np 128 cgcam' will cause cgcam to read input from cgcam.inp. The user can also place inputs in a custom file, say case01.inp for example. In this case the file name needs to be mentioned on the execution command line, e.g. 'mpirun -np 128 cgcam case01.inp'

[1]	Cgcam will also look for, and read input from the file input.dat if cgcam.inp does not exist. This functionality is for legacy support and is thus discouraged for new runs. Support for this option may be removed in the future.

The input file has a simple structure as illustrated by the example below:

Nx            100          Number of points in x
Ny            100          Number of points in y
Nz            48           Number of points in z
i_grid        3            0-general grid, 1-Cartesian, 2-general in xz plane, 3-terrain
# comments can be added like this
i_restart     0            0-fresh start, 1-read restart
nt_restart    000000       Time step for restart file
#n_steps       1000         Number of time steps
n_steps       10           Number of time steps
n_skip_h      10           Skip factor for history output
n_skip_p      10           Skip factor for planes output
n_skip_v      1000         Skip factor for volumes output

More extended comments can be placed at the bottom of the file (like this)
if separated from the input section by a blank line.  The '#' symbol is not
required by this construct.

Each line consists of a keyword, value, and optional description. The keywords are case-insensitive and the numerical values can take any desired format (e.g. 1, 1.0, 1.00000, 1.0e+00, etc.). Inputs can also be ordered arbitrarily within the file. The only restriction is that the keyword begin in column 1, and that there be no blank lines within the input variable specification section. This latter feature can be used to advantage in order to place an extended comment block at the bottom of the file, as illustrated in the example above. Comments can also be included within the input variable section by placing the '#' character in column 1. This feature provides an easy mechanism for keeping track of inputs that might have been changed temporarily for testing purposes. Such a use of this feature is shown in the example above for the input n_steps.

Cgcam does not require the use of any specific system of units - the only requirement is that all inputs be consistent with a chosen system. Obviously the chosen unit system applies to both the grid (grid.dat) and the user inputs (cgcam.inp). A common mistake would be to specify the grid in units of km (instead of m) when the SI unit system is in use. Note that Non-dimensional inputs are easily accommodated by consistently normalizing all inputs by a fixed length, time (or velocity), and any two thermodynamic variables.

A short description of all possible user inputs is given in the following two sections. The vast majority of possible inputs are optional, meaning that sensible values will be assumed if the user chooses not to specify them explicitly. This feature allows for a compact input file and ensures that sensible values are chosen for inputs that the user does not care to understand fully. A few inputs are required, however, and the code will halt with an error if any one of these are missing. Certain optional inputs may be dynamically promoted to required based on the values of other input parameters. For example, if the user sets i_cfl=0 to signify that the code should should use a fixed time step, then the formerly optional argument dt0 (the fixed time step) will be marked as required.

Required Input Parameters

The following input parameters must appear in the input file.

Number of grid points, grid type, and number of time steps

The number of mesh points and the grid type must be consistent with the data in the grid file (grid.dat). n_steps is the number of time steps to execute for the current run.

Nx:Number of points in x. Ny:Number of points in y. Nz:Number of points in z. i_grid:Grid type (see table below) n_steps:Number of time steps.

Flags used for the grid type (i_grid)

i_grid	Grid type
0	General curvilinear
1	Cartesian
2	General curvilinear in x and z, Cartesian y
3	Cartesian in x and y with Terrain at the lower boundary

Fluid state

The following parameters specify the thermodynamic state at the reference altitude z0.

z0:Reference altitude. rho_o:Density at the reference altitude z0. To:Temperature at the reference altitude z0. vis:Dynamic viscosity at the reference altitude z0. Pr:Prandtl number (fixed with altitude). gamma_gas:Specific heat ratio (fixed with altitude). R_gas:Gas constant (fixed with altitude). grav:Gravitational acceleration (fixed with altitude).

Boundary conditions

iubc_x1:Upstream velocity bc flag (see table below). iubc_x2:Downstream velocity bc flag (see table below). iubc_y1:Right lateral velocity bc flag (see table below). iubc_y2:Left lateral velocity bc flag (see table below). iubc_z1:Lower velocity bc flag (see table below). iubc_z2:Upper velocity bc flag (see table below). itbc_x1:Upstream temperature bc flag (see table below). itbc_x2:Downstream temperature bc flag (see table below). itbc_y1:Right lateral temperature bc flag (see table below). itbc_y2:Left lateral temperature bc flag (see table below). itbc_z1:Lower temperature bc flag (see table below). itbc_z2:Upper temperature bc flag (see table below).

Flags used for boundary conditions (iubc and itbc)

Flag	Velocity	Temperature
0	No stress	Adiabatic
1	No slip	Isothermal
2*	Transpiration	Transpiration
3*	Radiation	Radiation
4*	Inflow/outflow	Inflow/outflow
5	Periodic	Periodic
6	Extrapolation	Extrapolation
7*	Use forcing	Use forcing
8+	Characteristic	Characteristic
9	Free stream	Free stream
15	Branch cut	Branch cut

* Not currently implemented. + Currently only implemented in the z-direction.

Although inflow/outflow and characteristic boundary conditions are currently not available in the horizontal directions, these can effectively be created through the use of periodic boundary conditions coupled with sponges (see Sponge layers at boundaries). The sponges work to restore the solution to the background state near the boundaries and thus waves and other disturbances will appear to pass through in a manner similar to characteristic boundary conditions. Similarly, the solution at an inflow boundary will match the background state, which effectively becomes the inflow conditions. The periodic conditions do not really impose any additional constraint on the solution, as the sponges make the solutions equal on opposing boundaries. When the periodic/sponge combination is in use, it is best to think of the effective boundary as being the location where the sponge begins and then to disregard the solution in the sponge region, as it is non-physical.

Optional Input Parameters

Cgcam responds to a large number of optional parameters. Many of these will activate optional features in the code, whereas others will change the solver characteristics.

Geometric Parameters

z1_fade:Upper altitude where terrain affects the mesh. Default value is dynamically set to the upper boundary position. i_body_beg:i index for the start of the branch cut for a C mesh. Default value is 0. i_body_end:i index for the end of the branch cut for a C mesh. Default value is 0.

Time stepping

i_cfl:Time step control flag: 0 for fixed dt, 1 for fixed cfl. Default value is 1. dt0:Fixed time step (used when i_cfl = 0). Default value is 0.01. cfl0:Fixed CFL (used when i_cfl = 1). Default value is 0.8. nrk_max:Time stepping scheme flag: 1-Euler, 2-RK2, 3-RK3. Default value is 3. i_restart:Restart flag: 0-fresh start, 1-read restart. Default value is 0. nt_restart:Time step for restart file. Default value is 0. nt_scale:Scale factor for the time step counter. Possible values are 1, 100, 1000. Default value is 1.

Additional flow state parameters

grav_s:Pseudo-gravity acting on the scalar field. Default value is 0.0.

Background fields

By default cgcam will make use of background flow and thermodynamic states that are vary only in the vertical direction. It is also possible to specify space- and time-varying states via the data assimilation facility. Here we describe only the default profile-based method. See section Data Assimilation Facility for details on the data assimilation scheme.

The background thermodynamic state can either be read from the file background.wind (using i_read_b=1), or generated internally using the i_background input variable. Similarly, the background wind profile can either be read from the file background.wind (using i_read_w=1), or generated internally using the i_wind input variable. The internal generation options will be described first, then the background.[state,wind] file structure.

i_read_b:Background thermodynamic state input flag: 1-read the background state, 0-generate internally. Default value is 0. i_read_w:Background wind input flag: 1-read the background wind, 0-generate internally. Default value is 0. i_background:Internally-generated background thermodynamic state type (used when i_read_b=0). See the table below for flag values. Default value is 0. i_wind:Internally-generated background wind type (used when i_read_w=0). See the table below for flag values. Default value is 0. lapse:Background temperature lapse rate. Default value is 0.0. lapse_pot:Background potential temperature lapse rate. Default value is 0.0. Uo:Constant x-directed velocity used by some background wind types. Default value is 1.0. Vo:Constant y-directed velocity used by some background wind types. Default value is 0.0. U_wind0:Velocity scale used by some background wind types. Default value is 0.0. U_wind1:Velocity scale used by some background wind types. Default value is 0.0. wind_cent_z:Center for wind profile used by some background wind types. Default value is 0.0. wind_width_z:Width for wind profile used by some background wind types. Default value is 1.0e+9. i_shear_dir(1:3):  Direction for shear for up to three different shear layers. Default value is 0.0. shear_cent(1:3):  z location for the center of up to three deferent shear layers. Default value is 0.0. shear_width(1:3):  Half the velocity change across up to three deferent shear layers Default value is 1.0e+9. shear_vel(1:3):Half the velocity change across up to three deferent shear layers Default value is 0.0. i_smooth_wind:Set to 1 to smooth the wind profiles near an inviscid boundary. Default value is 0.0 rot_coords:Use to specify the winds as zonal/meridional when the computational domain is rotated by rod_coords degrees from NSEW. Default value is 0.0. n_scalar:Number of passive scalars to include (currently limited to 1) The scalar field will be initialized with a linear variation in z. Default value is 0.

Flags used for specified background thermodynamic profiles (i_background)

i_background	Thermodynamic state specification
-3	Temperature profile read from file background.wind.
0	Isothermal at value To
1	Fixed temperature lapse rate (using input lapse)
2	Fixed potential temperature lapse rate (using input lapse_pot)
3	Temperature profile specified by hard-coded function
4*	Specified potential temperature profile
5*	Specified N^2 profile
6	Density profile specified by hard-coded function
7*	Not currently defined
8	Stability duct (see below for details)

* Not currently implemented.

Note that all i_background values specify just one thermodynamic profile. The remaining profiles are computed from the hydrostatic balance and the ideal gas law.

When i_background=8, the temperature profile is set according to

\[T(z) = To\{ 1.0 + amp[ \tanh(s(z-duct\_cent\_z)/duct\_width\_z) + 1.0 ] \}\]

where

\[\begin{split}\begin{eqnarray*} amp & = & (c3-c1duct\_width\_z/scale\_h)/(s-c3)\\[0.1in] scale\_h & = & R\_gasTo/grav\\[0.1in] c3 & = & duct\_N2duct\_width\_z/grav\\[0.1in] s & = 2.5 \end{eqnarray*}\end{split}\]

Flags used for specified background wind profiles (i_wind)

i_wind	Wind specification
0	Constant (x,y) winds at values (Uo,Vo)
1	Linearly-varying x-directed wind from value U_wind0 at the lower boundary to U_wind1 at the upper boundary.
2*	Not currently used
3*	Not currently used
4	Gaussian x-directed jet with standard deviation wind_width_z, centered at wind_cent_z, having a maximum velocity of U_wind1, and velocity U_wind0 far away from the jet center.
5	X-directed tanh shear layer having velocity U_wind0 at the lower boundary, U_wind1 at the upper boundary, centered at wind_cent_z, and having width wind_width_z
6	The superposition of up to three tanh shear layers in either the x- (i_shear_dir[1:3]=13) or y-direction (i_shear_dir[1:3]=23), having a half velocity change of shear_vel[1:3], having centers shear_cent[1:3], and widths shear_width[1:3].

* Not currently implemented.

Scalar field

Currently cgcam supports a single scalar field, and this is initiated by setting n_scalar=1. The scalar field will be initialized with a linear variation in the z-direction.

Background.state file structure

When i_read_b=1, cgcam will read the background profiles from the file background.state. This file contains ASCII formatted data with either spaces, tabs. or commas separating the various columns. The file also contains a one-line header record that describes the fields. An example of a few lines of the file is given below:

#      z           rho           p            T          theta         N^2
-1.250000E+02 1.242443E+00 1.069744E+05 3.000000E+02 2.987905E+02  3.192997E-04
 1.250000E+02 1.207557E+00 1.039706E+05 3.000000E+02 3.012318E+02  3.193103E-04
 3.750000E+02 1.173650E+00 1.010513E+05 3.000000E+02 3.036930E+02  3.193103E-04
 6.250000E+02 1.140696E+00 9.821389E+04 3.000000E+02 3.061743E+02  3.193103E-04
 8.750000E+02 1.108666E+00 9.545617E+04 3.000000E+02 3.086759E+02  3.193103E-04

Here the columns are altitude, density, pressure, temperature, potential temperature and the buoyancy frequency squared. In order to facilitate boundary conditions in the vertical direction, cgcam requires background values at half a grid cell beyond the lower and upper boundaries. Thus it is best to extend the background profiles to these positions. If this is not done, cgcam will use extrapolation for these points. Note that only a single one of the thermodynamic profiles is unique, with the rest of them being related via the hydrostatic balance and the ideal gas law. For this reason, the background.state file really only needs to contain the altitude and one other data column. Currently cgcam will scan the header line, determine the temperature column, and then use this to recompute all other state variables. Thus, for the time being, the temperature must be contained in the background.state file. Cgcam will often interpolate the input temperature profile onto a z-point distribution that it considers optimal prior to re-computing the rest of the state variables. For reference, the full thermodynamic state at the cgcam-chosen sampling points will then be written to the file background.state_out

Background.wind file structure

When i_read_w=1, cgcam will read the zonal and meridional wind profiles, and optionally the temperature profile (when i_background=-3) from the file background.wind. This file contains ASCII formatted data with either spaces, tabs. or commas separating the various columns. The file also contains a one-line header record that describes the fields. An example of a few lines of the file is given below:

#     z             U             V             T
-1.250000E+02  1.795981E+01  0.000000E+00  3.000000E+02
 1.250000E+02  1.795981E+01  0.000000E+00  3.000000E+02
 3.750000E+02  1.795981E+01  0.000000E+00  3.000000E+02
 6.250000E+02  1.795981E+01  0.000000E+00  3.000000E+02

Including the temperature profile along with the wind is a convenient means to specify both the wind and the thermodynamic state in a single file. In this case i_read_b should be set to zero (or excluded from the input file so that it defaults to zero), and the i_background variable should be set to -3. As with the background.state file, the data should ideally extend a half grid cell below and above the vertical boundaries.

When inviscid boundary conditions are in use, the vertical derivatives of the mean winds are approximately zero at a solid surface. While cgcam will enforce this condition, it may result in kinks in the velocity profiles near the surface. If this is the case, then one can set i_smooth_wind=1 in the input file in order to smooth out any kinks.

By default cgcam will assume the the x-direction is zonal and the y-direction is meridional. There may be times where it is advantageous to rotate the coordinate system (in order to be aligned with a mountain range, for example), however. In this case one can either prepare the background.wind data taking the coordinate rotation into account, or let cgcam do the rotation internally using the rot_coords input. In the latter case, background.wind still contains zonal and meridional data and the output velocity data will also be in zonal/meridional coordinates. The rot_coords input is in degree measure, with a counter-clockwise rotation (when viewed from above) being taken as positive.

Cgcam will write the possibly-smoothed and rotated wind data, at its chosen sampling points to the file background.wind_out.

Initial conditions

The background wind and thermodynamic profiles discussed in the Background fields section above can be modified through the superposition of various flow elements, and the relevant inputs controlling these are described below. The noise smoothing options (n_filt_xy and n_filt_z) damp the otherwise white-noise spectrum at high wavenumbers. The rms of the damped white noise will equal flct_u and flct_T. The smoothed noise can also be damped further near the boundaries by changing the value of the hard-coded parameter damp_near_edges=.true. in the file initial_field.f.

flct_u:Initial velocity rms perturbation. Default value is 0.0. flct_T:Initial temperature rms perturbation. Default value is 0.0. n_filt_pass_xy:Number of initial noise filtering passes in the x and y directions. Default value is 6. n_filt_pass_z:Number of initial noise filtering passes in the z direction. Default value is 6. char_L:Reference length used by some initial condition types. Default value is 1.0. i_initial:Initial condition type (see table below). Default value is 0.

Flags used for Initial conditions (i_initial)

i_initial	initial Condition
0	Add smoothed white noise to the initial velocity and/or temperature field based on the values of flct_u, flct_T, n_filt_pass_xy, and | n_filt_pass_z.
4	Simple gravity wave
6	Compressible Couette flow
10	Gravity wave packet in z
11	Gravity wave packet in x and z
12	Gravity wave packet in x, y, and z
16	Taylor-Green vortex
17	Taylor-Green vortex, rotated

Output control

n_skip_h:Skip factor for history output. Default value is 0. n_skip_p:Skip factor for planes output. Default value is 0. n_skip_v:Skip factor for volumes output. Default value is 0. n_skip_s:Skip factor for sub-volume output. Default value is 0. n_skip_t:Skip factor for time-series output. Default value is 0. i_stat:Statistics generation control: 0-no stats, 1-new stats, 2-add stats to previous run. Default value is 0. i_beg_sub:i_index for the start of the sub-volume. Default value is 0. i_end_sub:i_index for the end of the sub-volume. Default value is 0. i_skip_sub:i_index skip factor for the sub-volume. Default value is 1. j_beg_sub:j_index for the start of the sub-volume. Default value is 0. j_end_sub:j_index for the end of the sub-volume. Default value is 0. j_skip_sub:j_index skip factor for the sub-volume. Default value is 1. k_beg_sub:k_index for the start of the sub-volume. Default value is 0. k_end_sub:k_index for the end of the sub-volume. Default value is 0. k_skip_sub:k_index skip factor for the sub-volume. Default value is 1. i_yz_plane[1-10]:  i index for yz plane [1-10]. Default value is 0. j_xz_plane[1-10]:  j index for xz plane [1-10]. Default value is 0. k_xy_plane[1-10]:  k index for xy plane [1-10]. Default value is 0. i_plane_dev:Mean definition for computing deviations to written to the planes data files: 0-use background winds and state, 1-compute instantaneous xy-averages. Default value is 0. pos_ts[1-9]:Coordinate location for time series. Default value is 0.0. i_beg_ts[1-9]:i_index for the start of the time series. Default value is 0. i_end_ts[1-9]:i_index for the end of the time series. Default value is 0. j_beg_ts[1-9]:j_index for the start of the time series. Default value is 0. j_end_ts[1-9]:j_index for the end of the time series. Default value is 0. k_beg_ts[1-9]:k_index for the start of the time series. Default value is 0. k_end_ts[1-9]:k_index for the end of the time series. Default value is 0. i_dir_ts[1-9]:Direction of the normal to the time series plane. Default value is 0.

Gravity wave initial conditions

lambda_x:Gravity wave horizontal wavelength. Default value is 1.0. Gam:Ratio of gravity wave horizontal to vertical wavelength ratio. Default value is 1.0. omega:Gravity wave ground-based frequency. Default value is 0.0. amplitude:Gravity wave initial amplitude. Default value is 0.0. packet_cent_x:X-coordinate for the gravity wave packet center. Default value is 0.0. packet_cent_y:X-coordinate for the gravity wave packet center. Default value is 0.0. packet_cent_z:Z-coordinate for the gravity wave packet center. Default value is 0.0. packet_width_x:Initial packet width in x. Default value is 0.0. packet_width_y:Initial packet width in y. Default value is 0.0. packet_width_z:Initial packet width in z. Default value is 0.0.

Scheme behavior

n_skip_filt:Skip factor for filtering. Default value is 0. i_diss:Artificial dissipation control: 1-use artificial dissipation, 0-do not. Default value is 0. eps_diss:Artificial dissipation scale factor. Default value is 0.0. i_hydrostat:Hydrostatic balance control: 0-compute it explicitly, 1-subtract the hydrostatic balance from the governing equations. Default value is 0. i_diff_meanT:Background temperature diffusion control: 0-allow the background temperature to diffuse, 1-do not allow. Default value is 0. i_diff_meanU:Background wind diffusion control: 0-allow the background wind to diffuse, 1-do not allow. Default value is 0.

Turbulence model

n_les:Turbulence model control: 0-DNS, 1-fixed constant Smagorinsky model, 2-dynamic model. Default value is 0. c_smag:Model constant for the Smagorinsky model (only used when n_les=1). Default value is 0.01. i_dm_avg:Dynamic model averaging control (only used when n_les=2): 0-no averaging, 1-line average in y, 2-plane average in x and y, 3, volume average in x, y, and z, 12-local plane average in x and y. Default value is 0. idm_beg:i index for the start of the dynamic model averaging. Default value is 2. idm_end:i index for the end of the dynamic model averaging. Default value is dynamically computed to be Nx+1. jdm_beg:i index for the start of the dynamic model averaging. Default value is 2. jdm_end:i index for the end of the dynamic model averaging. Default value is dynamically computed to be Ny+1. kdm_beg:i index for the start of the dynamic model averaging. Default value is 2. kdm_end:i index for the end of the dynamic model averaging. Default value is dynamically computed to be Nz+1. n_dm_avg_x2:Number of points in x to average the equations for the the dynamic model coefficients when i_dm_avg=12. Default value is 1. n_dm_avg_y2:Number of points in y to average the equations for the the dynamic model coefficients when i_dm_avg=12. Default value is 1. n_dm_avg_z2:Number of points in z to average the equations for the the dynamic model coefficients when i_dm_avg=12. Default value is 1.

Sponge layers at boundaries

i_sponge:Binary sponge switch x1x2y1y2z1z2 [xyz][12]=[0,1]. Default value is 0. w_spongex1:Sponge width at x=x1 boundary. Default value is 0.0. w_spongex2:Sponge width at x=x2 boundary. Default value is 0.0. w_spongey1:Sponge width at y=y1 boundary. Default value is 0.0. w_spongey2:Sponge width at y=y2 boundary. Default value is 0.0. w_spongez1:Sponge width at z=z1 boundary. Default value is 0.0. w_spongez2:Sponge width at z=z2 boundary. Default value is 0.0. t_spongex1:Sponge time constant at x=x1 boundary. Default value is 0.0. t_spongex2:Sponge time constant at x=x2 boundary. Default value is 0.0. t_spongey1:Sponge time constant at y=y1 boundary. Default value is 0.0. t_spongey2:Sponge time constant at y=y2 boundary. Default value is 0.0. t_spongez1:Sponge time constant at z=z1 boundary. Default value is 0.0. t_spongez2:Sponge time constant at z=z2 boundary. Default value is 0.0.

Forcing

i_noise:Random noise addition flag: 0-no noise, 1-add noise at each time step (currently deactivated), 2-add noise upon restart. The white noise rms will be flct_u nd flct_T. Default value is 0. i_force:Forcing control: 0-no forcing, 1-linear ramp, 2-half Gaussian ramp, 3-Gaussian ramp, 4-tanh ramp, 5-sinusoid with 1 period, 6-sinusoid for all time. Default value is 0. i_damp_wind:Initial wind damping control: 1-damp the wind initially near the surface and then only force this region, 0-no near-surface damping. Default value is 0. zc_damp_wind:Altitude for the center of the near_surface wind damping. Default value is 1.0. zw_damp_wind:Width for the near-surface wind damping. Default value is 1.0. t_force:Forcing time scale. Default value is 0.0