--- Welcome to the official ADCIRCWiki site! The site is currently under construction, with limited information. ---

For general information, see the ADCIRC site, ADCIRC FAQ, or the ADCIRC Wikipedia page. For model documentation not yet available on the wiki, see the ADCIRC site. New content is being continuously added to the ADCIRCWiki, and material from the main ADCIRC site will be gradually transitioned over to the wiki.

IM: Difference between revisions

From ADCIRCWiki
Jump to navigation Jump to search
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''IM''' is an important parameter in the [[fort.15 file]] that defines numerical model formulation and dimension. Among other things, IM specifies whether ADCIRC is solved in two-dimensional depth-integrated (2DDI) or in three-dimensions (3D), solution of the governing equations is semi-implicit or explicit in time, and whether the model formulation is barotropic or baroclinic. Popular values for 2D barotropic ADCIRC include IM=0 and IM=111112, though the latter also requires modifying [[A00, B00, C00]].  
'''<code>IM</code>''' is an important parameter in the [[fort.15 file]] that defines numerical model formulation and dimension. Among other things, <code>IM</code> specifies whether ADCIRC is solved in two-dimensional depth-integrated (2DDI) or in three-dimensions (3D), solution of the governing equations is semi-implicit or explicit in time, and whether the model formulation is barotropic or baroclinic. Popular values for 2D barotropic ADCIRC include <code>IM=0</code> and <code>IM=111112</code>; users should be aware that the <code>[[A00, B00, C00]]</code> coefficients must be specified differently in these two cases.  


== Default IM Values ==
== Default IM Values ==
Default simulation option combinations can be specified through single or double digit values, some of which are shortcuts to the six-digit codes described in the next heading.  
Default simulation option combinations can be specified through single or double digit values, some of which are shortcuts to the six-digit codes described in the next heading.  
The available IM values are specified below:
The available <code>IM</code> values are specified in the table below and in the following section on 6-digit values:


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 32: Line 32:
|-
|-
| 20
| 20
| 111113
| -
| Baroclinic 2DDI
| Baroclinic 2DDI
|-
|-
| 21
| 21
| 611113
| -
| Baroclinic 3D velocity-based momentum
| Baroclinic 3D velocity-based momentum
|-
|-
Line 48: Line 48:
|}
|}


Note that all default IM values employ the semi-implicit consistent GWCE mass matrix solver. It has less numerical error and tends to be more stable than the explicit mass-lumping approach at the expense of computational time and memory.
Note that all default <code>IM</code> values employ the semi-implicit consistent GWCE mass matrix solver. It has less numerical error and tends to be more stable than the explicit mass-lumping approach at the expense of computational time and memory.


== Six-digit IM Codes ==
== Six-digit IM Codes ==
For fine-grained control of various options six-digit codes for IM can be specified. Each digit represents a specific option regarding the dimension and the formulation of certain terms or integration methods in the GWCE or momentum equations.  
For fine-grained control of various options six-digit codes for <code>IM</code> can be specified. Each digit represents a specific option regarding the dimension and the formulation of certain terms or integration methods in the GWCE or momentum equations.  
The available options for each digit are specified below, with the first digit being the left-most:
The available options for each digit are specified below, with the first digit being the left-most. The internal flags that are set are listed to help users dig through the code.


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 65: Line 65:
|-
|-
| 1 (default)
| 1 (default)
| 2DDI, Kolar-Gray flux-based
| 2DDI, Kolar-Gray flux-based<br/><code>CGWCE_LS_KGQ=.TRUE.</code>
| Non conservative
| Non conservative<br/><code>CGWCE_Advec_NC=.TRUE.</code>
| Integration by parts, velocity-based
| Integration by parts, velocity-based<br/><code>CME_LS_IBPV=.TRUE.</code>
| Non conservative
| Non conservative<br/><code>CME_New_NC=.TRUE.</code>
| Corrected  
| Corrected <br/><code>CME_AreaInt_Corr=.TRUE.</code>
| Consistent (implicit for linear part of gravity wave term), barotropic
| Consistent (implicit for linear part of gravity wave term), barotropic<br/><code>ILump=0</code>
|-
|-
| 2
| 2
| 2DDI, 2-part flux-based
| 2DDI, 2-part flux-based<br/><code>CGWCE_LS_2PartQ=.TRUE.</code>
| Conservative form 1
| Conservative form 1<br/><code>CGWCE_Advec_C1=.TRUE.</code>
| Integration by parts, flux-based
| Integration by parts, flux-based<br/><code>CME_LS_IBPQ=.TRUE.</code>
| Conservative form 1
| Conservative form 1<br/><code>CME_New_C1=.TRUE.</code>
| Original  
| Original <br/><code>CME_AreaInt_Orig=.TRUE.</code>
| Lumped (explicit), barotropic
| Lumped (explicit), barotropic<br/><code>CGWCE_Lump=.TRUE.</code>, <code>ILump=1</code>
|-
|-
| 3
| 3
| 2DDI, 2-part velocity-based
| 2DDI, 2-part velocity-based<br/><code>CGWCE_LS_2PartV=.TRUE.</code>
| Conservative form 2
| Conservative form 2<br/><code>CGWCE_Advec_C2=.TRUE.</code>
| Integration by parts, velocity-based symmetrical
| Integration by parts, velocity-based symmetrical<br/><code>CME_LS_IBPSV=.TRUE.</code>
| Conservative form 2
| Conservative form 2<br/><code>CME_New_C2=.TRUE.</code>
| -
| -
| Consistent (implicit for full gravity wave term), barotropic (''not yet implemented in ADCIRC release version'')
| Consistent (implicit for full gravity wave term), barotropic<br/><code>CGWCE_HDP=.TRUE.</code>, <code>IFNL_HDP=1</code>, <code>ILump=0</code> {{ADC version|version=55|relation=+}}
|-
|-
| 4
| 4
| 2DDI, 2-part flux-based symmetrical
| 2DDI, 2-part flux-based symmetrical<br/><code>CGWCE_LS_2PartSQ=.TRUE.</code>
| -
| Integration by parts, flux-based symmetrical<br/><code>CME_LS_IBPSQ=.TRUE.</code>
| -
| -
| Integration by parts, flux-based symmetrical
| -
| -
| -
| -
| Consistent (implicit for full gravity wave term, modified dispersion relation), barotropic (''not yet implemented in ADCIRC release version'')
|-
|-
| 5
| 5
| 2DDI, 2-part velocity-based symmetrical
| 2DDI, 2-part velocity-based symmetrical<br/><code>CGWCE_LS_2PartSV=.TRUE.</code>
| -
| 2 Part, velocity-based (''not implemented'')<br/><code>CME_LS_2PartV=.TRUE.</code>
| -
| -
| 2 Part, velocity-based (''not implemented'')
| -
| -
| -
| -
| Specify a value of 5-8 to do the same as 1-4 (same order) but in baroclinic mode (''not yet implemented in ADCIRC release version'')
|-
|-
| 6
| 6
| 3D, Kolar-Gray flux-based
| 3D, Kolar-Gray flux-based<br/><code>C2DDI=.FALSE.</code>, <code>CGWCE_LS_KGQ=.TRUE.</code>, <code>C3D=.TRUE.</code>, <code>C3DVS=.TRUE.</code>, <code>ILump=0</code>
| -
| 2 Part, flux-based (''not implemented'')<br/><code>CME_LS_2PartQ=.TRUE.</code>
| -
| -
| 2 Part, flux-based (''not implemented'')
| -
| -
| -
| -
| -
|}
|}


A common code combination is IM = 111112, which is identical to the default 111111 (same as IM = 0), but simulates in explicit mass-lumping mode. Note that <code>[[A00, B00, C00]]</code> must be set to <code>0.0 1.0 0.0</code> alongside an IM value of 111112. Lumped explicit mode is a useful alternative to the (default) semi-implicit consistent GWCE mass matrix mode, which requires a matrix solve increasing computational time and memory compared to the explicit mass-lumping mode, which as about twice as fast and scales to fewer grid nodes per computational core.<ref>S. Tanaka, S. Bunya, J.J. Westerink, C. Dawson, R.A. Luettich, Scalability of an Unstructured Grid Continuous Galerkin Based Hurricane Storm Surge Model, J. Sci. Comput. 46 (2011) 329–358. doi:10.1007/s10915-010-9402-1</ref> Moreover, for model setups that are sufficiently resolved in space and time, differences in the solution between approaches should be negligible.
A common code combination is <code>IM=111112</code>, which is identical to the default <code>111111</code> (same as <code>IM=0</code>), but simulates in explicit mass-lumping mode. Note that <code>[[A00, B00, C00]]</code> must be set to <code>0.0 1.0 0.0</code> when in this mode. Lumped explicit mode is a useful alternative to the (default) semi-implicit consistent GWCE mass matrix mode, because the latter requires a matrix solve that increases computational time and memory.  By comparison, the explicit mass-lumping mode is about twice as fast and scales to fewer grid nodes per computational core.<ref>S. Tanaka, S. Bunya, J.J. Westerink, C. Dawson, R.A. Luettich, Scalability of an Unstructured Grid Continuous Galerkin Based Hurricane Storm Surge Model, J. Sci. Comput. 46 (2011) 329–358. doi:10.1007/s10915-010-9402-1</ref> Moreover, for model setups that are sufficiently resolved in space and time, differences in the solution between approaches should be small. Though, many users have reported somewhat lower stability in lumped explicit mode.
 
The most recent version (55+) also has an option that improves the (default) semi-implicit consistent GWCE mass matrix mode to compute the complete (total depth) gravity wave term (free surface gradient) implicitly; toggled by setting IMDigit-6 to 3. The default version (IMDigit-6=1), only computes the initial still water depth component of the free surface gradient implicitly, which might make it more susceptible to CFL violations in shallow depths and can encounter Matrix diagonality issues overland where the initial still water depth is negative.


== References ==
== References ==
<references />
<references />

Latest revision as of 15:30, 21 August 2020

IM is an important parameter in the fort.15 file that defines numerical model formulation and dimension. Among other things, IM specifies whether ADCIRC is solved in two-dimensional depth-integrated (2DDI) or in three-dimensions (3D), solution of the governing equations is semi-implicit or explicit in time, and whether the model formulation is barotropic or baroclinic. Popular values for 2D barotropic ADCIRC include IM=0 and IM=111112; users should be aware that the A00, B00, C00 coefficients must be specified differently in these two cases.

Default IM Values

Default simulation option combinations can be specified through single or double digit values, some of which are shortcuts to the six-digit codes described in the next heading. The available IM values are specified in the table below and in the following section on 6-digit values:

IM Value Six-digit Equivalent Description
0 111111 Barotropic 2DDI
1 611111 Barotropic 3D velocity-based momentum
2 - Barotropic 3D stress-based momentum
10 - Barotropic 2DDI with passive scalar transport
11 - Barotropic 3D velocity-based momentum with passive scalar transport
20 - Baroclinic 2DDI
21 - Baroclinic 3D velocity-based momentum
30 - Baroclinic 2DDI with passive scalar transport
31 - Baroclinic 3D velocity-based momentum with passive scalar transport

Note that all default IM values employ the semi-implicit consistent GWCE mass matrix solver. It has less numerical error and tends to be more stable than the explicit mass-lumping approach at the expense of computational time and memory.

Six-digit IM Codes

For fine-grained control of various options six-digit codes for IM can be specified. Each digit represents a specific option regarding the dimension and the formulation of certain terms or integration methods in the GWCE or momentum equations. The available options for each digit are specified below, with the first digit being the left-most. The internal flags that are set are listed to help users dig through the code.

Value Digit 1: 2DDI/3D, Lateral Stress in GWCE[1] Digit 2: Advection in GWCE[2] Digit 3: Lateral Stress in Momentum[1] Digit 4: Advection in Momentum[2] Digit 5: Area Integration in Momentum Digit 6: GWCE Mass Matrix, Barotropic/Baroclinic
1 (default) 2DDI, Kolar-Gray flux-based
CGWCE_LS_KGQ=.TRUE.
Non conservative
CGWCE_Advec_NC=.TRUE.
Integration by parts, velocity-based
CME_LS_IBPV=.TRUE.
Non conservative
CME_New_NC=.TRUE.
Corrected
CME_AreaInt_Corr=.TRUE.
Consistent (implicit for linear part of gravity wave term), barotropic
ILump=0
2 2DDI, 2-part flux-based
CGWCE_LS_2PartQ=.TRUE.
Conservative form 1
CGWCE_Advec_C1=.TRUE.
Integration by parts, flux-based
CME_LS_IBPQ=.TRUE.
Conservative form 1
CME_New_C1=.TRUE.
Original
CME_AreaInt_Orig=.TRUE.
Lumped (explicit), barotropic
CGWCE_Lump=.TRUE., ILump=1
3 2DDI, 2-part velocity-based
CGWCE_LS_2PartV=.TRUE.
Conservative form 2
CGWCE_Advec_C2=.TRUE.
Integration by parts, velocity-based symmetrical
CME_LS_IBPSV=.TRUE.
Conservative form 2
CME_New_C2=.TRUE.
- Consistent (implicit for full gravity wave term), barotropic
CGWCE_HDP=.TRUE., IFNL_HDP=1, ILump=0
ADCIRC version: 55
4 2DDI, 2-part flux-based symmetrical
CGWCE_LS_2PartSQ=.TRUE.
- Integration by parts, flux-based symmetrical
CME_LS_IBPSQ=.TRUE.
- - -
5 2DDI, 2-part velocity-based symmetrical
CGWCE_LS_2PartSV=.TRUE.
- 2 Part, velocity-based (not implemented)
CME_LS_2PartV=.TRUE.
- - -
6 3D, Kolar-Gray flux-based
C2DDI=.FALSE., CGWCE_LS_KGQ=.TRUE., C3D=.TRUE., C3DVS=.TRUE., ILump=0
- 2 Part, flux-based (not implemented)
CME_LS_2PartQ=.TRUE.
- - -

A common code combination is IM=111112, which is identical to the default 111111 (same as IM=0), but simulates in explicit mass-lumping mode. Note that A00, B00, C00 must be set to 0.0 1.0 0.0 when in this mode. Lumped explicit mode is a useful alternative to the (default) semi-implicit consistent GWCE mass matrix mode, because the latter requires a matrix solve that increases computational time and memory. By comparison, the explicit mass-lumping mode is about twice as fast and scales to fewer grid nodes per computational core.[3] Moreover, for model setups that are sufficiently resolved in space and time, differences in the solution between approaches should be small. Though, many users have reported somewhat lower stability in lumped explicit mode.

The most recent version (55+) also has an option that improves the (default) semi-implicit consistent GWCE mass matrix mode to compute the complete (total depth) gravity wave term (free surface gradient) implicitly; toggled by setting IMDigit-6 to 3. The default version (IMDigit-6=1), only computes the initial still water depth component of the free surface gradient implicitly, which might make it more susceptible to CFL violations in shallow depths and can encounter Matrix diagonality issues overland where the initial still water depth is negative.

References

  1. 1.0 1.1 K.M. Dresback, R.L. Kolar, R.A. Luettich, Jr. (2005). On the Form of the Momentum Equation and Lateral Stress Closure Law in Shallow Water Modeling, in: Estuar. Coast. Model., American Society of Civil Engineers, Reston, VA, 399–418. doi:10.1061/40876(209)23
  2. 2.0 2.1 K.M. Dresback, R.L. Kolar, J.C. Dietrich (2005). On the Form of the Momentum Equation for Shallow Water Models Based on the Generalized Wave Continuity Equation: Conservative vs. Non-Conservative. Advances in Water Resources, 28(4), 345-358. doi:10.1016/j.advwatres.2004.11.011
  3. S. Tanaka, S. Bunya, J.J. Westerink, C. Dawson, R.A. Luettich, Scalability of an Unstructured Grid Continuous Galerkin Based Hurricane Storm Surge Model, J. Sci. Comput. 46 (2011) 329–358. doi:10.1007/s10915-010-9402-1