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