# Differences

This shows you the differences between two versions of the page.

user_manual_artemis [2012/11/19 16:05]
j.parisi
user_manual_artemis [2014/10/10 15:01] (current)
Line 2061: Line 2061:

==== 6.1 Monochromatic waves ==== ==== 6.1 Monochromatic waves ====
+
+The simplest type of calculation of course concerns monochromatic waves. In this case, the user
+supplies the height of the incident waves in metres (HB) and their direction identified by the angle
+TETAB (in degrees) made between the incident wave vector and the X-axis (reckoned positively in a
+clockwise direction). This definition must be entered in the subroutine BORH. The wave period,
+expressed in seconds, is supplied with the key word WAVE PERIOD.
+
+If the user only wishes to specify a single incident wave direction (or when there is only one incident
+wave boundary), the data can be supplied more easily with the key word DIRECTION OF WAVE
+PROPAGATION In this case, this value is assigned to all the boundaries concerned. It should also be
+noted that the wave height is fixed by default at 1m for all boundaries.
+
+In the case of several boundaries with different incident wave directions, it is necessary to use the
+subroutine BORH.
+
+==== 6.2 Random waves ====
+
+In reality, waves are random. This can be interpreted as the superimposition of several
+monochromatic waves of different periods that are randomly out of phase with one another. In this
+case, the real wave energy is the sum of the energies of the component monochromatic waves. The
+curve showing energy density as a function of frequency is referred to as the “energy spectrum” (see
+§ 3.6).
+
+Numerically speaking, the principle adopted in ARTEMIS involves discretizing the energy spectrum
+into a number of bands of equal energy in order to perform a calculation in regular wave conditions
+for each of the characteristic frequencies of each band. ARTEMIS then recombines the various results
+in order to determine the overall wave height.
+
+In the case of multi-directional waves, the principle is the same. The direction spectrum is broken
+down into bands of equal energy.
+
+The random character of the waves is taken into account by activating the key words
+MONODIRECTIONAL RANDOM WAVE and MULTIDIRECTIONAL RANDOM WAVE, as the case may be.
+In order to discretize the energy spectrum, it is necessary on the one hand to fix the energy spectrum
+peak period (given by the key word PEAK PERIOD, and the number of bands of equal energy that the
+user wishes to use (given by the key word NUMBER OF PERIODS, which has a default value of 5).
+Moreover, the two key words MINIMUM SPECTRAL PERIOD (default value 0.02) and MAXIMUM
+SPECTRAL PERIOD (default value 200) are used to specify the limits of the spectrum. The key word GAMMA is used to specify the value of the coefficient g involved in Goda’s formula (cf. § 3.6). This
+key word can have values of between 1 and 7. The value 1 corresponds to. a spectrum of the Pierson-
+Moskowitz type, and 3.3 (default value) to a mean Jonswap spectrum.
+
+In the case of a multi-directional waves, the user must provide the boundaries of the direction
+spectrum (using the key words MINIMUM ANGLE OF PROPAGATION and MAXIMUM ANGLE OF
+PROPAGATION ), together with the number of bands using the key word NUMBER OF DIRECTIONS
+(default value 5). The maximum value of the exponent s involved in the expression giving the
+directional distribution of the wave energy (cf. § 3.6) is specified with the key word S EXPONENT
+(default value 20).
+
+==== 6.3 Period scanning. Resonance ====
+
+ARTEMIS offers the possibility of performing a calculation in monochromatic wave conditions by
+varying the wave period over a range of values defined by the user. This technique is used more
+particularly when searching for resonance frequencies (for example when introducing a wave into a
+closed basin).
+
+This option is activated with the logical key word PERIOD SCANNING. The user must also provide the
+boundaries of the scanning range using the real key words BEGINNING PERIOD FOR PERIOD
+SCANNING and ENDING PERIOD FOR PERIOD SCANNING. The scanning step is specified with the key
+word STEP FOR PERIOD SCANNING. All these values are fixed at zero by default.
+
+In this case, ARTEMIS performs a calculation for each of the periods specified. The results are stored
+in the results file (with period sampling if the key word GRAPHIC PRINTOUT PERIOD is used).
+
+==== 6.4 Bathymetric breaking ====
+
+ARTEMIS offers the possibility of including dissipation due to bathymetric wave breaking, for example
+when the waves reach a beach (bathymetric breaking is used in opposition to offshore whitecapping.
+
+ARTEMIS offers two formulations for regular wave breaking: that of Battjes and Janssen, and that of
+Dally. Only the first is available for random waves.
+
+This phenomenon is taken into account by activating the logical key word BREAKING (default value
+NO). The formulation to be used (cf. § 3.4.1) is then specified with the key word BREAKING LAW,
+which may have the value 1 (Battjes and Janssen) or 2 (Dally) (default value 1). Lastly, the value of
+the coefficient ​ gs in the breaking height criterion (cf. § 3.4.1.1) is given with the key word GAMMAS
+(default value 0.88), which is not to be confused with the key word GAMMA in the energy spectrum
+formula (cf. § 3.6).
+
+In the case of Dally’s formula, the coefficients G and K are provided with the key words GDALLY
+(default value 0.4) and KDALLY (default value 0.1). In the case of Battjes and Janssen’s formula, the
+coefficient a is provided with the key word ALPHA (cf. § 3.4.1.2).
+
+In a calculation that takes into account breaking, the mnemonic QB is added in the list of the key
+word VARIABLES FOR GRAPHIC PRINTOUTS in order to obtain the rate of breaking calculated by the software. This rate, which is between 0 and 1, represents the percentage of waves that break in the
+case of a random wave simulation. With monochromatic wave simulations,​ the breaking rate is 1 or
+0.
+
+==== 6.5 Bottom friction ====
+
+ARTEMIS allows dissipation due to bottom friction to be taken into account. This is done by using the
+formulation of Kostense et al. or that of Putnam and Johnson.
+
+Bottom friction is a complex question involving many notions that are described in § 3.4.2.
+
+The key word FRICTION (default value NO) is used to take this into account in the calculation.
+
+=== 6.5.1 Determination of friction factor ===
+
+The friction factor is either supplied by the user or determined directly by ARTEMIS in the case of a
+sandy bed.
+
+In order to introduce the friction factor directly, it is necessary to activate the logical key word
+FRICTION FACTOR IMPOSED. If this is spatially constant, the value may be specified simply by using
+the key word FRICTION FACTOR (default value 0). If not, it is necessary to enter the subroutine
+FWSPEC, and assign a friction factor value to the variable FW at each mesh node (to do this, it is
+possible to use the subroutine FILPOL, which enables the value of any variable to be prescribed
+inside a polygon).
+
+If the keyword FRICTION FACTOR IMPOSED = FALSE (default value), ARTEMIS assumes that the bed is
+sandy. In this case, the friction factor determination formulae built into ARTEMIS are used. The main
+consideration is the hydraulic regime. Here again, the regime may be determined automatically by
+ARTEMIS at each mesh point, or specified directly by the user. The latter option is activated using the
+logic key word HYDRAULIC REGIME IMPOSED (default value NO), and the type of regime is then given
+by the key word HYDRAULIC REGIME TYPE, which may have any of the following values:
+
+  * 1 : laminar regime
+  * 2 : smooth turbulent regime
+  * 3 : rough turbulent regime
+  * 4 : transient regime
+
+Depending on the hydraulic regime, the friction factor is calculated by means of various formulae, in
+which the various parameters must be supplied using key words (see § 3.4.2).
+
+In the case of a rough turbulent regime, the friction factor depends on the skin roughness, which is
+connected with the size of the sediment particles, and on the shape roughness, which is connected
+with the appearance of undulations on the ground referred to as ripples. ARTEMIS enables the user
+to ignore shape roughness by activating the logic key word SKIN ROUGHNESS ONLY (default value
+NO). In this case, the roughness value is taken to be equal to three times the value supplied by the
+key word DIAMETER90 described below.
+
+The other key words used to supply the physical parameters needed for ARTEMIS to take into
+account friction on a sandy bed are the following:
+
+  * The key word FLUID KINEMATIC VISCOSITY (default value 10-6 m2/s) provides the viscosity of the water.
+  * Key words FLUID SPECIFIC MASS (default value 1000 kg/m3) and SEDIMENT SPECIFIC WEIGHT (default value 2650 kg/m3) are used to supply the water and sand densities for rough turbulent or transient hydraulic regimes.
+
+The size of the sediment particles involved in determining the bottom friction factor is indicated with
+the following key words:
+
+  * Key word DIAMETER50 (default value 0.1x10-3) indicates the maximum size of 50% of the volume of sediment. The values generally used are:
+    : 0.66x10-3 for very coarse sand,
+    : 0.33x10-3 for coarse sand,
+    : 0.17x10-3 for medium sand,
+    : 0.083x10-3 for fine sand,
+    : 0.04x10-3 for very fine sand.
+  * Key word DIAMETER90 (default value 0.15x10-3) indicates the maximum size of 90% of the volume of sediment. The values generally used are:
+    : 10-3 for very coarse sand,
+    : 0.5x10-3 for coarse sand,
+    : 0.25x10-3 for medium sand,
+    : 0.125x10-3 for fine sand,
+    : 0.062x10-3 for very fine sand.
+  * Key word RIPPLES COEFFICIENT (default value 0.7) indicates the value of the ripple coefficient when shape roughness is taken into account. This key word can have the following values:
+    : 1 for ripples only,
+    : 0.7 when the ripples are superimposed on sand waves.
+
+=== 6.5.2 Determination of dissipation coefficient ===
+
+Once the friction factor has been determined, it is possible to calculate the value of the dissipation
+term associated with the bottom friction.
+
+ARTEMIS can calculate the dissipation term by one of two different formulae, that of Kostense,
+Meijer and Dingemans, or that of Putnam and Johnson.
+
+The formula is chosen (cf. § 3.4.2) with the key word BOTTOM FRICTION LAW, which can have the
+following values:
+  * 1 for Kostense et al.’s formula (default value)
+  * 2 for Putnam and Johnson’s formula.
+
+==== 6.6 Rapidly varying topography ====
+
+Since version 6.1, user can take into account second order bottom effects. To use this option, the
+keyword « RAPIDLY VARYING TOPOGRAPHY » must appear in the case file.
+
+The equation solved and the model choice is given in 1.3.1.3. The reader can find in 1.4.1 des
+informations détaillées sur l'​implémentation et l'​utilisation de cette option.
+
+The keyword « RAPIDLY VARYING TOPOGRAPHY » can take the values 0,1,2 or 3.
+
+  * 0 : correspond to classical mild-slope equation.
+  * 1 : gradient effects are taken into account.
+  * 2 : curvature effects are taken into account.
+  * 3 : both gradient and curvature effects are taken into account.
+
+Defaut value : 0.
+
+==== 6.7 Other parameters ====
+
+The key word GRAVITY ACCELERATION (default value 9.81) is used to specify the acceleration due to
+gravity in \$m/s^2\$.
+
+\\
+===== 7. Other parameters =====
+\\
+The general parameters for the calculation are indicated only in the parameters file (see Appendix 4).
+
+The title of the calculation is specified with the key word TITLE.
+
+If a vector computer is being used, it is necessary to specify the vector length with the key word
+VECTOR LENGTH. The default value of this key word (1) corresponds to a scalar computer (i.e. the
+case with workstations).
+
+When generating an executable, the libraries used to edit the links and the version of the libraries are
+specified with the key words LIBRARIES and RELEASE. When the software is installed on a
+workstation,​ the default value of these key words is often sufficient.
+
+\\
+===== 8. Numerical parameters =====
+\\
+A number of key words enable the user to configure an ARTEMIS calculation from the numerical
+standpoint.
+
+==== 8.1 Solver ====
+
+Firstly, the integer key word SOLVER is used to choose the solver for the system of equations
+processed by ARTEMIS. The possible values are:
+
+  * 1 : Conjugated gradient,
+  * 2 : Conjugated residual,
+  * 3 : Conjugated gradient on normal equation,
+  * 4 : Minimum error,
+  * 6 : Conjugated gradient of CGSTAB type,
+  * 7 : GMRES
+  * 8 : Direct solver
+
+By default, ARTEMIS uses the direct solver (option 8).
+
+When option 7 is used, the size of the Krylov space is specified with the key word SOLVER OPTION.
+
+It should be stressed that :
+
+  * in the present state of development of ARTEMIS, the solver GMRES (option 7) does not appear to give satisfactory results;
+  * The number of iteration require by the iterative solver to obtain a solution for the linear system is often high. By consequence,​ using such method is less interesting than a formal matrix inversion like with the direct solver;
+  * When you use the direct solver for large mesh sizes, you may need to increase the parameter MEMFACTOR in the new subroutine SD_SOLVE_1.f.
+
+==== 8.2 Accuracy ====
+
+When the linear system is solved by an iterative method. It is therefore necessary to define the
+accuracy that one wishes to obtain during the calculation,​ and the maximum permissible number of
+iterations, so as to avoid looping if the required level of precision is not attained.
+
+The level of accuracy is specified with the key word SOLVER ACCURACY (default value 10-4). The
+maximum number of iterations is specified with the key word MAXIMUM NUMBER OF ITERATIONS
+FOR SOLVER (default value 60000).
+
+The user may obtain information on the solver by activating the key word INFORMATION ABOUT
+SOLVER (default value YES). This information is supplied in the printout, and may be of two types:
+
+  * Either the process has converged before reaching the maximum permitted number of iterations, and in this case ARTEMIS indicates the number of iterations actually run, together with the precision attained.
+  * Or the process has not converged sufficiently quickly, the ARTEMIS then displays the message “MAXIMUM NUMBER OF ITERATIONS REACHED” and indicates the precision actually attained.
+
+==== 8.3 Preconditioning ====
+
+When the system of equations is solved by a conjugated gradient method, convergence may often be
+speeded up by preconditioning.
+
+ARTEMIS offers several preconditioning options. The key word PRECONDITIONING is used to choose
+the type required:
+
+  * 0 : no preconditioning,​
+  * 2 : diagonal preconditioning (default value),
+  * 3 : diagonal preconditioning with condensed matrix,
+  * 5 : diagonal preconditioning in absolute values,
+  * 7 : Crout’s preconditioning per element.
+
+Certain types of preconditioning can be cumulated, such as the diagonals with the others. The basic
+values are prime numbers, so that two types of preconditioning can be cumulated by assigning to the
+key word the product of the corresponding two prime numbers, e.g. 6 corresponds to types 2 and 3.
+
+==== 8.4 Handling of cases with energy dissipation ====
+
+When the calculation has to take into account dissipation phenomena (breaking, bottom friction or
+both), ARTEMIS first of all runs a calculation without taking the dissipation into account. This first
+solution is then used to determine an initial value of the dissipation term to be introduced into the
+mild slope equation. ARTEMIS then runs a second calculation,​ taking into account the new term. The
+process is then iterated until a satisfactory solution is obtained. As with the precision of the general
+solver (see § 9.2), the user may configure the convergence criteria of these iterations by using the
+key word SUB-ITERATIONS ACCURACY (default value 10-2) and the maximum number of iterations
+using the key word MAXIMUM SUB-ITERATIONS (default value 15).
+
+As with the general solver, ARTEMIS provides information concerning this process in the control
+printout if the key word INFORMATION ABOUT SOLVER is activated (default value YES). In particular,
+ARTEMIS provides the maximum difference between each sub-iteration and the previous one
+(expressed as a percentage).
+
+Lastly, a relaxation coefficient is introduced at each iteration, when the dissipation coefficient is
+calculated, in order to avoid oscillations in solver convergence. This coefficient is specified by means
+of the key word DISSIPATION RELAXATION (default value 0.5). It is introduced in the form:
+
+  : MU2 = MU1 + RELAX*(MU2-MU1)
+
+where
+
+  : MU2 is the dissipation term calculated during the current iteration,
+  : MU1 is the dissipation term calculated during the previous iteration,
+  : RELAX is the relaxation coefficient.
+
+The user may need to reduce the value of the relaxation coefficient,​ particularly in the case of regular
+waves.
+
+\\
+===== 9. Programming of complex cases =====
+\\
+
+==== 9.1 Modification of bed elevation (corfon) ====
+
+The sea bottom may be introduced at various levels, as indicated in § 3.4.
+
+ARTEMIS offers the possibility of modifying the bottom at the start of the calculation,​ using the
+subroutine CORFON. This subroutine is used to modify the value of the variable ZF at each mesh
+point. To do so, the user can change a number of variables, such as, for example, the point
+coordinates (X and Y), the area of the elements, the table of connectivities,​ etc.
+
+By default, the subroutine CORFON performs LISFON bottom smoothing, i.e. as many as are
+specified by the key word BOTTOM TOPOGRAPHY SMOOTHING (default value 0).
+
+==== 9.2 Modification of coordinates (corrxy) ====
+
+ARTEMIS also offers the possibility of modifying the coordinates of the mesh points. In this way it is
+possible to change, for example, the scale (transition from a scale model to real size), make a
+rotation or lateral displacement,​ etc.
+
+This is done by using the subroutine CORRXY, which is called up at the start of the calculation. By
+default, this subroutine is empty and shows an example of programming concerning a change of
+scale and origin, in the form of comment lines.
+
+==== 9.3 Addition of new variables ====
+
+ARTEMIS allows the user to create new variables. The names of these new variables must be
+declared in the subroutine NOMVAR in the form of a mnemonic of no more than 8 characters.
+
+Secondly, the user must calculate the value of these new variables in the subroutine UTIMP. To do
+this, he can use the tables PRIVE (dimension (number of points, NPRIV)) to transmit information
+between the various user-accessible subroutines. When these tables are being used, it is necessary
+to give their number (NPRIV value) in the main program.