C Library Functions - M_display (3)

NAME

M_display(3f) - [M_display] module for pretty-printing matrices

Introduction
Overview Of Modules
An Example Program
Author

INTRODUCTION

M_display is a standard Fortran 95 module for quick and easy displaying of numbers, vectors or matrices using default or specified format. It can be useful for debugging purposes, for preliminary display of numerical results, and even for final display of such results in cases when carefully formatted tables are not needed. It is comparable to the automatic matrix printing of Matlab, S and R, but offers substantially more control over the format used.
The module can handle the standard Fortran data types integer, single precision, double precision, complex, logical and character. Integer, real, complex and logical data of other than default kind are supported with add-on modules. The module contains the following public procedures:
      Subroutine DISP                  The main procedure used for displaying items
      Subroutine DISP_SET              Used to change default settings for DISP
      Subroutine DISP_SET_FACTORY      Restores DISP-settings to original (factory) default
      Function DISP_GET                Returns a structure with current DISP-settings
      Function TOSTRING                Returns a string representation of a scalar or vector
      Subroutine TOSTRING_SET          Used to change default settings for TOSTRING
      Subroutine TOSTRING_SET_FACTORY  Restores TOSTRING-settings to original default
In addition the module defines a public derived type, DISP_SETTINGS, used for saving and restoring settings for DISP. The procedures DISP and TOSTRING have a generic interface and optional arguments, so the same subroutine / function name, is used to display items of different data types and ranks, with or without labels, and using default or specified format. Similarly DISP_SET is generic and can be used both to change individual settings and to restore previously saved settings.
The most basic calling syntax for displaying is CALL DISP(expression) which will display the expression with default format. The format may be specified with CALL DISP(expression, edit- descriptor), and CALL DISP(title, expression) will label the displayed item with a title. Examples are CALL DISP(A), CALL DISP(A,’F9.3’), CALL DISP(’A=’,A) and CALL DISP(’A=’,A,’F9.3’), the last one specifying both title and format. If aij = exp(i + j - 1), i, j = 1,...,4, then CALL DISP(’A = ’, A) writes out:
     > A =  2.72    7.39   20.09    54.60
     >      7.39   20.09   54.60   148.41
     >     20.09   54.60  148.41   403.43
     >     54.60  148.41  403.43  1096.63
and if bij = exp(i*j) the result of CALL DISP(B) is:
     > 2.71828E+0  7.38906E+0  2.00855E+1  5.45981E+1
     > 7.38906E+0  5.45981E+1  4.03429E+2  2.98096E+3
     > 2.00855E+1  4.03429E+2  8.10308E+3  1.62755E+5
     > 5.45981E+1  2.98096E+3  1.62755E+5  8.88611E+6.
It is also possible to number the rows and columns: CALL DISP(A, STYLE=’NUMBER’) will give:
     >      1       2       3        4
     > 1   2.72    7.39   20.09    54.60
     > 2   7.39   20.09   54.60   148.41
     > 3  20.09   54.60  148.41   403.43
     > 4  54.60  148.41  403.43  1096.63.
The selection between F and E editing depends on the size of the largest displayed element as discussed in section 3.2 below. Among the settings that may be controlled is the spacing between columns, the number of significant digits, the placement of the label, and the file unit where the output goes. Items can in addition be displayed side by side, for example:
     > CALL DISP(’X = ’, X, ADVANCE=’NO’)
     > CALL DISP(’Y = ’, Y)
which might output:
     > X = 7  8  3   Y = 11
     >     4  0  2        2
     >     1  3  6        7
Complex numbers are formatted as illustrated by:
     > COMPLEX C(3,3)
     > FORALL(I=1:3, K=1:3) C(I,K)=LOG(CMPLX(-I*K))**K
     > CALL DISP(’C = ’, C, ’F0.3’)
which will display
     > C = 0.000 + 3.142i   -9.389 +  4.355i   -31.203 - 19.631i
     >     0.693 + 3.142i   -7.948 +  8.710i   -47.300 -  0.749i
     >     1.099 + 3.142i   -6.659 + 11.258i   -54.449 + 14.495i
infinite and not-a-number real values are supported and displayed as nan, +inf or -inf.
the remaining sections in this user manual contain detailed information on using the module. section 2 discusses the basics of using the module, including use statements, compiling and linking, and add-on modules supporting non-default kinds of data. section 3 gives a detailed description of the generic subroutine disp. all the possible arguments are listed and the purpose of each one described. section 4 describes how to change various settings that control how items are displayed with disp. section 5 describes the function tostring which may be used to change numbers to strings. finally testing of the module is discussed in section 6.

OVERVIEW OF MODULES

The file M_display.f90 actually begins with two auxiliary modules, PUTSTRMODULE and M_display_UTIL. The first one contains two dummy subroutines, PUTSTR and PUTNL, which do nothing, but must be incorporated to avoid an "undefined symbol" link error. In addition it defines the named constant (parameter) DEFAULT_UNIT = -3, which makes the asterisk unit (usually the screen) the default to display on.
Alternatively the user can write his own PUTSTRMODULE as described below. An example is near the beginning of M_display.f90 (commented out) and also in the file putstrmodule_mex.f90, enclosed with the package. It may be used (commented in instead of the default one) to allow Matlab mex files to display in the Matlab command window.

AN EXAMPLE PROGRAM

Following is a short example program that uses the package:

      program example
        use M_display
        real :: a(3) = [ 1.2345, 2.3456, 3.4567 ]
        call disp(’A = ’, A, SEP=’, ’, ORIENT = ’ROW’)
      end program example

The program should write out "A = 1.23450, 2.34560, 3.45670".

A longer example program:

   program demo_M_display
   use M_display
   implicit none
   integer, parameter :: rk = selected_real_kind(6), n = 3
   real(rk) :: a(n,n), b(n,n), x
   integer i, j, k(5)
     call disp_set(advance = ’double’)
     forall(i=1:n, j=1:n)
       a(i,j) = exp(real(i+j-1, rk))
       b(i,j) = exp(real(i**j, rk))
     end forall
     call disp(’A = ’, a)
     call disp(b)
     call disp(a(1:2,:),’f0.5’)
     call disp(’MATRIX’, a, style=’UNDERLINE & NUMBER’, unit=-3, digmax=4)
     k = [-3,0,12,14,0]
     call disp(’K’, k, style=’pad’, orient=’row’, sep=’ ’, zeroas=’.’)
     x = 1.5
     call disp(’The square of ’//tostring(x)//’ is ’//tostring(x*x))
     call disp_set(matsep = ’ | ’)
     call disp([11,12,13], advance=’no’)
     call disp([.true., .false., .true.], advance=’no’)
     call disp([’A’,’B’,’C’])
   end program demo_M_display

Expected results:

A = 2.718 7.389 20.086 7.389 20.086 54.598 20.086 54.598 148.413

2.71828E+00 2.71828E+00 2.71828E+00 7.38906E+00 5.45982E+01 2.98096E+03 2.00855E+01 8.10308E+03 5.32048E+11

2.71828 7.38906 20.08554 7.38906 20.08554 54.59815

MATRIX

--------------------

1 2 3

1 2.7 7.4 20.1

2 7.4 20.1 54.6

3 20.1 54.6 148.4

------K----- -3 . 12 14 .
The square of 1.5 is 2.25
11 | T | A 12 | F | B 13 | T | C

AUTHOR

Based on dispmodule(3f), "A Fortran 95 module for pretty-printing matrices". Version number 1.02 6-Sept-2008, Kristjan Jonasson, Dept. of Computer Science, University of Iceland (jonasson@hi.is).

Nemo Release 3.1

M_display (3)

February 23, 2025

Generated by manServer 1.08 from 4a2aaf9d-94ad-4725-a902-904fefac8b98 using man macros.