\section{Project Description}

One of the focus areas for DIANA~\cite{DIANA-proposal-2014} is to ``establish infrastructure for a higher-level of collaborative analysis, building on the successful patterns used for the Higgs boson discovery''.
A large component of this focus is statistical software.
\code{RooFit}~\cite{Verkerke:2003ir} is one of the primary tools used now, but it is facing scalability challenges.
In addition to processing speed, which is being addressed with GPU-based fitting approaches, we also face memory limitations as the combined statistical models grow in size.
Thus, it is critical to investigate more distributed models.\\

Within only a couple of years, the rapid development of software libraries for numerical computations through data flow graphs (e.g., \code{TensorFlow}~\cite{tensorflow2015-whitepaper}, \code{Theano}~\cite{theano-full}, and \code{MXNet}~\cite{DBLP:journals/corr/ChenLLLWWXXZZ15}) has led to a fundamental change of paradigm in machine learning software.
These libraries are designed around the concept that a numerical program can often equivalently be expressed as a graph --- where nodes represent mathematical operations and edges represent the data communicated between them.
Most notably, these libraries allow one to automatically deploy computation over one or more CPUs or GPUs within a single API. This makes it easy to maximize performance without specialized software expertise.\\

While these frameworks were originally developed for the purpose of deep learning research, they are usually general enough to be applicable in a wide variety of other domains.
For this reason, the objective of this DIANA project --- conducted by Matthew Feickert under the mentorship of Gilles Louppe and Vince Croft --- is to investigate the pros and cons of implementing the statistical models used in particle physics with a different computational graph framework.
As these models are typically built with \code{RooFit} and \code{HistFactory}~\cite{Cranmer:2012sba}, we first wish to establish reference benchmarks in these frameworks.
Later in the project, we will assess the capabilities and limits of different frameworks and determine how they would scale in terms of data and model parallelism.
In addition, the study should also determine whether existing probabilistic programming framework based data flow graphs (e.g., \code{Edward}~\cite{tran2016edward} and \code{tensorprob}~\cite{tensorprob2016}) are applicable for particle physics statistical models.
Where appropriate, the study should finally identify shortcomings on which further software efforts could be dedicated.\\

Chien-Chin Huang is a computer science Ph.D. student supported via DIANA.
He is investigating the model and data parallelism in systems such as \code{TensorFlow}.
A bottle neck in the current work is a set of benchmark physics problems that he can use for these scalability tests.
This DIANA fellowship would help remove that bottleneck and accelerate work to connect other DIANA projects like \code{Histogrammar}~\cite{histogrammar2017}.


% Copyright 2011, 2013 David W. Hogg (NYU).
% All rights reserved (for now).

% to-do
% -----
% - write
% - edit
% - post

\documentclass[12pt, letterpaper]{article}
\input{../hogg_style}

\newcommand{\data}{D}
\newcommand{\alldata}{\{D_i\}_{{\mathrm{all}}\,i}}
\newcommand{\galpars}{\theta}
\newcommand{\hyperpars}{\alpha}
\newcommand{\amplitude}{C}

\begin{document}
\section*{Data analysis recipes:\\
          Classification at low signal-to-noise}

\begin{abstract}
In classification problems of interest to physicists and astronomers,
it is not usually appropriate to use ``black-box'' classifiers (SVMs,
neural nets, and the like) trained on well-classified training sets.
This is because training data tend to be different---in selection,
calibration, signal-to-noise, or other important properties---from the
data on which the classification is to be performed.  Furthermore, the
data set to be classified is usually itself the best source of data
about the classification; if it weren't, the investigator wouldn't be
wanting to classify it!  Furthermore, the investigator usually wants
(whether or not he or she knows it) probabilistic classifications, for
use in subsequent utility-based hard classification or
forward-modeling projects.  Here we show that if the investigator has
generally useful information about the different classes and a noise
model for the data, hierarchical probabilistic inference can be used
to construct extremely successful classifiers even with no training
data whatsoever.  The method works by building a mixture-of-classes
model for the observed data, finding class probabilities and parameter
distributions that optimize the probability of the data under the
model (the marginalized likelihood), and then competing the classes
(mixture components) probabilistically.
\end{abstract}

The general problem of classification with noisy data has generated an
enormous literature, and a wide range of very capable and useful
techniques.  Most of these techniques are useless for the kind of
problems and objectives that physical scientists encounter: These are
problems where there are not extremely reliable training sets, where
the noise in the data is at least partially understood, and where the
objective is to propagate uncertainty through the classification
process.

For example, consider the astronomical problem of star--galaxy
separation: The goal is to take a set of images of the sky through
different filter bandpasses, and determine which of the astronomical
sources in the image are stars and which are galaxies.

Equations we will encounter include the following:
\begin{eqnarray}\displaystyle
p(\data_i|S,I) &=& \normal(\data_i|0,\sigma_i^2) \\
p(\data_i|G,\galpars,I) &=& \normal(\data_i|\galpars_i,\sigma_i^2) \\
p(\data_i|G,I,\hyperpars) &=& \int p(\data_i|G,\galpars,I)\,p(\galpars|G,\hyperpars)\,\dd \galpars \\
p(\data_i|I,\hyperpars) &=& \sum_{q=S}^G p(\data_i|q,I,\hyperpars)\,P_q \\
1 &=& \sum_{q=S}^G P_q \\
p(\alldata|I,\hyperpars) &=& \prod_i p(\data_i|I,\hyperpars) \\
p(\data_i|k,\amplitude_{ki},I) &=& \normal(\data_i|\amplitude_{ki},\Sigma_i^2) \\
p(\data_i|k,I,\hyperpars) &=& \int p(\data_i|k,\amplitude_{ki},I)\,p(\amplitude_{ki}|k,\hyperpars)\,\dd \amplitude_{ki} \\
p(\data_i|I,\hyperpars) &=& \sum_k p(\data_i|k,I,\hyperpars)\,P_k \\
1 &=& \sum_k P_k \\
p(\alldata|I,\hyperpars) &=& \prod_i p(\data_i|I,\hyperpars) \\
\end{eqnarray}

\end{document}


\section{An error in Hickerson et al.'s re-analysis of the Philippines data}
\citet{Hickerson2013} re-analyzed the dataset of \citet{Oaks2012} using a
model-averaging approach, where they placed a discrete uniform prior over eight
different prior models (see Table 1 of \citet{Hickerson2013}).
However, there was an error in their methodology; their model mixes different
units of time.

Each of the eight prior models used in the re-analysis by \citet{Hickerson2013}
has one of two priors on the mean size of the descendant populations of each
taxon pair:
$\meanDescendantTheta{} \sim U(0.0001, 0.1)$ or
$\meanDescendantTheta{} \sim U(0.0005, 0.04)$.
As described in \citet{Oaks2012}, the divergence-time parameters in the model
implemented in \msb are in generations scaled relative to a constant
reference-population size, \myTheta{C}.
This reference-population size is defined in terms of the upper limit of the
uniform prior on the mean size of the descendant populations,
\meanDescendantTheta{}, such that for the prior $\meanDescendantTheta{} \sim
U(\uniformMin{\meanDescendantTheta{}},\uniformMax{\meanDescendantTheta{}})$,
the size of the constant reference population is $\myTheta{C} =
\uniformMax{\meanDescendantTheta{}}/2$.
Thus, the model used by \citet{Hickerson2013} mixes two different units of
time.
In other words, some of their prior and posterior samples are in units of
$0.05/\mutationRate$ generations, whereas others are in units of
$0.02/\mutationRate$ generations.

A fundamental assumption of the \msb model and post hoc regression adjustment
is that all possible values of the parameter of interest (divergence times) are
in the same units.
Thus, the results in sections ``Using ABC Model Comparison to Weight
Alternative Priors for the Philippine Vertebrate Data'' and ``Improved Sampling
Efficiency by Prior Weighting Supports Asynchronous and Recent Divergence for
the Philippines Vertebrate Data'' and presented in Figure 2 of
\citet{Hickerson2013} are invalid and should be disregarded.
The error is easily illustrated by re-plotting their results with the different
time units indicated (Figure~S\ref{figJointPosteriorHickerson}).

\section{Theoretical implications of empirical priors for Bayesian model
choice---A simple example}
\begin{linenomath}
The distinctions between Bayesian parameter estimation and model choice
discussed in the main text can be illustrated with a simple example.
Let us say we are interested in the fairness of a particular coin, and we
denote the unknown probability of it landing heads as \myTheta{}.
More specifically, we are interested in the probability of two models, $M_1$
and $M_2$.
In both models the outcomes of flipping the coin are assumed to be binomially
distributed, but under $M_1$ the coin is weighted toward landing heads (i.e.,
$\myTheta{} > 0.5)$), whereas under $M_2$, the coin is weighted toward landing
tails (i.e., $\myTheta{} < 0.5$).
We already have data from flipping a different coin 20 times that landed both
heads and tails 10 times each, and so we decide to use these data in specifying
a beta prior on fairness of the new coin of $beta(a=10, b=10)$
(Figure~S\ref{figCoinFlip}).
We collect data by flipping the coin of interest $N=10$ times, $y=3$ of which
land heads.
Given the beta distribution is a conjugate prior for a binomial likelihood, the
posterior distribution has the nice analytical form $\theta \given y,N \sim
beta(a + y, b + N - y)$, which for the new dataset is simply $beta(13, 17)$
(Figure~S\ref{figCoinFlip}).
The maximum a posteriori (MAP) estimate of the probability of heads is 0.429,
and following Equation~\ref{eq:marginallikelhiood} in the main text the
marginal likelihoods of our models of interest are
\begin{equation}
    p(y=3, N=10 \given M_1) = \int_{0.5}^{1} p(y=3, N=10 \given
    \myTheta{}, M_1)p(\myTheta{} \given M_1) d\myTheta{} \approx 0.029,
\end{equation}
and
\begin{equation}
    p(y=3, N=10 \given M_2) = \int_{0}^{0.5} p(y=3, N=10 \given
    \myTheta{}, M_2)p(\myTheta{} \given M_2) d\myTheta{} \approx 0.097.
\end{equation}
Given the models have equal probability under our prior, we can calculate the
posterior probability of Model 1 as
\begin{equation}
    p(M_1 \given y=3, N=10) = \frac{p(y=3, N=10 \given M_1)}{p(y=3, N=10 \given
    M_1) + p(y=3, N=10 \given M_2)} \approx 0.23.
\end{equation}
This is the correct posterior probability of Model 1 given our prior
and data.
\end{linenomath}

To give the data more weight relative to the prior, we could use it twice, and
calculate an empirical Bayes estimate using a prior of $beta(13,17)$.  This
results in a ``posterior'' distribution of $beta(16, 24)$
(Figure~S\ref{figCoinFlip}), with a MAP estimate of 0.395, and $p(M_1 \given
y=3, N=10) = 0.10$.
The estimated posterior distribution of the parameter, and resulting MAP
estimate, is similar whether or not an empirically informed prior is used.
However, the posterior probability of Model 1 is very sensitive to the
empirical prior, decreasing by 56\%.
By using the empirically informed prior, we ignored prior uncertainty, leading
to an underestimate of our posterior uncertainty (Figure~S\ref{figCoinFlip}).
While this did not greatly affect our estimate of \myTheta{}, it misled us
to be overconfident in Model 2.
% Our mode estimate of \myTheta{} under the empirical prior might be closer
% to the true value than our posterior mode.
% Let us assume the truth of the matter is that the coin under study has a broad
% flat edge, and as a result lands on its edge at a certain frequency.
% Hence, both of our models are incorrect (i.e., the outcomes of flipping the
% coin are not binomially distributed).

% This can be demonstrated with a simple, albeit contrived, example.
% Let us say that principal investigator Mary and her new postdoc Will are
% interested in the hypothesis that the mass of George Washington's periwig
% renders the quarter dollar of the United States unfair.
% That is to say their null hypothesis is that the probability of a US
% quarter landing heads when tossed is less than 0.5 ($\theta < 0.5$).
% They can certainly evaluate this hypothesis, they can have undergraduate
% worker, Joe, flip the coin for them while they tabulate the results.
% But being Bayesians, before they call Joe into the lab, they agree on a
% prior probability to place on the set of all possible probabilities that
% the quarter will land heads when it is flipped.
% Given that neither of them have a quarter, and their prior knowledge that Joe
% moonlights as a magician, and is notorious for performing coin and card tricks
% in the lab, they suspect there is a good chance that the quarter Joe uses will
% be either two-headed or two-tailed.
% So, knowing that the beta distribution is the conjugate prior for a binomial
% likelihood, they decide to use a $beta(a=0.5, b=0.5)$ prior distribution
% (Figure~\ref{figCoinFlip}).

% Mary calls Joe into the lab, confirms that he has a quarter, and tells him to
% begin flipping it.
% After five tosses, four of which was heads, Joe decides that academics are
% crazy and leaves the lab to pursue a major in theatre.  Mary and Will, both
% being computational biologists, are satisfied with their
% empirical dataset of $y = 4$ heads out of $N = 5$ trials.
% They know from the conjugacy of the beta prior, that the posterior distribution
% has the nice analytical form $\theta|y,N \sim beta(a + y, b + N - y)$, which
% in this case is simply $beta(4.5, 1.5)$; this is the true posterior distribution
% of $\theta$ given their prior belief and data (Figure~\ref{figCoinFlip}).
% This allows them to plug these values into the beta cumulative distribution
% function to determine that the posterior probability of their hypothesis is
% $p(\theta < 0.5 | y=1, N=5) = 0.088$.
% Given their prior belief and dataset, this indeed is the correct posterior
% probability of the hypothesis, and Mary and Will should now update their
% posterior belief accordingly.

% However, reflecting upon the results of their experiment
% (Figure~\ref{figCoinFlip}), Mary and Will regret their choice of prior.
% Their prior looks very ``poorly selected,'' and if they had only known that the
% coin was fair before the data were collected, they would have selected a much
% better prior.
% Clearly, from their results, they should have used a prior centered
% around 0.2; their data suggest a prior of $beta(4.5, 1.5)$ would have been
% much ``better.''
% Rather than resort to flipping the coin five more times, Mary and Will decide
% to redo their analysis using the much better ``prior'' of $p(\theta) \sim
% beta(4.5, 1.5)$.
% This gives a ``posterior'' of $\theta|y,N \sim beta(8.5, 2.5)$, and a
% probability of their hypothesis of $p(\theta < 0.5 | y=1, N=5) = 0.026$.
% Now convinced that the US quarter is unfair, albeit not due to the mass of
% President Washington's head as they hypothesized, Will begins composing an
% e-mail of complaint addressed to the U.S.\ Mint.

% If Joe's flips were a representative sample, Mary and Will's empirical Bayes
% estimate might very well be a better point estimate for the parameter
% \myTheta{}.
% However, their empirical Bayes estimate of the probability of their hypothesis
% is incorrect and biased.
% This simple example shows how parameter estimation is fundamentally different
% from estimating the probability of a model.
% While empirically informed priors can be used to obtain well-behaved parameter
% estimators, using them for model choice is much less certain.

\section{Validation analyses}
Following \citet{Oaks2012}, we characterize the model-choice behavior of the
model-averaging approach of \citet{Hickerson2013} under the ideal conditions
where the prior is correct (i.e., the data are generated from parameters drawn
from the same prior distributions used in the analysis).
We used the same prior models as above ($M_1$--$M_5$;
Table~\ref{tabModelChoiceEmpirical}), and simulated 50,000 datasets under this
prior (10,000 from each model).
We used a simulated data structure of eight population pairs, with a single
1000 base-pair locus sampled from 10 individuals from each population.
We then analyzed each of these replicate datasets using the same prior with 2.5
million samples (500,000 from each of the five prior models), retaining 1000
posterior samples.
Our results are very similar to \citet{Oaks2012}, but we note that they
are not directly comparable as our simulations contained eight population
pairs rather than 10 (Figure~\ref{figValidationMCBehavior}).
We find that the approach of \citet{Hickerson2013} estimates the posterior
probability of divergence models reasonably well when all assumptions of the
method are met (i.e., the prior is correct) and the unadjusted posterior
estimates are used.
Similar to \cite{Oaks2012}, we find that the regression-adjusted estimates of
the model probabilities are biased.

\section{A difficult inference problem}
In the main text, we discuss how the prior assumption of uniformly distributed
divergence times in \msb leads to posteriors that are difficult to interpret.
However, it is also important to consider the difficult inference problem with
which \msb is faced.
When applying \msb to the dataset of \citet{Oaks2012} with 22 taxon
pairs, there are 581--602 free parameters that model highly stochastic
coalescent and mutational processes.
Under this rich stochastic model, the method is estimating the
probability of 1002 divergence models \citep[i.e., the number of integer
partitions of $Y=22$;][]{Oaks2012}.
Furthermore, all the information in the sequence alignment of each taxon pair
is distilled into four summary statistics.
This gives us a total of 88 summary statistics (four from each of the 22 taxon
pairs) that contain minimal information about many of the $\approx 600$
parameters in the model.
More summary statistics can be used in \msb, but most are highly correlated
with the four default statistics, and thus contribute little additional
information about the parameters from the sequence data.
The large number of parameters and divergence models relative to the amount of
information in the data is undoubtedly another reason the method lacks
robustness to prior conditions.

\section{Additional clarifications from \citet{Hickerson2013}}

\subsection{Saturation of summary statistics}
\citet{Hickerson2013} claim the priors used by \citet{Oaks2012} ``cause much of
the explored parameter space to be beyond the threshold of saturation in most
mtDNA genes.'' To explore this possibility, we simulated datasets under prior
settings that match two of the three priors used by \citet{Oaks2012}:
$\meanDescendantTheta{} \sim U(0.0005, 0.04)$ and $\ancestralTheta{} \sim
U(0.0005, 0.02)$.
Under this prior, we randomly sample divergence-time parameters from a uniform
distribution of $U(0, 20)$ coalescent units, simulate datasets, and plot the
\divt{} values against the summary statistics calculated from the resulting
datasets (Figure~\ref{figSaturationPlot}).
Clearly, the priors used by \citet{Oaks2012} with upper limits on \divt{} of five
and 10 coalescent units suffered little to no effect from saturation.
Even at divergence times of 20 coalescent units, there is still signal in the
summary statistics used by \msb (Figure~\ref{figSaturationPlot}).
Thus, the assertion of \citet{Hickerson2013} that the priors used by
\citet{Oaks2012} sample parameter space in which the mtDNA alignments are
saturated by substitutions is incorrect and, as a result, does not explain the
bias they found.

\subsection{Graphical prior comparisons}
\citet{Hickerson2013} advocate the use graphical checks of prior models.
This prior-predictive approach entails generating a small number (1000) of
random samples from the prior and plotting the resulting summary statistics in
comparison to the observed statistics to see if they coincide (see Figure 1 of
\citet{Hickerson2013}).
% As we show above, this strategy can be misleading, because the resulting plots
% of this approach have little correlation with the appropriateness of priors.
Given the richness of the \msb model ($\approx 600$ parameters for the Philippine
dataset analyzed by \citet{Hickerson2013}), we do not expect that 1000
\emph{random} draws from the vast prior parameter space will yield data and
summary statistics consistent with the observed data.
In fact, when such random draws are tightly clustered around the observed
statistics, this can be an indication that the prior is over-fit, as we show in
the main text (Table~\ref{tabModelChoiceEmpirical} and Figure~S\ref{figPCA}).
Thus, using such plots to select priors should be avoided, and the use of
posterior-predictive analyses would be much more informative about the overall
fit of models.

\subsection{Differing utilities of \numt{} and \vmratio{} in \texttt{msBayes}}
The primary component of the \msb model is the vector of divergence
times for each of the taxon pairs,
$\divtvector = \{\divt{1}, \ldots, \divt{Y}\}$
\citep{Oaks2012}.
\citet{Hickerson2013} argue that the dispersion index of this vector,
\vmratio{}, is a better model-choice estimator than the number of
divergence-time parameters within the vector,
\numt{}.
They present a plot of \numt{} against \vmratio{} (Fig.~S1 of
\citet{Hickerson2013}), which is essentially a plot of sample size versus
variance.
This plot shows that \vmratio{} has very little information
about the number of divergences among taxa.
Nonetheless, \citet{Hickerson2013} conclude \vmratio{} is more informative and
biogeographically relevant than \numt{}.
% We struggle to follow this logic.
However, the number of divergence-time parameters within the vector and their
values contains all of the information about the temporal distribution of
divergences, and is much more informative than the variance (i.e., the
dispersion index is not a sufficient statistic for \divtvector).
\citet{Hickerson2013} also argue that \msb can estimate \vmratio{} much better
than \numt{}.
However, \citet{Oaks2012} demonstrate that even when all assumptions of the
model are met, \vmratio{} is a poor model-choice estimator (see plots B, D \& F
of Figure 4 in \citet{Oaks2012}), whereas \numt{} performs better.

Importantly, \vmratio{} is limited to estimating the probability of only a
single model (the one-divergence model), and thus its utility for model-choice
is very limited.
I.e., it can only be informative about the probability of whether there is one
divergence shared among the taxa ($\vmratio{} = 0.0$) or there is greater than
one divergence ($\vmratio{} > 0.0$).
As a result, not only is its model-choice utility limited, but it is also
very difficult to estimate.
\vmratio{} can range from zero to infinity, and the point density that it is
at its lower limit of zero will always be zero.
Thus, an arbitrary threshold (0.01 is used throughout the \msb literature) must
be chosen to make the probability of ``simultaneous'' divergence estimable.
Even with this arbitrary threshold, it is still not surprising to see that it
is numerically difficult to obtain reliable estimates of the probability that
\vmratio{} is ``near'' its lower limit of zero.
It is easier, less subjective, and more interpretable to estimate the
probability of the model with one divergence-time parameter (i.e., $\numt{} =
1$).
Thus, it is not surprising that \citet{Oaks2012} find that \numt{} is a better
estimator of model probability than \vmratio{}.


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

\section{Covariant quantization of the electromagnetic field}

\marginpar{Saturday\\ 2020-6-20, \\ compiled \\ \today}

We try to apply the canonical quantization procedure with commutators to our massless vector field theory, with the gauge fixing term in the Feynman gauge \(\xi = 1\).

From the Poisson brackets we derived from the fields we obtain the quantization conditions:
%
\begin{align}
\qty[A^{\mu }(\vec{x}, t), \pi^{\prime, \nu }(\vec{y}, t)] = i \eta^{\mu \nu } \delta^{(3)} (\vec{x}-\vec{y})
\,,
\end{align}
%
while the commutators of \(\qty[A, A]\) and \(\qty[\pi , \pi ]\) vanish.
Here we have \(\pi^{\prime \nu } = - \partial_0 A^{\mu }\): so, we can write everything in terms of \(A\),
%
\begin{align}
\qty[A^{0} (\vec{x}, t), \partial_0 A^{0} (\vec{y}, t)] &= - i \delta^{(3)} (\vec{x} - \vec{y}) \\
\qty[A^{i} (\vec{x}, t), \partial_0 A^{i} (\vec{y}, t)] &= + i \delta^{(3)} (\vec{x} - \vec{y})
\,,
\end{align}
%
so the spatial components \(A^{i}\) obey the same quantization conditions as the \emph{real scalar field}, while the temporal component has an extra minus sign.
This is a qualitative indication of the fact that something will be wrong with the quantization of \(A^{0}\).

\begin{claim}
The creation and annihilation operators for the massless vector field can be written as
%
\begin{align}
a_0 (k) &= - \frac{1}{(2 \pi )^{3/2}} \int \frac{ \dd[3]{x}}{\sqrt{2 \omega_{k}}}
\epsilon^{\mu }_{(0)} (k) \qty(\omega_{k} A_{\mu } (x) + i \partial_0 A_{\mu }(x))\eval{e^{ikx}}_{k_0 = \abs{\vec{k}}} \\
a_i (k) &= + \frac{1}{(2 \pi )^{3/2}} \int \frac{ \dd[3]{x}}{\sqrt{2 \omega_{k}}}
\epsilon^{\mu }_{(i)} (k) \qty(\omega_{k} A_{\mu } (x) + i \partial_i A_{\mu }(x))\eval{e^{ikx}}_{k_0 = \abs{\vec{k}}}
\,.
\end{align}
\end{claim}

\begin{proof}
\todo[inline]{To do.}
\end{proof}

With this, the canonical quantization conditions needed to recover the harmonic oscillator algebra with these creation and annihilation operators read:
%
\begin{align}
\qty[a_{\lambda } (k), a ^\dag_{\lambda '} (p)] = - \eta_{\lambda \lambda'} \delta^{(3)} (\vec{k} - \vec{p})
\,,
\end{align}
%
while the \(\qty[a, a]\) and \(\qty[a ^\dag, a ^\dag]\) commutators vanish. So, we have \textbf{four} sets of harmonic oscillators, parametrized by \(\lambda \).
Once again the \(\lambda = 0\) polarization has the wrong sign (\(- \eta_{00 } = -1\)).

Let us now try and define the observables of this theory.

\subsubsection{Number density operator}

Let us define
%
\begin{align}
\mathscr{N}_{0}(k) = - a_0  ^\dag (k) a_0 (k)
\qquad \text{and} \qquad
\mathscr{N}_{i}(k) = + a_i  ^\dag (k) a_i (k)
\,,
\end{align}
%
and the corresponding number operators \(N_{\mu } = \int \dd[3]{k} \mathscr{N}_{\mu } (k) \).

The different sign for \(a_0 \) is needed in order to ensure the correct commutation relations, which read:
%
\begin{align}
\qty[N_{\mu }, a_\mu^{(\dag)}(k)] = \mp a_{\mu }^{(\dag)}(k)
\,,
\end{align}
%
where we have the \(+\) if the dagger is present, \(-\) if it is not present.

\subsubsection{Hamiltonian and momentum density}

Since we have defined the number density \(\mathscr{N}_{\lambda } (k)\), we can also define the Hamiltonian as
%
\begin{align}
H = \int \dd[3]{x} \mathscr{H}' =
\int \dd[3]{k} \omega_{k} \sum _{\lambda } \mathscr{N}_{\lambda } (k)
\,.
\end{align}

As usual, normal ordering is implied. Similarly, the momentum operator is
%
\begin{align}
P_{i} = - \int \dd[3]{x} \eta^{\mu \nu } \qty(\partial_0 A_{\mu } \partial_{i} A_{\nu })
= \int \dd[3]{k} k_i \sum _{\lambda=0}^{3} \mathscr{N}_{\lambda } (k)
\,.
\end{align}

These look sensible: however, the issue lies in the definition of the number density operator.

\begin{claim}
The Heisenberg-picture evolution equations read
%
\begin{align}
\dv{A_{\mu }}{t} (\vec{x}, t) &= -i \qty[A_{\mu }(\vec{x}, t), H] \\
\dv{\pi'_{\mu }}{t} (\vec{x}, t) &= -i \qty[\pi '_{\mu }(\vec{x}, t), H]
\,,
\end{align}
%
where the Hamiltonian can be found by integrating the Hamiltonian density
%
\begin{align}
\mathscr{H}' = \frac{1}{2} \qty(\pi^{\prime 2}_i + \qty(\partial_{i} A_{j})^2 - \pi_0^2 - \qty(\partial_{i} A_0 )^2)
\,,
\end{align}
%
so we can see again that the issue lies in the \(0\)-index part.
\end{claim}

\subsection{Fock space and indefinite metric}

We want to discuss how the Fock space for a vector field can be defined.

The definition of the \textbf{vacuum}, as usual, is \(a_{\lambda } (k) \ket{0} = 0\) for all \(k\).

For \(\lambda \in (1, 2, 3)\) there are no issues, we proceed as in the scalar case by populating the vacuum with particles. The unphysical behaviour comes out for \(\lambda = 0\): then, we would try to define a 1-particle state by
%
\begin{align}
\ket{1(k, 0)} \propto a ^\dag_{0} (k) \ket{0}
\,,
\end{align}
%
but then we can see that the norm of this state is negative:
%
\begin{align}
\braket{1(k, 0)}{1(p, 0)} &\propto \bra{0} a_0 (k) a_0 ^\dag (p) \ket{0}  \\
&= \bra{0} \qty[ a_0 (k),  a_0 ^\dag (p)] \ket{0} - \underbrace{\bra{0} a_0 ^\dag (p) a_0 (k)  \ket{0}}_{= 0}  \\
&= - \delta^{(3)} (k-p) \leq 0
\,,
\end{align}
%
which means that the metric on the Hilbert space of states is \textbf{not positive definite}!
This is a problem: it directly leads to negative probabilities.
We have the expectation values:
%
\begin{align}
\bra{1(k, 0)} N_{0} \ket{1(k, 0)} = - 1
\qquad \text{and} \qquad
\bra{1(k, 0)} H_{0} \ket{1(k, 0)} = - \omega_{k}
\,.
\end{align}

So, this new gauge-fixing theory we are trying to quantize leads to inconsistent results! We surely will need to throw it out, right?

\subsection{The Gupta-Bleuer condition}

The Fock space we have constructed contains unphysical states. However, we also know that the theory we have quantized is not electromagnetism, and in fact it is larger, since it has 4 degrees of freedom.

Right now the equations of motion for our theory (with \(\xi = 1\)) read \(\square A^{\mu } = 0\); however in classical electromagnetism this condition only holds as long as \(\partial_{\mu } A^{\mu } = 0\).

So, we need a way to enforce this condition. We have seen that we \emph{cannot impose \(\partial_{\mu } A^{\mu } = 0\) in an operatorial sense}, since the condition it leads to is not a covariant one.

The \textbf{Gupta-Bleuer} condition is a workaround: instead of imposing the condition on operators, we impose it by restricting the Fock space: if \(\ket{\text{phys}}\) is any physical state, we ask that
%
\begin{align}
\bra{\text{phys}'} \partial_{\mu } A^{\mu } \ket{\text{phys}} =0
\,.
\end{align}

The set of states \(\qty{\ket{\text{phys}}}\) which satisfy this condition is a subset of the Fock space.

\begin{claim}
We can state the GB condition equivalently as
%
\begin{align}
\partial_{\mu }A^{\mu }_{+ } \ket{\text{phys}} = 0
\qquad \text{or} \qquad
\bra{\text{phys}} \partial_{\mu }A^{\mu }_{- }  = 0
\,.
\end{align}
\end{claim}

The \(+\) solution for the EM field gives us
%
\begin{align}
\partial_{\mu } A^{\mu }_{+} (x) = \frac{- i}{(2 \pi )^{3/2}}
\int \frac{ \dd[3]{k}}{\sqrt{2 \omega_{k}}}
\underbrace{k_\mu \sum _{\lambda = 0 }^{3} \epsilon^{\mu }_{\lambda }(k) a_\lambda (k) \eval{e^{-ikx}}_{k_0 = \abs{\vec{k}.}}}_{L(k)}
\,.
\end{align}

We can use the operator \(L(k)\) in order to understand what the Gupta-Bleuer condition tells us in momentum space: it is
%
\begin{align}
L(k) \ket{\text{phys}} = 0
\qquad \text{or} \qquad
\bra{\text{phys}} L ^\dag (k) = 0
\,.
\end{align}

This can be understood better if it is expressed in terms of the polarization vectors: recall that \(\epsilon^{\mu }_{(0)} = n^{\mu }\), \(\epsilon^{\mu }_{(3)} = (k^{\mu } - (n \cdot k) n^{\mu }) / (n \cdot k)\) while the other two polarizations are orthogonal: \(\epsilon^{\mu }_{(1, 2)} k_\mu =0 \).

In terms of these, we have
%
\begin{align}
L(k) &= k_{\mu } \qty(n^{\mu } a_0 (k) + \qty(\frac{k^{\mu }}{(n \cdot k)} - n^{\mu } ) a_3(k))   \\
&= (k \cdot n) \qty(a_0 (k ) - a_3 (k))
\,,
\end{align}
%
since \(k^2=0\).
Then, we can explicitly write that \(L (k) \ket{\text{phys}} =0 \) means:
%
\begin{align}
a_0 (k) \ket{\text{phys}} =
a_3 (k) \ket{\text{phys}}
\,,
\end{align}
%
while \(\bra{\text{phys}} L ^\dag (k) = 0\) means:
%
\begin{align}
\bra{\text{phys}} a_0 ^\dag (k) =
\bra{\text{phys}} a_3 ^\dag (k)
\,.
\end{align}

Let us see what this means in terms of actual measurable properties of these physical states: first of all, it means that
%
\begin{align}
\expval{\mathscr{N}_{0} + \mathscr{N}_{3}} _{\text{phys}} &=
\expval{
    a ^\dag_{3} (k) a_3 (k ) -
    a ^\dag_{0} (k) a_0 (k )
    }
_{\text{phys}}  \\
&=
\expval{
    a ^\dag_{3} (k) a_3 (k ) +
    L ^\dag (k) a_0(k) -
    a ^\dag_{0} (k) a_0 (k )
    }
_{\text{phys}}   \\
&=
\expval{
    a ^\dag_{3} (k) a_3 (k ) +
    a ^\dag_{0}(k) a_0(k) -
    a ^\dag_{3} (k) a_0 (k) -
    a ^\dag_{0} (k) a_0 (k )
    }
_{\text{phys}}  \\
&=
\expval{
    a ^\dag_{3} (k) a_3 (k ) -
    a ^\dag_{3} (k) a_0 (k)
    }
_{\text{phys}}   \\
&= - \expval{
    a ^\dag_{3} (k) L(k)
    }
_{\text{phys}}  = 0
\,,
\end{align}
%
therefore when we compute the expectation of \(\sum _{\lambda } \mathscr{N}_{\lambda }(k)\) on physical states we find only the contributions from the transverse (\(1\) and \(2\)) polarizations.
This also applies to the Hamiltonian, since in momentum space it is proportional to \(\sum _{\lambda } \mathscr{N}_{\lambda }\).

So, if we require the Gupta-Blauer condition the observables do not depend on the 0 and 3 polarizations; so we can only consider the two transverse ones and be left with a theory that now corresponds to a true quantization of classical electromagnetism, since we have the three conditions
\begin{enumerate}
    \item \(\square A^{\mu } = 0\);
    \item \(\partial_{\mu } A^{\mu } = 0\) for physical states;
    \item two polarizations.
\end{enumerate}

We define \textbf{pseudophoton states} as ones which are obtained by applying \(L ^\dag\) to a physical state (note: the vacuum is a physical state, since \(a_{\mu } \ket{0} = 0\) for any \(\mu \)).

\begin{claim}
A pseudophoton state \(\ket{\psi }\) satisfies the following properties:
\begin{enumerate}
    \item \(\braket{\psi }{\psi } = 0\): zero norm;
    \item \(\braket{\psi }{\text{phys}} = 0\): orthogonality to physical states;
    \item \(\ev{H}{\psi } = 0\): zero energy.
\end{enumerate}

Also, the operator \(L(k)\) has the following properties:
\begin{enumerate}
    \item \(\qty[L(k), L ^\dag(p)] = 0\);
    \item \(\qty[L(k), H] = \omega_{k} L(k)\).
\end{enumerate}
\end{claim}

\begin{proof}
\todo[inline]{To do.}
\end{proof}

\begin{claim}
If \(\ket{P}\) is a physical state, and \(\ket{Q} = \ket{P} + \ket{\psi }\) where \(\psi \) is a pseudophoton state then we have
%
\begin{align}
\braket{Q}{Q} = \braket{P}{P}
\qquad \text{and} \qquad
\bra{Q} H \ket{Q} = \bra{P} H \ket{P}
\,.
\end{align}
\end{claim}

\begin{proof}
The first statement is proven using the facts that pseudophoton states are orthogonal to physical ones and have zero norm:
%
\begin{align}
\braket{Q}{Q} = \braket{P}{P} +
\underbrace{\braket{P}{\psi } +\braket{\psi }{P} + \braket{\psi }{\psi }}_{0}
\,.
\end{align}

The second statement is similarly proven: if can be expressed in terms of \emph{physical} energy eigenvectors as \(\ket{P} = \sum _{n} a_n\ket{n}\)
%
\begin{align}
\bra{Q} H \ket{Q} &=
\bra{P} H \ket{P}
+ \bra{P} H \ket{\psi }
+ \bra{\psi } H \ket{P }
+ \underbrace{\bra{\psi } H \ket{\psi }}_{0}  \\
&=
\bra{P} H \ket{P}
+ \qty(\sum _{n} a_n \bra{n}) H \ket{\psi }
+ \bra{\psi } H \qty(\sum _{n} a_n \ket{n})  \\
&= \bra{P} H \ket{P}
+ \sum _{n} a_n E_n \underbrace{\braket{n}{\psi }}_{0}
+ \sum _{n} a_n E_n \underbrace{\braket{\psi }{n }}_{0}
\,.
\end{align}
\end{proof}

So, we can take as our states \textbf{equivalence classes} of states, up to addition of pseudophoton states.

We generate physical Fock states by repeatedly applying the transverse polarization creation operators to them; and then add an arbitrary amout of pseudophoton states.

\begin{claim}
These equivalence classes are related to residual gauge invariance.
\end{claim}

\subsection{Covariant commutators for the photon}

The covariant commutator can be calculated as
%
\begin{align}
D^{\mu \nu } (x-y) &= \qty[A^{\mu  }(x), A^{\nu }(y)]  = D^{\mu \nu }_{+}(x-y) + D^{\mu \nu }_{-} (x-y)  \\
&= \qty[A^{\mu }_{+} (x), A^{\nu }_{-}(y)]
+ \qty[A^{\mu }_{-} (x), A^{\nu }_{+}(y)]
\,,
\end{align}
%
and if we plug in the solution to the Maxwell equations \(\square A^{\mu } = 0\) we find
%
\begin{align}
\qty[A^{\mu }_{+} (x), A^{\nu }_{-}(y)] &= - \eta^{\mu \nu } D_{+}(x-y) \\
\qty[A^{\mu }_{-} (x), A^{\nu }_{+}(y)] &= - \eta^{\mu \nu } D_{-}(x-y)
\,,
\end{align}
%
so their sum is
%
\begin{align}
D^{\mu \nu } (x-y) = - \eta^{\mu \nu } D_F(x-y)
\,,
\end{align}
%
and all the good results from the scalar case generalize.

\subsubsection{Summary}

We can quantize electromagnetism in a non-covariant way in either the Coulomb or Lorentz gauge.

In order to quantize it \textbf{covariantly} we need a different theory: we quantize a theory with an additional \textbf{gauge-fixing} term in the Lagrangian.
This theory's Fock space includes unphysical states, with negative norm and negative energy.

If we \emph{select} a subset of the Fock space with the \textbf{Gupta-Bleuer} condition we recover electromagnetism.
Different choices for the gauge-fixing Lagrangian give rise to different gauge choices.

One may ask: are the observables actually independent of the choice of \(\xi \) in the gauge-fixing Lagrangian? In fact they are, but this is not trivial to show; it depends on the \textbf{Ward identities} \eqref{eq:ward-identities}, which we will treat in a later chapter.

\end{document}


\documentclass[12pt,a4paper]{article}

\usepackage{amssymb,amsmath,color,enumitem,fancyvrb,hyperref,xspace}
\usepackage[affil-it]{authblk}

\bibliographystyle{alphaurl}
%\bibliographystyle{JHEP}

\setcounter{tocdepth}{2}
\fvset{fontsize=\small,commandchars=\\\{\}}

\definecolor{fuchsia}{RGB}{236,0,140}
\definecolor{prompt}{RGB}{245,124,0}
\definecolor{command}{RGB}{48,63,159}

\hypersetup{
    colorlinks,
    urlcolor={fuchsia},
    citecolor={blue}
}

\input include/commands.tex

\input include/layout.tex
\input include/title.tex

\begin{document}

\maketitle
\thispagestyle{empty}

\begin{abstract}
We present \fuchsia\xspace --- an implementation of the Lee algorithm, which for a given system of ordinary differential equations with rational coefficients $\partial_x\,\V J(x,\eps) = \M A(x,\eps)\,\V J(x,\eps)$ finds a basis transformation $\M T(x,\eps)$, i.e., $\V J(x,\eps) = \M T(x,\eps)\,\V J'(x,\eps)$, such that the system turns into the \textit{epsilon form}: $\partial_x\, \V J'(x,\eps) = \eps\,\M S(x)\,\V J'(x,\eps)$, where $\M S(x)$ is a Fuchsian matrix.
A system of this form can be trivially solved in terms of polylogarithms as a Laurent series in the dimensional regulator $\eps$.
That makes the construction of the transformation $\M T(x,\eps)$ crucial for obtaining solutions of the initial system.

In principle, \fuchsia can deal with any regular systems, however its primary task is to reduce differential equations for Feynman master integrals.
It ensures that solutions contain only regular singularities due to the properties of Feynman integrals.
\end{abstract}
\newpage

\input include/summary.tex
\newpage

\tableofcontents

\section{Introduction}

More than 60 years have passed since Richard Feynman proposed a diagrammatic approach for calculating perturbative processes in quantum field theories.
Since then Feynman integrals calculus has grown to a separate branch of mathematical physics with a big community of scientists conducting research in this exciting field.
With no doubt we can say that none of the recent discoveries in the high-energy particle physics could happen without precise theoretical calculations, which are based on the Feynman integrals calculation techniques.
It is also clear that such techniques will play a key role for discoveries at the present and future high-energy colliders, hence their development and further improvement are a very important task.

Recent progress in computational techniques has made it possible to automate the calculation of Feynman integrals; problems which seemed impossible 10 years ago now are successfully solved with state-of-the-art computer algorithms.
Among the most popular are integration-by-parts (IBP) reduction~\cite{CT81} and the method of differential equations (DE)~\cite{Kot91a,Kot91b,Kot91c}; for a detailed overview of these and other methods see~\cite{Smi06}.

In this paper we discuss the method of differential equations.
In particular, we focus on the fact that a solution to the system of DEs may be easily found as an $\eps$-series when an epsilon form of this system is known~\cite{Henn13}.
We consider a general algorithm to find an epsilon form of a given system of differential equations in one variable developed by Lee~\cite{Lee15}, for the review of the subject see~\cite{Henn14} and \cite{Pap14,Tan15,ABB15}.
The Lee algorithm allows
\begin{enumerate}
  \item To find a Fuchsian form of the system using improved Moser reduction algorithm \cite{Mos59}; and then
  \item To normalize eigenvalues of the Fuchsian system in all singular points.
\end{enumerate}
If these two steps are successfully completed%
\footnote{In principle, the first step can always be done because Feynman integrals contain only logarithmic singularities. For the discussion of potential complications in the second step see Section~\ref{sec:2}.}
then a transformation which puts the initial system into the epsilon form may be easily found.
Although this method is focused on systems for Feynman integrals, it also may be successfully used for different problems provided that the requirements on particular properties of the initial system are satisfied.
For another method for finding the epsilon form of a given system with multiple scales see \cite{Mey16a,Mey16b}.

Until recently, no implementation of the Lee method was made publicly available.
This fact motivated us to develop \fuchsia \ --- the first public implementation of the Lee algorithm~\cite{Lee15} which was presented in \cite{GM16}.
Another implementation of this method, called \texttt{Epsilon}, was recently presented in \cite{Pra17}.
In this paper we provide a description of some implementation and usage details of \fuchsia which together with algorithms and tools for the integration-by-parts reduction~\cite{Lap00,Smi08,MS12,Lee12,Lee13,SS13,Smi14,GLZ16} form a powerful tandem for evaluating Feynman integrals.

This paper is organized as follows: in Section \ref{sec:2} we introduce notation and definitions followed by a brief review of the Lee method and related algorithms implemented in \fuchsia.
In Section~\ref{sec:3} we describe how to install and how to use \fuchsia from different environments, depending on your goal and programming experience.

\section{Overview of the Lee method}
\label{sec:2}

\subsection{Notation and definitions}

Let us consider a system of ordinary differential equations (ODEs) of this form:
\begin{equation}
\label{eq:dj}
    \partial_x \V J(x,\eps) = \M A(x,\eps)\,\V J,
\end{equation}
where $\V J(x,\eps)$ is a column-vector of $n$ unknown functions (e.g., master integrals);
$x$ is a free variable;
$\eps$ is an infinitesimally small parameter (e.g., a dimensional regulator in $d=4-2\eps$ dimensions);
$\M A(x,\eps)$ is an $n \times n$ matrix, rational in both $x$ and $\eps$.

In the general case $\M A(x,\eps)$ may have a finite number of poles in $x$ at $x\in\{x_k\}$, including a pole at infinity.
The asymptotic behavior of $\M A(x,\eps)$ around these poles can be described as:
\begin{equation}
\label{eq:axeps}
    \M A(x \to x_k,\eps) =
    \begin{cases}
        (\M A_{k0}(\eps) + \M A_{k1}(\eps)\,(x - x_k) + \dots)/(x - x_k)^{1+p_k} & \text{if $x_k\neq\infty$}, \\
        -(\M A_{k0}(\eps) + \M A_{k1}(\eps)\,x^{-1} + \dots)\,x^{-1 + p_k} & \text{if $x_k=\infty$},
    \end{cases}
\end{equation}

where $p_k$ is the \textit{Poincar\'e rank} of $\M A(x,\eps)$ at the singular point $x=x_k$.
If $p_k=0$, we call $\M A(x,\eps)$ \textit{Fuchsian in $x=x_k$}, and $\M A_{k0}$ \textit{matrix residue} of $\M A(x,\eps)$ at $x=x_k$.
If all $p_k=0$, we call $\M A(x,\eps)$ \textit{Fuchsian}.

The behavior of the system at $x=\infty$ is a bit of a special case, but it is essential in the overall reduction process.
One must always keep in mind the $x=\infty$ point, and treat it on the same footing as other singular points.

\paragraph{Equivalent systems.}
We are interested in transforming system~\eqref{eq:dj} into a simpler form.
For this purpose let us consider a change of basis from $\V J$ into $\V J'$ using the linear transformation $\M T(x,\eps)$:
\begin{equation}
  \V J = \M T(x,\eps)\, \V J'.
\end{equation}

This leads to the {\em equivalent system} of ODEs
\begin{equation}
  \partial_x \V J' = \M A'(x,\eps)\,\V J',
\end{equation}
with the new matrix being
\begin{equation}
\label{eq:ta}
  \M A'(x,\eps) = \M T^{-1} \left( \M A \M T - \partial_x \M T \right).
\end{equation}

Generally speaking, the transformations $\M T(x,\eps)$ may have an arbitrary form.
However in the scope of this paper we will require the transformation matrices to be rational in both $x$ and $\eps$.
This restriction guarantees that the equivalent matrix $\M A'(x,\eps)$ and hence all equivalent systems are in rational form, thus making the expansion~\eqref{eq:axeps} possible.

In particular, we will be using the transformation constructed by stepwise application of a \textit{$\M P$-balance between $x=x_1$ and $x=x_2$}, defined as:
\begin{equation}
\label{eq:bal}
    \mathcal{B}(\M P(\eps), x_1, x_2; x) = \M I - \M P(\eps) + c \frac{x-x_2}{x-x_1} \M P(\eps),
\end{equation}
\begin{equation*}
    c \equiv
    \begin{cases}
        1/x_2 & \text{if $x_2=\infty$}, \\
        x_1 & \text{if $x_1=\infty$}, \\
        1 & \text{otherwise},
    \end{cases}
\end{equation*}
where $\M P(\eps)$ is a projector matrix (that is, $\M P^2=\M P$).

\paragraph{Classification of singularities.}
Following \cite{Mos59}, for a system \eqref{eq:dj} and its Laurent expansion~\eqref{eq:axeps} we define a rational number
\begin{equation}
\label{eq:mk}
    m_k(\M A) = p_k + \frac{rank(\M A_{k0})}{n}
\end{equation}
as the {\em Moser order} of $\M A(x,\eps)$ at point $x=x_k$.

Equivalent systems do not necessarily have identical Moser orders.
In fact, \cite{Mos59} introduces an algorithm that constructs a transformation decreasing $rank(\M A_{k0})$ by at least one (thus reducing $m_k(\M A)$),\footnote{Note, that if $rank(\M A_{k0})$ reaches zero, this means that $\M A_{k0}$ is now zero itself, and thus the Poincar\'e rank $p_k$ was decreased by at least one.} or certifies that no further order reduction can be achieved.

Let us then denote the {\em minimal order} of $\M A(x,\eps)$ at $x=x_k$ as:
\begin{equation}
\label{eq:muk}
  \mu_k(\M A) = \min m_k(\M A'), \text{ for } \forall \; \M T.
\end{equation}

If $\mu_k(\M A) < m_k(\M A)$ we say that the matrix $\M A(x,\eps)$ is {\em Moser-reducible} at $x=x_k$.

With this in mind we can classify a pole $x=x_k$ of $\M A(x,\eps)$ as:
\begin{itemize}
  \item {\em apparent singularity}, if $m_k(\M A) > 0$ and $\mu_k(\M A) = 0$;
  \item {\em regular singularity}, if $0 < \mu_k(\M A) \le 1$;
  \item {\em irregular singularity}, if $\mu_k(\M A) > 1$.
\end{itemize}
The matrix $\M A(x,\eps)$ is called {\em Fuchsian} if it does not contain irregular singularities at any value of $x$ including $\infty$.

\subsection{Reduction to epsilon form}

In the previous section we have introduced the notation and key definitions related to the Fuchsian theory of ODEs.
Now we are ready to review the reduction method proposed by Lee in~\cite{Lee15}.
With its help we can construct a rational transformation $\M T(x,\eps)$ which converts a system of ordinary differential equations with rational coefficients given by the matrix $\M A(x,\eps)$ to an equivalent system given by the matrix $\M M(x,\eps)$ which is Fuchsian and has an \textit{epsilon form} (also called {\em canonical} in \cite{Henn13}), i.e., $\M M(x,\eps) = \eps\, \M S(x)$.
When the epsilon form $\M M(x,\eps)$ of the initial system $\M A(x,\eps)$ is found we can easily solve it as a Laurent series in $\eps$ and restore solutions for the initial system $\M A(x,\eps)$ --- which is our ultimate goal --- by solving a linear system of equations.

The whole method is performed in the following three steps:

\begin{enumerate}
    \item Given a matrix $\M A(x,\eps)$, find an equivalent system $\M A'(x,\eps)$ and a corresponding transformation $\M T(x,\eps)$, such that $\M A'(x,\eps)$ is Fuchsian. We call this step \textit{fuchsification}.
    \item Given a Fuchsian matrix $\M A(x,\eps)$ with eigenvalues of all its residues of the form $n+m\,\eps$, where $n$ is integer, find an equivalent system (along with the transformation) which is still Fuchsian, but with residue eigenvalues being all of the form $k\,\eps$. We call this step \textit{normalization}.
    \item Given a normalized matrix $\M A(x,\eps)$, find an equivalent matrix $\M A'(x)$ in epsilon form, i.e. such that $\M A'(x,\eps) = \eps \, \M S'(x)$. We call this step \textit{factorization}.
\end{enumerate}

\subsubsection{Fuchsification}
\label{sec:fuchs}

To \textit{fuchsify} a system~\eqref{eq:dj} means to find an equivalent Fuchsian system.
This, of course, is only possible if $\M A(x,\eps)$ has no irregular singularities, or in other words $\mu_k(\M A)\le1$ for all $k$.\footnote{
    We expect this to be often the case in practice, in particular for ODEs corresponding to Feynman integrals which are known to have only logarithmic singularities, hence be solutions of some Fuchsian ODEs.
}

In the case of a single ODE of order~$n$, the minimal Moser order can be computed explicitly from power counting analysis of its coefficients (see the generalization of Fuchs' theorem in~\cite{Mos59}).
This is not possible for ODE systems like~\eqref{eq:dj}.
Instead, we have a criterion for Moser-reducibility of the form:

\textbf{Theorem 1.}
{\em If $m_k(\M A) > 1$ then the system \eqref{eq:dj} is Moser-reducible at $x=x_k$ if and only if the polynomial}
\begin{equation}
\label{eq:red_cond}
    \Delta^{r_k} \det\left(\frac{\M A_{k0}}{\Delta} + \M A_{k1} - \lambda \,\M I\right),
\end{equation}
{\em vanishes identically in $\lambda$ at $x=x_k$, where $r_k=\rank(\M A_{k0})$ and $\Delta=x-x_k$ if $x_k\ne\infty$, or $\Delta=1/x$ if $x_k=\infty$.}

When this condition fails the singularity in $x=x_k$ is {\em irregular}.

In addition to this criterion we have a method for constructing a transformation that lowers the Moser order at $x_i$, provided that the system is Moser-reducible at that point (possibly at the expense of increasing the Poincar\'e rank $p_j$ at another point $x=x_j$ by one).
This is done by selecting a projector matrix $\M P$ equal to a sum of products of a particular subset of (generalized) eigenvectors of $\M A_{i0}$ and $\M A_{j0}$, and constructing a $\M P$-balance between $x_i$ and~$x_j$.

The reader can find the details of this construction in \cite{Lee15}, but it is important to note that even if the system is Moser-reducible at $x_i$, it is only sometimes possible to construct a transformation that lowers $m_i(\M A)$ without increasing Poincar\'e rank at $x_j$.
Sometimes the best we can do is to choose $x_j$ to be some arbitrary regular point, and use a transformation that decreases $m_i(\M A)$ at the expense of turning $x_j$ into a pole (with $p_j=0$), effectively introducing an apparent singularity where there was none before.\footnote{
    In practice these apparent singularities are not a major problem, since they are subsequently removed during the normalization step.
    Still, we try not to introduce them if possible in order to decrease the intermediate expression sizes and to increase the overall performance.
}

With this in mind, to reduce a system to Fuchsian form we need to combine the reducibility check with the Moser rank-lowering transformation in stepwise fashion, as follows:

\begin{enumerate}
    \item Select some point $x_k$ with $m_k(\M A) > 1$. If none exist, reduction is complete.
    \item Check if $\M A(x,\eps)$ is reducible at $x=x_k$. If not, fail.
    \item Find a transformation $\M T(x,\eps) = \mathcal{B}(\M P(\eps), x_k, x_j; x)$ that lowers $m_k(\M A)$.
    \item Apply $\M T(x,\eps)$ and repeat from Step 1.
\end{enumerate}

In \fuchsia, this process is implemented by function \code{fuchsify}; see Section~\ref{sec:usage_py} for its usage.

Finally, let us mention that a similar problem of reducing Poincar\'e ranks and Moser orders of rational matrices was actively studied by Barkatou and co-authors, e.g., see~\cite{BP99}.
They developed algorithms implementing their method~\cite{BP99} which is available in the standard \texttt{Maple} package \texttt{DEtools} as \code{moser\_reduce} and \code{super\_reduce} routines.

\subsubsection{Normalization}
\label{sec:norm}

To \textit{normalize} a Fuchsian system \eqref{eq:dj} with matrix residue eigenvalues of the form $n+m\,\eps$ (where $n$ is integer), implies to find an equivalent Fuchsian system with residue eigenvalues of the form $m\,\eps$.

Just like in the previous step, the normalizing transformations are found by stepwise application of balance transformations~\eqref{eq:bal}.
We refer the reader to~\cite[p.~11]{Lee15} for the description of how such balances are constructed, but we will note that this transformation is possible due to these two facts:
\begin{itemize}
    \item Given a properly selected projector matrix $\M P(\eps)$, the balance $\mathcal{B}(\M P(\eps), x_i, x_j; x)$ shifts one of the eigenvalues of $\M A_{i0}$ by $\pm1$, shifts one of the eigenvalues of $\M A_{j0}$ by $\mp1$, and does not change the Poincar\'e ranks at any point.
    \item Since the system is Fuchsian, the sum of all its matrix residues is zero, and thus, the sum of all residue eigenvalues is zero as well.
\end{itemize}
Combining these two facts, we perform the normalization by shifting the residue eigenvalues by $1$ at each step, until a state is reached where the integer parts of all the eigenvalues are zero.

In \fuchsia, the normalization step is implemented by the function \code{normalize}.
See Section~\ref{sec:usage_py} for its usage.

It may happen that after fuchsification we obtain a system for which the residue eigenvalues do not fit to the $n+m\,\eps$ form neatly.
In this case it is sometimes possible to rectify the problem by using some non-linear change of variables.
Unfortunately we do not have an automated solution for such cases, and users are expected to find transformations appropriate for their system manually.

\subsubsection{Factorization}
\label{sec:fact}
After the normalization we have obtained a matrix $\M A(x,\eps)$ with all residue eigenvalues of the form $m\,\eps$.
The final step is to \textit{factorize} it by finding an equivalent matrix which is by itself proportional to $\eps$, so $\M A'(x,\eps)=\eps\,\M S(x)$.

A transformation which is constant in $x$ is sufficient for this task.
Let $\M T(\eps)$ be such a transformation, then according to \eqref{eq:ta}, we have:
\begin{equation}
  \M A'(x,\eps) \equiv \eps\, \sum_i \frac{\M S_i}{x-x_i} = \sum_i \M T^{-1}(\eps) \frac{\M A_{i0}(\eps)}{x-x_i} \M T(\eps),
\end{equation}
or explicitly
\begin{equation}
\label{eq:seps}
  \M S_i = \M T^{-1}(\eps) \frac{\M A_{i0}(\eps)}{\eps} \M T(\eps).
\end{equation}
Since $\M S_i$ in \eqref{eq:seps} is the same no matter what values $\eps$ takes, we can say that:
\begin{equation}
  \M S_i = \M T^{-1}(\eps) \frac{\M A_{i0}(\eps)}{\eps} \M T(\eps) =
    \M T^{-1}(\mu) \frac{\M A_{i0}(\mu)}{\eps} \M T(\mu),
\end{equation}
from where we obtain a system of linear equations for $\M T(\eps,\mu) \equiv \M T(\eps) \, \M T^{-1}(\mu)$:
\begin{equation}
  \frac{\M A_{i0}(\eps)}{\eps} \M T(\eps,\mu) = \M T(\eps,\mu) \frac{\M A_{i0}(\mu)}{\mu}, \text{for all $i$.}
\end{equation}
Solving this system for $\M T(\eps,\mu)$ we can reconstruct the initial transformation as $\M T(\eps) = \M T(\eps,\mu_0)$, where $\mu_0$ can be chosen arbitrary as long as $\M T(\eps)$ will come out invertible.

In general, the solution for $\M T(\eps,\mu)$ can have multiple free variables aside from just $\mu$.
We choose to set all of them to random small integers, preferably zeros, which keeps the resulting matrix $\M S(\eps)$ simple.

In \fuchsia the factorization step is implemented as the \code{factorize} routine (again, see Section~\ref{sec:usage_py} for its usage).

\subsubsection{Block-triangular form}
\label{sec:blockreduce}

It often happens that a matrix which defines an ODEs is sparse, i.e. it has many zeros, and can be shuffled into block-triangular form with small blocks.
It is possible to exploit this fact to considerably speed up fuchsification and normalization.

Let us consider a block-triangular matrix of this form:
\begin{equation}
\label{eq:bdiag}
\M A(x,\eps)=
\left(
\begin{matrix}
  \M A^{(11)} & 0 & 0 & 0
\\
  \M A^{(21)} & \M A^{(22)} & 0 & 0
\\
  \vdots & \cdots & \ddots & 0
\\
  \M A^{(m1)} & \M A^{(m2)} & \cdots & \M A^{(mm)}
\end{matrix}
\right),
\end{equation}
where $\M A^{(ba)}(x,\eps)$ is a sub-matrix of size $n_b \times n_a$.

We start by reducing {\bf diagonal blocks} of this matrix, $\M A^{(ba)}(x,\eps)$, to epsilon form.
This can be done by treating each diagonal block as an independent matrix, and proceeding as described in the previous sections.
Since the characteristic polynomial of a block-triangular matrix is a product of characteristic polynomials of its diagonal blocks, i.e.,
\begin{equation}
  \det(\M A(x,\eps)-\lambda \M I) =
    \det(\M A^{(11)}(x,\eps) - \lambda\M I) \cdot \ldots \cdot
    \det(\M A^{(mm)}(x,\eps) - \lambda \M I),
\end{equation}
once we have normalized the diagonal blocks, the whole matrix becomes normalized as well (but not necessarily Fuchsian yet).

Next, we fuchsify {\bf off-diagonal blocks} given by rectangular matrices $\M A^{(ba)}(x,\eps)$, $b > a$.
To do this, let us look at the parts of \eqref{eq:dj} related to such a block:
\begin{equation}
  \begin{cases}
  \partial_x \V J^{(a)} =
    \M A^{(aa)}\,\V J^{(a)} + \ldots \\
  \partial_x \V J^{(b)} =
    \M A^{(ba)}\,\V J^{(a)} +
    \M A^{(bb)}\,\V J^{(b)} + \ldots
  \end{cases}
\end{equation}
If $\M A^{(ba)}(x,\eps)$ has a singularity of Poincar\'e rank $r>0$ at $x=x_k$, then to reduce $r$ we can apply this basis transformation:
\begin{equation}
  \label{eq:offdiagt}
  \V J^{(b)} = \V J'^{(b)} + \Delta^{-r} \M D\, \V J^{(a)},
\end{equation}
where $\M D$ is some constant matrix, and $\Delta=x-x_k$ if $x_k\ne\infty$, or $\Delta=1/x$ if $x_k=\infty$.
This transformation changes $\M A^{(ba)}_{k0}(\eps)$ into
\begin{equation}
  \M A'^{(ba)}_{k0}(\eps) = \M A^{(ba)}_{k0}\!(\eps) + r\,\M D + \M A^{(bb)}_{k0}\!(\eps) \, \M D - \M D\, \M A^{(aa)}_{k0}(\eps)
\end{equation}

If both $\M A^{(aa)}_{k0}(\eps)$ and $\M A^{(bb)}_{k0}(\eps)$ have been factorized then it is always possible to solve the right-hand side of this equation for $\M D$, thus reducing the Poincar\'e rank of $\M A'^{(ba)}$ by one.
Moreover, this transformation only affects $\M A^{(bi)}$ for $i \le a$ and $\M A^{(ia)}$ for $i > b$, therefore if we will sequentially apply the transformation \eqref{eq:offdiagt} for each off-diagonal block, starting from the first row to the last, and from the last column to the first, we will obtain a fully Fuchsian (and still normalized) matrix.

Finally, we factorize the whole matrix as described in Section~\ref{sec:fact}, thus completing the transformation to epsilon form.

In \fuchsia the process of shuffling a matrix to its shortest lower block-diagonal form is performed by the \code{block\_triangular\_form} routine; fuchsification and normalization of diagonal blocks is done by the \code{reduce\_diagonal\_blocks}; fuchsification of the remaining off-diagonal blocks is done by the \code{fuchsify\_off\_diagonal\_blocks}.

\section{Using \fuchsia}
\label{sec:3}

\subsection{Installation}

To run \fuchsia one needs \sage~\cite{sagemath} version 7.0 or higher to be installed on the computer.
This task can be accomplished by following installation instructions available at the website \url{http://www.sagemath.org}.
\footnote{
    Some \linux distributions have \sage available in their package repositories; we do not recommend using those.
    A number of \maxima releases contain bugs which \fuchsia is sensitive to, and so far the official \sage builds have avoided those releases (unlike some \linux distributions).
}

\sage is a free and open-source Computer Algebra System licensed under GPL.
It is written in \python~2.7 and combines together a number of existing open-source mathematical systems and libraries like \texttt{Maxima}, \texttt{Singular}, and others with the goal of providing the best free CAS.
In particular our code heavily relies on the interface to \maxima~\cite{maxima}.

Next, source file \code{fuchsia.py} should be downloaded from the website \url{https://github.com/gituliar/fuchsia} (additional materials like examples of reduced matrices and the up-to-date documentation is located there as well).

\vspace{10mm}

\subsection{Usage from the command line}

To run \fuchsia use the command\footnote{For brevity, we use a shortcut \code{fuchsia} which is equivalent to \code{sage -python fuchsia.py}.}
\begin{Verbatim}
    \prompt{$}{sage -python fuchsia.py <action> <options>}
\end{Verbatim}
where
\begin{itemize}
  \item \code{<action>} is one of the algorithms described in the previous section, i.e., \code{fuchsify}, \code{normalize}, \code{factorize}, or auxiliary action \code{transform}, which applies a user-defined transformation to the given matrix.
  \item \code{<options>} are action-dependent options described in the help message printed with the help of \code{fuchsia -h} command.
\end{itemize}

In the following we provide a complete help information printed by \code{fuchsia~-h}:
\begin{Verbatim}
Fuchsia v17.01.19
Authors: Oleksandr Gituliar, Vitaly Magerya

Usage:
    fuchsia [-hv] [--use-maple] [-f <fmt>] [-l <path>] [-P <path>]
            <command> <args>...

Commands:
    reduce [-x <name>] [-e <name>] [-m <path>] [-t <path>] <matrix>
        find an epsilon form of the given matrix

    fuchsify [-x <name>] [-m <path>] [-t <path>] <matrix>
        find a transformation that will transform a given matrix
        into Fuchsian form

    normalize [-x <name>] [-e <name>] [-m <path>] [-t <path>] <matrix>
        find a transformation that will transform a given Fuchsian
        matrix into normalized form

    factorize [-x <name>] [-e <name>] [-m <path>] [-t <path>] <matrix>
        find a transformation that will make a given normalized
        matrix proportional to the infinitesimal parameter

    sort [-m <path>] [-t <path>] <matrix>
        find a block-triangular form of the given matrix

    transform [-x <name>] [-m <path>] <matrix> <transform>
        transform a given matrix using a given transformation

    changevar [-x <name>] [-y <name>] [-m <path>] <matrix> <expr>
        transform a given matrix by susbtituting free variable
        by a given expression

Options:
    -h          show this help message
    -f <fmt>    matrix file format: mtx or m (default: m)
    -l <path>   write log to this file
    -v          produce a more verbose log
    -P <path>   save profile report into this file
    -x <name>   use this name for the free variable (default: x)
    -y <name>   use this name for the new free variable (default: y)
    -e <name>   use this name for the infinitesimal parameter (default: eps)
    -m <path>   save the resulting matrix into this file
    -t <path>   save the resulting transformation into this file
    --use-maple speed up calculations by using Maple when possible

Arguments:
    <matrix>    read the input matrix from this file
    <transform> read the transformation matrix from this file
    <expr>      arbitrary expression
\end{Verbatim}

Simple and more advanced results obtained with the help of \fuchsia are located in the directory \code{examples}.
There you will find many examples of original matrices together with generated transformations which lead to the epsilon form of corresponding matrices.
Another example of applying \fuchsia to find master integrals for next-to-leading order contributions to splitting functions in QCD were discussed in \cite{GM16}.

\subsection{Usage from \sage or \python}
\label{sec:usage_py}

You can also use \fuchsia as a library by starting the \sage prompt and importing the \texttt{fuchsia} module like this:

\begin{Verbatim}
    \prompt{$}{sage}
    ┌────────────────────────────────────────────────────────────────────┐
    │ SageMath Version 7.1, Release Date: 2016-03-20                     │
    │ Type "notebook()" for the browser-based notebook interface.        │
    │ Type "help()" for help.                                            │
    └────────────────────────────────────────────────────────────────────┘
    \prompt{sage:}{from fuchsia import *}
\end{Verbatim}

In order to give an example for the API, let us try to reduce a simple matrix.
For the list of functions available after import, please, read the next section.

\begin{Verbatim}
    \prompt{sage:}{x, eps = var("x eps")}
    \prompt{sage:}{M = matrix([}
    \prompt{....:}{  [(2-eps)/x, 0, 0],}
    \prompt{....:}{  [x/(x-1), eps/x, 0],}
    \prompt{....:}{  [(1+2*eps)/x**3, 0, (1+eps)/x/(x+1)]}
    \prompt{....:}{])}
\end{Verbatim}

First, let us see where the singularities of this matrix are located:

\begin{Verbatim}[commandchars=\\!|]
    \prompt!sage:|!singularities(M, x)|
    {-1: 0, 0: 2, 1: 0, +Infinity: 1}
\end{Verbatim}

So, 4 singularities in total, with the Poincar\'e rank being 2 at $\code{x}=0$, 1 at $\code{x}=\infty$ and 0 everywhere else.
To get rid of non-zero ranks (thus transforming the system into Fuchsian form) we will need to \textit{fuchsify} this matrix as:

\begin{Verbatim}[commandchars=\\!|]
    \prompt!sage:|!Mf, Tf = fuchsify(M, x)|
    \prompt!sage:|!Mf|
    [ -(eps - 2)/x           0                          0]
    [   -1/(x - 1)  (eps -1)/x                          0]
    [(2*eps + 1)/x           0  (eps + 2*x + 3)/(x^2 + x)]
    \prompt!sage:|!singularities(Mf, x)|
    {-1: 0, 0: 0, 1: 0, +Infinity: 0}
\end{Verbatim}

Now, let us take a look at the eigenvalues of \code{Mf} residues:

\begin{Verbatim}
    \prompt{sage:}{[matrix_residue(Mf, x, x0).eigenvalues()}
    \prompt{....:}{  for x0 in [-1, 0, 1, Infinity]]}
    [[-eps - 1, 0, 0],
     [-eps + 2, eps - 1, eps + 3],
     [0, 0, 0],
     [-eps + 1, eps - 2, -2]]
\end{Verbatim}

Many of these eigenvalues are not equal to zero in the limit $\code{eps}\to0$, so \code{Mf} is not normalized.
It is, however, the case that all of the eigenvalues are of the form $n + m*\code{eps}$, so there is a chance that we will be able to normalize \code{Mf}.
Let us try:

\begin{Verbatim}
    \prompt{sage:}{Mn, Tn = normalize(Mf, x, eps)}
    \prompt{sage:}{Mn}
    [-eps/x                                                            ...
    [(4*eps^3 - 8*eps^2 - (4*eps^2 - 6*eps + 3)*x + 5*eps)/((4*eps^3 - ...
    [((2*eps + 1)*x + 3*eps + 1)/(x^2 + x)                             ...
    \prompt{sage:}{[matrix_residue(Mn, x, x0).eigenvalues()}
    \prompt{....:}{  for x0 in [-1, 0, 1, Infinity]]}
    [[-eps, 0, 0],
     [-eps, eps, eps],
     [0, 0, 0],
     [-eps, eps, 0]]
\end{Verbatim}

So, the matrix is normalized, but it grew quite a bit larger.
This happens.
Sometimes it is possible to simplify it a bit:

\begin{Verbatim}
    \prompt{sage:}{Ms, Ts = simplify_by_jordanification(Mn, x)}
    \prompt{sage:}{Ms}
    [               -eps/x      0              0]
    [            1/(x - 1)  eps/x              0]
    [1/2*(eps + 1)/(x + 1)      0  eps/(x^2 + x)]
\end{Verbatim}

That is much better.

Finally, we need to \textit{factorize} \code{Ms} to complete the reduction:

\begin{Verbatim}
    \prompt{sage:}{Mr, Tr = factorize(Ms, x, eps)}
    \prompt{sage:}{Mr}
    [         -eps/x      0              0]
    [1/4*eps/(x - 1)  eps/x              0]
    [5/8*eps/(x + 1)      0  eps/(x^2 + x)]
\end{Verbatim}

This is the fully transformed matrix.
As you can see, it is both proportional to \code{eps} and Fuchsian.
To make sure we got everything right, we can double-check the full transformation:

\begin{Verbatim}
    \prompt{sage:}{T = (Tf*Tn*Ts*Tr).simplify_rational()}
    \prompt{sage:}{(Mr - transform(M, x, T)).is_zero()}
    True
\end{Verbatim}

Note that we have used the construct \code{(A - B).is\_zero()} to compare matrices instead of the more obvious \code{bool(A == B)}.
This is a \sage idiosyncrasy; the more obvious way compares symbolic matrices only structurally.

Of course, you do not need to walk through all these steps yourself every time.
Normally, you just need to call this one function to do all the reduction work:

\begin{Verbatim}
    \prompt{sage:}{MM, TT = epsilon_form(M, x, eps)}
    \prompt{sage:}{MM}
    [                          -eps/x      0              0]
    [                 1/4*eps/(x - 1)  eps/x              0]
    [1/4*(9*eps*x + 13*eps)/(x^2 + x)      0  eps/(x^2 + x)]
    \prompt{sage:}{(MM - transform(M, x, TT)).is_zero()}
    True
\end{Verbatim}

Notice that this matrix is slightly more complex than the one we have obtained step by step above.
This also happens.
The final form we are computing is not unique, and it will be different depending on the precise sequence of reduction steps you have taken.

Additionally, many of the transformations take a special $seed$ parameter to control the order of operations they perform internally.
By supplying different seeds, you will obtain different results as well.

\subsubsection{Function reference}

\begin{description}[style=nextline]

\functionitem{epsilon\_form}{\M M, x, epsilon, seed=0}
Fully reduces a system of equations defined by a matrix $\M M$, an independent variable $x$, and an infinitesimal parameter $epsilon$.
Returns a pair of values: the transformed matrix $\M M'$ and the transformation matrix $\M T$.
Raises $FuchsiaError$, if the system is irreducible.

The reduction is performed by first converting $\M M$ to block-triangular form, then reducing the diagonal blocks via $\F{fuchsify}$, $\F{normalize}$ and $\F{factorize}$, reducing off-diagonal blocks as described in Section~\ref{sec:blockreduce}, and finally factorizing $epsilon$ via $\F{factorize}$.

\functionitem{fuchsify}{\M M, x, seed=0}
Reduces a system defined by a matrix $\M M$ and an independent variable $x$ to Fuchsian form.
That is, it makes sure that the Poincar\'e ranks of all singularities of the transformed matrix $\M M'$ are $0$.
Returns a pair of values: the transformed matrix $\M M'$ and the transformation $\M T$.
If the system is irreducible, it raises $FuchsiaError$.

\functionitem{normalize}{\M M, x, epsilon, seed=0}
Transforms a Fuchsian system defined by a matrix $\M M$, an independent variable $x$ and, an infinitesimal parameter $epsilon$ to a normalized form.
That is, it makes sure that real parts of the eigenvalues of all matrix residues of the transformed matrix $\M M'$ lie in the range $[-1/2, 1/2)$ in the limit $epsilon\to0$.
Returns a pair of values: the transformed matrix $\M M'$ and the transformation $\M T$.
If such a transformation can not be found, it raises $FuchsiaError$.

\functionitem{factorize}{\M M, x, epsilon, seed=0}
Transforms a normalized system defined by a matrix $\M M$, an independent variable $x$, and an infinitesimal parameter $epsilon$ so that the
transformed matrix $\M M'$ is proportional to $epsilon$.
Returns a pair of values: the transformed matrix $\M M'$ and the transformation $\M T$.
If such a transformation can not be found, it raises $FuchsiaError$.

\functionitem{block\_triangular\_form}{\M M}
Transforms a matrix $\M M$ into a lower block-triangular form.

Returns three values: a transformed matrix $\M M'$, a transformation matrix $\M T$, and a list of tuples $(m_i, n_i)$, where $n_i$ is the size of $i$-th diagonal block, and $m_i = \sum_{j=1}^{i-1} n_j$.
The tuple list represents block structure of $\M M'$; it is used by the next two functions, where it is passed as the argument $B$.

\functionitem{reduce\_diagonal\_blocks}{\M M, x, epsilon, B=None, seed=0}
Finds a transformation that reduces diagonal blocks of $\M M$ into epsilon form.
If $B$ is not provided, it transforms $\M M$ into lower triangual form before reduction.
Otherwise it assumes $\M M$ blocks are described by $B$.

Returns two values: a transformed matrix $\M M$ and a transformation matrix $\M T$.

\functionitem{fuchsify\_off\_diagonal\_blocks}{\M M, x, epsilon, r=None}
Given a matrix $M$ with diagonal blocks in epsilon form, it transforms off-diagonal blocks in to Fuchsian form.
If $B$ is not provided, it transforms $\M M$ into lower triangual form before reduction.
Otherwise it assumes that blocks of $\M M$ are described by $B$.

Returns two values: a transformed matrix $\M M$ and a transformation matrix $\M T$.

\functionitem{simplify\_by\_jordanification}{\M M, x}
Tries to simplify a system defined by a matrix $\M M$ and an independent variable $x$ by constant transformations that transform leading expansion coefficients of $\M M$ into their Jordan forms.
Returns a pair of values: the simplified matrix $\M M'$ and the transformation $\M T$.
If none of the attempted transformations reduces the complexity of $\M M$ (as measured by $\F{matrix\_complexity}$), it returns the original matrix and the identity transformation.

\functionitem{simplify\_by\_factorization}{\M M, x}
Tries to simplify a system defined by a matrix $\M M$ and an independent variable $x$ by a constant transformation that extracts common factors found in $\M M$ (if any).
Returns a pair of values: the simplified matrix $\M M'$ and the transformation $\M T$.

\functionitem{matrix\_complexity}{\M M}
This function is used as a measure of matrix complexity by $\F{fuchsify}$ and simplification functions.
Currently it is defined as the length of textual representation of matrix $\M M$.

\functionitem{balance}{\M P, x_1, x_2, x}
Returns a \textit{balance} transformation between points $x=x_1$ and $x=x_2$ using the projector matrix $\M P$.
See eq.~\eqref{eq:bal} for the definition of a \textit{balance}.

\functionitem{transform}{\M M, x, \M T}
Transforms a system defined by a matrix $\M M$ and an independent variable $x$ using the transformation matrix $\M T$ as specified by eq.~\eqref{eq:ta}.
Returns the transformed matrix $\M M'$.

\functionitem{balance\_transform}{\M M, \M P, x_1, x_2, x}
Same as $\F{transform}(\M M, x, \F{balance}(\M P, x_1, x_2, x))$, but implemented more efficiently: since the inverse of $\F{balance}(\M P, x_1, x_2, x)$ is $\F{balance}(\M P, x_2, x_1, x)$, this function can avoid a time-consuming matrix inversion operation that $\F{transform}$ must perform.

\functionitem{singularities}{\M M, x}
Finds values of $x$ around which the matrix $\M M$ has a singularity in $x$.
Returns a dictionary with $\{x_i: p_i\}$ entries, where $p_i$ is the Poincar\'e rank of $\M M$ at $x=x_i$.
The set of singular points can include \code{Infinity}, if $\M M$ has a singularity at $x\to\infty$.

\functionitem{matrix\_c0}{\M M, x, x_0, p}
Returns the 0-th coefficient of the series expansion of a matrix $\M M$ around $x=x_0$, assuming the Poincar\'e rank of $\M M$ at that point is $p$.
If $x_0$ is \code{Infinity}, it returns minus the coefficient at the highest power of $x$.
In other words, it returns $\M A_{k0}$ from eq.~\eqref{eq:axeps}.

\functionitem{matrix\_c1}{\M M, x, x_0, p}
Returns the 1-th coefficient of the series expansion of a matrix $\M M$ around $x=x_0$, assuming the Poincar\'e rank of $\M M$ at that point is $p$.
If $x_0$ is \code{Infinity}, it returns minus the coefficient at the second-to-highest power of $x$.
In other words, it returns $\M A_{k1}$ from eq.~\eqref{eq:axeps}.

\functionitem{matrix\_residue}{\M M, x, x_0}
Returns a residue of a matrix $\M M$ at $x=x_0$, assuming that the Poincar\'e rank of $\M M$ at $x=x_0$ is $0$.
Returns matrix residue at infinity if $x_0$ is \code{Infinity}.

This is the same as $\F{matrix\_c0}(\M M, x, x_0, 0)$.

\functionitem{export\_matrix\_to\_file}{filename, \M M, fmt=\code{"m"}}
Writes a matrix $\M M$ to a file $filename$ using MatrixMarket array format if $fmt$ is \code{"mtx"}, or Mathematica format if $fmt$ is \code{"m"} (which is the default).

\functionitem{import\_matrix\_from\_file}{filename}
Reads a symbolic matrix from a file $filename$.
Both Mathematica and MatrixMarket array formats are supported.
The exact format will be autodetected.

\functionitem{setup\_fuchsia}{verbosity=0, use\_maple=\code{False}}
Modifies some of the \fuchsia inner workings.
In particular, it sets $verbosity$ to $2$ to enable verbose logging, $1$ to enable normal logging, and $0$ to only log errors.

Set $use\_maple$ to \code{True} to enable usage of \texttt{Maple} to speed up calculations when possible; this may be particularly beneficial for big matrices, and for matrices with singularities at complex points.

\classitem{FuchsiaError}
This is the class of exceptions raised by the \fuchsia routines.
It indicates the inability to perform the requested reduction.

\end{description}

\section{Summary}
\label{sec:4}

In this paper we have presented \fuchsia, a program for reducing differential equations for Feynman master integrals to the epsilon form based on the Lee algorithm \cite{Lee15} which consists of three main computational steps: fuchsification, normalization, and factorization.
\fuchsia is open-source in its nature and depends on free software tools only: the programming language \python and the computer algebra system \maximasage, which makes it available for everyone.

Unfortunately in some cases \fuchsia may exhibit poor performance: complex and/or irrational coefficients (or singular point locations) are particularly known to lead to a slowdown (or a complete halt) due to difficulty of working with those numbers symbolically.
In many such cases switching from \maxima to \maple will help, speeding up the calculations and preventing resource exhaustion, hence the access to latter is desirable.
In other cases, even \maple is not powerful enough.

Despite such limitation \fuchsia shows great performance in many cases.
It is possible due to the optimization for block-triangular (or sparse) matrices, which allows to reduce relatively large matrices: the reduction of ${74\times74}$ matrix with 20 rational and complex singular points and at most $3\times3$ coupled blocks takes about an hour on a laptop with Intel i5 CPU.

\section*{Acknowledgment}

We are gratefully thankful for advanced examples of differential equations provided by Roman Lee and Costas Papadopolous.
We also appreciate useful suggestions from Sven Moch during writing of this paper.

This work has been supported by the Deutsche Forschungsgemeinschaft in Sonderforschungs\-be\-reich 676 {\it Particles, Strings, and the Early Universe} and by the Narodowe Centrum Nauki with the Sonata Bis grant DEC-2013/10/E/ST2/00656.

\bibliography{fuchsia}

\end{document}