DIRSYS Getting started. SIMONA report number

(1)

DIRSYS

Getting started

(2)

(3)

Version : 1.1, January 2006

Maintenance : see www.helpdeskwater.nl/waqua Copyright : Rijkswaterstaat

DIRSYS

Getting started

(4)

(5)

Preface

DIRSYS

is a collection of Fortran-77 subroutines that makes it

possible to read data from the SDS-file by using logical names such

as MNMXAK (number of active points), SEP (water level), CZU,

CZV (Chézy in u- and v-direction), etc.

When retrieving arrays the result can be requested either in

compressed form (1:MNMAXK; like on the SDS-file: only points

within the enclosure) or in expanded form (1:NMAX,1:MMAX; as

requested by many postprocessing programs).

Furthermore standard operations can be performed on the data.

Examples are interpolation to water level points, interpolation to a

reference plane, filtering on time series, the marking of dry points,

etc..

In fact,

DIRSYS

is a layer above the

SIMONA

data structure and

memory management tools and is fully cooperative with

SIMONA

.

This means that writing a program using

DIRSYS

does not disable the

use of such

SIMONA

routines. This includes routines like

SISTAR

(start

SIMONA

),

SIDSOP

(open

SDS

-file) and

SIDSCL

(close

SDS

-file).

However, there is no need to use these tools of

SIMONA

. In principle,

DIRSYS

is a data-retrieval library only. However, extensions have

been implemented which enables the setting of data and even

creating

SIMONA

arrays and writing to an SDS-file as well.

DIRSYS

also consists of a Programmer's Guide, system documentation

and an addition of the message file. For each application

DIRSYS

needs a structured description of the LDS (a dlds-file, formerly

sds.doc).

(6)

(7)

Contents

1 About this manual... 1

2 Setting up the

DIRSYS

environment ... 3

3 DIRSYS

Local Data Structure (DLDS) ... 5

4 Acknowledged problems ... 7

5 Filling of IDA (Integer

DIRSYS

Array) ... 7

6 Simple examples... 9

6.1 Starting and stopping

DIRSYS

... 9

6.2 Activating arrays... 9

6.3 Get scalar value... 9

6.4 Get complete time independent array ... 10

6.5 Get complete time dependent array... 10

6.6 Get part of a time independent array ... 10

6.7 Get part of a time dependent array ... 10

6.8 ASCII output: dipasc... 11

6.9 ASCII output: dipmat ... 11

6.10 Matlab output, binary ... 12

6.11 Using the compute function ... 12

6.12 Large models: adjusting bufsize... 13

6.13 Error handling... 13

7 DIRSYS

programming style... 15

8 Combined examples ... 17

8.1 Water level time series to Matlab... 17

8.2 Concentration time series to Matlab ... 17

8.3 Water level map data to Matlab ... 17

8.4 Water level map data to Matlab (only active points) ... 18

8.5 Binary Matlab output with separate subroutine ... 18

8.6 Output in Waqiew format ... 18

8.7 SLIB

3 D

output in Waqview format ... 18

9 Recommendations ... 19

10 Appendices ... 21

10.1 Example 1... 21

10.2 Example 2... 23

10.3 Example 3... 25

10.4 Example 3b... 27

10.5 Example 5... 29

10.6 Example 6... 31

(8)

DIRSYS Getting Started iv

10.7 Example 7... 33

10.8 Example 8a ... 35

10.9 Example 8b... 37

10.10 Example 8c... 39

10.11 Example 9... 41

10.12 Example 10... 43

10.13 Example 11... 45

10.14 Example 12... 47

10.15 Example 13... 49

10.16 Example 14... 51

10.17 Example 14b... 53

10.18 Example 15... 55

10.19 Example 16... 57

10.20 libdgs.f... 59

10.20.1 opentxtfilew ... 59

10.20.2 startdirsys... 60

10.20.3 maxtimes... 61

10.20.4 haaldimensies ... 63

10.20.5 diminfo ... 64

10.20.6 printida... 65

10.20.7 leesuitvoer... 66

10.20.8 wbm1... 66

10.20.9 wbm2... 68

10.20.10 wbm3 ... 69

10.21 libdgs90.f... 70

10.22 guiwic.f ... 71

10.23 guiwrc.f ... 74

10.24 wagi2b.f... 78

10.25 wagr2b.f ... 80

10.26 wasrwm.f... 84

10.27 dgs.pl... 88

10.28 lgridplot.m ... 92

10.29 plotts.m... 93

10.30 Index ... 94

10.31 Log-sheet ... 96

(9)

About this manual

1 About this manual

This "

DIRSYS

Getting started" is written to provide the

SIMONA

user

with a number of examples with explanations how to use

DIRSYS

for

retrieving data from an SDS-file.

The first part shows some examples, which illustrate the most

important functions and output formats of

DIRSYS

.

Output formats are actually not a part of

DIRSYS

. This is a task for the

yet to build Conversion

SIDONIA

component.

The second part shows how the user can retrieve time series and map

data from the SDS file and how (s)he can visualise them in Matlab.

In each paragraph a small example program is described. The

example programs self can be found in the appendixes. In the

examples Fortran-77 and Fortra-90 are both used. The reason for this

is that

SIMONA

assumes the use of Fortran-77, whereas in the near

future Fortran-90 will be used.

The

DIRSYS

routines are described briefly, because they are

extensively described in the Programmer's Guide.

(10)

(11)

Setting up the dirsys environment

2 Setting up the DIRSYS environment

DIRSYS

is an extension of

SIMONA

and to run a

DIRSYS

program the

following files have to be copied to the current directory:

simona.env

SIMETF (file with

SIMONA

error messages)

lds.dlds (concatenation of among others

GEN_MESH_PROB_lds.dlds en WAQUA_lds.dlds)

For compiling the following libraries are necessary:

dirsys.a, blas.a and tools.a.

In the examples in this manual, the run script dgs.pl arranges this.

In the Fortran program self

DIRSYS

has to be started and stopped, see

paragraph 6.1

(12)

(13)

dirsys Local Data Structure (DLDS)

3 DIRSYS Local Data Structure (DLDS)

DIRSYS

fills its administration concerning the

SIMONA

data structure

by reading ASCII-input files describing the

LDS

. The files are called

the "

DLDS

" files, referring to their extension.

Using these files, any

SDS

file can be accessed using

DIRSYS

, as long

as the

LDS

description in the

DLDS

file meets the

LDS

stored in the

SDS

-file.

DIRSYS

requires these dlds-files in order to retrieve variables. For

WAQUA

/

TRIWAQ

and

SIMPAR

such a description is standard available.

Therefore

DIRSYS

expects the file lds.dlds in the current directory.

Normally the run script will take care of this. By using the function

DIRDOC

another file name can be used. See the example with a

SLIB

3 D

SDS-file in paragraph 10.19.

Directory system

As a

SIMONA

LDS is a hierarchical data system, it looks very much

like a

DIR

ectory

SYS

tem (

DIRSYS

): each compound array can be seen

as a "directory" in which new directories (compound arrays) or files

(data arrays) can reside.

Point of origin in

DIRSYS

is that each

SIMONA

level has a

characteristic name (in capitals), in which the tree structure is visible

(like a directory structure, but in

SIMONA

separated by " " instead of

"/" in

DIRSYS

). For example: top-level array

MESH

has sublevels

MESH IDIMEN

,

MESH LGRID

and so on. Suppose array

MAIN

was a

sublevel of

MESH IDIMEN

, its name would be

MESH IDIMEN MAIN

.

SIMONA

arrays not fulfilling this concept cannot be processed using

DIRSYS

.

DIRSYS

names

The

DIRSYS

naming convention is the same as the above-mentioned

SIMONA

characteristic names, except that ' ' (underscore) is replaced

by '/' (slash) for each level. For example "/mesh/idimen/main".

DIRSYS

uses the fact that the

SIMONA

applications until now only use

uppercase characters for the characteristic names. Each time

DIRSYS

has to find a

DIRSYS

name, it is first capitalized, and then searched in

the

SIMONA

administration. This implicates that

DIRSYS

names are

case insensitive for the user.

The full name of a variable always starts with a "/" (slash). Using a

full name means specifying the complete path to an array.

Extension to

The lowest level in

SIMONA

is a data array, in which often a number

s

IMONA

arrays

of variables reside. Like in

MESH IDIMEN

:

MMAX

,

NMAX

,

MNMAXK

,

and so on. Within a

SIMONA

application, the programmer must count

the offset within a

SIMONA

array, using the

LDS

description on paper.

In a

DIRSYS

application it is possible to have

DIRSYS

administrate

these lower level variables as well, with their own type and

dimension. An application just has to refer to

MMAX

(or

/

MESH

/

IDIMEN

/

MMAX

to be sure), and

DIRSYS

will take care of

computing the right offset.

(14)

(15)

Acknowledged problems

4 Acknowledged problems

DIRSYS

works with names from the data dictionary, like for example

“

SEP

” for water levels. A problem hereby is that certain names occur

more than once in the data dictionary.

An example is “

TIMDIS

”. In such a case the full path has to be given:

"/

PROBLEM

_

FLOW

/

DISCH

/

TIMDIS

".

DIRSYS

does not distinguish upper case from lower case.

Furthermore routine

DIPASC

does not work exactly as described in

the documentation.

5 Filling of IDA (Integer DIRSYS Array)

Dirsys administrates dimensions of variables. A maximum of 10

dimensions can be used for a single variable. Each dimension may be

given a name, in order to be able to set a certain dimension range

using its name. For instance, array

UP

(u-velocities,

WAQUA

/

TRIWAQ

)

is dimensioned

UP

(

N

=1:

NMAX

,

M

=1:

MMAX

,

LAYER

=1:

KMAX

).

Note that the sequence of the dimensions may be different from the

declaration, as dimension names are used by

DIRSYS

to look up the

corresponding dimension (case insensitive). The names of the

dimensions may be omitted, in which case the sequence must

correspond to the declaration.

In order to retrieve an array with

DIRSYS

, an array with dimensions

has to be given. In this paragraph the meaning of this array’s

elements are described, together with some much-used examples.

The definition of IDA:

integer ida(2, mdim+1)

(1,1) number of dimensions of the

DIRSYS

variable

(2,1) number of dimensions of IDA minus 1 (typically mdim)

(1,2) start first dimension

(2,2) end first dimension

(1,3) start second dimension

(2,3) end second dimension

(.,.) etc.

A few examples are:

For a 2D field,

only active points (mnmaxk):

(1,1) 1

(2,1) mdim

(1,2) 1

(2,2) mnmaxk

For a 3D field, only active

points (mnmaxk,kmax):

(1,1) 2

(2,1) mdim

(1,2) 1

(2,2) mnmaxk

(1,3) 1

(2,3) kmax

(16)

DIRSYS Getting Started

8

For a 2D field,

all points (nmax,mmax):

(1,1) 2

(2,1) mdim

(1,2) 1

(2,2) nmax

(1,3) 1

(2,3) mmax

For a 3D field, all

points (nmax,mmax,kmax):

(1,1) 3

(2,1) mdim

(1,2) 1

(2,2) nmax

(1,3) 1

(2,3) mmax

(1,4) 1

(2,4) kmax

DIRSYS

has two routines that can fill IDA:

DIGDIM

en

DIRDIM

.

Digdim gives back the dimensions corresponding to a variable;

dirdim translates a string in the form of '(n=1:9999,m=1:9999)'.

LGRID

pointers

In

DIRSYS

it is possible to let a dimension be accessed indirectly,

using a pointer array. In the example, when you want to access

up(n=5,m=3,layer=2)

you will actually get

up(lgrid(5,3),2).

DIRSYS

will perform this translation itself, when the dimension is

declared as follows in the

DLDS

file:

(p:lgrid=mnmaxk,layer=kmax).

The first dimension is declared to be a "pointered" dimension, using

pointer array

LGRID

.

The automatic translation of pointers by

DIRSYS

can be switched off

using routine

DIPOIN

. By default, it is switched on. This switch has

impact on all your interfacing with

DIRSYS

. Asking for the

dimensions of

UP

with the switch on will result in returning 3

dimension (n,m,k), with the switch off in returning 2 dimensions

(nm,k). Asking for a partial array

UP

must be done using 3

dimensions with the switch on, but with 2 dimensions with the switch

off. Etc, etc

(17)

Simple examples

6 Simple examples

6.1 Starting and stopping

DIRSYS

In a program

DIRSYS

can be initialised by routine

dirope

. The

program is stopped with routine

diclos

.

Furthermore each

DIRSYS

program, subroutine or function begins and

stops with routine with

dirstk

. Dirstk is important for the error

messages system.

See example in § 10.1 for a very simple

DIRSYS

program.

6.2 Activating arrays

SIMONA

insiders not using

DIRSYS

are used to perform the following

steps when reading some value(s) from an SDS file:

1. read array from the

SDS

file

2. get

IBUFFR

offset

3. get value(s) from

IBUFFR

Using

DIRSYS

, however, things go different. Reading from an SDS

file is done automatically when

DIRSYS

notices the array is not read

yet, or when another time is needed than the one in memory.

Activating arrays and computing

IBUFFR

offsets is also done

automatically when you request values from the

LDS

. For example,

when you

want to read the value of

MMAX

, you just call

mmax = idigsi('mmax',sds,exp,ierr)

and all opening

SDS

-file, reading, activating, etc. is done by

DIRSYS

.

DIRSYS

pointers

In order to make all above possible,

DIRSYS

has its own

administration, which is an extension to the

SIMONA

administration.

This administration is stored in the

DIRSYS

common blocks

CDIVAR

and

CDICHA

. All

DIRSYS

names are stored in

CDICHA

, with pointers in

CDIVAR

to the

SIMONA

INFOR

-table, to connect a

DIRSYS

variable

with a

SIMONA

characteristic name.

Thus, using

DIRSYS

introduces an extra pointer (

DIRSYS

pointer),

pointing to the

INFOR

-table (

SIMONA

pointer), which in turn points to

IBUFFR

(

IBUFFR

-pointer).

SIMONA

-programmers know they first have to activate all

SIMONA

arrays needed for a certain action, get the

SIMONA

-pointers, and

finally get all

IBUFFR

-pointers. Using

DIRSYS

this is not different:

first get all

DIRSYS

-pointers (automatically reading/activating arrays),

then get all

IBUFFR

-pointers.

6.3 Get scalar value

In the first example three scalars are retrieved and printed out. For

retrieving the functions

idigsi

and

rdigsi

, and the subroutine

digsc

are used. Function idigs gets an integer, function rdigsi gets a real

and routine digsc gets a string. The functions (ir)digsi have four

arguments: the name of the variable to be collected, the name of the

SDS file, the experiment name and the error code. It is very

important to check if the error code has the value 0. In that case a

serious error occurred. The subroutine digsc has five arguments: the

(18)

10

first three and the last argument are the same as with (ir)digsi, the

fourth argument contains the requested string.

(see example in § 10.1 and § 10.27)

6.4 Get complete time independent array

A couple of things are important when retrieving an array:

is the array time dependent or time independent?

is it an integer, real or string array?

whole array or part of the array?

All points or only active points?

To begin with the last point: internally

DIRSYS

translates the “only

active points(mnmaxk)” to “all points(nmax,mmax)” by default.

This can be changed by routine

dipoin

.

In the second example the array H (depths) is retrieved. First the 2D

array with all points is retrieved and then the 1D array with only the

active points. The retrieving is done with subroutine

digrar

. In this

example

digdim

is used to fill IDA (see example in § 10.2 and §

10.27).

6.5 Get complete time dependent array

When retrieving a time dependent array, it has to be known for which

time instance the array is required.

Routine

digtim

can be used for this. In example 3 (see § 10.3), array

SEP is retrieved for the second time instance. Also TFMAPF,

TIMAPF and TLMAPF (first time, time interval and last time to

write map data) could be used to determine for which time instances

arrays are available. A possible danger is that these arrays have yet to

be computed for certain time instances, or that due to halfway

interruption, data not for all time instances available is (see example

in § 10.3 and § 10.27)

TFMAPF, TIMAPF and TLMAPF could be used to determine the

maximum of time instances. In Fortran-90 the output array in digtim

can then be created dynamically. Apart from that the available time

instances for FLOW and TRANS can have different values (see

example in § 10.4 and § 10.27).

6.6 Get part of a time independent array

Maybe for the future.

6.7 Get part of a time dependent array

There are two ways for retrieving a part of an array: a crosscut of the

region of interest, or a certain layer in a Triwaq computation. In

example five de salinity is retrieved for each layer (separate) with

routine

digrpa

(see example in § 10.5 and § 10.27) .

(19)

Simple examples

6.8 ASCII output: dipasc

DIRSYS

has two routines for output:

dipmat

and

dipasc

. Dipmat,

output for Matlab, is extensively described in the next paragraph.

Dipasc has 11 parameters. The interface is as follows:

subroutine dipasc (lu, icode, varnam, sds, exp, times, idimin, + form1, timfor, dumval, ierr)

Varnam, sds, exp, times, idimin and ierr have the usual meaning of

respectively the

DIRSYS

variable, the name of the SDS-file, the

experiment name, array with start, increment, and end times, and the

error code. The others have the following meaning:

lu

unit number for output

icode

code for type of output:

1=free format,

2=box format,

3=Matlab script,

4=binary Matlab (not yet implemented)

form1

Fortran format for output, e.g. '(9(1x,E12.6))' or '(9F12.5)'.

For icode = 2 (box) or icode = 3 (Matlab) the number of

values per line can be decreased to keep the number of

characters per line under 121.

timfor

Fortran format for time instance, may be empty

Dumval value for non-active points

For printing an array with icode = 1 (free format) or icode = 2 (box

format) the lgrid pointering has to be turned on. For icode=box that

is obvious but for icode=free it isn’t, so there has to be looked at (see

example in § 10.6 and § 10.27).

6.9 ASCII output: dipmat

To produce (ASCII) Matlab output dipmat is available. The interface

is as follows:

subroutine dipmat ( lu, varnam, sds, exp, times, idimin, ierr )

Varnam, sds, exp, times, idimin and ierr have the usual meaning of

respectively the

DIRSYS

variable, the name of the SDS-file, the

experiment name, array with start, increment, and end times, and the

error code; lu is the unit number for output. When lgrid pointering is

turned on, all non-active points get the value 0. It seems that per time

instance one value can be written (see example in § 10.7 and §

10.27).

(20)

12

6.10 Matlab output, binary

Binary Matlab output has not yet been implemented in

DIRSYS

, but

an alternative is given in paragraph 8.5.

6.11 Using the compute

function

Another extension to

SIMONA

is the use of "computational fields".

These are arrays/values computed using other

LDS

variables or even

other computational fields, and possibly user input. Computational

fields are defined in the

DLDS

files, specifying which

LDS

variables

are needed as input, which user input, what work space and what

output must be generated. For now the following functions are

available:

Velocity at water level points

Potential field

Zmap (Interpolation to reference plane)

Dryfall

There is a big difference between the first two and the last two. The

first two are simple in use; the last two require many fields to be

filled. An example of velocities in water level points and the potential

field can be found in (see example in § 10.8 and § 10.27). This

example makes clear that VELU, VELV and PSI can be used as

"regular"

DIRSYS

variables.

Computing

The actual computation is performed when an output array is

accessed by some function. At that time

DIRSYS

will activate all input

arrays needed (at the requested time), create temporary workspace

when appropriate, create output arrays, and call a dedicated routine

computing the output. When a second access is performed to the

same or another output array of the same computational field,

DIRSYS

will know that all initialisation and computation is already done, and

therefore will just return the requested data.

The routine performing the actual computation is written specially

for the computational field requested, and requires in- and output

parameters in the same sequence as specified in the

DLDS

file.

Therefore,

THE DLDS FILE SHOULD NOT BE CHANGED

without

changing the computational routine as well.

Output arrays

The output arrays of computational fields can be accessed just like

other

LDS

variables, using the same routines. When one or more input

arrays are time-dependent, the output arrays will be time-dependent

as well, with the same time list. The name of an output array is the

name of the computational field (level 1), extended with the name of

the requested output field (level 2). For example "/snelheid/velu" or

"/snelheid/velv".

Characteristics

The output arrays get

SIMONA

characteristic names as soon as they

are created. The characteristic name will be:

(21)

Simple examples

level1: <computational field name>

level2: <output array name>

For example, the computational field "

SNELHEID

" (Waqua/Triwaq)

computes u- and v-velocities in the (x,y) plane at water level points.

The output arrays are called "

VELU

" and "

VELV

". The following

characteristic names are created:

SNELHEID

SNELHEID VELU

SNELHEID VELV

VAR INPUT

A computational field may contain variable input. Variable input

consists of names of

LDS

variables, defined before in the

DLDS

file.

They can be replaced by other pointers, using routine

DISVAR

.

USER INPUT

Sometimes user input is needed,

for example when velocity is to be

computed at a certain z-level. The z position will be user input. In a

computational field this can be specified (in the

DLDS

file) using

keyword

USER INPUT

. After this keyword, one or more variables

and/or arrays can be declared, using the regular dimensioning, typing

and naming convention of the

DIRSYS

DLDS

-file. The names of these

variables/arrays will be

/{computational field name} USER/{array name}>

For example:

/zmap user/zpos

All user input is default set to zero, which can be overruled by an

application using regular

DIRSYS

routines.

An example of interpolation to a reference plane can be found in (see

example in § 10.9 and § 10.27). The routines idipsr and idipsi set a

few parameters and disvar links ZMAP to RP. After all this

RMAP2D can be used as a normal

DIRSYS

variable.

Dryfall can be used in an almost similar way. Only difference is that

no new

DIRSYS

variable is created but the original value is

overwritten. An example of Dryfall is in (see example in § 10.10 and

§ 10.27).

6.12 Large models: adjusting bufsize

The default buffer size is specified in the environment file (located in

$SIMONADIR/bin/). The default buffer size can be overruled with

the command-line option –bufsize

<rval>

.

6.13 Error handling

DIRSYS

has a different way for tracing errors than

SIMONA

. It still

uses the

SIMONA

routine

SIERRO

, but the user controls whether or not

DIRSYS

should print the messages. If not, the messages are user

controlled except for fatal errors.

In

SIMONA

applications a routine-path is administrated by passing

parameter "name1(1:ilen)" to most of the

SIMONA

routines. At the

start of an application, "name" is filled with the application name,

(22)

14

and in each called routine, this named is padded with the routine

name separated by a colon (using

SIMONA

routine

SICONC

).

In

DIRSYS

applications, tracing the routine-path in which an error

occurs is done by using the routine

DIRSTK

instead of passing

parameter "name" and padding it with the actual routine-name. At

routine entry

DIRSTK

can be called to set "name" to the path of the

calling routine and "name1" to the path of the actual routine. At

routine exit

DIRSTK

should be called to reset "name" and "name1".

Next 3 routines are related to error solving:

-

DIERRO

: print error message

-

DIPERR

: do/do not let

DIRSYS

print error messages

-

DIRSTK

: set/reset routine calling path

DIRSYS

has the possibility to suppress error messages. This can be

done by calling routine

diperr

with .false.. For several parts of the

program the suppressing can be turned off again.

(23)

dirsys programming style

7 DIRSYS programming style

To avoid all sorts of complex issues the examples in chapter 5 are

kept relatively simple.

However, in practice the programs are getting more and more larger

and more difficult, so you have to keep the maintenance of the

program in mind, as soon as possible. A good programming style can

help to keep the program readable and maintainable. A few tips:

Prevent the retrieval of non-existing arrays by first checking the

existing. Furthermore always check which error code

DIRSYS

returns. In testing phase, let error occur and see how they get

handled.

All

DIRSYS

actions belonging together should be kept in a (small)

separate routine.

Use of meaningful comment code, and description of used

variables (see

OMS

/

SIMONA

norm).

Use of a flag to produce little, much or very much debug output.

Let another programmer have a look at your code: it’s a valuable

experience for the both of you!

If you write a general function reconsider to (re)write it as a

compute function (see § 6.11), and take it to Simona*B+O.

(24)

(25)

Combined examples

8 Combined examples

8.1 Water level time series to Matlab

The water level time series are described with the

DIRSYS

variables:

blftim times on which history data is written

blzwl water levels at the water level stations

namwl names of water level stations

nowl number of water level stations

nuthbf number of time instances

These variables are written with function dipmat. After this you can

type plot(BLFTIM,BLZWL) in Matlab or the Matlab script

"plotts.m" (see § 10.29) can be used:

plotts(NAMWL,BLFTIM,BLZWL,string), where through string a

selection can be made on station names.

Type “help plots” in Matlab for the exact possibilities (see example

in § 10.12 and § 10.27).

8.2 Concentration time series to Matlab

Concentrations (e.g. salt) time series are described with the

DIRSYS

variables:

blttim Times on which concentrations history data is written

blgro concentrations at concentration stations

nampol names of concentration stations

nopol number of concentrations stations

nuthbt number of time instances

A difference with the last example is that a timeserver exists for each

(vertical) layer and for each transported substance. In the example

one layer and one substance are written. In this example also a line of

Matlab code is added, that removes 2 empty dimensions.

In Matlab

m

is read and plot(BLTTIM,BLGRO) is typed (see

example in § 10.13 and § 10.27).

8.3 Water level map data to Matlab

To plot map data in Matlab, besides the field self, also the grid

coordinates have to be given. With visualisation you are mostly

interested in the active points, so we use the compute function

dryfall. Non-active points are set to 2E30, and with an extra line

Matlab-code they are set to NaN (see example in § 10.14 and §

10.27). In Matlab: pcolor(XZETA,YZETA,SEP); shading flat;

colorbar;

(26)

18

Because of the plotting properties of pcolor the grid should be shifted

half the size of a grid cell in both directions.

8.4 Water level map data to Matlab (only active points)

It is also possible to write only the active points. This saves disk

space and CPU time for writing and reading en possible network

traffic. The array LGRID has once to be written first to do this, and in

Matlab everything has to be expanded (see example in § 10.15 and §

10.27). In Matlab: lgridplot(LGRID,XZETA,YZETA,SEP) (see §

10.28).

8.5 Binary Matlab output with separate subroutine

Marcel Zeilema from RIKZ has written a routine waswrm that can

produce a binary Matlab file (.mat). In this example a variable is

retrieved by

DIRSYS

and with waswrm written to a Matlab file (see

example in § 10.16 and § 10.27).

Actually waswrm is a shell around guiwrc; a routine that performs

the conversion to Matlab. In the next example the routine guiwrc is

used direct (see example in § 10.17 and § 10.27).

8.6 Output in Waqiew format

Waqview can read the

SIMONA

box format. This makes it possible to

plot a quantity, a quantity not implemented in Waqvie, or a quantity

from Simpar or Slib3d. The example program produces output in box

format.

By starting Waqview with

waqview.run

the contents of the box file is

plotted (see example in § 10.18 and § 10.27).

8.7 SLIB

3 D

output in Waqview format

In order to read a

SLIB

3 D

file with

DIRSYS

, the dlds-file of

SLIB

3 D

should be available. However, for the time being the standard

environment does not contain such a dlds-file. A temporary

work-around is available. In example 16 slib mass or slib concentrations

are written to box format. Later they can be plotted in e.g. Waqview

(see example in § 10.19 and § 10.27).

(27)

Recommendations

9 Recommendations

The function maxtimes is very useful and should become

available as a compute function.

The use of Fortran-77 and Fortran-90 mixed together results in

unnecessary complications. It’s about time that

SIMONA

switches

to Fortran-90.

When new applications are admitted, a dlds file should also be

admitted.

For printing an array with dipasc, with icode = 1 (free format) or

icode = 2 (box format) the lgrid pointering has to be turned on.

For icode=box that is obvious; in both situations this it not

according to the documentation.

(28)

(29)

Appendices

10 Appendices

10.1 Example 1

program dgs_ex_1 c ******************************************************************** c

c Programmer Edwin Spee; RIKZ; OSA; SIMONA. c Version 1.0 Date 05-Aug-2003

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started c Example 1: get scalair value c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 name, name1,sds,exp,itdate integer idigsi, mnmaxk, ierr, ilen real rdigsi, dksi

c

c Initialisatie voor foutmeldingensysteem: c

call dirstk (name, 'vb_1', name1, ilen) c

c Lees naam SDS-file: c

write (*,*) 'Geef naam van de SDS-file:' read (*,'(a)') sds

exp = ' ' c

c Start Simona en Dirsys: c

call dirope (sds, exp) write (*,*)

write (*,'(a a)') ' exp = ',exp c

c Haal scalairen mnmaxk en dksi op: c Stop bij eventuele fout.

c

mnmaxk = idigsi ('mnmaxk',sds,exp,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij idigsi-mnmaxk' else

write (*,'(a,i6)') 'mnmaxk = ', mnmaxk endif

dksi = rdigsi ('dksi',sds,exp,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij rdigsi-dksi' else

write (*,'(a,f4.1)') 'dksi = ', dksi

endif

call digsc('itdate',sds,exp,itdate,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij digsc-itdate' else

write (*,'(2a)') ' itdate = ', itdate endif

(30)

22

c

c Sluit Simona/Dirsys netjes af:

c

call diclos c

c Reset calling path c

call dirstk (name, ' ', name1, ilen) end

(31)

Appendices

10.2 Example 2

program dgs_ex_2

c ******************************************************************** c

c Programmer Edwin Spee; RIKZ; OSA; SIMONA. c Version 1.0 Date 28-Jul-2003

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started

c Example 2: get time-independent-array H (depths) c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 name, name1,sds,exp, namdim(mdim) integer idigsi, mnmaxk, mmax, nmax, ierr, ilen, idim(2,mdim+1) real time

real, allocatable :: h1(:),h2(:,:) c

exp = ' ' c

call dirope(sds, exp) write (*,*)

c Haal scalairen mnmaxk, mmax, en nmax op: c mnmaxk = idigsi('mnmaxk',sds,exp,ierr) mmax = idigsi('mmax',sds,exp,ierr) nmax = idigsi('nmax',sds,exp,ierr) c c alloceer arrays: c

allocate(h1(mnmaxk), h2(nmax,mmax), stat=ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij allocate.' call diclos

endif c

c vul time, idim en haal data op voor h2: c time = 0.0 idim(2,1) = mdim call digdim('h',sds,exp,idim,namdim,ierr) call printida(idim,namdim,name1(1:ilen)) call digrar('h',time,sds,exp,h2,idim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij ophalen h2' call diclos

endif c

c schakel lgrid-pointering uit: c

(32)

24

c

c vul time, idim en haal data op voor h1: c time = 0.0 idim(2,1) = mdim call digdim('h',sds,exp,idim,namdim,ierr) call printida(idim,namdim,name1(1:ilen)) call digrar('h',time,sds,exp,h1,idim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij ophalen h1' call diclos

endif c

c eenvoudige uitvoer: min, gem. en max h1, h2: c

write (*,'(a,3(1x,SPE9.3))') 'Min, mean, max h1 = ', & minval(h1(2:mnmaxk)), sum(h1(2:mnmaxk))/(mnmaxk-1), & maxval(h1(2:mnmaxk))

write (*,'(a,3(1x,SPE9.3))') 'Min, mean, max h2 = ', minval(h2), & sum(h2)/(mmax*nmax), maxval(h2)

c

c Sluit Simona/Dirsys netjes af: c

call diclos c

call dirstk(name, ' ', name1, ilen) end

(33)

Appendices

10.3 Example 3

program dgs_ex_3

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started c Example 3: get time-dependent-array c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 name, name1,sds,exp, namdim(mdim) integer i, idigsi, mnmaxk, ierr, ilen, idim(2,mdim+1), lentim integer, parameter :: maxlentim = 10

real time, timlst(maxlentim) real, allocatable :: sep(:) c

exp = ' ' c

c Haal mnmaxk op: c

mnmaxk = idigsi('mnmaxk',sds,exp,ierr) c

c alloceer array sep: c

allocate(sep(mnmaxk), stat=ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij allocate.' call diclos endif c c vul timlst c lentim = maxlentim call digtim('sep',sds,exp,timlst,1,lentim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij digtim.' call diclos

endif

if (lentim .le. 2) then

write (*,*) 'Te weinig tijdstippen beschikbaar.' call diclos

endif c

(34)

26

c schakel lgrid-pointering uit:

c

call dipoin('n') c

c vul idim en haal data op voor sep: c

time = timlst(2) idim(2,1) = mdim

call digdim('sep',sds,exp,idim,namdim,ierr) call digrar('sep',time,sds,exp,sep,idim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij ophalen sep' call diclos

endif c

c eenvoudige uitvoer: min, gem. en max sep c en (eerste) beschikbare tijdstippen: c

write (*,'(a,3(1x,SPE9.3))') 'Min, mean, max sep = ', & minval(sep(2:mnmaxk)), sum(sep(2:mnmaxk))/(mnmaxk-1), & maxval(sep(2:mnmaxk))

write (*,'(a,10f8.2)') ' Sep weggeschreven op:', & (timlst(i),i=1,lentim)

c

call diclos c

(35)

Appendices

10.4 Example 3b

program dgs_ex_3b

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c Example 3b: get time-dependent-array; timlst is allocatable c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 name, name1,sds,exp

integer i, idigsi, mnmaxk, ierr, ilen, idim(2,mdim+1), lentim integer maxlentim, maxtimes

real time

real, allocatable :: sep(:), timlst(:) c

call dirstk (name, 'vb_3b' , name1, ilen) c

exp = ' ' c

c Haal mnmaxk op: c Stop bij eventuele fout. c

mnmaxk = idigsi('mnmaxk',sds,exp,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij idigsi-mnmaxk' call diclos

endif c

c alloceer array sep: c

allocate(sep(mnmaxk), stat=ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij allocate.'

call diclos endif c

c zoek bovengrens van aantal tijdstippen op SDS-file: c en allocate timlst

c later maxtimes in een computefunctie stoppen!!! c

(36)

28

write (*,*) 'maxlentim = ', maxlentim

allocate(timlst(maxlentim), stat=ierr)

if (ierr .ne. 0) then

write (*,*) 'Fout bij allocate.' call diclos endif c c vul timlst c lentim = maxlentim call digtim('sep',sds,exp,timlst,1,lentim,ierr) write (*,*) 'lentim = ', lentim

if (ierr .ne. 0) then write (*,*) 'Fout bij digtim.' call diclos

endif

write (*,*) 'Te weinig tijdstippen beschikbaar.' call diclos

endif c

call dipoin('n') c

c vul idim en haal data op voor sep: c time = timlst(2) idim(1,1) = 1 idim(2,1) = mdim idim(1,2) = 1 idim(2,2) = mnmaxk call digrar('sep',time,sds,exp,sep,idim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij ophalen sep' call diclos

endif c

c eenvoudige uitvoer: min, gem. en max sep c en (eerste) beschikbare tijdstippen: c

write (*,*) 'Min, mean, max sep = ',

& minval(sep(2:mnmaxk)), sum(sep(2:mnmaxk))/(mnmaxk-1), & maxval(sep(2:mnmaxk))

write (*,'(a)') ' Sep weggeschreven op:' write (*,'(10f8.2)') timlst(1:lentim) c

call diclos c

(37)

Appendices

10.5 Example 5

program dgs_ex_5

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started c Example 5: get time-dependent-array c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 name, name1,sds,exp integer i, k, kmax, idigsi, mnmaxk, ierr, ilen, & idim1(2,mdim+1), idim2(2,mdim+1), lentim integer, parameter :: maxlentim = 10 character*12 namdim(mdim+1) real time, timlst(maxlentim) real, allocatable :: zout(:) c

exp = ' ' c

c Haal mnmaxk en kmax op: c Stop bij eventuele fout. c

mnmaxk = idigsi('mnmaxk',sds,exp,ierr) kmax = idigsi('kmax',sds,exp,ierr) c

c alloceer array zout: c

allocate(zout(mnmaxk), stat=ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij allocate.' call diclos endif c c vul timlst c lentim = maxlentim call digtim('rp',sds,exp,timlst,1,lentim,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij digtim.' call diclos

(38)

30

write (*,*) 'Te weinig tijdstippen beschikbaar.'

call diclos endif c

call dipoin('n') c

c vul idim1, idim2, namdim en haal data op voor zout: c do k = 1, kmax time = timlst(lentim) idim1(1,1) = 1 idim1(2,1) = mdim idim1(1,2) = 1 idim1(2,2) = mnmaxk idim2(1,1) = 3 idim2(2,1) = mdim idim2(1,2) = 1 idim2(2,2) = mnmaxk idim2(1,3) = k idim2(2,3) = k idim2(1,4) = 1 idim2(2,4) = 1 namdim(1) = 'p:lgrid' namdim(2) = 'layer' namdim(3) = 'constit' call digrpa('rp',time,sds,exp,idim2,namdim,zout,idim1,ierr) if (ierr .ne. 0) then

write (*,*) 'Fout bij ophalen zout' call diclos

endif c

c eenvoudige uitvoer: min, gem. en max zout c en (eerste) beschikbare tijdstippen: c

write (*,'(a,i,3f8.2)') ' Min, mean, max zout k = ',k,

& minval(zout(2:mnmaxk)), sum(zout(2:mnmaxk))/(mnmaxk-1), & maxval(zout(2:mnmaxk))

enddo

write (*,'(a,10f8.2)') ' zout weggeschreven op:', & (timlst(i),i=1,lentim)

c

call diclos c

(39)

Appendices

10.6 Example 6

program dgs_ex_6

c ******************************************************************** c

c Programmer Edwin Spee; RIKZ; OSA; SIMONA. c Version 1.0 Date 04-Aug-2003

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started c Example 6: voorbeeld uitvoer dipasc c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 filename,name, name1,sds,exp,fmtstr, namdim(mdim) integer ierr, ilen

integer lu, iref, info(4), idim(2,mdim+1) real times(3), my_nan

parameter (my_nan = 2E30) c

exp = ' ' c

c Open uitvoer file c filename = 'test_vb_6.box' info(1) = 2 info(2) = 0 info(3) = 0 info(4) = 0

call siflop (filename, info, iref, name1(1:ilen)) lu = ireffl(1,iref)

c

c zet lgrid-pointering aan (nodig voor icode=1 en icode=2): c

call dipoin('y') c

c zet times, idim en fmtstr c fmtstr = '(9(1x,SPE12.6))' times(1) = 0.0 times(2) = 1.0 times(3) = 0.0 idim(2,1) = mdim call digdim('xzeta',sds,exp,idim,namdim,ierr) call dipasc (lu,2,'xzeta',sds,exp,times,idim,

(40)

32

& fmtstr,' ', my_nan, ierr)

write (*,*) 'Fout bij dipasc xzeta' endif

c

c sluit uitvoer bestand: c

call siflcl ( iref, name1(1:ilen) ) c

call diclos c

(41)

Appendices

10.7 Example 7

program dgs_ex_7

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c A part of the dirsys Getting Started c Example 7: voorbeeld uitvoer dipmat c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 filename,name, name1,sds,exp,namdim(mdim) integer ierr, ilen

integer lu, iref, info(4), idim(2,mdim+1) integer lentim, maxlentim

parameter (maxlentim = 10) real times(3), timlst(maxlentim) c

exp = ' ' c

c Open uitvoer file c filename = 'test_vb_7.m' info(1) = 2 info(2) = 0 info(3) = 0 info(4) = 0

c

c zet lgrid-pointering aan c

call dipoin('y') c

c zet times en idim

c

lentim = maxlentim

call digtim('sep',sds,exp,timlst,1,lentim,ierr) times(1) = timlst(lentim-1)

times(2) = timlst(lentim) - timlst(lentim-1) times(3) = timlst(lentim)

idim(2,1) = mdim

call digdim('sep',sds,exp,idim,namdim,ierr) call dipmat (lu,'sep',sds,exp,times,idim, ierr)

(42)

34

endif

c

call diclos c

(43)

Appendices

10.8 Example 8a

program dgs_ex_8a

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c Example 8a: voorbeeld compute functie snelheid en psi (pot. veld) c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 filename,name, name1,sds,exp, namdim(mdim) integer ierr, ilen

parameter (maxlentim = 10) real times(3), timlst(maxlentim) c

call dirstk (name, 'vb_8a', name1, ilen) c

exp = ' ' c

c Open uitvoer file c filename = 'test_vb_8a.m' info(1) = 2 info(2) = 0 info(3) = 0 info(4) = 0

c

call dipoin('y') c

c zet times en idim

c lentim = maxlentim call digtim('sep',sds,exp,timlst,1,lentim,ierr) times(1) = timlst(lentim) times(2) = 1.0 times(3) = timlst(lentim) idim(2,1) = mdim call digdim('velu',sds,exp,idim,namdim,ierr) call printida(idim,namdim,name1(1:ilen))

call dipmat (lu,'velu',sds,exp,times,idim, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij dipmat velu'

(44)

36

call digdim('velv',sds,exp,idim,namdim,ierr) call dipmat (lu,'velv',sds,exp,times,idim, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij dipmat velv'

call digdim('psi',sds,exp,idim,namdim,ierr) call dipmat (lu,'psi',sds,exp,times,idim, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij dipmat psi' c

call diclos c

(45)

Appendices

10.9 Example 8b

program dgs_ex_8b

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c Example 8b: voorbeeld compute functie zmap c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 filename,name, name1,sds,exp, namdim(mdim) integer idipsi, idipsr, ierr, ilen, idigsi, kmax

parameter (maxlentim = 10)

real times(3), timlst(maxlentim), my_nan parameter (my_nan = 2E30)

c

call dirstk (name, 'vb_8b', name1, ilen) c

exp = ' ' c

write (*,'(a a)') ' exp = ',exp

kmax = idigsi('kmax', sds, exp, ierr) if (kmax .eq. 1) then

write (*,*) 'zmap werkt niet voor kmax = 1' call diclos

endif c

c Open uitvoer file c filename = 'test_vb_8b.m' info(1) = 2 info(2) = 0 info(3) = 0 info(4) = 0

call siflop (filename, info, iref, name1(1:ilen))

lu = ireffl(1,iref) c

call dipoin('y') c

c zet times en idim c

lentim = maxlentim

call digtim('rp',sds,exp,timlst,1,lentim,ierr) times(1) = timlst(lentim)

(46)

38

times(2) = 1.0

times(3) = timlst(lentim)

c

c zet parameters zmap c zpos = coordinaat ref. vlak

c dumval = waarde voor (tijdelijk) droge punten c izflag = switch voor t.o.v. NAP (0) of waterspiegel (1) c icode = switch voor grid staggering

c

ierr = idipsr ( 2.0 , '/zmap_user/zpos ', sds, exp ) if (ierr .ne. 0) write (*,*) 'Fout bij idipsr zpos'

ierr = idipsr ( my_nan , '/zmap_user/dumval', sds, exp ) if (ierr .ne. 0) write (*,*) 'Fout bij idipsr dumval' ierr = idipsi ( 1 , '/zmap_user/izflag', sds, exp ) if (ierr .ne. 0) write (*,*) 'Fout bij idipsi izflag' ierr = idipsi ( 1 , '/zmap_user/icode ', sds, exp ) if (ierr .ne. 0) write (*,*) 'Fout bij idipsi icode' call disvar ( '/zmap', 'rp', 1, sds, exp, ierr ) if (ierr .ne. 0) write (*,*) 'Fout bij disvar zmap - rp'

idim(2,1) = mdim

call digdim('rmap2d',sds,exp,idim,namdim,ierr) call printida(idim,namdim,name1(1:ilen)) call dipmat (lu,'rmap2d',sds,exp,times,idim, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij dipmat rmap2d' c

call diclos c

(47)

Appendices

10.10 Example 8c

program dgs_ex_8c

c ******************************************************************** c

c

c ******************************************************************** c

c DESCRIPTION c

c Example 8c: voorbeeld compute functie dryfall c c ******************************************************************** c c COMMON BLOCKS c implicit none include 'cdivar.i' include 'csiref.i' c c ********************************************************************** c c LOCAL PARAMETERS c

character*80 filename,name, name1,sds,exp, namdim(mdim) integer idipsr, ierr, ilen, ip

integer lu, iref, i, j, info(4), idim(2,mdim+1) integer lentim, maxlentim

parameter (maxlentim = 10)

real times(3), timlst(maxlentim), my_nan parameter (my_nan = 2E30)

c

call dirstk (name, 'vb_8c', name1, ilen) c

exp = ' ' c

c Open uitvoer file c filename = 'test_vb_8c.m' info(1) = 2 info(2) = 0 info(3) = 0 info(4) = 0

c

call dipoin('y') c

c zet times en idim c lentim = maxlentim call digtim('sep',sds,exp,timlst,1,lentim,ierr) times(1) = timlst(lentim) times(2) = 1.0 times(3) = timlst(lentim) c

c zet parameters dryfall

c dumval = waarde voor (tijdelijk) droge punten c

(48)

40

if (ierr .ne. 0) write (*,*) 'Fout bij idipsr dumval'

call disvar ( '/dryfall', 'sep', 1, sds, exp, ierr ) if (ierr .ne. 0) write (*,*) 'Fout bij disvar dryfall sep' c

c bereken droogval d.m.v. call digsim c

idim(2,1) = mdim

call digdim('/dryfall',sds,exp,idim,namdim,ierr) call digsim( '/dryfall', times(1), sds, exp, idim, ip, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij digsim dryfall sep'

write (*,*) 'Times: ',(times(i),i=1,3)

write (*,*) 'IDA: ',((idim(i,j),i=1,2),j=1,idim(1,1)+1)

call dipmat (lu,'sep',sds,exp,times,idim, ierr) if (ierr .ne. 0) write (*,*) 'Fout bij dipmat (dryfall) sep' c

call diclos c