PROGRAM restart_file_tool

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: restart_file_tool.html 6380 2013-08-05 23:47:11Z nancy $

NAMELIST / MODULES / FILES / REFERENCES / ERRORS / PLANS / TERMS OF USE

Overview

Utility program to alter the data timestamp in a DART restart file, to add or remove a model-advance time, to convert from ASCII to binary or back, and to either split or combine ensemble restarts into one or multiple files.

DART restart files contain a single timestamp with the model time at which the data was generated, followed by the model data. Each file can be ASCII or binary format, and can contain a timestamp and data for a single ensemble member or repeated timestamp/data blocks for multiple ensemble members.

The files named temp_ic or assim_model_state_ic.0001 contain the same information as a normal restart file but the data for each ensemble is preceeded by an additional timestamp which indicates to the model advance code how far in time the model needs to run. This program can add or remove these timestamps, in addition to altering the normal data timestamps.

Note that the output from the model advance, temp_ud or assim_model_state_ud.0001, are normal restart files without the extra timestamp.

Namelist interface &restart_file_tool_nml must be read from file input.nml.

ASCII restart files are portable across different hardware architectures (these days, most notably between IBM PowerX chip-based systems and anything else including all Intel/AMD systems). However, they are larger in size, and can lose precision when converting from binary to ASCII and back. Binary restart files can be moved even between incompatible systems by using the 'swabrestart' utility found in the $DART/utilities directory. See the extensive comment section at the top of that file for an explanation of the details of moving binary files between incompatible systems.

[top]

NAMELIST

This namelist is read from the file input.nml. Namelists start with an ampersand '&' and terminate with a slash '/'. Character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the namelist.

&restart_file_tool_nml 
   input_file_name              = "filter_restart",        
   output_file_name             = "filter_updated_restart",
   ens_size                     = 1,
   single_restart_file_in       = .true.,
   single_restart_file_out      = .true.,
   write_binary_restart_files   = .true.,
   overwrite_data_time          = .false.,
   new_data_days                = -1,  
   new_data_secs                = -1,
   input_is_model_advance_file  = .false.,
   output_is_model_advance_file = .false.,
   overwrite_advance_time       = .false.,
   new_advance_days             = -1, 
   new_advance_secs             = -1,
   gregorian_cal                = .true.,
   print_only                   = .false.
/


Item Type Description
input_file_name character Filename containing the DART restart data. If 'single_restart_file_in' is .true., this is the exact filename. If 'single_restart_file_in' is .false. this is the base name and '.ens_num' will be appended to each name before being opened.
output_file_name character Filename to be created. If 'single_restart_file_out' is .true., this is the exact filename. If 'single_restart_file_out' is .false. this is the base name and '.ens_num' will be appended to each name before being created.
ens_size integer Total number of ensemble members.
single_restart_file_in logical Whether the input filename contains a single ensemble member or multiple members concatinated in the same file.
single_restart_file_out logical Whether to create an output file which contains a single member or multiple members concatinated in the same file.
write_binary_restart_files logical Whether to write the data in ASCII or binary. The format of the input file will be detected automatically.
overwrite_data_time logical Whether to replace the timestamp in the input with a new time. If true, new_data_days and new_data_secs must both be set to valid values.
new_data_days integer Day number if replacing the data timestamp in the file.
new_data_secs integer Seconds if replacing the data timestamp in the file.
input_is_model_advance_file logical If true, this file was written to be read by a model advance conversion program and contains two timestamps (the time to advance to, and the current time).
output_is_model_advance_file logical Whether to write a file with two timestamps in output.
overwrite_advance_time logical Replace existing advance timestamp, or add an advance timestamp if output_is_model_advance_file is true. If true, new_advance_days and new_advance_secs must both be set to valid values.
new_advance_days integer Day number if replacing or adding a model advance timestamp in the file.
new_advance_secs integer Seconds if replacing or adding a model advance timestamp in the file.
gregorian_cal logical If model uses the Gregorian calendar, this program will print out the date in both day number and seconds, but also in calendar year/month/date etc format. Set to false if this model does not use this calendar. Does not affect the timestamps in the file, only the printout for user.
print_only logical If .true., do not create the output file. Only print the model size and existing time information in the input file.


[top]

MODULES USED

types_mod
time_manager_mod
utilities_mod
assim_model_mod
obs_model_mod
ensemble_manager_mod
mpi_utilities_mod
[top]

FILES

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
restart_file_tool Only use single process Only a single mpi process can be used with this program
restart_file_tool must specify data days and times If overwrite_data_time is true, the namelist must include the new day and time.
restart_file_tool output_is_model_advance_file must be true to set advance time If overwrite_advance_time is true, output_is_model_advance_file must also be true.
restart_file_tool must specify advance days and times If overwrite_advance_time is true, the namelist must include the new day and time.
restart_file_tool overwrite_advance_time must be true if output file has advance time If the incoming file does not have a model advance time, the output cannot have one unless the user gives one in the namelist, and sets overwrite_advance_time to true.

KNOWN BUGS

none

[top]

FUTURE PLANS

none

[top]

Terms of Use

DART software - Copyright 2004 - 2013 UCAR.
This open source software is provided by UCAR, "as is",
without charge, subject to all terms of use at
http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 6380 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/classic/utilities/restart_file_tool.html $
Change Date: $Date: 2013-08-05 17:47:11 -0600 (Mon, 05 Aug 2013) $
Change history:  try "svn log" or "svn diff"