improve doc and variable naming

README.md

@@ -22,7 +22,7 @@ desired module files, in the following way:
     export NWPCONFDIR=$HOME/conf
     export NWPCONFBINDIR=$HOME/nwpconf/bin
     export NWPCONF=production/dailymodelrun/forecast
-    # source the main libary file
+    # source the main library file
     . $NWPCONFBINDIR/nwpconf.sh
     # source other optional modules
     . $NWPCONFBINDIR/nwptime.sh

bin/getarki.sh

@@ -14,7 +14,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ## @file
-## @brief Modules with functions for retrieving observations and initial/boundary conditions from arkimet archive.
+## @brief Module with functions for retrieving observations and initial/boundary conditions from arkimet archive.
 ## @details This module provides functions for retrieving observations
 ## in BUFR format and initial/boundary conditions, tipically in GRIB
 ## format, from the desired dataset of an [Arkimet
@@ -74,7 +74,7 @@ getarki_obsbufr() {
 getarki_icbc() {
     local h hinput timerange ana d2h t2h
 
-    for h in `seq $MODEL_START $MODEL_FREQ_INPUT $MODEL_STOP`; do
+    for h in `seq $MODEL_START_SLICE $MODEL_FREQ_SLICE $MODEL_STOP_SLICE`; do
 	[ -n "$WAITFUNCTION" ] && $WAITFUNCTION $h
 
 	if [ "$MODEL_BCANA" = "Y" ]; then
@@ -84,12 +84,12 @@ getarki_icbc() {
 	    timerange="timerange:Timedef,0h,254"
 	else
 	    reftime=`getarki_datetime $D2 $T2`
-	    hinput=$(($h+$DELTABD))
+	    hinput=$(($h+$DELTABD_SLICE))
 	    timerange="timerange:Timedef,${hinput}h,254"
 	fi
 	arki-query --data -o `inputmodel_name $h` \
 	    "reftime:=$reftime;$timerange" $ARKI_ICBC_DS
-#	[ "$h" -eq "0" -a ] or [ "$h" -eq "$MODEL_START" ] ?
+#	[ "$h" -eq "0" -a ] or [ "$h" -eq "$MODEL_START_SLICE" ] ?
 	if [ "$h" -eq "0" ]; then
 	    ana=`inputmodel_name a`
 	    [ -f "$ana" -o -h "$ana" ] || ln -s `inputmodel_name $h` $ana
@@ -112,6 +112,6 @@ getarki_datetime() {
 set -a
 # checks
 check_dep getarki nwptime
-#check_defined DATE TIME D1 T1 D2 T2 MODEL_START MODEL_FREQ_INPUT MODEL_STOP MODEL_BCANA
+#check_defined DATE TIME D1 T1 D2 T2 MODEL_START_SLICE MODEL_FREQ_SLICE MODEL_STOP_SLICE MODEL_BCANA
 # stop exporting all assignments
 set +a

bin/nwpconf.sh

@@ -72,7 +72,7 @@
 ## 
 ## ### Picking different variants of a generic file
 ## 
-## The configuration tree can also contain generic files redy for use,
+## The configuration tree can also contain generic files ready for use,
 ## at different configuration levels, the function conf_getfile() helps
 ## in choosing the one with highest priority in these cases.
 

bin/nwptime.sh

@@ -13,6 +13,53 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+## @file
+## @brief Module with functions for managing the reference time of NWP runs.
+## @details This module provides functions for performing various
+## types of computations related to the reference and forecast time of
+## a NWP model run and of the driving model data. Assimilation and
+## forecast modes are supported, as well analysed and forecast
+## boundary conditions with a desired reference time shift. The terms
+## _input model_ and _driving model_ are used interchangeably
+## hereafter.
+## 
+## The following environmental variables should be set in order to
+## describe the model reference timing:
+## 
+## - `$DATE` (YYYYMMDD) and `$TIME` (hhmm) indicate the current date
+##   and time, i.e. the start of the run for a forecast or the end of
+##   the run for an assimilation run
+## 
+## - `$MODEL_BACK` indicates the number of hours to go back from
+##   `$DATE$TIME` for starting an assimilation run (0 for a forecast
+##   run)
+## 
+## - `$MODEL_STOP` indicates the duration of the run in hours (`==
+##   $MODEL_BACK` for an assimilation run)
+## 
+## - `$MODEL_BCANA` if set to `Y` indicates that analysis data are
+##   used as boundary conditions
+## 
+## - `$MODEL_DELTABD` indicates the difference in hours between
+##   `$DATE$TIME` and the initialisation time of last available input
+##   model forecast, it is ignored if `$MODEL_BCANA == Y`
+## 
+## - `$MODEL_FREQANA_INPUT` indicates the interval in hours between
+##   available analysis data from the driving model, used in the case
+##   of `$MODEL_BCANA == Y`, it is assumed that analyses are produced
+##   at 00 UTC and successively every `$MODEL_FREQANA_INPUT` hours
+## 
+## - `$MODEL_FREQINI_INPUT` indicates the interval in hours between
+##   initialisation of successive driving model forecasts, it is
+##   assumed that forecasts are initialised at 00 UTC and successively
+##   every `$MODEL_FREQINI_INPUT` hours
+## 
+## - `$MODEL_FREQFC_INPUT` indicates the interval in hours between
+##   successive driving model forecast steps of a single forecast run
+## 
+## It is an optional module and it has to be sourced after the main
+## _nwpconf.sh_ module.
+
 ## @fn nwptime_init()
 ## @brief Initialise the time-related environment for a NWP run.
 ## @details This function is implicitly called when the module is
@@ -28,17 +75,11 @@ nwptime_init() {
 # assimilation window / start of forecast) and start of last available
 # input forecast providing BC (for BCANA=N)
     if [ "$MODEL_BCANA" = "Y" ]; then
-	export MODEL_FREQ_INPUT=$MODEL_FREQANA_INPUT
+	export MODEL_FREQ_SLICE=$MODEL_FREQANA_INPUT
 	MODEL_DELTABD=0
     else
-	export MODEL_FREQ_INPUT=$MODEL_FREQFC_INPUT
+	export MODEL_FREQ_SLICE=$MODEL_FREQFC_INPUT
     fi
-    DELTABD=0
-    # DELTABD=$(($MODEL_DELTABD-$MODEL_BACK))
-    # while [ $DELTABD -lt 0 ]; do
-    # 	DELTABD=$(($DELTABD+$MODEL_FREQANA_INPUT))
-    # done
-    # DELTABDLOCAL=$DELTABD
 }
 
 
@@ -50,62 +91,66 @@ nwptime_init() {
 ## like using analysed or forecast BC's, possibly with a shift in time
 ## and with specified frequency of availability.
 nwpbctimeloop_init() {
-    MODEL_FULL_STOP=$MODEL_STOP
-    MODEL_STOP=0
-# DELTABD is difference between start of assimilation and start of
+    MODEL_STOP_SLICE=0
+    : ${MODEL_BACK:=0} # set to 0 if unset
+# DELTABD_SLICE is difference between start of assimilation and start of
 # input forecast suitable for providing BC
     if [ "$MODEL_BCANA" != "Y" ]; then
-	DELTABD=$(($MODEL_DELTABD-$MODEL_BACK))
-	while [ $DELTABD -lt 0 ]; do
-	    DELTABD=$(($DELTABD+$MODEL_FREQINI_INPUT))
+	DELTABD_SLICE=$(($MODEL_DELTABD-$MODEL_BACK))
+	while [ $DELTABD_SLICE -lt 0 ]; do
+	    DELTABD_SLICE=$(($DELTABD_SLICE+$MODEL_FREQINI_INPUT))
 	done
 	D3=`date_sub $DATE $TIME $MODEL_DELTABD`
 	T3=`time_sub $DATE $TIME $MODEL_DELTABD`
+    else
+	DELTABD_SLICE=0
     fi
-    DELTABDLOCAL=$DELTABD
+    DELTABD_SAVE=$DELTABD_SLICE
 }
 
 
 ## @fn nwpbctimeloop_loop()
 ## @brief Advance a loop on the model runs providing input boundary conditions for a NWP run.
 ## @details This function has to be called for advancing a loop over
 ## the model runs that provide the boundary conditions to an
-## assimilation run. The function sets the variables `$D2`, `$T2`,
-## `$MODEL_START`, `$MODEL_STOP`, `$DELTABD` The return value is 1
-## (true) if the loop is not finished or 0 (false) if the loop is
-## finished, thus it should be used in the following way:
+## assimilation or forecast run. The function sets the variables
+## `$D2`, `$T2`, `$MODEL_START_SLICE`, `$MODEL_STOP_SLICE`,
+## `$MODEL_FREQ_SLICE`, `$DELTABD_SLICE`. The return value is 1 (true)
+## if the loop is not terminated, or 0 (false) if the loop is
+## terminated, thus it should be used in the following way:
 ## 
 ##     nwpbctimeloop_init
 ##     while nwpbctimeloop_loop; do
 ##         performoperationsintheloop
 ##     done
 nwpbctimeloop_loop() {
-    [ $MODEL_STOP -lt $MODEL_FULL_STOP ] || return 1
-    DELTABD=$DELTABDLOCAL
-    D2=`date_sub $D1 $T1 $DELTABD`
-    T2=`time_sub $D1 $T1 $DELTABD`
+    [ $MODEL_STOP_SLICE -lt $MODEL_STOP ] || return 1
+    DELTABD_SLICE=$DELTABD_SAVE
+    D2=`date_sub $D1 $T1 $DELTABD_SLICE`
+    T2=`time_sub $D1 $T1 $DELTABD_SLICE`
 
-    MODEL_START=`max 0 $((-$DELTABD))`
+    MODEL_START_SLICE=`max 0 $((-$DELTABD_SLICE))`
     if [ "$MODEL_BCANA" = "Y" ]; then
-	MODEL_STOP=$MODEL_START
-# prepare for next loop, update DELTABDLOCAL so that DELTABD can be
+	MODEL_STOP_SLICE=$MODEL_START_SLICE
+# prepare for next loop, update DELTABD_SAVE so that DELTABD_SLICE can be
 # used outside
-	DELTABDLOCAL=$(($DELTABD-$MODEL_FREQANA_INPUT))
+	DELTABD_SAVE=$(($DELTABD_SLICE-$MODEL_FREQANA_INPUT))
     else
 # test whether this is the last possible loop
 	DT=`date_add $D2 $T2 $MODEL_FREQINI_INPUT`
 	TT=`time_add $D2 $T2 $MODEL_FREQINI_INPUT`
 	if [ $DT$TT -gt $D3$T3 ]; then
-	    MODEL_STOP=$MODEL_FULL_STOP
+	    MODEL_STOP_SLICE=$MODEL_STOP
 	else
-	    MODEL_STOP=`min $MODEL_FULL_STOP $(($MODEL_FREQINI_INPUT-$DELTABD-$MODEL_FREQFC_INPUT))`
+	    MODEL_STOP_SLICE=`min $MODEL_STOP $(($MODEL_FREQINI_INPUT-$DELTABD_SLICE-$MODEL_FREQFC_INPUT))`
 	fi
-# prepare for next loop, update DELTABDLOCAL so that DELTABD can be
+# prepare for next loop, update DELTABD_SAVE so that DELTABD_SLICE can be
 # used outside
-	DELTABDLOCAL=$(($DELTABD-$MODEL_FREQINI_INPUT))
+	DELTABD_SAVE=$(($DELTABD_SLICE-$MODEL_FREQINI_INPUT))
     fi
 
-    if [ $MODEL_START -eq 0 ]; then
+# is this used anywhere? erase 
+    if [ $MODEL_START_SLICE -eq 0 ]; then
 	MODEL_LANA=.TRUE.
     else
 	MODEL_LANA=.FALSE.