| Back to HOW_TO  |  Back to General Information  | Back to TOP |



This page contains
| General remarks | Documentation of instruction file | Examples of instruction files |
| Documentation of Namelist &param | Special considerations |
| Running in the background | Graphics diagnostics |

If you are interested in the Storm Surge problem (pressure and wind forcing), use otemw1 instead. That procedure has many parameters and features in common with this one, so you will have to read the present document in any case.

General remarks.

otemt1.f  is a Fortran main program. Location of source code (unix): /home/hgs/OTEQ/PROG/EXEC/otemt1.f

Prerequisits:    cream => otem92 => otem16

This program calls TTEQ to iterate the differential equation system from a time-step stage IB to a stage IE. Alternatively, the process can be started from a zero state. "Explicitly time-dependent" means that tides can be computed realistically for a specified kalendar epoch; a rich spectrum of tides can be used simultaneously to drive the basin, and air pressure can be added as a driving force (implementation pending (? well, there is indeed a Call Pressure_Param)).

Explanations concerning TTEQ are found only a mouseclick away:  TTEQ subroutine otes12.f.

Forcing options comprise

The first three forcing options (or methods, if you like) are prepared by otem16, and a file containing the forcing information, ETDX.DMP, is passed to otemt1. 
Note that the excitation potential may contain degree-3 tides, but not degree-4 as their potential is much too weak.
Degree-4 effects can, however, be modelled if the loading potential and the boundary data contains such information. See  otem92 (Example 4, includes M4) and otem16 (namelist variable wave-set). Other higher-degree effects may arise due to nonlinear terms in the differential equations.

The main products of this process are: Since many tides can be included in the forcing, harmonic solutions of only the dominating effects make sense (consider spectral resolution given the usually short time window of the solution). The harmonic solution requires a long succession of tide fields in a steady-state condition. To this end, the solution must have converged fairly well before harmonic solutions can be taken at face value.


OTEMT1       Documentation   *.INS file

Graphics diagnostics
The grex plot routines print diagnostics to file unit 99. You can redirect the output to another xterm by specifying

setenv U99 /dev/pts
setenv U99 TERM

where `pts completes the path to the other xterm device, e.g. pts/3
With  TERM ,that xterm is used from where the program is launched.
The default is a file named  graphics-diagnostics.99 in the current directory.
The default can be changed in the namelist:  file99='filename'
The advantage with a terminal is that the diagnostics will be complete even up to the point when the program aborts due to code errors etc..

Input sections in the *.INS file

Input sections (1) to (8) as detailed below  in the following order.
Format code * means free format.

(0) (invariable name, always needed): The ETDX.DMP data set. This contains the driving forces, boundary conditions, and out-of-area data.
      The file is supposed to be found according to the PATH namelist parameter (default ./)
      Since otem16 (the program that compiles ETDX.DMP from the output of otem92) is fast and ETDX.DMP big, there is no need to save different versions.

(1)  Comments; line feed characters in column 1, width 80 characters.
  /*        (in columns 1-2): End of comments.

(2) Namelist block #1
    Parameters common to all solution cycles can be defined here. Coding of namelist
    block as usual starting in column 2.

              NRCYC = number of cycles
               NSOL = dump section number for continuing a job
                      -1  to start from zero.
               PATH = path and file name radical for ETDX external tide
            GEOCXYZ = .true. to input crustal dynamics site coordinates XYZ
        or GEOGRAPH = .true., ... coordinates in degrees.
              FMTLS = format for crustal dynamic sites.

    NSOL=-1:   TIDE = tide for fine-adjustment of time step
                      (the basic reference tide)

(3) Open-file block, input files:
      must be terminated by a record containing  Q  in the fourth column.
    31 - resolved 'Z'-flags and /carea/
    32 - unresolved 'M'-flags and bathymetry
    33 - act.boundary location data
    03 - dump file (needed if NSOL > 0)

(4) Tide gauge sites (harmonic analysis printed on protocol):
    Line 1     : N
    Line 2..N+1: Site name ...... xxx yyy

    Symbol      Meaning                                 Format
    N         = number of sites                           *
    Site name   (obvious)                              '(A16)'
     xxx yyy  = location on 'Z'-grid                   '(2I4)'

(5) Tide gauge sites (tide time-series output):
    Line 1     : N, IU
    Line 2..N+1: Site name ...... xxx yyy

    Symbol      Meaning                                 Format
    N         = number of sites                           *
    IU        = file unit; -1 to disable output in the
                first cycle

    Site name                                          '(A16)'
     xxx yyy  = location on 'Z'-grid                   '(2I4)'

(6) Crustal dynamic sites (loading displacements time series output):
    Line 1     : N, IU
    Line 2..N+1: Site name ...... x y z

    Symbol      Meaning                                 Format
    N         = number of sites                            *
    IU        = file unit; -1 to disable output in the
                first cycle                                *

                IU   : radial
                IU+1 : tangential, east
                IU+2 :     "       north
    Site name                                        (&param FMTLS)
    x y [z] [h] 
              = coordinates                          (&param FMTLS)

                GEOGRAPH=.true.: x = east longitude [deg]
                                 y = latitude [deg]
                                 h = height above sea level [m]
                                     default = 0.0

                GEOCXYZ =.true.: geocentric,  x y z [h]     [m]

    If GEOGRAPH=.false. .and. GEOCXYZ=.false., the following line must still be specified:
    Line 1   : 0, -1

(6a) Conditionally if   QProc_Buoys=.true. :    Buoy data block.

    Line 1     : N, IU
    Line 2..N+1: x y

    Symbol      Meaning                                 Format
    N         = number of buoys                            *
    IU        = file unit; -1 to disable                   *
    x y       = initial buoy location with
                respect to area centre [km]                *

(7) Open-file block, output files
      must be terminated by a record containing  Q  in the fourth column.
     2 - dump file
    41 - harmonic tide solution CMPX array, 'Z'-grid
    42 - (conditionally) harmonic tide solution upper harmonic if TIDEH=/='NO'
    75 - (suggested) tide gauge time series
    67 - (suggested) ocean loading time series output.
         Vertical, east and north components of displacement.

(8)  Namelist block #2, #3 ... #NRCYC


     One block for each program cycle implicates a call to subroutine TTEQ, "SOLVE"-phase.
     Consider the following parameters to redefine the parameters:

    KCYC        - number of complete cycles of tide CTIDE
    FRICP(1..4) - friction parameters. Values less than zero indicate that
                  the previous values are kept. This is useful if inter-
                  ative change of friction parameters is planned during the
    NONLIN      - nonlinearity options. A value of -1 indicates that the
                  previous value is kept (e.g. interactively changed during
    Gra_Opt     - screen display. Use 'N' if program is to execute without
    QSPECA...   - the special area is introduced / modified.
    No_Adv_Area - an area where the advection term is skipped.
    QMYPRC      - execute the section  myprc.fi  included in MAIN code.
    IUTGG       - turn on tide gauge output by specifying IUTGG > 0
    IUEVL       - turn on loading time series output be specifying IUEVL > 0
    IUN_EVL_OUT - (with MOD_EVL_OUT) to output elevation fields

More on files
File unit 99 is used for diagnostic output, especially graphics.

The communication mechanism (script OC -> subroutine ubr_ff (oteu18.f) uses a file for which an available unit number is scanned for.
The name of this file is $HOME/OTEQ/comm$OC_PID
where  OC_PID is an environment variable.

myproc.fi is prefarably a symlink to a code snippet that alters   O-O-AREA, FLZ, FLM and  H arrays..
Main must be recompiled of course. The executable could be given a specific name or place.


(Suggest to start a new browser window)

Start a model

Continue iteration

Boundary step experiment
(Note: QSetEl = .true. would be needed if we specify the step from initially up, AB_Step_VF=1.0,  AB_Step_VT=0.0)

Generating an M6 solution for Skagerak-Kattegatt
(Note: QPlay_with_ETD requests to execute code in subroutine Play_with_ETD, included in main otemt1.f)

Free oscillations in the Baltic - BALTIC/otemt-slope.ins


OTEMT1          Documentation       NAMELIST /PARAM/

Thematic summary:
Harmonic analysis
                CTIDE, TIDEH, QHZ, QHM, QHDC

Cycling; solution version numbers:

Online graphic display:
                RANGE, ITGRA, GRA_OPT

Run-in damping:

Model parameters:
                C_NONLIN, IDTTEP

Active boundary and potential input:
                PATH, IUSAP

                NVU, QTAKE(100), QBT, QLT, QFB, QABT, QABF, ZABF
                QAB_Step, AB_Step_VF,    AB_Step_VT,  QSETEL
                          AB_Step_TB,    AB_Step_TE
                          AB_Step_IB,    AB_Step_IE
                          AB_Step_BDate, AB_Step_BTime
                          AB_Step_EDate, AB_Step_ETime

Astronomical parameters:

Air pressure simulation

Green's function for online loading effects:
                IUNG, DISMAX, GPATH, GREENSF

Output online results / protocol:
                IUEVL, IUTGG, IUTGP, IMON,JMON, QSafe_TGG

Input control, load effect sites:
                FMTLS, GEOGRAPH, GEOCXYZ, Target_EVL

Special Area:
                QSPECA, ISPECA, PSPECA

Screen stuff:
                IX_Window_Size, IY_Window_Size

                                                              useful in SOLVE-phase__
________ NAMELIST /PARAM/ parameters ____________________________________ (default)__*_

AB_Step_VF   = Act.bound. step height "from" (if QAB_Step true)               (0.0)  *
   = step height "to"; set N_ramp to make smooth transition         (1.0)  *
AB_Step_TB   = Act.bound. step begin, seconds from start (real*8)            (0.d0)  *

AB_Step_TE   = Act.bound. step end,   seconds from start (real*8)           (1.d20)  *
AB_Step_IE   = an alternative to _TB, _TE: time step numbers                         *
AB_Step_BDate, AB_Step_BTime
AB_Step_EDate, AB_Step_ETime
             = (integer arrays dimensioned (3) and (4), respectively)
               an alternative to
_TB, _TE: yyyy,mm,dd, hh,mm,ss,ff                   *

APC          = Air pressure in centre [m water column]                        (0.0)  *
APVX,APVY    = velocity [km/h]
APW          = width of pressure perturbation [km]
APX,APY      = position of centre at time 0 [grid units]

BOTTOM       = Cutting the bathymetry at this value [m];
               a negative value: leave bathymetry unchanged                  (-1.0) 

CTIDE        = the tides for harmonic analysis.                            ('M2  ')  *
               Specify 2-char symbols with one intervening blank

CYCWB        = Begin to dump at cycle CYCWB.                                    (2)  *

C_NONLIN     = String with nonlinearity options.
               '+S'  - shallow water
               '+AM' - advection by 1/h (U grad M)
               '+AU' - advection by 1/h (U grad U)                           ('+S')  *

DECR_D       = damping decrement (~relaxation time)                          (100.)  *

DISMAX       = maximum distance load - site (or -1. for model diagonal)       (-1.) 

ETD_SLOPE_OPT = regional forcing by adding features to the potential        (3*' ')  *
                Use _OPT(1) and (2) for E and N specifications,
                _OPT(3) for timing
                E:ax,cx,wx,tx       for east-west geometry
                N:ay,cy,wy,ty       for north-south   "
                T:b,d,p [s] [HOLD]  for begin, duration and period
d,p [s] [HOLD]    for now!, duration and period

                a - amplitude
                c - centre location in grid units
                w - width of sinusoid half-cycle in grid units
                τ - taper; product τ w gives a distance from which outward
                    the forcing function is zero.
                b - begin time from epoch
                d - duration
                p - number of semi-cycles in d
                s - all times assumed in hours or, if `s is given, in seconds.
             HOLD - prolong, hold the last forcing value.
                The equation is
                     F(i,j,t)=(12+12cosπR)(X+Y)sin(2πpt-tbd)F(i,j,t) = \left(\frac{1}{2}+\frac{1}{2}\cos\:\pi R\right)\; (X+Y)\;\sin\left(2\pi p\frac{t-t_b}{d}\right)
                     X=axsin(π2i-cxwx),Y=aysin(π2j-cywy)X=a_x \;\sin\left(\frac{\pi}{2}\;\frac{i-c_x}{w_x}\right) \;\;,\quad Y=a_y \;\sin\left(\frac{\pi}{2}\;\frac{j-c_y}{w_y}\right)

                     R=min{1,(i-cxwxτx)2+(j-cywyτy)2}R = \min\left\{1,\;\left(\frac{i-c_x}{w_x\:\tau_x}\right)^2+\left(\frac{j-c_y}{w_y\:\tau_y}\right)^2\right\}

FILE99       = char*48 filename for graphics diagnostics ('graphics-diagnostics.99')  *
FMTLS        = char*32 format string                             ('(a16,4x,3f15.0)')

FRICP(1..4):   friction parameters:
FRIC(1)      = run-in damping,                                                 (0.6)  *
FRIC(2)      = lin. bottom friction coefficient * DT,                         (0.25)  *
FRIC(3)      = quadr.  "      "          "      * DT,                          (0.0)  *
FRIC(4)      = eddy viscosity [ s m^-2]                                        (0.0)  *

GEF          = Corr.factor for wave dispersion relation.                      (1.07)  *

GEOGRAPH     = (logical) option: read geographic coordinates               (.false.)
GEOCXYZ      =    "      "   : read geocentric x-y-z                       (.false.)

               If both are .false., the load site block should consist

               of the header record only:
               0, -1

GPATH        = (char*48) path and file name radical to Green's functions.
               Will be set if right delimited by ']'                           (' ')

GRA_OPT      = (Char*1) Graphic display of solution evolution
               'N'     - no display
               'E' 'e' - display elevation with / without prompt
               'P' 'p' -   "     tide potential w / wo      "
               'A' 'a' -   "     both           w / wo      "                  ('N')  *

GRASOL_VMODE = (integer) Graphics mode, either 18 or 24 
               Mode 24 screen has 1024x768 pixels.

GRASOL_BASEBOX = (integer) the basic colour-box size, 3, 4, or 5                 (3)

GREENSF      = (char*) name part of loading Green's function table     ('MC00EGBO]')

HMIN         = Minimum allowed bathym.                                         (10.)  *

I_START      = Number of steps offset from ETD_Epoch in INIT-0                   (0)

IDTTEP       = Number of steps between recomputation of tide potential          (10)  *

IMON,JMON    = monitored site on protocol.                                     (0,0)  *

ISPECA(1..4) = area bounds (west,south,east,north)                     (99999,0,0,0)  *

ITGRA        = time interval between graphic displays.                          (20)  *

IUBOUY       = file unit for buoy output                                        (-1)  *

IUNG         = file unit number for Green's function                            (61)

IUSAP        = ETDX.DMP file unit number (see PATH)                             (11)

IUEVL        = file unit for load effects output or -1 for none.                (-1)  *

IUTGG        = file unit for tide gauge output or -1 for none.                  (-1)  *

IUTGP        = file unit for potential sensor or -1 for none.                   (-1)  *

IUN_EL_OUT   = file unit for a series of elevation fields                       (-1)  *
               (interval is specified as modulus of time-step, MOD_EL_OUT)

IX_WINDOW_SIZE = Xwindow size if value > 0  and GRASOL_VMODE=24                 (-1)

JSVER        = Introduce a new generation by adding JSVER to current version.
               The version number stored will be:  N.r + JSVER + k, k=1,...
               where N.r is the version number retrieved by LGETZM and k is
               incremented before OUTZM or OUTZMN are called.
               Keep the version numbers less than 99990 !                        (0)  *

KCYC         = Number of complete tide periods in one TTEQ-cycle                 (4) 
               IFF KCYC < 0: Use N_STEPS

LOADEFFECT   = 'GRAV' or 'OTEP' - one-component loading effects under
                                  EVLOAD (oteu16.f)
               'RADI' implies 'TANG' too, three components                  ('RADI')

MOD_EL_OUT   = Modulus of time-step number, output of elevation fields   (999999999)  *

N_CLOSE_DAMP = time step when run-in damping is turned off.                   ( 800)  *
               Start time offset due to I_Start or Start_Date will
               be added to  N_Hold_  and  N_Close_  by system.

N_HOLD_DAMP  = time step until run-in damping is constant.                     (300)  *

N_STEPS      = Number of time steps to iterate                                 (100)  *
               the harmonic analysis tide

               (will exceed KCYC or N_STEPS)                                (.true.)

N_RAMP       = time step when ramp-up of forcing is complete.                  (500)  *

No_Adv_Area(1..4) = Area limits (SW-, NE- corner, grid units)
               where to avoid the advection term.                   (99999,99998,..)  *

NONLIN       = Type of nonlinearity (0 1 2 or 3) Replaced by C_NONLIN
               1, 3 for shallow water
               2, 3 for advection                                                (1)  *

NRCYC        = Number of times TTEQ is to be called ("cycled")                   (3)  *

NSOL         = Dumped solution to be resumed, 999 meaning the last.             (-1)
               -1: Start from zero.

NSVER        = The version number of the solution to be produced - 1.            (0)  *

NVU          = number of tide constituents to be retrieved (and used
               for excitation)                                                  (30)  #

PATH         = (char*32) file name for retrieval of excitation data;
               'ETDX.DMP' is added.                                          ('./]')

PSPECA(1..10)= parameters (meaning depends on TTEQ, OTES12.f)               (10*1.0)  *

QAB_EAPR     = (logical) use inverse barometer response on
               active boundary                                              (.true.)  *

QAB_Step     = (logical) Do a step response experiment.
               Heaviside active boundary                                   (.false.)  *

QABF         = chg.relative amplitude factor for active boundary data      (.false.)  *

QABT         = substitute supplied active boundary tide;
               .false.: supply zero.                                        (.true.)  *

QADJ_TEND  = (logical) Adjust time steps to get complete periods of
             (periods of the basic reference tide)

QAP          = (logical) do air pressure                                   (.false.)  * 

QAPSTOP      = (logical) stop air pressure simulation

QBuoy        = (logical) Activate/deactivate                               (.false.)  *

QBT          = include body tide.                                           (.true.)  *

QFB          = free inner active 'Z'-boundary                              (.false.)  *

QHZ          = Harmonic analysis of elevation                               (.true.)  *
QHM          = Harmonic analysis of currents                               (.false.)  *
QHDC         = Analysis of the mean state                                  (.false.)  *
               If the mean state is not requested, the TIDEH is in effect

QLT          = include load tide.                                           (.true.)  *

QMYPRC       = execute the statements in INCLUDE file MYPRC.FI
               after reading namelist in program cycle                     (.false.)  *

QOUT_HARM    = (logical) Output harmonic solutions;
               begin at cycle number CYCWB                                  (.true.)

QPlay_with_ETD                                                             (.false.)
             = (logical) If enabled, ETDREP will call subroutine
               Play_with_ETD, which is included in otemt1.f
               Instructions and an example are included.

               Purpose is to manipulate with the tide-generating terms.

QProc_Buoys  = (logical) Process a buoy block in the INS-file.             (.false.)

QSafe_Buoy   = (logical) safe writing option (re-open/close)               (.false.)

QSafe_TGG    = (logical) re-open/close tide_gauge and
               potential_sensor files.                                      (.true.)  *

QSetEl       = (logical) Start with EL(i,j,.) = AB_Step_TV this cycle      (.false.)  *

QSPECA       = (logical) declare a special area (friction, eddy, ...)      (.false.)  *

QTAKE        = include tide constituents (dim=100, logical)             (100*.true.)

RANGE        = signal range for graphic screen [m]                             (1.0)  *

Samp_Int_EVL = sampling interval for loading effects [s]                     (3600.)

Samp_Int_TGG = sampling interval for tide gauges [s]                         (3600.)

SLP          = self-loading parameter.                                         (0.0)  *
START_DATE(3) = Year, month, day                                          (-1,-1,-1)

START_TIME(4) = Hour, minute, second, 1/100 second                         (0,0,0,0)
                Start_Date and _Time are used only if I_START=0

Target_EVL   = char*8 target string for loading computations.               ('SA] ')

TIDE         = the tide that determines fine-adjustment of the time step.
             = the basic reference tide                                       ('S2')

TIDEH        = name of the first harmonic to CTIDE (as an output file tag)
               If 'NO', output is suppressed. '..' generates a symbol "in

               tune" with CTIDE.  However, see QHDC                           ('..')  *

TSTEP        = Time step reduction factor: TSTEP * dt_crit => dt_used          (0.9)

ZABF         = new factor for act.bound. tides (complex*8)               ((1.0,0.0))  *

* = effective in namelist block #2.. (i.e. during program cycling).
# = must not exceed the value specified in namelist #1

Special considerations:

Logical file unit numbers:
  Unit 8 is reserved; it is used for some I/O in connection with screen graphics.
  IUSAP, IUNG are used temporarily. No need to change default values.
  IUEVL, IUEVL+1 and IUEVL+2 will be used for RADIal and TANGential.

Green's function file name:
  CALL EVL_GPATH  ('gpath]')
  CALL INIEVL_ETD ('name]',)
  results in  'gpathname.dat'

QMYPRC and include-file myprc.fi :
  Program code section (include-file) myprc.fi would typically contain code
  to update an area, change some boundary conditions etc.
  Using QMYPRC such feature can be included conditionally.
     Coding of a section requires good knowledge of OTEMT1.f, especially in
  concern of declared variables, array dimensions, whether an array can be
  used temporarily, ... The main program must be compiled with the myprc.fi
  code segment that applies to the special modification. You can keep a bank
  of code variations and incorporate them by e.g. symbolic links.
      Currently (that is on the 386-PC) MDL12\MYPRC.FI contains code to build
  a dam across the Strait of Gibraltar for MDL12.

  Use of flag array 'M' on condition QTTEQ=.true. :
  For example OTEMT1 uses array FLM and therefore supplies QTTEQ=.true.
  APLOAD doesn't, so it sets  QTTEQ=.false.
     Generally it is safest to code e.g.  CALL MY_TTEQ (call list) as the only
  statement in  myprc.fi, code a subroutine (e.g. file  mytteq.f), and include
  mytteq.o in the link file.

Running in the Background

The instruction file must be adjusted to have all graphic options set to no,

The process should be started by...

prompter> cd OTEQ
prompter> otemt1 MODEL/otemtabc > MODEL/otemtabc.prt
 > *.ins file () > $
prompter> jobs
[1]    Running                       /home/hgs/bin/emacswt MODEL/otemtabc.ins
[2]  + Suspended                     otemt1 MODEL/otemtabc > MODEL/otemtabc.prt
prompter> bg %2

If you have missed to set  Gra_Opt='n', wait until you obtain the graphic window
and the system prompts you there. You can enforce prompting by issuing  OC ^E
from a system prompter provided you are the same $USER as the one who started otemt1.

You select   Txtscr (press T )  and   Stop  (press  S ).
The window should disappear and not return again.

A new job's command should tell you  "[2] Running".  You can check the
activity of the program by keying
prompter> ps

In the list you get, otemt1 should show an increasing use of CPU time (third column)

Now you can log out.

When you log in again you can see whethter the process is still active by using the ps command:

prompter> ps -u userid | fgrep otemt1
  8756 ttyp6    27:57 otemt1

or the top command (showing the most heavy processes currently running)
or sending   OC ^E  and hoping the graphic window wakes up.

If the program has completed, the end of the print file will give you a hint:

prompter> tail -100 MODEL/otemtabc.prt