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

Link to this comparison view

user_manual_artemis [2012/11/19 16:05]
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
 +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. § 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. §
 +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
 +==== 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 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
 +==== 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)
 +  : 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
 +===== 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.