.. _geohints:
==================================
Cautionary Hints on using GeoClaw
==================================
As with all of Clawpack, the GeoClaw code is provided as a research
and teaching tool with no guarantee of suitability for any particular
purpose, and no liability on the part of the authors. See the
:ref:`license` for more details.
The authors believe that GeoClaw can be used for some real-world modeling of
geophysical hazards, but it is the responsibility of the user to fully
understand the model and its limitations and validate it for the intended
purpose.
.. _geohints_tsunami:
Tsunami hazard modeling
-----------------------
GeoClaw is currently in use for tsunami hazard assessment
by several research groups. Version 4.6.1 of the code was approved in 2012
by the US National Tsunami Hazard
Mitigation Program (`NHTMP `_) for use in
modeling work supported by the program, after an extensive benchmarking
project, the results of which can be found on the
`NTHMP benchmarking page
`_.
However, users who wish to apply GeoClaw to the real world should be aware
that doing so properly requires a good understanding of the capabilities and
limitations of the code, the equations they model, and the suitability of
using these equations to model any particular real-world scenario.
The authors of this code have invested considerable time in learning about
appropriate aspects of geohazard modeling, through reading the literature
and working directly with geoscientists who are domain experts. Even so we
are very cautious in using any results from GeoClaw without performing
sensitivity studies, grid refinement studies, etc., and if possible comparing
results with those obtained by other modeling groups and confirming with
experts that the results are reasonable.
It is impossible to encapsulate the knowledge needed to deal with all the
inaccuracies and uncertainties of geohazard modeling in any piece of
software or its documentation, and there is
no replacement for extensively reading the
literature and working with domain experts.
It is also important to understand the various parameters in GeoClaw and if
necessary experiment with different settings and perform sensitivity studies.
See :ref:`setrun_geoclaw`.
Here are a few of the things that should be considered in any GeoClaw
simulation:
* The depth-averaged shallow water equations are a fairly good model for the
fluid dynamics of tsunamis provided the wave length is long relative to
the depth of the water. In particular, for large tsunamis generated by
subduction zone earthquakes propagating over the ocean, these equations
may be adequate. However, even then, they are only an approximation.
More accurate depth-averaged equations such as Boussinesq equations that
include dispersive terms may be more accurate.
* For short wavelength tsunamis such as those generated by landslides,
shallow water equations are less accurate since dispersive terms can be very
important. Incorporating dispersive terms in GeoClaw is planned for the
future but not yet available. These limitations should be clearly
understood.
* GeoClaw solves the nonlinear shallow water equations and can capture
turbulent bore formation to some extent via the formation of shock waves.
It does not model wave breaking directly and in the nearshore region the
use of depth-averaged equations may be inaccurate since the flow becomes
fully three-dimensional. Reasonable agreement with observations from
historic events and wave tank experiments have been seen in validation
studies, both of GeoClaw and other shallow water codes, but caution is
required.
* The empirical Manning formulation is used to model bottom friction, as
described further in the section :ref:`manning`, where some limitations
are discussed.
* For most tsunami simulations including the Coriolis terms in the momentum
equations makes little difference in the observed results and so these
terms are often turned off for efficiency (*icoriolis = 0*).
* The geoclaw parameter *sealevel* determines the initial fluid depth
relative to the topography, as specified by the *topo* files.
It is important to know what
`vertical datum `_
the topography is relative to. Coastal bathymetry developed for tsunami
modeling is often relative to Mean High Water (MHW) at some point, in
which case setting *sealevel = 0.* corresponds to assuming the water level
being initially at MHW. See :ref:`sealevel` for more information.
* Tsunami modeling generally requires specifying a seafloor displacement in
order to initiate the tsunami, by specifying a *dtopo* file. This may be a
time-dependent displacement, as explained in :ref:`dtopo`. However, it is
important to understand that any displacement of the seafloor causes the
entire water column above this point to be shifted upwards by the same
amount (since the depth *h* is held constant), and so is immediately
observed in the sea surface elevation. In reality, displacement of the
seafloor leads to the propagation of acoustic waves that result in a
surface displacement