upstream changes

.github/ISSUE_TEMPLATE/add-development-request.md

@@ -0,0 +1,10 @@
+---
+name: Add Development Request
+about: Request that a new development be added to WW3
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Create a report to help us improve WW3
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,15 @@
+---
+name: Documentation request/update
+about: Add new section in the documentation or report a type/mistake in the documentation
+title: ''
+labels: 'documentation'
+assignees: ''
+
+---
+
+**Describe the section in the documentation that is missing or requires an update?**
+
+**Report a bug/typo in the documentation**
+
+**Link the issue(s) associated with this documentation update**
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for WW3
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. 
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -0,0 +1,43 @@
+# Pull Request Summary
+(Instructions: this, and all subsequent sections of text should be removed and filled in as appropriate.)   
+Please describe the PR summary
+
+## Description
+Provide a detailed description of what this PR does.
+What bug does it fix, or what feature does it add?
+Is a change of answers expected from this PR?
+
+### Issue(s) addressed
+* Is there an issue associated with this development (bug fix, enhancement, new feature)?    
+Please add a reference to a related issue(s) in WW3 repository (Follow [link](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue)).
+Link the issues to be closed with this PR, whether in this repository, or in another repository.
+(Remember, issues should always be created before starting work on a PR branch!).  
+Note that properly "linked issues" (either automatic links, or manual ones using the correct keywords) will be automatically closed when the PR is merged.
+
+- fixes #<issue_number>
+- fixes noaa-emc/ww3/issues/<issue_number>
+
+### Check list  
+* Is your feature branch up to date with the authoritative repository (NOAA/develop)?
+* Make sure you have checked the [checklist for a developer submitting to develop](https://github.com/NOAA-EMC/WW3/wiki/Code-Management#checklist-for-a-developer-submitting-to-develop), [checklist for a developer submitting to develop](https://github.com/NOAA-EMC/WW3/wiki/Code-Management#checklist-for-a-developer-submitting-to-develop) and [updating version number](https://github.com/NOAA-EMC/WW3/wiki/Code-Management#checklist-for-updating-version-number)
+* Reviewers: @mentions of suggested reviewers of the proposed changes.
+
+
+### Testing
+* How were these changes tested?
+* Are the changes covered by regression tests? (If not, why? Do new tests need to be added?)
+* If a new feature was added, was a new regression test added?
+* Have regression tests been run?
+* Which compiler / HPC you used to run the regression tests in the PR? 
+* Please provide the summary output of matrix.comp (_matrix.Diff.out_, _matrixCompFull.out_ and _matrixCompSummary.out_):    
+Please indicate the expected changes in the outputs ([excluding the known list of non-identical tests](https://github.com/NOAA-EMC/WW3/wiki/How-to-use-matrix.comp-to-compare-regtests-with-master#4-look-at-results)).
+
+
+
+
+
+
+
+
+
+

.gitignore

@@ -33,6 +33,7 @@ manual/ww3_systrk.tex
 manual/ww3_uprstr.tex
 manual/ww3_grib.tex
 manual/ww3_gint.tex
+manual/ww3_trnc.tex
 manual/gx_outf.tex
 manual/gx_outp.tex
 manual/*.log
@@ -44,16 +45,23 @@ manual/*.toc
 manual/*.out
 manual/*.dvi
 manual/*.pdf
+model?
+model??
+regtests/list*
+regtests/before
 regtests/matrix*
 regtests/*/work*
 regtests/*/input*/*.nc
 regtests/*/input*/*/*.nc
 regtests/*/input*/partition.ww3
 regtests/*/*.png
 regtests/ww3_tp2.14/input/oasis3-mct/doc
-regtests/ww3_tp2.14/input*/*.nc.OAS*CM
-regtests/ww3_tp2.14/input*/*/*.nc.OAS*CM
+regtests/ww3_tp2.14/input*/*.nc.OAS*CM*
+regtests/ww3_tp2.14/input*/*/*.nc.OAS*CM*
 regtests/ww3_tp2.17/input/inlet.msh
+regtests/ww3_tp2.21/input/mesh.msh
+regtests/ww3_tp2.21/input/obstructions_local.glo_unst.in
+regtests/ww3_tp2.21/input/obstructions_shadow.glo_unst.in
 *.nc
 */*.nc
 */*/*.nc
@@ -83,5 +91,9 @@ model/bin/wwatch3.env
 */*.swp
 */*/*.swp
 */*/*/*.swp
+.*.swp
+*/.*.swp
+*/*/.*.swp
+*/*/*/.*.swp
 
 .idea/

README.md

@@ -1,6 +1,6 @@
 # The WAVEWATCH III Framework
 
-WAVEWATCH III ® is a community wave modeling framework that includes the 
+WAVEWATCH III<sup>&reg;</sup>  is a community wave modeling framework that includes the 
 latest scientific advancements in the field of wind-wave modeling and dynamics.
 
 ## General Features
@@ -11,11 +11,11 @@ for shallow-water (surf zone) applications, as well as wetting and drying of
 grid points. Propagation of a wave spectrum can be solved using regular 
 (rectilinear or curvilinear) and unstructured (triangular) grids. See 
 [About WW3](https://github.com/NOAA-EMC/WW3/wiki/About-WW3) for a 
-detailed description of WAVEWATCH III &reg;.
+detailed description of WAVEWATCH III<sup>&reg;</sup> .
 
 ## Installation
 
-The WAVEWATCH III framework package has two parts that need to be combined so 
+The WAVEWATCH III<sup>&reg;</sup>  framework package has two parts that need to be combined so 
 all runs smoothly: the GitHub repo itself, and a binary data file bundle that 
 needs to be obtained from our ftp site. Steps to successfully acquire and install 
 the framework are outlined in our [Quick Start](https://github.com/NOAA-EMC/WW3/wiki/Quick-Start)

guide/guide.tex

@@ -17,7 +17,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % proper link to most recent manual %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\newcommand{\manver}{6.07}
+\newcommand{\manver}{7.12}
 \newcommand{\manref}{ww3man2019}
 \newcommand{\manregtestsec}{5.6}
 

manual/app/nuopc.tex

@@ -25,6 +25,10 @@ \subsection{~Building and Installing the NUOPC Cap} \label{sec:nuopcbuild}
 this makefile will subsequently call {\code w3\_make}. As part of this process a nuopc.mk makefile
 fragment will also be created, which tells NUOPC/ESMF where the \ws\ library is located. 
 
+Note there is a new switch {\code WRST} which will add 10 m wind to the restart file and use that wind field 
+at the initial time step of the wave model. This can be used in situations where the coupled atmospheric model 
+does not have 10 m wind speeds at initialization.
+
 \vssub
 \subsection{~Import/Export Fields in the NUOPC Cap} \label{sec:nuopcfields}
 \vssub

manual/defs.tex

@@ -1,4 +1,4 @@
-\newcommand{\WWver}{6.07}
+\newcommand{\WWver}{7.12}
 \newcommand{\guidever}{1.2}
 \newcommand{\guideref}{tol:MMABguide}
 \newcommand{\genever}{1.5}

manual/eqs/IS2.tex

@@ -104,21 +104,8 @@ \subsubsection{~$S_{is}$: Floe-size dependent scattering and dissipation} \label
 
 
 
-Inelastic dissipation was added in this routine, following \cite{art:Wad73}, because it critically 
-depends on the floe size.  It assumes that the floes deformation is not fully elastic, and that the secondary creep under the wave-induced cyclic causes the dissipation of wave energy into heat. 
-We use the ice floe law
-\begin{equation}
-%\left(\frac{d\varepsilon}{dt}\right)_{ij}=\frac{\tau^{n-1}}{B^n}\sigma_{i,j}'
-\left(\frac{d\varepsilon}{dt}\right)_{ij}=\frac{\tau^2}{B^3}\sigma_{i,j}',
-\end{equation}
-$B$ is the floe law  constant and is a function of ice temperature. Using the normalized parameter estimated by \cite{art:Cea98} from 
-laboratory experiments, $A=10^{11}$,  and  a uniform ice temperature of 270~K  gives a value 
-of $B=10^7$~s$^{1/3}$. The volumic dissipation rate is 
-\begin{equation}
-%\frac{de}{dt}= | \sigma_{xx}^{n+1}/(2B)^{n} |.
-\frac{de}{dt}= | \sigma_{xx}^{4}/(2B)^3 |.
-\end{equation}
-Also, the cyclic deformation of the ice can require a much larger elastic energy than the gravity potential 
+Anelastic or inelastic dissipation was inclued in this routine instead of ICn, because it critically 
+depends on the floe size. Following \cite{art:Bea18}, it is assumed that the floes deformation is not fully elastic, and that the wave-induced cyclic strain and stress cause the dissipation of wave energy into heat. The cyclic deformation of the ice can require a much larger elastic energy than the gravity potential 
 energy, but this is only true if the ice is not broken. As a result, working with a wave elevation spectrum $E(k)$ 
 could introduce large changes in $E(k)$ when the ice is broken or reformed. Instead we prefer 
 to work with an energy spectrum $ R C_g E(k)/C_{g,\mathrm{ice}}$, using the coefficient $R$ introduced by \cite{art:Wad73}, which 
@@ -136,47 +123,62 @@ \subsubsection{~$S_{is}$: Floe-size dependent scattering and dissipation} \label
 R=1+C_R\frac{4Y^*h^3\pi^4}{3\rho g \lambda^4(1-\nu^2)},
 \label{R}
 \end{equation}
-where we have been careful that \cite{art:Wad73} used $2h$ for the  ice thickness, 
+where we have been careful  that \cite{art:Wad73} used $2h$ for the  ice thickness, 
 and $C_R$ is by default set to 1.0 using the namelist parameter {\code IS2BREAKE}, but it can 
 be set to zero to work with the true elevation spectrum instead. This factor $R$ is also 
 applied in the calculation of ice breakup by the waves.\\
 
-
-The inelastic dissipation is linearized as  $S_{\mathrm{ine}}=-\alpha_{\mathrm{ine}} E_{ice}$. 
-The coefficient $\alpha_{\mathrm{creep}}$ was adapted from the 
-\cite{art:Wad73} monochromatic formula and is equal to
+By default, the anelastic dissipation term is used, activated by the namelist parameter {\code IS2ANDISB} set to {\code TRUE}. 
+Anelastic dissipation corresponds to the energy dissipated into heat during the oscillatory motion of the dislocations induced by the cyclic stress associated to waves.  This behaviour results in a hysteresis that can be seen in stress-strain diagrams when sea ice is submitted to a sinusoidal stress as presented in Fig.~4 of \cite{art:Cea98} study. This latter article also suggests a model for the anelastic behaviour of sea ice, with a stress-strain relationship that enables to compute the area within the ellipse which results from the hysteresis. Anelastic dissipation is linearized as  $S_{\mathrm{ane}}=-\alpha_{\mathrm{ane}} E_{ice}$. 
+\cite{art:Bea18} have derived  $\alpha_{\mathrm{ane}}$  from \cite{art:Cea98} model for a monochromatic stress, 
 \begin{equation}
-%\alpha_{\mathrm{ine}}=0.05 B h^5 \left(\frac{Y^*}{2B(1-\nu^2)}\right)^{(n+1)} I_n k^{n+1} \frac{C_g^2}{\rho g C_{g_{ice}}R^2} F \int_{k_1}^{k_2} k_{ice}^4 E(k)dk 
-\alpha_{\mathrm{ine}}=0.05 B h^5 \left(\frac{Y^*}{2B(1-\nu^2)}\right)^{4} I_3 k^4 \frac{C_g^2}{\rho g C_{g_{ice}}R^2} F_{\rm broken} \int_{k_1}^{k_2} k_{ice}^4 E(k)dk, 
-\label{eq:alpha_creep}
-\end{equation}
-where $I_3=\frac{1}{\pi} \int_0^\pi \sin^{4}\beta d\beta$. Details of the computation are given in \cite{art:Bea18}.
-$F_{\rm broken}$  is a heuristic smooth transition from unbroken to broken ice, so that the dissipation 
+\alpha_{\mathrm{ane}}= \dfrac{A}{6}\left(k_i^{2}\dfrac{Y^*}{(1-\nu^{2})\rho gG}\right)^{2}h^{3}\frac{C_g}{GC_{g,i}} F_{\rm broken},
+\label{eq:alpha_ane}
+\end{equation}  
+where $F_{\rm broken}$  is a heuristic smooth transition from unbroken to broken ice, so that the dissipation 
 gradually goes to zero for waves much longer than the floe sizes, because in that case the ice does 
 not deform and produces no dissipation of wave energy, 
 \begin{equation}
-F_{\rm broken}=\tanh \left( {\frac{D_{\max}-C_{\lambda}\lambda_{ice}} {D_{\max}C_{smooth} } }\right) .
+F_{\rm broken}=\tanh \left( {\frac{D_{\max}-C_{\lambda}\lambda_{ice}} {D_{\max}C_{smooth} } }\right).
 \label{smooth}
 \end{equation}
-Inelastic dissipation is computed after updating $D_{\max}$. 
+Anelastic or inelastic dissipation is computed after updating $D_{\max}$. 
 %dissipation is full for
 %$\lambda_{ice}\leq D_{\max}$ and disappears for $C_{\lambda}\lambda_{ice}< D_{\max}$.  
 The two parameters in this smooth transition $C_{\lambda}$ and $C_{smooth}$ are 
-set to  $0.4$ and $0.2$ by the adjustable namelist parameters {\code IS2CREEPD} and {\code IS2CREEPC}.\\
-
-Possibility of subsituting this inelastic dissipation by an anelastic dissipation term has also been added. It is activated by setting the namelist parameter {\code IS2ANDISB} to {\code TRUE}. 
-Anelastic dissipation corresponds to the energy dissipated into heat during the oscillatory motion of the dislocations induced by the cyclic stress associated to waves.  This behaviour results in a hysteresis that can be seen in stress-strain diagrams when sea ice is submitted to a sinusoidal stress as presented in Fig.~4 of \cite{art:Cea98} study. This latter article also suggests a model for the anelastic behaviour of sea ice, with a stress-strain relationship that enables to compute the area within the ellipse which results from the hysteresis. Similarly to what has been done for inelastic dissipation, anelastic dissipation is linearized as  $S_{\mathrm{ane}}=-\alpha_{\mathrm{ane}} E_{ice}$. 
-\cite{art:Bea18} have derived  $\alpha_{\mathrm{ane}}$  from \cite{art:Cea98} model for a monochromatic stress. They obtained the following coefficient: 
-\begin{equation}
-\alpha_{\mathrm{ane}}= \dfrac{A}{6}\left(k_i^{2}\dfrac{Y^*}{(1-\nu^{2})\rho gG}\right)^{2}h^{3}\frac{C_g}{GC_{g,i}} F_{\rm broken},
-\label{eq:alpha_ane}
-\end{equation}  
-where  $F_{\rm broken}$ is the same as for inelastic dissipation and $A$ is equal to:
+set to  $0.5$ and $0.4$ by default, as adujsted to Southern Ocean wave data. They can be modified by the namelist parameters {\code IS2CREEPD} and {\code IS2CREEPC}.
+FInally,  $A$ is given by 
 \begin{equation}
 A=\dfrac{4}{3}\sigma \alpha_{d}~\delta D^{d}~\dfrac{1}{\exp(\alpha_{d}s)+\exp(-\alpha_{d}s)}, 
 \label{eq:A_ane}
 \end{equation}  
-in which terms are detailed in the table at the end of this section.\\
+in which terms are detailed in the table at the end of this section. The magnitude of the dissipation is controlled by the dislocation relaxation parameter $\delta D^{d}$ .\\
+
+
+An alternative inelastic dissipation can be activated by setting {\code IS2ANDISB} to {\code FALSE}. In this case the following dissipation is used: 
+
+We use the ice floe law
+\begin{equation}
+%\left(\frac{d\varepsilon}{dt}\right)_{ij}=\frac{\tau^{n-1}}{B^n}\sigma_{i,j}'
+\left(\frac{d\varepsilon}{dt}\right)_{ij}=\frac{\tau^2}{B^3}\sigma_{i,j}',
+\end{equation}
+$B$ is the floe law  constant and is a function of ice temperature. Using the normalized parameter estimated by \cite{art:Cea98} from 
+laboratory experiments, $A=10^{11}$,  and  a uniform ice temperature of 270~K  gives a value 
+of $B=10^7$~s$^{1/3}$. The volumic dissipation rate is 
+\begin{equation}
+%\frac{de}{dt}= | \sigma_{xx}^{n+1}/(2B)^{n} |.
+\frac{de}{dt}= | \sigma_{xx}^{4}/(2B)^3 |.
+\end{equation}
+The inelastic dissipation is linearized as  $S_{\mathrm{ine}}=-\alpha_{\mathrm{ine}} E_{ice}$. 
+The coefficient $\alpha_{\mathrm{creep}}$ was adapted from the 
+\cite{art:Wad73} monochromatic formula and is equal to
+\begin{equation}
+%\alpha_{\mathrm{ine}}=0.05 B h^5 \left(\frac{Y^*}{2B(1-\nu^2)}\right)^{(n+1)} I_n k^{n+1} \frac{C_g^2}{\rho g C_{g_{ice}}R^2} F \int_{k_1}^{k_2} k_{ice}^4 E(k)dk 
+\alpha_{\mathrm{ine}}=0.05 B h^5 \left(\frac{Y^*}{2B(1-\nu^2)}\right)^{4} I_3 k^4 \frac{C_g^2}{\rho g C_{g_{ice}}R^2} F_{\rm broken} \int_{k_1}^{k_2} k_{ice}^4 E(k)dk, 
+\label{eq:alpha_creep}
+\end{equation}
+where $I_3=\frac{1}{\pi} \int_0^\pi \sin^{4}\beta d\beta$, and $F_{\rm broken}$ was defined above.
+ Details of the computation are given in \cite{art:Bea18}.
 
 Finally we recall the various model parameters used in IS2 in the following table. Some are defined 
 as constants in the {\code W3IS2MD} module, others can be adjusted with the {\F SIS2} namelist. 
@@ -195,10 +197,10 @@ \subsubsection{~$S_{is}$: Floe-size dependent scattering and dissipation} \label
 Flow law parameter           &$n$            & {\code IS2CREEPN} & 3\\
 Flow law parameter           &$B$            & {\code IS2CREEPB} &  10$^7$~s$^{1/3}$\\
 Elastic energy correction    & $C_R$         & {\code IS2BREAKE} & 1.0 \\
-Relax. of disloc. compliance & $\delta D^{d}$& {\code IS2ANDISD} & $\Delta_d \Omega b^2/K$ (Pa$^{-1}$)\\
-Dislocation density          & $\Delta_d$    & N. A. & 1.8$\times10^{9}$ (m$^{-2}$)\\
-Restoring stress term        & $K$           & N. A. & 0.07 (Pa) \\
-Orientation factor           & $\Omega$      & N. A. & $\pi^{-1}$ \\
+Relax. of disloc. compliance & $\delta D^{d}$& {\code IS2ANDISD} & $2  \times 10^{-9}$~(Pa$^{-1}$)\\
+%Dislocation density          & $\Delta_d$    & N. A. & 1.8$\times10^{9}$ (m$^{-2}$)\\
+%Restoring stress term        & $K$           & N. A. & 0.07 (Pa) \\
+%Orientation factor           & $\Omega$      & N. A. & $\pi^{-1}$ \\
 Burgers vector               & $b$           & N. A. & 4.52$\times10^{-10}$ (m) \\
 Drag term                    & $B$           & N. A. & $B_0 \exp(Q_v/(k_bT_K)$ (Pa.s)\\
  -                           & $B_0$         & N. A. & 1.205$\times10^{-9}$ (Pa.s)\\