Add symmetric tridiagonal matrices module by Mahmood-Sinan · Pull Request #1091 · fortran-lang/stdlib

Mahmood-Sinan · 2026-01-21T06:15:21Z

This draft PR adds support for symmetric tridiagonal matrices inside specialmatrices in stdlib.
It includes implementation, tests, documentation and examples.
The PR implements the same arithmetic and matrix operations as the existing tridiagonal module.

Remaining tasks:

Add validation for the op argument in spmv, following PR Add validation for op argument in spmv routine for special matrices #1087
(this will be added here once that implementation is merged).

Feedback is welcome.

codecov · 2026-01-21T06:51:02Z

Codecov Report

❌ Patch coverage is 0% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.50%. Comparing base (843ffb0) to head (296c35a).
⚠️ Report is 11 commits behind head on master.

Files with missing lines	Patch %	Lines
...pecialmatrices/example_sym_tridiagonal_dp_type.f90	0.00%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1091      +/-   ##
==========================================
- Coverage   68.55%   68.50%   -0.06%     
==========================================
  Files         396      397       +1     
  Lines       12746    12753       +7     
  Branches     1376     1376              
==========================================
- Hits         8738     8736       -2     
- Misses       4008     4017       +9

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

loiseaujc · 2026-01-22T18:22:39Z

It looks pretty nice. One little thing though (even if I overlooked it when implementing the tridiagonal_type ) : you could define a single pure subroutine to construct the symtridiagonal matrices (make it two if you include the constant diagonal cases) and then have it called by the pure and impure constructors. It's a little thing but that would reduce a bit code duplication I guess.

I'll go through the code a bit more thoroughly tomorrow but it looks pretty good to me already.

…tants

Mahmood-Sinan · 2026-01-25T10:44:30Z

One little thing though (even if I overlooked it when implementing the tridiagonal_type ) : you could define a single pure subroutine to construct the symtridiagonal matrices (make it two if you include the constant diagonal cases) and then have it called by the pure and impure constructors. It's a little thing but that would reduce a bit code duplication I guess.

Thanks for the suggestion! You’re right, I implemented so. Now the tridiagonal and symtridiagonal construction is now handled by two pure helper routines(one from arrays and one from constants), which is called by both the pure and impure constructors.

…es directory

loiseaujc

I'll take a deeper look at it by the end of the week, but it looks quite good to me so far.

loiseaujc · 2026-01-27T16:51:38Z

src/specialmatrices/stdlib_specialmatrices.fypp

    implicit none
    private
-    public :: tridiagonal
+    public :: tridiagonal, sym_tridiagonal


It is mostly a question of personal tastes, but I prefer symtridiagonal over sym_tridiagonal. The no underscore naming is also the one used by Julia. What do you guys think @perazz, @jvdp1 and @jalvesz ?

Modulo this very style question, I think it's pretty much all good for me !

I also prefer symtridiagonal. However, the style guide says that "Variable and procedure names should be made up of one or more full words separated by an underscore,"

As @jvdp1 mentioned, if I remember correctly I chose sym_tridiagonal for the same reason

src/specialmatrices/stdlib_specialmatrices_sym_tridiagonal.fypp

loiseaujc

LGTM.

…rogram name

loiseaujc · 2026-02-12T09:06:41Z

@perazz, @jalvesz and @jvdp1 : This PR is ready for merging. The only question I have left is a triviality though. What convention should we use for naming types : sym_tridiagonal_dp_type or symtridiagonal_dp_type ? My preference goes to the first one personally.

Mahmood-Sinan · 2026-02-20T16:35:40Z

@perazz, @jalvesz and @jvdp1 : This PR is ready for merging. The only question I have left is a triviality though. What convention should we use for naming types : sym_tridiagonal_dp_type or symtridiagonal_dp_type ? My preference goes to the first one personally.

@perazz @jalvesz @jvdp1 Please look into this.

jvdp1

Thank you @Mahmood-Sinan for this PR. Please find below some comments and suggestions.

jvdp1 · 2026-02-20T16:38:59Z

doc/specs/stdlib_specialmatrices.md

+    \end{bmatrix}.
+$$
+Hence, only one vector of size `n` and one vector of size `n-1` need to be stored to fully represent the matrix.
+Interfaces to the most common ones will soon be provided by `stdlib_specialmatrices`.


What do you mean be "soon"? Is it not what is proposed in this PR?

Thank you for noticing. I have missed out a sentence before this which was common for both tridiagonal and symmetric tridiagonal. I added that sentence now. The interfances that this sentence talks about were solve, inverse, etc...

jvdp1 · 2026-02-20T16:39:57Z

doc/specs/stdlib_specialmatrices.md

+
+`A = ` [[stdlib_specialmatrices(module):sym_tridiagonal(interface)]] `(du, dv)`
+
+- To construct a symmetric tridiagonal matrix of size `n x n` with constant diagonal elements `du` and `dv`:


by "constant" do you mean "scalar"

Yes, I changed it so scalar now.

jvdp1 · 2026-02-20T16:40:39Z

doc/specs/stdlib_specialmatrices.md

+- To construct a symmetric tridiagonal matrix of size `n x n` with constant diagonal elements `du` and `dv`:
+
+`A = ` [[stdlib_specialmatrices(module):sym_tridiagonal(interface)]] `(du, dv, n)`
+


Please define (type, kind, intent, ...) the variables du, dv, n.

I have added them now under a new heading named arguments.

jvdp1 · 2026-02-20T16:41:35Z

example/specialmatrices/example_sym_tridiagonal_dp_type.f90

@@ -0,0 +1,17 @@
+program example_sym_tridiagonal_matrix
+   use stdlib_linalg_constants, only: dp
+   use stdlib_specialmatrices


Suggested change

use stdlib_specialmatrices

use stdlib_specialmatrices, only: sym_tridiagonal_dp_type, sym_tridiagonal

jvdp1 · 2026-02-20T16:44:31Z

src/specialmatrices/stdlib_specialmatrices.fypp

    implicit none
    private
-    public :: tridiagonal
+    public :: tridiagonal, sym_tridiagonal


I also prefer symtridiagonal. However, the style guide says that "Variable and procedure names should be made up of one or more full words separated by an underscore,"

jvdp1 · 2026-02-20T17:12:08Z

src/specialmatrices/stdlib_specialmatrices_sym_tridiagonal.fypp

+        ${t1}$, intent(in) :: alpha
+        type(sym_tridiagonal_${s1}$_type) :: B
+        B = sym_tridiagonal(A%du, A%dv)
+        B%du = alpha*B%du; B%dv = alpha*B%dv;


Suggested change

B%du = alpha*B%du; B%dv = alpha*B%dv;

B%du = alpha*B%du

B%dv = alpha*B%dv

and similarly at other places...

jvdp1 · 2026-02-20T17:13:33Z

test/linalg/test_linalg_specialmatrices.fypp

+            call random_number(du) ; call random_number(dv)
+            A = sym_tridiagonal(du, dv) ; Amat = dense(A)


Suggested change

call random_number(du) ; call random_number(dv)

A = sym_tridiagonal(du, dv) ; Amat = dense(A)

call random_number(du)

call random_number(dv)

A = sym_tridiagonal(du, dv)

Amat = dense(A)

jvdp1 · 2026-02-20T17:14:06Z

test/linalg/test_linalg_specialmatrices.fypp

+            allocate(x(n), source = 0.0_wp)   ; call random_number(x)
+            allocate(y1(n), source = 0.0_wp)  ; allocate(y2(n), source=0.0_wp)


Suggested change

allocate(x(n), source = 0.0_wp) ; call random_number(x)

allocate(y1(n), source = 0.0_wp) ; allocate(y2(n), source=0.0_wp)

allocate(x(n))

call random_number(x)

allocate(y1(n), source = 0.0_wp)

allocate(y2(n), source=0.0_wp)

jvdp1 · 2026-02-20T17:14:19Z

test/linalg/test_linalg_specialmatrices.fypp

+            allocate(y1(n), source = 0.0_wp)  ; allocate(y2(n), source=0.0_wp)
+
+            ! Test y = A @ x
+            y1 = matmul(Amat, x) ; call spmv(A, x, y2)


Suggested change

y1 = matmul(Amat, x) ; call spmv(A, x, y2)

y1 = matmul(Amat, x)

call spmv(A, x, y2)

jvdp1 · 2026-02-20T17:16:18Z

test/linalg/test_linalg_specialmatrices.fypp

+
+            ! Test y = A @ x
+            y1 = matmul(Amat, x) ; call spmv(A, x, y2)
+            call check(error, all_close(y1, y2), .true.)


Add a comment in each check to facilitate the debugging, in case a test is failing (currently it won't be easy to trace back which one is failing)

Mahmood-Sinan · 2026-02-21T08:55:19Z

Thank you @Mahmood-Sinan for this PR. Please find below some comments and suggestions.

Thank you so much for reviewing. I have made those changes. Please take a look at them.

Mahmood-Sinan · 2026-02-26T17:41:53Z

@jvdp1 Please handle.

Mahmood-Sinan added 4 commits January 21, 2026 10:50

added function definitions

492c378

added function implementations and examples

ce3f60f

added tests for sym_tridiag and renamed the test suite name

624bdfa

docs: add symmetric tridiagonal matrices and cdp example

af1df17

add build functions for construction of matrices from arrays and cons…

eecc723

…tants

Mahmood-Sinan added 3 commits January 25, 2026 20:05

merge

bf53d95

merged the latest stdlib and moved sym_tridiagonal into specialmatric…

ab6b3d1

…es directory

move build constructors under interfaces

f692605

loiseaujc reviewed Jan 27, 2026

View reviewed changes

Mahmood-Sinan added 3 commits January 28, 2026 14:26

remove if condition for linalg_error_handling inside constructors

97464f4

modify the fypp logic inside spmv for rank based preprocessing

a17f62c

Merge remote-tracking branch 'upstream/master' into symtridiag

6e4291b

loiseaujc marked this pull request as ready for review February 5, 2026 09:52

loiseaujc approved these changes Feb 5, 2026

View reviewed changes

Mahmood-Sinan added 2 commits February 6, 2026 14:50

Merge remote-tracking branch 'upstream/master' into symtridiag

173283c

add: spmv error check for operator for sym tridiag, modify: example p…

fc95858

…rogram name

loiseaujc approved these changes Feb 9, 2026

View reviewed changes

jvdp1 reviewed Feb 20, 2026

View reviewed changes

Mahmood-Sinan added 7 commits February 20, 2026 23:21

Merge remote-tracking branch 'upstream/master' into symtridiag

70796c9

update: docs to add arguments and missing sentence

867cf4e

modify: example and src

7054d66

modify: add new lines between inline assignments

3dff7c4

add: new lines in test

5081221

add debug statements in test

2121952

change constant to scalar inside comments

154f312

Mahmood-Sinan added 3 commits February 21, 2026 11:54

modify: if(present()) to optval inside spmv

3dc8641

change: constant to scalar inside docs

dd191d7

modify: docs to add err argument

296c35a


		`A = ` [[stdlib_specialmatrices(module):sym_tridiagonal(interface)]] `(du, dv)`

		- To construct a symmetric tridiagonal matrix of size `n x n` with constant diagonal elements `du` and `dv`:

	use stdlib_specialmatrices
	use stdlib_specialmatrices, only: sym_tridiagonal_dp_type, sym_tridiagonal

	B%du = alphaB%du; B%dv = alphaB%dv;
	B%du = alpha*B%du
	B%dv = alpha*B%dv

		call random_number(du) ; call random_number(dv)
		A = sym_tridiagonal(du, dv) ; Amat = dense(A)

		allocate(x(n), source = 0.0_wp) ; call random_number(x)
		allocate(y1(n), source = 0.0_wp) ; allocate(y2(n), source=0.0_wp)

	y1 = matmul(Amat, x) ; call spmv(A, x, y2)
	y1 = matmul(Amat, x)
	call spmv(A, x, y2)

Conversation

Mahmood-Sinan commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

loiseaujc commented Jan 22, 2026

Uh oh!

Mahmood-Sinan commented Jan 25, 2026

Uh oh!

loiseaujc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

loiseaujc left a comment

Choose a reason for hiding this comment

Uh oh!

loiseaujc commented Feb 12, 2026

Uh oh!

Mahmood-Sinan commented Feb 20, 2026

Uh oh!

jvdp1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mahmood-Sinan commented Feb 21, 2026

Uh oh!

Mahmood-Sinan commented Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Mahmood-Sinan commented Jan 21, 2026 •

edited

Loading

codecov bot commented Jan 21, 2026 •

edited

Loading