Commit a4dc26f53e905559e2497c32618bc7cb3195f036

Authored by Jérémy Baudry
1 parent a7863271
Exists in master

ajout documentation

documentation/alpha.png 0 → 100644

21.8 KB

documentation/break.png 0 → 100644

15.7 KB

documentation/doc.pdf 0 → 100644
No preview for this file type
documentation/doc.synctex.gz 0 → 100644
No preview for this file type
documentation/doc.tex 0 → 100644
... ... @@ -0,0 +1,336 @@
  1 +\documentclass[10pt,a4paper]{report}
  2 +\usepackage[utf8x]{inputenc}
  3 +\usepackage{ucs}
  4 +\usepackage{amsmath}
  5 +\usepackage{amsfonts}
  6 +\usepackage{amssymb}
  7 +\usepackage{float}
  8 +\usepackage{graphicx}
  9 +\usepackage{listings}
  10 +\usepackage{color} %May be necessary if you want to color links
  11 +\usepackage{hyperref}
  12 +\hypersetup{
  13 + colorlinks=true, %set true if you want colored links
  14 + linktoc=all, %set to all if you want both sections and subsections linked
  15 + linkcolor=blue, %choose some color if you want links to stand out
  16 +}
  17 +
  18 +%\usepackage[obeyspaces]{url}
  19 +\newcommand{\inlinecode}{\texttt}
  20 +%\author{Dany Dumont, Eliott Bismuth, Jérémy Baudry}
  21 +\title{User Manual and Documentation of WIM}
  22 +\begin{document}
  23 +\maketitle
  24 +\tableofcontents
  25 +\chapter{Introduction}
  26 +WIM (Wave in-ice Model) is a simple conceptual 1D spectral model designed to assess some processes evolving in the interactions between waves and sea ice.
  27 +\chapter{Physical aspects}
  28 +The model capture two main features of the interactions between waves and sea ice:
  29 +The attenuation of wave energy by ice and the fracturation of the ice by waves.
  30 +This section review the physical processes implemented in WIM.
  31 +\section{The basics: The wave spectrum}
  32 +A record of the sea surface elevation $\eta(t)$ can be considered to be the sum of a large number of harmonic waves with random amplitude and phase.
  33 +\begin{equation}
  34 +\eta(t)=\sum_{i=1}^{N}\underline{a_i}cos(2\pi f_it+\underline{\alpha_i})
  35 + \end{equation}
  36 + \begin{figure}[H]
  37 + \begin{center}
  38 + \includegraphics[scale=0.5]{harmonic}
  39 +\caption{A wave record is a sum of many harmonic waves with different amplitudes and phases }
  40 +\end{center}
  41 +\end{figure}
  42 +The phases and amplitudes being random variables, they can be characterised with their probability density function. For each frequency, the phase $\underline{\alpha_i}$ is uniformly distributed between 0 and 2$\pi$ and the amplitude $\underline{a_i}$ is rayleigh distributed.
  43 +\begin{equation}
  44 +P(a_i)=\frac{\pi}{2}\frac{a_i}{\mu_i^2}\text{exp}\left( -\frac{\pi a_i^2}{4\mu_i^2}\right)
  45 +\end{equation}
  46 +where $\mu_i$ is the expected value of the amplitude $\mu_i=E\lbrace\underline{a_i}\rbrace$.
  47 +The function that shows this expected value over each frequency is called the amplitude spectrum.
  48 +\begin{figure}[H]
  49 + \begin{center}
  50 + \includegraphics[scale=0.5]{spectre1}
  51 +\caption{amplitude spectrum}
  52 +\end{center}
  53 +\end{figure}
  54 +But it is more relevant to consider the variance density spectrum
  55 +\begin{figure}[H]
  56 + \begin{center}
  57 + \includegraphics[scale=0.5]{spectre2}
  58 +\caption{variance density spectrum}
  59 +\end{center}
  60 +\end{figure}
  61 +By multiplying the variance density spectrum by $\rho g$, we obtain the \emph{energy spectrum}
  62 +\begin{equation}
  63 +S_{energy}=\rho gS_{variance}
  64 +\end{equation}
  65 +In WIM, the energy spectrum is described using an analytical function. There are many differents equation used to model the wave spectrum, in WIM it is possible to choose between a JONSWAP or a Bretschneider type spectrum. (see section 4.2.3)
  66 +\section{Advection}
  67 +The wave spectrum is advected by solving
  68 +\begin{equation}
  69 +\frac{\partial S}{\partial t}+c_g\frac{\partial S}{\partial x}=0
  70 +\end{equation}
  71 +\section{Attenuation}
  72 +The attenuation source term is defined as:
  73 +\begin{equation}
  74 +R_{ice}=\widehat{\alpha} S
  75 +\end{equation}
  76 +where $\widehat{\alpha}$ is a dimensional attenuation coefficient defined such as:
  77 +\begin{equation}
  78 +\widehat{\alpha}=\frac{\alpha c}{\left\langle D\right\rangle }
  79 +\end{equation}
  80 +where $\alpha$ is the dimensionless attenuation coefficient, i.e. the
  81 +(average) amount of attenuation per individual floe, which is a function of ice thickness and wave period.
  82 + \begin{figure}[H]
  83 + \begin{center}
  84 + \includegraphics[scale=0.5]{alpha}
  85 +\caption{Dimensionless energy attenuation coefficient $\alpha$ given bythe model of kohout et meylan (2008) }
  86 +\end{center}
  87 +\end{figure}
  88 +\section{floe breaking}
  89 +The model of Williams et al.(2013) is used to parametrize the wave induced floe breaking. \\
  90 +The flexural strain imposed by passing waves on ice is defined as:
  91 +\begin{equation}
  92 +\varepsilon=\frac{h}{2}\frac{\partial^2\eta}{\partial x^2}
  93 +\end{equation}
  94 +where $\eta$ is the sea surface elevation,$h$ the ice thickness and $x$ the horizontal distance.
  95 +We can also define the significant strain
  96 +\begin{equation}
  97 +E_s=2\sqrt{\left\langle \varepsilon^2\right\rangle}
  98 +\end{equation}
  99 +The mean square value is $\left\langle \varepsilon^2\right\rangle=m_0\left[ \varepsilon\right] $
  100 +where $m_0\left[ \varepsilon\right] $ is the 0th moment of the strain spectrum.
  101 +For a sinusoidal wave of the form $A_{ice}sin\left(k_{ice}x-\omega t\right) $ the maximum strain is \begin{equation}
  102 +E=\frac{h}{2}k_{ice}^2A_{ice}(\omega)
  103 +\end{equation}
  104 +where $k_{ice}$ is the wavelength in ice and $A_{ice}$ is the amplitude in the ice.
  105 +We can then define the 0th moment of the strain spectrum
  106 +\begin{equation}
  107 +m_0\left[ \varepsilon\right]=\int S(\omega)E^2(\omega)d\omega
  108 +\end{equation}
  109 +If the significant strain $E_s$ exceed a certain threshold $E_s>\varepsilon_c$ then the ice breaks and the maximumfloesiwe is set to
  110 +\begin{equation}
  111 +D_{max}=max\left[ \lambda_w/2,D_{min}\right]
  112 +\end{equation}
  113 +where $D_{min}$ is the minimum floe size and $\lambda_w$ the dominant wavelength defined as $ \lambda_w=2\pi/k_w$ and $k_w=k_{ice}(2\pi/T_w)$.
  114 +$T_w$ is the dominant period of the spectrum defined as:
  115 +\begin{equation}
  116 +T_w=2\pi\sqrt{\frac{m_0\left[\eta \right] }{m_2\left[\eta \right]}}
  117 +\end{equation}
  118 +where $m_n\left[\eta \right]$ is the nth moment of the wave spectrum defined as:
  119 +\begin{equation}
  120 +m_n\left[\eta \right]=\int\omega^nS(\omega)d\omega
  121 +\end{equation}
  122 +\chapter{Getting started}
  123 +\section{Get WIM source code}
  124 +The WIM source code is available on the plateform \url{https://gitlasso.uqar.ca/}.
  125 +To download WIM from this plateform, please execute the following steps:
  126 +
  127 +\begin{enumerate}
  128 +\item create the destination folder where the source code will be download by typing \inlinecode{mkdir <directory name>}
  129 +\item go to the destination folder \inlinecode{cd <directory name>} and execute \inlinecode{ git clone https://gitlasso.uqar.ca/bauj0001/WIM2.git .}
  130 +\end{enumerate}
  131 +\subsection{Contents}
  132 +There are 3 subdirectories:
  133 +\begin{enumerate}
  134 + \item \path{src}: This directory contains all the source files of the routines and subroutines of WIM and the makefile to link and compile all source files
  135 + \item \path{nml}: Contains the namelist file which allow to change model parameters without recompiling the code
  136 + \item \path{output}: Contains the outputs in NETCDF format.
  137 + \end{enumerate}
  138 +
  139 +\section{Compile and execute WIM}
  140 +Compilation in WIM is relatively easy. The following steps should however be executed correctly to compile the code without errors.
  141 +\begin{enumerate}
  142 +\item Open the \textbf{makefile} in \path{WIM/src/}
  143 +\item Choose the compiler that will be used to produce the executable by changing the variable COMPILER. By default, the compiler used is GFORTRAN but it should work with other compilers like INTEL FORTRAN
  144 +\item WIM uses the NETCDF library to save outputs. Ensure first that the fortran NETCDF library is currently installed on your machine. If it is not the case, you can download it at \url{http://www.unidata.ucar.edu/downloads/netcdf/index.jsp}. Once the NETCDF library is installed on your machine, you should link it to WIM by indicating the path of the includes files, modules and libraries in the variables NETCDFINC, NETCDFMOD, NETCDFLIB.
  145 +\item You can now compile the code by typing \inlinecode{make} in \path{src/}. The executable will be created in the parent directory \path{WIM/}.You can also type \inlinecode{make clean} or \inlinecode{make mrproper} to remove the executable, the objects .o and modules .mod if needed.
  146 +\item Now execute WIM by typing \inlinecode{./<executable name>}
  147 +\end{enumerate}
  148 +\section{Beginning with WIM: using namelists}
  149 +Designing a simulation with WIM is quite easy. The WIM model uses \textit{namelists} allowing to change some parameter values without recompiling the source code. afterchanging parameters in the namelists, the values will be read by the routine \textbf{parameters.f90} (see \textit{routines details} for more informations). All namelists are written in a single file \path{nml/parameter.nml}. The file is composed by 4 namelists:
  150 +\begin{itemize}
  151 +\item \textbf{model paramete}r: This namelist allow to change some global parameters of the simulations such as the siwe of the domain, the name of the output directory, the name of the simulation etc..
  152 +\item \textbf{waves parameters}: Specifies the waves parameters such as the significant height, the peak period and some features like allowing dispersion or not.
  153 +\item \textbf{spectrum parameters}: Specifies the parameters to construct the wave spectrum such as the number of frequency bin, the minimal and maximal frequency.
  154 +\item \textbf{ice parameters}: Specifies some ice features like the ice concentration, thickness, initial mean diameters of the floes etc..
  155 +\end{itemize}
  156 +After having changed the parameters in the namelists, you can now run WIM.
  157 +
  158 +\chapter{Implementation}
  159 +\section{General}
  160 +\subsection{General algorithm}
  161 +
  162 +\begin{verbatim}
  163 +read namelists
  164 +allocate memory
  165 +initialize
  166 +
  167 +do time loop
  168 + advection
  169 +
  170 + do space loop
  171 + attenuation
  172 + floe breaking
  173 + compute new FSD
  174 + end space loop
  175 +
  176 +end time loop
  177 +
  178 +write outputs
  179 +deallocate memory
  180 +
  181 +\end{verbatim}
  182 +
  183 +\subsection{Solving ODEs}
  184 +Time ordinary differential equations are solved in WIM using the first-order Euler method.
  185 +For a ODE of the general form
  186 +\begin{equation}
  187 +\frac{dX}{dt}=F(X,t)
  188 +\end{equation}
  189 +The euler method give:
  190 +\begin{equation}
  191 +X_{n+1}=X_n + F(X_n,t_n)\Delta t
  192 +\end{equation}
  193 +\section{Routine details}
  194 +
  195 +\subsection{main.f90}
  196 +This is the main program of WIM. It calls all the other subroutines and does the time Loop. It also contains the subroutine \inlinecode{progress} which displays a progress bar in the consol while the model is running.
  197 +\subsection{parameters.f90}
  198 +The module \path{parameters.f90} contains all variable and parameters definitions used in the model. All others routines call this module with the Fortran function \inlinecode{USE PARAMETERS}. This module also contains some other subroutines:
  199 +\begin{enumerate}
  200 +\item \textbf{read namelists}: Read parameters value specified in the differents namelists contained in the file \inlinecode{parameters.nml} (see Beginning with WIM: using namelists)
  201 +\item \textbf{array allocation}: Allocate memory for the different arrays and matrix.
  202 +
  203 +\end{enumerate}
  204 +\subsection{initialization.f90}
  205 +In this routine, the initial spectrum and ice transect are built and initial values for arrays are set.
  206 +\subsubsection{initial spectrum}
  207 +It is possible de choose between different methods to build the initial spectrum by setting the parameter \inlinecode{init spec} in the namelist \inlinecode{spectrum parameters}. If \inlinecode{init spec}=1 then a JONSWAP spectrum is built according to
  208 +\begin{equation}
  209 +S_{init}=\alpha H_s^2\frac{f_p^4}{f^5}\text{exp}\left[\frac{-5}{4}\left(\frac{f_p}{f} \right)^4 \right] \gamma^{\text{exp}\left[ \frac{-(f-fp)^2}{2\sigma^2f_p^2}\right] }
  210 +\end{equation}
  211 +where
  212 +\[\alpha=\frac{0.0624}{0.23+0.0336\gamma-\frac{0.185}{1.9+\gamma}}\]
  213 +and
  214 +\[
  215 +\sigma=
  216 +\begin{cases}
  217 +0.07, & \text{if } f\leq f_p \\
  218 +0.09 , & \text{if } f> f_p
  219 +\end{cases}\]
  220 +(see \url{http://hmf.enseeiht.fr/travaux/CD0910/bei/beiere/groupe4/node/59}).\\
  221 +If \inlinecode{init spec}=2 then a Bretschneider spectrum is built according to
  222 +\begin{equation}
  223 +S_{init}=\frac{1.25H_s^2T^5}{8\pi T_p^2}e^{-1.25(T/T_p)^4}
  224 +\end{equation}
  225 +where $T_p$ is the peak period and $H_s$ the significant height
  226 +\subsubsection{Ice transect}
  227 +Parameters for ice transect can be set in the namelist \inlinecode{ice parameters}. Ice concentration is uniform through the domain
  228 +\begin{equation}
  229 +C(x)=
  230 +\begin{cases}
  231 +0, & \text{if } x<X_1 \\
  232 +\inlinecode{cice} , & \text{if } X_1<x<X_2
  233 +\end{cases}
  234 + \end{equation}
  235 +If \inlinecode{ice thick}=0 then the ice thickness is constant along the transect. if \inlinecode{ice thick}=1 the ice thickness depends on the distance from the ice edge according to
  236 +\begin{equation}
  237 +h(x)=
  238 +\begin{cases}
  239 +0, & \text{if } x<X_1 \\
  240 +h_{\infty}\left(0.1+0.9\left(1-e^{-\left(x-X_1/X_h \right) }\right) \right) , & \text{if } X_1<x<X_2
  241 +\end{cases}
  242 + \end{equation}
  243 + \begin{figure}[H]
  244 + \begin{center}
  245 + \includegraphics[scale=0.5]{icetransect}
  246 +\caption{Schematical visualization of the ice transect}
  247 +\end{center}
  248 +\end{figure}
  249 +\subsection{advection.f90}
  250 +Here the wave spectrum is advected through the domain by solving
  251 +\begin{equation}
  252 +\frac{\partial S}{\partial t}+c_g\frac{\partial S}{\partial x}=0
  253 +\end{equation}.
  254 +This equation is discretized using the second order Lax-Wendroff sheme with a superbee flux limiter.
  255 +\subsubsection{Lax-Wendroff without Flux limiter}
  256 +The Lax-Wendroff sheme is a \textit{multistep} method where the quantity $S_i^{t+1}$ is calculated using the quantities $S_{i-\frac{1}{2}}^{t+\frac{1}{2}}$
  257 +and $S_{i+\frac{1}{2}}^{t+\frac{1}{2}}$.\\
  258 +Using the central difference sheme, the quantity $S_i^{t+1}$ can be approximated by
  259 +\begin{equation}
  260 +S_i^{t+1}=S_i^{t}-\frac{c_g\Delta t}{\Delta x}\left(S_{i+\frac{1}{2}}^{t+\frac{1}{2}}-S_{i-\frac{1}{2}}^{t+\frac{1}{2}} \right)
  261 +\end{equation}
  262 +The both quantities $S_{i\pm\frac{1}{2}}^{t+\frac{1}{2}}$ are obtained by the Lax method:
  263 +\begin{equation}
  264 +S_{i-\frac{1}{2}}^{t+\frac{1}{2}}=\frac{1}{2}\left(S_i^{t}+S_{i-1}^{t}\right)-\frac{c_g\Delta t}{2\Delta x}\left(S_i^{t}-S_{i-1}^{t} \right)
  265 +\end{equation}
  266 +\begin{equation}
  267 +S_{i+\frac{1}{2}}^{t+\frac{1}{2}}=\frac{1}{2}\left(S_i^{t}+S_{i+1}^{t}\right)-\frac{c_g\Delta t}{2\Delta x}\left(S_{i+1}^{t}-S_{i}^{t} \right)
  268 +\end{equation}
  269 +\begin{figure}[H]
  270 +\includegraphics[scale=0.6]{laxW}
  271 +\caption{Schematical visualization of the Lax-Wendroff method}
  272 +\end{figure}
  273 +The Lax-Wendroff sheme is then:
  274 +\begin{equation}
  275 +S^{t+1}_i=S^{t}_i-\frac{c_g\Delta t}{2\Delta x}\left(S^{t}_{i+1}-S^{t}_{i-1} \right)+\frac{c_g^2\Delta t^2}{2\Delta x^2}\left(S^{t}_{i+1}-2S^{t}_{i}+S^{t}_{i-1} \right)
  276 +\end{equation}
  277 +\subsubsection{The Superbee Flux limiter}
  278 +It can be seen above that the Lax-Wendroff sheme is a combination of a 1-order term and a 2-order term. To avoid oscillation near steps due to this second term, we add a flux limiter which will "weight" the two terms.
  279 +\begin{equation}
  280 +\phi(\theta)=\text{max}\left[0,\text{min}\left(2\theta,1 \right),\text{min}\left(\theta,2 \right) \right]
  281 +\end{equation}
  282 +where $\theta$ is given by
  283 +\begin{equation}
  284 +\theta=\frac{S^t_{i+1}-S^t_{i}}{S^t_{i}-S^t_{i-1}}
  285 +\end{equation}
  286 +The Lax-Wendroff with superbee flux limiter is then
  287 +\begin{equation}
  288 +S^{t+1}_i=S^{t}_i-\phi(\theta)\frac{c_g\Delta t}{2\Delta x}\left(S^{t}_{i+1}-S^{t}_{i-1} \right)+\phi(\theta)\frac{c_g^2\Delta t^2}{2\Delta x^2}\left(S^{t}_{i+1}-2S^{t}_{i}+S^{t}_{i-1} \right)
  289 +\end{equation}
  290 +\subsubsection{Boundary conditions}
  291 +Boundary conditions are set according to $\Delta S=0$
  292 +\subsubsection{Wave dispersion}
  293 +In WIM it is possible to allow or not wave dispersion by changing the parameter \inlinecode{disp} in the namelist \inlinecode{waves parameters}.
  294 +If \inlinecode{disp} take the value 1, dispersion is allowed and $c_g$ depend on the wave period.
  295 +If \inlinecode{disp} take the value 0, the spectrum is advected at all frequencies at the same speed $c_g=max[c_g(\omega)]$
  296 +
  297 +\subsection{attenuation.f90}
  298 +In this routine, the dimensionless attenuation coefficient $\alpha$ from Kohout and Meylan (2008) is approximated and the attenuation source term is computed
  299 +\subsection{fsd build.f90}
  300 +In this routine the average floe size $\left\langle D\right\rangle $ for wave attenuation calculation. It is possible to choose between two methods by setting the parameter \inlinecode{FSD sheme} in the namelist \inlinecode{model parameters}.
  301 +If \inlinecode{FSD sheme}$=0$ then the method proposed by Dumont et al (2011) is used.
  302 +\begin{equation}
  303 +\left\langle D\right\rangle=\frac{\sum_{m=0}^{M}(\xi^2f)^m\xi^{-m}D_{max}}{\sum_{m=0}^{M}(\xi^2f)^m}
  304 +\end{equation}
  305 +where $f$ is the breaking probability (ie. the fragility of the floes), $D_{min}$ the minimum floe size, $\xi$ a parameter which determine the number of pieces each floe will be fragmented into and $M$ the number of fragmentation steps defined as:
  306 +\begin{equation}
  307 +M=\text{log}_\xi(D_{max}/D_{min})
  308 +\end{equation}
  309 + \begin{figure}[H]
  310 + \begin{center}
  311 + \includegraphics[scale=0.4]{break}
  312 +\caption{Schematical visualization of the ice transect}
  313 +\end{center}
  314 +\end{figure}
  315 +if \inlinecode{FSD sheme}$=1$, a power law is used to compute $\left\langle D\right\rangle $
  316 +\begin{equation}
  317 +\left\langle D\right\rangle=A^{-1}\int_{D_{min}}^{D_{max}}D^{-\gamma +1}
  318 +\end{equation}
  319 +where $\gamma$ is the exponent of the power law and $A$ a coefficient defined as
  320 +\begin{equation}
  321 +A=\frac{1}{1-\gamma}\left( D_{max}^{1-\gamma}- D_{min}^{1-\gamma}\right)
  322 +\end{equation}
  323 +\subsection{write output.f90}
  324 +In this routine, the output file is created in NETCDF format. Here is an example of an output file:
  325 +\begin{figure}[H]
  326 + \begin{center}
  327 + \includegraphics[scale=0.5]{output}
  328 +\caption{Example of an output file}
  329 +\end{center}
  330 +\end{figure}
  331 +\chapter{Graphical User Interface}
  332 +
  333 +\begin{center}
  334 +This section is not yet available
  335 +\end{center}
  336 +\end{document}
0 337 \ No newline at end of file
... ...
documentation/harmonic.png 0 → 100644

36.5 KB

documentation/icetransect.png 0 → 100644

15.6 KB

documentation/laxW.png 0 → 100644

7.21 KB

documentation/output.png 0 → 100644

14.9 KB

documentation/spectre1.png 0 → 100644

10.1 KB

documentation/spectre2.png 0 → 100644

15.7 KB