JSON Structure Details

JSON Structure Details

Input JSON structure

This file describes the JSON structure of namelist settings and matrices data to generate intermediate files for the WRF forecast process.

Initial considerations

  • Any value present in the documentation of namelist (.wps and .input) can be defined by the user. To do this just add the name of the setting (as referred in namelist documentation) and its desired value in the right group and it will be added or changed and placed in the namelist file.

  • There are certain groups of namelist files that have default settings and values. However, if a setting or value is specified for that group in the JSON file, then all default settings are ignored, and it is mandatory to specify all other settings that must be contained in that group in the JSON file (see the default namelist configuration bellow).

  • There are values that are inferred in the namelist files according to the data entered by the user. These values will be marked as “optional” but once the user has set their value, the inferred value is discarded.

  • The user can add groups and their settings that want to see reflected in the namelist files, just add the desired groups and it’s settings in the namelist_wps or namelist_input groups in JSON file.

  • All settings presented in this document are validated in terms of data type, size and format. The other settings available for the namelist files are the sole responsibility of the user.

  • If the user uses nested domains then all settings must be defined manually.

  • From now on, the files namelist.wps and namelist.input will be referred to as wps and input, respectively

The value types of the JSON file will be converted to the accepted format of the namelist files. Below is an example of each value type and their result in the namelists file.

The JSON configuration bellow…

{
"group_name": {
 "real_value": 1.0,
 "string_value": "string",
 "boolean_value": true,
 "list_value": [10, 20, 30]
}
}

…will produce the following namelist configuration lines:

&group_name:
real_value: 1.0,
string_value: 'string',
boolean_value: .true.,
list_value: 10, 20, 30,
/

Below is the configuration generated for the files wps and input according to the default values for each settings groups. If no definition is provided for these groups, the following will be generated:

NOTES:

  • please remember that if any setting is defined in JSON for the groups shown below, then all desired settings and respective values must be defined for that group.

  • settings marked with “*” mean that their value is repeated for each nested domain (max_dom). #### wps: ..

    ungrib group:

    &ungrib
    out_format = 'WPS',
    prefix = 'FILE',
    /
    


metgrid group:

&metgrid
fg_name = 'FILE',
io_form_metgrid = 2,
/

physics group:

&physics
*mp_physics = 3,
*ra_lw_physics = 1,
*ra_sw_physics = 1,
*radt = 30,
*sf_sfclay_physics = 1,
*sf_surface_physics = 2,
 num_soil_layers = 4,
*bl_pbl_physics = 1,
*bldt = 0,
*cu_physics = 0,
*cudt = 0,
 isfflx = 1,
 ifsnow = 0,
 icloud = 1,
 surface_input_source = 1, 2,
 num_land_cat = 24,
*sf_urban_physics = 0,
 sf_ocean_physics = 0,


dynamics group:

&dynamics
 w_damping = 0,
*diff_opt = 1,
*km_opt = 4,
*diff_6th_opt = 0,
*diff_6th_factor = 0.12,
 base_temp = 290.0,
 damp_opt = 0,
*z_damp = 5000,
*dampcoef = 0,
*non_hydrostatic = .true.,
*moist_adv_opt = 1,
*scalar_adv_opt  = 0,
/


bdy_control group:

&bdy_control
 spec_bdy_width = 5,
 spec_zone = 1,
 relax_zone = 4,
*specified = .false.,
*nested = .false.,
/


namelist_quilt group:

&namelist_quilt
nio_tasks_per_group = 0,
nio_groups = 1,
/


Other groups and definitions can be added to the name lists. Let’s see the example below:

The user wants to add the group “mod_levs” in wps and define the pressure values for the vertical layers through the “press_pa” setting present in that group. JSON should then be:

...
{
 "namelist_wps": {
   "share": {
     ...
   },
   "geogrid": {
     ...
   },
   "mod_levs": {
     "press_pa": [201300, 200100, 100000, 95000, 90000, 85000, 80000, 75000, 70000, 65000, 60000, 55000, 50000, 45000,
       40000, 35000, 30000, 25000, 20000, 15000, 10000, 5000, 1000]
 }
}
}

that will produce the following namelist.wps file configuration:

&share
...
/
&geogrid
...
/
...
&mod_levs
press_pa = 201300, 200100, 100000, 95000, 90000, 85000, 80000, 75000, 70000, 65000, 60000, 55000, 50000, 45000,
           40000, 35000, 30000, 25000, 20000, 15000, 10000, 5000, 1000,
/

JSON configuration file

The JSON file is divided in 3 main groups:

  • grid_control: has the geo grid settings such as grid coordinates and resolution

  • namelist_wps: has all the wps file groups, settings and their values

  • namelist_input: has all the input file groups, settings and their values

grid_control

Set the geo grid settings

The following settings should be present in this group:

  • start_coordinates

  • coordinates_step

  • Type: list

  • Items count: 2

  • Items type: real value

  • Description: Set the start latitude and longitude of the geo grid in the world. The value should be a list with the latitude and longitude coordinates.
    Example: [-7.80, 41.98]

  • Type: int, float, list

  • Max items count: 2

  • Items type: real value

  • Description: Set the latitude and longitude grid step (grid resolution). The value can be a list with the latitude and longitude step.
    Example: [0.5, -0.5]

namelist_wps

Sets the groups and it’s settings that must be defined in wps. The names of the groups and each group settings should respect the wps structure and best practices

The following settings are should be present in this group:

  • share

  • geogrid

This group defines the wps share group settings (read more namelist best practices: share)

NOTE: Any setting that needs to be present in wps can be added to this group. Some fields may have static values, so changes in JSON are not reflected in the wps

The following settings should be present in this group:

  • start_date

  • end_date

  • interval_seconds

  • Type: string

  • Item type: date time in ISO format (YYYY-MM-DD hh:mm:ss)

  • Description: specifies the beginning date and time of the simulation.

  • Type: string

  • Item type: date time in ISO format (YYYY-MM-DD hh:mm:ss)

  • Description: specifies the beginning date and time of the simulation.

  • Type: int, float

  • Description: specifies the temporal interval in which the input data are available (in seconds). If the data are available every 3 hours, this should be set to 10800, for example.

This group defines the wps share group settings (read more namelist best practices: share)

NOTE: Any setting that needs to be present in wps can be added to this group. Some fields may have static values, so changes in JSON are not reflected in the wps

The following settings should be present in this group:

  • e_we

  • e_sn

  • dx

  • dy

  • map-proj

  • ref_lat

  • ref_lon

  • truelat1

  • truelat2

  • stand_lon

  • Type: int, list

  • Description: specifies each domain’s full west-east and south-north dimensions (or grid spaces)

  • Type: int, float, list

  • Description: specifies the grid distance (or grid resolution) in the x and y directions. Value in meters for Lambert, Polar and Mercator projections and degrees for Lat-Lon projection

  • Type: string

  • Possible values: lat-lon, lambert, polar, mercator

  • Description: specifies the projection of the simulation domain (all domains will use this defined projection)

  • Type: int, float

  • Description: specifies the latitude and longitude of a location whose location in the simulation is known

  • Type: int, float

  • Description: specifies the first true latitude for the Lambert projection, or the true latitude for the Polar projection, or the Mercator projection

  • Type: int, float

  • Description: specifies the second true latitude for the Lambert conformal conic projection

  • Type: int, float

  • Description: specifies the longitude that is parallel with the y-axis in conic and azimuthal projections

namelist_input

Sets the groups and it’s settings that must be defined in input. The names of the groups and each group settings should respect the input structure and best practices

NOTE: In addition to the default settings, the values of the “time_control” and “domains” groups are inherited from wps, although user values can be set

JSON matrices file

Set the WRF input data matrices The data required by the ungrib must be respected.

The following settings should be present in this group:

  • 2D

  • 3D

2D

This group defines the ungrib 2D data matrices

The following settings should be present in this group:

  • PSFC

  • PMSL

  • SKINTEMP

  • SOILHGT

Some matrices require extra data beyond their data values. For this, the group “info” must be added, even if empty (not recommended). Supported matrices are PSFC, PMSL, SKINTEMP, SOILHGT. For other 2D matrices, “info” group should be defined as follows:

...
{
 "2D": {
   "SM000010":{
     "info": {
       "name": "Soil moisture",
       "units": "m3 m-3",
       "pressure_level": "200100"
     },
     "data": [...
     ...]
   },
  ...
 }
}
  • Type: string

  • Default value: “unknown”

  • Description: specifies the name of data represented by the matrix

  • Type: string

  • Default value: “unknown”

  • Description: specifies the units of matrix data

  • Type: string

  • Default value: “200100”

  • Description value: should be used “200100” for surface data and “201300” for sea level pressure data

NOTE: Any other matrix can be added here, as long as it respects the data accepted by the WRF and the defined JSON structure

Each group defines the ungrib 2D matrix data and/or info

The following settings should be present in this groups:

  • data

  • Type: list

  • Description: specifies matrices (one per time interval) data

Example:

{
  "2D": {
    "PSFC": {
      "data": [  // matrices (one per time interval)
          // matrix for interval 0
          [
            [1, 6, 3, 6, 6, ...],
            [7, 8, 9, 1, 4, ...],
            ...
          ],
          // matrix for interval 1
          [
            [1, 5, 4, 9, 1, ...],
            [3, 0, 4, 6, 0, ...],
            ...
          ],
          ...
        ]
      }
   }
}

3D

This group defines the ungrib 3D data matrices

The following settings should be present in this group:

  • pressure_levels (optional)

  • TT

  • RH

  • UU

  • VV

  • GHT

  • Type: list

  • Description: specifies the pressure levels in hectopascals (Pa) of 3D matrices

  • Type: list

  • Description: specifies matrices (one per time interval) data

Example:

{
  "3D": {
    "TT": [  // matrices (one per time interval)
            // 3D matrix for interval 0
            [
              // matrix for level 0
              [
                [1, 6, 3, 6, 6, ...],
                [7, 8, 9, 1, 4, ...],
                ...
              ],
              // matrix for level 1
              [
                [1, 3, 5, 2, 8, ...],
                [1, 6, 3, 8, 3, ...]
                ...
              ],
              ...
            ],
            // 3D matrix for interval 1
            [
              // matrix for level 0
              [
                [1, 6, 3, 6, 6, ...],
                [7, 8, 9, 1, 4, ...],
                ...
              ],
              // matrix for level 1
              [
                [1, 3, 5, 2, 8, ...],
                [1, 6, 3, 8, 3, ...]
                ...
              ],
              ...
            ],
            ...
        ]
      }
   }
}