-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #126 from nekStab/update_docs
Update docs
- Loading branch information
Showing
19 changed files
with
128 additions
and
198 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,7 +15,7 @@ jobs: | |
| uses: actions/checkout@v3 | ||
|
|
||
| - name: Build Documentation | ||
| uses: ResearchSoftwareActions/[email protected] | ||
| uses: loiseaujc/[email protected] | ||
| id: build | ||
|
|
||
| - name: Deploy to GitHub Pages | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,153 +1,77 @@ | ||
| --- | ||
| project: LightKrylov | ||
| summary: Lightweight implementation of Krylov methods using modern Fortran. | ||
| author: Jean-Christophe Loiseau, Simon Kern, and Ricardo Frantz | ||
| media_dir: ./imgs | ||
| graph: false | ||
| license: bsd | ||
| project_github: https://github.com/nekStab/LightKrylov | ||
| src_dir: src | ||
| include: src | ||
| include | ||
| media_dir: imgs | ||
| exclude: src/TestUtils.f90 | ||
| src/Logger.f90 | ||
| display: public | ||
| protected | ||
| source: true | ||
| proc_internals: true | ||
| sort: permission-alpha | ||
| extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html | ||
| stdlib_io_npy:https://stdlib.fortran-lang.org/module/stdlib_io_npy.html | ||
| stdlib_linalg:https://stdlib.fortran-lang.org/module/stdlib_linalg.html | ||
| stdlib_math:https://stdlib.fortran-lang.org/module/stdlib_math.html | ||
| stdlib_optval:https://stdlib.fortran-lang.org/module/stdlib_optval.html | ||
| stdlib_sorting:https://stdlib.fortran-lang.org/module/stdlib_sorting.html | ||
| stdlib_stats:https://stdlib.fortran-lang.org/module/stdlib_stats.html | ||
| stdlib_stats_distribution_normal:https://stdlib.fortran-lang.org/module/stdlib_stats_distribution_normal.html | ||
| print_creation_date: true | ||
| project_github: https://github.com/nekStab/LightKrylov | ||
| project_website: https://nekstab.github.io/LightKrylov/ | ||
| project_download: https://github.com/nekStab/LightKrylov/archive/refs/tags/v0.1.0-beta.zip | ||
| doc_license: by-sa | ||
| license: bsd | ||
| author: nekstab/LightKrylov contributors | ||
| email: [email protected] | ||
| github: https://github.com/nekStab | ||
| twitter: https://x.com/loiseau_jc | ||
| css: ./bootstrap.min.css | ||
| --- | ||
|
|
||
| @note | ||
| This documentation still is work in progress. | ||
| @endnote | ||
|
|
||
| Targeting large-scale linear algebra applications where the matrix $\mathbf{A}$ is only defined implicitly (e.g. through a call to a `matvec` subroutine), this package provides lightweight Fortran implementations of the most useful Krylov methods to solve a variety of problems, among which: | ||
|
|
||
| 1. Eigenvalue Decomposition | ||
| $$\mathbf{A} \mathbf{x} = \lambda \mathbf{x}$$ | ||
|
|
||
| 2. Singular Value Decomposition | ||
| $$\mathbf{A} = \mathbf{U} \boldsymbol{\Sigma} \mathbf{V}^T$$ | ||
|
|
||
|
|
||
| 3. Linear system of equations | ||
| $$\mathbf{Ax} = \mathbf{b}$$ | ||
|
|
||
| Krylov methods are particularly appropriate in situations where such problems must be solved but factorizing the matrix $\mathbf{A}$ is not possible because: | ||
|
|
||
| - $\mathbf{A}$ is not available explicitly but only implicitly through a `matvec` subroutine computing the matrix-vector product $\mathbf{Ax}$. | ||
| - $\mathbf{A}$ or its factors (e.g. `LU` or `Cholesky`) are dense and would consume an excessive amount of memory. | ||
|
|
||
| Krylov methods are *iterative methods*, i.e. they iteratively refine the solution of the problem until a desired accuracy is reached. While they are not recommended when a machine-precision solution is needed, they can nonetheless provide highly accurate approximations of the solution after a relatively small number of iterations. Krylov methods form the workhorses of large-scale numerical linear algebra. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| `LightKrylov` leverages Fortran's `abstract type` feature to provide generic implementations of the various Krylov methods. | ||
| The only requirement from the user to benefit from the capabilities of `LightKrylov` is to extend the `abstract_vector` and `abstract_linop` types to define their notion of vectors and linear operators. `LightKrylov` then provides the following functionalities: | ||
|
|
||
| - Krylov factorizations : `arnoldi`, `lanczos_tridiagonalization`, `lanczos_bidiagonalization`. | ||
| - Spectral analysis : `eigs`, `eighs`, `svds`. | ||
| - Linear systems : `gmres`, `cg`. | ||
|
|
||
| ### Examples | ||
|
|
||
| Some examples can be found in the `example` folder. These include: | ||
| - [Ginzburg-Landau]() : Serial computation of the leading eigenpairs of a complex-valued linear operator via time-stepping. | ||
| - [Laplace operator]() : Parallel computation of the leading eigenpairs of the Laplace operator defined on the unit-square. | ||
|
|
||
| Alternatively, you can also look at [`neklab`](https://github.com/nekStab/neklab), a bifurcation and stability analysis toolbox based on `LightKrylov` and designed to augment the functionalities of the massively parallel spectral element solver [`Nek5000`](). | ||
|
|
||
| | [**Ginzburg-Landau**]() | [**Laplace operator**]() | | ||
| | :---------------------: | :----------------------: | | ||
| | ADD FIGURE | ADD FIGURE | | ||
|
|
||
| ## Installation | ||
|
|
||
| Provided you have `git` installed, getting the code is as simple as: | ||
|
|
||
| ``` | ||
| git clone https://github.com/nekStab/LightKrylov | ||
| ``` | ||
|
|
||
| Alternatively, using `gh-cli`, you can type | ||
|
|
||
| ``` | ||
| gh repo clone nekStab/LightKrylov | ||
| ``` | ||
|
|
||
| ### Dependencies | ||
|
|
||
| `LightKrylov` has a very minimal set of dependencies. These only include: | ||
|
|
||
| - a Fortran compiler, | ||
| - [`fpm`](https://github.com/fortran-lang/fpm) for building the code. | ||
|
|
||
| To date, the tested compilers include: | ||
|
|
||
| - `gfortran 12` (Linux) | ||
| - `gfortran 13` (Linux, Windows, MacOS) | ||
| - `ifort` (Linux) | ||
| - `ifx` (Linux) | ||
|
|
||
| ### Building with `fpm` | ||
|
|
||
| Provided you have cloned the repo, installing `LightKrylov` with `fpm` is as simple as | ||
|
|
||
| ``` | ||
| fpm build --profile release | ||
| ``` | ||
|
|
||
| To install it and make it accessible for other non-`fpm` related programs, simply run | ||
|
|
||
| ``` | ||
| fpm install --profile release | ||
| ``` | ||
|
|
||
| Both of these will make use of the standard compilation options set by the `fpm` team. Please refer to their documentation ([here](https://fpm.fortran-lang.org/)) for more details. | ||
|
|
||
| ### Running the tests | ||
|
|
||
| To see if the library has been compiled correctly, a set of unit tests are provided in [test](). Run the following command. | ||
|
|
||
| ``` | ||
| fpm test | ||
| ``` | ||
|
|
||
| If everything went fine, you should see | ||
|
|
||
| ``` | ||
| All tests successfully passed! | ||
| ``` | ||
|
|
||
| If not, please feel free to open an Issue. | ||
|
|
||
| ### Running the examples | ||
|
|
||
| To run the examples: | ||
|
|
||
| ``` | ||
| fpm run --example | ||
| ``` | ||
|
|
||
| This command will run all of the examples sequentially. You can alternatively run a specific example using e.g. | ||
|
|
||
| ``` | ||
| fpm run --example Ginzburg-Landau | ||
| ``` | ||
|
|
||
| For more details, please refer to each of the examples. | ||
|
|
||
| ## Contributing | ||
|
|
||
| ### Current developers | ||
|
|
||
| `LightKrylov` is currently developed and maintained by a team of three: | ||
| - [Jean-Christophe Loiseau](https://loiseaujc.github.io/) : Assistant Professor of Applied maths and Fluid dynamics at [DynFluid](https://dynfluid.ensam.eu/), Arts et Métiers Institute of Technology, Paris, France. | ||
| - [Ricardo Frantz](https://github.com/ricardofrantz) : PhD in Fluid dynamics (Arts et Métiers, France, 2022) and currently postdoctoral researcher at DynFluid. | ||
| - [Simon Kern](https://github.com/Simkern/) : PhD in Fluid dynamics (KTH, Sweden, 2023) and currently postdoctoral researcher at DynFluid. | ||
|
|
||
| Anyone else interested in contributing is obviously most welcomed! | ||
| @warning | ||
| This API documentation for the `LightKrylov` pacakge is a work in progress. | ||
| It is build from the source code in the `main` branch and does not track the current development in `dev` or any other branches. | ||
| If you use another branch, please refer to the in-code documentation. | ||
| Use the navigation bar at the top of the screen to browse `modules`, `procedures`, `source files`, etc. | ||
| The listings near the bootom of the page are incomplete. | ||
| @endwarning | ||
|
|
||
| This is the main API documentation landing page generated by [FORD](https://github.com/Fortran-FOSS-Programmers/ford#readme). This documentation is released under the [`CC-BY-SA`](https://creativecommons.org/licenses/by-sa/4.0/) license while the `LightKrylov` source code is distribution under the [`BSD-3 Clause`](https://opensource.org/license/bsd-3-clause) one. | ||
|
|
||
| ## Scope | ||
|
|
||
| The goal of `LightKrylov` is to provide a lightweight implementation of many standard Krylov techniques using modern `Fortran` features, including: | ||
|
|
||
| - Linear solvers for \( \mathbf{Ax} = \mathbf{b} \) | ||
| + [`cg`](https://en.wikipedia.org/wiki/Conjugate_gradient_method) when \( \mathbf{A} \) is a symmetric (hermitian) positive definite matrix. | ||
| + [`gmres`](https://en.wikipedia.org/wiki/Generalized_minimal_residual_method) when \( \mathbf{A} \) is a non-symmetric square linear operator. | ||
| - Krylov-based matrix factorizations | ||
| + `arnoldi` - Construct an upper Hessenberg matrix \( \mathbf{H} \) and an orthonormal (unitary) basis \( \mathbf{X} \) capturing the dominant eigenspace of a square non-symmetric matrix \( \mathbf{A} \) using the [`Arnoldi`](https://en.wikipedia.org/wiki/Arnoldi_iteration) iterative process. | ||
| + `lanczos` - Construct a symmetric (hermitian) tridiagonal matrix \( \mathbf{T} \) and an orthonormal (unitary) basis \( \mathbf{X} \) capturing the dominant eigenspace of a symmetric (hermitian) linear operator \( \mathbf{A} \) using the [`Lanczos`](https://en.wikipedia.org/wiki/Lanczos_algorithm) iterative process. | ||
| + `bidiagonalization` - Construct a bidiagonal matrix \( \mathbf{B} \) and orthonormal bases \( \mathbf{U} \) and \( \mathbf{V} \) for the dominant column (resp. row) span of a general linear operator \( \mathbf{A} \) using the [`Lanczos bidiagonalization`](https://en.wikipedia.org/wiki/Bidiagonalization) iterative process. | ||
| - Eigenvalue solvers for \( \mathbf{Ax} = \lambda \mathbf{x} \) | ||
| + `eigs` to compute the largest eigenvalues and associated eigenvectors of a general square linear operator \( \mathbf{A} \) using the [`Arnoldi`](https://en.wikipedia.org/wiki/Arnoldi_iteration) iterative process. | ||
| + `eighs` to compute the largest eigenvalues and associated eigenvectors of a symmetric (hermitian) linear operator \( \mathbf{A} \) using the [`Lanczos`](https://en.wikipedia.org/wiki/Lanczos_algorithm) iterative process. | ||
| - Singular value decomposition \( \mathbf{A} = \mathbf{U} \boldsymbol{\Sigma} \mathbf{V}^H \) | ||
| + `svds` to compute the leading singular triplets of a general linear operator \( \mathbf{A} \) using the [`Lanczos bidiagonalization`](https://en.wikipedia.org/wiki/Bidiagonalization) iterative process. | ||
| - Solving a system of nonlinear equations \( F(\mathbf{x}) = \mathbf{0} \) | ||
| + `newton` to find the solution to \( F(\mathbf{x}) = \mathbf{0} \) using a Newton-Krylov solver with optimal step size found by a simple bisection method. | ||
|
|
||
| While similar and more feature-complete packages exist (e.g. [Arpack](https://www.arpack.org), [SLEPC](https://slepc.upv.es/) or [Trilinos](https://trilinos.github.io/)), the use of `abstract_type` in `LightKrylov` and its nearly non-existant list of dependencies makes it far easier to incorporate into an existing code base. Preliminary benchmark results moreover show that it is on par with `Arpack` in terms of accuracy and computational performances. | ||
|
|
||
| ## Acknowledgment | ||
|
|
||
| The development of `LightKrylov` is part of an on-going research project funded by [Agence Nationale pour la Recherche](https://anr.fr/en/) (ANR) under the grant agreement ANR-22-CE46-0008. The project started in January 2023 and will run until December 2026. | ||
| We are also very grateful to the [fortran-lang](https://fortran-lang.org/) community and the maintainers of [`stdlib`](https://github.com/fortran-lang/stdlib). | ||
|
|
||
| ## Related projects | ||
|
|
||
| ### Related projects | ||
| `LightKrylov` is the base package of our ecosystem. If you like it, you may also be interested in: | ||
|
|
||
| `LightKrylov` is the base package of our ecosystem. If you like it, you may also be interested in : | ||
| - [`LightROM`](https://github.com/nekStab/LightROM) : a lightweight Fortran package providing a set of functions for reduced-order modeling, control and estimation of large-scale linear time invariant dynamical systems. | ||
| - [`neklab`]() : a bifurcation and stability analysis toolbox based on `LightKrylov` for the massively parallel spectral element solver [`Nek5000`](). | ||
| - [`neklab`](https://github.com/nekStab/neklab) : a bifurcation and stability analysis toolbox based on `LightKrylov` for the massively parallel spectral element solver [`Nek5000`](https://github.com/Nek5000/Nek5000). |
Oops, something went wrong.