Documentation pdf and TeX sources added

.gitignore

@@ -122,4 +122,9 @@ venv.bak/
 # mypy
 .mypy_cache/
 .dmypy.json
-dmypy.json
\ No newline at end of file
+dmypy.json
+
+#TeX rubbish
+*.log
+*.aux
+*.synctex.gz

documentation/description.tex

+ \section{Описание}
+
+Функция \texttt{supersvd} по двум заданным наборам пространственно--временных полей строит матрицу ковариации, а затем вычисляет её неполное сингулярное разложение. 
+
+Функция \texttt{supersvd} принимает на вход 2 обязательных аргумента (два поля, максимально скоррелированные моды которых мы ищем) и 2 опциональных параметра: количество пар максимально скоррелированных мод (по умолчанию 3) и значение переключателя режима вычитания из поля его среднего по времени значения (по умолчанию \texttt{True}, то есть из поля \textit{вычитается} его среднее по времени значение).
+
+Пусть $X(t), Y(t)$  --- два меняющихся во времени поля, максимально скоррелированные моды которых мы ищем, причём $\operatorname{dim}(X)=nT \times nX$\footnote{Здесь и далее размерности массивов указаны в порядке, принятом в \texttt{C} и \texttt{Python}. В \texttt{Fortran} размерности массивов следует развернуть в обратном порядке} и $\operatorname{dim}(Y)\hm=nT \times nY$, где $nX$ и $nY$ могут быть одним или несколькими измерениями массивов (в случае среднемесячных данных INMCM $nX$ и $nY$ --- $120 \times 180$). 
+Функция \texttt{supersvd} вычисляет разложение вида:
+\begin{equation}
+\begin{aligned}
+X(t) &= \overline{X} + XV_1 XC_1(t) + XV_2 XC_2(t) + \ldots + XV_k XC_k(t) + \ldots,\\
+Y(t) &= \overline{Y} + YV_1 YC_1(t) + YV_2 YC_2(t) + \ldots + YV_k YC_k(t) + \ldots,
+\end{aligned}
+\label{eq:svd}
+\end{equation}
+где 
+\begin{equation*}
+\overline{X}=\frac{1}{nT}\sum_{t=1}^{nT} X(t),\qquad
+\overline{Y}=\frac{1}{nT}\sum_{t=1}^{nT} Y(t),
+\end{equation*}
+а $k$ --- количество пар максимально скоррелированных мод. В \eqref{eq:svd} каждое новое слагаемое получается максимизацией корреляции между $XC_k(t)$ и $YC_k(t)$, а
+$XV_k, YV_k$~--- два семейства ортогональных пространственных мод.
+
+Моды $XV_k, YV_k$ являются левыми и правыми сингулярными векторами матрицы ковариации $$C =\frac{1}{nT} \sum_{t=1}^{nT} (X(t) - \overline{X}) (Y(t) - \overline{Y})^{\mathsf T}.$$
+
+Функция \texttt{supersvd} возвращает: 
+\begin{itemize}
+	\item массивы \texttt{x\_coeff}, \texttt{y\_coeff}  временных коэффициентов $XC(t), YC(t)$ разложения \eqref{eq:svd} \big(раз\-мерности $k \times nT$\big);
+	\item массив \texttt{x\_vect}  левых сингулярных векторов $XV$ \big(размерности $k \times nX$\big);
+	\item массив \texttt{y\_vect} правых сингулярных векторов $YV$ \big(размерности $k \times nY$\big);
+	\item массив \texttt{corrcoeff}, содержащий $k$ коэффициентов корреляции между $XC_k(t)$ и  $YC_k(t)$;
+	\item массив \texttt{x\_variance\_fraction} (\texttt{y\_variance\_fraction}), содержащий доли дисперсии, приходящиеся на каждый из $k$ левых (правых) сингулярных векторов;
+	\item массив \texttt{eigenvalue\_fraction}, содержащий долю дисперсии матрицы ковариации, приходящуюся на $k$-ую пару сингулярных векторов;
+	\item массив \texttt{eigenvalues} сингулярных значений матрицы ковариации $C$.   
+\end{itemize}

documentation/supersvd_doc.tex

+\documentclass[12pt, a4paper]{article}
+\usepackage[T2A]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage[russian]{babel}
+\usepackage[top=15mm,left=17.5mm, right=17.5mm, bottom=20mm]{geometry}
+\usepackage{amsmath}
+\usepackage{icomma}
+
+\newcommand*{\hm}[1]{#1\nobreak\discretionary{}%
+	{\hbox{$\mathsurround=0pt #1$}}{}}
+
+\title{\large Программа для вычисления максимально скоррелированных мод и ЭОФ}
+\author{Мария Тарасевич, \texttt{mashatarasevich@gmail.com}}
+\date{}
+
+\begin{document}
+\maketitle
+	
+	
+Написанная на языке \texttt{Python 3} программа состоит из двух файлов \texttt{main.py} и \texttt{supersvd.py}. В файле \texttt{supersvd.py} находится алгоритм вычисления максимально скоррелированных мод, а в \texttt{main.py} --- вспомогательный код, который анализирует ключи запуска программы, делает чтение входных данных из файлов, а также записывает в выходные файлы результаты работы алгоритма.
+
+Функцию \texttt{supersvd} можно напрямую использовать из кода на \texttt{Python}, в этом случае не обязательно сохранять массивы в виде файлов на диске. 
+ 
+\input{description}
+
+\input{usage}
+
+\end{document}

documentation/usage.tex

+\section{Использование}
+
+Функция \texttt{supersvd} может вызываться как и из другой \texttt{Python}-функции, принимая на вход массивы данных, так и из командной строки, принимая на вход бинарные файлы (\texttt{.STD}). Последняя возможность реализована в функции \texttt{main}.
+
+ Функция \texttt{main} принимает на вход 3 обязательных аргумента: 
+ \begin{itemize}
+ 	\item[\texttt{-x}] имя файла, содержащего первое из полей (например, \texttt{X.STD});
+ 	\item[\texttt{-y}] имя файла, содержащего второе из полей  (например, \texttt{Y.STD})\footnote{Если нужно посчитать ЭОФы, то в качестве первого и второго нужно задать одно и то же поле, то есть передать два раза имя одного файла.};
+ 	\item[\texttt{-t}, \texttt{-{}-time}] длину временного интервала (например, в случае среднемесячных данных исторического эксперимента с INMCM это 165 лет).
+ \end{itemize}
+ 
+ Также функция \texttt{main} принимает 7 необязательных (опциональных) параметров:
+ \begin{itemize}
+ 	\item[\texttt{-{}-type}] тип используемых данных --- \texttt{real} (4 байта) или \texttt{double} (8 байт), значение по умолчанию~--- \texttt{real};
+ 	\item[\texttt{-k}] количество вычисляемых пар максимально скоррелированных мод, значение по умолчанию --- 3;
+ 	\item[\texttt{-xv}] имя файла, в который запишется массив \texttt{x\_vect};
+ 	\item[\texttt{-yv}] имя файла, в который запишется массив \texttt{y\_vect};
+ 	\item[\texttt{-xc}] имя файла, в который запишется массив \texttt{x\_coeff};
+ 	\item[\texttt{-yc}] имя файла, в который запишется массив \texttt{y\_coeff};
+ 	\item[\texttt{-stat}] имя файла (предпочтительно в формате \texttt{.CSV}), в который для каждого $k$ запишутся домноженные на 100\% элементы массивов: \texttt{corrcoeff}, \texttt{x\_variance\_fraction}, \texttt{y\_vari\-ance\_fraction}, \texttt{eigenvalue\_fraction}. 
+ \end{itemize}  
+
+Функция \texttt{main} также может быть запущена с ключом \texttt{-{}-dont-subtract-mean}: при этом из полей $X$, $Y$ \textit{не будут вычитаться} их средние по времени значения.
+
+Итак, чтобы вычислить с помощью функции \texttt{main} 4 максимально скоррелированные моды аномалий температуры и давления (типа \texttt{float}) и сохранить все возможные результаты, достаточно в командной строке выполнить:\\
+\verb|python3 main.py -x ts.std -y ps.std -t 1147 -k 4 -xv tsv.std -yv psv.std|\\
+\verb|                 -xc tsc.std -yc psc.std -stat c.csv|
+
+Информацию, сохраняемую в файл \texttt{c.csv}, функция \texttt{main} также выводит на экран.
\ No newline at end of file