diff --git a/README.md b/README.md index ac3c2ca..4af520a 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/). +[![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) -## **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: Krylov Subspace-Based Adaptive Solvers -## **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: +KrySBAS is a free and open-source MATLAB toolbox containing a collection of adaptive solvers based on Krylov subspaces. -* 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. +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/). -This repository is also intended to explore applications to real-world problems. +## Installation -### **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$. +To install KrySBAS, simply clone this repository and add it to your MATLAB path. -```math -\mathcal{K}_r(A,b) = \text{span} \lbrace b, Ab, A^2b, \ldots, A^{r-1}b \rbrace -``` - -## **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: +## Solvers catalogue -```math -x_{j} = x_{j-1} + \mathcal{K}_{m} (A,r_{j-1}) -``` +### PD-GMRES(*m*) ([Núñez & Schaerer & Bhaya, 2018](https://www.sciencedirect.com/science/article/pii/S037704271830030X)) -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., +Variant of the restarted GMRES that employs a Proportional-Derivative (PD) controller for the automatic selection of the restart parameter *m*. -```math -\min_{x_{j}\in x_{j-1} + \mathcal{K}_{m} (A,r_{j-1})} \parallel b-Ax_{j} \parallel. $$ +```Matlab +[x, flag, relresvec, mvec, time] = pd_gmres(A, b, mInitial, mMinMax, mStep, tol, maxit, xInitial, alphaPD) ``` -In practice: -* 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. +## Contributing -## **The adaptive approach** -In this repository, a combination of strategies improving the convergence of GMRES($m$) is presented. Some techniques are: - -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? -``` +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. -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.