Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit f02c2e2

Browse files
committed
Merge branch 'master' of https://github.com/fortran-lang/stdlib into directory
2 parents 8012ac8 + a2fadac commit f02c2e2

39 files changed

+2275
-385
lines changed

‎doc/specs/stdlib_math.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,7 @@ Experimental
459459

460460
Elemenal function.
461461

462-
### Description
462+
#### Description
463463

464464
`rad2deg` converts phase angles from radians to degrees.
465465

‎doc/specs/stdlib_specialmatrices.md

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
---
2+
title: specialmatrices
3+
---
4+
5+
# The `stdlib_specialmatrices` module
6+
7+
[TOC]
8+
9+
## Introduction
10+
11+
The `stdlib_specialmatrices` module provides derived types and specialized drivers for highly structured matrices often encountered in scientific computing as well as control and signal processing applications.
12+
These include:
13+
14+
- Tridiagonal matrices
15+
- Symmetric Tridiagonal matrices (not yet supported)
16+
- Circulant matrices (not yet supported)
17+
- Toeplitz matrices (not yet supported)
18+
- Hankel matrices (not yet supported)
19+
20+
In addition, it also provides a `Poisson2D` matrix type (not yet supported) corresponding to the sparse block tridiagonal matrix obtained from discretizing the Laplace operator on a 2D grid with the standard second-order accurate central finite-difference scheme.
21+
22+
## List of derived types for special matrices
23+
24+
Below is a list of the currently supported derived types corresponding to different special matrices.
25+
Note that this module is under active development and this list will eventually grow.
26+
27+
### Tridiagonal matrices {#Tridiagonal}
28+
29+
#### Status
30+
31+
Experimental
32+
33+
#### Description
34+
35+
Tridiagonal matrices are ubiquituous in scientific computing and often appear when discretizing 1D differential operators.
36+
A generic tridiagonal matrix has the following structure:
37+
$$
38+
A
39+
=
40+
\begin{bmatrix}
41+
a_1 & b_1 \\
42+
c_1 & a_2 & b_2 \\
43+
& \ddots & \ddots & \ddots \\
44+
& & c_{n-2} & a_{n-1} & b_{n-1} \\
45+
& & & c_{n-1} & a_n
46+
\end{bmatrix}.
47+
$$
48+
Hence, only one vector of size `n` and two of size `n-1` need to be stored to fully represent the matrix.
49+
This particular structure also lends itself to specialized implementations for many linear algebra tasks.
50+
Interfaces to the most common ones will soon be provided by `stdlib_specialmatrices`.
51+
Tridiagonal matrices are available with all supported data types as `tridiagonal_<kind>_type`, for example:
52+
53+
- `tridiagonal_sp_type` : Tridiagonal matrix of size `n` with `real`/`single precision` data.
54+
- `tridiagonal_dp_type` : Tridiagonal matrix of size `n` with `real`/`double precision` data.
55+
- `tridiagonal_xdp_type` : Tridiagonal matrix of size `n` with `real`/`extended precision` data.
56+
- `tridiagonal_qp_type` : Tridiagonal matrix of size `n` with `real`/`quadruple precision` data.
57+
- `tridiagonal_csp_type` : Tridiagonal matrix of size `n` with `complex`/`single precision` data.
58+
- `tridiagonal_cdp_type` : Tridiagonal matrix of size `n` with `complex`/`double precision` data.
59+
- `tridiagonal_cxdp_type` : Tridiagonal matrix of size `n` with `complex`/`extended precision` data.
60+
- `tridiagonal_cqp_type` : Tridiagonal matrix of size `n` with `complex`/`quadruple precision` data.
61+
62+
63+
#### Syntax
64+
65+
- To construct a tridiagonal matrix from already allocated arrays `dl` (lower diagonal, size `n-1`), `dv` (main diagonal, size `n`) and `du` (upper diagonal, size `n-1`):
66+
67+
`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du)`
68+
69+
- To construct a tridiagonal matrix of size `n x n` with constant diagonal elements `dl`, `dv`, and `du`:
70+
71+
`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du, n)`
72+
73+
#### Example
74+
75+
```fortran
76+
{!example/specialmatrices/example_tridiagonal_dp_type.f90!}
77+
```
78+
79+
## Specialized drivers for linear algebra tasks
80+
81+
Below is a list of all the specialized drivers for linear algebra tasks currently provided by the `stdlib_specialmatrices` module.
82+
83+
### Matrix-vector products with `spmv` {#spmv}
84+
85+
#### Status
86+
87+
Experimental
88+
89+
#### Description
90+
91+
With the exception of `extended precision` and `quadruple precision`, all the types provided by `stdlib_specialmatrices` benefit from specialized kernels for matrix-vector products accessible via the common `spmv` interface.
92+
93+
- For `tridiagonal` matrices, the LAPACK `lagtm` backend is being used.
94+
95+
#### Syntax
96+
97+
`call ` [[stdlib_specialmatrices(module):spmv(interface)]] `(A, x, y [, alpha, beta, op])`
98+
99+
#### Arguments
100+
101+
- `A` : Shall be a matrix of one of the types provided by `stdlib_specialmatrices`. It is an `intent(in)` argument.
102+
103+
- `x` : Shall be a rank-1 or rank-2 array with the same kind as `A`. It is an `intent(in)` argument.
104+
105+
- `y` : Shall be a rank-1 or rank-2 array with the same kind as `A`. It is an `intent(inout)` argument.
106+
107+
- `alpha` (optional) : Scalar value of the same type as `x`. It is an `intent(in)` argument. By default, `alpha = 1`.
108+
109+
- `beta` (optional) : Scalar value of the same type as `y`. It is an `intent(in)` argument. By default `beta = 0`.
110+
111+
- `op` (optional) : In-place operator identifier. Shall be a character(1) argument. It can have any of the following values: `N`: no transpose, `T`: transpose, `H`: hermitian or complex transpose.
112+
113+
@warning
114+
Due to limitations of the underlying `lapack` driver, currently `alpha` and `beta` can only take one of the values `[-1, 0, 1]` for `tridiagonal` and `symtridiagonal` matrices. See `lagtm` for more details.
115+
@endwarning
116+
117+
#### Examples
118+
119+
```fortran
120+
{!example/specialmatrices/example_specialmatrices_dp_spmv.f90!}
121+
```
122+
123+
## Utility functions
124+
125+
### `dense` : converting a special matrix to a standard Fortran array {#dense}
126+
127+
#### Status
128+
129+
Experimental
130+
131+
#### Description
132+
133+
Utility function to convert all the matrix types provided by `stdlib_specialmatrices` to a standard rank-2 array of the appropriate kind.
134+
135+
#### Syntax
136+
137+
`B = ` [[stdlib_specialmatrices(module):dense(interface)]] `(A)`
138+
139+
#### Arguments
140+
141+
- `A` : Shall be a matrix of one of the types provided by `stdlib_specialmatrices`. It is an `intent(in)` argument.
142+
143+
- `B` : Shall be a rank-2 allocatable array of the appropriate `real` or `complex` kind.
144+
145+
### `transpose` : Transposition of a special matrix {#transpose}
146+
147+
#### Status
148+
149+
Experimental
150+
151+
#### Description
152+
153+
Utility function returning the transpose of a special matrix. The returned matrix is of the same type and kind as the input one.
154+
155+
#### Syntax
156+
157+
`B = ` [[stdlib_specialmatrices(module):transpose(interface)]] `(A)`
158+
159+
#### Arguments
160+
161+
- `A` : Shall be a matrix of one of the types provided by `stdlib_specialmatrices`. It is an `intent(in)` argument.
162+
163+
- `B` : Shall be a matrix of one of the same type and kind as `A`.
164+
165+
### `hermitian` : Complex-conjugate transpose of a special matrix {#hermitian}
166+
167+
#### Status
168+
169+
Experimental
170+
171+
#### Description
172+
173+
Utility function returning the complex-conjugate transpose of a special matrix. The returned matrix is of the same type and kind as the input one. For real-valued matrices, `hermitian` is equivalent to `transpose`.
174+
175+
#### Syntax
176+
177+
`B = ` [[stdlib_specialmatrices(module):hermitian(interface)]] `(A)`
178+
179+
#### Arguments
180+
181+
- `A` : Shall be a matrix of one of the types provided by `stdlib_specialmatrices`. It is an `intent(in)` argument.
182+
183+
- `B` : Shall be a matrix of one of the same type and kind as `A`.
184+
185+
### Operator overloading (`+`, `-`, `*`) {#operators}
186+
187+
#### Status
188+
189+
Experimental
190+
191+
#### Description
192+
193+
The definition of all standard artihmetic operators have been overloaded to be applicable for the matrix types defined by `stdlib_specialmatrices`:
194+
195+
- Overloading the `+` operator for adding two matrices of the same type and kind.
196+
- Overloading the `-` operator for subtracting two matrices of the same type and kind.
197+
- Overloading the `*` for scalar-matrix multiplication.
198+
199+
#### Syntax
200+
201+
- Adding two matrices of the same type:
202+
203+
`C = A` [[stdlib_specialmatrices(module):operator(+)(interface)]] `B`
204+
205+
- Subtracting two matrices of the same type:
206+
207+
`C = A` [[stdlib_specialmatrices(module):operator(-)(interface)]] `B`
208+
209+
- Scalar multiplication
210+
211+
`B = alpha` [[stdlib_specialmatrices(module):operator(*)(interface)]] `A`
212+
213+
@note
214+
For addition (`+`) and subtraction (`-`), matrices `A`, `B` and `C` all need to be of the same type and kind. For scalar multiplication (`*`), `A` and `B` need to be of the same type and kind, while `alpha` is either `real` or `complex` (with the same kind again) depending on the type being used.
215+
@endnote

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /