\providecommand{\main}{..}
\documentclass[\main/thesis.tex]{subfiles}
\begin{document}

\chapter{A gentle introduction to dependently typed programming in Agda}\label{agda}

There are already plenty of tutorials and introductions of Agda
\cite{norell2009dependently}\cite{FLOLAC16DTP}\cite{brutal}.
We will nonetheless compile a simple and self-contained tutorial from the
materials cited above, covering the parts (and only the parts) we need in this thesis.

Some of the more advanced constructions (such as views and universes) will not
be introduced in this chapter, but in other places where we need them.

\paragraph{Remark}
We assume that readers have some basic understanding of Haskell. Readers who are
familiar with Agda and dependently typed programming may skip this chapter.

\section{Some basics}

Agda is a \textit{dependently typed functional programming language} and also an
\textit{interactive proof assistant}. This language can serve both purposes because
it is based on \textit{Martin-Löf type theory}\cite{martin1984intuitionistic},
hence the Curry-Howard correspondence\cite{sorensen2006lectures},
which states that: ``propositions are types'' and ``proofs are programs.''
In other words, proving theorems and writing programs are essentially the same.
In Agda we are free to interchange between these two interpretations.
The current version (Agda2) is a completely rewrite by Ulf Norell during his
Ph.D. at Chalmers University of Technology.

We say that Agda is interactive because theorem proving involves a lot of
conversations between the programmer and the type checker.
Moreover, it is often difficult, if not impossible, to develop and prove a theorem at one stroke.
Just like programming, the process is incremental.
So Agda allows us to leave some ``holes'' in a program, refine them gradually, and
complete the proofs ``hole by hole''.

Take this half-finished function definition for example.

\begin{lstlisting}
is-zero : ℕ → Bool
is-zero x = ?
\end{lstlisting}

We can leave out the right-hand side and ask:
``what's the type of the goal?'', ``what's the context of this case?'', etc.
Agda would reply us with:

\begin{lstlisting}
GOAL : Bool
x : ℕ
\end{lstlisting}

Next, we may ask Agda to pattern match on {\lstinline|x|} and rewrite the program for us:

\begin{lstlisting}
is-zero : ℕ → Bool
is-zero zero    = ?
is-zero (suc x) = ?
\end{lstlisting}

We could fulfill these goals by giving an answer,
or even ask Agda to solve the problem (by pure guessing) for us if it is not too difficult.

\begin{lstlisting}
is-zero : Int → Bool
is-zero zero    = true
is-zero (suc x) = false
\end{lstlisting}

After all of the goals have been accomplished and type-checked,
we consider the program to be finished.
Often, there is not much point in running an Agda program,
because it is mostly about compile-time static constructions.
This is what programming and proving things looks like in Agda.

\section{Simply typed programming in Agda}

Since Agda was heavily influenced by Haskell, simply typed programming in Agda
is similar to that in Haskell.

\paragraph{Datatypes}

Unlike in other programming languages, there are no ``built-in''
datatypes such as \textit{Int}, \textit{String}, or \textit{Bool}.
The reason is that they can all be created out of thin air, so why
bother having them predefined?

Datatypes are introduced with {\lstinline|data|} declarations.
Here is a classical example, the type of booleans.

\begin{lstlisting}
data Bool : Set where
    true  : Bool
    false : Bool
\end{lstlisting}

This declaration brings the name of the datatype ({\lstinline|Bool|})
and its constructors ({\lstinline|true|} and {\lstinline|false|}) into scope.
The notation allow us to explicitly specify the types of these newly introduced
entities.

\begin{enumerate}
    \item {\lstinline|Bool|} has type {\lstinline|Set|}\footnote{{\lstinline|Set|} is the type of small types, and {\lstinline|Set₁|} is the type
of {\lstinline|Set|}, and so on. They form a hierarchy of types.}
    \item {\lstinline|true|} has type {\lstinline|Bool|}
    \item {\lstinline|false|} has type {\lstinline|Bool|}
\end{enumerate}

\paragraph{Pattern matching}

Similar to Haskell, datatypes are eliminated by pattern matching.
Here is a function that pattern matches on {\lstinline|Bool|}.

\begin{lstlisting}
not : Bool → Bool
not true  = false
not false = true
\end{lstlisting}

Agda is a \textit{total} language,
which means that partial functions are not valid constructions.
Programmers are obliged to convince Agda that a program terminates and does not
crash on all possible inputs.
The following example will not be accepted by the termination checker because the
case {\lstinline|false|} is missing.

\begin{lstlisting}
not : Bool → Bool
not true  = false
\end{lstlisting}

\paragraph{Inductive datatype} Let us move on to a more interesting datatype with
an inductive definition. Here is the type of natural numbers.

\begin{lstlisting}
data ℕ : Set where
    zero : ℕ
    suc : ℕ → ℕ
\end{lstlisting}

The decimal number ``4'' is represented as {\lstinline|suc (suc (suc (suc zero)))|}.
Agda also accepts decimal literals if the datatype {\lstinline|ℕ|} complies with
certain language pragma.

Addition on {\lstinline|ℕ|} can be defined as a recursive function.

\begin{lstlisting}
_+_ : ℕ → ℕ → ℕ
zero  + y = y
suc x + y = suc (x + y)
\end{lstlisting}

We define {\lstinline|_+_|} by pattern matching on the first argument, which results
in two cases: the base case, and the inductive step. We are allowed to make
recursive calls, as long as the type checker is convinced that the function
would terminate.

Those underlines surrounding {\lstinline|_+_|} act as placeholders for arguments, making
it an infix function in this instance.

\paragraph{Dependent functions and type arguments}

Up till now, everything looks much the same as in Haskell, but a problem arises as
we move on to defining something that needs more power of abstraction. Take identity
functions for example:

\begin{lstlisting}
id-Bool : Bool → Bool
id-Bool x = x

id-ℕ : ℕ → ℕ
id-ℕ x = x
\end{lstlisting}

In order to define a more general identity function, those concrete types need
to be abstracted away. That is, we need \textit{parametric polymorphism}, and this is
where dependent types come into play.

A dependent type is a type whose definition may depend on a value. A dependent
function is a function whose type may depend on a value of its arguments.

In Agda, function types are denoted as:

\begin{lstlisting}
A → B
\end{lstlisting}
%
where {\lstinline|A|} is the type of domain and {\lstinline|B|} is the type of
codomain. To let {\lstinline|B|} depends on the value of {\lstinline|A|}, the
value has to \textit{named}. In Agda we write:

\begin{lstlisting}
(x : A) → B x
\end{lstlisting}

The value of {\lstinline|A|} is named {\lstinline|x|} and then fed to {\lstinline|B|}.
As a matter of fact, {\lstinline|A → B|} is just a syntax sugar for {\lstinline|(_ : A) → B|}
with the name of the value being irrelevant. The underline {\lstinline|_|} here
means ``I don't bother naming it''.

Back to our identity function, if {\lstinline|A|} happens to be {\lstinline|Set|},
the type of all small types, and the result type happens to be solely {\lstinline|x|}:

\begin{lstlisting}
(x : Set) → x
\end{lstlisting}

Voila, we have polymorphism, and thus the identity function can now be defined as:

\begin{lstlisting}
id : (A : Set) → A → A
id A x = x
\end{lstlisting}

{\lstinline|id|} now takes an extra argument, the type of the second argument.
{\lstinline|id Bool true|} evaluates to {\lstinline|true|}.

\paragraph{Implicit arguments}

We have implemented an identity function and seen how polymorphism can be modeled
with dependent types. However, the additional argument that the identity function
takes is rather unnecessary, since its value can always be determined by looking
at the type of the second argument.

Fortunately, Agda supports \textit{implicit arguments}, a syntax sugar that could
save us the trouble of having to spell them out. Implicit arguments are enclosed
in curly brackets in the type expression. We are free to dispense with these arguments
when their values are irrelevant to the definition.

\begin{lstlisting}
id : {A : Set} → A → A
id x = x
\end{lstlisting}

Or when the type checker can figure them out on function application.

\begin{lstlisting}
val : Bool
val = id true
\end{lstlisting}

Any arguments can be made implicit, but it does not imply that values of
implicit arguments can always be inferred or derived from context. We can always
make them implicit arguments explicit on application:

\begin{lstlisting}
val : Bool
val = id {Bool} true
\end{lstlisting}

Or when they are relevant to the definition:

\begin{lstlisting}
silly-not : {_ : Bool} → Bool
silly-not {true}  = false
silly-not {false} = true
\end{lstlisting}

\paragraph{More syntax sugars}

We could skip arrows between arguments in parentheses or braces:

\begin{lstlisting}
id : {A : Set} (a : A) → A
id {A} x = x
\end{lstlisting}

Also, there is a shorthand for merging names of arguments of the same type, implicit or not:

\begin{lstlisting}
const : {A B : Set} → A → B → A
const a _ = a
\end{lstlisting}

Sometimes when the type of some value can be inferred, we could either replace
the type with an underscore, say {\lstinline|(A : _)|}, or we could write it as
{\lstinline|∀ A|}. For the implicit counterpart, {\lstinline|{A : _}|} can be
written as {\lstinline|∀ {A}|}.

\paragraph{Parameterized Datatypes}

Just as functions can be polymorphic, datatypes can be parameterized by other
types, too. The datatype of lists is defined as follows:

\begin{lstlisting}
data List (A : Set) : Set where
    []  : List A
    _∷_ : A → List A → List A
\end{lstlisting}

The scope of the parameters spreads over the entire declaration so that they can
appear in the constructors.
Here are the types of the datatype and its constructors.

\begin{lstlisting}
infixr 5 _∷_

[] : {A : Set} → List A
_∷_ : {A : Set} → A → List A → List A
List : Set → Set
\end{lstlisting}
%
where {\lstinline|A|} can be anything, even {\lstinline|List (List (List Bool))|},
as long as it is of type {\lstinline|Set|}. {\lstinline|infixr|} specifies the
precedence of the operator {\lstinline|_∷_|}.

\paragraph{Indexed Datatypes}

% Indexed datatypes, or inductive families, allow us to not only

{\lstinline|Vec|} is a datatype that is similar to {\lstinline|List|}, but more
powerful, in that it encodes not only the type of its element but also its
length.

\begin{lstlisting}
data Vec (A : Set) : ℕ → Set where
    []  : Vec A zero
    _∷_ : {n : ℕ} → A → Vec A n → Vec A (suc n)
\end{lstlisting}

{\lstinline|Vec A n|} is a vector of values of type {\lstinline|A|} and
has the length of {\lstinline|n|}. Here are some of its inhabitants:

\begin{lstlisting}
nil : Vec Bool zero
nil = []

vec : Vec Bool (suc (suc zero))
vec = true ∷ false ∷ []
\end{lstlisting}

We say that {\lstinline|Vec|} is \textit{parameterized} by a type of {\lstinline|Set|}
and is \textit{indexed} by values of {\lstinline|ℕ|}.
We distinguish indices from parameters. However, it is not obvious how they are
different by looking at the declaration.

Parameters are \textit{parametric}, in the sense that, they have no effect on the ``shape'' of a datatype.
The choice of parameters only effects which kind of values are placed there.
Pattern matching on parameters does not reveal any insights into their whereabouts.
Because they are \textit{uniform} across all constructors, one can always replace
the value of a parameter with another one of the same type.

On the other hand, indices may affect which inhabitants are allowed in the
datatype. Different constructors may have different indices. In that case, pattern
matching on indices may yield relevant information about their constructors.

For example, given a term whose type is {\lstinline|Vec Bool zero|},
then we are certain that the constructor must be {\lstinline|[]|},
and if the type is {\lstinline|Vec Bool (suc n)|} for some {\lstinline|n|},
then the constructor must be {\lstinline|_∷_|}.

We could, for instance, define a {\lstinline|head|} function that cannot crash.

\begin{lstlisting}
head : ∀ {A n} → Vec A (suc n) → A
head (x ∷ xs) = x
\end{lstlisting}

As a side note, parameters can be thought as a degenerate case of indices whose
distribution of values is uniform across all constructors.

\paragraph{With abstraction}

Say, we want to define {\lstinline|filter|} on {\lstinline|List|}:

\begin{lstlisting}
filter : ∀ {A} → (A → Bool) → List A → List A
filter p [] = []
filter p (x ∷ xs) = ?
\end{lstlisting}

We are stuck here because the result of {\lstinline|p x|} is only available at
runtime. Fortunately, with abstraction allows us to pattern match on the result
of an intermediate computation by adding the result as an extra argument on the
left-hand side:

\begin{lstlisting}
filter : ∀ {A} → (A → Bool) → List A → List A
filter p [] = []
filter p (x ∷ xs) with f x
filter p (x ∷ xs) | true  = x ∷ filter p xs
filter p (x ∷ xs) | false = filter p xs
\end{lstlisting}

\paragraph{Absurd patterns}

The \textit{unit type}, or \textit{top}, is a datatype inhabited by
exactly one value, denoted {\lstinline|tt|}.

\begin{lstlisting}
data ⊤ : Set where
    tt : ⊤
\end{lstlisting}

The \textit{empty type}, or \textit{bottom}, on the other hand, is a datatype
that is inhabited by nothing at all.

\begin{lstlisting}
data ⊥ : Set where
\end{lstlisting}

These types seem useless, and without constructors, it is impossible to
construct an instance of {\lstinline|⊥|}. What is an type that cannot be
constructed good for?

Say, we want to define a safe {\lstinline|head|} on {\lstinline|List|} that
does not crash on any inputs. Naturally, in a language like Haskell,
we would come up with a predicate like this to filter out empty lists
{\lstinline|[]|} before passing them to {\lstinline|head|}.

\begin{lstlisting}
non-empty : ∀ {A} → List A → Bool
non-empty []       = false
non-empty (x ∷ xs) = true
\end{lstlisting}

The predicate only works at runtime. It is impossible for the type
checker to determine whether the input is empty or not at compile time.

However, things are quite different quite in Agda. With \textit{top} and \textit{bottom},
we could do some tricks on the predicate, making it returns a \textit{Set}, rather
than a \textit{Bool}!

\begin{lstlisting}
non-empty : ∀ {A} → List A → Set
non-empty []       = ⊥
non-empty (x ∷ xs) = ⊤
\end{lstlisting}

Notice that now this predicate is returning a type. So we can use it in the type
expression. {\lstinline|head|} can thus be defined as:

\begin{lstlisting}
head : ∀ {A} → (xs : List A) → non-empty xs → A
head []       proof = ?
head (x ∷ xs) proof = x
\end{lstlisting}

In the {\lstinline|(x ∷ xs)|} case, the argument {\lstinline|proof|} would
have type {\lstinline|⊤|}, and the right-hand side is simply {\lstinline|x|};
in the {\lstinline|[]|} case, the argument {\lstinline|proof|} would
have type {\lstinline|⊥|}, but what should be returned at the right-hand side?

It turns out that, the right-hand side of the {\lstinline|[]|} case would be the
least thing to worry about because it is completely impossible to have such a case.
Recall that {\lstinline|⊥|} has no inhabitants, so if a case has an argument of
that type, it is too good to be true.

Type inhabitance is, in general, an undecidable problem.
However, when pattern matching on a type that is obviously empty (such as {\lstinline|⊥|}),
Agda allows us to drop the right-hand side and eliminate the argument with {\lstinline|()|}.

\begin{lstlisting}
head : ∀ {A} → (xs : List A) → non-empty xs → A
head []       ()
head (x ∷ xs) proof = x
\end{lstlisting}

Whenever {\lstinline|head|} is applied to some list {\lstinline|xs|},
the programmer is obliged to convince Agda that {\lstinline|non-empty xs|}
reduces to {\lstinline|⊤|},
which is only possible when {\lstinline|xs|} is not an empty list.
On the other hand, applying an empty list to {\lstinline|head|} would result in
a function of type {\lstinline|head [] : ⊥ → A|} which is impossible to
be fulfilled.

\paragraph{Propositions as types, proofs as programs}

The previous paragraphs are mostly about the \textit{programming}
aspect of the language, but there is another aspect to it.
Recall the Curry–Howard correspondence, propositions are types and proofs are
programs. A proof exists for a proposition the way that a value inhabits a type.

{\lstinline|non-empty xs|} is a type, but it can also be thought of as a
proposition stating that {\lstinline|xs|} is not empty.
When {\lstinline|non-empty xs|} evaluates to {\lstinline|⊥|}, no value inhabits
{\lstinline|⊥|}, which means no proof exists for the proposition {\lstinline|⊥|};
when {\lstinline|non-empty xs|} evaluates to {\lstinline|⊤|}, {\lstinline|tt|}
inhabits {\lstinline|⊥|}, a trivial proof exists for the proposition {\lstinline|⊤|}.

In intuitionistic logic, a proposition is considered to be ``true'' when it is
inhabited by a proof, and considered to be ``false'' when there exists no proof.
Contrary to classical logic, where every propositions are assigned one of two truth values.
We can see that {\lstinline|⊤|} and {\lstinline|⊥|} corresponds to \textit{true}
and \textit{false} in this sense.

Negation is defined as a function from a proposition to {\lstinline|⊥|}.

\begin{lstlisting}
¬ : Set → Set
¬ P = P → ⊥
\end{lstlisting}

We could exploit {\lstinline|⊥|} further to deploy the principle of explosion
of intuitionistic logic, which states that: ``from falsehood, anything (follows)''
(Latin: \textit{ex falso (sequitur) quodlibet}).

\begin{lstlisting}
⊥-elim : ∀ {Whatever : Set} → ⊥ → Whatever
⊥-elim ()
\end{lstlisting}

\paragraph{Decidable propositions}

A proposition is decidable when it can be proved \textit{or} disapproved.
\footnote{The connective \textit{or} here is not a disjunction in the classical sense.
Either way, a proof or a disproval has to be given.}

\begin{lstlisting}
data Dec (P : Set) : Set where
    yes :   P → Dec P
    no  : ¬ P → Dec P
\end{lstlisting}

{\lstinline|Dec|} is very similar to its two-valued cousin {\lstinline|Bool|},
but way more powerful, because it also explains (with a proof) why a proposition
holds or why it does not.

Suppose we want to know if a natural number is even or odd. We know that {\lstinline|zero|}
is an even number, and if a number is even then its successor's successor is even as well.

\begin{lstlisting}
    data Even : ℕ → Set where
        base : Even zero
        step : ∀ {n} → Even n → Even (suc (suc n))
\end{lstlisting}

We need the opposite of {\lstinline|step|} as a lemma as well.

\begin{lstlisting}
    2-steps-back : ∀ {n} → ¬ (Even n) → ¬ (Even (suc (suc n)))
    2-steps-back ¬p q = ?
\end{lstlisting}

{\lstinline|2-steps-back|} takes two arguments instead of one because the return
type {\lstinline|¬ (Even (suc (suc n)))|} is actually a synonym of
{\lstinline|Even (suc (suc n)) → ⊥|}. Pattern matching on the second argument
of type {\lstinline|Even (suc (suc n))|} further reveals that it could only be
constructed by {\lstinline|step|}.  By contradicting {\lstinline|¬p : ¬ (Even n)|}
and {\lstinline|p : Even n|}, we complete the proof of this lemma.

\begin{lstlisting}
    contradiction : ∀ {P Whatever : Set} → P → ¬ P → Whatever
    contradiction p ¬p = ⊥-elim (¬p p)

    two-steps-back : ∀ {n} → ¬ (Even n) → ¬ (Even (suc (suc n)))
    two-steps-back ¬p (step p) = contradiction p ¬p
\end{lstlisting}

Finally, {\lstinline|Even?|} determines a number be even by induction on its
predecessor's predecessor. {\lstinline|step|} and {\lstinline|two-steps-back|}
can be viewed as functions that transform proofs.

\begin{lstlisting}
    Even? : (n : ℕ) → Dec (Even n)
    Even? zero          = yes base
    Even? (suc zero)    = no (λ ())
    Even? (suc (suc n)) with Even? n
    Even? (suc (suc n)) | yes p = yes (step p)
    Even? (suc (suc n)) | no ¬p = no  (two-steps-back ¬p)
\end{lstlisting}

The syntax of {\lstinline|λ ()|} looks weird, as the result of contracting
an argument of type {\lstinline|⊥|} of a lambda expression {\lstinline|λ x → ?|}.
It is a convention to suffix a decidable function's name with {\lstinline|?|}.

\paragraph{Propositional equality}

Saying that two things are ``equal'' is a notoriously intricate topic in type theory.
There are many different notions of equality \cite{equality}.
We will not go into each kind of equalities in depth but only skim through those exist in Agda.

\textit{Definitional equality}, or \textit{intensional equality} is simply a
synonym, a relation between linguistic expressions. It is a primitive judgement
of the system, stating that two things are the same to the type checker
\textbf{by definition}.

\textit{Computational equality} is a slightly more powerful notion.
Two programs are consider equal if they compute (beta-reduce) to the same value.
For example, {\lstinline|1 + 1|} and {\lstinline|2|} are equal in Agda in this notion.

However, expressions such as {\lstinline|a + b|} and {\lstinline|b + a|} are not
considered equal by Agda, neither \textit{definitionally} nor \textit{computationally},
because there are simply no rules in Agda saying so.

{\lstinline|a + b|} and {\lstinline|b + a|} are only \textit{extensionally equal}
in the sense that, given \textbf{any} pair of numbers, say {\lstinline|1|} and {\lstinline|2|},
Agda can see that {\lstinline|1 + 2|} and {\lstinline|2 + 1|} are computationally equal.
But when it comes to \textbf{every} pair of numbers, Agda fails to justify that.

We could convince Agda about the fact that {\lstinline|a + b|} and {\lstinline|b + a|}
are equal for every pair of {\lstinline|a|} and {\lstinline|b|} by encoding this
theorem in a \textit{proposition} and then prove that the proposition holds.
This kind of proposition can be expressed with \textit{identity types}.

\begin{lstlisting}
data _≡_ {A : Set} (x : A) : A → Set where
    refl : x ≡ x
\end{lstlisting}

This inductive datatype says that: for all {\lstinline|a b : A|},
if {\lstinline|a|} and {\lstinline|b|} are \textit{computationally equal},
that is, both computes to the same value,
then {\lstinline|refl|} is a proof of {\lstinline|a ≡ b|},
and we say that {\lstinline|a|} and {\lstinline|b|} are \textit{propositionally equal}!

{\lstinline|_≡_|} is an equivalence relation. It means that {\lstinline|_≡_|}
is \textit{reflexive} (by definition), \textit{symmetric} and \textit{transitive}.

\begin{lstlisting}
sym : {A : Set} {a b : A} → a ≡ b → b ≡ a
sym refl = refl

trans : {A : Set} {a b c : A} → a ≡ b → b ≡ c → a ≡ c
trans refl refl = refl
\end{lstlisting}

{\lstinline|_≡_|} is congruent, meaning that we could \textbf{substitute equals for equals}.

\begin{lstlisting}
cong : {A B : Set} {a b : A} → (f : A → B) → a ≡ b → f a ≡ f b
cong f refl = refl
\end{lstlisting}

Although these {\lstinline|refl|}s look all the same at term level,
they are proofs of different propositional equalities.

\paragraph{Dotted patterns}

Consider an alternative version of {\lstinline|sym|} on {\lstinline|ℕ|}.

\begin{lstlisting}
sym' : (a b : ℕ) → a ≡ b → b ≡ a
sym' a b eq = ?
\end{lstlisting}
%
where {\lstinline|eq|} has type {\lstinline|a ≡ b|}.
If we pattern match on {\lstinline|eq|} then Agda would rewrite {\lstinline|b|}
as {\lstinline|.a|} and the goal type becomes {\lstinline|a ≡ a|}.
\begin{lstlisting}
sym' : (a .a : ℕ) → a ≡ a → a ≡ a
sym' a .a refl = ?
\end{lstlisting}

What happened under the hood is that {\lstinline|a|} and {\lstinline|b|} are
\textit{unified} as the same thing. The second argument is dotted to signify that
it is \textit{constrained} by the first argument {\lstinline|a|}. {\lstinline|a|}
becomes the only argument available for further binding or pattern matching.

\paragraph{Standard library}

It would be inconvenient if we have to construct everything we need from scratch.
Luckily, the community has maintained a standard library that comes with many useful
and common constructions.

The standard library is not ``chartered'' by the compiler or the type checker,
there's simply nothing special about it. We may as well as roll our own library.
\footnote{Some primitives that require special treatments, such as IO, are taken
care of by language pragmas provided by Agda.}

\end{document}


\chapter{SM-02}
Boltzman entrophy relation: $S=K \ln \Omega$\\
striling approximation: $\ln n !=n \ln n-n$\\
Number of microstates:
$\Omega_{M B}=\underset{i}{\pi}\left(g_{i}\right)^{n_{i}}$\\
$\Omega_{B E}=\underset{i}{\pi}\frac{\left(n_{i}+g_{i}-1\right) !}{n_{i} !(g i-1) !}$\\
${ }^{\Omega_{F D}}=\underset{i}{\pi}{g i }\  C_{n_{i}}$\\
$g_{i} \rightarrow$ degeneracy\\
$n_{i} \rightarrow$ identical Particles\\
Energy distribution function :$f(E)=\frac{n_{i}}{g_{i}}$
Q.The number of ways in which $N$ identical bosons can distributed in two energy levels is
 \begin{tasks}(4)
	\task[\textbf{a.}] $N+1$
	\task[\textbf{b.}]$N(N-1) \mid 2$
	\task[\textbf{c.}]$N(N+1) \mid 2$
	\task[\textbf{d.}]$N$
\end{tasks}
\begin{answer}
	\begin{align*}
	\Omega&=N_ {C_n}=\frac{N !}{n !(N-n) !}\hspace{2cm}\underset{\text{-------------- }e}{n}\\
	\text { entropy }(s)&=k \ln \Omega=k \ln \frac{N !}{n !(N-n) !}\hspace{1.1cm}\underset{\text{-------------- } 0}{(N-n)}\\
	\operatorname{s\alpha } &\ln \frac{N !}{n !(N-n) !}
	\end{align*}
		So the correct answer is \textbf{Option (d)}
\end{answer}
\begin{note}
	Probability will be maximum for equal distribution.
\end{note}
Q. Let $N_{M B}, N_{B E}, N_{F D}$ denote the number of ways in which two particles can be distributed in two energy states according to maxwell-Boltzmann, Bose-Einstein \& fermi-Dirac statistics respectively. Then $N_{M B}: N_{B E}: N_{F D}$ is:
 \begin{tasks}(4)
	\task[\textbf{a.}]$4: 3: 1$
	\task[\textbf{b.}] $4: 2: 3$
	\task[\textbf{c.}]$4: 3: 3$
	\task[\textbf{d.}] $4: 3: 2$
\end{tasks}
\begin{answer}
	\begin{align*}
	\Omega_{M B}&=\left(g_{i}\right)^{n_{i}}=(2)^{2} \Rightarrow 4 \\
	\Omega_{B E}&=\frac{\left(n_{i}+g_{i}-1\right) !}{n_{i} !((-i-1) !}=\frac{(2+2-1) !}{2 !(2-1) !}=\frac{3 !}{2 !}=3\\
	\Omega_{F D}&=g i C_{n_{i}}=\frac{2 !}{2 ! 1 !}=1\\
	&4:3:1
	\end{align*}
	So the correct answer is \textbf{Option (a)}
\end{answer}
Relative Probability: \\
$$r=\frac{P_1}{P_2}=\frac{\text{Probability of finding particle in same state}}{\text{Probability of finding particle in different state.}}$$
$r_{B E}: r_{M B}: r_{F \cdot D}=1: 1 / 2: 0$\\
$\Rightarrow U_{B E} \leqslant U_{M B} \leqslant U_{F D} \Rightarrow P_{B E} \leqslant P_{M B} \leqslant P_{F D}$ \\
Q If $N$ particle are to be distributed into two groups such that group i contain $n_1$ particles and group two contains $n_2$ particles, and $N=n_1+n_2$ Find the number of ways of distribution?
\begin{answer}
	\begin{align*}
	\Omega&={ }^{N} C_{n_{1}} \text { or }{ }^{N} C_{n_{2}} 4 N=n_{1}+n_{2}\\
	N_{C_{n_{i}}}&=\frac{N !}{n_{1} !(N-n) !}=\frac{N !}{n_{1} ! n_{2} !}\\
	&\text{similaarly, for $ni$ particles}\\
	\Omega&=\frac{N!}{n_1!n_2!.......n_i!}
	\end{align*}
\end{answer}
Q. A system has energy levels $E_{0}, 2 E_{0}, 3 E_{0}, \ldots .$ where the excited states are triphy generate four non-interacting bosons are placed in this system. If the total energy og these bosons is $5E_0$ the number of microstates is:
 \begin{tasks}(4)
	\task[\textbf{a.}]2
	\task[\textbf{b.}]3
	\task[\textbf{c.}]4
	\task[\textbf{d.}] 5
\end{tasks}
\begin{answer}
	\begin{figure}[H]
		\centering
		\includegraphics[height=4cm,width=6cm]{SP-12}
	\end{figure}
	So the correct answer is \textbf{Option (b)}
\end{answer}
\textbf{Phase Space}:(Position + momentum) space\\
volume of single phase cell: $d \tau=h^{f} \quad f \rightarrow D O F$\\
allowed vol. of phace space: $\int d^{3} q \int d^{3} p$\\
$$
V_{p} \Rightarrow V \times \frac{4}{3} \pi p^{3}\text{( for 3-Dim).}
$$
\textbf{Non-Relativistic Free Particle: }$E=p^2/2m$\\
\renewcommand*{\arraystretch}{1.8}
 \begin{tabular}{|p{4cm}|p{4cm}|p{4cm}|}
 	\hline
 3-Dimensional&2-Dimensional&1-Dimensional\\\hline
 $d \tau=h^{3}$&$d \tau=h^{2}$&$d \tau=h$\\\hline
 $V_{p}=V \times \frac{4}{3} \pi p^{3}$&$V_{p}=A \times \pi p^{2}$&$V_p=L\times2p$\\\hline
 $\Omega=\frac{V \cdot \frac{4}{3} \pi p^{3}}{\hbar^{3}}$&$\Omega(p)=\frac{\pi \times \pi p^{2}}{h^{2}}$&$\Omega(p)=\frac{L \times 2 p}{h}$\\\hline
 $\Omega(E)=\frac{\mu\pi V(2mE)^3}{3h^3}$&$\Omega(E)=\frac{\pi A(2mE)}{h^2}$&$\Omega(E)=\frac{2L\sqrt{2mE}}{h}$\\\hline
 $\Omega^{\prime}(E)=\frac{2 \pi V(2 m)^{3 / 2} E^{1 / 2}}{h^2}dE$&$\Omega^{\prime}(E)=\frac{2 \pi mA}{h^3}dE$&$\Omega^{\prime}(E)=\frac{L(2m)^{1/2}E^{-1/2}}{h}dE$\\\hline
 \end{tabular}
\begin{figure}[H]
	\includegraphics[height=5.5cm,width=13cm]{SP-13}
\end{figure}
\begin{exercise}
	In a classical microcanonical ensemble for a system of $N$ non-interacting particles, the fundamental volume of phase space which is regarded as "equivalent to one-microstate" is
\end{exercise}
 \begin{tasks}(4)
	\task[\textbf{a.}] $h^{3 N}$
	\task[\textbf{b.}]$h^{2 N}$
	\task[\textbf{c.}]$h^{N}$
	\task[\textbf{d.}]$h$
\end{tasks}
\begin{answer}
	\begin{align*}
	\text{For $N$ non-interacting particles }\text { DOF }&=3 N=f\\
	\text{volume of phase space }&=h^{f}\\
	&=R^{3 N}
	\end{align*}
	So the correct answer is \textbf{Option (a)}
\end{answer}
\textbf{Extremely Relativistic Free Particle: }(E=pc)\\
\renewcommand*{\arraystretch}{1.8}
\begin{tabular}{|p{4cm}|p{4cm}|p{4cm}|}
	\hline
	3-Dimensions & 2-Dimensions & 1-Dimensions\\\hline
	$\Omega(p)=\frac{v \cdot \frac{4}{3} \pi p^{3}}{h^{3}}$&$\Omega(p)=\frac{\pi A p^{2}}{h^{2}}$&$\Omega(p)=\frac{L \times 2 p}{h}$\\
	$\Omega^{\prime}(p)=\frac{4 \pi V p^{2} d p}{h^{3}}$&$\Omega^{\prime}(p)=\frac{2 \pi A p d p}{h^{2}}$&$\Omega^{\prime}(p)=\frac{2 L d p}{h}$\\\hline
	$\Omega(E)=\frac{4 \pi V E^{3}}{3 c^{3} h^{3}}$&$\Omega(E)=\frac{A \pi E^{2}}{C^{2} n^{2}}$&$\Omega(E)=\frac{2 L E}{\hbar c}$\\
	$\Omega(E)=2 \times \frac{4 \pi v\left(E^{2}\right)}{c^{3} h^{3}} d E$&$\Omega^{\prime}(E)=\frac{2 \pi A E}{C^{2} h^{2}}$&$\Omega^{\prime}(E)=\frac{2 L}{R C} d E$\\\hline
\end{tabular}
Q. Find density of states at energy $E$ of the quantized radiation (photon) is:
 \begin{tasks}(4)
	\task[\textbf{a.}]$\frac{8 \pi v}{h^{3} c^{3}} E^{2}$
	\task[\textbf{b.}]$\frac{8 \pi V}{h^{3} c^{3}} E^{3 / 2}$
	\task[\textbf{c.}]$\frac{8 \pi V}{h^{3} c^{3}} E$
	\task[\textbf{d.}] $\frac{8 \pi V}{h^{3} c^{3}} E^{3 / 2}$
\end{tasks}
\begin{answer}
	\begin{align*}
	\Omega(p)&=\frac{V \times \frac{4}{3} \pi p^{3}}{h^{3}} \Rightarrow \Omega(E)=\frac{4 \pi V E^{3}}{3 c^{3} h^{3}}\\
	\Omega^{\prime}(E)&=\left(\frac{4 \pi V E^{2}}{c^{3} h^{3}} d E\right) \times 2\\
	\Omega^{\prime}(E)&=g(E) d E\\
	g(E)&=\frac{8 \pi V}{c^{3} h^{3}} E^{2}
	\end{align*}
	So the correct answer is \textbf{Option (a)}
\end{answer}
Q. \textbf{For free particle (with $E=ap^s$) with d-DOF: }\\
\begin{align*}
\text{Volume of sphere of radius (R) }V_{d}&=\frac{\pi^{d / 2} R^{d}}{\left(\frac{d}{2}\right) !}\\
\text{area of sphere of radius (R) }s_{d}&=\frac{2 \pi^{d / 2} R^{d-1}}{\left(\frac{d}{2}-1\right) !}\\
\text{ volume of single phase cell }d \tau&=h^{d}\\
g(E)&=\frac{g i V_{d} \pi^{d / 2}\left(\frac{1}{a}\right)^{d / s}\left(\frac{d}{s}\right) E^{(d / s-1)}}{R^{d}(d / 2) !}\\
&g(E) \propto E^{(d / s-1)}\hspace{3cm}d=DOF\\
s=1 \text{(marsless)},\quad
2 \text{(massive)}
\end{align*}
\begin{exercise}
	For an energy state $E$ of a photon gas, the density of states is proportional to
\end{exercise}
 \begin{tasks}(4)
	\task[\textbf{a.}] $\sqrt{E}$
	\task[\textbf{b.}] $E $
	\task[\textbf{c.}]$E^{3 / 2}$
	\task[\textbf{d.}] $E^{2}$
\end{tasks}
\begin{answer}
	\begin{align*}
	D(E) &\propto E^{\left(\frac{d}{s}-1\right)}\\
	\text { For proton: } d&=3 \text { and } s=1\\
	D(E) \propto E^{3-1} &\Rightarrow D(E) \alpha E^{2}
	\end{align*}
		So the correct answer is \textbf{Option (d)}
\end{answer}
\begin{exercise}
 The number of states for a system of $N$ indentical free particles in a three dimensional space having total energy between $E$ and $E+\delta E(\delta E<<E),$ is proportional to
\end{exercise}
 \begin{tasks}(4)
	\task[\textbf{a.}]$E^{\left(\frac{3 N}{2}-1\right)} \delta E$
	\task[\textbf{b.}]$E^{\frac{N}{2}} \delta E$
	\task[\textbf{c.}]$N E^{\frac{1}{2}} \delta E$
	\task[\textbf{d.}]$N^{N} \delta E$
\end{tasks}
\begin{answer}
	\begin{align*}
	D(E) &\propto E^{(d / s-1)}\\
	\text { Here } d&=3 \mathrm{~N} \text { and } s=2 \text { (massive) }\\
	D(E) &\propto E^{\left(\frac{3 N}{2}-1\right)}
	\end{align*}
		So the correct answer is \textbf{Option (a)}
\end{answer}
\begin{exercise}
 Draw phase space trajectory of linear (1-dimension) Harmonic oscillator and calculate number of microstate if particle has:\\
	a). sharp value of energy\\
	b). Energy lies between $E$ to $E+d E$
\end{exercise}
\begin{answer}
	\begin{align*}
	E&=\frac{p^{2}}{2 m}+\frac{1}{2} m \omega^2 x^{2}\\
	1&=\frac{p^{2}}{\sqrt{2 m E}}+\frac{x^{2}}{\left(\sqrt{\frac{2 E}{m \omega^2}}\right)^{2}}\\
	\text{area of ellipse }&=\pi a b\\
	\text{volume of single phase cell }&(1-D)=h\\
	\Omega(E)=\frac{\pi a b}{h}&=\frac{\pi \times \sqrt{\frac{2 E}{m \omega^2}}  \times \sqrt{2 m E}}{h}\\
	\Omega(E)&=\frac{2 \pi E}{h \omega}=\frac{E}{h \omega}\\
	\Omega^{\prime}(E)&=\frac{d E}{\hbar \omega}
	\end{align*}
\end{answer}
\begin{note}
	\begin{align*}
	\text{	maxinum valle of }&x \\
\text{	on }x-\text{axis: }p&=0 \hspace{3cm}x_{0}=\sqrt{\frac{2 E_{0}}{m \omega^{2}}}\\
	E_{0}&=0+\frac{1}{2} m u^{2} x_{0}^{2}\hspace{2cm}x_{0} \alpha \sqrt{E_{0}}\\
	\end{align*}
\end{note}

\newpage
\begin{abox}
	Practise set-1
\end{abox}
\begin{enumerate}
	\item Consider an ideal Bose gas in three dimensions with the energy-momentum relation $\varepsilon \propto p^{s}$ with $s>0$. The range of $s$ for which this system may undergo a Bose-Einstein condensation at a non-zero temperature is
{\exyear{NET/JRF(JUNE-2011)}}
\begin{tasks}(4)
\task[\textbf{A.}] $1<s<3$
\task[\textbf{B.}] $0<s<2$
\task[\textbf{C.}] $0<s<3$
\task[\textbf{D.}] $0<s<\infty$
\end{tasks}

\item The internal energy $E$ of a system is given by $E=\frac{b S^{3}}{V N}$, where $b$ is a constant and other symbols have their usual meaning. The temperature of this system is equal to
{\exyear{NET/JRF(JUNE-2011)}}
\begin{tasks}(4)
\task[\textbf{A.}] $\frac{b S^{2}}{V N}$
\task[\textbf{B.}] $\frac{3 b S^{2}}{V N}$
\task[\textbf{C.}]  $\frac{b S^{3}}{V^{2} N}$
\task[\textbf{D.}] $\left(\frac{S}{N}\right)^{2}$
\end{tasks}

\item Consider a Maxwellian distribution of the velocity of the molecules of an ideal gas. Let $V_{m p}$ and $V_{r m s}$ denote the most probable velocity and the root mean square velocity, respectively. The magnitude of the ratio $V_{m p} / V_{r m s}$ is
{\exyear{NET/JRF(DEC-2011)}}
\begin{tasks}(4)
\task[\textbf{A.}] (a) 1
\task[\textbf{B.}] $2 / 3$
\task[\textbf{C.}] $\sqrt{2 / 3}$
\task[\textbf{D.}] $3 / 2$
\end{tasks}

\item If the number density of a free electron gas in three dimensions is increased eight times, its Fermi temperature will
{\exyear{NET/JRF(DEC-2011)}}
\begin{tasks}(2)
\task[\textbf{A.}] Increase by a factor of 4
\task[\textbf{B.}] Decrease by a factor of 4
\task[\textbf{C.}] Increase by a factor of 8
\task[\textbf{D.}] Decrease by a factor of 8
\end{tasks}

\item A one-dimensional chain consists of a set of $N$ rods each of length $a$. When stretched by a load, each rod can align either parallel or perpendicular to the length of the chain. The energy of a rod is $-\varepsilon$ when perpendicular to it. When the chain is in thermal equilibrium at temperature $T$, its average length is
{\exyear{NET/JRF(DEC-2011)}}
\begin{tasks}(2)
\task[\textbf{A.}] $\mathrm{Na} / 2$
\task[\textbf{B.}] $\mathrm{Na}$
\task[\textbf{C.}] $N a /\left(1+e^{-2 \varepsilon / k_{B} T}\right)$
\task[\textbf{D.}] $N a\left(1+e^{-2 \varepsilon / k_{B} T}\right)$
\end{tasks}

\item The excitations of a three-dimensional solid are bosonic in nature with their frequency $\omega$ and wave-number $k$ are related by $\omega \propto k^{2}$ in the large wavelength limit. If the chemical potential is zero, the behavior of the specific heat of the system at low temperature is proportional to
{\exyear{NET/JRF(DEC-2011)}}
\begin{tasks}(4)
\task[\textbf{A.}] $T^{1 / 2}$
\task[\textbf{B.}] $T$
\task[\textbf{C.}]  $T^{3 / 2}$
\task[\textbf{D.}] $T^{3}$
\end{tasks}

\item Gas molecules of mass $m$ are confined in a cylinder of radius $R$ and height $L$ (with $R>>L$ ) kept vertically in the Earth's gravitational field. The average energy of the gas at low temperatures (such that $m g L>>k_{B} T$ ) is given by
{\exyear{NET/JRF(DEC-2011)}}

\begin{tasks}(4)
\task[\textbf{A.}] (a) $N k_{B} T / 2$
\task[\textbf{B.}] $3 N k_{B} T / 2$
\task[\textbf{C.}] $2 N k_{B} T$
\task[\textbf{D.}] $5 N k_{B} T / 2$
\end{tasks}

\item Consider a system of non-interacting particles in $d$ dimensional obeying the dispersion relation $\varepsilon=A k^{s}$, where $\varepsilon$ is the energy, $k$ is the wave vector; $s$ is an integer and $A$ is constant. The density of states, $N(\varepsilon)$, is proportional to
{\exyear{NET/JRF(JUNE-2012)}}

\begin{tasks}(4)
\task[\textbf{A.}] $\varepsilon^{\frac{s}{d}-1}$
\task[\textbf{B.}] $\varepsilon^{\frac{d}{s}-1}$
\task[\textbf{C.}] $\varepsilon^{\frac{d}{s}+1}$
\task[\textbf{D.}] $\varepsilon^{\frac{s}{d}+1}$
\end{tasks}

\item The number of ways in which $\mathrm{N}$ identical bosons can be distributed in two energy levels, is
{\exyear{NET/JRF(JUNE-2012)}}
\begin{tasks}(4)
\task[\textbf{A.}] $N+1$
\task[\textbf{B.}] $\frac{N(N-1)}{2}$
\task[\textbf{C.}] $\frac{N(N+1)}{2}$
\task[\textbf{D.}] $N$
\end{tasks}

\item The free energy of the gas of $N$ particles in a volume $V$ and at a temperature $T$ is $F=N k_{B} T \ln \left[a_{0} V\left(k_{B} T\right)^{5 / 2} / N\right]$, where $a_{0}$ is a constant and $k_{B}$ denotes the Boltzmann constant. The internal energy of the gas is
{\exyear{NET/JRF(JUNE-2012)}}

\begin{tasks}(2)
\task[\textbf{A.}] $\frac{3}{2} N k_{B} T$
\task[\textbf{B.}] $\frac{5}{2} N k_{B} T$
\task[\textbf{C.}] $N k_{B} T \ln \left[a_{0} V\left(k_{B} T\right)^{5 / 2} / N\right]-\frac{3}{2} N k_{B} T$
\task[\textbf{D.}] $N k_{B} T \ln \left[a_{0} V /\left(k_{B} T\right)^{5 / 2}\right]$
\end{tasks}

\item A system has two normal modes of vibration, with frequencies $\omega_{1}$ and $\omega_{2}=2 \omega_{1} .$ What is the probability that at temperature $T$, the system has an energy less than $4 \hbar \omega_{1}$ ?
[In the following $x=e^{-\beta \hbar \omega_{1}}$ and $Z$ is the partition function of the system.]
{\exyear{NET/JRF(JUNE-2012)}}

\begin{tasks}(2)
\task[\textbf{A.}] $x^{3 / 2}\left(x+2 x^{2}\right) / Z$
\task[\textbf{B.}] $x^{3 / 2}\left(1+x+x^{2}\right) / Z$
\task[\textbf{C.}] $x^{3 / 2}\left(1+2 x^{2}\right) / Z$
\task[\textbf{D.}]  $x^{3 / 2}\left(1+x+2 x^{2}\right) / Z$
\end{tasks}

\item Bose condensation occurs in liquid $H e^{4}$ kept at ambient pressure at $2.17 K$. At which temperature will Bose condensation occur in $H e^{4}$ in gaseous state, the density of which is 1000 times smaller than that of liquid $H e^{4}$ ? (Assume that it is a perfect Bose gas.)
{\exyear{NET/JRF(JUNE-2012)}}

\begin{tasks}(4)
\task[\textbf{A.}] $2.17 \mathrm{mK}$
\task[\textbf{B.}] $21.7 \mathrm{mK}$
\task[\textbf{C.}] $21.7 \mu K$
\task[\textbf{D.}] $2.17 \mu K$
\end{tasks}

\item Consider black body radiation contained in a cavity whose walls are at temperature $T$. The radiation is in equilibrium with the walls of the cavity. If the temperature of the walls is increased to $2 T$ and the radiation is allowed to come to equilibrium at the new temperature, the entropy of the radiation increases by a factor of
{\exyear{NET/JRF(JUNE-2012)}}

\begin{tasks}(4)
\task[\textbf{A.}] 2
\task[\textbf{B.}] 4
\task[\textbf{C.}] 8
\task[\textbf{D.}] 16
\end{tasks}

\item Consider a one-dimensional Ising model with $N$ spins, at very low temperatures when almost all spins are aligned parallel to each other. There will be a few spin flips with each flip costing an energy $2 J .$ In a configuration with $r$ spin flips, the energy of the system is $E=-N J+2 r J$ and the number of configuration is ${ }^{N} C_{r} ; r$ varies from 0 to $N$. The partition function is
{\exyear{NET/JRF(DEC-2012)}}

\begin{tasks}(4)
\task[\textbf{A.}] $\left(\frac{J}{k_{B} T}\right)^{N}$
\task[\textbf{B.}]  $e^{-N J / k_{B} T}$
\task[\textbf{C.}] $\left(\sinh \frac{J}{k_{B} T}\right)^{N}$
\task[\textbf{D.}] $\left(\cosh \frac{J}{k_{B} T}\right)^{N}$
\end{tasks}

\item Consider a system of three spins $S_{1}, S_{2}$ and $S_{3}$ each of which can take values $+1$ and $-1 .$ The energy of the system is given by $E=-J\left[S_{1} S_{2}+S_{2} S_{3}+S_{3} S_{1}\right]$ where $J$ is a positive constant. The minimum energy and the corresponding number of spin configuration are, respectively,
{\exyear{NET/JRF(DEC-2012)}}

\begin{tasks}(4)
\task[\textbf{A.}] $J$ and 1
\task[\textbf{B.}] $-3 J$ and 1
\task[\textbf{C.}] $-3 J$ and 2
\task[\textbf{D.}] $-6 J$ and 2
\end{tasks}
\newcommand*{\downuparrow}[1]{\ensuremath{\overset{\uparrow}{#1}}}
\newcommand*{\downdownarrow}[1]{\ensuremath{\overset{\downarrow}{#1}}}

	\item A system of non-interacting spin-1/2 charged particles are placed in an extemal magnetic field. At low temperature $T$, the leading behavior of the excess energy above the ground state energy, depends on $T$ as: $(c$ is a constant)
	{\exyear{NET/JRF(JUNE-2013)}}

\begin{tasks}(2)
	\task[\textbf{A.}] $c T$
	\task[\textbf{B.}]  $c T^{3}$
	\task[\textbf{C.}] $e^{-c / T}$
	\task[\textbf{D.}] $c$ (is independent of $T$ )
\end{tasks}

	\item Consider a system of two Ising spins $S_{1}$ and $S_{2}$ taking values $\pm 1$ with interaction energy given by $\varepsilon=-J S_{1} S_{2}$, when it is in thermal equilibrium at temperature $T$. For large $T$, the average energy of the system varies as $C / k_{B} T$, with $C$ given by
	{\exyear{NET/JRF(JUNE-2013)}}

\begin{tasks}(4)
	\task[\textbf{A.}]  $-2 J^{2}$
	\task[\textbf{B.}] $-J^{2}$
	\task[\textbf{C.}] $J^{2}$
	\task[\textbf{D.}] $4 J$
\end{tasks}

	\item Consider two different systems each with three identical non-interacting particles. Both have single particle states with energies $\varepsilon_{0}, 3 \varepsilon_{0}$ and $5 \varepsilon_{0},\left(\varepsilon_{0}>0\right)$. One system is populated by spin $-\frac{1}{2}$ fermions and the other by bosons. What is the value of $E_{F}-E_{B}$ where $E_{F}$ and $E_{B}$ are the ground state energies of the fermionic and bosonic systems respectively?
    	{\exyear{NET/JRF(JUNE-2013)}}

\begin{tasks}(4)
	\task[\textbf{A.}] $6 \varepsilon_{0}$
	\task[\textbf{B.}] $2 \varepsilon_{0}$
	\task[\textbf{C.}] $4 \varepsilon_{0}$.
	\task[\textbf{D.}] $\varepsilon_{0}$
\end{tasks}

	\item Three identical spin- $\frac{1}{2}$ fermions are to be distributed in two non-degenerate distinct energy levels. The number of ways this can be done is
	{\exyear{NET/JRF(DEC-2013)}}

\begin{tasks}(4)
	\task[\textbf{A.}] 8
	\task[\textbf{B.}] 4
	\task[\textbf{C.}] 3
	\task[\textbf{D.}] 2
\end{tasks}

	\item Which of the graphs below gives the correct qualitative behaviour of the energy density $E_{r}(\lambda)$ of blackbody radiation of wavelength $\lambda$ at two temperatures $T_{1}$ and $T_{2}\left(T_{1}<T_{2}\right) ?$
	{\exyear{NET/JRF(JUNE-2014)}}

\begin{tasks}(2)
	\task[\textbf{A.}] \begin{figure}[H]
		\centering
		\includegraphics[height=4cm,width=5cm]{diagram-20210924(10)-crop}
	\end{figure}
	\task[\textbf{B.}] \begin{figure}[H]
		\centering
		\includegraphics[height=4cm,width=5cm]{diagram-20210924(11)-crop}
	\end{figure}
	\task[\textbf{C.}] \begin{figure}[H]
		\centering
		\includegraphics[height=4cm,width=5cm]{diagram-20210924(12)-crop}
	\end{figure}
	\task[\textbf{D.}] \begin{figure}[H]
		\centering
		\includegraphics[height=4cm,width=5cm]{diagram-20210924(13)-crop}
	\end{figure}
\end{tasks}

	\item The pressure of a non-relativistic free Fermi gas in three-dimensions depends, at $T=0$, on the density of fermions $n$ as
	{\exyear{NET/JRF(JUNE-2014)}}
\begin{tasks}(4)
	\task[\textbf{A.}] $n^{5 / 3}$
	\task[\textbf{B.}] $n^{1 / 3}$
	\task[\textbf{C.}]  $n^{2 / 3}$
	\task[\textbf{D.}] $n^{4 / 3}$
\end{tasks}

	\item A collection $N$ of non-interacting spins $S_{i}, i=1,2, \ldots ., N,\left(S_{i}=\pm 1\right)$ is kept in an external magnetic field $B$ at a temperature $T .$ The Hamiltonian of the system is $H=-\mu B \Sigma_{i} S_{i} .$ What should be the minimum value of $\frac{\mu B}{k_{B} T}$ for which the mean value $\left\langle S_{i}\right\rangle \geq \frac{1}{3} ?$
	{\exyear{NET/JRF(DEC-2014)}}
\begin{tasks}(4)
	\task[\textbf{A.}]  $\frac{1}{2} N \ln 2$
	\task[\textbf{B.}] $2 \ln 2$
	\task[\textbf{C.}] $\frac{1}{2} \ln 2$
	\task[\textbf{D.}]  $N \ln 2$
\end{tasks}

	\item Consider three Ising spins at the vertices of a triangle which interact with each other with a ferromagnetic Ising interaction of strength $J .$ The partition function of the system at temperature $T$ is given by $\left(\beta=\frac{1}{k_{B} T}\right):$
	{\exyear{NET/JRF(JUNE-2015)}}

\begin{tasks}(2)
	\task[\textbf{A.}]  $2 e^{3 \beta J}+6 e^{-\beta J}$
	\task[\textbf{B.}] $2 e^{-3 \beta J}+6 e^{\beta J}$
	\task[\textbf{C.}] $2 e^{3 \beta J}+6 e^{-3 \beta J}+3 e^{\beta J}+3 e^{-\beta J}$
	\task[\textbf{D.}] $(2 \cosh \beta J)^{3}$
\end{tasks}

	\item An ideal Bose gas in $d$-dimensions obeys the dispersion relation $\in(\vec{k})=A k^{s}$, where $A$ and $s$ are constants. For Bose-Einstein condensation to occur, the occupancy of excited states
	$$
	N_{e}=c \int_{0}^{\infty} \frac{\epsilon^{\frac{(d-s)}{s}}}{\left(e^{\beta(\epsilon-\mu)}-1\right)} d \in
	$$
	where $c$ is a constant, should remain finite even for $\mu=0$. This can happen if
	{\exyear{NET/JRF(JUNE-2015)}}

\begin{tasks}(4)
	\task[\textbf{A.}] $\frac{d}{s}<\frac{1}{4}$
	\task[\textbf{B.}] $\frac{1}{4}<\frac{d}{s}<\frac{1}{2}$
	\task[\textbf{C.}] $\frac{d}{s}>1$
	\task[\textbf{D.}] $\frac{1}{2}<\frac{d}{s}<1$
\end{tasks}

	\item For a system of independent non interacting one-dimensional oscillators, the value of the free energy per oscillator, in the limit $T \rightarrow 0$, is
	{\exyear{NET/JRF(DEC-2015)}}
\begin{tasks}(4)
	\task[\textbf{A.}] $\frac{1}{2} \hbar \omega$
	\task[\textbf{B.}] $\hbar \omega$
	\task[\textbf{C.}] $\frac{3}{2} \hbar \omega$
	\task[\textbf{D.}] 0
\end{tasks}

\end{enumerate}
\colorlet{ocre1}{ocre!70!}
\colorlet{ocrel}{ocre!30!}
\setlength\arrayrulewidth{1pt}
\begin{table}[H]
	\centering
	\arrayrulecolor{ocre}
	\begin{tabular}{|p{1.5cm}|p{1.5cm}||p{1.5cm}|p{1.5cm}|}
		\hline
		\multicolumn{4}{|c|}{\textbf{Answer key}}\\\hline\hline
		\rowcolor{ocrel}Q.No.&Answer&Q.No.&Answer\\\hline
		1&\textbf{A} &2&\textbf{B}\\\hline
		3&\textbf{C} &4&\textbf{A} \\\hline
		5&\textbf{C} &6&\textbf{C} \\\hline
		7&\textbf{D}&8&\textbf{B}\\\hline
		9&\textbf{A}&10&\textbf{B}\\\hline
		11&\textbf{D} &12&\textbf{B}\\\hline
		13&\textbf{C}&14&\textbf{D}\\\hline
		15&\textbf{C}&16 &\textbf{C}\\\hline
		17&\textbf{B}&18 &\textbf{B}\\\hline
		19&\textbf{B}&20 &\textbf{C}\\\hline
		21&\textbf{A}&22 &\textbf{C}\\\hline
		23&\textbf{B}&24 &\textbf{C}\\\hline
		25 &\textbf{A}& &\\\hline
	\end{tabular}
\end{table}
\begin{abox}
	Practise set-2
\end{abox}
\begin{enumerate}
	\item Consider a system of two particles $A$ and $B$. Each particle can occupy one of three possible quantum states $|1\rangle,|2\rangle$ and $|3\rangle$. The ratio of the probability that the two particles
	are in the same state to the probability that the two particles are in different states is calculated for bosons and classical (Maxwell-Boltzmann) particles. They are respectively
	{\exyear{JEST 2013}}

	\begin{tasks}(4)
		\task[\textbf{A.}] 1,0
		\task[\textbf{B.}]  $\frac{1}{2}, 1$
		\task[\textbf{C.}] $1, \frac{1}{2}$
		\task[\textbf{D.}] $0, \frac{1}{2}$
	\end{tasks}

	\item Consider three situations of 4 particles in one dimensional box of width $L$ with hard walls. In case (i), the particles are fermions, in case (ii) they are bosons, and in case (iii) they are classical. If the total ground state energy of the four particles in these three cases are $E_{F}, E_{B}$ and $E_{c l}$ respectively, which of the following is true?
	{\exyear{JEST 2013}}
		\begin{tasks}(2)
		\task[\textbf{A.}] $E_{F}=E_{B}=E_{c l}$
		\task[\textbf{B.}] $E_{F}>E_{B}=E_{c l}$
		\task[\textbf{C.}] $E_{F}<E_{B}<E_{c l}$
		\task[\textbf{D.}] $E_{F}>E_{B}>E_{c l}$
	\end{tasks}

	\item If the mean square fluctuations in energy of a system in equilibrium at temperature $T$ is proportional to $T^{\alpha}$, then the energy of the system is proportional to
	{\exyear{JEST 2017}}
	\begin{tasks}(4)
		\task[\textbf{A.}] $T^{\alpha-2}$
		\task[\textbf{B.}] $T^{\frac{\alpha}{2}}$
		\task[\textbf{C.}] $T^{\alpha-1}$
		\task[\textbf{D.}] $T^{\alpha}$
	\end{tasks}
	\item For a two-dimensional free electron gas, the electronic density $\mathrm{n}$, and the Fermi energy $\mathrm{E}_{\mathrm{F}}$, are related by
	{\exyear{GATE 2010}}
	\begin{tasks}(4)
		\task[\textbf{A.}] $n=\frac{\left(2 m E_{F}\right)^{3 / 2}}{3 \pi^{2} \hbar^{3}}$
		\task[\textbf{B.}] $n=\frac{m E_{F}}{\pi \hbar^{2}}$
		\task[\textbf{C.}] $n=\frac{m E_{F}}{2 \pi \hbar^{2}}$
		\task[\textbf{D.}] $n=\frac{\left(2 m E_{F}\right)^{3 / 2}}{\pi \hbar}$
	\end{tasks}

	\item For an ideal Fermi gas in three dimensions, the electron velocity $V_{F}$ at the Fermi surface is related to electron concentration $n$ as,
	{\exyear{GATE 2012}}

	\begin{tasks}(4)
		\task[\textbf{A.}] $V_{F} \propto n^{2 / 3}$
		\task[\textbf{B.}]  $V_{F} \propto n$
		\task[\textbf{C.}] $V_{F} \propto n^{1 / 2}$
		\task[\textbf{D.}] $V_{F} \propto n^{1 / 3}$
	\end{tasks}

	\item The total energy, $E$ of an ideal non-relativistic Fermi gas in three dimensions is given by $E \propto \frac{N^{5 / 3}}{V^{2 / 3}}$, where $N$ is the number of particles and $V$ is the volume of the gas. Identify the CORRECT equation of state ( $P$ being the pressure),
	{\exyear{GATE 2012}}
	\begin{tasks}(4)
		\task[\textbf{A.}] $P V=\frac{1}{3} E$
		\task[\textbf{B.}] $P V=\frac{2}{3} E$
		\task[\textbf{C.}] $P V=E$
		\task[\textbf{D.}] $P V=\frac{5}{3} E$
	\end{tasks}

	\item Consider a linear collection of $N$ independent spin $1 / 2$ particles, each at a fixed location. The entropy of this system is $(k$ is the Boltzmann constant)
	{\exyear{GATE 2013}}
	\begin{tasks}(4)
		\task[\textbf{A.}] Zero
		\task[\textbf{B.}]  $N k$
		\task[\textbf{C.}]  $\frac{1}{2} N k$
		\task[\textbf{D.}] $N k \ln (2)$
	\end{tasks}

	\item Two identical fermions
	{\exyear{GATE 2013}}
	\begin{tasks}(2)
		\task[\textbf{A.}] $e^{-2 \beta E}+e^{-4 \beta E}+e^{-6 \beta E}+e^{-8 \beta E}$
		\task[\textbf{B.}] $e^{-3 \beta E}+e^{-4 \beta E}+e^{-5 \beta E}+e^{-6 \beta E}+e^{-7 \beta E}$
		\task[\textbf{C.}] $\left(e^{-\beta E}+e^{-2 \beta E}+e^{-3 \beta E}+e^{-4 \beta E}\right)^{2}$
		\task[\textbf{D.}] $e^{-2 \beta E}-e^{-4 \beta E}+e^{-6 \beta E}-e^{-8 \beta E}$
	\end{tasks}

	\begin{minipage}{\textwidth}
		\item Two distinguishable particles
		{\exyear{GATE 2014}}
	\end{minipage}
	\begin{tasks}(2)
		\task[\textbf{A.}] $e^{-2 \beta E}+e^{-4 \beta E}+e^{-6 \beta E}+e^{-8 \beta E}$
		\task[\textbf{B.}] $e^{-3 \beta E}+e^{-4 \beta E}+e^{-5 \beta E}+e^{-6 \beta E}+e^{-7 \beta E}$
		\task[\textbf{C.}] $\left(e^{-\beta E}+e^{-2 \beta E}+e^{-3 \beta E}+e^{-4 \beta E}\right)^{2}$
		\task[\textbf{D.}] $e^{-2 \beta E}-e^{-4 \beta E}+e^{-6 \beta E}-e^{-8 \beta E}$
	\end{tasks}

	\item For a system of two bosons each of which can occupy any of the two energy levels 0 and $\varepsilon$. The mean energy of the system at temperature $T$ with $\beta=\frac{1}{k_{\beta} T}$ is given by
	{\exyear{GATE 2014}}

	\begin{tasks}(4)
		\task[\textbf{A.}] $\frac{\varepsilon e^{-\beta \varepsilon}+2 \varepsilon e^{-2 \beta \varepsilon}}{1+2 e^{-\beta \varepsilon}+e^{-2 \beta \varepsilon}}$
		\task[\textbf{B.}] $\frac{1+\varepsilon e^{-\beta \varepsilon}}{2 e^{-\beta \varepsilon}+e^{-2 \beta \varepsilon}}$
		\task[\textbf{C.}] $\frac{2 \varepsilon e^{-\beta \varepsilon}+\varepsilon e^{-2 \beta \varepsilon}}{2+e^{-\beta \varepsilon}+e^{-2 \beta \varepsilon}}$
		\task[\textbf{D.}] $\frac{\varepsilon e^{-\beta \varepsilon}+2 \varepsilon e^{-2 \beta \varepsilon}}{2+e^{-\beta \varepsilon}+e^{-2 \beta \varepsilon}}$
	\end{tasks}

	\begin{minipage}{\textwidth}
		\item Consider a system of 3 fermions which can occupy any of the 4 available energy states with equal probability. The entropy of the system is
		{\exyear{GATE 2014}}
	\end{minipage}
	\begin{tasks}(4)
		\task[\textbf{A.}] $k_{B} \ln 2$
		\task[\textbf{B.}] $2 k_{B} \ln 2$
		\task[\textbf{C.}]  $2 k_{B} \ln 4$
		\task[\textbf{D.}]  $3 k_{B} \ln 4$
	\end{tasks}
	\item In Boss-Einstein condensation, the particles
	{\exyear{GATE 2015}}
		\begin{tasks}(1)
		\task[\textbf{A.}] Have strong interparticle attraction
		\task[\textbf{B.}] Condense in real space
		\task[\textbf{C.}]  Have overlapping wavefunctions
		\task[\textbf{D.}] Have large and positive chemical potential
	\end{tasks}

	\begin{minipage}{\textwidth}
		\item For a black body radiation in a cavity, photons are created and annihilated freely as a result of emission and absorption by the walls of the cavity. This is because
		{\exyear{GATE 2015}}
	\end{minipage}
	\begin{tasks}(1)
		\task[\textbf{A.}] The chemical potential of the photons is zero
		\task[\textbf{B.}] Photons obey Pauli exclusion principle
		\task[\textbf{C.}] Photons are spin-1 particles
		\task[\textbf{D.}] The entropy of the photons is very large
	\end{tasks}

	\item The total power emitted by a spherical black body of radius $R$ at a temperature $T$ is $P_{1}$. Let $P_{2}$ be the total power emitted by another spherical black body of radius $\frac{R}{2}$ kept at temperature $2 T$. The ratio, $\frac{P_{1}}{P_{2}}$ is----------- (Give your answer upto two decimal places)
	{\exyear{GATE 2016}}

	\item Consider a system having three energy levels with energies $0,2 \varepsilon$ and $3 \varepsilon$, with respective degeneracies of 2,2 and 3 . Four bosons of spin zero have to be accommodated in these levels such that the total energy of the system is $10 \varepsilon$. The number of ways in which it can be done is------------
	{\exyear{GATE 2016}}

	\item Consider a triatomic molecule of the shape shown in the figure in three dimensions. The heat capacity of this molecule at high temperature (temperature much higher than the vibrational and rotational energy scales of the molecule but lower than its bond dissociation energies) is:
	{\exyear{GATE 2017}}
	\begin{figure}[H]
		\centering
		\includegraphics[height=3cm,width=4.5cm]{diagram-20210911(13)-crop}
	\end{figure}
	\begin{tasks}(4)
		\task[\textbf{A.}] $\frac{3}{2} k_{B}$
		\task[\textbf{B.}] $3 k_{B}$
		\task[\textbf{C.}] $\frac{9}{2} k_{B}$
		\task[\textbf{D.}] $6 k_{B}$
	\end{tasks}

	\item Consider two particles and two non-degenerate quantum levels 1 and $2 .$ Level 1 always contains a particle. Hence, what is the probability that level 2 also contains a particle for each of the two cases:\\
	(i) when the two particles are distinguishable and (ii) when the two particles are bosons?
	{\exyear{GATE 2017}}
	\begin{tasks}(2)
		\task[\textbf{A.}] (i) $\frac{1}{2}$ and (ii) $\frac{1}{3}$
		\task[\textbf{B.}] (i) $\frac{1}{2}$ and (ii) $\frac{1}{2}$
		\task[\textbf{C.}] (i) $\frac{2}{3}$ and (ii) $\frac{1}{2}$
		\task[\textbf{D.}] (i) 1 and (ii) 0
	\end{tasks}

\end{enumerate}
\colorlet{ocre1}{ocre!70!}
\colorlet{ocrel}{ocre!30!}
\setlength\arrayrulewidth{1pt}
\begin{table}[H]
	\centering
	\arrayrulecolor{ocre}
	\begin{tabular}{|p{1.5cm}|p{1.5cm}||p{1.5cm}|p{1.5cm}|}
		\hline
		\multicolumn{4}{|c|}{\textbf{Answer key}}\\\hline\hline
		\rowcolor{ocrel}Q.No.&Answer&Q.No.&Answer\\\hline
		1&\textbf{C} &2&\textbf{B}\\\hline
		3&\textbf{C} &4&\textbf{D} \\\hline
		5&\textbf{D} &6&\textbf{B} \\\hline
		7&\textbf{D}&8&\textbf{B}\\\hline
		9&\textbf{C}&10&\textbf{A}\\\hline
		11&\textbf{B} &12&\textbf{C}\\\hline
		13&\textbf{A}&14&\textbf{0.25}\\\hline
		15&\textbf{18}&16 &\textbf{D}\\\hline
		17&\textbf{C}&\\\hline

	\end{tabular}
\end{table}


\documentclass[12pt,a4paper]{article}

\usepackage[T1]{fontenc}
\usepackage[charter]{mathdesign}
\usepackage{amsmath,amsthm,enumitem,titlesec,xcolor}
\usepackage{microtype}
\usepackage[a4paper,margin=25mm]{geometry}
\usepackage[unicode]{hyperref}

\hypersetup{
    hidelinks,
    pdftitle={Distributed Algorithms},
    pdfauthor={Jukka Suomela},
}

\definecolor{titlecolor}{HTML}{0088cc}
\definecolor{hlcolor}{HTML}{f26924}

\newcommand{\q}[2]{\paragraph{\mbox{Question #1: }#2.}}
\newcommand{\sep}{{\centering \raisebox{-3mm}[0mm][0mm]{$*\quad*\quad*$}\par}}
\newcommand{\hl}[1]{\textbf{\emph{#1}}}
\newcommand{\cemph}[1]{\textcolor{hlcolor}{\textbf{\emph{\boldmath #1}}}}

\DeclareMathOperator{\diam}{diam}

\setitemize{noitemsep,leftmargin=3ex}

\titleformat{\paragraph}[runin] {\normalfont\normalsize\bfseries\color{titlecolor}}{\theparagraph}{1em}{}

\begin{document}

\noindent
\emph{CS-E4510 Distributed Algorithms / Jukka Suomela\\
exam, 16 December 2021}

\paragraph{Instructions.}

There are three questions; please \cemph{try to answer something in each of them}. If you cannot solve a problem entirely, please at least explain what you tried and what went wrong. Do not spend too much time with one problem; the problems are not listed in order of difficulty and they do not depend on each other. All questions refer to problems that we studied in the previous exam, you can find the old exam here:
\begin{center}
\url{https://jukkasuomela.fi/da2020/exam-2021-10-27.pdf}
\end{center}

You are free to look at any source material (this includes lecture notes, textbooks, and anything you can find with Google), but you are not allowed to collaborate with anyone else or ask for anyone's help (this includes collaboration with other students and asking for help in online forums). You are free to use any results from the lecture notes directly without repeating the details.

Please note that we are looking for mathematical proofs here. The proof can be brief and a bit sketchy, but the proof idea has to be solid. Please give enough details so that a friendly, cooperative reader can understand your proof idea correctly and see why it makes sense. Illustrations are probably going to be very helpful.

\q{1}{PN}

Recall question 1 in the previous exam. There you were allowed to label edges with arbitrary \cemph{integers}, and you showed that the problem was solvable with a deterministic algorithm in the PN model. Now let us make the problem slightly more challenging: the edge labels must be integers from the set \cemph{$\{-1, 0, +1\}$}; everything else remains the same (adjacent edges have different labels, and the sum of the labels is $0$). Prove that the new problem \hl{cannot} be solved with any deterministic algorithms in the PN model.

\medskip
\noindent\hl{Hint:} You are expected to use an argument that uses covering maps.

\q{2}{LOCAL}

Recall question 2 in the previous exam. There we specified a graph problem, and you designed an algorithm that solves the problem in \cemph{$o(n)$} rounds. Prove that the same problem \hl{cannot} be solved with any deterministic algorithm in the LOCAL model in \cemph{$O(1)$} rounds.

\q{3}{CONGEST}

Recall question 3 in the previous exam. There we specified a graph problem, and you designed a deterministic CONGEST model algorithm that solves the problem in \cemph{$O(\diam(G))$} rounds. Prove that the same problem \hl{cannot} be solved with any deterministic algorithm in the CONGEST model in \cemph{$0$} rounds (i.e., without any communication). Prove that this holds even if the unique identifiers are numbers from $\{1,2,\dotsc,n^2\}$, and the nodes get the value of $n$ as input.

\end{document}


\documentclass[12pt, english]{article}

\usepackage{listings}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{amssymb,amsmath}

\newcommand\mred[1]{%
	\protect\leavevmode
	\begingroup
	\color{red}%
	#1%
	\endgroup
}

\newcommand{\red}{\textcolor{black}}
\newcommand{\redd}{\textcolor{black}}
\newcommand{\reddd}{\textcolor{black}}
\newcommand{\LP}{\text{LP}}
\newcommand{\wpone}{w.p.~$1$ as $S \rightarrow \infty$}
\newcommand{\Qfwd}{\red{\tilde Q}}
\newcommand{\Qalpha}{\red{\hat Q_\alpha}}
\newcommand{\QalphaS}{\hat Q_\alpha^S}
\newcommand{\QA}{\red{L_{\alpha}^S}}
\newcommand{\valpha}{\red{\hat v_\alpha}}
\newcommand{\valphak}{\red{\hat v_\alpha^k}}
\newcommand{\vfwd}{\red{\tilde v}}
\newcommand{\va}{\red{\nu_\alpha}}
\newcommand{\QR}{\hat{Q}_{\text{out}}^{\tau}}
\newcommand{\QRnext}{\hat{Q}_{\text{out}}^{\tau + 1}}
\newcommand{\fs}{\lfloor s \rfloor}
\newcommand{\lbd}{LBDA($\alpha$)}
\newcommand{\icp}{\text{c}}
\newcommand{\ks}{k_s^{\tau}}
\newcommand{\tks}{\hat k_s^{\tau}}
\newcommand{\xalpha}{\red{\hat x_\alpha}}
\newcommand{\xalphaplus}{\red{\hat x_\alpha^+}}

\lstset{
	language=C++,
	basicstyle=\ttfamily\footnotesize,
	frame=lines,
	keywordstyle=\color{blue},
	tabsize=4
}

\title{LBDA+ v1.0 user manual}
\author{
	Niels van der Laan
	\and
	Ward Romeijnders
	\and
	Niels Wouda
}

\date{\today}

\begin{document}

\maketitle
\tableofcontents

\clearpage

\section{Introduction}
\label{sec:introduction}
This is the user manual for the computer code of the \emph{loose Benders decomposition algorithm (LBDA)}, introduced in van der Laan and Romeijnders~\cite{vanderLaan2020}. This algorithm approximately solves two-stage mixed-integer recourse models with uncertainty in the right-hand side; see Section~\ref{subsec:model}.

The algorithm is developed for solving mixed-integer recourse models \emph{with integer decision variables in the second stage}. In fact, the algorithm is based on a Benders decomposition for a convex approximation of the \emph{expected} mixed-integer value function. However, if all decision variables are continuous, then the algorithm reduces to the classical L-shaped algorithm. Moreover, if there are integer decision variables in the first stage, then the master problem is a MIP instead of LP.

For convenience the repository does not only contain the code for LBDA, but also for solving the \emph{deterministic equivalent problem} using Gurobi. In this way the numerical experiments in van der Laan and Romeijnders~\cite{vanderLaan2020} can easily be replicated. Moreover, the code for LBDA is set up in such a way that different types of optimality cuts can easily be added. For example, next to the LBDA cuts and standard Benders cuts used in the paper, also strong Benders cuts are implemented, see Section~\ref{subsec:cut_families}.

The algorithm is coded in C++, free to use and distribute, and also has a Python interface. A reference manual is provided in Section \ref{sec:reference_manual}. Within the algorithm, all linear and integer programs are solved using Gurobi. Moreover, SMPS input is accepted, but the problem data can also be specified manually. See Section~\ref{sec:examples} for examples on how to apply LBDA using both input methods.

The problem instances that are solved using the LBDA in \cite{vanderLaan2020} are available in SMPS format. These, and a frozen version of the code, can be found at \url{https://doi.org/10.34894/45RPGB}. The code is also available as a git repository, here: \url{https://github.com/wardromeijnders/LBDA}, which contains the latest version.

Before explaining the LBDA code in detail, we first briefly discuss in Section~\ref{subsec:model} the mathematics behind the two-stage mixed-integer recourse models that LBDA solves. This subsection coincides with part of the introduction of van der Laan and Romeijnders \cite{vanderLaan2020}.

\subsection{Two-stage mixed-integer recourse models\label{subsec:model}}

Consider the two-stage mixed-integer recourse model with random right-hand side \begin{equation}\label{etastar}\eta^* := \min_{x}\left\{c^{\top}x + Q(x) :\quad Ax = b,\;x \in X\subseteq \mathbb{R}^{n_1}_+\right\},\end{equation} where the recourse function $Q$ is defined as \begin{equation}\label{defQ}Q(x):=\mathbb{E}_{\omega}\left[ \min_y \left\{   q^{\top}y: Wy = \omega - Tx,\; y \in Y \subseteq \mathbb R^{n_2 }_+\right\}\right]  , \quad x\in \red{X}. \end{equation}This model represents a two-stage decision problem under uncertainty. In the first stage, a decision~$x$ has to be made here-and-now, subject to deterministic constraints $Ax = b$ and random goal constraints $Tx = \omega$. Here, $\omega$ is a \red{continuous or discrete} random vector whose probability distribution is known. In the second stage, the realization of $\omega$ becomes known and any infeasibilities with respect to $Tx = \omega$ have to be repaired. This is modelled by the second-stage problem \begin{equation}\label{vwx}v(\omega,x) := \min_y \left\{   q^{\top}y:Wy = \omega - Tx,\; y \in Y \subseteq  \mathbb{R} ^{n_2 }_+\right\}.\end{equation}The objective in this two-stage recourse model is to minimize the sum of immediate costs $c^{\top}x$ and expected second-stage costs $Q(x) = \mathbb{E}_\omega[v(\omega,x)]$, ${x \in X}$.

Frequently, integrality restrictions are imposed on the first- and second-stage decisions. That is, $X$ and $Y$ are of the form $X = \mathbb Z^{p_1}_+ \times \mathbb{R}^{n_1 - p_1}_+$ and $Y = \mathbb Z^{p_2}_+\times \mathbb{R}^{n_2 - p_2}_+$. Such restrictions arise naturally when modelling real-life problems, for example to model on/off decisions or batch size restrictions. The resulting model is called a mixed-integer recourse (MIR) model.
Such models have many practical applications in for example energy, telecommunication, production planning, and environmental control.

\section{Installation instructions}
\label{sec:installation_instructions}

We explain how to set-up a local copy of the LBDA C++ codebase for use and development. If you only want to use the Python bindings, the package is available on the Python package index as \texttt{lbdapy} for Python 3.8 on Windows and Linux. Make sure the environment variable \texttt{GUROBI\_HOME} points to the Gurobi installation directory, and Armadillo is installed on your computer.

TODO get the package on PyPI

After following the instruction below, you can either compile your code directly against the source code of our project, or include the headers in \texttt{lbda/include} and link against the \texttt{lbda} static library.

\subsection{On Linux}
A development installation is set-up as follows in a Unix/Linux environment. This was tested on Ubuntu 20.04, but should work similarly for many other distributions.
\begin{enumerate}
	\item Clone the repository into some folder. This also clones two submodules, \texttt{pybind11} and \texttt{carma}, which are used to compile the Python bindings.

	\item We use CMake as our build tool. It might already be available on your system; if not, it will be installed when we install Armadillo.

	\item Install Gurobi. Any recent version should do, but the code was written and tested with Gurobi 9. The header files and libraries should be available in a standard location relative to the \texttt{GUROBI\_HOME} environment variable.

	\item For linear algebra, we use the Armadillo library. It is available for many distributions, often via the package manager. The code was written and tested against Armadillo 9.8. You can install the library yourself, or use the \texttt{scripts/install.sh} script to do this for you. It should work on most Debian-based distributions, like Ubuntu. You likely need to be root for the script to work.

	\item If everything is set-up correctly, CMake can build \texttt{lbda} from the repository root as \texttt{cmake build lbda}. The resulting Makefile has three targets: \texttt{lbdaexec}, \texttt{lbdapy}, and \texttt{tests}. The first is a stand-alone executable that can read and solve problems specified in the SMPS format. The second is a compiled Python module. The third is a small test suite than can be used to verify a correct installation.

	\item If you run \texttt{make lbdaexec}, you should obtain a compiled binary in \texttt{bin/lbdaexec}. Run \texttt{bin/lbdaexec -h} to be greeted by a help message explaining the command-line interface. Finally, \texttt{make tests} compiles a suite of tests that can be ran as \texttt{bin/tests}.

	\item \textbf{Python}. Running \texttt{make lbdapy} should result in a compiled Python module in the \texttt{lib} directory. This library can be used together with the Python code in \texttt{lbda/python/lbdapy}, by putting the compiled Python module in \texttt{lbda/python/lbdapy/lib}, and installing the package with the \texttt{pip install .} command from the \texttt{lbda/python} directory. Thereafter, one can solve the Python examples of Section \ref{sec:examples}.
\end{enumerate}

\subsection{On Windows}
A Windows set-up can be obtained as follows. This was tested using Visual Studio 2019. As an alternative, a WSL set-up using the Linux instructions is also fully supported.

\begin{enumerate}
	\item Clone the repository into some folder. This also clones two submodules, \texttt{pybind11} and \texttt{carma}, which are used to compile the Python bindings.

	\item Set-up the project in Visual Studio. Although other IDEs should work, this guide was written using Visual Studio, and it might be easiest to follow along.

	\item Install Gurobi. Any recent version should do, but the code was written and tested with Gurobi 9. The header files and libraries should be available in a standard location relative to the \texttt{GUROBI\_HOME} environment variable. This variable is often automatically set to the  appropriate location during by the Gurobi installation process.

	\item Make sure you have the Armadillo library installed. Download the source code from \href{http://arma.sourceforge.net/download.html}{their website} and extract it somewhere (the code was developed against Armadillo 9.8, but any recent version should do). Then follow \href{https://stackoverflow.com/a/44659049/4316405}{these instructions}.

	\item Three build targets should now be available in Visual Studio: \texttt{lbdaexec}, \texttt{tests}, and \texttt{lbdapy}. For the \texttt{lbdaexec} you might need to provide the Unix/Linux \texttt{getopt} facilities, as explained \href{https://stackoverflow.com/a/17195644/4316405}{here}. The build targets are the same as in the Linux instructions above, and the remainder of the set-up can be found there.
\end{enumerate}

\section{Examples}
\label{sec:examples}

We present two common use cases: solving a known problem given in SMPS format, and specifying a new problem by providing your own matrices and vectors as input. The example code can be ran as-is, either by compiling it against the source files (for the C++ code, where it offers an alternative implementation of the \texttt{main.cpp} file), or by installing the \texttt{lbdapy} package from the package index (for the Python code).

\subsection{Solving a MIR problem using SMPS input}
\label{subsec:solving_smps_example}

Solving a MIR problem specified as a triplet of SMPS files is rather easy. Listings \ref{listing:smps_example_c++} and \ref{listing:smps_example_python} provide some example code, solving a problem provided in the data set, assumed present in the data directory of the repository (see Section \ref{sec:introduction} for a link to obtain these SMPS files).
\begin{lstlisting}[caption={Solving MIR using SMPS input in C++.},
                   label={listing:smps_example_c++}]
#include "deterministicequivalent.h"
#include "masterproblem.h"
#include "problemdata.h"
#include "cutfamilies/loosebenders.h"

int main()
{
	auto problem = ProblemData::fromSmps(
		"data/sslp/sslp_5_25_50");

	// Solves the deterministic equivalent formulation.
	DeterministicEquivalent detEqv(problem);
	auto decisions = detEqv.solve();

	std::cout << *decisions << '\n';
	std::cout << detEqv.objective() << '\n';
	std::cout << detEqv.firstStageObjective() << '\n';
	std::cout << detEqv.secondStageObjective() << '\n';

	// Applies the LBDA.
	arma::vec alpha = arma::zeros(problem.Wmat().n_cols);
	LooseBenders cutFamily(problem, alpha);

	MasterProblem master(problem, -1000);
	decisions = master.solveWith(cutFamily);

	std::cout << *decisions << '\n';
	std::cout << master.objective() << '\n';
	std::cout << master.firstStageObjective() << '\n';
	std::cout << master.secondStageObjective() << '\n';
}
\end{lstlisting}
\begin{lstlisting}[caption={Solving MIR using SMPS input in Python.},
                   label={listing:smps_example_python},
                   language={Python}]
from lbdapy import (DeterministicEquivalent, MasterProblem,
                    ProblemData)
from lbdapy.cutfamilies import LooseBenders

import numpy as np

problem = ProblemData.from_smps("data/sslp/sslp_5_25_50")

# Solves the deterministic equivalent formulation.
det_eqv = DeterministicEquivalent(problem)
decisions = det_eqv.solve()

print(decisions)
print(det_eqv.objective())
print(det_eqv.first_stage_objective())
print(det_eqv.second_stage_objective())

# Applies the LBDA.
alpha = np.zeros(problem.Wmat().shape[1])
cut_family = LooseBenders(problem, alpha)

master = MasterProblem(problem, lower_bound=-1000)
decisions = master.solve_with(cut_family)

print(decisions)
print(master.objective())
print(master.first_stage_objective())
print(master.second_stage_objective())
\end{lstlisting}
Our SMPS reader is rather strict and might reject reading your files if they do not adhere to the standard \textit{exactly}. If this happens to you, the repository contains a simple Python script you can point to the offending problem set. The script is given in \texttt{data/fix\_faulty\_smps.py}.

In the listings above, we first read the problem data contained in the ``sslp\_5\_25\_50'' files. This is a stochastic server location problem with binary first- and second-stage variables, due to Ntaimo and Sen \cite{ntaimo2005}.  A call to \texttt{fromSmps} (C++) or \texttt{from\_smps} (Python) returns an instance of the class \texttt{ProblemData} (Section \ref{subsec:problem_class}). All solution methods take such a \texttt{ProblemData} instance. Thereafter, we apply two solution methods. First, we construct and solve the deterministic equivalent, and print its optimal first-stage decisions, and objective costs. Then, we solve the same problem with the L-shaped algorithm. We also specify a lower bound of $-1000$. In general, it is important not to forget setting a lower (and possibly upper) bound when using the decomposition. We apply the LBDA cuts of \ref{subsubsec:loose_benders} with $\alpha = 0$. Observe that \emph{the interface for obtaining decisions and objective values is similar for both the decomposition-based \texttt{MasterProblem}, and the direct solution of the \texttt{DeterministicEquivalent}}.

\subsection{Specifying your own problem data}
\label{subsec:own_data_example}

The \texttt{ProblemData} class exposes a constructor, which can be used to specify a problem instance that is not available in SMPS format. This is a bit more involved as there is quite a bit of data to specify. The argument order is given in the reference manual, in Listing \ref{listing:problem_data}.

We solve a small investment problem, originally due to Schultz et al. \cite{schultz1998}. In the first stage, we select $x \in [0, 5]^2$ yielding some immediate revenue. Further revenue is gained from projects $y \in \{0, 1\}^4$ for which investment is done in the second stage, after having observed the random vector $\omega \in [5, 15]^2$, leading to the budget $\omega - x$. As a minimization problem, we have
\[ \min_x \left\{ -\frac{3}{2}x_1 -4 x_2 + \mathbb{E}_\omega [v(\omega, x)]~:~x \in [0, 5]^2 \right\}, \]
where
\[
\begin{split}
	% The second constraint differs between LBDA paper (y_4) and Schultz et al. (2y_4). I follow
	% the LBDA paper here.
	v(\omega, x) = \min_{y \in Y} \{ -16y_1 -19y_2 -23y_3 - 28y_4~&: \\
							            2y_1 + 3y_2 + 4y_3 + 5y_4 &\le \omega_1 - x_1 \\
					                     6y_1 + y_2 + 3y_3 + y_4 &\le \omega_2 - x_2 \},
\end{split}
\]
and $Y = \{0, 1\}^4$. The problem has relatively complete recourse. We discretize the support of $\omega$ as $\{5, 10, 15\} \times \{5, 10, 15\}$, resulting in $9$ scenarios. Each scenario occurs with fixed probability $p_k = 1 / 9$, $k = 1, \ldots, 9$. The problem is then specified in C++ and Python as given in Listings \ref{listing:custom_example_c++} and \ref{listing:custom_example_python}, respectively.

\begin{lstlisting}[caption={Specifying a custom problem in C++.},
                   label={listing:custom_example_c++}]
#include "deterministicequivalent.h"
#include "masterproblem.h"
#include "problemdata.h"
#include "cutfamilies/loosebenders.h"

int main()
{
    arma::sp_mat A;
	arma::sp_mat T = arma::speye(2, 2);

	// This is a quicker way to specify the fully dense
	// matrix W in our small toy problem, but should not
	// be used when W is large and sparse.
	arma::mat WDense = {{2, 6}, {3, 1}, {4, 3}, {5, 1}};
	arma::sp_mat W(WDense);

	arma::mat scenarios = {{5, 5, 5, 10, 10, 10, 15, 15, 15},
	                       {5, 10, 15, 5, 10, 15, 5, 10, 15}};

	arma::vec probs = arma::ones(9) / 9;

	arma::Col<char> firstStageSenses;
	arma::Col<char> secondStageSenses = {'<', '<'};

	arma::Col<char> firstStageVarTypes = {'C', 'C'};
	arma::Col<char> secondStageVarTypes = {'B', 'B', 'B', 'B'};

	arma::vec firstStageCoeffs = {-1.5, -4};
	arma::vec secondStageCoeffs = {-16, -19, -23, -28};

	arma::vec firstStageLB = {0, 0};
	arma::vec firstStageUB = {5, 5};

	arma::vec secondStageLB = {0, 0, 0, 0};
	arma::vec secondStageUB = {1, 1, 1, 1};

	arma::vec firstStageRhs;

	ProblemData problem(A,
						T,
						W,
						scenarios,
						probs,
						firstStageSenses,
						secondStageSenses,
						firstStageVarTypes,
						secondStageVarTypes,
						firstStageCoeffs,
						secondStageCoeffs,
						firstStageLB,
						firstStageUB,
						secondStageLB,
						secondStageUB,
						firstStageRhs);

	// Solves the deterministic equivalent formulation.
	DeterministicEquivalent detEqv(problem);
	auto decisions = detEqv.solve();

	std::cout << *decisions << '\n';
	std::cout << detEqv.objective() << '\n';
	std::cout << detEqv.firstStageObjective() << '\n';
	std::cout << detEqv.secondStageObjective() << '\n';

	// Applies the LBDA.
	arma::vec alpha = arma::zeros(problem.Wmat().n_cols);
	LooseBenders cutFamily(problem, alpha);

	MasterProblem master(problem, -100);
	decisions = master.solveWith(cutFamily);

	std::cout << *decisions << '\n';
	std::cout << master.objective() << '\n';
	std::cout << master.firstStageObjective() << '\n';
	std::cout << master.secondStageObjective() << '\n';
}
\end{lstlisting}
\begin{lstlisting}[caption={Specifying a custom problem in Python.},
                   label={listing:custom_example_python},
                   language={Python}]
import numpy as np
from lbdapy import (DeterministicEquivalent, MasterProblem,
					ProblemData)
from lbdapy.cutfamilies import LooseBenders
from scipy.sparse import eye

A = []
T = eye(2, 2, format="csc")
W = [[2, 6], [3, 1], [4, 3], [5, 1]]

scenarios = [[5, 5, 5, 10, 10, 10, 15, 15, 15],
             [5, 10, 15, 5, 10, 15, 5, 10, 15]]

probs = np.ones(9) / 9

first_stage_senses = []
second_stage_senses = ['<', '<']
first_stage_var_types = ['C', 'C']
second_stage_var_types = ['B', 'B', 'B', 'B']

first_stage_coeffs = [-1.5, -4]
second_stage_coeffs = [-16, -19, -23, -28]

first_stage_lb = [0, 0]
first_stage_ub = [5, 5]

second_stage_lb = [0, 0, 0, 0]
second_stage_ub = [1, 1, 1, 1]

first_stage_rhs = []

problem = ProblemData(A,
				      T,
					  W,
					  scenarios,
					  probs,
					  first_stage_senses,
					  second_stage_senses,
					  first_stage_var_types,
					  second_stage_var_types,
					  first_stage_coeffs,
					  second_stage_coeffs,
					  first_stage_lb,
					  first_stage_ub,
					  second_stage_lb,
					  second_stage_ub,
					  first_stage_rhs)

# Solves the deterministic equivalent formulation.
det_eqv = DeterministicEquivalent(problem)
decisions = det_eqv.solve()

print(decisions)
print(det_eqv.objective())
print(det_eqv.first_stage_objective())
print(det_eqv.second_stage_objective())

# Applies the LBDA.
alpha = np.zeros(problem.Wmat().shape[1])
cut_family = LooseBenders(problem, alpha)

master = MasterProblem(problem, lower_bound=-100)
decisions = master.solve_with(cut_family)

print(decisions)
print(master.objective())
print(master.first_stage_objective())
print(master.second_stage_objective())
\end{lstlisting}
Although we did not explicitly mention this in Section \ref{subsec:model}, it is not required to specify the problem with strict equality constraints before applying the LBDA: arbitrary constraint senses are accepted, as shown in the listings above. Observe that the matrices $T$ and $W$ are specified in code as $T^\top$ and $W^\top$: \emph{all three matrices $A$, $T$, and $W$ must be specified in this manner}. We require this for performance reasons, due to the memory lay-out of the numerical library we use.

Once the problem is specified, the solution method is the same as for the other examples. First we construct the deterministic equivalent and solve it. Then we solve the decomposition using loose Benders' cuts with $\alpha = 0$. Observe that we again specify a lower bound, this time of $-100$.

\section{Reference manual}
\label{sec:reference_manual}

We present a short reference manual of the public methods on classes one might commonly use from the
LBDA+ library. The manual details the C++ interface. The names are similar in the Python interface, but are written in their Pythonic equivalents (\textit{e.g.} \texttt{firstStageObjective} in the C++ code is accessed as \texttt{first\_stage\_objective} in the Python interface). Both interfaces expect similar arguments. For example code in both languages, we refer to Section \ref{sec:examples}.

Our code uses the Armadillo numerical library. Particularly, we often rely on the vector, matrix, and sparse matrix classes offered by Armadillo. Such an Armadillo class can be recognised as belonging to the \texttt{arma} namespace (\textit{e.g.} \texttt{arma::vec} for a real-valued column vector, \texttt{arma::mat} for a real-valued matrix, and \texttt{arma::sp\_mat} for a real-valued sparse matrix in compressed column format). The Armadillo library and documentation are available at \href{http://arma.sourceforge.net/}{their website}.

\subsection{The \texttt{ProblemData} class}
\label{subsec:problem_class}

The \texttt{ProblemData} class contains all data describing a problem instance: the matrices $A$, $T$, and $W$, variable lower- and upper-bounds, constraint senses, objective coefficients, and scenario-specific right-hand sides. All solution methods solve problems described by a \texttt{ProblemData} instance. The public interface is given in Listing \ref{listing:problem_data}, and will be discussed below.
\begin{lstlisting}[caption={Public interface of the \texttt{ProblemData} class.},
                   label={listing:problem_data}]
class ProblemData
{
public:
    ProblemData(arma::sp_mat Amat,
				arma::sp_mat Tmat,
				arma::sp_mat Wmat,
				arma::mat scenarios,
				arma::vec scenarioProbabilities,
				arma::Col<char> firstStageConstrSenses,
				arma::Col<char> secondStageConstrSenses,
				arma::Col<char> firstStageVarTypes,
				arma::Col<char> secondStageVarTypes,
				arma::vec firstStageCoeffs,
				arma::vec secondStageCoeffs,
				arma::vec firstStageLowerBound,
				arma::vec firstStageUpperBound,
				arma::vec secondStageLowerBound,
				arma::vec secondStageUpperBound,
				arma::vec firstStageRhs);

	static ProblemData fromSmps(std::string const &location);

	arma::Col<char> const &firstStageConstrSenses() const;

	arma::Col<char> const &secondStageConstrSenses() const;

	arma::Col<char> const &firstStageVarTypes() const;

	arma::Col<char> const &secondStageVarTypes() const;

	arma::sp_mat const &Amat() const;

	arma::sp_mat const &Tmat() const;

	arma::sp_mat const &Wmat() const;

	arma::vec const &firstStageCoeffs() const;

	arma::vec const &secondStageCoeffs() const;

	arma::vec const &firstStageRhs() const;

	arma::vec const &firstStageLowerBound() const;

	arma::vec const &firstStageUpperBound() const;

	arma::vec const &secondStageLowerBound() const;

	arma::vec const &secondStageUpperBound() const;

	size_t nScenarios() const;

	arma::mat const &scenarios() const;

	double scenarioProbability(size_t scenario) const;
};
\end{lstlisting}
There are two ways to instantiate the \texttt{ProblemData} class: either by supplying your own vectors and matrices to the constructor, or supplying the filesystem location of an SMPS triplet of files to \texttt{fromSmps}. If one of the three SMSP files does not exist, \texttt{fromSmps} throws a \texttt{std::runtime\_error}.

Most of the member functions are data getters, returning parts of the data that define a two-stage recourse problem. The functions \texttt{Amat()}, \texttt{Tmat()} and \texttt{Wmat()} return references to the (sparse) matrices $A$, $T$, and $W$, respectively. \texttt{nScenarios()} returns the number of scenarios, \texttt{scenarios()} a dense matrix of all scenario right-hand sides (one column for each scenario). Finally, \texttt{scenarioProbability} returns the occurrence probability of the given scenario (number). The use of the other member functions should be clear based on their names.

\subsection{The \texttt{DeterministicEquivalent} class}
\label{subsec:det_eqv_class}

The \texttt{DeterministicEquivalent} class formulates the two-stage recourse problem as a single deterministic (possibly mixed-integer) linear program, and solves it directly. This is sometimes also called the \textit{extensive form}. The public interface is given in Listing \ref{listing:det_eqv}.
\begin{lstlisting}[caption={Public interface of the \texttt{DeterministicEquivalent} class.},
                   label={listing:det_eqv}]
class DeterministicEquivalent
{
public:
	DeterministicEquivalent(ProblemData const &problem);

	std::unique_ptr<arma::vec> solve(
		double timeLimit = arma::datum::inf);

	bool isOptimal() const;

	double mipGap() const;

	double firstStageObjective();

	double secondStageObjective();

	double objective() const;
};
\end{lstlisting}
Its constructor takes a \texttt{ProblemData} instance to solve (see Section \ref{subsec:problem_class}). After construction, one can call the \texttt{solve} method, with an optional time limit argument (in seconds). When such an argument is not passed, the time limit defaults to infinity. If the time limit is exceed and no feasible solutions are available, \texttt{solve} throws a \texttt{std::runtime\_error}. This exception is also thrown when the problem is infeasible. The return argument is a (unique) pointer to a vector of first-stage decisions. These decisions are optimal when \texttt{isOptimal} returns true. When \texttt{isOptimal} returns false, the decisions are the best solution found by Gurobi. \texttt{mipGap} returns the relative optimality gap (as a percentage) of the returned solution: this is generally only informative when the solution is not optimal.

After solving the deterministic equivalent, the \texttt{firstStageObjective}, \texttt{secondStageObjective}, and \texttt{objective} methods return the first-stage costs, the expected cost-to-go in the second-stage, and the overall objective cost, respectively.

\subsection{The \texttt{CutFamily} classes}
\label{subsec:cut_families}

The \texttt{CutFamily} abstract class specifies the way a family of cutting planes should be implemented within the Benders' decomposition solution approach. Specifically, a cut family solves a relaxation of the second-stage sub problems to obtain cut coefficients for insertion into the first-stage master problem (see also Section \ref{subsec:master_problem_class}). If $\theta$ is our first-stage approximation of the recourse function $Q$, such an optimality cut takes the form of
\[ \theta \ge \gamma + \beta^\top x, \]
where $\gamma \in \mathbb{R}$ is an intercept and $\beta \in \mathbb{R}^{n_1}$ the slope. The public interface a cut family should implement is given in Listing \ref{listing:cut_family}.
\begin{lstlisting}[caption={Public interface of the \texttt{CutFamily} class.},
                   label={listing:cut_family}]
class CutFamily
{
public:
	struct Cut
	{
		arma::vec beta;
		double gamma;
	};

	virtual CutFamily::Cut computeCut(arma::vec const &x) = 0;

	virtual ~CutFamily() = default;
};
\end{lstlisting}
All that is required of a family of cutting planes is that it implements a method \texttt{computeCut}, which takes the current first-stage decisions and returns suitable cut coefficients, obtained from some relaxation of the sub problems. We now turn to several implementations.

\subsubsection{The \texttt{LpDual} class}
\label{subsubsec:lpdual}

These are the regular Benders' cuts, well-known in stochastic programming from their application in the L-shaped algorithm. The relaxation solved is the LP relaxation of the second-stage sub problem for each of the $K$ scenarios $\omega_k$, $k = 1,\ldots,K$. We denote the optimal objective by $v_{LP}(\omega_k, \bar x)$ for given first-stage solutions $\bar x$, and dual solutions by $\pi_k$. Let
\[ \beta = \sum_{k = 1}^K p_k \beta_k,\]
where $\beta_k = -\pi_k T$.
We choose $\gamma$ as
\begin{equation}
\gamma = \sum_{k = 1}^K \left[ p_k v_{LP}(\omega_k, \bar x) \right] - \beta^\top \bar x.
\label{eq:benders_coeffs}
\end{equation}
The \texttt{LpDual} class implements the \texttt{computeCut} method to return these coefficients. The public interface is straightforward, and given in Listing \ref{listing:lpdual}.
\begin{lstlisting}[caption={Public interface of the \texttt{LpDual} class.},
                   label={listing:lpdual}]
class LpDual : public CutFamily
{
public:
	LpDual(ProblemData const &problem);

	CutFamily::Cut computeCut(arma::vec const &x) override;
};
\end{lstlisting}

\subsubsection{The \texttt{StrongBenders} class}
\label{subsubsec:strong_benders}

This family is due to Zou et al. \cite{zou2019} and strengthens the regular LP-duality cuts by raising the intercept $\gamma$. As before, we obtain an optimal dual solution $\pi_k$ of the LP relaxation of the $k$\textsuperscript{th} sub problem, for each $k = 1,\ldots,K$, and we compute $\beta_k = -\pi_k T$ and $\beta = \sum_{k = 1}^K p_k \beta_k$. We then solve a Lagrangian relaxation problem at the dual solution of the LP relaxation. This problem is given by
\[ \mathcal{L}(\omega, \beta) := \min_{y, z} \{ q^\top y - \beta^\top z~:~Tz + Wy = \omega, Az = b, y \in Y, z \in X \}. \]
For $\gamma$, we now take
\begin{equation}
\quad \gamma = \sum_{k = 1}^K p_k \mathcal{L}(\omega_k, \beta_k).
\label{eq:strong_benders_coeffs}
\end{equation}
The \texttt{StrongBenders} class implements the \texttt{computeCut} method to return these coefficients. The public interface is again straightforward, and given in Listing \ref{listing:strong_benders}.
\begin{lstlisting}[caption={Public interface of the \texttt{StrongBenders} class.},
                   label={listing:strong_benders}]
class StrongBenders : public CutFamily
{
public:
	StrongBenders(ProblemData const &problem);

	~StrongBenders() override;

	CutFamily::Cut computeCut(arma::vec const &x) override;
};
\end{lstlisting}

\subsubsection{The \texttt{LooseBenders} class}
\label{subsubsec:loose_benders}

The \texttt{LooseBenders} class implements the loose Benders' cuts for the generalized $\alpha$-approximations in~\cite{vanderLaan2020}.
The generalized $\alpha$-approximations and the corresponding loose Benders' cuts depend on a parameter $\alpha$, which is a vector of the same size as $\omega$.
In particular, let $B_k$ denote an optimal basis matrix of $v_{LP}(\omega_k, \bar x)$, and consider the corresponding \emph{Gomory relaxation} $v_{B_k}(\omega_k, \bar x)$, obtained by relaxing the integer restrictions on the basic variables, see~\cite{vanderLaan2020} for details.
Then, $\gamma$ is given by
\[\gamma = \sum_{k = 1}^K p_k\left(v_{B_k}(\omega_k - \alpha, 0) + \pi_k^\top\alpha \right),\]
and, as before, $\beta = -\sum_{k = 1}^K p_k \pi_k T$. The public interface is given in Listing \ref{listing:loose_benders}.
\begin{lstlisting}[caption={Public interface of the \texttt{LooseBenders} class.},
                   label={listing:loose_benders}]
class LooseBenders : public CutFamily
{
public:
	LooseBenders(ProblemData const &problem,
			 	 arma::vec const alpha,
			 	 double timeLimit = 1e2);

	~LooseBenders() override;

	CutFamily::Cut computeCut(arma::vec const &x) override;
};
\end{lstlisting}
Observe that the \texttt{LooseBenders} class takes a vector $\alpha$ as an argument, and a time limit (in seconds). The time limit applies to the Gomory relaxation $v_{B_k}$, and defaults to $100$s. If the time limit is exceeded, the best known lower bound for $v_{B_k}$ is used instead.

\subsection{The \texttt{MasterProblem} class}
\label{subsec:master_problem_class}

The \texttt{MasterProblem} class solves the two-stage recourse problem by means of decomposition. In particular, it formulates the first-stage master problem, and for each second-stage scenario a suitable sub problem. It then applies a family of cutting planes (Section \ref{subsec:cut_families}) to iteratively approach an optimal solution. The public interface for this class is given in Listing \ref{listing:master_problem}.
\begin{lstlisting}[caption={Public interface of the \texttt{MasterProblem} class.},
                   label={listing:master_problem}]
class MasterProblem
{
public:
	MasterProblem(ProblemData const &problem,
				  double lowerBound = 0.,
				  double upperBound = arma::datum::inf);

	std::unique_ptr<arma::vec> solveWith(CutFamily &cutFamily,
	                                     double tol = 1e-3);

	double firstStageObjective() const;

	double secondStageObjective() const;

	double objective() const;
};
\end{lstlisting}
Its constructor takes the familiar \texttt{ProblemData} instance, and two optimal arguments providing a lower- and upper-bound on $\theta$. If these are not passed, it is assumed that $0 \le \theta \le \infty$. After construction, one can call the \texttt{solveWith} method, with an appropriate family of cutting planes as an argument. This cut family is then used to derive optimality cuts solving the problem. An optional tolerance argument, \texttt{tol}, can be passed, which specifies the tolerance that should be used when evaluating the optimality of a current first-stage solution. The default tolerance is $0.001$. If the master problem is infeasible, a \texttt{std::runtime\_error} is thrown. In case a sub problem is infeasible, the same exception is thrown; this might happen when we do not have (relatively) complete recourse. The return argument is a (unique) pointer to a vector of near-optimal first-stage decisions.

Once the master problem has been solved, the \texttt{firstStageObjective}, \texttt{secondStageObjective}, and \texttt{objective} methods return the first-stage costs, the expected second-stage costs, and the overall objective cost, respectively.

\clearpage
\bibliographystyle{plain}
\begin{thebibliography}{9}

	\bibitem{vanderLaan2020}
	van der Laan, N., and W.\ Romeijnders, 2020. A loose Benders decomposition algorithm for approximating two-stage mixed-integer recourse models. Accepted for publication in \emph{Mathematical Programming}.

	\bibitem{zou2019}
	Zou, J., S. Ahmed, and X.A. Sun. 2019. Stochastic dual dynamic integer programming. \emph{Mathematical Programming}. 175, pp. 461--502.

	\bibitem{ntaimo2005}
	Ntaimo, L., and S. Sen. 2005. The Million-Variable ``March'' for Stochastic Combinatorial Optimization. \emph{Journal of Global Optimization}. 32, pp. 385-–400.

	\bibitem{schultz1998}
	Schultz, R., L. Stougie, and M.H. van der Vlerk. 1998. Solving stochastic programs with integer recourse by enumeration: a framework using Gr\"obner basis reductions. \emph{Mathematical Programming}. 83(1–3), pp. 229-–252.

\end{thebibliography}

\end{document}