C Library Functions - disp (3)
NAME
disp(3f) - [M_display] pretty-print a matrix
CONTENTS
Description
Call With Complete List Of Arguments
Asterisk_unit And Null_unit
Author
DESCRIPTION
This is the principal subroutine of the package. It has various control arguments that specify the exact format of the output. Most of these may also be used as arguments of the subroutine DISP_SET. When used with DISP, a control argument affects only the item being displayed with the current call, but when used with DISP_SET, the default settings for subsequent DISP calls are affected. The default values for individual arguments given below are used unless they have been changed by a call to DISP_SET. All character arguments should be of type default character.
Simple Calls:
call disp call disp(x) call disp(title, x) call disp(x, fmt) call disp(title, x, fmt)The first call advances to the next line, and the other calls display X on the default unit (the unit may be changed with the UNIT argument). The default putstrmodule (see section 2) sets the asterisk unit (usually the screen) to be default. The purpose of individual arguments is as follows:
X The item to be displayed. X may be scalar, vector or matrix (i.e. of rank <= 2) and the following kinds of data are supported: default integer default real (or single precision, real(kind(1.0))) double precision real (or real(kind(1d0))) default complex (or complex(kind(1.0))) double precision complex (or complex(kind(1d0))) default logical default characterWith the add-on modules described in section 2.3 other kinds may be displayed. Matrices are displayed in traditional mathematical order, so the rows displayed are X(1,:), X(2,:) etc. Vectors are by default displayed as column vectors (but a row orientation may be specified with the ORIENT argument). An SS edit descriptor is applied automatically so positive elements are not prefixed with a + sign (the Fortran standard makes outputting a + sign optional).
TITLE Provides a label for X. The label prefixes X by default but this may be changed with the STYLE argument (see examples in section 3.2). When X is absent TITLE must also be absent. FMT When present, FMT should contain an edit descriptor that will be used to format each element of X (or the real parts of X in case X is complex and FMT_IMAG is present; see below). The possible edit descriptors are: Fw.d, Dw.d, Ew.dEe, ENw.dEe, ESw.dEe: real data (the Ee suffixes are optional) Iw, Bw, Ow, Zw: integer data (all may be suffixed with .m) Lw: logical data A, Aw: character data Gw.d, Gw.dEe: any dataExample calls for numeric X are CALL DISP(X,’ES11.4’) and CALL DISP(’X=’,X,’F8.4’). If X is a scalar string (i.e. of rank 0) and TITLE is absent FMT must be specified with a keyword (otherwise the call is taken to have TITLE and X): CALL DISP(’str’,FMT=’A4’) displays "str" but CALL DISP(’str’,’A4’) displays "strA4").
If FMT is absent, each element of X is formatted with a default edit descriptor. When X is of type logical the default is L1 and when it is of type character the default is A (which is equivalent to Aw where w = LEN(X)). For integer data the default is Iw where w is exactly big enough to accommodate both the largest positive and the largest negative values in X. For real and complex data the default also depends on the largest absolute values in X, as detailed in the DIGMAX-paragraph in section 3.2. The format used for complex numbers is demonstrated in the introduction above.
CALL WITH COMPLETE LIST OF ARGUMENTS
CALL DISP(TITLE, X, FMT, FMT_IMAG, ADVANCE, DIGMAX, LBOUND, ORIENT, SEP, STYLE, TRIM, UNIT, ZEROAS)
All dummy arguments are optional and some of them are incompatible with some data types of X. The arguments control how X is displayed, as described in section 3.1 and below. For the character arguments ADVANCE and ORIENT the case of letters is ignored (so e.g. ADVANCE = ’yes’ and ADVANCE = realized with argument keywords, e.g. CALL DISP(’X=’, X, DIGMAX=3, ORIENT=’ROW’). When X is a scalar string FMT must also be associated with keyword, as mentioned in section 3.1. The most useful application of calling DISP with X absent is to advance to the next line or display an empty line. For this purpose, the only relevant arguments are UNIT, and ADVANCE with the value
FMT_IMAG = edit-descriptor-imag An edit descriptor for imaginary parts of complex X. The statement CALL DISP((1.31,2.47),’F0.1’,’F0.2’) will display "1.3 + 2.47i". If FMT_IMAG is absent and FMT is present then both real and imaginary parts are edited with FMT. If both are absent, separate defaults are used, as explained in the DIGMAX-paragraph below. FMT_IMAG must be absent if X is not complex. ADVANCE = adv The value for ADVANCE may be ’yes’, ’no’ or ’double’. If the value is ’yes’ then X is written out immediately, if it is ’double’ then X is written out followed by an empty line (thus giving double spacing), and if it is ’no’ then X is not written out until the next DISP call on the same unit with advancing turned on (either by default, via a call to DISP_SET, or via the ADVANCE keyword). When this occurs, all the items displayed with DISP since the last output occurred on the unit are written out side by side, separated by three spaces unless a different separation has been specified via the MATSEP argument of DISP_SET. Default value of ADVANCE is ’yes’. DIGMAX = n Controls the format used for real and complex data in the absence of FMT. For real items the format is chosen so that the displayed number of largest absolute magnitude (say xmax) has n significant decimal digits. If 0.1 <= |xmax| < 10**n an F edit descriptor is used, otherwise an E edit descriptor. For complex items these rules are applied separately to the real parts and imaginary parts, and thus two different formats are used. When X is not of real or complex type the argument DIGMAX is ignored. When DIGMAX is present FMT should be absent. The default is n = 6. LBOUND = lbound This argument is a default integer vector with the numbers of the first row / column to show when displaying with numbered style. When calling subroutines in Fortran, only the shape of matrix arguments is passed with the arguments, but matrix lower bounds are assumed to be 1 unless declared explicitly in the routine. To compensate for this deficiency LBOUND may be set to the declared lower bound(s) of X. To take an example, let aij = exp(i + j - 1) as in section 1, but let A be declared with REAL::A(0:3,0:3). Then CALL DISP(A, STYLE = ’NUMBER’, LBOUND = LBOUND(A)) will display: > 0 1 2 3 > 0 1.000 2.718 7.389 20.086 > 1 2.718 7.389 20.086 54.598 > 2 7.389 20.086 54.598 148.413 > 3 20.086 54.598 148.413 403.429.In fact the call may be shortened to CALL DISP(A, LBOUND = LBOUND(A)) because numbering is default when LBOUND is present.
ORIENT = ori This argument can only be used when X is a vector (i.e. has rank 1). If ORIENT is results. SEP = sep Specifies a string which is written out between columns of displayed matrices. If X has rows (-1, 3) and (5, 10) and SEP is ’, ’ then the output will be: > -1, 5 > 5, 10
The length of the string must be at most 9. Default is ’ spaces). STYLE = style There are five possible styles: ’left’ Title is immediately to the left of the first line of the displayed item. ’above’ Title is centered immediately above the item. ’pad’ Title is centered above the item, padded with hyphens (-). ’underline’ Title is centered above the item, underlined with hyphens. ’number’ Each matrix or vector row and / or column is numbered.Any of the four title position styles can also be combined with the number style by specifying for example STYLE = ’pad & number’. Any character except space may be used instead of hyphen by prefixing it to the style. STYLE = ’*underline’ will thus underline the title with asterisks. Both row and column numbers appear for numbered matrices, but for vectors only row numbers appear (or column numbers when ORIENT is ’col’). The five styles are illustrated below, accompanied by an example of combined padded title and numbering.
> Matr = 1.2 4.2 Matr ---Matr-- Matr 1 2 ____Matr____ > 5.6 18.3 1.2 4.2 1.2 4.2 --------- 1 1.2 4.2 1 2 > 5.6 18.3 5.6 18.3 1.2 4.2 2 5.6 18.3 1 1.2 4.2 > 5.6 18.3 2 5.6 18.3The default value of STYLE is ’left’ if LBOUND is absent, ’number’ if it is present, and
TRIM = trim This argument can take three values, ’YES’, ’NO’ and ’AUTO’. When YES is specified, each column of displayed items is trimmed from the left, with ’NO’ the items are not trimmed and if TRIM is ’AUTO’ the items are trimmed when FMT is absent but not when it is present. In the following example, X and U are displayed with TRIM = ’yes’, but Y and V with TRIM = > ----X---- -------Y------ -----U----- -------V------ > 1 2 4 1 2 3 333 22 4444 333 22 4444 > 2 22 34 2 22 34 > 3 32 1234 3 32 1234One application of trimming is to display matrices with a fixed number of fractional digits but variable effective field width. Then Fw.d editing with w big enough is accompanied by TRIM = ’yes’. An example is the following display of a matrix with (i, k) element exp(k**i) using F20.2 and ’yes’:
power exponentials
2.72 7.39 20.09 2.72 54.60 8103.08 Similar output may be obtained using I and F edit descriptors with w = 0 as discussed in section 3.5. Apart from I and F edited displays, it is possible to trim A-edited displays as well as E-edited displays with some negative elements, but the first column all positive: With TRIM=’yes’:X=1.2e+5 -4.1e-2 With TRIM=’no’:X= 1.2e+5 -4.1e-2 2.3e-3 8.6e+1 2.3e-3 8.6e+1
UNIT = external-file-unit The unit which the output is sent to. There are three special units, which may be referred to either with constants or parameters (named constants) as follows: Constant Parameter Preconnected unit -3 ASTERISK_UNIT The asterisk unit (often the screen) -2 PUTSTR_UNIT The subroutines PUTSTR and PUTNL -1 NULL_UNIT Null device (all output to this is discarded)These units are further described in sections 3.3 and 3.4. Other unit numbers correspond to external files that should have been connected with open-statements. The default unit depends on the named constant DEFAULT_UNIT, defined in PUTSTRMODULE. The default PUTSTRMODULE sets it to -3 (see sections 2 and 3.4).
ZEROAS = zerostring Supported for integer and real X (not complex) Any element that compares equal to 0 will be displayed as zerostring. If, for example, A is a 4 by 4 upper triangular matrix with aij = 1/max(0,j - i + 1) then CALL DISP(’A = ’, A, ’F0.3’, ZEROAS = ’0’, ADVANCE = ’NO’) and CALL DISP(’B = ’, A, ’F0.3’, ZEROAS = ’.’) will display: A = 1.000 0.500 0.333 0.250 B = 1.000 0.500 0.333 0.250 0 1.000 0.500 0.333 . 1.000 0.500 0.333 0 0 1.000 0.500 . . 1.000 0.500 0 0 0 1.000 . . . 1.000Notice that when zerostring contains a decimal point it is lined up with other decimal points in the column. If zerostring has length 0, the default behavior of not treating zeros specially is re-established, in case an earlier DISP_SET call has been used to set ZEROAS.
ASTERISK_UNIT AND NULL_UNIT
As already mentioned in section 3.2 there are three special units, ASTERISK_UNIT = -3, PUTSTR_UNIT = -2 and NULL_UNIT = -1. These public named constants (parameters) are defined by M_display.
Selecting ASTERISK_UNIT channels all output to the unit that WRITE(*,...) statements use. The ISO_FORTRAN_ENV intrinsic module of Fortran 2003 defines the named constant OUTPUT_UNIT and this may be used instead, unless its value is set to -2 by the compiler (which would clash with PUTSTR_UNIT).
Selecting NULL_UNIT causes all output via DISP to be discarded. This feature makes it simple to turn the output on and off, which may be useful for debugging and testing purposes. If UNIT = U is specified in all DISP-calls, it is enough to change the value of U to -1 to turn off output.
PUTSTR_UNIT: Output with user written subroutines
One of the purposes of the PUTSTR_UNIT is to make displaying possible in situations where ordinary print- and write-statements do not work. This is for example the case in Matlab mex-files (in fact the execution of a write statement on the asterisk unit crashes Matlab). To use the PUTSTR_UNIT it is necessary to write two subroutines with interfaces:
SUBROUTINE PUTSTR(S) CHARACTER(*), INTENT(IN) :: SThe first of these should output the string S, and the second one should advance output to the next line. These subroutines should be placed in a module PUTSTRMODULE as explained in section 2. The module should also define a named constant DEFAULT_UNIT, which could be set to -2 to make the PUTSTR_UNIT default. An example that works with g95 and Matlab mex-files is:SUBROUTINE PUTNL()
module putstrmodule integer, parameter :: default_unit = -2At the beginning of the file M_display.f90 there is a slightly longer version which works with both g95 and gfortran. Testing this module is discussed in section 6.2 below.contains subroutine putstr(s) character(*), intent(in) :: s call mexprintf(s//char(0)) end subroutine putstr
subroutine putnl() call mexprintf(char(10)//char(0)) end subroutine putnl
end module putstrmodule
USING W=0 EDITING
The Fortran standard stipulates that writing a single element with I0 editing results in the smallest field width that accommodates the value, and the same applies to B0, O0, Z0 and F0.d editing. With DISP, the width of a displayed column will be the width of the widest field in the column, and each element is right-adjusted in the column. This gives exactly the same output as using TRIM=’yes’ and a specified field width bigger than the largest occurring. Note that with F0.d editing, there is no limit on the width of a column, but with Fw.d and TRIM=’yes’ any element wider than w will be displayed as w asterisks:
------------------F0.2------------------ -----F13.2, TRIM=’yes’---- 14.28 142857142857142857142857.14 0.47 14.28 ************* 0.47 1.42 1414213562.37 0.69 1.42 1414213562.37 0.69NOT-A-NUMBER AND INFINITE VALUES
If the compiler supports not-a-number and infinite values as defined by the IEEE exceptional values of Fortran 2003, these are displayed as NaN, +Inf or Inf. A not-a-number value X is identified as being not equal to itself, and an infinite value is either greater than HUGE(X) or smaller than -HUGE(X). On all the compilers tried the sequence BIG=1E20; CALL DISP(EXP(BIG)) displays +Inf, and the program segment:
> real :: z = 0, big = 1e20 > call disp([z, z/z, big, -exp(big)])displays
> 0.00000E+00 > NaN > 1.00000E+20 > -Inf
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 | disp (3) | February 23, 2025 |
