Provide state/error handling for linear algebra #774

perazz · 2024-03-16T10:22:16Z

With this PR I aim to introduce a state/error handler for expert flow control of linear algebra procedures:

linalg_state derived type with all pure interfaces
fast, fixed-size memory storage
expert control: on error, stop the program. Otherwise, do not stop and return state handler if user requested it
developer friendly: easy to set error messages thanks to generic interface
add tests for all stdlib kinds

cc: @fortran-lang/stdlib @jvdp1 @everythingfunctional @henilp105 @jalvesz @gnikit

This and #772 are prelminary to begin adding lapack-backed high-level algebra APIs, more context here.

certik

I think we need a mechanism like this, thanks for creating it.

We just need to discuss the details of the implementation. I left some comments.

Another question to decide is whether this should be specialized to linear algebra, or made more general.

certik · 2024-03-25T13:55:36Z

src/stdlib_linalg_state.fypp

+
+    !> Error creation message, from N input variables (numeric or strings)
+    pure type(linalg_state) function new_state_nowhere(flag,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10, &
+                                               v1,v2,v3,v4,v5) result(new_state)


I am not sure about this.

Here's an example of how these functions allow easy coding of the error/state variable, for example for a complex number:

stdlib/test/linalg/test_linalg.fypp

Line 962 in c5c568b

state = linalg_state(LINALG_SUCCESS,' 32-bit array: ',v1=[(1.0_sp,0.0_sp),(0.0_sp,1.0_sp)])

And the expected user error message:

stdlib/test/linalg/test_linalg.fypp

Line 964 in c5c568b

' 32-bit array: [(1.00000000E+00,0.00000000E+00) (0.00000000E+00,1.00000000E+00)]', &

The real formats for 32/64/128 bit are taken from here:

stdlib/src/stdlib_io.fypp

Lines 28 to 46 in 8853ecd

character(*), parameter :: &

!> Format string for integers

FMT_INT = '(i0)', &

!> Format string for single precision real numbers

FMT_REAL_SP = '(es15.8e2)', &

!> Format string for souble precision real numbers

FMT_REAL_DP = '(es24.16e3)', &

!> Format string for extended double precision real numbers

FMT_REAL_XDP = '(es26.18e3)', &

!> Format string for quadruple precision real numbers

FMT_REAL_QP = '(es44.35e4)', &

!> Format string for single precision complex numbers

FMT_COMPLEX_SP = '(es15.8e2,1x,es15.8e2)', &

!> Format string for double precision complex numbers

FMT_COMPLEX_DP = '(es24.16e3,1x,es24.16e3)', &

!> Format string for extended double precision complex numbers

FMT_COMPLEX_XDP = '(es26.18e3,1x,es26.18e3)', &

!> Format string for quadruple precision complex numbers

FMT_COMPLEX_QP = '(es44.35e4,1x,es44.35e4)'

certik · 2024-03-25T13:55:50Z

src/stdlib_linalg_state.fypp

+       call appendv(new_state%message,v2)
+       call appendv(new_state%message,v3)
+       call appendv(new_state%message,v4)
+       call appendv(new_state%message,v5)


And this mechanism.

certik · 2024-03-25T13:58:23Z

src/stdlib_linalg_state.fypp

+    end function new_state_nowhere
+
+    ! Append a generic value to the error flag
+    pure subroutine append(msg,a,prefix)


Is this function appending a string representation of an integer, real or an array into the string message?

If so, I would keep it separate (the linalg library can append what it needs into the error message), not tie this into the implementation of the error state.

Exactly @certik, it covers all real, integer, complex kinds covered by stdlib (according to the preprocessing) and strings. I designed it this way so that error handling is easy to be read by the user but also easy to implement. See for example in my current solve implementation:

https://github.com/perazz/fortran-lapack/blob/869e12f0aff09e3520a828e11e90898591872d47/src/stdlib_linalg_solve.f90#L178-L189

I find it very easy to read - and no need to write formats for each possible error string. Also, there are at least 5-6 possible error messages out of each LAPACK routine, it could be a format nightmare down the road.

One option could be to move the numeric->string routines to stdlib_io?

Could you use the stdlib to_string?

Totally, although here I purposedly avoided allocatable components, because there is going to be one linalg_state_type variable in every function, and I wanted the compiler to be able to put it on the stack to minimize performance penalty. What do you think?

Is performance a real problem here? I mean, if it is at this stage, it means that there is an issue.
Anyway, I am ok with the code as it is now. I am just wondering what would be the impact performance-wise.

perazz · 2024-03-25T15:28:51Z

whether this should be specialized to linear algebra, or made more general.

Thanks a lot @certik for the review! We briefly touched this point during the last monthly call. It seems like the consensus was: let's try to use this error handling method for the linear algebra part first. If we see that we like it, don't find issues, etc., then it could be promoted to a global error handling paradigm for the whole stdlib. So far, there is really little/no error handling whatsoever, so we won't introduce breaking compatibility changes, as long as the contents of the linalg_state handler are agreed upon (i.e. state flag, message, and location):

stdlib/src/stdlib_linalg_state.fypp

Lines 49 to 56 in c5c568b

    
           !> The current exit state 
        
           integer(ilp) :: state = LINALG_SUCCESS 
        
           !> Message associated to the current state 
        
           character(len=MSG_LENGTH) :: message = repeat(' ',MSG_LENGTH) 
        
           !> Location of the state change 
        
           character(len=NAME_LENGTH) :: where_at = repeat(' ',NAME_LENGTH)

jvdp1

Thank you @perazz . Overall LGTM. Here are some suggestions.
It would be good to add some specs too.

src/stdlib_linalg_constants.fypp

src/stdlib_linalg_state.fypp

jvdp1 · 2024-03-25T14:24:30Z

src/stdlib_linalg_constants.fypp

+module stdlib_linalg_constants
+     use stdlib_kinds, only: sp, dp, qp, int32, int64, lk
+     use, intrinsic :: ieee_arithmetic, only: ieee_is_nan 
+!$   use omp_lib


Is omp_lib needed here?

Suggested change

!$ use omp_lib

Yes, it is used by the LAPACK functions. I put it in the constants module to avoid repeated use statements.

src/stdlib_linalg_constants.fypp

src/stdlib_linalg_state.fypp

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

address style changes

perazz · 2024-04-02T09:17:48Z

@certik @jvdp1 (@gnikit @jalvesz) do you have further comments that could help get this merged soon? Thanks @jvdp1's review, IMHO everything looks in line with stdlib's style now.

After we have error/state handling merged, we can begin adding several high-level APIs in parallel, so people will have time to look and comment and we can iterate on them efficiently.

gnikit

I just had a quick look. The majority of the contributions seem okay to me, but I feel I am missing something/misunderstanding the mechanism behind methods such as new_state_nowhere. I think I might need to spend some more time into this (probably not today) before I can leave a fully informed review. In the meantime, if others have the time to review please go ahead, don't wait for my comments.

perazz · 2024-04-02T12:53:47Z

the mechanism behind methods such as new_state_nowhere

2 state creation interfaces (with/without location info) use optional, rank-agnostic, unlimited polymorphic inputs for easy setup of the error messages, e.g.:

stdlib/example/linalg/example_state1.f90

Lines 7 to 8 in 41bf3a3

    
           err = linalg_state_type(LINALG_VALUE_ERROR,'just an example with scalar ',& 
        
                                   'integer=',1,'real=',2.0,'complex=',(3.0,1.0),'and array ',[1,2,3],'inputs')

no clogging of the high-level APIs with format statements
no over-head issues (the variables may be resolved at runtime, but it's not a problem as this will only happen when an error is occurred)
up to 20 input tokens per message are supported

jalvesz · 2024-04-02T17:19:27Z

I tried to give a look and had a bit of trouble to fully grasp the mechanism. Also because I usually use very simple error handling. So my 1 cent at this stage would be that maybe a more complete example, (a kind of micro-tutorial) showing how it can be used together with an interface built locally within the example could help?

perazz · 2024-04-05T06:19:57Z

@certik @gnikit @jalvesz do you have indications that would make you happy of the PR, complete the review and approve for merge? For example, remove the helper functions altoghether, then manually set each error message.

jalvesz · 2024-04-06T07:04:27Z

I was thinking, for the example, say that you were to use this error catching mechanism to implement an interface for matrix inversion and you would like to decide wether to stop or just throw a warning if the determinant is zero? How would you structure the program? a small example showing this could be enlightening :)

perazz · 2024-04-06T10:32:56Z

a small example showing this could be enlightening :)

Great idea @jalvesz, I added one more example, I hope shows it better (later when we start merging linear algebra functions, there will be plenty more):

stdlib/example/linalg/example_state2.f90

Lines 38 to 55 in 00db324

    
           if (b==0.0) then  
        
               ! Division by zero 
        
               err0 = linalg_state_type(this,LINALG_VALUE_ERROR,'Division by zero trying ',a,'/',b) 
        
           elseif (.not.abs(b)<MAXABS) then  
        
               ! B is out of bounds 
        
               err0 = linalg_state_type(this,LINALG_VALUE_ERROR,'B is infinity in a/b: ',[a,b]) ! use an array 
        
           elseif (.not.abs(a)<MAXABS) then  
        
               ! A is out of bounds 
        
               err0 = linalg_state_type(this,LINALG_VALUE_ERROR,'A is infinity in a/b: a=',a,' b=',b) 
        
           else 
        
               a_div_b = a/b 
        
               if (.not.abs(a_div_b)<MAXABS) then  
        
                   ! Result is out of bounds 
        
                   err0 = linalg_state_type(this,LINALG_VALUE_ERROR,'A/B is infinity in a/b: a=',a,' b=',b) 
        
               else 
        
                   err0%state = LINALG_SUCCESS 
        
               end if 
        
           end if

jalvesz · 2024-04-08T06:16:38Z

Thanks @perazz LGTM!!

jvdp1

LGTM. Thank you @perazz for this PR. I just have a few minor suggestions. Feel free to ignore them.

example/linalg/example_state1.f90

example/linalg/example_state2.f90

src/stdlib_linalg_state.fypp

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

perazz · 2024-04-08T12:18:51Z

Thanks for the reviews @jvdp1 @jalvesz: let's see if there are more comments. If I see that no outstanding issues in the next few days, I think it's good enough to merge.

jvdp1 · 2024-04-11T09:53:00Z

@perazz Should I generate a new release of stdlib (v0.5.0)?

perazz · 2024-04-11T10:14:06Z

Yes @jvdp1, what do you think? I believe it's a good idea because that sets the starting point for the linear algebra procedures. Another option would be to wait until some of them are also implemented, but that could also come with 0.5.1, or another minor tick.

jvdp1 · 2024-04-11T10:19:48Z

I think it would set the starting point of the integration of BLAS/LAPACK into stdlib. This will help users to test it and provide some feedbacks.
Additional APIs and related changes could be indeed part of revision of this version.
@gnikit what do you think?

gnikit · 2024-04-11T10:36:36Z

Yes, that sounds great @jvdp1! (If I am unresponsive here you can always reach me on Discourse).

perazz added 6 commits March 16, 2024 09:25

add linalg state handler

7ccdb49

cleanup, fyppize numeric types

6d6fb55

more cleanup

e7398a0

complex format: add brackets i.e. (0.0,1.0) instead of 0.0 1.0

31cb5eb

add linalg_state tests

4ef4fb0

remove multiple public statement

c5c568b

perazz marked this pull request as draft March 16, 2024 10:29

perazz marked this pull request as ready for review March 16, 2024 10:53

certik reviewed Mar 25, 2024

View reviewed changes

jvdp1 reviewed Mar 25, 2024

View reviewed changes

perazz and others added 9 commits March 25, 2024 16:50

Update src/stdlib_linalg_constants.fypp

88317d9

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update src/stdlib_linalg_constants.fypp

9eb9775

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

address style changes

9f74fd7

address style changes

documentation + example

3762517

generalize interface (rank-agnostic)

cb9a7fc

add xdp formats

0782e43

intel compiler issue: remove buffer write

b9e7e67

add xdp symbol

affd5d0

move kinds to stdlib_kinds

322b37e

perazz mentioned this pull request Mar 26, 2024

Request to upgrade Intel-classic compiler in macOS CI #776

Closed

gnikit mentioned this pull request Mar 26, 2024

Provide BLAS, LAPACK backends and interfaces #772

Merged

3 tasks

perazz added 2 commits April 2, 2024 11:03

Merge branch 'master' into linalg_state

526e816

remove duplicate stdlib_linalg_constants.fypp

41bf3a3

jvdp1 mentioned this pull request Apr 2, 2024

Preparation for 0.5.0 release #779

Merged

gnikit reviewed Apr 2, 2024

View reviewed changes

more explanation

a90f25a

Update example_state1.f90

fb008b4

add another state example

00db324

jalvesz approved these changes Apr 8, 2024

View reviewed changes

jvdp1 approved these changes Apr 8, 2024

View reviewed changes

perazz and others added 6 commits April 8, 2024 14:17

Update example/linalg/example_state1.f90

9b52091

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update example/linalg/example_state2.f90

4b3c20a

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update example/linalg/example_state2.f90

422a3d0

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update src/stdlib_linalg_state.fypp

c6ab922

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update src/stdlib_linalg_state.fypp

36b3f93

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Update src/stdlib_linalg_state.fypp

dbc843a

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

perazz added 2 commits April 8, 2024 14:57

example_state1: import operator(/=)

33c2de6

import linalg_error_handling

dfd03fc

perazz merged commit 407798c into fortran-lang:master Apr 11, 2024
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provide state/error handling for linear algebra #774

Provide state/error handling for linear algebra #774

perazz commented Mar 16, 2024 •

edited

Loading

certik left a comment

certik Mar 25, 2024

perazz Mar 25, 2024

certik Mar 25, 2024

certik Mar 25, 2024 •

edited

Loading

perazz Mar 25, 2024 •

edited

Loading

perazz Apr 2, 2024

jvdp1 Apr 2, 2024

perazz Apr 2, 2024

jvdp1 Apr 2, 2024

perazz commented Mar 25, 2024 •

edited

Loading

jvdp1 left a comment

jvdp1 Mar 25, 2024

perazz Apr 2, 2024

perazz commented Apr 2, 2024

gnikit left a comment

perazz commented Apr 2, 2024 •

edited

Loading

jalvesz commented Apr 2, 2024

perazz commented Apr 5, 2024 •

edited

Loading

jalvesz commented Apr 6, 2024

perazz commented Apr 6, 2024

jalvesz commented Apr 8, 2024

jvdp1 left a comment

perazz commented Apr 8, 2024

jvdp1 commented Apr 11, 2024

perazz commented Apr 11, 2024

jvdp1 commented Apr 11, 2024

gnikit commented Apr 11, 2024

	character(*), parameter :: &
	!> Format string for integers
	FMT_INT = '(i0)', &
	!> Format string for single precision real numbers
	FMT_REAL_SP = '(es15.8e2)', &
	!> Format string for souble precision real numbers
	FMT_REAL_DP = '(es24.16e3)', &
	!> Format string for extended double precision real numbers
	FMT_REAL_XDP = '(es26.18e3)', &
	!> Format string for quadruple precision real numbers
	FMT_REAL_QP = '(es44.35e4)', &
	!> Format string for single precision complex numbers
	FMT_COMPLEX_SP = '(es15.8e2,1x,es15.8e2)', &
	!> Format string for double precision complex numbers
	FMT_COMPLEX_DP = '(es24.16e3,1x,es24.16e3)', &
	!> Format string for extended double precision complex numbers
	FMT_COMPLEX_XDP = '(es26.18e3,1x,es26.18e3)', &
	!> Format string for quadruple precision complex numbers
	FMT_COMPLEX_QP = '(es44.35e4,1x,es44.35e4)'

Provide state/error handling for linear algebra #774

Provide state/error handling for linear algebra #774

Conversation

perazz commented Mar 16, 2024 • edited Loading

certik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

certik Mar 25, 2024 • edited Loading

Choose a reason for hiding this comment

perazz Mar 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

perazz commented Mar 25, 2024 • edited Loading

jvdp1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

perazz commented Apr 2, 2024

gnikit left a comment

Choose a reason for hiding this comment

perazz commented Apr 2, 2024 • edited Loading

jalvesz commented Apr 2, 2024

perazz commented Apr 5, 2024 • edited Loading

jalvesz commented Apr 6, 2024

perazz commented Apr 6, 2024

jalvesz commented Apr 8, 2024

jvdp1 left a comment

Choose a reason for hiding this comment

perazz commented Apr 8, 2024

jvdp1 commented Apr 11, 2024

perazz commented Apr 11, 2024

jvdp1 commented Apr 11, 2024

gnikit commented Apr 11, 2024

perazz commented Mar 16, 2024 •

edited

Loading

certik Mar 25, 2024 •

edited

Loading

perazz Mar 25, 2024 •

edited

Loading

perazz commented Mar 25, 2024 •

edited

Loading

perazz commented Apr 2, 2024 •

edited

Loading

perazz commented Apr 5, 2024 •

edited

Loading