Dispmodule User Manual
Contents
1. 1PG12 5 IFMT IO TRIMB YES and TRIMZ G 5 4 TOSTRING examples When the original factory defaults are in effect the result of invoking TOSTRING will usually be as follows Invocation Returned string tostring atan 1 0 0 785398 tostring exp 3 1 0 1 4 97871E 02 0 36788 1 2 7183 tostring real i i 1 5 8 1 256 6561 65536 3 90625E 05 tostring 1 23456 1 2300 1 23456e6 11 2346 1 23 1 23456E 06 tostring real i i 1 5 8 f0 1 1 0 256 0 6561 0 65536 0 390625 0 tostring real Ci i 1 5 8 f6 1 1 0 256 0 6561 0 tostring 1200000 1 2e 9 1 2E 06 1 2E 09 tostring 1 200d103 1 24103 tostring 1 140 2 2d10 3 3d201 1 1E 00 2 2E 10 3 3E 20 tostring 77 77 tostring Ci i 3 3 11 177147 2048 1 0 1 2048 177147 tostring Ci i 2 3 3 11 i7 cg 2048 1 0 1 2048 177147 Poser ingChcrs i 3 3 11 i4 eek ERE 1 0 1 2048 Tee EAE TIN 0 5 0 57 tostring emplx 1 2 0 25 0 70711 0 707111 0 8409 0 84091 tostring true false false T F F tostring true L2 TI The returned strings may be slightly different from the ones shown because some compilers at least some versions of g95 will produce one more decimal place in a few cases and because the Fortran standard al lows G editing to give exponent fields in the form 0dd instead of Edd The examples make use of brackets to construct ve2. 6554E 05 0 3906E 06 tostring 1200000 1 2e 9 0 12bE 07 0 12E 08 cal 1 tostring set factory Q 6 TESTING THE MODULES The package has been checked successfully with four different compilers g95 gfortran ifort from Intel and f95 from Nag The g95 compiler has been used on Windows Ubuntu Linux and Sun Solaris gfortran on Windows and Ubuntu Linux ifort on Windows and an AMD 64 computer with Suse Linux and the Nag compiler on Windows only There is one named constant at the beginning of the test programs which may be changed This is the pa rameter verbose When verbose is 2 the results of all tests are reported on the screen when verbose is 1 the default the report is much more concise and when it is 0 the report is minimal and a few tests are by passed In all cases the report ends with OK if all tests are passed otherwise it ends with assertion failure information 6 1 Checking DISPMODULE only The display modules are accompanied by a test program in the file test dispmodule f90 The test program is fairly comprehensive and tries to test all the features of DISPMODULE Thus all public procedures are called with and without all optional arguments and for those arguments that have a limited range of allowed values such as ADVANCE STYLE and TRIM all these values are tried In addition the tests check all the examples that are given in this user manual However it is obviously impossible to test all possible c
3. Computer Science University of Iceland jonasson hi is Permission to use copy modify and or distribute this software for any purpose with or without fee is hereby granted provided that the above copyright notice and this permission notice appear in all copies The software is provided as is and the author disclaims all warranties Explanation I wanted a short license to emphasize that the package is free and that people could add it to commercial packages if they wished I did a little browsing and found this license text called the ISC licence I have shortened the no warranty clause K J 17 The files in the package are all contained in the same folder They are the following FORTRAN 95 MODULES THE ALGORITHM IMPLEMENTATION dispmodule f90 Principal module of package disp_ilmod f90 Add on module for 1 byte integers disp i2mod f90 Add on module for 2 byte integers disp i4mod f90 Add on module for 4 byte integers disp i8mod f90 Add on module for 8 byte integers disp llmod f90 Add on module for 1 byte logicals disp rl16mod f90 Add on module for quad precision reals DOCUMENTATION dispmodule userman doc User manual in Word 2003 format dispmodule userman pdf User manual in pdf format dispmodule userman html User manual in html dispmodule userman txt User manual in plain text format dispmodule doc Paper submitted to TOMS in April 2008 changelog txt Textfile detailing changes since version 0 00 submitted
4. cking DISPMODULE only et peri hits edd eo et e i eee eee ik eoe 16 6 2 Complete checking rninn ru Ree Rt HER Used etc fe ede Rene os REUS Le ds 17 6 3 Displaying from Matlab mex files enne nnne nennen nennen nnne 17 Ret rences stain esaet nc ewido wlan tbe etii bodie ge ti Le sn 17 Appendix Contents ofc README lepi 2e iiti RE ee ette bee E EE EUR EHE Ee aan sa E sir 17 1 INTRODUCTION DISPMODULE is a standard Fortran 95 module for quick and easy displaying pretty printing of num bers vectors or matrices using default or specified format It can be useful for debugging purposes for pre liminary display of numerical results and even for final display of such results in cases when carefully for matted 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 re
5. is with most if not all computers compilers either 4 or 8 bytes and many if not all computers compilers support other kinds of integers covering the range of byte lengths 1 2 4 and 8 The support of 1 byte logicals is also common and some computers compilers have quadruple precision reals Support of these non standard kinds is provided by the add on modules DISP I1MOD DISP I2MOD DISP I4MOD DISP I8MOD DISP L1MOD and DISP R16MOD These assume that the following hold SELECTED INT KIND 2 1 byte integers SELECTED INT KIND 4 2 byte integers SELECTED INT KIND 9 4 byte integers SELECTED INT KIND 18 8 byte integers SELECTED REAL KIND 25 16 byte reals quad precision LOGICAL 1 1 byte logicals If this is not the case or support for other kinds is wanted then the files must be edited to obtain what is de sired To use any of these modules reference them with use statements USE DISP_xxMOD compile them and link with the program With a little editing effort it is also possible to combine a subset of them with DISPMODULE in a single module the details are left to the user 3 SUBROUTINE DISP 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
6. when used with DISP_SET the default settings for subsequent DISP calls are affected The default values for individual argu ments given below are used unless they have been changed by a call to DISP_SET All character arguments should be of type default character An overview of the arguments is in table 1 and further details are in sec tions 3 1 3 5 3 1 Simple calls CALL DISP CALL DISP X CALL DISPCTITLE X CALL DISP X FMT CALL DISPCTITLE X FMT Table I Arguments of subroutine DISP all are optional Argument Type Length Kind Rank Possible values Default Purpose TITLE Character Default 0 Any Empty Label to use for X Integer Real 0 1 X Complex Any Any Item to display Logical or2 Character Depends Edit descriptor for an FMT Character Default 0 Valid edit descriptor on X and element of X real part if DIGMAX X is complex Depends Edit descriptor for imagi FMT IMAG Character Default O0 Valid edit descriptor on X and nary parts of elements of DIGMAX X Stay on same line ad ADVANCE Character lt 6 Default 0 N YES ance to next line to next DOUBLE line but one Number of significant digits to show for X DIGMAX Integer Default 0 1 2 90 6 element of largest abso lute magnitude 1 or Numbers of first row LBOUND Integer Default 1 Any 1 1 leohimaroe X ORIENT Character 3 Default 0 ROW or CO
7. with Matlab to write s The square of num2str x is num2str x x disp s and in Java one may write String s The square of Float toString x is Float toString x x System out println s or in fact even shorter System out println The square of x is x x Both program fragments will display The square of 1 5 is 2 25 It is possible to achieve a similar effect in Fortran using internal files and list directed output character 100 s real x 1 5 write s The square of x is x x print trim s but this is cumbersome and also there is the disadvantage that the result is compiler dependent 13 DISPMODULE has a function TOSTRING which overcomes this disadvantage and offers additional flexibility With x 1 5 the following statement will produce the same output as Matlab and Java give call disp The square of tostring x is tostring x x Because Fortran 95 does not have variable length strings using TOSTRING lacks some of the possibilities of the Java and Matlab functions However TOSTRING is compatible with the ISO VARYING STRING module and if this is available one may for example obtain the same output as above with use iso varying string type varying string xs x2s x 1 5 xs tostring x x2s tostring x 2 print The square of xs is x2s TOSTRING accepts integer logical or real scalars or vectors The subroutine TOSTRING SET ma
8. 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 DISPC Y Y which might output X PAN woo 3 2 2 6 Complex numbers are formatted as illustrated by complex C 3 3 forall i 1 3 k 1 3 Ci k log emplx 1 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 7497 1 099 3 1423 6 659 11 2581 54 449 14 4957 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 dis cusses 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 possibl
9. DISP SET AND DISP GET The subroutine DISP SET may be used to change default values of all the arguments of DISP except TITLE X FMT and LBOUND In addition the default separator between items that are displayed side by side using ADVANCE no may be changed with the MATSEP argument 4 1 The derived type DISP SETTINGS DISPMODULE contains the following definition of the data type DISP SETTINGS TYPE DISP SETTINGS character 3 advance YES character 9 matsep character 3 orient COL character 9 sep character 19 style LEFT character 4 trim AUTO character 9 zeroas integer digmax 6 integer matseplen 3 integer seplen 2 integer unit 3 integer zaslen 0 END TYPE DISP_SETTINGS Structures of type DISP_SETTINGS may be used to save and later restore format control settings of DISP As shown new variables of this type will automatically have default values for all components 4 2 Calling syntax for DISP_SET There are two ways to call DISP_SET CALL DISP_SETCSETTINGS CALL DISP SETCADVANCE DIGMAX MATSEP ORIENT SEP STYLE UNIT ZEROAS Both calls change the default format control used in subsequent calls to DISP In the first call SETTINGS is of type DISP SETTINGS and the default values for all arguments is changed In the second call all the arguments are optional If an argument is absent the corresponding default setting is not changed An example ca
10. ES ENGINEERING RESEARCH INSTITUTE vc UNIVERSITY OF ICELAND Dispmodule User Manual Kristj n J nasson Report VH 01 2008 Reykjav k May 2008 Report VH 01 2008 Reykjavik May 2008 Kristj n J nasson DISPMODULE User Manual Engineering Research Institute University of Iceland Technical report VHI 01 2008 May 2008 Kristj n J nasson associate professor Department of Computer Science Hjardarhagi 4 IS 107 Reykjavik Iceland Email jonasson hi is The author is responsible for the opinions expressed in this report These opinions do not necessarily represent the position of the Engineering Research Institute or the University of Iceland Copyright Kristj n J nasson 2008 The software described in this user manual is free and distributed with the following license Permission to use copy modify and or distribute this software for any purpose with or without fee is hereby granted provided that the above copyright notice and this permission notice appear in all copies The software is provided as is and the author disclaims all warranties The software is available on the author s web page www hi is jonasson Engineering Research Institute University of Iceland Hjar arhagi 4 IS 107 Reykjavik Iceland CONTENTS 1 Introduction esiin RI 4 Di ISAS E 5 2 T Overview of modules 53 xe veo be e AE ET A E AA AEO E E EU eR 5 2 2 An example program aso mei terere testet De eed reget ctt ble lese oer d
11. L GOD eo column vector String used to separate SEP Character lt 9 Default O0 Any matis columns LEFT ABOVE PAD UNDERLINE Placement and form of STYLE Character lt 9 Default 0 or NUMBER can LEFT title should rows col be combined e g umns be numbered PAD amp NUMBER Trim blanks from left of TRIM Character lt 4 Default 0 YES NO or AUTO AUTO X AUTO means trim if FMT is absent ASTERIS External file unit to send eun UNIT Integer Default 0 2 3 K_UNIT output to String to display instead ZEROAS Character lt 9 Default O0 Any Bi 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 s as follows 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 X The item to be displayed X may be scalar vector or matrix i e of rank 2 and the follow ing 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 character With the add on modules de
12. above the item padded with hyphens underline Title is centred 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 amp 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 accom panied by an example of combined padded title and numbering Matr 1 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 3 The default value of style is left if LBOUND is absent number if it is present and left amp number if both TITLE and LBOUND are present 9 TRIM trim This argument can take three values YES NO and AUTO When YES is speci fied 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 pre sent In the following example X and U are displayed with trim yes but Y and V with trim no In all cases the edit descriptor is the default I4 The default i
13. ample program Following is a short example program that uses the package PROGRAM EXAMPLE USE DISPMODULE REAL A 3 1 2345 2 3456 3 4567 CALL DISPC A A SEP ORIENT ROW END PROGRAM EXAMPLE If this program is in a file example f90 and the Gnu Fortran compiler is used with Unix the following commands will accomplish compiling linking and executing the symbols are operating system prompts 5 gfortran c dispmodule f90 gfortran o example example f90 dispmodule o example Alternatively the compiled modules may be placed in a library that is included when linking gfortran c dispmodule f90 ar r libdispmodule a dispmodule o gfortran o example example f90 L ldispmodule example The program should write out A 1 23450 2 34560 3 45670 The package also contains a little longer example program in dispdemo f90 with a makefile On Unix with gfortran the command make demo compiler gfortran should compile link and run dispdemo The makefile s default compiler name is f95 2 3 Displaying data of non default kind The Fortran standard only guarantees the support of one kind of integers logicals and characters and two kinds of real and complex numbers the standard mentions double precision complex numbers and reading between the lines their support is almost deducible though not directly guaranteed The size of default kind integers logicals and single precision reals
14. arts are edited with FMT If both are ab sent 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 adv may be yes no or double If the value is yes then X is written out immediately if itis 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 8 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 lt Ix 10 an F edit descriptor is used otherwise an E edit descriptor For complex items these rules are applied separately to the real parts and imagi nary parts and thus two different formats are used When X is not of real or complex type the ar gument DIGMAX is ignored When DIGMAX is present FMT should be absent The default is n 6 LBOUND bound This argument is a default integer vec
15. ctor constants a Fortran 2003 feature If the compiler being used does not support this and must be used instead Notice that trimming is on by default so there is not much purpose in specifying the format for integers and logicals Notice also that usually 5 significant digits are displayed when the default G editing results in F edited output but 6 digits for the numbers of small or large magnitude displayed with E editing This discrepancy is present in the Fortran standard the presence of the scale factor 1P in the edit descriptor increases the number of displayed significant digits Examples of using TOSTRING SET follow again the returned string may be slightly different 15 Invocation Returned string call tostring_set sep tostring 1 2 30 1 2 30 call tostring_set trimb NO tostring real i i1 1 5 8 f6 1 1 0 256 0 6561 0 xxv iste xe tostring C 1 2 30 i3 1 2 30 tostring i i 3 3 11 i4 eem 0 1 2048 tostring 1 2 30 i0 1 2 30 tostring true L3 vou call tostring_set trimz NONE sep trimb YES tostring real Ci i 1 4 8 1 0000 256 00 6561 0 65536 tostring 1 23456 1 2300 1 23456e6 1 2346 1 2300 1 23456E 06 tostring 1 200d103 1 200004103 call tostring set trimz ALL tostring realC Ci i21 5 20 8 f0 1 1 256 6561 65536 390625 call tostring set rfmt G12 4 tostring realC Ci 120 5 2 8 1 256 6561 0
16. e 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 sec tion 6 2 USAGE 2 1 Overview of modules The major part of the package is the module DISPMODULE in the file dispmodule f90 This module should be referenced with a use statement USE DISPMODULE and the file should be compiled and linked with other files To display non default kinds of data the add on modules described in section 2 3 below must also be used The file dispmodule f90 actually begins with two auxiliary modules PUTSTRMODULE and DISPMODULE_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 The second auxiliary module has utility procedures which are not accessible to the user Alternatively the user can write his own PUTSTRMODULE as described in section 3 4 below An example is near the beginning of dispmodule f90 commented out It may be used by commenting it in and com menting the default module out to allow Matlab mex files to display in the Matlab command window 2 2 An ex
17. e makes it simple to turn the out put on and off which may be useful for debugging and testing purposes If UNIT Uis specified in all DISP calls it is enough to change the value of U to 1 to turn off output 3 4 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 INTENTCIN S SUBROUTINE PUTNLO The 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 MODULE PUTSTRMODULE integer parameter default unit 2 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 At the beginning of the file dispmodule f90 there is a slightly longer version which works with both g95 and gfortran Te
18. gers L1 for logicals and 1PG12 5 for reals 5 3 The subroutines TOSTRING SET and TOSTRING SET FACTORY The subroutine TOSTRING SET has five arguments all of which are optional Argument association will nor mally be realized using argument keywords e g CALL TOSTRING_SET SEP The examples in section 5 4 clarify how to use this subroutine The five arguments are SEP Character string used to separate elements of displayed vectors Original default value is 14 RFMT Character string containing default edit descriptor to use to display real items The original default value is 1PG12 5 IFMT Character string containing default edit descriptor to use to display integer items The origi nal default value is IO TRIMB Controls whether leading and trailing blanks are trimmed from individual displayed ele ments Possible values are YES to trim blanks and NO for no trimming Default is YES TRIMZ Controls whether trailing zeros are trimmed from the fractional part of displayed items Possible values are NONE for no zero trimming G to trim fractional trailing zeros only when G editing is used and ALL to trim zeros with all types of editing Trailing decimal points are also removed when zero trimming is active Default value is G The subroutine TOSTRING SET FACTORY which has no arguments may be called to restore all settings of TOSTRING to the original default values the factory defaults SEP RFMT
19. he use disp_ statements changing the kind parameters i range or sik logikind and srk near the beginning of test dispmodule f90 and linking with the needed add on modules With some compilers computers it may be necessary to make changes to definitions of kind parameters in the add on modules and the test pro gram 6 3 Displaying from Matlab mex files There is a separate example program of calling DISP from a Matlab mex file in mexdispdemo f90 This has been tested with g95 gfortran and ifort on Windows To run this example one must first set up the Matlab mex command for Fortran compilation and for the testing this has been done with gnumex see gnu mex sourceforge net Also one needs to use the PUTSTRMODULE that is commented out at the start of DISPMODULE or with g95 the one given in section 3 4 instead of the dummy version Having made these preparations one can issue from the Matlab prompt the commands gt gt mex c dispmodule f90 gt gt mex mexdispdemo f90 dispmodule obj gt gt mexdispdemo hilb 3 1 4 Mexdi spdemo simply displays its arguments which should be a matrix and a vector REFERENCES 1 Kristj n J nasson Pretty printing matrices in standard Fortran 95 using DISPMODULE Engineering Research Institute University of Iceland Technical report VHI 02 2008 May 2008 APPENDIX CONTENTS OF README FILE README file for DISPMODULE package LICENSE Copyright c 2008 Kristj n J nasson Dept of
20. i doeet E eee 5 2 3 Displaying data of non default kind essent enne 6 Sv Subroutine DISP 5 edere RR eoe ee a CR Ro eed eee 6 Simple calls ett ttt ettet ttp ete mtu tt uM tuu De 6 3 2 Call with complete list of arguments cessere eene enn enne 8 3 3 ASTERISK UNIT and NULL UNIT 3 na n tet reiten egeta dees a 11 3 4 PUTSTR UNIT Output with user written subroutines 000 lees ceseceseceteeeteeeeeeeseeeeaeeeseeeneeenaes 11 3 5 Using w O0 editing spese p HERR eel etes dies Loop ee Met fete 11 3 6 Not a number and infinite values eese enne nennen nne neen nennen nennen tnn 12 4 Controlling default settings DISP SET and DISP GET eene emen 12 4 1 The derived type DISP SETTINGS dide mte Eier t te bise EEEE E 12 4 2 Calling syntax Tor DISP SET ooa go RE eR e 12 43 The function DISP GET riesce nee rtr sack Peto etre eee Te eee CP Pee RE eere RR 13 Ss Nurmbetrs to SLIDES eet e n Leder er HERE cau ehe ene redeo S tere cepi lente despide reete en ters 13 Sl Introduction 4e e e eee eet t Ee E e d E Le HE lee lae dee deti LR E totes 13 5 2 The function TOSTRING une ber dece eed o e OR oe edes 14 5 3 The subroutines TOSTRING SET and TOSTRING SET FACTORY eee 14 5 4 TOSTRING exainples in erede utere E Pee arenae cree eol eee Ci ee eet ee lessees 15 6 Testing the modules osni ie ER ertet i ede eee tel re a xac Eee ge ME ened cal 16 6 I Ch
21. in PUTSTRMODULE The default PUTSTRMODULE sets it to 3 see sections 2 and 3 4 ZEROAS zeros tring Supported for integer and real items 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 a 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 O 1 000 0 500 0 333 1 000 0 500 0 333 0 0 1 000 0 500 i 1 000 0 500 0 0 0 1 000 1 000 Notice 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 behaviour of not treating zeros specially is re established in case an earlier DISP SET call has been used to set ZEROAS 10 3 3 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 DISPMODULE 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 featur
22. ll is CALL DISP SET STYLE pad SEP The effect is that titles will be written padded above matrices and matrix column will be separated by one blank The type and purpose of all the arguments except MATSEP has been described in section 3 2 12 MATSEP ms Specifies a character string of length lt 9 that is written out between items matri ces when they are displayed side by side An example is CALL DISP X ADVANCE NO CALL DISP Y ADVANCE NO CALL DISP SET MATSEP CALL DISP Z ADVANCE YES The output from these calls might be 1 1 NON OAN SW oo Awe 0 2 0 Note that MATSEP affects the separation of all items that have been placed in the output queue of the unit being displayed on 4 3 The function DISP GET The argumentless function DISP GET returns the current default settings in a structure of type DISP SETTINGS If a subroutine changes the default settings with DISP SET it is possible to save the settings that are in effect when the routine is entered and restore these settings before returning from the routine An example is subroutine disp xy x y use dispmodule real x yC type disp settings ds ds disp get call disp set digmax 4 sep call disp x x call disp y y call disp set ds end 5 NUMBERS TO STRINGS 5 1 Introduction Many programming languages have built in functions that change numbers to strings It is for instance pos sible
23. o 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 de tailed in the DIGMAX paragraph in section 3 2 The format used for complex numbers is dem onstrated in the introduction above 3 2 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 argu ments 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 YES are equivalent Normally argument association for arguments after FMT or FMT_IMAG will be realized with ar gument 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 yes or double FMT IMAG edit descriptor imag An edit descriptor for imaginary parts of complex X The statement CALL DISP 1 31 2 47 FO 1 FO 2 will display 1 3 2 471 If FMT IMAG is absent and FMT is present then both real and imaginary p
24. ombinations of argu ments and argument values so one must be content with a partial test accompanied by examination of the source code of the modules and the test program To check only DISPMODULE not the add on modules test dispmodule should be compiled and linked with dispmodule With the Gnu Fortran compiler and Unix give the commands gfortran o test test dispmodule f90 dispmodule f90 test It is also possible to use Make with the command again assuming the Gnu compiler make check compiler gfortran 16 6 2 Complete checking To check also the add on modules and displaying of NaN s and infinities it is easiest to use Make which works if the compiler has a pre processing option most compilers do Use one of the make commands make check all kinds make check quadprec make check naninf make check naninf ieee possibly adding an option to select the compiler and or editing the makefile to select the add on modules to link with the program needed if default integers are 8 bytes The first listed make command checks display ing of 1 2 4 and 8 byte integers single and double precision reals and 1 byte logicals the second one checks displaying of quaruple precision reals and the last two check displaying of nan s and infinities use check naninf ieee if the compiler supports Fortran 2003 ieee_arithmetic 33 It is also possible to carry out complete checking manually by un commenting some of t
25. on display make check naninf Compile link and run checks of nan and infinities display make check naninf ieee Compile link amp run checks of nan and infinities display ieee compilers For other compilers or on Microsoft Windows with make installed e g cygwin mingw one can issue for example make demo compiler g95 platform windows make check compiler nag make check compiler ifort It may also be necessary to edit the makefile Apart from compiler and platform is is possible to set values of the makefile variables optimize debug fflags and more See the makefile itself for more information and examples Author Kristjan Jonasson Dept of Computer Science University of Iceland jonasson Ghi is 18
26. presentation 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 individ ual 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 a exp it j 1 i j 1 4 then CALL DISPC 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 b exp ij the result of CALL DISP B is 2 71828E 0 7 38906Et0 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
27. s TRIM AUTO ne em Ysaia eas cts ks V go 1 2 3 333 22 4444 333 22 4444 222 34 2 22 34 3 32 1234 3 32 1234 One 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 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 exter nal files that should have been connected with open statements The default unit depends on the named constant DEFAULT UNIT defined
28. scribed 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 speci fied 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 op tional 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 data Example 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 DISPC 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 t
29. sting this module is discussed in section 6 2 below 3 5 Using w 0 editing The Fortran standard stipulates that writing a single element with IO editing results in the smallest field width that accommodates the value and the same applies to BO OO ZO and FO 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 FO 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 ss F0 2 F13 2 TRIM yes 14 28 142857142857142857142857 14 0 47 14 28 ws wkw 0 47 1 42 1414213562 37 0 69 1 42 1414213562 37 0 69 11 3 6 Not a number and infinite values If the compiler supports not a number and infinite values as defined by the IEEE exceptional values of For tran 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 OO 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 C Z Z Z BIG EXP BIG displays 0 00000E 00 NaN 1 00000E 20 Inf 4 CONTROLLING DEFAULT SETTINGS
30. to TOMS originally EXAMPLE DRIVER dispdemo f90 Fortran 95 main program demonstrating usage expected demo output txt File with expected output from the demo program TESTING MATERIAL test dispmodule f90 Principal test Checks correctness of principal module test dispmodule fpp F90 Checks correctness of add on modules needs Fortran preprocessor test naninf f90 Checks displaying of nans and infinities with non ieee compilers test naninf ieee f90 Checks displaying of nans and infinities on ieee supporting compilers test naninf mod f90 Module used by test naninf f90 and test naninf ieee f90 mexdispdemo f90 Program for testing displaying from a Matlab mex file test all sh A shell script that runs a full set of tests MAKEFILE COMMAND FILE Makefile Makefile gnu make for example driver and test programs EVIDENCE OF PORTABILITY AND CONFORMANCE TO FORTRAN 95 STANDARD portability evidence txt Results of running test all sh on 5 different compiler platform combinations POSSIBLE MAKE COMMANDS The default compiler name is f95 and the default platform is Unix Linux It is assumed that gnu make is used on some systems one should use gmake instead of make If this is the case one may issue make demo Compile link and run example driver make check Compile link and run principal test make check all kinds Compile link and run checks of principal and add on modules make check quadprec Compile link and run checks of quadruple precisi
31. tor 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 as sumed to be 1 unless declared explicitly in the routine To compensate for this deficiency bound may be set to the declared lower bound s of X To take an example let a 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 ori is co1 the default a column vector is displayed and if ori is row a row vector 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 sepis then the output will be l 5 5 10 The length of the string must be at most 9 Default is character string with two spaces STYLE sfyle There are five possible styles left Title is immediately to the left of the first line of the displayed item above Title is centred immediately above the item pad Title is centred
32. y be used to change settings for TOSTRING 5 2 The function TOSTRING Apart from the item to be turned into a string an edit descriptor to use can optionally be supplied as the sec ond argument to TOSTRING The two ways to invoke TOSTRING are TOSTRING CX TOSTRING X FMT These invocations return a character string representing the value of the argument X When X is a vector indi vidual elements are separated by a string with the original or factory default value By original de fault G editing is used to convert real numbers I editing integers and blanks are trimmed from each ele ment of X both from the left and the right In addition trailing zeroes are trimmed from the fractional part of real X elements as well as a trailing decimal point The separating string trimming behaviour and default editing may be changed by calling TOSTRING SET X The item to be changed to a string X may be a scalar or a vector i e of rank 0 or 1 and of one of the following kinds default integer default real i e rea1 1 0 single precision double precision real i e rea1 1d0 default logical FMT Character string with an edit descriptor used to format each element of X The possible edit de scriptors are given in section 3 1 except that A and Aw can of course not be used When FMT is absent a default edit descriptor is used The default may be set by calling TOSTRING SET but the original or factory defaults are IO for inte
Download Pdf Manuals
Related Search