\documentclass[11pt,oneside,a4paper]{article}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{stmaryrd}
\usepackage{listings}

\lstset{
  language = Java,
  breaklines = true,
  captionpos = b,
  basicstyle = \footnotesize,
  frame = leftline,
  morekeywords = {skip,then},
}

\newenvironment{changemargin}[2]{%
\begin{list}{}{%
\setlength{\topsep}{0pt}%
\setlength{\leftmargin}{#1}% \setlength{\rightmargin}{#2}%
\setlength{\listparindent}{\parindent}%
\setlength{\itemindent}{\parindent}%
\setlength{\parsep}{\parskip}%
}%
\item[]}{\end{list}}

\newcommand{\SExp}[2]{\mathcal{#1}\llbracket #2 \rrbracket}
\newcommand{\AExp}[2]{\SExp{A}{#1}(#2)}
\newcommand{\BExp}[2]{\SExp{B}{#1}(#2)}
\newcommand{\AMIns}[1]{\textsc{#1}}
\newcommand{\AMConf}[3]{\langle #1, #2, #3 \rangle}
\newcommand{\AMArrow}{\: &\triangleright&\:\;}
\newcommand{\sign}{\textbf{Sign}_{\bot}}
\newcommand{\TT}{\textbf{TT}_{\bot}}
\newcommand{\abs}[2]{\textbf{abs}_{\,#1_{\bot}} #2 }
\begin{document}
\title{Report for Lab Assignment 2, DD2457 Program Semantics and Analysis}
\author{Erik Helin \& Oskar Arvidsson}
\date{\today}
\maketitle
\section*{Operational semantics for AM}
\begin{align*}
&\AMConf{\AMIns{push-}n:c}{e}{s} \AMArrow
 \AMConf{c}{\abs{Z}{\SExp{N}{n}}:e}{s} \\
&\AMConf{\AMIns{add}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 +_{SE} v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{sub}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 -_{SE} v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{mul}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 \star_{SE} v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{div}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 \: /_{SE}\: v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{true}:c}{e}{s} \AMArrow
 \AMConf{c}{\abs{T}{\textbf{tt}}:e}{s}& \\
&\AMConf{\AMIns{false}:c}{e}{s} \AMArrow
 \AMConf{c}{\abs{T}{\textbf{ff}}:e}{s}& \\
&\AMConf{\AMIns{eq}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 =_{SE} v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{le}:c}{v_1:v_2:e}{s} \AMArrow
 \AMConf{c}{v_1 \leq_{SE} v_2:e}{s}& \text{ if } v_1, v_2 \in \:& \sign \\
&\AMConf{\AMIns{and}:c}{t_1:t_2:e}{s} \AMArrow
 \AMConf{c}{t_1 \land_{SE} t_2:e}{s}& \text{ if } t_1, t_2 \in \:& \TT \\
&\AMConf{\AMIns{neg}:c}{t_1:t_2:e}{s} \AMArrow
 \AMConf{c}{t_1 \: \neg_{SE}\: t_2:e}{s}& \text{ if } t_1, t_2 \in \:& \TT \\
&\AMConf{\AMIns{fetch-}x:c}{e}{s} \AMArrow
 \AMConf{c}{(s\;x):e}{s} \\
&\AMConf{\AMIns{store-}x:c}{v:e}{s} \AMArrow
 \begin{cases}
    \AMConf{c}{e}{s[x \mapsto v]} & \text{ if } v \sqsubseteq_{SE} Z \\
    \AMConf{c}{e}{\hat{s}} & \text{ if } ERR_A \sqsubseteq_{SE} v \\
    \AMConf{c}{e}{s[x \mapsto v \underset{SE}{\sqcap} Z]} &
    \text{ if } Z \sqsubseteq_{SE} v \\
 \end{cases}& \\
&\AMConf{\AMIns{noop}:c}{e}{s} \AMArrow
 \AMConf{c}{e}{s} \\
&\AMConf{\AMIns{branch}(c_1,c_2):c}{v:e}{s} \AMArrow
 \begin{cases}
    \AMConf{c_1:c}{e}{s} & \text{ if } TT \sqsubseteq_{TE} v \\
    \AMConf{c_2:c}{e}{s} & \text{ if } FF \sqsubseteq_{TE} v \\
    \AMConf{c}{e}{\hat{s}} & \text{ if } ERR_B \sqsubseteq_{TE} v \\
 \end{cases}& \\
&\AMConf{\AMIns{loop}(c_1,c_2):c}{e}{s} \AMArrow
 \AMConf{c_1:\AMIns{branch}(c_2:\AMIns{loop}(c_1, c_2), \AMIns{noop}):c}{e}{s}\\
&\AMConf{\AMIns{try}(c_1, c_2):c}{e}{s} \AMArrow
 \AMConf{c_1:\AMIns{catch}(c_2):c}{e}{s}& \\
&\AMConf{\AMIns{catch}(c_1):c}{e}{s} \AMArrow
 \AMConf{c}{e}{s}& \\
&\AMConf{\AMIns{catch}(c_1):c}{e}{\hat{s}} \AMArrow
 \AMConf{c_1:c}{e}{s}& \\
&\AMConf{c_1:c}{e}{\hat{s}} \AMArrow \AMConf{c}{e}{\hat{s}}
\end{align*}
In the rule for \textsc{store}, \(\underset{SE}{\sqcap}\) means the greatest
lower bound in the \(\sign\) lattice.
Note that, in the rule for \textsc{store}, if \(x\) equals \(Z\), the
configuration returned from the first and third case will be equivalent.
Therefore the result becomes only one configuration. Also note that
\textsc{store} and \textsc{branch} are the only nondeterministic rules.

\section*{Analysis}
  Under the right conditions the analysis is able to show a number of
  interesting features of the analysed program, such as:

  \begin{description}
    \item[Variables values] Features of the variables values in the
      configuration states throughout the program. E.g.\ a variable may always
      be positive at a control point in the program.
    \item[Exceptional states] Control points where an exception may occur.
    \item[Unreachable code] Control points in the program that cannot be
      reached in the given context.
    \item[Unneeded try-catch constructs] For example if an exceptional state
      impossibly can occur in a try block.
    \item[Termination] The analysis can tell if the program will terminate
      normally if it terminates or if the termination may be exceptional. In
      some cases the analysis is able to tell that the program won't terminate.
  \end{description}

  \subsection*{Examples}
    Below follows a number of results obtained from the analysis.

    \subsubsection*{Infinite looping}
      In listing \ref{lst:inf} the analysis is able to capture that the program
      won't terminate. If the line $y := y - 1$ had been interchanged with $y
      := y + 1$ though, the analysis wouldn't have catched this although the
      program wouldn't have terminated in this case either.

      \lstinputlisting[
        caption={Analysis of a non-terminating program},
        label=lst:inf]{analysis/infinite.analysis}

    \subsubsection*{Catch}
      In listing \ref{lst:catch-1} the analysis comes to the result that the
      catch block is unneeded. Correspondingly, in listing \ref{lst:catch-2}
      the analysis discovers that the program will always go through the catch
      block.

      \lstinputlisting[
        caption={Analysis of a program with an unneeded catch block},
        label=lst:catch-1]{analysis/unneeded_catch.analysis}

      \lstinputlisting[
        caption={Analysis of a program where the catch block is always reached},
        label=lst:catch-2]{analysis/always_catch.analysis}

\section*{Discussion}
  Alas, the analysis is not very good for all but very simple programs. For
  example, in the program given below $x$ is clearly evaluated to $0$, but the
  analysis will evaluate it to a non error value -- that is either positive,
  negative or zero which is pretty much useless for further analysis.

  \[
    x := 5-5
  \]

  A better analysis for example given above is pretty easy to incorporate in
  the analyzer. For a better analysis it would be useful with more discrete
  possible values. Many loops operate over quite small ranges of integer
  values, e.g.\ $x \in [0,255]$. It would be quite easy to add more discrete
  values to the analyzer although the analyzing process would take more time.

  Another example of a feature that's missing in the analyzer is that simple
  conditions that always hold are not captured. For example, in listing
  \ref{lst:invariant}, $x > y$ always holds. Thus the else block will never be
  executed, but the analyzer will not capture this.

  \begin{lstlisting}[
      caption={A program where $y > x$ always holds},
      label=lst:invariant,
      gobble=4
    ]
    x := 0 ;
    y := 2 ;
    i := 0 ;

    (while i <= 10 do
      x := x + 1 ;
      y := y + 1 ;
      i := i + 1
    ) ;

    if x <= y then
      x := 0
    else
      x := 1
  \end{lstlisting}

\end{document}


\documentclass{discussion}

\usepackage{framed}
\usepackage[position=b]{subcaption}
\DeclareMathOperator{\Parents}{Parents}
\DeclareMathOperator{\NonDesc}{NonDesc}
\newcommand{\G}{\mathcal{G}}
\newcommand{\I}{\mathcal{I}}
\linespread{1.0}
\begin{document}

% Lecture Info
\lecture{9}{Explaining Away}{Benjamin R. Bray and Chansoo Lee}

%%%% INTRODUCTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Probabilistic influence}

Recall the HW5 Problem 3.

\begin{lemma}
\(P(t_1 | d_1) < P(t_1 | d_0)\)
\end{lemma}
Intuitively, this statement is kind of obvious. The person is on good diet $(d_1)$ should be less likely to test for high cholesterol $(t_1)$
\begin{proof}
From the factorization theorem, $T$ is independent of all variables other than $C$ given $D$. So,
\begin{equation}
\label{eq:t_d_ind}
	P(T | D, u) = P(T | D)
\end{equation} for all values of $u$.

Now from the definition, we have that
\begin{equation}
	P(c_1 | d_1) < P(c_1 | d_0)
\end{equation}
meaning people with good diet is less likely to have a high cholesterol than those with bad diet. We were able to eliminate the conditioning on $u$ because of \eqref{eq:t_d_ind}.
Similarly,
\[P(t_1 | c_1) > P(t_1 | c_0).\]

Because $T$ and $D$ are independent given $C$, we can write
\[P(T | D) = \sum_{c} P(T, C = c | D) = \sum_{c} P(T| C = c) P(C = c | D).
\]

Now,
\[
P(t_1 | d_1) = P(t_1 | c_1) P(c_1 | d_1) +P(t_1 | c_0) P(c_0 | d_1)
\]
and
\[P(t_1 | d_0) = P(t_1 | c_1) P(c_1 | d_0)
+P(t_1 | c_0) P(c_0 | d_0)
\]

We compute the difference:
\begin{align*}
P(t_1 | d_0) - P(t_1 | d_1)
&= P(t_1 | c_1) (P(c_1 | d_0) - P(c_1 | d_1))
+ P(t_1 | c_0) (P(c_0 | d_0) - P(c_0 | d_1)) \\
&= P(t_1 | c_1) (P(c_1 | d_0) - P(c_1 | d_1))
+ P(t_1 | c_0) \big(1 - P(c_1 | d_0) - (1 - P(c_1 | d_1))\big) \\
& = \big(P(t_1 | c_1) - P(t_1 | c_0)\big) \big(P(c_1 | d_0) - P(c_1 | d_1)\big)
\end{align*}
which is positive because both terms in the parentheses are positive.
\end{proof}

\begin{corollary}
\[	P(t_1 | d_1) < P(t_1)\]
\end{corollary}
\begin{proof}
	Note that
	\[P(t_1) = P(t_1 | d_1) p(d_1) + p(t_1 | d_0) p(d_0) > P(t_1 | d_1) p(d_1) + p(t_1 | d_1) p(d_0) = P(t_1 | d_1)\qedhere\]
\end{proof}

% \begin{lemma}
% \[	P(d_1 | e_1, m_1) < P(d_1 | m_1)\]
% \end{lemma}
% \begin{proof}
% \[	P(d_1 | e_1, m_1)
%  = P(m_1 | d_1, e_1) P(d_1) / P(m_1)
%  > P(m_1 | d_1, e_0) P(d_1) / P(m_1)
%  = P(d_1 | e_0, m_1).
% \]
% So,
% \[P(d_1 | m_1) = P(d_1 | m_1, e_0) P(e_0) + P(d_1 | m_1, e_1)P(e_1) < P(d_1 | m_1, e_1) P(e_0) + P(d_1 | m_1, e_1)P(e_1) = P(d_1 | m_1,e_1)\]
% \end{proof}

\section{Explaining Away}
The explaining away is the following phenomenon:
\begin{equation}
\label{eq:explainaway}
	P(h_1 | b_0, e_1) < P(h_1 | b_1, e_1).
\end{equation}
It follows that
\[P(h_1 | b_0, e_1) < P(h_1 | e_1)< P(h_1 | b_1, e_1).\]
Let's explore the sufficient and necessary condition for this to happen.

By the Bayes rule,
\[P(h_1 | e_1, B) = P(e_1 | h_1, B) \frac{P(h_1 | B)}{P(e_1 | B)} = P(e_1 | h_1, B) \frac{P(h_1)}{P(e_1 | B)}\]
since $H$ and $B$ are independent.

%  \eqref{eq:explainaway} is equivalent to
% \[\frac{P(e_1 | h_1, b_0)}{P(e_1 | b_0)} < \frac{P(e_1 | h_1, b_1)}{P(e_1 | b_1)}	\]
% which is also equivalent to
% \begin{equation}
% \label{eq:explainaway_ratio}
% \frac{P(e_1 | b_0)}{P(e_1 | h_1, b_0)} > \frac{P(e_1 | b_1)}{P(e_1 | h_1, b_1)}
% \end{equation}

Note that
\[P(e_1 | B) = P(e_1 | h_1, B)P(h_1) + P(e_1 | h_0, B)P(h_0)\]

So,
\[\frac{1}{P(h_1|e_1,B)}
= 1 + \frac{P(e_1 | h_0, B)P(h_0)}{P(e_1|h_1,B)P(h_1)}\]

Hence, an equivalent statement of \eqref{eq:explainaway}
\[	1/P(h_1 | b_0, e_1) > 1/P(h_1 | b_1, e_1)
\]
is equivalent to
\[1 + \frac{P(e_1 | h_0, b_0)P(h_0)}{P(e_1|h_1,b_0)P(h_1)} > 1 + \frac{P(e_1 | h_0, b_1)P(h_0)}{P(e_1|h_1,b_1)P(h_1)}
\]
which simplifies to
\[\frac{P(e_1 | h_0, b_0)}{P(e_1|h_1,b_0)} > \frac{P(e_1 | h_0, b_1)}{P(e_1|h_1,b_1)}.\]
% and similarly,
% \[P(e_1 | b_1) = P(e_1 | h_1, b_1)P(h_1) + P(e_1 | h_0, b_1)P(h_0)\]

Finally, we rearrange this:
\begin{equation}
\label{eq:explainaway_condition}
	\frac{P(e_1 | h_0, b_0)}{P(e_1 | h_0, b_1)} > \frac{P(e_1|h_1,b_0)}{P(e_1|h_1,b_1)}.
\end{equation}

So, the time constraint has more dramatic effect on the people that are not health-conscious. Health-conscious people are less likely to exercise if they are busy, but this probability drop is much less severe because they try to make time for exercise.

\begin{exercise}
	Give a realistic example where \eqref{eq:explainaway_condition} fails to hold.
\end{exercise}

\paragraph{Answer.}	In the same graphical structure as $H,E,B$ but replace $H$ with horrible weather, $B$ with road block (due to construction) and $E$ with extremely long commute.

	Suppose the road can't handle traffic given either of the bad conditions. The difference between $P(e_1| h_0, b_0)$ and $P(e_1 | h_0, b_1)$ is big, making the LHS small. But if the road is already hit with horrible weather, then the additional effect of road block is small, so the RHS is big.

\end{document}


\documentclass[a4paper]{article}

\def\npart{II}

\def\ntitle{Dynamical Systems}
\def\nlecturer{J.\ R.\ Lister}

\def\nterm{Michaelmas}
\def\nyear{2017}

\input{header}

\begin{document}

\input{titlepage}

\section{Stability}

It is clear what we mean by \emph{hyperbolic nodel focii} begin stable/unstable. We need to be more careful with other kinds of fixed points or other invariant sets because there are at least two distinct types of stabilities, i.e. saddle and centre.

\subsection{Definitions}

Consider a flow \(\phi_t(x)\),
\begin{definition}[Lyapunov Stability]
 A fixed point \(x_0\) is \emph{Lyapunov stable} if \(\forall\varepsilon>0, \exists\delta>0\) such that
\[
  |\phi_t(x)-x_0| < \varepsilon \, \forall t>0.
\]
\end{definition}

\begin{slogan}
  If it starts near, it stays near.
\end{slogan}

\begin{definition}[Quasi-asymptotic stability]
  A fixed point \(x_0\) is \emph{quasi-symptotically stable} if for all \(\varepsilon>0\) such that \(|x-x_0|<\delta\) imples that \(\phi(x)\to x_0\) as \(t\to \infty\).
\end{definition}

\begin{slogan}
  It tends to the fixed point eventually.
\end{slogan}

\begin{eg}\leavevmode
  \begin{itemize}
  \item \(\dot r = 0, dot \theta = 1\): \(\V 0\) is Lyapunov stable (take \(\varepsilon = \delta\)) but not quasi-asymptotic stable.
  \item \(\dot r = r(a-r^2), \dot \theta = \sin^2(\theta/2)\): \(\theta=0,r=1\) is quasi-aymptotically stable but not Lyapunov stable.
  \end{itemize}
\end{eg}

\begin{definition}[Asymptotic stability]
  A fixed piont \(x_0\) is \emph{asymptotically stable} if it is both Lyapunov stable and quasi-asymptotically stable.
\end{definition}

\begin{eg}
  A sink (all \(\lambda_i\) have \(\Re \lambda_i<0\)) is asymptotically stable (just take \(\delta\) small that the linear terms dominate), and clearly sources/saddles are not Lyapunov stable.
\end{eg}

To describe the stability of other invariant sets \(\Lambda\) we define
\[
  N_\delta(\Lambda) := \{x: \exists y\in\Lambda, |x-y|<\delta \}
\]
and say \(\phi_t(x)\to \Lambda\) if
\[
  \inf_{y\in \Lambda}\{|\phi_t(x)-y|\}\to 0 \text{ as } t\to \infty.
\]

\begin{definition}[Stability for an invariant set]
  \(\Lambda\) is Lyapunov stable if for all \(\varepsilon>0\) exists \(\delta>0\) such that \(x\in N_\varepsilon(\Lambda)\), \(\phi_t(x) \in N_\varepsilon(\Lambda)\) for all \(t>0\).

  \(\Lambda\) is quasi-asymptotically stable if exists \(\delta>0\) such that \(x\in N_\delta(\Lambda)\) such that \(\phi_t(x)\to \Lambda\) as \(t\to \infty\).

  \(\Lambda\) is aymptotically stable if it is both Lyapunov and quasi-asymptotically stable.
\end{definition}

\subsection{Lyapunov Functions}

Lyapounov functions allow us to say more about the stability of a fixed point which, without loss of generality, we may take to be at \(x=0\).

\begin{definition}[Lyapunov function]
  A continuously differentiable function \(V:\R^n\to \R\) is a \emph{Lyapunov function} for \(\dot{x} = f(x)\) on a domain \(D\) containing \(\V 0\) if it is
  \begin{itemize}
  \item positive-definite: \(V(\V 0) = 0\) and \(V(x) >0\) for all \(x\neq 0\) in \(D\). Informally, \(\V 0\) is the lowest point.
  \item non-increasing: \(\dot{V} = f\cdot\nabla V \leq 0\) for all \(x\in D\). Informally, it means all trajectories in \(D\) head ``downhill'' or level, but never ``uphill''.
  \end{itemize}
\end{definition}

These properties allow us to prove

\begin{theorem}[Lyapunov's First Theorem]
  If a Lyapunov function exists then \(x=0\) is Lyaponov stable.
\end{theorem}

\begin{proof}
  Wlog assume \(\varepsilon\) is sufficiently small that \(\{|x|\leq\varepsilon\} \subset D\). Let
  \[
    m = \inf \{V(x): |x| = \varepsilon\}.
  \]
  Since \(|x|=\varepsilon\) is compact, the infimum is attained and by the first property above, \(m>0\).

  Let \(C_{m,\varepsilon} = \{x: V(x)<m, |x| < \varepsilon \}\). Then for all \(x\in C_{m,\varepsilon}\), \(\phi_t(x) \in C_{m,\varepsilon}\) for all \(t>0\) as \(V\geq m\) on the boundary.

  Choose \(\delta\) such that \(\{|x|< \delta\} \subseteq C_{m,\varepsilon}\).
\end{proof}

Note that a trajectory can head ``downhill'' and not end up at \(x=0\). But there is a very important constraint:

\begin{theorem}[La Salle's Invariance Principle]
  If \(V\) is a Lyapunov function on a bounded domain \(D\) and \(\mathcal O^+(x) \subseteq D\), then \(\phi_t(x)\) tends to an \emph{invariant} subset of \(\{x: \dot{V} = 0\} \cap D\).
\end{theorem}

\begin{proof}
  \(V(\phi_t(x))\) is monotonically decreasing and bounded below by \(0\). Therefore \(V\to \alpha\) for some \(\alpha\geq0\). \(D\) is compact so the limit set \(\omega(x)\) is non-empty. \(\forall y\in \omega(x)\), \(\exists\{t_n\}\) such that \(\phi_{t_n}(x)\to y\) so \(V(y) = \alpha\) by continuity of \(V\). So \(V(\phi_t(y))=\alpha\) as \(\phi_t(y)\in \omega(x)\). Thus \(\dot{V}(y) = 0\) for all \(y\in\omega(x)\).

  Hence \(\omega(x) \subseteq \{ \dot{V} = 0\}\) and \(\omega(x)\) is invariant (c.f. section 1.4).
\end{proof}

\begin{corollary}
  If \(V\) is a Lyapunov function on a domain \(D\) and the only invariant subset of \(\{\dot{V}=0\}\) is \(\{\V 0\}\) then \(x=0\) is aymptotically stable.
\end{corollary}

\end{document}


% ---
% title: Phase and the Hilbert Transform
% description: A remix of my 2014 TLE tutorial on computing phase responses and
%   how to use them
% short_title: Phase and the Hilbert Transform
% authors:
%   - name: Steve Purves
%     affiliation: curvenote
%     location: La Orotava, Spain
%     curvenote: https://curvenote.com/@stevejpurves
%     is_corresponding: false
% date:
%   year: 2020
%   month: 9
%   day: 8
% tags:
%   - tutorial
%   - exploration
%   - seismic-attributes
%   - phase
%   - python
% oxalink: https://curvenote.com/oxa:RkW3EUemHJbWfgejvqYu/BAflQTB9BBGlfSVT40RN.53
% jtex:
%   version: 1
%   template: null
%   strict: false
%   input:
%     references: main.bib
%     tagged: {}
%   output:
%     path: _build
%     filename: main.tex
%     copy_images: true
%     single_file: false
%   options: {}
% ---

%% https://curvenote.com/oxa:RkW3EUemHJbWfgejvqYu/j4p2ktrUnpNLTYJxNZAq.5

Phase is a useful underlying property of the analytic trace model of seismic data that can be used as both an interpretation aid and a means to calibrate and check interpretations on a given seismic dataset. We introduce the analytical trace model and demonstrate some of its usages. We provide working code in python for computation of the Hilbert Transform using a robust FFT-based method and explore 2 use cases for such computed quantities. Jupyter notebooks used for computation and generation of the figures are included in this project.

%% https://curvenote.com/oxa:RkW3EUemHJbWfgejvqYu/nxoOOSUIjwn60BZbKluN.15

\subsection*{Introduction}

The concept of phase permeates seismic data processing and signal processing in general, but it can be awkward to understand, and manipulating it directly can lead to surprising results. It doesn't help that the word phase is used to mean a variety of things, depending on whether we refer to the propagating wavelet, the observed wavelet, post-stack seismic attributes, or an entire seismic data set. Several publications have discussed the concepts and ambiguities \citep{Roden1999significance, Liner2002Phase, 2002Tutorial}.

%% https://curvenote.com/oxa:RkW3EUemHJbWfgejvqYu/ihBcaiMuiszbc8xSI8bd.20

\begin{figure}[!htbp]
  \centering
  \includegraphics[width=0.7\linewidth]{images/RkW3EUemHJbWfgejvqYu-ihBcaiMuiszbc8xSI8bd-v20.png}

  \caption*{

  }
\end{figure}


\subsection{Example \#2: dependence model between two time series}
\label{S:ExampleDispTemp}

\subsubsection{Data description}

This example uses two synthetic time series that mimics the displacement and temperature data measured on a bridge.
The  Figure~\ref{fig:DataSummaryRaw2}a shows that data points exist between August 2013 and October 2015.
The timestep in the original data is non-uniform; it varies from 1 hour to 25 hours (see Figure~\ref{fig:DataSummaryRaw2}b).
The timestep vector is not identical on each time series.
It means that the time series are not synchronized between each other.
The most frequent (i.e referent) time step is 1 hour for both time series (Section~\ref{SS:NonUniform}).
There is no missing data (\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!NaN!) on the displacement time series, but there are missing data on the temperature time series as indicated by the red crosses on the Figure~\ref{fig:DataSummaryRaw2}c.
Each red cross indicates the presence of a Not a Number (\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!NaN!) value in the time series.
After data synchronization, the time step vectors are identical on each time series (Figure~\ref{fig:DataSummaryDefaultPreProcessed2}).
Both time series are stationary, and they exhibit a level, a yearly and daily periodic pattern as well as an autoregressive pattern.
The periodic patterns observed on the displacement time series is due to the temperature variations observed in the temperature time series.

In this example, we choose to resample the original data in order to have timesteps of 6h instead of 1h.

\begin{figure*}[h!]
\centering
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/raw/ALL_AMPLITUDES.pdf}
\caption{Amplitude}
\end{subfigure}
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/raw/ALL_TIMESTEPS.pdf}
\caption{Timestep}
\end{subfigure}
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/raw/AVAILABILITY.pdf}
\caption{Availability}
\end{subfigure}
\caption{Raw data in the example \#2 where the reference timestep is 1h.}
\label{fig:DataSummaryRaw2}
\end{figure*}

\begin{figure*}[h!]
\centering
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/preprocessed_default/ALL_AMPLITUDES.pdf}
\caption{Amplitude}
\end{subfigure}
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/preprocessed_default/ALL_TIMESTEPS.pdf}
\caption{Timestep}
\end{subfigure}
\begin{subfigure}{\linewidth}
\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/preprocessed_default/AVAILABILITY.pdf}
\caption{Availability}
\end{subfigure}
\caption{Data used in example \#2 after resampling to obtain a reference timestep of 6h.}
\label{fig:DataSummaryDefaultPreProcessed2}
\end{figure*}

\subsubsection{Model description}
\label{SS:ModelConstructionExample2}

The model includes one model class, and the hidden state variables are
\begin{gather*}
\textbf{x}=[x^{\mathtt{LL}}_{\mathtt{D}}, x^{\mathtt{AR}}_{\mathtt{D}}, x^{\mathtt{LL}}_{\mathtt{T}}, x^{\mathtt{P1}\text{,yearly}}_{\mathtt{T}}, x^{\mathtt{P2}\text{,yearly}}_{\mathtt{T}}, x^{\mathtt{P1}\text{,daily}}_{\mathtt{T}} , x^{\mathtt{P2}\text{,daily}}_{T}, x^{\mathtt{AR}}_{\mathtt{T}}],
\end{gather*}
where $\mathtt{D}$ and $\mathtt{T}$ refer to the displacement and temperature time series, respectively.
The periodic patterns observed on the displacement are considered through a dependency of the displacement on the hidden state variables of the periodic  and autoregressive components of the temperature time series (Section~\ref{S:Dependencies}).
The associated model parameters are
\begin{align*}
\bm\theta & =[\sigma_{w, \mathtt{D}}^{\mathtt{LL}}, \phi^{\mathtt{AR}}_{D}, \sigma_{w, \mathtt{D}}^{\mathtt{AR}}, \sigma_{v, \mathtt{D}},  \\
&  \sigma_{w, \mathtt{T}}^{\mathtt{LL}},  p^{\mathtt{P}, \text{yearly}}_{\mathtt{T}}, \sigma_{w, \mathtt{T}}^{\mathtt{P}, \text{yearly}} , p^{\mathtt{P}, \text{daily}}_{\mathtt{T}} , \sigma_{w, \mathtt{T}}^{\mathtt{P}, \text{daily}}, \phi^{\mathtt{AR}}_{\mathtt{T}}, \sigma_{w, \mathtt{T}}^{\mathtt{AR}}, \sigma_{v, \mathtt{T}},\phi^{\mathtt{D}|\mathtt{T}}_{\mathtt{P}_{y}},\phi^{\mathtt{D}|\mathtt{T}}_{\mathtt{P}_{d}},\phi^{\mathtt{D}|\mathtt{T}}_{\mathtt{AR}}].
\end{align*}
The optimized model parameters values computed using the Newton-Raphson algorithm (see~\ref{SS:THModelParameterEstimation}) with a training period of 180 days are
\begin{align*}
 \bm\theta^{\text{*}}& =[0, 0.90, 0.037, 1.94\times10^{-5},  \\
 & 0, 365.2422, 0, 1, 0, 0.98, 0.86, 1.14\times10^{-4}, -0.013, 0.0706, 0.00073 ].
\end{align*}
The estimated initial hidden states mean and covariance values are
\begin{align*}
\bm \mu^{*}_{0} & = [	25.9,-2.55\times10^{-5},5.53,16.3,-0.999,0.263,0.669,3.77 ]^{\intercal}, \text{and} \\
\bm\Sigma^{*}_{0} & = \text{diag}([4.27\times10^{-5},1.68\times10^{-3},0.715,0.338,0.341,6.73\times10^{-5},6.73\times10^{-5},1.81]).
 \end{align*}
The hidden states computed using the estimated model parameters and initial hidden states are presented in Figure~\ref{fig:DISPTEMPSIMOptimizedOptimizedExample2}.

\subsubsection{Run the example from the pre-existing configuration file}
\label{SS:LoadConfigFileEx2}
There is a configuration file CFG\_Example\_DISPTEMP\_optim.m which is located in the ``config\_files'' folder of the OpenBDLM package.
CFG\_Example\_DISPTEMP\_optim.m contains the optimized model parameters and optimized initial hidden states values.
There is also a data file DATA\_Example\_DISPTEMP\_optim.mat that is located in the ``data/mat'' subfolder.
Therefore, it is possible to run the example \#2 by following the steps below while interacting with the \MATLAB{} command line:
\begin{enumerate}
\item Start OpenBDLM. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main('CFG_Example_DISPTEMP_optim.m');!}.
\item Access hidden states estimation menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}.
\item Run the Kalman filter to estimate the hidden states. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.
\item Save and quit. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Q!}.
\end{enumerate}

\subsubsection{Run the example from command line interaction}

The analysis of a new dataset usually requires to start from scratch.
This section explains how to run the example \#2 from scratch, that is, how to load  and resample the data presented in Figure~\ref{fig:DataSummaryRaw2}, configure the model, estimate the model parameters and estimate the hidden states.
This may be done by following steps below while interacting with the \MATLAB{} command line:
\begin{enumerate}
\item Start OpenBDLM. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main;!}.
\item Choose the interactive tool. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!0!}.
\item Enter the project name. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Example_DISPTEMP!}.
\item Disregard generating synthetic data. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!no!}.
\item Load new data. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!0!}.
\item Select from the graphical user interface the data files located in the ``/data/csv/Example\_DISPTEMP/'' folder. The Figure~\ref{fig:DataSummaryRaw2} that represents the raw data should popup on screen.
\item Access the resampling menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!4!}.

\item Resample data to obtain timesteps of 6h (0.25 day). Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!0.25!}. The Figure \ref{fig:DataSummaryDefaultPreProcessed2} should popup on the screen this time for the resampled data.

\item Save and continue. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!7!}. The same figures should popup on the screen again.
\item Select dependency for the time series \#1. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![2]!}.
\item Select dependency for the time series \#2. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![0]!}.
\item Select the number of model classes. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.
\item Select the model block components for time series \#1. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![11 41]!}.
\item Select the model block components for time series \#2. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![11 31 31 41]!}.

\item Access the training period modification menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!13!}.

\item Modify the training period. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.

\item Choose the starting time (day). Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.

\item Choose the end time (day). Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!180!}.

%\item Access hidden states estimation menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}.
%\item Change the state estimation method to UD\footnote{The UD computation is required in this case because of the presence of missing data. See Section~\ref{SS:KFUD} for more details.}. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}.
%\item Return to the main menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!R!}.
\item Access model parameter estimation menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.
\item Start the Newton-Raphson algorithm. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}. Once the algorithm has converged, the optimized model parameters values should be close to the values presented in \S\ref{SS:ModelConstructionExample2}. Note also that it is possible to get slightly different parameter values\footnote{Keep in mind that the optimization may take several minutes. It is possible to abort the analysis here and to load the configuration file called CFG\_Example\_DISPTEMP\_optim.m to load pre-computed values of model parameters, as presented in Section~\ref{SS:LoadConfigFileEx2}.}.
\item Estimate the initial hidden states values. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!2!}.
\item Estimate the hidden states using the Kalman filter. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}. The estimation should be similar to the results presented in Figure~\ref{fig:DISPTEMPSIMOptimizedOptimizedExample2}.
\item Access export menu. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!17!}.
\item Export the current project in a configuration file. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.
\item Save and quit OpenBDLM. Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Q!}.
\end{enumerate}

%\subsection{Step 4: configure the model}
%
%The next step is to configure the model.
%First, the program requests the number of model class.
%In this exemple, the time series data looks stationary and we are not interested in anomaly detection, and therefore we type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}.
%Secondly, because there are several time series, OpenBDLM needs to know if there are dependencies between the time series.
%Typing \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!2!} for the first time series, and \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!0!} for the second time series means that the model will consider the irreversible components (if any) of the second (temperature) time series as covariates to describe the irreversible patterns observed in the first (displacement) time series.
%Then, OpenBDLM asks for the type of block component for each time series.
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![11 41]!} for the displacement time series and \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]![11 31 31 41]!} for the temperature time series.
%The yearly and daily periodic patterns observed in the displacement time series are modelled using the dependence on the periodic components defined for modelling the temperature time series data.
%Note that because an autoregressive component is chosen for the displacement time series data, the time-dependent model error on the displacement is modelled using a dependence on the autoregressive component of the temperature time series data, as well as an independent autoregressive component.
%The  output on \MATLAB{} command window during interactive model configuration is presented in Listing~\ref{LST:OpenBDLMModelConfigureExample2}.
%Type $\dlsh$ to valid.
%The model is then built, a \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!DATA_DISPTEMP.mat! binary data file, a \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!CFG_DISPTEMP.m! configuration file, as well as a \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!PROJ_DISPTEMP.mat! project file are created.
%The OpenBLDM main menu must appear on the \MATLAB{} command window (see Listing~\ref{LST:OpenBDLMMainMenu}).
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Q!} to save and quit.

% \begin{lstlisting}[ frame = single, basicstyle = \mlttfamily \small, caption = { \MATLAB{} command window output during model configuration}, label = LST:OpenBDLMModelConfigureExample2,  float =h!, linewidth=\linewidth, captionpos=b, breaklines=true]
%- Identifies dependence between time series; use [0] to indicate no dependence
%    time serie #1 depends on time series # >> [2]
%
%- Identifies dependence between time series; use [0] to indicate no dependence
%    time serie #2 depends on time series # >> [0]
%
%- How many model classes do you want for each time series?
%     choice >> 1
%
%     ------------------------------------
%          BDLM Component reference numbers
%     ------------------------------------
%     11: Local level
%     12: Local trend
%     13: Local acceleration
%     21: Local level compatible with local trend
%     22: Local level compatible with local acceleration
%     23: Local trend compatible with local acceleration
%     31: Periodic
%     41: Autoregressive process (AR(1))
%     51: Kernel regression
%     61: Level Intervention
%     --------------------------------------
%
%- Identify components for time series #1; e.g. [11 31 41]
%     choice >> [11 41]
%
%- Identify components for time series #2; e.g. [11 31 41]
%     choice >> [11 31 31 41]
%
%     Building model...
%     Saving project...
%     Project saved in saved_projects/PROJ_Example_DISPTEMP.mat.
%     Printing configuration file...
%     Saving data...
%     Database saved in data/mat/DATA_Example_DISPTEMP.mat
%     Configuration file saved in config_files/CFG_Example_DISPTEMP.m.
%\end{lstlisting}

%\subsection{Step 5: open the configuration file}
%
%After the data loading and the model configuration, a configuration file named \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!CFG_Example_DISPTEMP.m! configuration file is automatically created and saved in ``config\_files'' folder.
%Open the configuration file from \MATLAB{} command line by typing  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!edit CFG_Example_DISPTEMP.m!}.
%%The first part of this configuration file as it should appear on the \MATLAB{} editor is shown in Listing~\ref{LST:CFGFileExample1}.
%The Model parameters section of the configuration file shows that the model totalizes 15 model parameters, that is
%\begin{gather*}
%\bm\theta=\{\sigma_{w, \mathtt{D}}^{LL},  \phi^{AR}_{\mathtt{D}}, \sigma_{w,\mathtt{D}}^{AR} ,\sigma_{v,\mathtt{D}},  \\
% \sigma_{w, \mathtt{T}}^{LL}, p^{\text{PD1}}_{\mathtt{T}}, \sigma_{w,\mathtt{T}}^{\text{PD1}} , p^{\text{PD2}}_{T}, \sigma_{w, \mathtt{T}}^{\text{PD2}}, \phi^{AR}_{T}, \sigma_{w, \mathtt{T}}^{AR}, \sigma_{v,\mathtt{T}}, \phi^{\mathtt{D}|\mathtt{T}}_{PD1}, \phi^{\mathtt{D}|\mathtt{T}}_{PD2},  \phi^{\mathtt{D}|\mathtt{T}}_{AR}\}.
%\end{gather*}
%%The default value of the model parameters are assigned  using heuristic knowledge or computed from the data using statistics on the data.
%The default model parameters values are
%\begin{gather*}
%\bm\theta^{\text{default}}=\{0, 0.75, 0.017, 0.0087, \\
%0, 365.24, 0, 1, 0, 0.75, 1.2905, 0.64526, 0.5, 0.5, 0.5 \}.
%\end{gather*}
%%In the same manner, default value for the initial hidden states are assigned using heuristic knowledge or computed using statistics on the data.
%The default initial hidden states mean  and covariance values are
%\begin{align*}
% \bm \mu^{\text{default}}_{0} & = [	25.7  ,	0  ,   	16.7  	, 5     ,	0   ,  	5   ,  	0    , 	0        ]^{\intercal}, \text{and} \\
% \text{diag}(\bm\Sigma^{\text{default}}_{0})  & = [	0.122, 	0.0305,	666,   	666,   	666,   	666,   	666 ,  	167     ],
%\end{align*}
%respectively.
%%$\bm \mu^{\text{default}}_{0} = [	25.7  ,	0  ,   	16.7  	, 5     ,	0   ,  	5   ,  	0    , 	0        ]$, and $\text{diag}(\bm\Sigma^{\text{default}}_{0}) = [	0.122, 	0.0305,	666,   	666,   	666,   	666,   	666 ,  	167     ]$, respectively.
%In the Options section, change \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!misc.options.MethodStateEstimation='kalman'! to \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!misc.options.MethodStateEstimation='UD'!.
%In this specific example, the presence of missing data requires the use of UD computations instead of the standard, default, Kalman computation.
%Note that the choice about UD or Kalman is problem dependent.
%
%\subsection{Step 6: estimate the hidden states}
%
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main('CFG_Example_DISPTEMP.m');!} in the \MATLAB{} command line.
%Once, the main menu appears, type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}, then \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!} to estimate the filtered hidden states using the default model parameters and default initial hidden states values.
%The value of the log-likelihood is $-3800091$.
%The estimated hidden states are presented in Figure~\ref{fig:DISPTEMPSIMDefaultDefaultExample2}.

%\subsection{Step 7: estimate the model parameters from the data}
%
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main('CFG_Example_DISPTEMP.m');!} in the \MATLAB{} command line.
%Once, the main menu appears, type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!}, then \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!} to estimate the model parameters using Newton-Raphson (type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!} to use the Stochastic Gradient instead).
%The model parameters learning procedure should start (see for example Listing~\ref{LST:OpenBLDMModelParameterLearning}).
%Note that, by default, OpenBDLM considers that the parameters $\sigma_{w, \mathtt{D}}^{LL}$, $\sigma_{w, \mathtt{T}}^{LL}$, $p^{\text{PD1}}_{\mathtt{T}}$, $\sigma_{w, \mathtt{T}}^{\text{PD1}}$ , $p^{\text{PD2}}_{\mathtt{T}}$, $\sigma_{w,\mathtt{T}}^{\text{PD2}}$ are known.
%Therefore, there are nine model parameters to be learned from the data in this example.
%The estimation of the model parameters may take several hours.
%Therefore, press combinations \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Ctrl!} + \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!c!} to abort the process.
%Once the algorithm is converged, the optimized model parameters values should be close to  \footnote{Note that it is possible to get slightly different value of parameters with the same performance.}
%\begin{gather*}
% \bm\theta^{\text{*}}=\{0, 0.97, 0.019, 7.42\times10^{-7}, 0, 365.2422, 0, 1, 0, 0.99, 0.43, 2.67\times10^{-5},  \\
% -0.011, 0.0711, 0.000292 \}
%\end{gather*}

%\subsection{Step 8: estimate the hidden states using the optimized model parameters. values}
%
%In the ``examples/Example\_DISPTEMP'' folder, there is a configuration file named \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!CFG_Example_DISPTEMP_optim.m! that contains optimized model parameters estimated using the Newton-Raphson algorithm.
%Copy and paste \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!CFG_Example_DISPTEMP_optim.m! from  the ``examples/Example\_DISPTEMP'' subfolder  to the ``config\_files'' folder.
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main('CFG_Example_DISPTEMP_optim.m');!} in the \MATLAB{} command line to load the configuration file  \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!CFG_Example_DISPTEMP_optim.m!.
%Once the main menu appears, type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}, then \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!} to estimate the filtered hidden states using the optimized model parameters and default initial hidden states values.
%The value of the log-likelihood is now $38085$.
%The estimated hidden states are presented in Figure~\ref{fig:DISPTEMPSIMOptimizedDefaultExample2}.

%\subsection{Step 9: estimate the initial hidden states}
%
%Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main('CFG_Example_DISPTEMP_optim.m');!} in the \MATLAB{} command line.
%Then, type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!2!}, to optimize the initial hidden states value.
%The estimated initial hidden states mean and covariance values are
%\begin{align*}
%\bm \mu^{*}_{0} & = [	 25.9  ,	-0.0595	, 5.45  	, 17.6  ,	-0.934	, 0.678 ,	0.41  ,	2.1]^{\intercal}, \text{and} \\
% \text{diag}(\bm\Sigma^{*}_{0}) & = [	3.71\times10^{-5},	0.000457	, 0.287 	, 0.263 ,	0.265 	,8.14\times10^{-5}	, \\
% & 8.14\times10^{-5}	, 0.71    ],
% \end{align*}
% respectively.
%Once it is done, type  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!3!}, and then  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!1!} to compute the filtered hidden states using the optimized model parameters and optimized initial hidden states.
%The value of the log-likelihood is $38120$.
%The estimated hidden states are presented in Figure~\ref{fig:DISPTEMPSIMOptimizedOptimizedExample2}.

%\begin{figure*}[h!]
%\centering
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/DISP_ObservedPredicted.pdf}
%\caption{Observed and estimated displacement data}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/DISP_LL_1.pdf}
%\caption{Estimated displacement local level component.}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/DISP_AR_2.pdf}
%\caption{Estimated displacement autoregressive component.}
%\end{subfigure}
%\end{figure*}
%\begin{figure*}[h!]
%\ContinuedFloat
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/TEMP_ObservedPredicted.pdf}
%\caption{Observed and estimated temperature data}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/TEMP_LL_1.pdf}
%\caption{Estimated temperature local level component.}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/TEMP_S1_2.pdf}
%\caption{Estimated temperature yearly component (first hidden state)}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/TEMP_S1_4.pdf}
%\caption{Estimated temperature daily component (first hidden state)}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/default/TEMP_AR_6.pdf}
%\caption{Estimated temperature autoregressive component}
%\end{subfigure}
%\caption{Estimated results using OpenBDLM default model parameters and default initial hidden states. The hidden states are estimated from the data presented in Figure~\ref{fig:DataSummaryDefaultPreProcessed2}a. The solid line and shaded area represent the mean and standard deviation of the estimated hidden states, respectively.}
%\label{fig:DISPTEMPSIMDefaultDefaultExample2}
%\end{figure*}

%\begin{figure*}[h!]
%\centering
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/DISP_ObservedPredicted.pdf}
%\caption{Observed and estimated displacement data}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/DISP_LL_1.pdf}
%\caption{Estimated displacement local level component.}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/DISP_AR_2.pdf}
%\caption{Estimated displacement autoregressive component.}
%\end{subfigure}
%\end{figure*}
%\begin{figure*}[h!]
%\ContinuedFloat
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/TEMP_ObservedPredicted.pdf}
%\caption{Observed and estimated temperature data}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/TEMP_LL_1.pdf}
%\caption{Estimated temperature local level component.}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/TEMP_S1_2.pdf}
%\caption{Estimated temperature yearly component (first hidden state)}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/TEMP_S1_4.pdf}
%\caption{Estimated temperature daily component (first hidden state)}
%\end{subfigure}
%\begin{subfigure}{\linewidth}
%\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_default_initialhiddenstate/TEMP_AR_6.pdf}
%\caption{Estimated temperature autoregressive component}
%\end{subfigure}
%\caption{Estimated results using OpenBDLM optimized model parameters and default initial hidden states. The hidden states are estimated from the data presented in Figure~\ref{fig:DataSummaryDefaultPreProcessed2}a. The solid line and shaded area represent the mean and standard deviation of the estimated hidden states, respectively.}
%\label{fig:DISPTEMPSIMOptimizedDefaultExample2}
%\end{figure*}

\begin{figure*}[h!]
\centering
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/DISP_ObservedPredicted.pdf}
\caption{Observed and estimated displacement data}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/DISP_LL_1.pdf}
\caption{Estimated displacement local level component.}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/DISP_AR_2.pdf}
\caption{Estimated displacement autoregressive component.}
\end{subfigure}
\end{figure*}
\begin{figure*}[h!]
\ContinuedFloat
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/TEMP_ObservedPredicted.pdf}
\caption{Observed and estimated temperature data}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/TEMP_LL_1.pdf}
\caption{Estimated temperature local level component.}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/TEMP_S1_2.pdf}
\caption{Estimated temperature yearly component (first hidden state)}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/TEMP_S1_4.pdf}
\caption{Estimated temperature daily component (first hidden state)}
\end{subfigure}
\begin{subfigure}{\linewidth}\centering
\includegraphics[width=0.9\linewidth]{./docfigs/Example_DISPTEMPSIM/optim_param_optim_initialhiddenstate/TEMP_AR_6.pdf}
\caption{Estimated temperature autoregressive component}
\end{subfigure}
\caption{Estimated results using OpenBDLM with the optimized model parameters and initial hidden states. The hidden states are estimated from the data presented in Figure~\ref{fig:DataSummaryDefaultPreProcessed2}a. The solid line and shaded area represent the mean and standard deviation of the estimated hidden states, respectively.}
\label{fig:DISPTEMPSIMOptimizedOptimizedExample2}
\end{figure*}


\documentclass[11pt]{article}
\usepackage{fullpage}
\usepackage{amsmath, amssymb}

\title{An Overview of \\
      \textbf{Fiber Orientation Tools} \\
      { \normalsize \texttt{http://github.com/charlestucker3/Fiber-Orientation-Tools}} }

\author{Charles L.~Tucker III \\
       Department of Mechanical Science and Engineering \\
        University of Illinois at Urbana-Champaign \\
        1206 W.~Green St. \\
        Urbana, IL 61801 \\
        }
\include{defs}  % Macro definitions

\begin{document}
\maketitle

This document summarizes \textbf{Fiber Orientation Tools}, a set of \matlab\ functions for modeling flow-induced fiber orientation in discontinuous fiber composites, and for predicting the resulting mechanical properties.

The tools accompany the book \textit{Fundamentals of Fiber Orientation: Description, Measurement and Prediction} by C. L. Tucker III (Hanser, Munich, 2022), and references to sections, figures, and equations indicate items in the book.

 \matlab\ live scripts that demonstrate the use of various tools are described first, followed by a list of the functions in the toolkit, organized by category.  To see the details of any function, type \texttt{help} followed by the function name in the \matlab\ command window.

\section{Live Scripts with Example Calculations}

The live scripts are arranged topically, following the chapters of the book.

\subsection*{Chapter 2.  Describing Fiber Orientation and Length}

\begin{description}

    \item[OrientationDistributionFunctions.mlx]{creates 3-D orientation distribution functions $\psi(\pv)$ using the Jeffery distribution function, as in Fig.~2.5.  Uses \texttt{A2F} and \texttt{drawPsi}.}

    \item[OrientationTensorExamples.mlx]{calculates orientation tensors for various combinations of $\pv$ vectors.  Uses \texttt{p2A} and follows the examples in Sections~2.3.1 and 2.3.5.}

    \item[EigenvaluesEigenvectors.mlx]{finds eigenvalues and eigenvectors of a second-order orientation tensor, and compares the standard \matlab\ function \texttt{eig} with the \texttt{eigsort} function from this toolkit.}

    \item[ReconstructDiscreteDistributionFcn.mlx]{shows how to find a set of orientation vectors $\pv^i$ and weighting factors $f_i$ to form a discrete approximation of an orientation distribution function, using the Jeffery distribution function, Eqn.~(2.103).  Uses \texttt{A2F} and \texttt{matchA}. }

        \item[A2Faccuracy.mlx]{explains how to control the accuracy of \texttt{A2F}, which finds the deformation gradient tensor $\F$ that will transform an initially isotropic orientation state to a given second-order tensor $\A$, using the deformation form of Jeffery's equation.  \texttt{F2A} does the reverse calculation.}

\end{description}

\subsection*{Chapter 3.  Measuring Fiber Orientation and Length}

\begin{description}

    \item[PlanarSectionMeasurement.mlx]{uses \texttt{thetaphi2A} to compute orientation information for data from a planar section.  Follows Example~3.1.1.}

\end{description}

\subsection*{Chapter 4. Flow Orientation of Single Fibers}

\begin{description}

    \item[JefferyFiberMotion.mlx]{calculates the motion of a single fiber following Jeffery's equation using \texttt{pDot} and \texttt{ode45} (Section~4.2.3).   Jeffery orbits are illustrated, as in Fig.~4.14.}

    \item[JefferyDeformationForm.mlx]{illustrates the use of \texttt{changep}, which implements the deformation form of Jeffery's equation.  Also uses \texttt{randomfibers} to generate a set of $\pv$ vectors that are randomly distributed in all directions, and \texttt{p2A} to determine the initial and final orientation tensors.}

\end{description}

\subsection*{Chapter 5. Flow Orientation of Groups of Fibers}

\begin{description}

        \item[JefferyTensorEqn.mlx]{illustrates the numerical solution of the orientation tensor equation when every fiber follows Jeffery's equation.  This is the example from Section 5.1.2, and uses \texttt{AdotJeffQuad}.}

        \item[SolvePlanarDistnFcn.mlx]{shows how to solve for the planar orientation distribution function $\psi_\phi (\phi, t)$ using \texttt{solvePsi2D}.  See Sections~5.2.1 and 5.3.1.  This script produces Fig.~5.5(a), and illustrates the control of `wiggles' in the finite difference solution using power-law upwinding and/or grid refinement.}

        \item[Solve3DdistnFcn.mlx]{shows how to solve for the 3-D orientation distribution function $\psi (\pv, t)$  using \texttt{solvePsi3D}.  See Sections~5.2.2 and 5.3.2.  This script produces the tensor history in Fig.~5.7, and shows how to display distribution functions as in Fig. 5.6.  This script also shows how to calculate $\psi(\pv, t)$ for anisotropic rotary diffusion models using \texttt{solvePsiARD} (Section~ 5.6).  }

        \item[OrientationTensorEqns.mlx]{uses \texttt{Adot2} together with \texttt{ode45} to solve tensor equations for flow-induced fiber orientation.  The script shows solutions to the Folgar-Tucker equation (Sections~5.3 and 5.4), anisotropic rotary diffusion models (Section~5.6), and slow kinetics models (Section~5.7).}

        \item[FitCI.mlx]{illustrates the use of \texttt{fitCI} to find the interaction coefficient $C_I$ that produces a given steady-state value of $A_{11}$ in simple shear flow for the Folgar-Tucker model.  This script also demonstrates that the choice of closure approximation affects the value of $C_I$.}

        \item[FitARDparams.mlx]{uses \texttt{fitARD} to obtain the ARD parameters that give desired steady-state values of $A_{11}$ and $A_{33}$ in simple shear flow.  Also demonstrates that the steady-state orientation is independent of the kinetic parameter $\kappa$ when an RSC or RPR model is used together with anisotropic rotary diffusion.}

\end{description}

\subsection*{Chapter 6. Suspension Rheology and Flow-Orientation Coupling}

\begin{description}

    \item[FiberSuspensionStress.mlx]{demonstrates the use of \texttt{tauFiber} to find the orientation-dependent stress in a fiber suspension.  Shows how to do the calculations used to generate Fig.~6.4.}

\end{description}

\subsection*{Chapter 7. Fiber Length Degradation during Processing}

\begin{description}

    \item[FiberLengthModel.mlx]{explains the dimensionless version of the Phelps-Tucker fiber length model as implemented in \texttt{solveFLDstar}, and shows the calculations for the example in Fig. 7.4.}

\end{description}

\subsection*{Chapter 8. Mechanical Properties and Orientation}

\begin{description}

    \item[UnidirectionalProperties.mlx]{shows how to calculate the stiffness and thermal expansion of composites with unidirectional fiber orientation using mean-field theories.  The main functions for this are \texttt{mori} for the Mori-Tanaka model, \texttt{lielens} for the Lienlens/double-inclusion model, and \texttt{halpin} for the Halpin-Tsai model.  The functions \texttt{iso2C}, \texttt{C2eng}, and \texttt{inv4} are also used.}

    \item[OrientationAveragedProperties.mlx]{applies orientation averaging to find the properties of a composite with a distribution of fiber orientation.  Both stiffness and thermal expansion are considered, and Voigt averages are computed.  The main functions are \texttt{oravg4} and \texttt{oravg2}.  The script reproduces Fig.~8.5(a) showing elastic modulus vs.\ orientation, and creates a plot of thermal expansion vs.\ orientation similar to Fig.~8.8(a).}

    \item[LaminatedPlateProperties.mlx]{uses classical lamination theory, as implemented in \break \texttt{Clayer2laminate}, to find the tensile and flexural moduli of an injection molded composite whose orientation varies across the thickness.  Partial results from Table~8.4 are reproduced.  A summary of the underlying theory is given in \textbf{LaminationTheory.pdf} in the Documentation folder.}
\end{description}

\section{Functions Listed by Category}

\subsection{Operations on Orientation Tensors}

\begin{description}

    \item[eigsort]{returns the eigenvalues and eigenvectors of a tensor, sorted from largest eigenvalue to smallest.}

    \item[inv4]{finds the tensor inverse of a fourth-order tensor in $6 \times 6$ matrix form.}

    \item[p2A]{converts a set of $\pv$ vectors to second-order and fourth-order orientation tensors, with or without weighting factors.}

    \item[rotate4]{performs a coordinate transformation on a fourth-order tensor.  See Section~A.4.5.}

    \item[tens2vec]{converts a symmetric second-order tensor from $3 \times 3$ matrix form to $6 \times 1$ column vector (contracted) form.  See Section~2.3.5.1.}

    \item[tens2vec4]{converts a symmetric fourth-order tensor from $6 \times 6$ matrix form to $15 \times 1$ column vector form.  This is not discussed in the book, but is used by \texttt{matchA}.}

    \item[thetaphi2A]{returns the second-order orientation tensor corresponding to a set of angles $(\theta, \phi)$ measured from planar section data (Section~3.1.1).  Either the Bay or Konicek weighting functions can be used.}

    \item[transisoA]{returns the full second-order orientation tensor $\A$ and fourth-order orientation tensor $\Afour$ for a transversely isotropic orientation state with given values of $A_{11}$ and $\Afour_{1111}$.}

    \item[vec2tens]{converts a symmetric second-order tensor from $6 \times 1$ column vector form to $3 \times 3$ matrix form.  See Section~2.3.5.1.}

    \item[vec2tens4]{converts a symmetric fourth-order tensor from $15 \times 1$ column vector form to $6 \times 6$ matrix form.  This is not discussed in the book, but is the inverse of \texttt{tens2vec4}.  It can be used to convert fourth-order tensor results from \texttt{solvePsi3D} and \texttt{solvePsiARD} to matrix form.}

\end{description}

\subsection{Flow-Induced Orientation Models}

\begin{description}

    \item[Adot2]{gives the time derivative $\dot{\A}$ as a function of $\A$, $\mathbf{L}$ and orientation model parameters, for a wide range of orientation models.  This is the principal tool used to predict flow-induced orientation.}

    \item[AdotJeffQuad]{gives the time derivative $\dot{\A}$ for the Jeffery model using the quadratic closure.  This is a simplified version of \texttt{Adot2}, used in Section~5.1.2 and Fig.~5.1.}

    \item[Asteady]{finds the steady-state orientation tensor $\A$ for a given velocity gradient $\mathbf{L}$, for any orientation model in \texttt{Adot2}.}

    \item[changep]{finds a set of current orientation vectors $\pv$ using the deformation form of Jeffery's equation, for a given set of initial vectors $\pv'$ and deformation gradient tensor $\F$.}

    \item[closeA4]{uses any of several closure approximations to find the fourth-order orientation tensor $\Afour$ corresponding to a second-order tensor $\A$.  See Section~ 5.4.}

    \item[fitARD]{finds the anisotropic rotary diffusion (ARD) model parameters that achieve given steady-state values of $A_{11}$ and $A_{33}$ in 1--3 simple shear flow.}

    \item[fitCI]{finds the interaction coefficient $C_I$ for the Folgar-Tucker model that achieves a given steady-state value of $A_{11}$ in simple shear flow.}

    \item[pDot]{gives the time derivative $\dot{ \pv}$ of an orientation vector $\pv$ using Jeffery's equation.  See Section~4.2.3.}

    \item[solvePsi2D]{solves for the orientation distribution function $\psi_\phi ( \phi, t)$ for the 2-D version of the Folgar-Tucker model.  See Sections~5.2.1 and 5.3.21}

    \item[solvePsi3D]{solves for the orientation distribution function $\psi( \theta, \phi, t)$ for the 3-D version of the Folgar-Tucker model.  See Sections~5.2.2 and 5.3.2.}

    \item[solvePsiARD]{solves for the orientation distribution function $\psi( \theta, \phi, t)$ for 3-D anisotropic rotary diffusion models.  See Section~5.6.}

    \item[tauFiber]{finds the extra-stress tensor $\btau$ for a fiber suspension, for a given orientation tensor $\A$ and rate of deformation $\D$, Eqn.~(6.29).}

\end{description}

\subsection{Fiber Length Prediction}

\begin{description}

    \item[fldRstar]{returns a matrix $[R^*]$ used in the non-dimensional version of the Phelps-Tucker fiber length model.  This function is not used directly, but is required by \texttt{solveFLDstar}.}

    \item[solveFLDstar]{solves a non-dimensional version of the Phelps-Tucker fiber length model.}

\end{description}

\subsection{Mechanical Property Prediction}

\begin{description}

    \item[C2eng]{finds the engineering constants for a given stiffness tensor $\Cfour$.}

    \item[Clayer2laminate]{finds the laminate stiffness matrices $[A]$, $[B]$, and $[D]$ for a laminate, given the stiffness tensor $\Cfour$ for each layer and the layer thicknesses.  This is used to compute the tensile and bending properties of a composite where the orientation varies across the thickness; see Section~8.4.5.}

    \item[diluteEshelby]{finds the stiffness tensor $\Cfour$ for a dilute composite with unidirectional alignment using Eshelby's equivalent inclusion.  This model is primarily of theoretical interest, and is used in Fig.~8.3.}

    \item[eng2C]{converts the engineering constants for an orthotropic material into a stiffness tensor $\Cfour$.}

    \item[eshtens]{returns the Eshelby tensor $\Efour$ for a spheroidal particle in an isotropic matrix.  The particle can be prolate (fiber-like), spherical, or oblate (disk-like).}

    \item[halpin]{finds the engineering constants, stiffness tensor $\Cfour$, and thermal stress tensor $\bbeta$ for a discontinuous fiber composite with unidirectional fibers using the Halpin-Tsai equations.}

    \item[iso2C]{finds the stiffness tensor $\Cfour$ for an isotropic material with Young's modulus $E$ and Poisson ratio $\nu$.}

    \item[lielens]{returns the stiffness tensor $\Cfour$ and thermal stress tensor $\bbeta$ for a unidirectional composite using the Lielens/double-inclusion model.}

    \item[mori]{returns the stiffness tensor $\Cfour$ and thermal stress tensor $\bbeta$ for a unidirectional composite using the Mori-Tanaka model.}

    \item[oravg2]{computes the orientation average of a transversely isotropic second-order tensor, Eqn.~(8.81).}

    \item[oravg4]{computes the orientation average of a transversely isotropic fourth-order tensor, Eqn.~(8.77).}

\end{description}

\subsection{Reconstruction of Orientation Distribution Functions}

\begin{description}

    \item[A2F]{find the orientation tensor $\A$ for any deformation gradient tensor $\F$ using the deformation form of Jeffery's equation.}

    \item[F2A]{returns the orientation tensor $\A$ for a given deformation gradient tensor $\F$ using Jeffery's model.}

    \item[matchA,]{given a set of orientation vectors $\pv^i$ and weights $f^i$, adjusts the weights to exactly match a given second-order or fourth-order orientation tensor, while minimizing the mean square difference between the original and adjusted weights.  WARNING: This function can return negative values for some weights, usually when the orientation state is highly aligned.  See \texttt{RecontructDiscreteDistributionFcn.mlx} for examples.}

\end{description}

\subsection{Graphics and Utility Functions}

\begin{description}

    \item[drawPsi]{draws a sphere colored by the Jeffery orientation distribution function for a given deformation gradient tensor $\F$.}

    \item[fill3elt]{draws a triangular mesh in three dimensions, colored according to element values.}

    \item[fill3mesh]{draws a triangular mesh in three dimensions, colored according to nodal values.}

    \item[meshcon]{builds the edge connectivity information for a triangular mesh, as needed by \texttt{refinemesh}.}

    \item[p2sph]{converts a set of $\pv$ vectors to the angles $(\theta, \phi)$ in a spherical coordinate system.}

    \item[plot3mesh]{draws the elements of a triangular mesh in three dimensions.}

    \item[plot3nodes]{draws the nodes of a mesh in three dimensions.}

    \item[randomfibers]{generates a set of fiber orientation vectors $\pv$, randomly oriented in three dimensions.}

    \item[refinemesh]{refines a triangular mesh by dividing each initial element into $n^2$ smaller ones.}

    \item[sph2p]{converts a set angles $(\theta, \phi)$ in a spherical coordinate system into unit vectors $\pv$.}

    \item[spheremesh]{generates different types of triangular meshes on a unit sphere, or on half of a sphere.}

    \item[sphTriArea]{finds the area of each triangle in a mesh on the unit sphere.  Each element is treated as a spherical triangle, rather than a planar triangle.}

    \item[surfPsi3D]{colors the surface of a unit sphere according to an orientation distribution function $\psi (\pv)$.  This function is designed to display distribution functions calculated by \texttt{solvePsi3D} and \texttt{solvePsiARD}.}

    \item[weightFrac2volFrac]{converts fiber weight fraction to fiber volume fraction for a two-phase composite.}

\end{description}

\end{document}


\chapter{Introduction}
\todo{regroup into old structure}
We are interested in constructive notions of finiteness, formalised in Cubical
Type Theory~\cite{cohenCubicalTypeTheory2016}.
In this paper we will explore five such notions of finiteness, including their
categorical interpretation, and use them to build a simple proof-search library
facilitated in a fundamental way by univalence.
Along the way we will use the Countdown
problem~\cite{huttonCountdownProblem2002} as an example, and provide a program
which produces verified solutions to the puzzle.
We will also briefly examine countability, and demonstrate its parallels and
differences with finiteness.
\section{The Varieties of Finiteness}
\todo{Make all references parenthetical}
In Section~\ref{finiteness-predicates} we will explore a number of different
predicates for finiteness.
In contrast to classical finiteness, in a constructive setting there are many
predicates which all have some claim to being the formal interpretation of
``finiteness''~\cite{coquandConstructivelyFinite2010}.
The particular predicates we are interested in are organised in
Figure~\ref{finite-classification}: each arrow in the diagram represents a proof
that one predicate can be derived from another.
Each arrow in Figure~\ref{finite-classification} corresponds to a proof of
implication: cardinal finiteness, for instance, with a strict total order,
implies split enumerability (Theorem~\ref{cardinal-to-manifest-bishop}).

\input{figures/finite-classification}

These finiteness predicates differ along two main axes: informativeness, and
restrictiveness.
More ``informative'' predicates have proofs which contain extraneous information
other than the finiteness of the underlying type: a proof of split enumerability
(Section~\ref{split-enumerability}), for instance, comes with a strict total
order on the underlying type.

The ``restrictiveness'' of a predicate refers to how many types it admits into
its notion of ``finite''.
There are strictly more Kuratowski finite (Section~\ref{kuratowski}) types than
there are Cardinally finite (Section~\ref{cardinal-finiteness}).

Proofs coming with extra information is a common theme in constructive
mathematics: often this extra information is in the form of an algorithm which
can do something useful related to the proof itself.
Indeed, our proofs of finiteness here will provide an algorithm to solve the
countdown puzzle.
Occasionally, however, the extra information is undesirable: we may want to
assert the existence of some value \(x : A\) which satisfies a predicate \(P\)
without revealing \emph{which} \(A\) we're referring to.
More concretely, we will need in this paper to prove that two types are in
bijection without specifying a particular bijection.
This facility is provided by Homotopy Type Theory~\cite{hottbook} in the form of
propositional truncation, and it is what allows us to prove the bulk of
propositions in this paper.

For each predicate we will also prove its closure properties (i.e.\ that the
product of two finite sets is finite).
The most significant of these closure proofs is that of closure under \(\Pi\)
(dependent functions) (Theorem~\ref{split-enum-pi}).
\section{Toposes and Finite Sets}
In Section~\ref{topos}, we will explore the categorical interpretation of
decidable Kuratowski finite sets.
The motivation here is partially a practical one: by the end of this work we
will have provided a library for proof search over finite types, and the
``language'' of a topos is a reasonable choice for a principled language for
constructing proofs of finiteness in the style of
QuickCheck~\cite{claessenQuickCheckLightweightTool2011} generators.

Theoretically speaking, showing that sets in Homotopy Type Theory form a topos
(with some caveats) is an important step in characterising the categorical
implications of Homotopy Type Theory, first proven
in~\cite{rijkeSetsHomotopyType2015}. \todo{This reference should be citet not citep}
Our work is a formalisation of this result (and the first such formalisation
that we are aware of).
The proof that decidable Kuratowski finite sets form a \(\Pi\)-pretopos is
additional to that.
\section{Countability Predicates}
After the finite predicates, we will briefly look at the infinite countable
types, and classify them in a parallel way to the finite predicates
(Section~\ref{infinite}).
We will see that we lose closure under function arrows, but we gain it under the
Kleene star (Theorem~\ref{split-countability-sigma}).
\section{Search}
All of our work is formalised in Cubical
Agda~\cite{vezzosiCubicalAgdaDependently2019}: as a result, the constructive
interpretation of each proof is actually a program which can be run on a
computer.
In finiteness in particular, these programs are particularly useful for
exhaustive search.

We will use the countdown problem as a running example throughout the paper: we
will show how to prove that any given puzzle has a finite number of solutions,
and from that we will show how to enumerate those solutions, thereby solving the
puzzle in a verified way.

In Section~\ref{search} we will package up the ``search'' aspect of finiteness
into a library for proof search: similar libraries have been built
in~\cite{fruminFiniteSetsHomotopy2018}
and~\cite{firsovDependentlyTypedProgramming2015}.
Our library differs from those in three important ways: firstly, it is strictly
more powerful, as it allows for search over function types.
Secondly, finiteness proofs also provide equivalence proofs to any other finite
type: this allows transport of proofs between types of the same cardinality.
Finally, through generic programming we provide a simple syntax for stating
properties which mimics that of QuickCheck.
We also ground the library in the theoretical notions of omniscience.
\section{Notation and Background}
We work in Cubical Type Theory~\cite{cohenCubicalTypeTheory2016}, specifically
Cubical Agda~\cite{vezzosiCubicalAgdaDependently2019}.
Cubical Agda is a dependently-typed functional programming language, based on
Martin-Löf Intuitionistic Type Theory, with a Haskell-like syntax.

Being a dependently-typed language, we'll have to be clear about what we mean
when we say ``type'' in Agda.
\begin{definition}[Type]
  We use \(\AgdaDatatype{Type}\) to denote the universe of (small) types.
  The universe level is denoted with a subscript number, starting at 0.
  ``Type families'' are functions into \(\AgdaDatatype{Type}\).
\end{definition}

The are two broad ways to define types in Agda: as an inductive
\(\AgdaKeyword{data}\) type, similar to data type definitions in Haskell, or as
a \(\AgdaKeyword{record}\).
Here we'll define the basic type formers used in MLTT.\@
\begin{definition}[Basic Types]
  The three basic types---often called 0, 1, and 2 in MLTT---here will be
  denoted with their more common names: \(\bot\), \(\top\), and
  \(\mathbf{Bool}\), respectively.
  \begin{multicols}{3}
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{bot}
    \end{agdalisting}

    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{top}
    \end{agdalisting}

    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{bool}
    \end{agdalisting}
  \end{multicols}
\end{definition}
\begin{definition}[The Dependent Sum]
  Dependent sums are denoted with the usual \(\Sigma\) symbol, and has the
  following definition in Agda:

  \begin{center}
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{sigma}
    \end{agdalisting}
  \end{center}
  We will use different notations to refer to this type depending on the
  setting.
  The following four expressions all denote the same type:
  \begin{multicols}{4}
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{sigma-syntax-1}
    \end{agdalisting} \columnbreak
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{sigma-syntax-3}
    \end{agdalisting} \columnbreak
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{sigma-syntax-4}
    \end{agdalisting} \columnbreak
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{sigma-syntax-2}
    \end{agdalisting}
  \end{multicols}\vspace{-1.5\baselineskip}%
  The non-dependent product is a special instance of the dependent.
  We denote a simple pair of types \(A\) and \(B\) as \(A \times B\).
\end{definition}
\begin{definition}[Dependent Product]
  Dependent products (dependent functions) use the \(\Pi\) symbol.
  The three following expressions all denote the same type:
  \begin{multicols}{3}
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{pi-syntax-1}
    \end{agdalisting} \columnbreak
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{pi-syntax-2}
    \end{agdalisting} \columnbreak
    \begin{agdalisting}
      \ExecuteMetaData[agda/Snippets/Introduction.tex]{pi-syntax-3}
    \end{agdalisting}
  \end{multicols}\vspace{-1.5\baselineskip}
  Non-dependent functions are denoted with the arrow (\(\rightarrow\)).
\end{definition}

At this point, as a quick example, we can define the first of our objects for
the countdown transformation: the vector of Booleans for selection.
A vector is relatively simple to define: a vector of zero elements is simply a
unit, a vector of \(n+1\) elements is the product of an element and a vector of
\(n\) elements.
\begin{agdalisting}
  \ExecuteMetaData[agda/Data/Vec/Iterated.tex]{vec-def}
\end{agdalisting}
From this we can see that a vector of \(n\) Booleans has the type
\(\AgdaDatatype{Vec} \; \AgdaDatatype{Bool} \; n\)

Finally, there is one last thing we must define before moving on to the
finiteness predicates: paths.
\begin{definition}[Path Types]\label{path-types}
  The equality type (which we denote with \(\equiv\)) in CuTT is the type of
  Paths\footnotemark.
  The nature and internal structure of Paths is complex and central to how
  Cubical Type Theory ``implements'' Homotopy Type Theory, but those details are
  not relevant to us here.
  Instead, we only need to know that univalence holds for paths, and path types
  do indeed compute in Cubical Agda.
\end{definition}

\footnotetext{%
  Actually, CuTT does have an identity type with similar semantics to the
  identity type in MLTT.\@
  We do not use this type anywhere in our work, however, so we will not consider
  it here.
}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../paper"
%%% End:


\section{Soundness of Refinement Reflection}

We prove Theorem~\ref{thm:safety}
of \S~\ref{sec:types-reflection}
by reduction to Soundness of \undeclang~\citep{Vazou14}.

\begin{theorem}{[Denotations]}~\label{tech:thm:denotations}
If $\hastype{\env}{\prog}{\typ}$ then
$\forall \sto\in \interp{\env}. \applysub{\sto}{\prog} \in \interp{\applysub{\sto}{\typ}}$.
\end{theorem}
\begin{proof}
We use the proof from~\citep{Vazou14-tech} and specifically Lemma 4
that is identical to the statement we need to prove.
%
Since the proof proceeds by induction in the type derivation,
we need to ensure that all the modified rules satisfy the statement.
\begin{itemize}
\item\rtexact
 Assume
 	\hastype{\env}{e}{\tref{v}{\btyp}{\reft_r\land v = e}}.
 By inversion
	\hastype{\env}{e}{\tref{v}{\btyp}{\reft_r}}(1).
 By (1) and IH we get
 $\forall \sto\in \interp{\env}.
   \applysub{\sto}{e} \in \interp{\applysub{\sto}{\tref{v}{\btyp}{\reft_r}}}$.
 We fix a $\sto\in \interp{\env}$
 We get that if \evalsto{\applysub{\sto}{e}}{w},
 then $\evalsto{\applysub{\sto}{\reft_r}\subst{v}{w}}{\etrue}$.
 By the Definition of $=$ we get that
 $\evalsto{w = w}{\etrue}$.
 Since $\evalsto{\applysub{\sto}{(v = e)}\subst{v}{w}}{w = w}$,
 then $\evalsto{\applysub{\sto}{(\reft_r\land v = e)}\subst{v}{w}}{\etrue}$.
 Thus
   $\applysub{\sto}{e} \in \interp{\applysub{\sto}{\tref{v}{\btyp}{\reft_r\land v = e}}}$
  and since this holds for any fixed $\sto$,
 $\forall \sto\in \interp{\env}.
   \applysub{\sto}{e} \in \interp{\applysub{\sto}{\tref{v}{\btyp}{\reft_r\land v = e}}}$.
\item\rtlet
  Assume
	\hastype{\env}{\eletb{x}{\gtyp_x}{e_x}{\prog}}{\typ}.
  By inversion
	\hastype{\env, \tbind{x}{\gtyp_x}}{e_x}{\gtyp_x} (1),
	\hastype{\env, \tbind{x}{\gtyp_x}}{\prog}{\gtyp} (2), and
    \iswellformed{\env}{\typ} (3).
 By IH
	$\forall \sto\in \interp{\env, \tbind{x}{\gtyp_x}}.
	\applysub{\sto}{e_x} \in \interp{\applysub{\sto}{\gtyp_x}}$ (1')
	$\forall \sto\in \interp{\env, \tbind{x}{\gtyp_x}}.
	\applysub{\sto}{\prog} \in \interp{\applysub{\sto}{\gtyp}}$ (2').
 By (1') and by the type of $\efix{}$
	$\forall \sto\in \interp{\env, \tbind{x}{\gtyp_x}}.
	\applysub{\sto}{\efix{x}\ e_x} \in \interp{\applysub{\sto}{\gtyp_x}}$.
 By which,  (2') and (3)
	$\forall \sto\in \interp{\env}.
	\applysub{\sto}{\SUBST{\prog}{x}{\efix{x}\ {e_x}}} \in \interp{\applysub{\sto}{\gtyp}}$.
%% \NV{CHECK}
\item\rtreflect
  Assume
  \hastype{\env}{\erefb{f}{\gtyp_f}{e}{\prog}}
			    {\typ}.
  By inversion,
    \hastype{\env}{\eletb{f}{\exacttype{\gtyp_f}{e}}{e}{\prog}}
			     {\typ}.
  By IH,
 	$\forall \sto\in \interp{\env}.
	\applysub{\sto}{\eletb{f}{\exacttype{\gtyp_f}{e}}{e}{\prog}} \in \interp{\applysub{\sto}{\gtyp}}$.
  Since denotations are closed under evaluation,
	$\forall \sto\in \interp{\env}.
	\applysub{\sto}{\erefb{f}{\exacttype{\gtyp_f}{e}}{e}{\prog}} \in \interp{\applysub{\sto}{\gtyp}}$.

\item\rtfix
  In Theorem 8.3 from~\citep{Vazou14-tech} (and using the textbook proofs from~\citep{PLC})
  we proved that for each type $\typ$, $\efix{}_\typ \in \interp{(\typ \rightarrow \typ) \rightarrow \typ}$.
\end{itemize}
\end{proof}

\begin{theorem}{[Preservation]}
If \hastype{\emptyset}{\prog}{\typ}
       and $\evalsto{\prog}{w}$ then $\hastype{\emptyset}{w}{\typ}$.
\end{theorem}
\begin{proof}
In~\citep{Vazou14-tech} proof proceeds by iterative application
of Type Preservation Lemma 7.
%
Thus, it suffices to ensure Type Preservation in \corelan, which
it true by the following Lemma.
\end{proof}

\begin{lemma}
If \hastype{\emptyset}{\prog}{\typ}
       and $\evals{\prog}{\prog'}$ then $\hastype{\emptyset}{\prog'}{\typ}$.
\end{lemma}
\begin{proof}
Since Type Preservation in \undeclang is proved by induction on the type derivation tree,
we need to ensure that all the modified rules satisfy the statement.
\begin{itemize}
\item\rtexact
 Assume
 	\hastype{\emptyset}{\prog}{\tref{v}{\btyp}{\reft_r\land v = \prog}}.
 By inversion
	\hastype{\emptyset}{\prog}{\tref{v}{\btyp}{\reft_r}}.
 By IH we get
	\hastype{\emptyset}{\prog'}{\tref{v}{\btyp}{\reft_r}}.
 By rule \rtexact we get
 	\hastype{\emptyset}{\prog'}{\tref{v}{\btyp}{\reft_r\land v = \prog'}}.
 Since subtyping is closed under evaluation, we get
 	\issubtype{\emptyset}{\tref{v}{\btyp}{\reft_r\land v = \prog'}}
 	                {\tref{v}{\btyp}{\reft_r\land v = \prog}}.
 By rule \rtsub we get
 	\hastype{\emptyset}{\prog'}{\tref{v}{\btyp}{\reft_r\land v = \prog}}.

\item\rtlet
  Assume
	\hastype{\emptyset}{\eletb{x}{\gtyp_x}{e_x}{\prog}}{\typ}.
 By inversion,
   \hastype{\tbind{x}{\gtyp_x}}{e_x}{\gtyp_x}  (1),
   \hastype{\tbind{x}{\gtyp_x}}{\prog}{\gtyp} (2), and
   \iswellformed{\env}{\typ} (3).
 By rule \rtfix
   \hastype{\tbind{x}{\gtyp_x}}{\efix{x}\ {e_x}}{\gtyp_x}  (1').
 By (1'), (2) and Lemma 6 of~\citep{Vazou14-tech}, we get
   \hastype{}{\SUBST{\prog}{x}{\efix{x}\ {e_x}}}{\SUBST{\gtyp}{x}{\efix{x}\ e_x}}.
 By (3)
   $ \SUBST{\gtyp}{x}{\efix{x}\ e_x} \equiv \gtyp$.
 Since
   $\prog' \equiv \SUBST{\prog}{x}{\efix{x}\ {e_x}}$,
 we have
 \hastype{\emptyset}{\prog'}{\gtyp}.

\item\rtreflect
  Assume
	\hastype{\emptyset}{\erefb{x}{\gtyp_x}{e_x}{\prog}}{\typ}.
 By double inversion, with $\gtyp_x' \equiv \exacttype{\gtyp_x}{e_x} $;
   \hastype{\tbind{x}{\gtyp_x'}}{e_x}{\gtyp_x'}  (1),
   \hastype{\tbind{x}{\gtyp_x'}}{\prog}{\gtyp} (2), and
   \iswellformed{\env}{\typ} (3).
 By rule \rtfix
   \hastype{\tbind{x}{\gtyp_x'}}{\efix{x}\ {e_x}}{\gtyp_x'}  (1').
 By (1'), (2) and Lemma 6 of~\citep{Vazou14-tech}, we get
   \hastype{}{\SUBST{\prog}{x}{\efix{x}\ {e_x}}}{\SUBST{\gtyp}{x}{\efix{x}\ e_x}}.
 By (3)
   $ \SUBST{\gtyp}{x}{\efix{x}\ e_x} \equiv \gtyp$.
 Since
   $\prog' \equiv \SUBST{\prog}{x}{\efix{x}\ {e_x}}$,
 we have
 \hastype{\emptyset}{\prog'}{\gtyp}.

\item\rtfix
  This case cannot occur, as $\efix{}$ does not evaluate to any program.
\end{itemize}
\end{proof}