From b24ab4dd075464010e75ec345f08e58ee885aefe Mon Sep 17 00:00:00 2001 From: Jhabriel Varela Date: Thu, 28 Dec 2023 16:04:44 -0300 Subject: [PATCH 1/4] ENH: Rewrite README --- README.md | 55 ++++++++++++++++--------------------------------------- 1 file changed, 16 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index ac3c2ca..02b6d6b 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,31 @@ -# [KRYSBAS](https://github.com/nidtec-una/krysbas-dev) -A repository for KRYlov Subspace-Based Adaptive Solvers for Sparse Linear Systems. Developed at the [Scientific Computing and Applied Mathematics](https://nidtec.pol.una.py/ccyma/) group at the [NIDTEC](https://nidtec.pol.una.py/) research center of the [Polytechnic Faculty, National University of Asunción, Paraguay](https://www.pol.una.py/). +# KrySBAS: Krylov Subspace-Based Adaptive Solvers -## **Table of Contents** -1. [Introduction](#introduction) - - [Krylov Subspace Methods](#krylov-subspace-methods) -2. [Generalized minimal residual method (GMRES)](#generalized-minimal-residual-method-gmres) -3. [The adaptive approach](#the-adaptive-approach) +KrySBAS is a free and open-source MATLAB toolbox containing a collection of adaptive solvers based on Krylov subspaces. -## **Introduction** -The main goal of this library is to propose control strategies for Krylov Subspace iterative methods, which is supported on new paradigms of computational architectures aiming at their stability, robustness and speed. Two types of algorithms will be considered: +The toolbox is developed by the [Scientific Computing and Applied Mathematics](https://nidtec.pol.una.py/ccyma/) group at the [NIDTEC](https://nidtec.pol.una.py/) research center of the [Polytechnic Faculty, National University of Asunción, Paraguay](https://www.pol.una.py/). -* those that present the best efficiency for defined positive symmetric systems, and -* those that present better efficiency for general systems, possibly indefinite and poorly conditioned. +## Installation -This repository is also intended to explore applications to real-world problems. +To install KrySBAS, simply clone this repository and add it to your MATLAB path. -### **Krylov Subspace Methods** -The $r$-th order [Krylov Subspace](https://en.wikipedia.org/wiki/Krylov_subspace) generated by a $n\times n$ matrix $A$ and a vector $b$ of dimension $n$ is the linear subspace spanned by matrix-vector multiplications between the powers of $A$ and the vector $b$. +## Solvers catalogue -```math -\mathcal{K}_r(A,b) = \text{span} \lbrace b, Ab, A^2b, \ldots, A^{r-1}b \rbrace -``` +### PD-GMRES(*m*) ([Núñez & Schaerer & Bhaya, 2018](https://www.sciencedirect.com/science/article/pii/S037704271830030X)) -## **Generalized minimal residual method (GMRES)** -The [GMRES(m)](https://en.wikipedia.org/wiki/Generalized_minimal_residual_method) (Saad) method approximates the solution to the linear system $Ax=b$ at the $j$-th restart cycle using the previous residual, $r_{j-1}=b-Ax_{j-1}$, by constructing a $m$th-order Krylov subspace. The $j$-th approximation is built as: +PD-GMRES(*m*) is a variant of the restarted GMRES that employs a Proportional-Derivative (PD) controller for the automatic selection of the restart parameter *m*. -```math -x_{j} = x_{j-1} + \mathcal{K}_{m} (A,r_{j-1}) +```Matlab +[x, flag, relresvec, mvec, time] = pd_gmres(A, b, mInitial, mMinMax, mStep, tol, maxit, xInitial, alphaPD) ``` -where the index $m$ denotes that the restarting parameter was set to the value $m$. GMRES($m$) obtains an approximate solution which minimizes the $2$-norm of the residual $r_j$, i.e., - -```math -\min_{x_{j}\in x_{j-1} + \mathcal{K}_{m} (A,r_{j-1})} \parallel b-Ax_{j} \parallel. $$ -``` -In practice: +## Contributing -* if $m$ is not appropriate, then GMRES($m$) stagnates (the residual norm reduces very slowly), -* important information about $\mathcal{K}_{m} (A,r_{j-1})$ is lost in the restarting process. +If you wish to contribute to KrySBAS, please read the [developer guide](https://github.com/nidtec-una/krysbas-dev/blob/dev_guide/dev_guide.md) before opening a pull request. -## **The adaptive approach** -In this repository, a combination of strategies improving the convergence of GMRES($m$) is presented. Some techniques are: +## Citing -1. **Adaptive controllers** : control-theory based, proportional-derivative controllers that modify the restarting parameter $m$ when stagnation is detected (Cuevas). - -```math -aqui va la formula PD rule? -``` +*TODO*: Add Zenodo reference. -2. **Enriching the Krylov Subspace by switching techniques**: the Krylov search subspace is augmented by aggregating either error approximation vectors of the current subspace before restart (Baker) or Harmonic Ritz vectors (Morgan) in the case the previous ones do not help to improve the rate of convergence. The switching strategy has been studied in (Cabral). +## Feature requests and bug reports -## **References** -(add references here? Yes, please.) +For future requests and bug reports, please create an [issue](https://github.com/nidtec-una/krysbas-dev/issues). In the latter case, we kindly ask you to provide a MWE that reproduces the error. From 35e46412e60760d93979fa3d24212455942e8098 Mon Sep 17 00:00:00 2001 From: Jhabriel Varela Date: Thu, 28 Dec 2023 16:05:48 -0300 Subject: [PATCH 2/4] MAINT: Better description of pd_gmres --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 02b6d6b..ce38c02 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ To install KrySBAS, simply clone this repository and add it to your MATLAB path. ### PD-GMRES(*m*) ([Núñez & Schaerer & Bhaya, 2018](https://www.sciencedirect.com/science/article/pii/S037704271830030X)) -PD-GMRES(*m*) is a variant of the restarted GMRES that employs a Proportional-Derivative (PD) controller for the automatic selection of the restart parameter *m*. +Variant of the restarted GMRES that employs a Proportional-Derivative (PD) controller for the automatic selection of the restart parameter *m*. ```Matlab [x, flag, relresvec, mvec, time] = pd_gmres(A, b, mInitial, mMinMax, mStep, tol, maxit, xInitial, alphaPD) From 12a4f8ffcba6a04166584446549f8eb6db05ab8c Mon Sep 17 00:00:00 2001 From: Jhabriel Varela Date: Thu, 28 Dec 2023 16:10:00 -0300 Subject: [PATCH 3/4] ENH: Add badges --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index ce38c02..049007e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +[![MATLAB tests](https://github.com/nidtec-una/krysbas-dev/actions/workflows/matlab_tests.yaml/badge.svg)](https://github.com/nidtec-una/krysbas-dev/actions/workflows/matlab_tests.yaml) +[![code_style](https://github.com/nidtec-una/krysbas-dev/actions/workflows/code_style.yml/badge.svg)](https://github.com/nidtec-una/krysbas-dev/actions/workflows/code_style.yml) +[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) + # KrySBAS: Krylov Subspace-Based Adaptive Solvers KrySBAS is a free and open-source MATLAB toolbox containing a collection of adaptive solvers based on Krylov subspaces. From 47333153be7a876347095020a869c8236d9cb031 Mon Sep 17 00:00:00 2001 From: Jhabriel Varela Date: Thu, 28 Dec 2023 16:22:25 -0300 Subject: [PATCH 4/4] MAINT: Remove citing section --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 049007e..4af520a 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,6 @@ Variant of the restarted GMRES that employs a Proportional-Derivative (PD) contr If you wish to contribute to KrySBAS, please read the [developer guide](https://github.com/nidtec-una/krysbas-dev/blob/dev_guide/dev_guide.md) before opening a pull request. -## Citing - -*TODO*: Add Zenodo reference. - ## Feature requests and bug reports For future requests and bug reports, please create an [issue](https://github.com/nidtec-una/krysbas-dev/issues). In the latter case, we kindly ask you to provide a MWE that reproduces the error.