Aether Cube Sphere

This document describes the DART interface to the Aether ionosphere-thermosphere model in its cube sphere implementation.

In addition to the standard DART programs associated with a given model, this interface creates two additional programs for the Aether cube sphere: aether_to_dart, and dart_to_aether. It also has a program in the developer_tests directory, test_aether_grid that tests the geometry related aspects of the grid, verifies model interpolation assumptions, and compares to a template filter_input_file.

aether_to_dart

This program reads Aether restart files and combines them into a single filter input file for DART. This program reads entries from two namelists in input.nml:

In &aether_to_dart_nml:

  • aether_file_directory Path to the Aether restart files

  • dart_file_directory Path to the where filter_input files will be created

In &transform_state_nml:

  • np Number of grid points across each cube sphere face (no halos)

  • nblocks Total number of Aether grid files

  • nhalos Number of Aether halo rows

  • scalar_f10_7 True if F10.7 is a scalar in the DART state vector, false means it is has a value at each column.

Using aether_to_dart

When executing aether_to_dart a range of ensemble members must be specified as command line arguments:

aether_to_dart 1 10

This example would translate ensemble members 1 to 10. There are three types of Aether netcdf restart files required in the Aether input directory. The first are grid files that include the metadata that defines the location of Aether grid points and halos for each block. These file are named grid_g####.nc where #### is the number of the block, starting from 0000. The second are neutrals files that contain the data for neutral quantities. There is one file for each block for each ensemble member. These are named neutrals_m&&&&_g#### where &&&& is the ensemble member starting from 0000 and #### is the block. The third are ions files named ions_m&&&&_g#### with the same numbering as the neutrals files. A single filter input file is created for each ensemble with the name filter_input_&&&& where &&&& is the ensemble number starting at 0001 (note the offset in numbering from the Aether files).

dart_to_aether

This program reads filter output files and inserts the data into Aether block restart files. This program reads entries from two namelists in input.nml”

In &dart_to_aether_nml:

  • dart_file_directory Path to the filter_output files that are read

  • aether_file_directory Path to the Aether restart files that will be modified

In &transform_state_nml:

  • np Number of grid points across each cube sphere face (no halos)

  • nblocks Total number of Aether grid files

  • nhalos Number of Aether halo rows

  • scalar_f10_7 True if F10.7 is a scalar in the DART state vector, false means it is has a

Using dart_to_aether

When executing dart_to_aether a range of ensemble members must be specified as command line arguments:

./dart_to_aether 1 10

This example would translate ensemble members 1 to 10. A single filter input file is read for each ensemble with the name filter_output_&&&& where &&&& is the ensemble number starting at 0001. The results are written into previously created aether neutrals and ions files that are named as described above for aether_to_dart. The Aether directory must also contain grid files that contain the metadata for the Aether restarts. It is possible to overwrite the Aether files in the same directory that was used for input to aether_to_dart, or to copy the files from that directory to a new directory to be updated by dart_to_aether.

Using perfect_model_obs or filter with the aether model_mod

Simple example workflow

This section describes a simple workflow that demonstrates and tests the capabilities of the DART/Aether system. To do this simple example, you will need to contact Jeff Anderson, jla@ucar.edu, or dart@ucar.edu to request a copy of the file TEST_INPUT.tar.gz. Place this file in the models/aether_cube_sphere/ directory and execute the command tar -xzvf TEST_INPUT.tar.gz to create the TEST_INPUT directory. that contains a small set of Aether grid input files. There are 6 blocks, one covering each face of the cubed sphere. The neutrals files contain two variables, O2 and Temperature. The ions files contain two variables, O2+ and N2+. The TEST_INPUT directory only contains a single ensemble member for the ions and neutrals files.

Demonstration steps:

1. In the models/aether_cube_sphere directory, execute the matlab script perturb_aether_ensemble.m. This generates 10 ensemble members in the TEST_INPUT directory. All variables are perturbed so that the prior correlations between any two variables are one.

2. In the aether_cube_sphere direcctory, copy the TEST_INPUT directory to the TEST_OUTPUT directory, cp -rf TEST_INPUT TEST_OUTPUT.

3. Build all of the DART programs by executing quickbuild.sh nompi in the aether_cube_sphere/work directory.

  1. Run aether_to_dart 1 10 in the aether_cube_sphere/work directory.

5. Run perfect_model_obs in the aether_cube_sphere/work directory. This creates synthetic observations using the file obs_seq.in for metadata and creating the file obs_seq.out.

  1. Run filter in the work directory to do a single step ensemble assimilation.

7. Run dart_to_aether 1 10 in the work directory to create updated aether restart files in the aether_cube_sphere/TEST_OUTPUT directory.

8. Use matlab script plot_filter_lat_lon.m in the aether_cube_sphere directory to interactively view the increments for different variables for the DART filter_input_&&&&.nc and filter_output_&&&&.nc files

9. Use matlab script plot_aether_lat_lon.m in the aether_cube_sphere directory to view increments between the input aether restart files in the TEST_INPUT directory and the updated aether restart filtes in the TEST_OUTPUT directory.

The obs_seq.in file defines the observations that are created by perfect_model_obs and then assimilated by filter. In this case, there are 6 observations, one each of temperature, density of O2, density of O2P, density of N2P, a ground station GPS vertical total electron content, and a slant GPS total electron content. Each is at a different horizontal location and the first 4 are at different vertical locations.

The file create_obs_seq.input in the aether_cube_sphere directory contains input that can be read by the program create_obs_sequence to create the default obs_seq.in file

Work in Progress

Time: The method by which model time is read into DART has not been finalized at this time. All tests to date use time that is manually inserted into the perfect_model_obs and filter namelist entries init_time_days and init_time_seconds. The specifics of the how time is included in Aether input files needs to be clarified so that the model_mod can read this directly from the filter restart files. Aether is not currently using time that is consistent with any calendar supported by DART, so this may require code in aether_to_dart.f90 that translates the aether time to a time that DART understands.

F10.7: Aether restart netcdf files do not currently include parameter values like F10.7. For now, the aether_to_dart and dart_to_aether programs do not do not do input/output with Aether. Default (meaningless) F10.7 values are generated by transform_state_mod.f90. Once Aether modelers decide where the F10.7 value will come from, code will need to be added to read the F10.7 value in model_to_dart and write it in dart_to_model, but obvious hooks are available in transform_state_mod.f90. This module implements the basics of two ways to do F10.7 estimation. The first is to have a single scalar value of F10.7 in the DART state. Subroutine get_state_meta_data provides some initial suggestions for the location associated with a scalar F10.7 that are taken from Alexey Morozov’s work in GITM. Because this requires the time, which is not yet available from Aether, this requires additional implementation. Aether scientists also need to confirm that the subsolar point is the right choice for a location. Alexey also implemented a different localization algorithm for F10.7 in GITM. Aether scientists should work with DART experts to determine if and how this would be implemented in Aether. Under namelist control, aether_to_dart can also treat F10.7 as a horizontally distributed variable, basically copying the same value of F10.7 to each horizontal column. The value at each column is updated and dart_to_aether currently just averages the posterior values. Other choices for weighted averages are scientifically interesting and could be explored by aether/DART collaborations.

VTEC: The established forward operator for vertically integrated electron content in DART is found in the observations/forward_operators/obs_def_upper_atm_mod.f90. It assumes that the DART state includes a 3D field with quantity QTY_DENSITY_ION_E and that the state also includes the geometric height of each grid point in QTY_GEOMETRIC_HEIGHT. The subroutine get_expected_gnd_gps_vtec integrates the density in a column. This subroutine was originally developed for GITM and then extended for TIEGCM. Unlike GITM, Aether does not include the ION density in its restart netcdf files. The aether_to_dart.f90 sums up the density of all variables in the ions files that have units of /m3 and puts this into the filter_input file that is created. Aether model experts should verify both the creation of the density field and the way that a vertical integral is computed to confirm that these are consistent with the model and the available observations. Note that there are other electron content forward operators that may also need to be evaluated by model experts before use.

Slant VTEC: There is a subroutine called get_expected_slant_gps_vtec in /observations/forward_operators/obs_def_upper_atm_mod.f90. It does exaclty the same thing as the vtec described above. However, it includes extended metadata in the obs_seq files. These are two locations descriptions, one for the satellite postion (lon, lat, height), and one for a ground point (lon, lat, height). One way to implement a slant vtec forward operator would be to trace a ray between the satellite and the ground and get the density at each level along the ray. Other ways of describing the geometry of the ray may be more appropriate. Aether developers and observation experts should be able to use the example code to easily implement the forward operator once the exact method for tracing the ray from the satellite is implemented.

Testing the grid computations

The program test_aether_grid in developer_tests/aether_grid can be run with the namelist setting used for a filter run to verify the geometry in the model_mod and to confirm consistency with the aether template file selected by the template_file entry in the model_nml namelist. Note that an aether template filter file must have been created in the aether_cube_sphere/work directory before this test is run.