From 6301b91b90e63d9b21c2d0a3655e528281384c49 Mon Sep 17 00:00:00 2001 From: Maria Tarasevich <mashatarasevich@gmail.com> Date: Tue, 1 Jun 2021 10:06:19 +0000 Subject: [PATCH] Add new file --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3a404fc --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# supersvd +Python tool to perform maximal covariance analysis and calculating empirical orthogonal functions + +Написанная на языке `Python 3` программа состоит из двух файлов: `main.py` и `supersvd.py`. +В файле `supersvd.py` находится алгоритм вычисления максимально скоррелированных мод, а в `main.py` — вспомогательный код, +который анализирует ключи запуска программы, делает чтение входных данных из файлов, а также записывает в выходные файлы результаты работы алгоритма. + +Функцию `supersvd` можно напрямую использовать из кода на `Python`, в этом случае не обязательно сохранять массивы в виде файлов на диске. + +## Описание + +Функция `supersvd` по двум заданным наборам пространственно–временных полей строит матрицу ковариации, а затем вычисляет её неполное сингулярное разложение. + +Функция `supersvd` принимает на вход 2 обязательных аргумента (два поля, максимально скоррелированные моды которых мы ищем) и 2 опциональных параметра: +количество пар максимально скоррелированных мод (по умолчанию 3) и значение переключателя режима вычитания из поля его среднего по времени значения +(по умолчанию `True`, то есть из поля _вычитается_ его среднее по времени значение). + +Пусть $`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} -- GitLab