.. Wavetank documentation master file, created by sphinx-quickstart on Fri Sep 6 16:38:21 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. _intro-sec: A Novel Boussinesq-type Numerical Wave Model Development (Flood & Coastal - Work Unit) ======================================================================================= PhaseWave is a new open-source phase resolving numerical wave model, that is being developed within the numerical modeling strategy in the Coastal and Hydraulics Laboratory (CHL) of the U.S. Army Engineering Resarch and Development Center (ERDC). For now it comprises of two main modules that are based on two open-source Boussinesq-type wave formulations - FUNWAVE and COULWAVE (pCOULWAVE - parallel). FUNWAVE (http://chinacat.coastal.udel.edu/programs/funwave/funwave.html) is a package for simulating waves in shallow water environment and has been written by Jim Kirby et al. The current version of the code that this repository contains is version 2.1. pCOULWAVE (http://isec.nacse.org/models/coulwave_download.php) is also an open-source Boussinesq-type phase-resolving numerical wave model, originally developed by Patrick J. Lynett and Philip L.-F. Liu. Substantial additions and modifications have been implemented by Khairil Irfan Sitanggang and Dae-Hong Kim. The current version that is being used is 2.0 (manual), released in 2010. The phaseWave package suite and various test cases are maintained by Matt Malej under the Flood & Coastal Work Unit - ``A novel Boussinesq-type numerical wave model development``. Motivation ---------- Modeling of nonlinear coastal wave processes, such as inundation, wave runup, bore propagation, tsunami propagation, harbor resonance, ship wakes, and infragravity waves, requires efficient and accurate computing of the evolution of highly nonlinear time-dependent, three-dimensional surface wave fields in various coastal environments. This is a challenging hydrodynamic problem. Most models commonly used for describing nonlinear surface waves are far from being complete. They rely on ad-hoc models for the physical processes involved, such as nonlinear wave-wave interactions, energy dissipation due to wave breaking, or interplay between waves and currents. An additional complication in modeling coastal waves is that there is a wide range of scales to be resolved. The coupling between various modes and thus the energy transfer between different spatial and temporal scales lack a thorough understanding. Operational phase-averaged wave action balance models suffer from inaccurate prediction of the wave spectrum in shallow water. This is often attributed to incomplete modeling of nonlinear interactions (both resonant and non-resonant). With improvements in high performance computing, phase-resolving models are becoming more practical to apply. Their primary area of application thus far has been a shallow-water environment. Boussinesq-type models are especially attractive in these regimes, where weak nonlinearity and low dispersion are prevalent. The U.S. Army Corp of Engineers has a pressing need for a robust and computationally efficient phase-resolving numerical wave model. The current state of practice at ERDC-CHL is to use BOUSS-2D in modeling nearshore waves, circulation, and related processes [1-15]. This numerical model has been around for ~20 years and possesses several deficiencies, for instance: the code is not open source and it does not belong to CHL, it runs on a single processor, its integration schemes are primitive and rely on finite-difference methods, plus setup and post-processing requires other proprietary software (e.g., SMS, Matlab®). Purpose ------- We proposed that a new phase-resolving numerical wave model be adopted and implemented for use within CHL numerical strategic framework. The purpose of this research and development initiative is to advance the state of the art of the phase-resolving numerical wave models for the Corps. The areas of applicability include: nearshore wind-wave propagation, harbor entrances, nonlinear shoaling, runup, inundation, tsunamis, and ship waves. Products -------- The deliverable product is a robust phase-resolving numerical wave model, that will be: open-source, parallelized to run on HPC (High Performance Computing) systems, a community based effort, version controlled (Git), written in a higher level languages (C/C++, Python) and interfaced with other lower-level languages (Fortran), implemented to accommodate variable boundaries and topography (finite volume, spectral methods, finite difference, finite element method). Subsequent efforts will explore a stand alone computational interface and a robust UI (User Interface), that should be both intuitive, easy to navigate, and web-based so it can be accessed remotely if desired. The developed numerical model will span multiple spatial and temporal scales, which are relevant to coastal and hydrodynamic phenomena normally exhibited in ERDC’s research and development efforts. These processes include, but are not limited to: * Inundation mapping – overland propagation and runup, * Bore propagation and waves on highly variable bottom topography, * Harbor resonance and marina infrastructure modification * sub-harmonic generation and dissipation * diffraction * reflection (variable surfaces) * channel deepening/widening/realignment * Transient waves (tsunamis, sneaker waves), * Ship wakes * vessel generated waves and effects on shorelines * vessel generated bed velocities and shear stresses * vessel interactions with other vessels and with locks and dams. The broader impact of this project is the advancement of state of the art of Boussineq-type (phase-resolving) numerical wave modeling, as well as analysis and decision support. Payoff ------ The immediate benefits will be more accurate and efficient applications to: harbor and marina infrastructure, inundation mapping – overland propagation and runup, vessel generated waves and effects on shorelines, and waves on reefs. The broader impact will be in improved risk communication and risk informed decision making. The computational ease of use will be critical to the Corps District users, which rely on a user-friendly interface. Flexible gridding will allow for greater computational utility, as other high-fidelity and phase-averaged models within CHL will have a clear pathway for communication and two-way dynamic coupling. Consequently, this initiative will push CHL towards the forefront of computational phase-resolving wave modeling. .. note:: The original ``phaseWave`` package was written by ``Matt Malej``, with its main modules ``funwaveModule`` and ``coulwaveModule`` written by James Kirby et al. and Patrick Lynett et al., respectively. License ======== FUNWAVE is licensed under GNU - General Pulic License. The source can be obtained directly from the FUNWAVE website. COULWAVE (pCOULWAVE) is open source with no official license. .. _obtaining-sec: Obtaining phaseWave =================== For now, ``phaseWave`` is only available to developers as source from our git repository (:ref:`git-sec`). The currently supported platforms are:: * Linux * Mac OSX * Garnet (ERDC HPC system) under GNU, Intel, PGI compiler suites. The result is a portable compilation process. .. _git-sec: Git Repository Access ===================== The source code is available on github at: ``https://github.com/malej/phaseWave`` See ``http://help.github.com`` for help on using git and github. If you have setup Git on your system and have been granted acces to ``phaseWave`` repository, do the following:: %cd $HOME %git clone git@github.com:malej/phaseWave.git That will create phaseWave directory on in your home directory. .. _installing-sec: Installation ============= Build instructions for ``phaseWave`` are available on our wiki ``https://github.com/malej/phaseWave/wiki``, and you can ask for help on the developers' mailing list ``http://groups.google.com/group/phasewave-dev/subscribe``. At the moment we are working on automating the build process on our systems and will provide ``MAKEFILES`` for various platforms [WIP = Work In Progress] * Linux (Ubuntu, etc.) * OS X (Snow Leopard, Mountain Lion, Mavericks) * ERDC DSRC (High Performance Computting - HPC system: Garnet) * Windows ... eventually Note that you will have to set a system variable ``PHASEWAVE`` to point wherever you cloned the reposity. If you cloned it to your home directory, then in ``bash`` do the following:: export PHASEWAVE=$HOME/phaseWave source $PHASEWAVE/envConfig/YOURSYSTEM.bash where you would replace ``YOURSYSTEM`` with either * linux * darwin (Mac OS X) * garnet.gnu * garnet.intel * garnet.pgi Post-processing --------------- Currently there are native post-processing scripts supplied with both FUNWAVE and COULWAVE, but we are working on transitioning all of our post-processing scripts to an open-source platform (e.g. Matplotlib, ParaView, etc.). Developer Information ====================== The source code, wiki, and issue tracker for this ERDC adaptation of * FUNWAVE's version 2.1 of Jim Kirby et al. are * pCOLWAVE version 2.0 of Patrick Lynett et al. are on Github at https://github.come/malej/phaseWave. The developers' mailing is at http://groups.google.com/group/phasewave-dev. Access to this repository is private and requires approval at this time. Contact ======= For questions on the working version of this ERDC project contact the PI - Matt Malej (matt.malej@erdc.dren.mil) Contents ======== .. toctree:: :maxdepth: 5 ../api/modules.rst ../api/references.rst Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`