%%% exercise 05 %%%
\documentclass{article}
\usepackage[margin=1in]{geometry}
\usepackage{amsmath, amssymb, amsfonts, enumitem, fancyhdr, tikz}
% get rid of paragraph indent
\setlength{\parindent}{0 pt}
% allow section.equation numbering
\numberwithin{equation}{section}
% allows you to copy-paste code segments. requires pygments to be installed
% natively, i.e. not just in a Python venv! for example, on WSL Ubuntu you
% need to sudo apt-get install python3-pygments (unfortunately, the version
% will be a bit dated) and cannot rely on your venv Pygments version.
\usepackage{minted}
% alternative to minted that does not require Python, LaTeX only. listings is
% however disgusting out of the box and some setup is required.
\usepackage{listings, xcolor}
% makes clickable links to sections
\usepackage{hyperref}
% make the link colors blue, as well as cite colors. urls are magenta
\hypersetup{
    colorlinks, linkcolor = blue, citecolor = blue, urlcolor = magenta
}
% fancy pagestyle so we can use fancyhdr for fancy headers/footers
\pagestyle{fancy}
% add logo in right of header. note that you will have to adjust logo path!
\fancyhead[R]{\includegraphics[scale = 0.15]{../bac_logo1.png}}
% don't show anything in the left and center header
\fancyhead[L, C]{}
% give enough space for logo by reducing top margin height, head separator,
% increasing headerheight. see Figure 1 in the fancyhdr documentation. if
% \topmargin + \headheight + \headsep = 0, original text margins unchanged.
\setlength{\topmargin}{-60 pt}
\setlength{\headheight}{50 pt}
\setlength{\headsep}{10 pt}
% remove decorative line in the fancy header
\renewcommand{\headrulewidth}{0 pt}

% title, author + thanks, date
\title{Exercise 5}
\author{Derek Huang\thanks{NYU Stern 2021, BAC Advanced Team.}}
\date{June 6, 2021\thanks{Original version released on March 30, 2021.}}

% shortcut links. the % characters strip extra spacing.
\newcommand{\pytest}{\href{https://docs.pytest.org/en/stable/}{pytest}}
\newcommand{\minimize}{%
    \href{%
        https://docs.scipy.org/doc/scipy/reference/generated/%
        scipy.optimize.minimize.html%
    }{\texttt{scipy.optimize.minimize}}%
}
% don't wanna keep typing this out
\newcommand{\tr}{\operatorname{tr}}
\newcommand{\npinv}{%
    \href{%
        https://numpy.org/doc/stable/reference/generated/numpy.linalg.inv.html%
    }{\texttt{numpy.linalg.inv}}%
}
\newcommand{\pdb}{%
    \href{https://docs.python.org/3/library/pdb.html}{\texttt{pdb}}%
}

\begin{document}

\maketitle
% need to include this after making title to undo the automatic
% \thispagestyle{plain} command that is issued.
\thispagestyle{fancy}

\section{Introduction}

The goal of this exercise is to implement a linear discriminant classifier,
computing the sample covariance matrix using a maximum likelihood estimate
with optional shrinkage.

\section{Instructions}

\subsection{General}

The \texttt{exercise\_05.py} file contains a skeleton for the
\texttt{LinearDiscriminantAnalysis} class, unit tests, and \pytest{} fixtures.
Your job is to finish implementing the \texttt{LinearDiscriminantAnalysis}
class's \texttt{fit} and \texttt{score} methods by replacing the
\texttt{\#\#\# your code goes here \#\#\#} comment blocks with appropriate
Python code.

\medskip

Your code \textbf{must} be written in the areas marked by these blocks. Do
\textbf{not} change any of the pre-written code. The exercise is complete
$ \Leftrightarrow $ \texttt{pytest /path/to/exercise\_05.py} executes with
zero test failures. Note that attributes ending with \texttt{\_}, ex.
\texttt{coef\_}, are created \textbf{during} the fitting process.

\subsection{Implementing \texttt{fit}}

The class prior estimates must be assigned to the local variable
\texttt{priors}, the class mean estimates must be assigned to the local
variable \texttt{means}, and the covariance matrix estimate must be assigned
to the local variable \texttt{cov}. At the end of the \texttt{fit} method,
\texttt{priors} is assigned to \texttt{self.priors\_}, \texttt{means} is
assigned to \texttt{self.means\_}, and \texttt{cov} is assigned to
\texttt{self.covariance\_}.

\subsection{%
    Computing \texttt{priors\_}, \texttt{means\_}, \texttt{covariance\_}%
}

The estimates for the class priors and class means should be computed via
maximum likelihood. Note that the shape of \texttt{means\_} is specified in
the docstring to be \texttt{(n\_classes, n\_features)}. The covariance matrix
estimate $ \hat{\mathbf{\Sigma}} \succeq \mathbf{0} \in
\mathbb{R}^{d \times d} $ is such that for $ \alpha \in [0, 1] $ we have
\begin{equation} \label{cov_est}
    \hat{\mathbf{\Sigma}} \triangleq \alpha\frac{\tr(\mathbf{S})}{d}\mathbf{I}
        + (1 - \alpha)\mathbf{S}
\end{equation}

Here $ \mathbf{S} \succeq \mathbf{0} \in \mathbb{R}^{d \times d} $ is the
maximum likelihood estimate for the covariance matrix and
$ \tr(\mathbf{S}) $ is its trace, i.e.
\begin{equation*}
    \tr(\mathbf{S}) = \sum_{i = 1}^ds_{ii}
\end{equation*}

Note that in this context, $ \tr(\mathbf{S}) / d $ is the average of the
input features' variances. In practice, other \textit{shrinkage estimators}
may be used, especially when $ d $ is much larger than $ N $, for example
the \href{http://www.ledoit.net/ole1a.pdf}{Ledoit-Wolf}\footnote{
    In portfolio optimization, Ledoit-Wolf instead refers to
    \href{http://www.ledoit.net/honey.pdf}{%
        a particular constant correlation shrinkage estimator%
    }.
} and
\href{https://arxiv.org/pdf/0907.4698.pdf}{%
    oracle approximating shrinkage%
} estimators, which are beyond the scope of our introductory coverage.

\subsection{Implementing \texttt{score}}

The \texttt{score} method of the \texttt{LinearDiscriminantAnalysis} class
computes the accuracy of the predictions. Given parameters $ \theta $,
classification function $ F_\theta $ (the classifier), and data
$ \mathcal{D} \triangleq \{(\mathbf{x}_1, y_1), \ldots (\mathbf{x}_N, y_N)\} $,
where the $ y_k $ values may either be numeric or class labels, the accuracy
$ \mathcal{A}_\theta $ of the model on the data $ \mathcal{D} $ is such that
\begin{equation*}
    \mathcal{A}_\theta(\mathcal{D}) = \frac{1}{|\mathcal{D}|}
        \sum_{(\mathbf{x}, y) \in \mathcal{D}}\mathbb{I}_{\{y\}}\left(
            F_\theta(\mathbf{x})
        \right)
\end{equation*}

Note that $ \operatorname{im}\mathcal{A}_\theta = [0, 1] $, so for
data $ \mathcal{D} $, $ \mathcal{A}_\theta(\mathcal{D}) $ is the
fraction of examples the model correctly classified.

\subsection{Tips}

\begin{enumerate}
    \item
    Carefully read the \texttt{LinearDiscriminantAnalysis} docstrings and
    review slide 8.

    \item
    In the \texttt{fit} method, don't forget to either assign your covariance
    matrix estimate to a local variable named \texttt{cov} or replace the
    variable name passed to the \npinv{} call with the name of the local
    variable holding a reference to the covariance matrix estimate.

    \item
    In the \texttt{score} method, you should first call the \texttt{predict}
    method and use it get predicted labels.

    \item
    Use NumPy functions whenever possible for efficiency, brevity, and ease
    of debugging.

    \item
    Invoke \pytest{} with the \texttt{--pdb} flag to start \pdb, the Python
    debugger. Doing so allows you to inspect the variables in the current
    call frame and look more closely at what went wrong.
\end{enumerate}

\end{document}


%! Author = tstreule

\section{Potentiometric Biosensors}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Redox Reaction}
%
\textbf{oxidation}: $e^-$ donor (\textit{anode}) \qquad
\textbf{reduction}: $e^-$ acceptor (\textit{cathode})

\formtex{Chemical reaction}{\ce{A*ox + B*X + z*e^- <=>[$k_{red}$][$k_{ox}$] C*red + D*Y}}
\vspace{-.5mm}
\formbox{reaction quotient}{
    Q = \mathrm{\frac{a\ped{ox}^A \;\cdot\; a\ped{X}^B}{a\ped{red}^C \;\cdot\; a\ped{Y}^D}}
}
%\textcolor{gray}{$= \Big(\prod\limits_j a_j^{v_j}\Big)$}
\begin{tabular}{@{$\bullet\;$}l @{\quad$\bullet\;$}l}
    $\mathrm{a}\ped{ion} = r\ped{ion} [\mathrm{ion}]/\unitfrac[1]{mol}{l}$ &
    $\mathrm{a}\ped{solids} = 1$\\
    $\mathrm{a}\ped{gas} = p\ped{gas}/\unit[1.013]{bar}$ &
    $[\ce{H2O}] = 1$
\end{tabular}

\formula{Standard conditions}{
    T = \SI{1}{\degreeCelsius}, \quad
    p = \SI{101.3}{\kilo\pascal} = \SI{1.013}{\bar}
}
\formula{\centering ``STP''}{
    [\mathrm{ion}] \equiv c\ped{ion} = \unitfrac[1]{mol}{l}, \quad
    r = 1 \text{ ``activity coeff.''}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Electrochemistry}
%
\formtex{Dynamic equi.}{no net charge over time ($k_1 = k_{-1}$)}
\formula{Chemical potential}{\mu_j = \big( \pderiv{G}{n_j} \big)_{p,T,n'}}
\formula{Equilibrium}{\mu_A = \mu_B}
\quad general: $\sum\limits\ped{prod}v_j\mu_j = \sum\limits\ped{react}v_j\mu_j$
\vspace{-.5mm}
\formula{Chemical potential}{\mu\ped{redox}\equiv E\ped{\emph{F},redox}\equiv E^*}
%\quad where \quad $D\ped{red}(\lambda,E^*) = D\ped{ox}(\lambda,E^*)$
\formbox{Equilibrium}{\bar\mu_A = \bar\mu_B}
\quad $\bar\mu_j = \mu_j^0 + z_jF\Delta\phi$

\formula{\textbf{Contact potential}}{\Delta\phi
    = V\ped{in}-V\ped{out} = \frac{k\ped{B}T}{Q} \ln\left(\frac{[C]\ped{out}}{[C]\ped{in}}\right)
}
\formula{~}{\phantom{\Delta\phi}
    = -\frac{\Delta_rG}{zF}
    = \frac{1}{zF} \Big( \sum\limits\ped{ox} v_j\mu_j - \sum\limits\ped{red} v_j\mu_j + z\mu_e \Big)
}
\formbox{Nernst eq., $\Delta\phi$}{E {=} E^0 {-} \frac{\unit[59]{mV}}{z} \log_{10}Q}
\textcolor{gray}{\footnotesize $\frac{RT}{zF}\ln Q = \frac{2.303 RT}{zF}\log_{10}Q$}
\formtex{~}{$E\ped{cell}=E_1-E_2$ \quad or \quad let $E_1 \overset{!}{=} E_2 \to \mathrm{pH}=\ldots$}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Ion-selective Electrodes \textnormal{(ISE)}}
%
Sensor is seperated to solution through a \ce{H+} permeable glass.
\formbox{pH electrode}{\mathrm{pH} = -\log_{10} a\ped{\ce{H+}} = \frac{K'-\Delta\phi}{\unit[0.059]{V}}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Bioenzymatic Electrodes}
%
\formtex{Find out how much}{\fbox{\ce{substrate + X + ... ->[enzyme] product + Y + ...}}}
\formtex{of an enzyme was}{Detect \textbf{``a lot''} \ce{X}}
\formtex{initially present}{\hfill$\leftrightarrow$ \textbf{``very few''} \ce{substrate} was initially present}


\section*{Notes Week 8}

\begin{itemize}

    \item A \definition{loop} is an edge that connects a node to itself. Mostly relevant to directed graphs \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \draw (1) to [out=180,in=270,looseness=5] (1);
    \end{tikzpicture}

    \item A \definition{simple path} is a path where all vertices are distinct except possibly the first and last. \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \draw (1) -- (2);
        \draw (3) -- (4);
        \draw (2) -- (3);
    \end{tikzpicture}

    \item A \definition{cycle} is a path that starts and ends on the same vertex.

    \item \definition{Acyclic} graphs contain no cycles.

    \item \definition{DAG}: Directed Acyclic Graph

    \item \definition{Strongly} connected graphs are ones where any vertex has a path to any other vertex; \definition{Weakly} connected graphs have vertices without paths to other vertices.

    \item A \definition{Bipartite Graph} is one we can separate vertices into two groups where edges only travel between groups. \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \node[main] (5) [below right of = 1] {$x_5$};
        \node[main] (6) [below right of = 2] {$x_6$};
        \node[main] (7) [below right of = 3] {$x_7$};
        \draw (1) -- (5);
        \draw (2) -- (5);
        \draw (2) -- (6);
        \draw (3) -- (6);
        \draw (3) -- (7);
        \draw (4) -- (7);
    \end{tikzpicture}

    \item Formally, a \definition{Bipartite Graph} is $BG = (A \cup B, E)$ such that every edge connects an element of A with an element B.

    \item A complete Bipartite graph is one where all nodes in group B are connected to all nodes in group B.

    \item A \definition{Tree} is any connected, undirected, acyclic graph.

\end{itemize}

\pagebreak

\section*{Depth-First $vs$ Breadth-First Searches}

\begin{tabularx}{\textwidth}{X X}

    \definition{Depth-First Search}

    \begin{enumerate}

        \item Push Start Vertex
        \item Mark start vertex as visited
        \item Loop until stack empty
        \begin{enumerate}
            \item Pop $U$
            \item Mark $U$ as visited
            \item For each of $U$ unvisited neighbors, push them
        \end{enumerate}

    \end{enumerate}

    &

    \definition{Breadth-First Search}

    \begin{enumerate}

        \item Enqueue Start Vertex
        \item Mark start vertex as visited
        \item Loop until queue empty
        \begin{enumerate}
            \item Dequeue $U$
            \item Mark $U$ as visited
            \item For each of $U$ unvisited neighbors, Enqueue them
        \end{enumerate}

    \end{enumerate}

\end{tabularx}

\begin{itemize}

    \item Both BFS and DFS are $O(V + E)$
    \begin{itemize}
        \item Vertices: $V = n$
        \item Edges: $E = n(n-1)/2$ at most in a complete, undirected graph
        \item Therefore: $O(n + n^2) = O(n^2)$ as an upper bound, but is dependet on
    \end{itemize}

    \item Under what circumstances would BFS or DFS run faster?

    \item Well, neither? Closer on graph favors BFS.

\end{itemize}

\section*{Topological Sort}

\begin{itemize}

    \item An ordering of vertices in a directed, acyclic graph such that, if there is a path, from vertex $A$ to vertex $B$, then vertex $B$ appears after vertex $A$ in the order. \\

\end{itemize}

\begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \draw[->] (1) -- (2);
        \draw[->] (3) -- (4);
        \draw[->] (2) -- (3);
\end{tikzpicture}

\begin{itemize}

    \item Topological sorts are not guaranteed to be unique. There could be many correct orders.

    \item Examples: Family Tree, Course Prerequisites

    \item Assumptions:
    \begin{enumerate}
        \item Indegree for each vertex is stored
        \item Edges stored in an adjacency list
    \end{enumerate}

\end{itemize}

\pagebreak

\begin{algorithm}
    \caption{Topological Sort 1 $O(n^2)$}
    \begin{algorithmic}
        \While{Graph is not empty}
            \State Find any vertex with no incoming edges
            \State Display Vertex
            \State Remove it, and its edges, from the graph
        \EndWhile
    \end{algorithmic}
\end{algorithm}

\begin{algorithm}
    \caption{Topological Sort 2}
    \begin{algorithmic}
        \State Maintain a queue of vertices with indegree $0$
        \While Queue is not empty
            \State Dequeue a vertex
            \State Display the Vertex
            \State Remove it and its edges from the graph
            \State Update remaining Vertices, enqueueing any whose indgree is $0$
        \EndWhile
    \end{algorithmic}
\end{algorithm}

\begin{itemize}
    \item Each vertex enqueued and dequeued once $\rightarrow O(n^2)$
    \item Each edge gets removed once $\rightarrow n^2$ potential
    \item Therefore, Topological Sort 2 is $O(V+E)$
    \item TS2 depends on number of edges, whereas TS1 depends on nodes
    \item TS2 approaches TS1 only when the graph is complete, or close to it
\end{itemize}

\section*{The Selection Problem}

Find the $k^{th}$ largest number in a set of $n$ numbers.

\begin{itemize}

    \item \definition{$i^{th}$ order statistic}: the $i^{th}$ smallest term in a set of $n$ elements
    \item Recall week 1 notes; best algorithm was $O(nlog(n))$
    \item It's possible to make this $O(n)$
    \begin{itemize}
        \item Pick a good pivot similar to QuickSort
        \item Then like Binary Search, use the half that's relevant
        \item The dividing runs in $(log(n))$ but the pivot search runs in $O(n)$
    \end{itemize}

\end{itemize}

\end{document}


\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage[osf]{libertine}
\usepackage[scaled=0.8]{beramono}
\usepackage[margin=1.5in]{geometry}
\usepackage{url}
\usepackage{booktabs}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{nicefrac}
\usepackage{microtype}
\usepackage{bm}

\usepackage{sectsty}
\sectionfont{\large}
\subsectionfont{\normalsize}

\usepackage{titlesec}
\titlespacing{\section}{0pt}{10pt plus 2pt minus 2pt}{0pt plus 2pt minus 0pt}
\titlespacing{\subsection}{0pt}{5pt plus 2pt minus 2pt}{0pt plus 2pt minus 0pt}

\usepackage{pgfplots}
\pgfplotsset{
  compat=newest,
  plot coordinates/math parser=false,
  tick label style={font=\footnotesize, /pgf/number format/fixed},
  label style={font=\small},
  legend style={font=\small},
  every axis/.append style={
    tick align=outside,
    clip mode=individual,
    scaled ticks=false,
    thick,
    tick style={semithick, black}
  }
}

\pgfkeys{/pgf/number format/.cd, set thousands separator={\,}}

\usepgfplotslibrary{external}
\tikzexternalize[prefix=tikz/]

\newlength\figurewidth
\newlength\figureheight

\setlength{\figurewidth}{8cm}
\setlength{\figureheight}{6cm}

\newlength\squarefigurewidth
\newlength\squarefigureheight

\setlength{\squarefigurewidth}{7cm}
\setlength{\squarefigureheight}{6cm}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}

\newcommand{\acro}[1]{\textsc{\MakeLowercase{#1}}}
\newcommand{\given}{\mid}
\newcommand{\mc}[1]{\mathcal{#1}}
\newcommand{\data}{\mc{D}}
\newcommand{\trans}{^\top}
\newcommand{\inv}{^{-1}}
\newcommand{\intd}[1]{\,\mathrm{d}{#1}}
\newcommand{\mat}[1]{\bm{\mathrm{#1}}}
\renewcommand{\vec}[1]{\bm{\mathrm{#1}}}

\DeclareMathOperator{\var}{var}

\begin{document}

{\large \textbf{CSE 515T (Spring 2015) Midterm solutions}}
\begin{enumerate}
\item
  Consider two coins with unknown bias $\theta_1$ and $\theta_2$,
  respectively.  We place independent, identical beta priors on these
  quantities:
  \begin{equation*}
    p(\theta_1) = \mc{B}(\theta_1; 2, 2);
    \qquad
    p(\theta_2) = \mc{B}(\theta_2; 2, 2).
  \end{equation*}
  Imagine someone flips both coins and tells you that \emph{exactly
    one} of the outcomes (but not which) was a ``head.''  Thus the
  observation was either HT or TH, but you are not told which.  The
  below expressions are conditioned on ``H'' to indicate this
  observation.
  \begin{itemize}
  \item
    Give an expression for the posterior of the first coin's bias
    given this observation, $p(\theta_1 \given \text{H})$.  Simplify
    the result as much as you can.  Plot the prior and the posterior
    for $\theta_1$ over the interval $\theta_1 \in (0, 1)$.
  \item
    Give an expression for the joint posterior $p(\theta_1, \theta_2
    \given \text{H})$. Plot the joint prior, the likelihood, and the
    joint posterior as three separate heat maps over the unit square
    $(\theta_1, \theta_2) \in (0, 1)^2$.  Use a grid with at least 100
    values along each of the two $\theta$ axes.
  \item
    Summarize what the observation taught us about the bias of the
    coins.
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

The outcome of the unseen experiment was either HT or TH.  These are
mutually exhaustive and independent events, so we may use the sum
rule to derive the desired posterior:
\begin{equation*}
  p(\theta_1 \given \text{H})
  =
  \Pr(\text{HT})p(\theta_1 \given \text{HT})
  +
  \Pr(\text{TH})p(\theta_1 \given \text{TH})
  .
\end{equation*}
Notice that both $p(\theta_1 \given \text{HT})$ and $p(\theta_1 \given
\text{TH})$ can be computed explicitly as updated beta distributions,
now that the coins in the outcomes have been identified:
\begin{align*}
  p(\theta_1 \given \text{HT})
  &=
  \mc{B}(\theta_1; 3, 2)
  \\
  p(\theta_1 \given \text{TH})
  &=
  \mc{B}(\theta_1; 2, 3).
\end{align*}

What is $\Pr(\text{HT})$?  It can be calculated explicitly, but a
simpler approach is to appeal to symmetry between the coins to
conclude $\Pr(\text{HT}) = \Pr(\text{TH}) = \nicefrac{1}{2}$.  Thus
\begin{equation*}
  p(\theta_1 \given \text{H})
  =
  \tfrac{1}{2}
  \bigl(
  p(\theta_1 \given \text{HT}) +
  p(\theta_1 \given \text{TH})
  \bigr)
  =
  \tfrac{1}{2}
  \bigl(
  \mc{B}(\theta_1; 3, 2) +
  \mc{B}(\theta_1; 2, 3)
  \bigr)
  .
\end{equation*}
We can simply this expression further.  The posterior is proportional
to
\begin{equation*}
  p(\theta_1 \given \text{H})
  \propto
  \theta_1^2 (1 - \theta_1)
  +
  \theta_1 (1 - \theta_1)^2
  =
  \theta_1(1 - \theta_1)
  \propto
  \mc{B}(\theta_1; 2, 2).
\end{equation*}
Therefore the distribution of $\theta_1$ has not changed given our
observation!  The prior (and posterior!) for $\theta_1$ is plotted
in Figure \ref{problem_1_prior_1}.

\begin{figure}
  \centering
  \input{figures/problem_1_prior_1}
  \caption{The prior and posterior (given the observation H) of
    $\theta_1$.}
  \label{problem_1_prior_1}
\end{figure}

There are two ways to compute the joint posterior over $(\theta_1,
\theta_2)$: the easy way and the hard way.  The easy way is to use the
sum rule again to write
\begin{align*}
  p(\theta_1, \theta_2 \given \text{H})
  &=
  \Pr(\text{HT})
  p(\theta_1, \theta_2 \given \text{HT})
  +
  \Pr(\text{TH})
  p(\theta_1, \theta_2 \given \text{TH})
  \\
  &=
  \tfrac{1}{2}
  \mc{B}(\theta_1; 3, 2)
  \mc{B}(\theta_2; 2, 3)
  +
  \tfrac{1}{2}
  \mc{B}(\theta_1; 2, 3)
  \mc{B}(\theta_2; 3, 2).
\end{align*}

If we go with the hard way, we begin by computing the joint prior.  By
independence, we have:
\begin{equation*}
  p(\theta_1, \theta_2)
  =
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{equation*}
To derive the likelihood, we again note that our observation could
have been generated by two mutually independent events: HT or TH.
Given $\theta_1$ and $\theta_2$, the total probability of these
events is:
\begin{equation*}
  \Pr(\text{H} \given \theta_1, \theta_2)
  =
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2;
\end{equation*}
the first term accounts for HT and the second term for TH.  The
posterior is now:
\begin{align*}
  p(\theta_1, \theta_2 \given \text{H})
  &=
  \tfrac{1}{Z}
  \Pr(\text{H} \given \theta_1, \theta_2)
  p(\theta_1, \theta_2)
  \\
  &=
  \tfrac{1}{Z}
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{align*}
The normalization constant is
\begin{equation*}
  Z
  =
  \Pr(\text{H})
  =
  \int_0^1
  \int_0^1
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2)
  \intd{\theta_1}
  \intd{\theta_2}.
\end{equation*}
This integral is tractable and equals
\nicefrac{1}{2}.\footnote{\url{http://goo.gl/wRofuX}} In fact, this is
always true for any arbitrary mean-\nicefrac{1}{2} beta priors on
$\theta_1, \theta_2$: if our best guess is that each coin is unbiased,
then the outcomes HT/TH always have equal combined probability as the
outcomes HH/TT.

The posterior is now
\begin{equation*}
  p(\theta_1, \theta_2 \given \text{H})
  =
  2
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{equation*}
This is equivalent to the expression we derived with ``the easy way.''

The prior, likelihood, and posterior are plotted below.  From the
posterior, we can see that joint probabilities corresponding to
jointly low or high values: these combinations would correspond to a
higher probability of seeing either HH or TT observations.  Despite
the marginals for $\theta_1$ and $\theta_2$ remaining unchanged, the H
observation has entangled the previously independent beliefs in the
anticorrelated posterior.

\begin{figure}
  \centering
  \input{figures/problem_1_joint_prior.tex}
  \caption{The joint prior $p(\theta_1, \theta_2)$.}
  \label{problem_joint_prior}
\end{figure}

\begin{figure}
  \centering
  \input{figures/problem_1_joint_likelihood.tex}
  \caption{The joint likelihood $p(\text{H} \given \theta_1, \theta_2)$.}
  \label{problem_joint_likelihood}
\end{figure}

\begin{figure}
  \centering
  \input{figures/problem_1_joint_posterior.tex}
  \caption{The joint posterior $p(\theta_1, \theta_2 \given \text{H})$.}
  \label{problem_joint_posterior}
\end{figure}

\clearpage
\begin{enumerate}
\setcounter{enumi}{1}
\item
  Consider the three-dimensional parameter vector $\vec{\theta} =
  [\theta_1, \theta_2, \theta_3]\trans$, with the following joint
  multivariate Gaussian prior:
  \begin{equation*}
    p(\vec{\theta})
    =
    \mc{N}(\vec{\theta}; \vec{\mu}, \mat{\Sigma})
    =
    \mc{N}
    \left(
    \begin{bmatrix}
      \theta_1 \\
      \theta_2 \\
      \theta_3
    \end{bmatrix}
    ;
    \begin{bmatrix}
      0 \\
      1 \\
      2
    \end{bmatrix},
    \begin{bmatrix}
      1 & 2 & 0   \\
      2 & 9 & 0 \\
      0 & 0 & 16
    \end{bmatrix}
    \right).
  \end{equation*}
  We are going to consider a decision problem with action space
  $\mc{A} = \{1, 2, 3\}$.  The result of choosing an action $a \in
  \mc{A}$ will be to observe the exact value of $\theta_a$, the $a$th
  element of $\vec{\theta}$.

  Consider the following loss functions, $\ell_1$ and $\ell_2$:
  \begin{equation*}
    \ell_1(\vec{\theta}, a) =
    \begin{cases}
      1 & \theta_a   >  0 \\
      0 & \theta_a \leq 0
    \end{cases}
    \qquad
    \ell_2(\vec{\theta}, a) = \min(0, \theta_a).
  \end{equation*}
  For each:
  \begin{itemize}
  \item
    Write a generic expression for the expected loss of action $a$ in
    terms of $\vec{\mu}$ and $\mat{\Sigma}$.  Evaluate any integrals
    you encounter.
  \item
    Give a numerical value for the expected loss of each action, using
    the values of $(\vec{\mu}, \mat{\Sigma})$ provided above.
  \item
    State the Bayes action.
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

First, we note that the loss functions only depend on $\vec{\theta}$
through $\theta_a$, so we must only consider the marginal belief about
$\theta_a$ when contemplating action $a$.  By applying the marginalization
formula for multivariate Gaussians, this belief is:
\begin{equation*}
  p(\theta_a) = \mc{N}(\theta_a; \mu_a, \Sigma_{aa}).
\end{equation*}
For loss $\ell_1$, we may calculate the expected loss of each action:
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_1(\vec{\theta}, a)
  \bigr]
  =
  \int_{-\infty}^\infty
  \ell_1(\vec{\theta}, a)
  p(\theta_a)
  \intd{\theta_a}
  =
  \int_0^\infty
  \mc{N}(\theta_a; \mu_a, \Sigma_{aa})
  \intd{\theta_a}
  =
  1 - \Phi(0; \mu_a, \Sigma_{aa}).
\end{equation*}
Using this result, we may numerically calculate the expected loss for
each action:
\begin{equation*}
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 1)\bigr]
  =
  0.5 \qquad
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 2)\bigr]
  =
  0.631 \qquad
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 3)\bigr]
  =
  0.691.
\end{equation*}
The Bayes action is $a = 1$, with the lowest expected loss.

For loss $\ell_2$, we proceed in the same way:
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_2(\vec{\theta}, a)
  \bigr]
  =
  \int_{-\infty}^\infty
  \ell_2(\vec{\theta}, a)
  p(\theta_a)
  \intd{\theta_a}
  =
  \int_{-\infty}^0
  \theta_a
  \mc{N}(\theta_a; \mu_a, \Sigma_{aa})
  \intd{\theta_a}.
\end{equation*}
We may compute this definite integral; I used a table of Gaussian
integrals\footnote{\url{http://en.wikipedia.org/wiki/List_of_integrals_of_Gaussian_functions}}
and the identity
\begin{equation*}
  \phi\biggl(
  \frac{a - \mu}{\sigma}
  \biggr)
  =
  \sigma \mc{N}(a; \mu, \sigma^2)
\end{equation*}
to derive
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_2(\vec{\theta}, a)
  \bigr]
  =
  \mu_a \Phi(0; \mu_a, \Sigma_{aa})
  -
  \Sigma_{aa}
  \mc{N}(0; \mu_a, \Sigma_{aa}).
\end{equation*}
Using this result, we may numerically calculate the expected loss for
each action:
\begin{equation*}
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 1)\bigr]
  =
  -0.399 \qquad
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 2)\bigr]
  =
  -0.763 \qquad
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 3)\bigr]
  =
  -0.791.
\end{equation*}
The Bayes action is now $a = 3$, with the lowest expected loss.

\clearpage
\begin{enumerate}
\setcounter{enumi}{2}
\item
  Consider a $d$-dimensional vector $\vec{\theta}$ with an arbitrary
  multivariate Gaussian distribution:
  \begin{equation*}
    p(\vec{\theta})
    =
    \mc{N}(\vec{\theta}; \vec{\mu}, \mat{\Sigma}).
  \end{equation*}
  \begin{itemize}
  \item
    Give a general expression for the distribution of the following
    (scalar) value $\tau$.
    \begin{equation*}
      \tau = \theta_1 + 2\theta_2 + \dotsb d\theta_d
    \end{equation*}
  \item
    Consider again the specific distribution of the three-dimensional
    vector $\vec{\theta}$ from the last problem, as well as the action
    space $\mc{A}$ with the same observation mechanism: after choosing
    $a \in \mc{A}$, we will observe the corresponding value
    $\theta_a$.  Suppose we may select one action and then must
    predict $\tau$ under a squared loss function:
    \begin{equation*}
      \ell(\tau, \hat{\tau}) = (\tau - \hat{\tau})^2.
    \end{equation*}
    Using the distribution from the last problem. what is the expected
    loss of each of the three available actions?  Which is the Bayes
    action?
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

Define the (row) vector $\vec{d}\trans = [1, 2, \dotsc, d]$.  We first
notice that $\tau$ is simply a linear transformation of
$\vec{\theta}$:
\begin{equation*}
  \tau = \vec{d}\trans \vec{\theta};
\end{equation*}
therefore $\tau$ has a multivariate Gaussian distribution:
\begin{equation*}
  p(\tau)
  =
  p(\vec{d}\trans \vec{\theta})
  =
  \mc{N}(\tau; \vec{d}\trans \vec{\mu}, \vec{d}\trans \mat{\Sigma} \vec{d}).
\end{equation*}

In the second part of the question, we must consider estimating $\tau$
under a squared loss function $\ell(\tau, \hat{\tau}) = (\tau -
\hat{\tau})^2$.  A general result from Bayesian decision theory is
that the Bayes action is to estimate $\hat{\tau}$ as the (posterior)
mean of $\tau$.  For example, given the initial belief from the last
problem, we would predict $\hat{\tau} = \vec{d}\trans \vec{\mu} = 8$.
What is the \emph{expected} loss when predicting the mean $\hat{\tau}
= \mathbb{E}[\tau]$?
\begin{equation*}
  \mathbb{E}
  \Bigl[
    \ell\bigl(\tau, \mathbb{E}[\tau]\bigr)
  \Bigr]
  =
  \mathbb{E}
  \Bigl[
    \bigl(\tau - \mathbb{E}[\tau]\bigr)^2
  \Bigr]
  =
  \var [ \tau ]
  =
  \vec{d}\trans \mat{\Sigma} \vec{d}.
\end{equation*}
The expected squared loss is simply the variance of $\tau$!  Conveniently,
we have a closed-form expression for this variance.

The problem asks us to consider how we would proceed with estimating
$\tau$ if we could observe one of the entries of the vector
$\vec{\theta}$ before making our prediction $\hat{\tau}$.  If we wish
to minimize our expected loss, we should minimize the variance of
$\tau$ with our observation.  Observing an entry of $\vec{\theta}$ is
a conditioning observation of a multivariate Gaussian.  We have a
closed-form expression for the posterior covariance of $\vec{\theta}$
after observing any entry $\theta_a$.  Remarkably, the posterior
covariance of $\vec{\theta}$ does not depend on the actual value we
observe, only the index of the entry we choose, $a$.  The posterior
covariance matrices $\mat{\Sigma}_{\vec{\theta} \given \theta_a}$ for
each available action $a \in \mc{A}$ are:
\begin{align*}
  \mat{\Sigma}_{\vec{\theta} \given \theta_1}
  &=
  \begin{bmatrix}
    0 & 0 & 0   \\
    0 & 5 & 0   \\
    0 & 0 & 16
  \end{bmatrix}
  \\
  \mat{\Sigma}_{\vec{\theta} \given \theta_2}
  &=
  \begin{bmatrix}
    \frac{5}{9} & 0 & 0   \\
    0           & 0 & 0   \\
    0           & 0 & 16
  \end{bmatrix}
  \\
  \mat{\Sigma}_{\vec{\theta} \given \theta_3}
  &=
  \begin{bmatrix}
    1 & 2 & 0 \\
    2 & 9 & 0 \\
    0 & 0 & 0
  \end{bmatrix}.
\end{align*}
The expected losses of our final prediction of $\hat{\tau}$
given $\theta_a$ is now given by
\begin{equation*}
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_a \bigr]
  =
  \vec{d}\trans \mat{\Sigma}_{\vec{\theta} \given \theta_a} \vec{d}.
\end{equation*}
For our particular problem, the expected final loss after each potential
action is:
\begin{equation*}
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_1\bigr]
  =
  164 \qquad
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_2\bigr]
  =
  144\,\nicefrac{5}{9} \qquad
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_3\bigr]
  =
  45.
\end{equation*}
The Bayes action is $a = 3$.  Despite the fact that $\theta_3$ is
uncorrelated with the other two entries, collapsing its large variance
from $16$ to zero has the effect of reducing the variance of $\tau$
(and therefore our expected loss) by $3^2 \cdot 16 = 144$.

\clearpage
\begin{enumerate}
\setcounter{enumi}{3}
\item
  Consider the following data:
  \begin{align*}
    \vec{x} &= [0.54, 1.84, -2.26, 0.86, 0.32]\trans; \\
    \vec{y} &= [-1.31, -0.43, 0.34, 3.58, 2.77]\trans.
  \end{align*}
  Consider the Bayesian linear regression model with $\phi(x) = [1,
    x]\trans$.  Use the prior $p(\vec{w}) = \mc{N}(\vec{w}; \vec{0},
  \mat{I})$.

  Plot the posterior probability that the slope of the regression line
  is positive as a function of the standard deviation of the
  observation noise $\sigma$ (the noise variance is then $\sigma^2$).
  Use a grid of at least 100 points in the range $\sigma \in (0.01,
  10)$.
\end{enumerate}

\subsection*{Solution}

Using the given linear regression model, we assume
\begin{equation*}
  y
  =
  \phi(x)\trans \vec{w} + \varepsilon
  =
  w_1 + w_2 x + \varepsilon.
\end{equation*}
The second entry of the weight vector $\vec{w}$, $w_2$, therefore
serves as the slope of the regression line.

The Bayesian linear regression model gives the following posterior for
$\vec{w}$ given observations $\data$ and a specified noise variance
$\sigma^2$:
\begin{equation*}
  p(\vec{w} \given \data, \sigma^2)
  =
  \mc{N}(\vec{w};
  \vec{\mu}_{\vec{w}\given\data},
  \mat{\Sigma}_{\vec{w}\given\data}
  ),
\end{equation*}
where
\begin{align*}
  \vec{\mu}_{\vec{w}\given\data}
  &=
  \mat{X}\trans
  (\mat{X}\mat{X}\trans + \sigma^2 \mat{I})\inv
  \vec{y};
  \\
  \mat{\Sigma}_{\vec{w}\given\data}
  &=
  \mat{I}
  -
  \mat{X}\trans
  (\mat{X}\mat{X}\trans + \sigma^2 \mat{I})\inv
  \mat{X},
\end{align*}
where we have plugged the given prior $p(\vec{w}) = \mc{N}(\vec{w};
\vec{0}, \mat{I})$ into the general result.

Given a value of $\sigma$, the formulas above give the posterior over
$\vec{w}$.  To determine the probability that $w_2$ is positive, we
simply take the marginal posterior distribution and evaluate the
normal \acro{CDF}:
\begin{equation*}
  \Pr(w_2 > 0 \given \data, \sigma^2)
  =
  1 -
  \Phi\bigl(
  0;
  (\vec{\mu}_{\vec{w}\given\data})_2
  ,
  (\mat{\Sigma}_{\vec{w}\given\data})_{22}
  \bigr).
\end{equation*}

This quantity is plotted as a function of $\sigma$ in Figure
\ref{problem_4}.  The larger the noise, the less confident we become
about the sign of the slope.

\begin{figure}
  \centering
  \input{figures/problem_4.tex}
  \caption{The posterior probability that the slope of the regression
    line is positive as a function of the noise standard deviation
    $\sigma$.  Note the limits on the $y$-axis.}
  \label{problem_4}
\end{figure}

\end{document}


\chapter{Overview}

The \sfincs~code is a freely available, open-source tool for solving neoclassical-type kinetic problems in nonaxisymmetric or axisymmetric plasmas
with nested toroidal flux surfaces.
As with other neoclassical codes, the input information used by \sfincs~is the equilibrium magnetic geometry together with the density, radial density gradient, temperature,
and radial temperature gradient of each species.  The code then solves a drift-kinetic equation for each species,
yielding the (gyro-angle averaged) distribution function.  Moments of the distribution function are computed such as the parallel
flow, bootstrap current, radial particle flux, radial heat flux, and variation of the density over a flux surface.
These moments are all saved in the output file, and if you wish, you can also save the distribution function itself.
Optionally, a quasi-neutrality
equation can be solved at the same time as the drift-kinetic equations, yielding the self-consistent variation of the electrostatic potential on a flux surface.

The kinetic equations solved in \sfincs~have four independent variables: poloidal angle $\theta$, toroidal angle $\zeta$,
normalized speed $x = v / v_{thermal}$, and pitch angle $\xi = v_{||}/v$.  The third velocity coordinate (gyro-angle) does not appear
since gyro-averaged equations are solved.  The flux surface label (radius) coordinate is only a parameter, rather than a full independent variable,
since a radially local approximation is made.
The solution is the first-order distribution function $f_{s1} \left(\theta, \zeta, x, \xi\right)$ (where the full distribution is $f_s = f_{s0} + f_{s1}$) on the flux surface for all species $s$, and if quasi-neutrality is solved also the electrostatic potential variation on the flux surface $\Phi_1 \left(\theta, \zeta\right) = \Phi-\left<\Phi\right>$.

This document discusses the practical use and operation of the code.  For more details about the specific equations implemented,
see the version 3 technical documentation available in the \path{sfincs/docs} directory.
Ref \cite{sfincsPaper} gives many details and some early physics results.

Often, the limiting factor for \sfincs~is the ability of the libraries \mumps~or \superludist~to factorize the preconditioner matrix, discussed in section \ref{sec:gmres}.
You may therefore find it useful to see the control parameters and error codes in the \mumps~user manual:
\url{http://mumps.enseeiht.fr/doc/userguide_5.0.0.pdf}.

This manual describes ``version 3'' of \sfincs.
To preserve previous versions of the code that have been used for publications, two older versions of the
code called singleSpecies and multiSpecies are also present in the repository.
For all versions, both MATLAB and fortran editions exist which are independent of each other.
The MATLAB editions exist primarily for debugging the fortran editions.
The same algorithms are implemented in the two different languages, and for identical input parameters,
the matrices and output quantities from the different editions should agree to several significant digits (roughly within the solver tolerance.)
Any significant differences between the matrices and output of the MATLAB and fortran editions can be used to identify a bug.
The MATLAB versions are serial whereas the fortran versions
are parallelized, so the fortran versions are significantly faster and can access much more memory.
For realistic experimental geometry and collisionality, the resolution (and hence memory) requirements will mean
you will need to use the fortran edition.

\section{Features}

\begin{itemize}

\item
Both self-species and inter-species collisions are treated using the most accurate linear operator available, the full linearized Fokker-Planck collision operator,
with no approximation of the field-particle term or expansion in mass ratio.  This collision operator conserves mass, momentum, and energy.

\item
Realistic experimental geometry can be simulated using an interface to \vmec.  Analytic model equilibria can also be used.

\item
Full coupling in the speed (or equivalently, kinetic energy) coordinate is retained, i.e. no monoenergetic approximation is made.  However,
if desired, \sfincs~can also be run in monoenergetic mode to compare with older codes.

\item
The code is formulated to permit solution of a wide variety of kinetic equations, whether or not phase space volume and/or energy are conserved, so individual terms can be turned on or off to examine their effect.

\item
A variety of models for terms involving the radial electric field are available to allow comparison between models.

\item
You can choose to include or not include the poloidal and toroidal magnetic drifts in the kinetic equation.

\item
The code takes advantage of modern algorithms (GMRES) and parallelized libraries (\PETSc, \superludist, and \mumps).

\item
Efficient representation of velocity space is achieved using a pseudospectral method based upon non-classical orthogonal polynomials. \cite{speedGrids}

\item
The electrostatic potential can either be taken to be constant or non-constant on a flux surface.

\item
Optional nonlinear terms in the kinetic equation (involving both the non-Maxwellian distribution function and poloidal/toroidal electric field) can be included using Newton's method.

\item
The radial classical particle and heat fluxes are calculated.

\end{itemize}

\section{Limitations}

\begin{itemize}

\item
The \sfincs~code is radially local, in the sense that it approximates
the radial derivative of the distribution function $\partial f/\partial \psi$ by
the derivative of a Maxwellian flux function $\partial f_M(\psi,x)/\partial \psi$.
This approximation is important for reducing the otherwise 5D space of independent variables $(\psi,\theta,\zeta,x,\xi)$
to a 4D space $(\theta,\zeta,x,\xi)$.
As a result, \sfincs~cannot compute certain finite-orbit-width effects that occur when the radial extent of the particle orbits
between bounces or transits is not small compared to the scale of radial variation in the equilibrium.
Such finite orbit width effects are significant near the magnetic axis, and in strong transport barriers, such as the pedestal of a tokamak H-mode.

\item
Turbulence is neglected.  There are good theoretical reasons to expect that the neoclassical effects computed by \sfincs~should
decouple from turbulence, as detailed in \cite{AbelReview}.  However, this argument relies on an expansion in $\rho_* \ll 1$, and so may break down
in some circumstances when $\rho_*$ is not sufficiently small.

\item
It is assumed that nested toroidal magnetic surfaces exist. Thus, the code cannot accurately model regions of stochastic field,
magnetic islands, or open field lines.

\end{itemize}

\section{Geometry options}
In \sfincs, a variety of options are available for the magnetic field geometry.  The geometry can be read directly
from a {\ttfamily vmec wout}
file, or from the {\ttfamily .bc} format Boozer-coordinate data files used at the Max Planck Institute for Plasma Physics (IPP).
A general analytic model for the magnetic field is also available, given by equation (\ref{eq:Bmodel}),
as are several analytic models for LHD and W7-X in which 3 or 4 Fourier components are retained.
The primary switch for controlling the magnetic geometry in \sfincs~is the \parlink{geometryScheme} parameter
in the {\ttfamily \hyperref[sec:geometryParameters]{geometryParameters}} input namelist.
For more details about geometry options in \sfincs, see section \ref{sec:geometryParameters}.

\section{GMRES/KSP and preconditioning}
\label{sec:gmres}

At its heart, \sfincs~solves one or more large sparse linear systems $Ax=b$.  Here $b$ is a known right-hand side vector,
$A$ is a large (often millions $\times$ millions) known sparse matrix, and $x$ is the desired and unknown solution vector.
The direct way to solve such systems is to $LU$-factorize
the matrix $A$ into lower- and upper-triangular factors.
Once the $L$ and $U$ factors are found, the solution of the linear system
for any right-hand side vector can be rapidly obtained.  However, even if the original matrix is sparse, the $L$ and $U$ factors
are generally not sparse, and so a very large amount of memory can be required for a direct $LU$-factorization.

An alternative way to solve
such large linear systems is with a so-called ``Krylov-space'' iterative method, which can dramatically reduce the memory required
compared to a direct solution.  For the non-symmetric matrices that arise in \sfincs, the preferred Krylov-space
algorithm is called GMRES (Generalized Minimal RESidual.)  In \sfincs, the \PETSc~library is used to solve the large systems
of equations. \PETSc~calls its family of linear solvers KSP, so in the output of \sfincs~you will see a ``KSP residual'' reported
as GMRES iterates towards the solution.

An important element of Krylov methods is preconditioning.  The art of preconditioning is to find a linear operator which has similar eigenvalues
to the ``true'' matrix you would like to invert (or more precisely, to $LU$-factorize), but which can be inverted faster.
If a good preconditioner can be found, the number of GMRES iterations is greatly reduced.  Many schemes for preconditioning exist,
but the version adopted in \sfincs~is to explicity form and $LU$-factorize a preconditioning matrix which is similar
to the true matrix (but somewhat simpler).  There is a basic trade-off:
the more similar the preconditioner matrix is to the true matrix, the fewer iterations will be required, but the more time will
be required to $LU$-factorize the preconditioning operator.  The usual preconditioner matrix in \sfincs~is obtained by dropping all coupling
between grid points in the speed coordinate and dropping coupling between species.  The preconditioner matrix need not be a physically
accurate or meaningful operator; as long as GMRES converges, the solution obtained will be independent of the preconditioner to whatever tolerance is specified.

\section{\sfincs~vs. \sfincsScan}
The core fortran part of \sfincs~solves the kinetic equation for each species
at a single flux surface, a single value of $E_r$, and a single set of other parameters.
However, often the goal is to determine the ambipolar $E_r$ at one or more surfaces, or to scan some other parameter.
For this task, the \sfincsScan~family of \python~scripts is available.
Using these scripts, it is also possible to scan other variables in the input file,
and in particular, to scan the resolution parameters to ensure
the physical output quantities are numerically converged.
For a full list of the types of scans available, see section \ref{sec:sfincsScanParams}

\section{Input and Output}

The input parameters for a \sfincs~computation are specified in a file named {\ttfamily input.namelist}.
This file contains both information for the fortran part of \sfincs~(in standard fortran namelist format),
as well as special lines beginning with {\ttfamily !ss} which are read by \sfincsScan.
The variables which can be specified in {\ttfamily input.namelist} are detailed in chapter \ref{ch:input}.
For scans over minor radius, an additional file named {\ttfamily profiles} is used to specify the profiles of density and temperature
for each species, as well as the range of radial electric field to consider.

The output from a single \sfincs~computation is saved in \HDF~format in the file %{\ttfamily sfincsOutput.h5}.
specified by \parlink{outputFileName}.
To browse this file you can enter {\ttfamily h5dump outputFileName|less} %{\ttfamily h5dump sfincsOutput.h5|less}
from the command line.
Every array saved in this file is annotated with strings that describe the array dimensions,
for example \Ntheta$\times$ \Nzeta. One of the array dimensions may be {\ttfamily iteration},
which can either indicate the iteration of the Newton solver for a nonlinear calculation,
or which right-hand side vector was used when computing a transport matrix.
Many of the variables in the output file are also annotated with
text that describes their meaning and normalization.
Some of the most frequently used output quantities are detailed in chapter~\ref{ch:output}.

\section{Questions, Bugs, and Feedback}

We enthusiastically welcome any contributions to the code or documentation.
For write permission to the repository, or to report any bugs, provide feedback, or ask questions, contact Matt Landreman at
\href{mailto:matt.landreman@gmail.com}{\nolinkurl{matt.landreman@gmail.com} }


\documentclass[]{article}

\usepackage{showframe} % To render a frame marking the margins

% for hyperlinks and URL links
\usepackage{hyperref}

\title{\LaTeX{} Experiments\\ Part II: Pictures}

\author{AeAeA}

\begin{document}

\maketitle

%==============================================================================
\section{Picture environment}

\begin{itemize}
    \item \url{https://en.wikibooks.org/wiki/LaTeX/Picture}
    \item \url{https://www.overleaf.com/learn/latex/Picture_environment}
    \item The default value of \verb+\unitlength+ is 1pt.
\end{itemize}
Picture is the standard tool to create figures in \LaTeX.
This tool is sometimes too restrictive and cumbersome to work with,
but it's supported by most of the compilers and no extra packages
are needed. If you need to create complex figures, for more
suitable and powerful tools see the TikZ and Pgfplots packages.

\vfill

\setlength{\unitlength}{1cm}
\begin{picture}(11,6)
    \thicklines
    \put(0,0){\circle*{0.2}}

    \put(0,0){\line(0,1){6}} % left
    \put(0,0){\line(1,0){11}} % bottom
    \put(11,0){\line(0,1){6}} % right
    \put(0,6){\line(1,0){11}} % top

    \put(0,1){\circle{1.4}} % max 14mm
    \put(0,1){\oval(10,1.4)[r]}

    \put(0,1){\circle*{1}} % max 5mm
    \put(0,1){\oval(10,0.5)[r]}
\end{picture}

\newpage

%--------------------------------------
\subsection{layout and several examples}

\vspace{5mm}
\setlength{\unitlength}{1pt}
\begin{picture}(345,40)
    \put(0,0){\circle*{5}}
    \put(345,0){\circle*{5}}
    \put(0,40){\circle*{5}}
    \put(345,40){\circle*{5}}

    \put(5,20){\circle{1}}
    \put(7,20){\circle{2}}
    \put(10,20){\circle{3}}
    \put(14,20){\circle{4}}
    \put(19,20){\circle{5}}
    \put(25,20){\circle{6}}
    \put(32,20){\circle{7}}
    \put(40,20){\circle{8}}
    \put(49,20){\circle{9}}
    \put(59,20){\circle{10}}

    \put(70,20){\circle{11}}
    \put(82,20){\circle{12}}
    \put(95,20){\circle{13}}
    \put(109,20){\circle{14}}
    \put(124,20){\circle{15}}
    \put(140,20){\circle{16}}
    \put(157,20){\circle{17}}
    \put(175,20){\circle{18}}
    \put(194,20){\circle{19}}
    \put(214,20){\circle{20}}

    \put(239,20){\circle{25}}
    \put(269,20){\circle{30}}
    \put(304,20){\circle{35}}
    \put(344,20){\circle{40}}

    \put(0,20){\circle{41}} % cannot be > 40
\end{picture}
\vspace{5mm}

Above is the the picture in first paragraph (no indent), below is picture
in next paragraph (with indent).

\vspace{5mm}
\setlength{\unitlength}{1pt}
\begin{picture}(330,20)
    \put(0,0){\circle*{5}}
    \put(330,0){\circle*{5}}
    \put(0,20){\circle*{5}}
    \put(330,20){\circle*{5}}

    \put(0,3){\line(1,0){330}}
    \put(0,17){\line(1,0){330}}

    \put(5,10){\circle*{1}}
    \put(7,10){\circle*{2}}
    \put(10,10){\circle*{3}}
    \put(14,10){\circle*{4}}
    \put(19,10){\circle*{5}}
    \put(25,10){\circle*{6}}
    \put(32,10){\circle*{7}}
    \put(40,10){\circle*{8}}
    \put(49,10){\circle*{9}}
    \put(59,10){\circle*{10}}

    \put(70,10){\circle*{11}}
    \put(82,10){\circle*{12}}
    \put(95,10){\circle*{13}}
    \put(109,10){\circle*{14}}
    \put(124,10){\circle*{15}} % cannot be > 14pt

    \put(150,10){\circle*{16}}
    \put(165,10){\circle*{17}}
    \put(180,10){\circle*{20}}
\end{picture}
\vspace{5mm}

\vspace{5mm}
\setlength{\unitlength}{1cm}
\begin{picture}(11,4)
    \put(0,0){\circle*{0.2}}
    \put(11,0){\circle*{0.2}}
    \put(0,4){\circle*{0.2}}
    \put(11,4){\circle*{0.2}}

    \thicklines
    \put(8,3.3){{\footnotesize $3$-simplex}}
    \put(9,3){\circle*{0.1}}
    \put(8.3,2.9){$a_2$}
    \put(8,1){\circle*{0.1}}
    \put(7.7,0.5){$a_0$}
    \put(10,1){\circle*{0.1}}
    \put(9.7,0.5){$a_1$}
    \put(11,1.66){\circle*{0.1}}
    \put(11.1,1.5){$a_3$}
    \put(9,3){\line(3,-2){2}}
    \put(10,1){\line(3,2){1}}
    \put(8,1){\line(1,0){2}}
    \put(8,1){\line(1,2){1}}
    \put(10,1){\line(-1,2){1}}
\end{picture}
\vspace{5mm}

\noindent Some text to demonstrate different effect of
\verb+\noindent+ on text (here) and on picture (above without
\verb+\noindent+ and below with \verb+\noindent+).
Compare the four corner dots for pictures above and below.

\vspace{5mm}
\noindent
\setlength{\unitlength}{0.20mm}
\begin{picture}(400,250)
    \put(0,0){\circle*{10}}
    \put(400,0){\circle*{10}}
    \put(0,250){\circle*{10}}
    \put(400,250){\circle*{10}}

    \put(75,10){\line(1,0){130}}
    \put(75,50){\line(1,0){130}}
    \put(75,200){\line(1,0){130}}
    \put(120,200){\vector(0,-1){150}}
    \put(190,200){\vector(0,-1){190}}
    \put(97,120){$\alpha$}
    \put(170,120){$\beta$}
    \put(220,195){upper state}
    \put(220,45){lower state 1}
    \put(220,5){lower state 2}
\end{picture}
\vspace{5mm}

Regular paragraph (without \verb+\noindent+).

\vspace{5mm}
\setlength{\unitlength}{0.8cm}
\begin{picture}(10,5)
    \put(0,0){\circle*{0.3}}
    \put(10,0){\circle*{0.3}}
    \put(0,5){\circle*{0.3}}
    \put(10,5){\circle*{0.3}}

    \thicklines

    % Bézier curves
    \qbezier(1,3)(7,5)(9,0.5)

    \put(1,3){\circle*{0.2}} % start point
    \put(1,2.5){{\footnotesize start}}
    \put(7,5){\circle*{0.2}} % control point
    \put(6.5,4.5){{\footnotesize control}}
    \put(9,0.5){\circle*{0.2}} % end point
    \put(8,0.5){{\footnotesize end}}

    \put(3,1){{Bézier curve}}

\end{picture}

\newpage

%--------------------------------------
\subsection{line}
\begin{verbatim}\put(x,y){\line(x1,y1){length}}\end{verbatim}
The components of the direction vector \verb+(x1,y1)+
of the line segment \\
\verb+\line(x1,y1){length}+ are restricted to the integers
$(-6,-5, ... , 5,6)$
and they have to be coprime.
The figure below illustrates all 25 possible slope values
in the first quadrant.

\vspace{5mm}
\setlength{\unitlength}{5cm}
\begin{picture}(1,1)
    \put(0,0){\circle*{0.02}}
    \put(1,0){\circle*{0.02}}
    \put(0,1){\circle*{0.02}}
    \put(1,1){\circle*{0.02}}

    \put(1,0){\line(0,1){1}} % right vertical
    \put(0,1){\line(1,0){3}} % top horizontal
    \put(0,0){\line(1,1){3}} % diagonal
    \put(0,0){\line(1,2){.5}}
    \put(0,0){\line(1,3){.3333}}
    \put(0,0){\line(1,4){.25}}
    \put(0,0){\line(1,5){.2}}
    \put(0,0){\line(1,6){.1667}}
    \put(0,0){\line(2,1){1}}
    \put(0,0){\line(2,3){.6667}}
    \put(0,0){\line(2,5){.4}}
    \put(0,0){\line(3,1){1}}
    \put(0,0){\line(3,2){1}}
    \put(0,0){\line(3,4){.75}}
    \put(0,0){\line(3,5){.6}}
    \put(0,0){\line(4,1){1}}
    \put(0,0){\line(4,3){1}}
    \put(0,0){\line(4,5){.8}}
    \put(0,0){\line(5,1){1}}
    \put(0,0){\line(5,2){1}}
    \put(0,0){\line(5,3){1}}
    \put(0,0){\line(5,4){1}}
    \put(0,0){\line(5,6){.8333}}
    \put(0,0){\line(6,1){1}}
    \put(0,0){\line(6,5){1}}
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{vector}
\begin{verbatim}\put(x,y){\vector(x1,y1){length}}\end{verbatim}
For vectors, the components of the direction vector are even more
narrowly restricted than for line segments, namely to the integers
$(-4,-3, ... , 3,4)$. Components also have to be coprime.
Notice the effect of the \verb+\thicklines+ command on the two arrows
pointing to the upper left.

\vspace{5mm}
\setlength{\unitlength}{0.75mm}
\begin{picture}(60,40)
    \put(0,0){\circle*{1}}
    \put(60,0){\circle*{1}}
    \put(0,40){\circle*{1}}
    \put(60,40){\circle*{1}}

\thinlines
    \put(30,20){\vector(0,1){257}} % vertical up to the border
    \put(30,20){\vector(1,0){187}} % horizontal right to the border

    % all possible angles between 0 and 45 degrees:
    \put(30,20){\vector(4,1){20}}
    \put(30,20){\vector(3,1){20}}
    \put(30,20){\vector(2,1){20}}
    \put(30,20){\vector(3,2){20}}
    \put(30,20){\vector(4,3){20}}
    \put(30,20){\vector(1,1){20}}

\thicklines
    \put(30,20){\vector(-4,1){30}}
    \put(30,20){\vector(-1,4){5}}
\thinlines
    \put(30,20){\vector(-1,-1){100}} % goes to the page border
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{circle}
\begin{verbatim}\put(x,y){\circle{diameter}}\end{verbatim}
The picture environment only admits diameters up to approximately 14mm
(40pt) for circles and 5mm (14pt) for disks, and even below this limit,
not all diameters are possible.

\vspace{5mm}
\setlength{\unitlength}{1mm}
\begin{picture}(65, 40)
    \put(0,0){\circle*{1}}
    \put(65,0){\circle*{1}}
    \put(0,40){\circle*{1}}
    \put(65,40){\circle*{1}}

    \put(1,30){\circle{1}}
    \put(3,30){\circle{2}}
    \put(6,30){\circle{3}}
    \put(10,30){\circle{4}}
    \put(15,30){\circle{5}}
    \put(21,30){\circle{6}}
    \put(28,30){\circle{7}}
    \put(36,30){\circle{8}}
    \put(45,30){\circle{9}}
    \put(55,30){\circle{10}}
    \put(55,20){\circle{10}}
    \put(44,20){\circle{11}}
    \put(32,20){\circle{12}}
    \put(19,20){\circle{13}}
    \put(5,20){\circle{14}}
    \put(5,15){\circle{15}} % cannot be > 14mm
    \put(21,5){\circle*{1}}
    \put(23,5){\circle*{2}}
    \put(26,5){\circle*{3}}
    \put(30,5){\circle*{4}}
    \put(35,5){\circle*{5}}
    \put(40,5){\circle*{6}} % cannot be > 5mm
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{Text and formulae}

\vspace{5mm}
\setlength{\unitlength}{0.8cm}
\begin{picture}(6,5)
    \put(0,0){\circle*{0.1}}
    \put(6,0){\circle*{0.1}}
    \put(0,5){\circle*{0.1}}
    \put(6,5){\circle*{0.1}}

\thicklines
    \put(1,0.5){\line(2,1){3}}
    \put(4,2){\line(-2,1){2}}
    \put(2,3){\line(-2,-5){1}}
    \put(0.7,0.3){$A$}
    \put(4.05,1.9){$B$}
    \put(1.7,2.95){$C$}
    \put(3.1,2.5){$a$}
    \put(1.3,1.7){$b$}
    \put(2.5,1.05){$c$}
    \put(0.3,4){$F=\sqrt{s(s-a)(s-b)(s-c)}$}
    \put(3.5,0.4){$\displaystyle s:=\frac{a+b+c}{2}$}
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{multiput}
\begin{verbatim}\multiput(x,y)(dx,dy){n}{object}\end{verbatim}

\vspace{5mm}
\setlength{\unitlength}{2mm}
\begin{picture}(30,20)
    \put(0,0){\circle*{0.5}}
    \put(30,0){\circle*{0.5}}
    \put(0,20){\circle*{0.5}}
    \put(30,20){\circle*{0.5}}

\linethickness{0.5pt}
    \multiput(0,0)(1,0){31}{\line(0,1){20}}
    \multiput(0,0)(0,1){21}{\line(1,0){25}}

\linethickness{1pt}
    \multiput(0,0)(5,0){6}{\line(0,1){20}}
    \multiput(0,0)(0,5){5}{\line(1,0){25}}
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{oval}
\begin{verbatim}\put(x,y){\oval(w,h)[position:b,t,l,r]}\end{verbatim}

\vspace{5mm}
\setlength{\unitlength}{0.75cm}
\begin{picture}(6,4)
    \put(0,0){\circle*{0.2}}
    \put(6,0){\circle*{0.2}}
    \put(0,4){\circle*{0.2}}
    \put(6,4){\circle*{0.2}}

\linethickness{0.5pt}
    \multiput(0,0)(1,0){7}{\line(0,1){4}}
    \multiput(0,0)(0,1){5}{\line(1,0){6}}

\thicklines
    \put(2,3){\oval(3,1.8)}
\thinlines
    \put(3,2){\oval(3,1.8)}
\thicklines
    \put(2,1){\oval(3,1.8)[tl]}
    \put(4,1){\oval(3,1.8)[b]}
    \put(4,3){\oval(3,1.8)[r]}
    \put(3,1.5){\oval(1.8,0.4)}
\end{picture}
\vspace{5mm}

%--------------------------------------
\subsection{Predefined picture boxes}
\begin{verbatim}
\newsavebox{name}
\savebox{name}(width,height)[position]{content}
\put(x,y){\usebox{name}}
\end{verbatim}

\vspace{5mm}
\setlength{\unitlength}{0.5mm}
\begin{picture}(120,168)
    \put(0,0){\circle*{2}}
    \put(120,0){\circle*{2}}
    \put(0,168){\circle*{2}}
    \put(120,168){\circle*{2}}

\newsavebox{\foldera}
\savebox{\foldera}(40,32)[bl]{% definition
    \multiput(0,0)(0,28){2}{\line(1,0){40}}
    \multiput(0,0)(40,0){2}{\line(0,1){28}}
    \put(1,28){\oval(2,2)[tl]}
    \put(1,29){\line(1,0){5}}
    \put(9,29){\oval(6,6)[tl]}
    \put(9,32){\line(1,0){8}}
    \put(17,29){\oval(6,6)[tr]}
    \put(20,29){\line(1,0){19}}
    \put(39,28){\oval(2,2)[tr]}
}

\newsavebox{\folderb}
\savebox{\folderb}(40,32)[l]{% definition
    \put(0,14){\line(1,0){8}}
    \put(8,0){\usebox{\foldera}}
}

    \put(34,26){\line(0,1){102}}
    \put(14,128){\usebox{\foldera}}
    \multiput(34,86)(0,-37){3}{\usebox{\folderb}}

\end{picture}

%--------------------------------------
\subsection{Quadratic Bézier curves}
\begin{verbatim}\qbezier(x1,y1)(x,y)(x2,y2)\end{verbatim}

\newpage
\setlength{\unitlength}{1pt}
\begin{flushleft}
\begin{picture}(345,550)(-10,-10)

% border corners
    \put(-10,-10){\circle*{5}}
    \put(335,-10){\circle*{5}}
    \put(-10,540){\circle*{5}}
    \put(335,540){\circle*{5}}

% grid
\linethickness{0.25pt}
    \multiput(0,0)(10,0){34}{\line(0,1){530}}
    \multiput(0,0)(0,10){54}{\line(1,0){330}}
\linethickness{0.5pt}
    \multiput(0,0)(50,0){7}{\line(0,1){530}}
    \multiput(0,0)(0,50){11}{\line(1,0){330}}
\linethickness{1pt}
    \multiput(0,0)(100,0){4}{\line(0,1){530}}
    \multiput(0,0)(0,100){6}{\line(1,0){330}}

    \put(-30,0){{\footnotesize $0$}}
    \put(-30,100){{\footnotesize $100$}}
    \put(-30,200){{\footnotesize $200$}}
    \put(-30,300){{\footnotesize $300$}}
    \put(-30,400){{\footnotesize $400$}}
    \put(-30,500){{\footnotesize $500$}}
    \put(-30,600){{\footnotesize $600$}}

    \put(0,-20){{\footnotesize $0$}}
    \put(100,-20){{\footnotesize $100$}}
    \put(200,-20){{\footnotesize $200$}}
    \put(300,-20){{\footnotesize $300$}}
    \put(400,-20){{\footnotesize $400$}}

% qbezier examples first column

\linethickness{2pt}
    \qbezier(0,400)(10,450)(0,500)
    \thinlines
    \put(0,400){\line(1,5){10}}
    \put(10,450){\circle*{5}}
    \put(0,500){\line(1,-5){10}}

\linethickness{2pt}
    \qbezier(0,400)(50,450)(0,500)
    \thinlines
    \put(0,400){\line(1,1){50}}
    \put(50,450){\circle*{5}}
    \put(0,500){\line(1,-1){50}}

\linethickness{2pt}
    \qbezier(50,400)(150,450)(50,500)
    \thinlines
    \put(50,400){\line(2,1){100}}
    \put(150,450){\circle*{5}}
    \put(50,500){\line(2,-1){100}}

\linethickness{2pt}
    \qbezier(0,300)(20,300)(0,400)
    \thinlines
    \put(0,300){\line(1,0){20}}
    \put(20,300){\circle*{5}}
    \put(0,400){\line(1,-5){20}}

\linethickness{2pt}
    \qbezier(0,200)(50,150)(0,300)
    \thinlines
    \put(0,200){\line(1,-1){50}}
    \put(50,150){\circle*{5}}
    \put(0,300){\line(1,-3){50}}

\linethickness{2pt}
    \qbezier(0,100)(50,0)(0,200)
    \thinlines
    \put(0,100){\line(1,-2){50}}
    \put(50,0){\circle*{5}}
    \put(0,200){\line(1,-4){50}}

\linethickness{2pt}
    \qbezier(0,0)(100,600)(0,100)
    \thinlines
    \put(0,0){\line(1,6){100}}
    \put(100,600){\circle*{5}}
    \put(0,100){\line(1,5){100}}

% qbezier examples second column

\linethickness{2pt}
    \qbezier(100,400)(400,450)(100,500)
    \thinlines
    \put(100,400){\line(6,1){300}}
    \put(400,450){\circle*{5}}
    \put(100,500){\line(6,-1){300}}

\linethickness{2pt}
    \qbezier(100,300)(400,300)(100,400)
    \thinlines
    \put(100,300){\line(1,0){300}}
    \put(400,300){\circle*{5}}
    \put(100,400){\line(3,-1){300}}

\linethickness{2pt}
    \qbezier(100,200)(400,150)(100,300)
    \thinlines
    \put(100,200){\line(6,-1){300}}
    \put(400,150){\circle*{5}}
    \put(100,300){\line(2,-1){300}}

\linethickness{2pt}
    \qbezier(100,100)(400,0)(100,200)
    \thinlines
    \put(100,100){\line(3,-1){300}}
    \put(400,0){\circle*{5}}
    \put(100,200){\line(3,-2){300}}

\linethickness{2pt}
    \qbezier(100,0)(300,600)(100,100)
    \thinlines
    \put(100,0){\line(1,3){200}}
    \put(300,600){\circle*{5}}
    \put(100,100){\line(2,5){200}}

\end{picture}
\end{flushleft}

\end{document}


% file: EM_dump.tex
% Electrodynamics, in unconventional ``grande'' format; fitting a widescreen format
% Electricity and Magnetism notes "dump"
%
% github        : ernestyalumni
% linkedin      : ernestyalumni
% wordpress.com : ernestyalumni
%
% This code is open-source, governed by the Creative Common license.  Use of this code is governed by the Caltech Honor Code: ``No member of the Caltech community shall take unfair advantage of any other member of the Caltech community.''
%

\documentclass[10pt]{amsart}
\pdfoutput=1
\usepackage{mathtools,amssymb,lipsum,caption}

\usepackage{graphicx}
\usepackage{hyperref}
\usepackage[utf8]{inputenc}
\usepackage{listings}
\usepackage[table]{xcolor}
\usepackage{pdfpages}
%\usepackage[version=3]{mhchem}
\usepackage{mhchem}

\usepackage{tikz}
\usetikzlibrary{matrix,arrows}

\usepackage{multicol}

\hypersetup{colorlinks=true,citecolor=[rgb]{0,0.4,0}}

\oddsidemargin=15pt
\evensidemargin=5pt
\hoffset-45pt
\voffset-55pt
\topmargin=-4pt
\headsep=5pt
\textwidth=1120pt
\textheight=595pt
\paperwidth=1200pt
\paperheight=700pt
\footskip=40pt

\newtheorem{theorem}{Theorem}
\newtheorem{corollary}{Corollary}
%\newtheorem*{main}{Main Theorem}
\newtheorem{lemma}{Lemma}
\newtheorem{proposition}{Proposition}

\newtheorem{definition}{Definition}
\newtheorem{remark}{Remark}

\newenvironment{claim}[1]{\par\noindent\underline{Claim:}\space#1}{}
\newenvironment{claimproof}[1]{\par\noindent\underline{Proof:}\space#1}{\hfill $\blacksquare$}

%This defines a new command \questionhead which takes one argument and
%prints out Question #. with some space.
\newcommand{\questionhead}[1]
  {\bigskip\bigskip
   \noindent{\small\bf Question #1.}
   \bigskip}

\newcommand{\problemhead}[1]
  {
   \noindent{\small\bf Problem #1.}
   }

\newcommand{\exercisehead}[1]
  { \smallskip
   \noindent{\small\bf Exercise #1.}
  }

\newcommand{\solutionhead}[1]
  {
   \noindent{\small\bf Solution #1.}
   }

\title{Electromagnetism, Electrodynamics Dump;  \large Electricity and Magnetism dump (includes notes and solutions to Purcell's Electricity and Magnetism}
\author{Ernest Yeung \href{mailto:ernestyalumni@gmail.com}{ernestyalumni@gmail.com}}
\date{7 mars 2017}
\keywords{Electromagnetism, Electrodynamics, Electricity, Magnetism}
\begin{document}

\definecolor{darkgreen}{rgb}{0,0.4,0}
\lstset{language=Python,
 frame=bottomline,
 basicstyle=\scriptsize,
 identifierstyle=\color{blue},
 keywordstyle=\bfseries,
 commentstyle=\color{darkgreen},
 stringstyle=\color{red},
 }
%\lstlistoflistings

\maketitle

From the beginning of 2016, I decided to cease all explicit crowdfunding for any of my materials on physics, math.  I failed to raise \emph{any} funds from previous crowdfunding efforts.  I decided that if I was going to live in \emph{abundance}, I must lose a scarcity attitude.  I am committed to keeping all of my material \textbf{open-sourced}.  I give all my stuff \emph{for free}.

In the beginning of 2017, I received a very generous donation from a reader from Norway who found these notes useful, through \emph{PayPal}.  If you find these notes useful, feel free to donate directly and easily through \href{https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=ernestsaveschristmas%2bpaypal%40gmail%2ecom&lc=US&item_name=ernestyalumni&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted}{PayPal}, which won't go through a 3rd. party such as indiegogo, kickstarter, patreon.  Otherwise, under the \emph{open-source MIT license}, feel free to copy, edit, paste, make your own versions, share, use as you wish.

\noindent gmail        : ernestyalumni \\
linkedin     : ernestyalumni \\
twitter      : ernestyalumni \\

\setcounter{tocdepth}{1}
\tableofcontents

\begin{multicols*}{2}

\begin{abstract}
Electricity and Magnetism notes "dump" - Everything about or involving electricity and magnetism, electrodynamics.

\end{abstract}

\part{Math}

\section{Codifferential, The "Vector Potential" and Laplacian}
\emph{Keywords}: codifferential, vector potential, Laplacian

\subsection{Codifferential $\delta$}

For smooth manifold $M$, $\text{dim}M = n$,
\begin{equation}
\boxed{
\begin{aligned}
	& \delta : \Omega^k(M) \to \Omega^{k-1}(M) \\
	& \delta = (-1)^{n(k+1)+1} * d*
\end{aligned}
}
\end{equation}

For $k=1,2$ cases,
\[
\begin{aligned}
	& \delta = (-1)^{n(1+1)+1} * d* = (-1) *d* \\
	& \delta = (-1)^{n(2+1) + 1} * d * = (-1)^{3n+1} *d*
\end{aligned}
\]
For $n=d=3$,
\[
\begin{aligned}
	& \mathbf{\delta} : \Omega^2(M) \to \Omega^1(M) \\
	& \mathbf{\delta} = \mathbf{* d * }
\end{aligned}
\]

\subsection{the "Vector Potential"}

If $B=\mathbf{d} A$, $B\in \Omega^2(M)$,
\[
\begin{gathered}
B= B_{jk} dx^j \wedge dx^k = \mathbf{d}A = \frac{ \partial A_k}{ \partial x^j} dx^j \wedge dx^k  \\
 B_{jk} = \frac{ \partial A_k}{ \partial x^j}
\end{gathered}
\]
So these statements are equivalent:
\begin{equation}
\boxed{
B =\mathbf{d} A \Longleftrightarrow \mathbf{B} = \text{curl} \mathbf{A}
}
\end{equation}

Indeed, recall the \emph{deRham cohomology}:

\[
\begin{gathered}
	H^k_{\text{deRham}}(M) = Z^k(M)/ \text{im}d = \frac{Z^k(M)}{ d\Omega^{k-1}(M) }
\end{gathered}
\]
And so this form for $B=\mathbf{d}A$ presupposes that
\[
B \in [1] = [\mathbf{d}A ] \in H^2_{\text{deRham}}(M')
\]
But it should be noted on another manifold, this form may not hold; indeed, consider a submanifold or domain $M' \subseteq M$.  In this case
\[
H^2_{\text{deRham}}(M') \ni B
\]

\subsection{Laplacian}

\begin{definition}[Laplacian]
\begin{equation}
\begin{aligned}
	& \Delta : \Omega^k(M) \to \Omega^k(M) \\
	& \Delta = d\delta + \delta d
\end{aligned}
\end{equation}
\end{definition}

Both recognizing the equivalence between these 2 formulations:
\[
\mathbf{*d*}B = \mathbf{\delta}B \Longleftrightarrow \text{curl} \mathbf{B}
\]
and acknowledging that it \emph{has} to be the case that $\mathbf{*d*}B$ is the correct expression, coming from $d*F$ for the electromagnetic 2-form $F$,
\[
\mathbf{\delta} B = \mathbf{\delta} \mathbf{d}A = \Delta A - \mathbf{d \delta} A
\]
Then
\[
\begin{gathered}
	\mathbf{*d}A = \frac{ \sqrt{|\mathbf{g} |} }{ (d-2)! } \epsilon_{i_1i_2 \dots i_{d-2} jk} g^{jj'} g^{kk'} \frac{ \partial A_{k'}}{ dx^{j'} } dx^{i_1} \wedge \dots \wedge dx^{i_{d-2}} = \sqrt{ |\mathbf{g} | } \epsilon_{ijk} g^{jj'} g^{kk'} \frac{ \partial A_{k'} }{ \partial x^{j'} } dx^i  \\
\end{gathered}
\]

Consider the expression
\[
\text{curl}\mathbf{B} = \text{curl}( \text{curl} \mathbf{A})
\]
I will generalize it and point out its misgivings.

Calculating from definitions for $*$ and $d$,
\[
\begin{gathered}
	\mathbf{d} \mathbf{*} \mathbf{d} A = \frac{ \epsilon_{i_1 i_2 \dots i_{d-2} jk } }{ (d-2)! } \frac{ \partial }{ \partial x^l} \left( \sqrt{|\mathbf{g} |} g^{jj'} g^{kk'} \frac{ \partial A_{k'} }{ \partial x^{j'} } \right) dx^l \wedge dx^{i_1} \wedge \dots \wedge dx^{i_{d-2} } \\
	\mathbf{*} \mathbf{d} \mathbf{*} \mathbf{d} A = \frac{ \sqrt{ |\mathbf{g} | } }{ (d-d(-1))! } \frac{ \epsilon_{id'i_1' i_2' \dots i'_{d-2} } }{ (d-2)! } g^{l'l} g^{i_1' i_1} g^{i_2' i_2} \dots g^{i_{d-2}' i_{d-2} } \frac{ \partial }{ \partial x^l } \left( \sqrt{ |\mathbf{g} | } g^{jj'} g^{kk'} \frac{ \partial A_{k'} }{ \partial x^{j'} } \right) \epsilon_{i_1 i_2 \dots i_{d-2} jk } dx^i = \\
\xrightarrow{d=3} \sqrt{ |\mathbf{g} | } \epsilon_{il'm'} g^{l'l} g^{m'm} \frac{ \partial }{ \partial x^l} \left( \sqrt{ |\mathbf{g} | } g^{jj'} g^{kk'} \frac{ \partial A_{k'} }{ \partial x^{j'} } \right) \epsilon_{mjk} dx^i
\end{gathered}
\]
In $\mathbb{R}^3$,
\[
\mathbf{*} \mathbf{d} \mathbf{*} \mathbf{d} A \xrightarrow{ \mathbb{R}^3} \frac{ \partial }{ \partial x^j} \left( \frac{ \partial A_k }{ \partial x^j} \right) - \frac{ \partial }{ \partial x^k} \left( \frac{ \partial A_k}{ \partial x^j} \right)
\]
At this point, in the "vector calculus" formulation, the partial derivatives in the $- \frac{ \partial }{ \partial x^k} \left( \frac{ \partial A_k}{ \partial x^j} \right)$ would be exchanged in order, and then a so-called "choice of gauge" for $\nabla \cdot A \equiv \text{div}A$ would be "made," making this term equal $0$.  As we clearly see above, this should not be the case.  Rather, this choice should be made:
\begin{equation}
\mathbf{d \delta } A = 0
\end{equation}
This is because we should directly use the "manifestly covariant" definition of the Laplacian:
\begin{equation}
\begin{gathered}
	\mathbf{* d * d } A = (-1)^{d(1-1) +1} \mathbf{ \delta d} A = (-1)^{0+1} \mathbf{ \delta d } A = (-1)^{1} (\Delta - \mathbf{d\delta } ) A \\
\xrightarrow{ d=3} (-1)(\Delta - \mathbf{ d\delta } ) A
\end{gathered}
\end{equation}
Note that $k=1$, i.e. we're dealing with 1-form $A$ here, in the $(-1)^{d(k-1)+1}$ factor.

So the true expression is this (to reiterate and emphasize the point):
\begin{equation}
\mathbf{\delta}B = (-1) (\Delta - \mathbf{d\delta } ) A
\end{equation}

Are there any necessary constraints on $A$ to make it, such that $\mathbf{d\delta }A=0$?  Perhaps we can take a look at how the definition of the codifferential $\mathbf{\delta}$ necessitates that this diagram commutes:
\[
 \begin{tikzpicture}
  \matrix (m) [matrix of math nodes, row sep=7.8em, column sep=7.8em, minimum width=5.2em]
  {
 \Omega^1(M)  &  \Omega^{d-1}(M)  \\
	\Omega^0(M) &  \Omega^d(M)  \\
};
  \path[->]
  (m-1-1) edge node [above] {$ \mathbf{*} $ }  (m-1-2)
edge node [auto] {$\mathbf{\delta} $ } (m-2-1)
	(m-1-2) edge node [auto] {$ \mathbf{d} $ } (m-2-2)
	(m-2-1) edge node [auto] {$ \mathbf{ * } (-1) $ }(m-2-2)
  ;
\end{tikzpicture}   \qquad \quad \,
\begin{tikzpicture}
  \matrix (m) [matrix of math nodes, row sep=7.8em, column sep=7.8em, minimum width=5.2em]
  {
 A  &  \mathbf{*}A  \\
	\delta A &  \mathbf{d}\mathbf{*} A  \\
};
  \path[|->]
  (m-1-1) edge node [above] {$ \mathbf{*} $ }  (m-1-2)
edge node [auto] {$\mathbf{\delta} $ } (m-2-1)
	(m-1-2) edge node [auto] {$ \mathbf{d} $ } (m-2-2)
	(m-2-1) edge node [auto] {$ \mathbf{ * } (-1) $ }(m-2-2)
  ;
\end{tikzpicture}
\]

\part{Maxwell's Equations; My version of Maxwell's Equations}

\section{My version of Maxwell's equations}

\subsection{Maxwell's Equations, my version, in "vector calculus" form}

If $\nabla \cdot \mathbf{B} = 0$, then
\begin{equation}
	\nabla \times \mathbf{E} = \frac{-1}{c} \left( \frac{ \partial \mathbf{B} }{\partial t} \right)
\end{equation}

If $\nabla \cdot \mathbf{E} = 4\pi \rho_{\text{total}}$, then
\begin{equation}
\begin{aligned}
	\nabla \times \mathbf{B} & = \frac{1}{c} \left( \frac{ \partial \mathbf{E}}{ \partial t} + 4\pi \frac{ \partial \mathbf{P} }{ \partial t} +  \right.  \\
	& \left.   + 4\pi \mathbf{J}_{\text{free}} + 4\pi c \nabla \times \mathbf{M}  \right)
\end{aligned}
\end{equation}

\subsection{Maxwell's Equations, my version, over spacetime manifold $M$}

For spacetime manifold $M$, of dimensions $\text{dim}M = d+1$, and for
\[
\begin{aligned}
	& E \in \Omega^1(M) \\
	& B \in \Omega^2(M)
\end{aligned}
\]
If $\mathbf{d}B=0$, then
\begin{equation}\label{Eq:MaxwellsEqnsDGEBInduction}
\boxed{ 	\mathbf{d}E + \frac{ \partial B}{ \partial t} = 0  }
\end{equation}

If $\mathbf{\delta}E = \mathbf{*} \mathbf{d} \mathbf{*} E = 4\pi \rho_{\text{total}}$,
\begin{equation}\label{Eq:MaxwellsEqnsDGEBFaraday}
	\boxed{ \mathbf{\delta} B = \mathbf{*} \mathbf{d} \mathbf{*} B = \frac{ \partial E}{ \partial t} + 4\pi \frac{ \partial P}{ \partial t} + 4\pi J_{\text{free}} + 4\pi c \mathbf{\delta} \mathbf{M} }
\end{equation}
with $\mathbf{M} \in \Omega^2(M)$, magnetization in matter (i.e. matter magnetization) is \emph{necessarily} a 2-form.

\subsubsection{Some of the algebra (scratch) work/explicit calculations, for Maxwell's Equations, my version, over spacetime manifold $M$}

\[
\mathbf{d}B \Longleftrightarrow \nabla \cdot B
\]
since component-wise,
\[
\begin{gathered}
	\mathbf{d} B = \frac{ \partial }{ \partial x^k } B_{ij} dx^k \wedge dx^i \wedge dx^j \Longleftrightarrow \nabla \cdot B
\end{gathered}
\]
\[
\mathbf{d}E = -\frac{ \partial B}{\partial t}   \Longleftrightarrow \nabla \times E \equiv \text{curl} E = \frac{-1}{c} \frac{ \partial \mathbf{B}}{ \partial t}
\]
since, component-wise,
\[
\mathbf{d} E = \frac{ \partial }{ \partial x^k} E_i dx^k \wedge dx^i = \frac{ \partial }{ \partial x^j} E_k dx^j \wedge dx^k = \frac{ -\partial }{ \partial t} B_{jk} dx^j \wedge dx^k
\]
For $\mathbf{\delta} E = \mathbf{*} \mathbf{d} \mathbf{*} E = 4\pi \rho_{\text{total}}$, consider
\[
\begin{gathered}
	\mathbf{*} E = \frac{1}{ (d-1)!} \sqrt{ \mathbf{g}} \epsilon_{i_1i_2 \dots i_{d-1} j_1} E_j g^{jj_1} e^{i_1} \wedge e^{i_2} \wedge \dots \wedge e^{i_{d-1}} = \frac{1}{2} \sqrt{ \mathbf{g}} \epsilon_{ijk} E_{k'} g^{k'k} dx^i \wedge dx^j
\end{gathered}
\]
Further,
\[
\begin{gathered}
	\mathbf{d} \mathbf{*} E = \frac{1}{ (d-1)! } \frac{ \partial }{ \partial x^k} (\sqrt{ \mathbf{g}} E_j g^{jj_1} ) \epsilon_{i_1 i_2 \dots i_{d-1} j_1 } dx^k \wedge dx^{i_1} \wedge dx^{i_2} \wedge \dots \wedge dx^{i_{d-1}} = \\
=\frac{1}{(d-1)!} \frac{ \partial }{ \partial x^k} (\sqrt{ \mathbf{g}} E^{j_1} ) \epsilon_{i_1 i_2 \dots i_{d-1} j_1} \epsilon^{ k i_1 i_2 \dots i_{d-1} } \frac{ \text{vol}^d}{ \sqrt{ |\mathbf{g} | } } = \\
=\frac{1}{(d-1)!} \frac{ \partial }{ \partial x^k} (\sqrt{ |\mathbf{g} | } E^{j_1} ) \delta^k_{ j_1} (d-1)! \frac{ \text{vol}^d}{ \sqrt{ |\mathbf{g} | } } = \frac{1}{ \sqrt{ |\mathbf{g} | }} \frac{ \partial }{ \partial x^k} (\sqrt{ |\mathbf{g} |} E^k) \text{vol}^d
\end{gathered}
\]
where this (generalized) Kronecker delta relation was used:
\[
\frac{1}{p!} \delta^{\mu_1 \dots \mu_p }_{\nu_1 \dots \nu_p } \delta^{ \nu_1 \dots \nu_p }{ \rho_1 \dots \rho_p } = \delta^{\mu_1 \dots \mu_p }_{ \rho_1 \dots \rho_p }
\]
where
\[
\delta^{\mu_1 \dots \mu_n }_{ \nu_1 \dots \nu_n } = \epsilon^{\mu_1 \dots \mu_n} \epsilon_{ \nu_1 \dots \nu_n }
\]
Note that
\[
\begin{aligned}
	*1 & = \text{vol} \\
**1  & = (-1)^{0(n-0)} 1 = 1 = *\text{vol}
\end{aligned}
\]
and so
\[
\mathbf{*} \mathbf{d} \mathbf{*} E = \mathbf{\delta} E = \frac{1}{\sqrt{ |\mathbf{g} | } } \frac{ \partial }{ \partial x^k} ( \sqrt{ | \mathbf{g} | } E^k )
\]
Indeed, we had generalized the divergence, but on a 1-form:
\begin{equation}
\begin{aligned}
	& \mathbf{\delta} : \Omega^1(M) \to C^{\infty}(M) \\
	& -\mathbf{\delta} E = -\mathbf{\delta} (E_kdx^k)  = \frac{1}{\sqrt{|\mathbf{g} |} } \frac{ \partial }{ \partial x^k} (\sqrt{ |\mathbf{g} | } E^k) \equiv \frac{1}{\sqrt{ |\mathbf{g} | } } \frac{ \partial }{ \partial x^k} ( \sqrt{ |\mathbf{g} | }  g^{kk_1} E_{k_1} )
\end{aligned}
\end{equation}

\section{Magnetostatics, macroscopic Magnetism, Magnetic permeability, magnetic susceptibility, field $\mathbf{H}$, free currents and field $\mathbf{H}$}

\emph{Keywords}: magnetic permeability, magnetic susceptibility

Suppose we have matter (i.e. the "macroscopic problem", referred to from Jackson (1998), Sec. 5.8 "Macroscopic Equations, Boundary Conditions on $B$ and $H$", \cite{Jack1998}), \emph{not} a vacuum.

Atoms in matter have electrons, $e^-$ in orbit, contributing to (rapidly) fluctuating magnetic moments $\mathbf{m}$, along with $e^-$'s intrinsic $\mathbf{m}$.

Consider an average macroscopic magnetization or magnetic moment density $\mathbf{M}(\mathbf{x})$ defined in a "vector calculus" manner by Jackson (1998) \cite{Jack1998},
\[
\mathbf{M}(\mathbf{x}) = \sum_I N_I\langle \mathbf{m}_I\rangle , \qquad \, I \equiv \text{ index of a particle }
\]

Recalling Maxwell's Equations, Eq. \ref{Eq:MaxwellsEqnsDGEBFaraday},
\[
\mathbf{\delta} B = \frac{ \partial E}{ \partial t} + 4\pi \frac{ \partial P }{ \partial t} + 4\pi J_{\text{free}} + 4\pi c \mathbf{\delta}\mathbf{M}
\]
Consider a time-independent $E$ and negligible $P$.  Then
\[
\Longrightarrow \mathbf{\delta} B =  4\pi J_{\text{free}} + 4\pi c \mathbf{\delta}\mathbf{M}
\]
Jackson (1998) \cite{Jack1998} considers this magnetization $\mathbf{M}$ as contributing to an \emph{effective current density} by vector calculus arguments of it having a vector potential form, and so he proceeds to write it as (Jackson (1998), Eqn. (5.80) \cite{Jack1998})
\[
\text{curl} \mathbf{B} = \mu_0 (\mathbf{J} + \text{curl}\mathbf{M} ) \qquad \, (SI)
\]
Then Jackson \emph{defines} the macroscopic field $\mathbf{H}$, in Jackson (1998), Eqn. (5.81) \cite{Jack1998},
\[
\mathbf{H} := \frac{1}{\mu_0} \mathbf{B} - \mathbf{M}
\]

However, Purcell's treatment is both more lucid, and more grounded in what $B$ field really is physically, less relying upon artificial artifices.

\subsection{Free currents $\mathbf{J}_{\text{free}}$ and the field $\mathbf{H}$, magnetic susceptibility}

cf. Purcell (1984) \cite{Purc1984}, Sec. 11.10 Free Currents, and the Field $\mathbf{H}$

\emph{Keywords}: $\mathbf{H}$, volume magnetic susceptibility

Bound current $\mathbf{J}_{\text{bound}}$ are current associated with molecular or atomic magnetic moments, including the intrinsic magnetic moment of particles with spin.

Free currents $\mathbf{J}_{\text{free}}$ are ordinary conduction currents.

\begin{equation}
\mathbf{J}_{\text{bound}} = c \nabla \times \mathbf{M}
\end{equation}
cf. Purcell (1984), Eq. (44) of Ch. 11 \cite{Purc1984}

At a surface, where $\mathbf{M}$ is discontinuous, we have a surface current density $\mathcal{J}$.

By superposition,
\begin{equation}
	\nabla \times \mathbf{B} = \frac{ 4\pi }{c} (\mathbf{J}_{\text{bound}} + \mathbf{J}_{\text{free} } ) = \frac{4\pi }{ c} \mathbf{J}_{\text{total} }
\end{equation}
cf. Purcell (1984), Eq. (50) of Ch. 11 \cite{Purc1984}

Thus,
\[
\begin{gathered}
\nabla \times \mathbf{B} = \frac{ 4\pi}{c}(c\nabla \times \mathbf{M} ) + \frac{4\pi}{c} \mathbf{J}_{\text{free}} = \\
	= \nabla \times (\mathbf{B} - 4\pi \mathbf{M} ) = \frac{4\pi }{c} \mathbf{J}_{\text{free} }
\end{gathered}
\]
cf. Purcell (1984), Eq. (51) of Ch. 11 \cite{Purc1984}

Purcell also defines
\begin{equation}
\mathbf{H} := \mathbf{B}-4\pi \mathbf{M}
\end{equation}
cf. Purcell (1984), Eq. (52) of Ch. 11 \cite{Purc1984}; and so
\[
\begin{gathered}
\nabla \times \mathbf{H} = \frac{4\pi}{c} \mathbf{J}_{\text{free}} \qquad \, (cgs) \qquad \qquad \, \nabla \times \mathbf{H} = \mathbf{J}_{\text{free}} \qquad \, (SI)
\end{gathered}
\]
cf. Purcell (1984), Eq. (53), (53'), respectively, of Ch. 11 \cite{Purc1984}.

In magnetic systems, it is precisely the free currents that we can control.  So $\mathbf{H}$ is useful:

\begin{equation}
\begin{gathered}
\int_C \mathbf{H} \cdot d\mathbf{l} = \frac{4\pi}{c}\int_S \mathbf{J}_{\text{free}} \cdot d\mathbf{a} = \frac{4\pi}{c} I_{\text{free}} \qquad \, (cgs) \qquad \qquad \, \int_C \mathbf{H} \cdot d\mathbf{l} = \int_S \mathbf{J}_{\text{free}} \cdot d\mathbf{a} =  I_{\text{free}} \qquad \, (SI)
\end{gathered}
\end{equation}
where in SI, $H \sim \frac{ \text{ amps } }{ \text{ meter } }$.  cf. Purcell (1984), Eq. (54), (54'), respectively, of Ch. 11 \cite{Purc1984}.

$\mathbf{B}$ is the \emph{fundamental magnetic field vector}; it is \textbf{only} $\mathbf{B}$ s.t. $\nabla \cdot \mathbf{B} =0$ or $\mathbf{d}B=0$

The basic magnetic field inside matter is $\mathbf{B}$, \emph{not} $\mathbf{H}$.  That's not a matter of mere definition, but a \emph{consequence of the absence of magnetic charges}.  cf. Purcell (1984)\cite{Purc1984}.

Now
\begin{equation}
\mathbf{M} = \chi_m \mathbf{H}
\end{equation}
cf. Purcell (1984), Eq. (56) Ch. 11 \cite{Purc1984}.

The lines of $\mathbf{H}$ inside the magnet look just like the lines of $\mathbf{E}$ inside the polarized cylinder.   \\
- $\mathbf{H}$ is the fiction of magnetic poles; if there wre magnetic poles then $\mathbf{H}$ is the macroscopic $\mathbf{B}$ filed inside the material.

For any material in which $\mathbf{M}$ is porportional to $\mathbf{H}$,
\begin{equation}
\boxed{
\begin{gathered}
	\mathbf{B} = \mathbf{H} + 4\pi \mathbf{M} = (1+4\pi \chi_m) \mathbf{H} \\
\mu = 1 + 4\pi \chi_m
\end{gathered}
}
\end{equation}

So \emph{if} there was a linear response between magnetization $\mathbf{M}$ and the measured macroscopic field $\mathbf{H}$, related through the volume magnetic susceptibility, $\chi_m$, ($\mathbf{M} = \chi_m \mathbf{H}$), then for $\mathbf{\delta} B = 4\pi J_{\text{free}} + 4\pi c \mathbf{\delta} \mathbf{M}$,
\[
\mathbf{\delta} (B-4\pi c M) = \mathbf{\delta} H = \mathbf{\delta} \frac{ B}{ \mu } = 4\pi J_{\text{free}} \Longrightarrow \mathbf{B} = \mu 4\pi J_{\text{free}}
\]
and so we have the usual expression (make the comparison)
\[
\text{curl} \mathbf{B} = \mu 4\pi \mathbf{J}_{\text{free}}
\]
Obtaining an integral form,
\[
\begin{gathered}
	\mathbf{*} \mathbf{\delta} B = \mathbf{*} \mathbf{*} \mathbf{d} \mathbf{*} B = (-1)^{2(d-2)} \mathbf{d}\mathbf{*} B = \mu 4\pi \mathbf{*} J_{\text{free}} \xrightarrow{ \int_S } \int_S \mathbf{d} \mathbf{*} B =  \int_{\partial S} \mathbf{*} B = \mu 4\pi \int_S \mathbf{*} J_{\text{free}}
\end{gathered}
\]

Jackson seems to imply to treat macroscopic field $\mathbf{H}$ as what you measure, since $\mathbf{J}_{\text{free}}$ is what one can measure and control, pointed out sagely by Purcell.  So consider this, as I write down an integral form,
\[
\begin{gathered}
\mathbf{*} \mathbf{\delta} H  = \mathbf{d} \mathbf{*} H = 4\pi \mathbf{*} J_{\text{free}} \xrightarrow{ \int_S } \int_S \mathbf{d} \mathbf{*} H = \int_{\partial S} \mathbf{*} H = 4\pi \int_S \mathbf{*} J_{\text{free}}
\end{gathered}
\]
If, over $S$, $\mathbf{J}_{\text{free}}$ is uniform, $\frac{4\pi}{c} \int_S \mathbf{*} \mathbf{J}_{\text{free}} = \frac{4\pi }{c} I_{\text{free}}$.  If we can measure the current, we can obtain the line integral of $\mathbf{H}$.  But we should really be aware that what we're \emph{really} measuring is $B-4\pi c \mathbf{M}$ - would it be possible to measure the macroscopic $\mathbf{M}$ itself?

\section{Eddy Currents}

I build upon the physical setup proposed by Jackson (1998) \cite{Jack1998} in Section 5.18 "Quasi-Static Magnetic Fields in Conductors; Eddy Currents; Magnetic Diffusion."

For a system (with characteristic) length $L$, $L$ being small, \\
compared to electromagnetic wavelength associated with dominant time scale of problem $T$,
\[
\begin{gathered}
	f := \frac{1}{T} ; \quad \, \omega = 2\pi f ; \quad \, \omega \lambda = c \Longrightarrow \lambda = \frac{c}{ \omega } = \frac{c}{ 2\pi f } = \frac{Tc}{2\pi }  \\
\frac{L}{\lambda} = \frac{LTc}{2\pi } \gg 1
\end{gathered}
\]
From Maxwell's equations, in particular, Faraday's Law, and in its integral form (over 2-dim. \emph{closed} surface $S$),
\begin{equation}
\begin{gathered}
\mathbf{d}E + \frac{ \partial }{ \partial t } B = 0 \text{ or } -\mathbf{d}E =\frac{ \partial B}{ \partial t} \xrightarrow{ \int_S } \int_S \frac{ \partial B}{ \partial t} = -\int_S \mathbf{d}E = -\int_{\partial S} E
\end{gathered}
\end{equation}
So on $S$, changing magnetic flux $\int \frac{ \partial B}{ \partial t}$ results in $E$ field, circulating around boundary of $S$, $\partial S$.

We know that in a conductor, free conducting electrons get pushed around by $E$ fields, result in a current density $J$.

$J$ is related to $E$, \emph{empirically} (by Ohm's Law)
\[
J = \sigma E
\]
where $\sigma$ is the resistivity.

Then use the force law on this induced current $J$ from the $B$ field set up:
\[
F_{\text{net}} = \frac{1}{c} \int_S J\times B dA
\]
By working through the right-hand rule, $F_{\text{net}}$ the force on those currents induced in the conductor due to the $B$ that's there, is in the direction to help oppose changing (increasing or decreasing $\frac{\partial B}{ \partial t}$).

To find $B$, suppose $B=dA$, i.e. $B\in H^2_{\text{deRham}}(M)$, i.e. $B=\text{curl}A$.

For sure,
\[
\mathbf{\delta} (B-4\pi c \mathbf{M}) = 4\pi J \Longleftrightarrow \text{curl}(B-4\pi c \mathbf{M} ) = \text{curl} H = 4\pi J
\]
Be warned now that the relation $B=\mu H$ may not be valid on all domains of interest; $\mu$ could even be a tensor! (e.g. $B_{ij} = \mu^{kl}_{ij} H_{kl}$).  However, both Jackson (1998) \cite{Jack1998} in Sec. 5.18 Quasi-Static Magnetic Fields in Conductors; Eddy Currents; Magnetic Diffusion, pp. 219, and Smythe (1968), Ch. X (his Ch. 10), pp. 368 \cite{Smyt1968}, continues on \emph{as if} this relation is linear: $B=\mu H$.

Nevertheless, as we want to find $B$ by finding its "vector potential" $A$, we obtain a diffusion equation:
\begin{equation}\label{Eq:EddyCurrentsAdiffusion}
\begin{gathered}
	- \mathbf{\delta}B = \mathbf{*d*d}A = (-1) \mathbf{\delta d} A = (-1)( \Delta - \mathbf{d\delta} ) A \xrightarrow{ \mathbf{d\delta} A = 0 } - \Delta A = \\
	= 4\pi \mu J = 4\pi \mu \sigma E = 4\pi \mu \sigma \left( -\frac{ \partial A}{ \partial t} \right) \\
\Longrightarrow \boxed{ \Delta A = 4\pi \mu \sigma \frac{ \partial A}{ \partial t } }
\end{gathered}
\end{equation}
where in the first 2 steps (equalities), $- \mathbf{\delta}B = \mathbf{*d*d}A = (-1) \mathbf{\delta d} A$ it's interesting to note that the codifferential $\mathbf{\delta}$ for the 2 form $B$ had to be written out explicitly, and then the codifferential for the 1-form $A$ is \emph{different} from the $\mathbf{\delta}$ for $B$ by a(n important) factor of $(-1)$; where $\mathbf{d\delta} A=0$ must be satisfied by the form $A$ takes; and where, since $B=\mathbf{d}A$,
\begin{equation}
\begin{gathered}
	\mathbf{d}E + \frac{ \partial B}{ \partial t} = \mathbf{d} E + \frac{ \partial }{ \partial t} \mathbf{d} A = \mathbf{d} \left( E+ \frac{ \partial A}{ \partial t} \right) = 0 \Longrightarrow E = -\frac{ \partial A}{ \partial t} + \text{grad}\Phi \xrightarrow{ \Phi = \text{ constant } } E = -\frac{ \partial A}{ \partial t}
\end{gathered}
\end{equation}
whereas a choice of gauge for $E$ was chosen so that $\Phi=\text{constant}$ (and so a particular form for $E$ was chosen, amongst those in the \emph{same} equivalence class of $H^1_{\text{deRham}}(M)$.

To ensure that the differential geometry formulation is in agreement with the practical vector calculus formulation, compare Eq. \ref{Eq:EddyCurrentsAdiffusion} with Eq. (5.160) of Jackson (1998) \cite{Jack1998} and Eq. (10) in Sec. 10.00 of Smythe (1968) \cite{Smyt1968}.

To summarize what's going on, I think one should at least understand in one's head how Maxwell's Equations apply, (and I will try to write in SI here)
\begin{equation}
\boxed{
\begin{gathered}
\int_S \frac{ \partial \mathbf{B}}{ \partial t} dA = -\oint \mathbf{E}\cdot d\mathbf{s} \Longrightarrow \mathbf{J}=\sigma \mathbf{E} \Longrightarrow \mathbf{F}_{\text{net}} = \int_S \mathbf{J} \times \mathbf{B} dA  \\
\text{ to find } \mathbf{B} = ? \qquad \, \text{ using form } \mathbf{B} = \nabla \times \mathbf{A}, \\
\nabla^2 \mathbf{A} = \mu \sigma \frac{ \partial \mathbf{A} }{ \partial t} \qquad \, (SI)
\end{gathered}
}
\end{equation}
where, a change in magnetic flux over a surface $S$ over the conductor, $\int_S \frac{ \partial \mathbf{B}}{ \partial t}dA$ induces a circulation of $E$ field around $S$, $-\oint \mathbf{E} \cdot d\mathbf{s}$, and this $E$ field is pushing around \emph{free conducting charges} according to Ohm's law, $\mathbf{J} = \sigma \mathbf{E}$, with $\sigma$ being the conductivity of the conducting material, and this current density $\mathbf{J}$ is then acted upon by the prevailing $B$ field, according to the usual force law.  To find $\mathbf{B}$, one can find $\mathbf{A}$ and \emph{try} to find $\mathbf{A}$ analytically.

Keep in mind that for $\nabla^2 \mathbf{A} = \mu \sigma \frac{ \partial \mathbf{A}}{ \partial t}$, we had used, critically, the Maxwell equation $\mathbf{\nabla} \times \mathbf{H} = \mathbf{J}$, with $\mathbf{J}$ being the \emph{induced current of free conducting charges on the conductor}.  This $\mathbf{H}$ will contribute (through linear superposition) to the $\mathbf{B}$ that could already be there due to the permanent magnet.

\end{multicols*}

\begin{thebibliography}{9}

\bibitem{Jack1998}
J.D. Jackson.  \textbf{Classical Electrodynamics} Third Edition.  Wiley.  1998.   ISBN-13: 978-0471309321

\bibitem{Purc1984}
Edward M. Purcell.  \textbf{Electricity and Magnetism} (Berkeley Physics Course, Vol. 2) Second Edition.  McGraw-Hill Science/Engineering/Math.  1984.  ISBN-13: 978-0070049086

\bibitem{Mori2001}
Shigeyuki Morita.  \textbf{Geometry of Differential Forms (Translations of Mathematical Monographs, Vol. 201)}.  American Mathematical Society (August 28, 2001).   ISBN-13: 978-0821810453

\bibitem{OCalinDChang2005}
Ovidiu Calin, Der-Chen Chang. \textbf{Geometric Mechanics on Riemannian Manifolds: Applications to Partial Differential Equations} (Applied and Numerical Harmonic Analysis).  Birkh\"{a}user. 2005. ISBN-13: 978-0817643546

\bibitem{Smyt1968}
William R. Smythe, \textbf{Static and Dynamic Electricity}.  3rd ed. (McGraw-Hill, New York, 1968).

  \end{thebibliography}

\end{document}