# 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. | ||