run_urtip

USAGE:
          run_urtip [options] [ts-modelfile]
 
PURPOSE:
 
          OBS!!!   Presently this script runs urtipgt by default.
                   Use  -C urtipg to change to the Bonn-version.
 
          Compute tide predictions from a table, produce
          a time-series file exactly synchronous with
          the specified ts-model file (t0, dt, epoch, length)
 
          The table is prepared by urtap[t] (.trs, unit 13),
          default file name t/urtap.trs
 
          The output is found in t/pt.tsf by default.
          For converting ASCII -> BIN, use
             tslist o/pt.tsf -gi4,5i3,t33,d18.0 -k3 -r#rate
          (the -r#rate option might be needed if the
          auto-detect rate is not precise enough).

          The timing parameters are derived from the model file.
          If no model file is specified, a source-script file
          must be prepared. See the section on FILES below.

          If you modify a trs-table (see -t ), observe the note.

          An alternative to make tide predictions is by coding up an
          urtip.ins instruction file and run it directly. A manual
          page for coding namelist and open-file block is here.
 
OPTIONS:

 -e          - test run, the instruction input to urtip is shown.
 
 -C prog     - the program name for predicting                         [urtipgt]
 
 -E src      - If no ts-file is specified, source src file to
               set the runtime parameters.                         [./urtip.env]
               A drift signal can be produced with prepared code,
               by adding a line
               set addrift=-Erun_urtip,EXP
               set addy=1.0
               (if the drift signal is to be added with factor 1.0   [0.0])
 
 -t table    - the table file                                      [t/urtap.trs]
 
 -o output   - the output file (ASCII)                                [o/pt.tsf]
                "    "      "  (BIN) accordingly:              
                                     extension .ts                     [o/pt.ts]
 -k            keep the ASCII file despite BIN output is requested          [no]
 
 -PM         - add polar motion                                          [don't]
 -LL         - longitude,latitude for PM calculation                 [11.9,57.6]
 
 -b [output] - produce ASCII and BIN file                           [ASCII only]
 -B [output] - Retain only BIN file                                    [o/pt.ts]              
 -bm         - like b, produce GRAV|PRED column
               in MC-file, however
 -BM         - like -bm, retain only BIN file, however
 -rmc        - remove the MC-file first                                  [don't]

 -s scale    - rescale the output                                        [1.0d0]
 -s u        - unscale the output (1/calfactor from the table file)
 -u          - unscale the output (1/calfactor ...))
 -dudt       - compute the time-derivative of the effect

 -prf file,dt[,trg]                                              [no pre-filter]
             - apply a pre-filter (the filtering that was involved in
               the model file, for instance).
               file - produced with a FILTER command and OUTFS in tsfedit
               dt   - the input sampling interval [h] or, if negative, in Sps
                      Add `s´ abutted to the value if dt is in seconds.
               trg  - the label of the filter section if the file
                      contains more than one. [' ']

 -besselprf n[,f0]                                            [no Bessel filter]
             - apply the Bessel-filter that was used on the analogue
               side of the data acquisition, GWR: 8,0.0174
               n    - Filter order
               f0   - Scaling frequency in Hertz.

 -A file     - a super-option implying BIN output and unscaling according
               to the CALFACTOR line in the trs-file.
               file is the intermediate ASCII-file that will be removed
               unless -k (keep) has been requested.

 -fjd        - print full Julian day (7-digits before the decimal point)   [MJD] 


ENVIRONMENT:
 
   RESIDEDIT - an option (or a series of options) for tslist when inspecting
               the model file. Typically:  setenv RESIDEDIT "-Efile.tse,target".
               run_urtip spawns for epoch, time step, and length

 FILES:

  ./urtip.ins - output, a copy of the run-time instructions read by urtipgt. 

  -E <source-file.csh>  source file coded in csh, example
set date=2012,10,25  
set hms=0,0,0  
set dt=1.     
set tscale=60.
set nout=1440
   The time step in hours used by urtipg[t] is:  dt/tscale; thus, the example
   generates 1-minute data.

   Here is the list of namelist parameters that can be (must) set with the source file:
 &param
 date=$date, hms=$hms
 dt=$dt, tscale=$tscale
 nout=$nout
 iun=31
 iun_prf=$iunprf, dt_prf=$dtprf, trg_prf='$trgprf'
 n_bessel_prf=$nbessel, f_bessel_prf=$fbessel
 qdudt=$dudt
 thd_file='/home/hgs/tap/d/etcpot.dat'
 utc_file='/home/hgs/tap/d/ttutcf.dat'
 qfjd=.false.
  $locstr
 &end
  ASCII output: A header file can be copied to the begin if the ASCII file's name
    contains (regexp) '.*Pname.*'; the name of the header file searched for is then
    ./Pname-header.dat

   -PM option, Polar Motion:
     This script will run the polar motion program and add the time series

A NOTE ON trs-FILES:
Modifying a tide table (trs-file), it's important that the numbers right next left of the `;´-sign point to the tide harmonic table's leading wave of the band.
The latter is obtained after the removal of the static tide (a.k.a. M0S0 and its degree-4 companion). Thus, the lunar nodal tide refers to number 1. Here is
an example that generates the tide band with frequencies below 1 cyc/yr:

(2,0,0,0,*)                      =     Nod2    1 ;  -3.56995845D+03  0.0
(3,0,0,0,*)                      =     Nod3    5 ;  -5.08756D+03     0.0
END WAVEGROUPS
   11.926000   57.396400    7.500000    0 = site long/lat/alt & IALTG
    9.798529    6378.137    6363.006      = g-used [m/s^2] r-used r-geocent [km]
   72     = n_eigenvalues
    0     = whitening filter length
S_GRAVIT  = core model
  -774.421 [nm/s^2]$        = CALFACTOR
 

EXAMPLES:
   Producing using nodal tides ("gnt...") for subtracting later from observations  d/g${begd}-OPNEND-1h.mc 
    set begd=100202
    run_urtip -t t/nodal-only.trs -rmc -BM d/gnt${begd}-OPNEND-1h.ts d/g${begd}-OPNEND-1h.mc
    setenv FNSUB d/gnt${begd}-OPNEND-1h.ts
    setenv FACSUB 774.47
    tslist d/g${begd}-OPNEND-1h.mc -LG+V -I -Esubts.tse,ADD \
           -O:`label GRAV,NTSUB` d/g${begd}-OPNEND-1h.mc

  Producing tides at 1-minute rate for a day:
    prtide4day -D 2013,01,02 -rm 1. -n 1440 > file.env
    run_urtip -A PT130102-60s.tsf -E file.env -u 

 A rather standard type of task: 1-s
    run_urtip -t tt/g090615-OPNEND-1h-nnt-ochy.trs -b tmp/G1_p_150204-1s.ts lpfu/G1_g_150204-1s.ts


 Running urtipgt from the command line, there are more parameters that can be set through the namelist.
 Examples:
   f9003     - char - format for writing the ascii file
   qleapsecs - log  - respect leap seconds [.true.]


 Here is the full list, copied from the Fortran source code:

 Namelist parameters:

 cause    - chr*3 - TGP or SRT
 iun      - output file unit (ASCII, YYYY MM DD hh mm ss and format
            is still fixed - we might need an update for dt < 1s

 usecal   - output calibration factor, default=1.0. See q_volt!

 date,t0,hms - start time = date + t0[h] or date+hms if hms(1)>=0
 nout,dt     - length and rate[1/h] of output.
 tscale      - rate = dt/tscale [1.0d0 = 1 hour]
 
 iutt        - as an alternative to timing above, read a time tie
               from file unit iutt
               List-directed format, YY MM DD [hh mm ss ff]

 zfacl2  - effective factor on Love no. l in NDR-combination
           for strain  [(6,0)]

 cfc     - core model, see ~/tap/t/p/ndrfs.f for applicable strings.

 q_abs   - the trs-file contains absolute in-phase cross-phase
           coefficients. Standard is factors w.r.t. tide potential.

 q_volt  - .true.: If trs-file contains a CALFACTOR record,
                   divide the output by the calfactor. The function
                   of this option is, if the tide analysis has been
                   done on a time series in units of nm/s^2
                   then this procedure will generate the corresponding
                   predictions in the original "Volt" units.
                   The factor for the output is usecal/calfactor

 q_ocean - (under q_abs=.true.) ... oceanographer's phase convention
           (c.conjugation is applied to the input.
           See *) below.)

 iun_trs - file unit for trs-file
 locstr  - location string, needed if iun_trs is 4 = ins-file, since
           the trs-file is rewound before reading. Use e.g.
           locstr='WAVE GROUPS' and place such a line before the
           wave groups input.
 
 wadd    - wadd>0 AND open file on unit 22 - a stub
           See ~/TD/run_urtip how to control tide synth using a
           template ts-file.
 ... even the mode d'employ is a stub, sorry
 iun_fcp - ??? apply spectral filter on potential, using f_on_pot
           ~/tap/p/potfcor.f
           Presently defunct, f_on_pot expects filter parameters
           via parameter list, not file. How to get a filter into this
           program - ??? getfs! /home/hgs/sas/p/filterios.f

 msglevel - In the time-series part, diagnostic printing is in effect
            with a low level number.
            0 - most excessive printing
            3 - no printing

 The *_prf parameters can be used if a prediction is to match a downsampled
 series of observations.

 *)
 You have cos and sin components from a tide gauge and want to compute
 a time series of ocean tide height.
 You need the wavegroup setup corresponding to the analysis' tide band setup
 e.g.
 (2,2,-2,*)                       =     2N2   452 ; #cos #sin
 (2,2,-2,0,2,*)                   =     2N2   452 ; #cos #sin
 (first line for a minimum resolution, second for a high resolution)
 etc etc
 Use core model (cfc) 'OT_EFFEC'
 

Coding an env-file (for option -E)

Take a look at the instruction input:
cat <<EOF >! urtip.ins
13 R $ttab
31 B $outf
$prfopen
   Q

 &param
 date=$date, hms=$hms
 dt=$dt, tscale=$tscale
 iun=31
 iun_prf=$iunprf, dt_prf=$dtprf, trg_prf='$trgprf'
 n_bessel_prf=$nbessel, f_bessel_prf=$fbessel
 qdudt=$dudt
 nout=$nout
 $locstr
 thd_file='$HOME/tap/d/etcpot.dat'
 utc_file='$HOME/tap/d/ttutcf.dat'
 &end
EOF
All variables need to be set. You may consider additional parameters as introduced in the urtiptg part of the manual above, 
The env-file should contain a series of set commands, depending on the shell. Assume csh, baptise the file urtip.env
set ttab = t/urtap<-analysis-version>.trs
set outf = o/pt<date-and-analysis-version>.tsf
set prfopen="48 < $HOME/TD/1h.fs"           # zero-phase decimation filter
set trgprf=
set n_bessel_prf=8  f_bessel_prf=0.0174     # SCG GGP filter
set dt=1.d0  tscale=1.0d0                   # hourly data
set date=2010,10,1  hms=0,0,0,0  nout=744   #  for October
set qdudt=.false.                           # .false. is the default:
#                                           # time series is NOT the derivative w.r.t. time
#
# The rare case of including the wave group data in the instruction file:
set iutrs=4                                 # omit to open trs-file on unit 13
set locstr=" locstr='Delta'"               
# Then, start the data section after a label `Delta´ in the first column after
# the &end of the namelist. 
etc.

Make a copy of the instruction code above (starting with cat <<EOF >! urtip.ins) , augment/edit it, and store it in a file, e.g. urtip_run
Then, generate urtip.ins for direct use in urtiptg @ urtip.ins
    source urtip.env
    source urtip_run
    urtipgt @ urtip.ins
   
or (csh style compulsory!)
    run_urtip ... -E source urtip.env ...
 
.bye