MATFOR 4 in Fortran

Document Sample
MATFOR 4 in Fortran Powered By Docstoc
					  Reference Guide


MATFOR 4
 in Fortran
2      MATFOR 4 in Fortran Reference Guide




Contents

    Contents ................................................................................................................................... 2


    Introduction ............................................................................................................................ 15

             Typographical Conventions ...............................................................................16
             Procedure Descriptions Convention ...................................................................17
             MATFOR Procedure Naming Convention.........................................................19
             MATFOR Parameters.........................................................................................21


    Essential Functions ............................................................................................................... 23

             mfArray manipulation ........................................................................................25
                mfIsEmpty, mfIsLogical, mfIsReal, mfIsComplex, mfIsNumeric ..............26
                mf .................................................................................................................28
                mfOut ...........................................................................................................30
                mfSize, msSize.............................................................................................32
                mfNDims......................................................................................................34
                mfShape .......................................................................................................36
                mfAll, msAll ................................................................................................38
                mfAny, msAny.............................................................................................40
                mfLength......................................................................................................42
             mfArray access ...................................................................................................43
                mfMatSub, mfS............................................................................................44
             Equivalency ........................................................................................................50
                msAssign......................................................................................................51
                msPointer .....................................................................................................52
                mfEquiv........................................................................................................54
             Memory Management ........................................................................................56
                    msReturnArray.............................................................................................57
                    msInitArgs, msFreeArgs ..............................................................................59
                                                                                                         Table of Contents            3


        Display................................................................................................................61
            msDisplay ....................................................................................................62
            msFormat .....................................................................................................64
        FileIO..................................................................................................................65
            mfLoad.........................................................................................................66
            mfLoad.m.....................................................................................................67
            mfLoadAscii ................................................................................................68
            mfLoadCsv...................................................................................................70
            msSave .........................................................................................................71
            mfSave.m .....................................................................................................72
            msSaveAscii.................................................................................................73
            msSaveCsv...................................................................................................74


Data Manipulation Functions ................................................................................................ 75

        Basic ...................................................................................................................76
            mfMax, msMax............................................................................................77
            mfMin, msMin .............................................................................................79
            mfProd, msProd ...........................................................................................81
            mfSort, msSort .............................................................................................83
            mfSortRows, msSortRows...........................................................................85
            mfSum, msSum............................................................................................87
        Fast Fourier Transform.......................................................................................89
            mfFFT, mfIFFT............................................................................................90
            mfFFT2, mfIFFT2........................................................................................92
            mfFFTShift, mfIFFTShift ............................................................................94
        Cartographic Functions ......................................................................................96
            msProj4, msProj4Inv....................................................................................97
              msCreateGeoidData ...................................................................................102
              msCreateGeoid3Data .................................................................................103
              msCreateCoastlineData..............................................................................104
              msCreateCoastline3Data............................................................................106
4      MATFOR 4 in Fortran Reference Guide


    Arithmetic & Relational Operators...................................................................................... 109

            Operator Precedence.........................................................................................110
            Arithmetic Operators ........................................................................................112
            Relational Operators.........................................................................................117


    Elementary Math Functions ................................................................................................ 121

            Trigonometry....................................................................................................123
                mfACos, msACos ......................................................................................124
                mfACosh, msACosh ..................................................................................125
                mfACot, msACot .......................................................................................126
                mfACoth, msACoth ...................................................................................127
                mfACsc, msACsc.......................................................................................128
                mfACsch, msACsch...................................................................................129
               mfASec, msASec .......................................................................................130
               mfASech, msASech ...................................................................................131
               mfASin, msASin ........................................................................................132
               mfASinh, msASinh ....................................................................................134
               mfATan, msATan........................................................................................135
               mfATan2, msATan2....................................................................................136
               mfATanh, msATanh....................................................................................137
               mfCos, msCos ............................................................................................138
               mfCosh, msCosh ........................................................................................139
               mfCot, msCot.............................................................................................140
               mfCoth, msCoth.........................................................................................141
               mfCsc, msCsc ............................................................................................142
               mfCsch, msCsch ........................................................................................143
               mfSec, msSec.............................................................................................144
               mfSech, msSech.........................................................................................145
               mfSin, msSin..............................................................................................146
               mfSinh, msSinh..........................................................................................147
               mfTan, msTan.............................................................................................148
               mfTanh, msTanh.........................................................................................149
            Exponential.......................................................................................................150
               mfExp, msExp............................................................................................151
               mfLog, msLog............................................................................................152
               mfLog10, msLog10....................................................................................153
               mfLog2, msLog2........................................................................................154
               mfPow2, msPow2 ......................................................................................156
                                                                                                      Table of Contents           5


          mfSqrt, msSqrt ...........................................................................................158
       Complex ...........................................................................................................159
          mfAbs, msAbs............................................................................................160
          mfAngle, msAngle.....................................................................................161
          mfComplex, msComplex ...........................................................................162
          mfConj, msConj.........................................................................................163
          mfImag, msImag ........................................................................................164
          mfReal, msReal..........................................................................................165
       Rounding and Remainder .................................................................................166
          mfCeil, msCeil ...........................................................................................167
          mfFix, msFix..............................................................................................169
          mfFloor, msFloor .......................................................................................171
          mfMod, msMod .........................................................................................173
          mfRem, msRem .........................................................................................175
             mfRound, msRound ...................................................................................177
             mfSign, msSign..........................................................................................179


Elementary Matrix-manipulation Functions....................................................................... 181

       Matrices ............................................................................................................183
          mfEye, msEye ............................................................................................184
          mfColon, msColon.....................................................................................185
          mfLinspace, msLinspace............................................................................186
          mfMagic, msMagic ....................................................................................187
          mfMeshgrid, msMeshgrid..........................................................................188
          mfOnes, msOnes ........................................................................................190
          mfRand, msRand........................................................................................191
          mfRepmat, msRepmat................................................................................192
          mfZeros, msZeros ......................................................................................194
       Matrix Manipulation.........................................................................................195
          mfDiag, msDiag.........................................................................................196
          mfFind, msFind..........................................................................................198
          mfLogical, msLogical ................................................................................200
          mfReshape, msReshape .............................................................................201
          mfTril .........................................................................................................202
          mfTriu ........................................................................................................204
6      MATFOR 4 in Fortran Reference Guide


    Matrix Functions .................................................................................................................. 207

             Matrix Analysis ................................................................................................209
                 mfDet .........................................................................................................210
                 mfNorm......................................................................................................211
                 mfRank.......................................................................................................213
                 mfTrace, msTrace ......................................................................................215
             Linear Equations...............................................................................................216
                 mfChol, msChol.........................................................................................217
                 mfCond ......................................................................................................219
                 mfInv..........................................................................................................221
                 mfRcond.....................................................................................................222
                 mfLu, msLu................................................................................................223
                 mfQr, msQr ................................................................................................225
                 mfMul ........................................................................................................227
                 mfRDiv, mfLDiv........................................................................................228
             Eigenvalues and singular values.......................................................................229
                 mfEig, msEig .............................................................................................230
                 mfHess, msHess.........................................................................................232
                 mfQz, msQz ...............................................................................................234
                 mfSchur, msSchur......................................................................................236
                 mfSvd, msSvd ............................................................................................238
             Factorization Utilities .......................................................................................240
                 mfBalance, msBalance...............................................................................241


    Sparse Array......................................................................................................................... 243

             Sparse Array .....................................................................................................245
                mfSpCreate ................................................................................................246
                msSpAdd....................................................................................................247
                msSpSet......................................................................................................249
                mfSpGet .....................................................................................................251
                mfSpGetM, mfSpGetN ..............................................................................253
                mfSpGetNNZ.............................................................................................255
                mfSpGetRow, mfSpGetCol........................................................................257
                mfSpGetVal................................................................................................259
                msSpGetIdx................................................................................................261
                msSpDisplay ..............................................................................................263
                msSpExport................................................................................................264
                mfSpImport ................................................................................................265
                                                                                                        Table of Contents           7


              mfSpEigs....................................................................................................266
              mfSpLDiv ..................................................................................................268
              mfSpMul ....................................................................................................270
              mfSpSize ....................................................................................................272
              mfSpToFull ................................................................................................274
              mfFullToSp ................................................................................................276
              mfSpy, msSpy ............................................................................................278


MATFOR Visualization Routines......................................................................................... 281

        Figure................................................................................................................289
            mfFigure, msFigure....................................................................................290
            msCloseFigure ...........................................................................................292
            mfFigureCount...........................................................................................293
        Window Frame .................................................................................................294
            mfWindowCaption, msWindowCaption....................................................295
            mfWindowSize, msWindowSize ...............................................................296
            mfWindowPos, msWindowPos..................................................................297
        Display..............................................................................................................298
            msGDisplay................................................................................................299
            msDrawNow ..............................................................................................300
            msViewPause .............................................................................................301
        Configuration....................................................................................................302
            msSaveConfig ............................................................................................303
            msLoadConfig............................................................................................304
        Recording .........................................................................................................305
            msRecordStart, msRecordEnd ...................................................................306
            msExportImage ..........................................................................................310
        Plot Creation and Control.................................................................................312
            mfSubplot, msSubplot................................................................................313
            msClearSubplot..........................................................................................316
            msHold.......................................................................................................317
            mfIsHold ....................................................................................................319
        Plot Annotation and Appearance......................................................................320
            mfTitle, mfXLabel, mfYLabel, mfZLabel.................................................321
            mfText, msText ..........................................................................................323
            mfAnnotation, msAnnotation ....................................................................324
            msShading..................................................................................................326
            msColorbar.................................................................................................328
8   MATFOR 4 in Fortran Reference Guide


           msColormap...............................................................................................330
           mfColormapRange, msColormapRange ....................................................333
           msDrawColormap ......................................................................................334
           msLegendBox ............................................................................................335
           msAddLegend ............................................................................................337
           msRemoveLegend, msRemoveAllLegend ................................................338
           mfBackgroundColor, msBackgroundColor ...............................................339
        Axis Control .....................................................................................................340
           mfAxis, msAxis .........................................................................................341
           msAxis2DMode .........................................................................................346
           msAxis3DMode .........................................................................................347
           msAxis2DDependency ..............................................................................348
           msAxis3DDependency ..............................................................................350
           mfAxis2DRange ........................................................................................352
           mfAxis3DRange ........................................................................................353
           msAxis2DPosition .....................................................................................354
           msAxisWall................................................................................................356
           msAxisGrid ................................................................................................358
        Object Manipulation.........................................................................................360
           msObjRotateX, msObjRotateY, msObjRotateZ ........................................361
           msObjRotateWXYZ ..................................................................................363
           mfObjScale, msObjScale ...........................................................................365
           mfObjPosition, msObjPosition ..................................................................367
           mfObjOrigin, msObjOrigin........................................................................369
           mfObjOrientation, msObjOrientation ........................................................371
           mfObjectModel, msObjectModel ..............................................................373
        Camera Manipulation .......................................................................................375
           msView ......................................................................................................376
            mfCamAngle, msCamAngle......................................................................379
            mfCamAzElRoll ........................................................................................380
            mfCamDistance..........................................................................................381
            mfCamProj, msCamProj ............................................................................382
            mfCamFocal...............................................................................................383
            mfCamZoom, msCamZoom ......................................................................384
            mfGetCamViewParam ...............................................................................385
            msSetCamViewParam................................................................................386
        Linear Graphs ...................................................................................................387
            mfPlot, msPlot............................................................................................388
                                                                                             Table of Contents           9


    mfPlot3, msPlot3........................................................................................391
    mfRibbon, msRibbon.................................................................................393
    mfTube, msTube ........................................................................................395
    mfStem, msStem ........................................................................................397
    mfBar .........................................................................................................400
    mfBarh .......................................................................................................403
    mfBar3 .......................................................................................................405
    mfBar3h .....................................................................................................407
Surface Graphs .................................................................................................409
    mfSurf, msSurf...........................................................................................410
    mfMesh, msMesh.......................................................................................412
    mfSurfc, msSurfc .......................................................................................414
    mfMeshc, msMeshc ...................................................................................416
    mfPColor, msPColor..................................................................................418
    mfFastPColor, msFastPColor.....................................................................420
    mfContour, msContour ..............................................................................422
    mfContour3, msContour3 ..........................................................................424
    mfSolidContour, msSolidContour .............................................................426
    mfSolidContour3, msSolidContour3 .........................................................428
    mfOutline, msOutline ................................................................................430
    mfIsoSurface, msIsoSurface ......................................................................432
    msGetIsoSurface ........................................................................................434
Slice Graphs .....................................................................................................435
    mfSliceXYZ, msSliceXYZ ........................................................................436
    mfSliceIJK, msSliceIJK.............................................................................439
    mfSlicePlane, msSlicePlane.......................................................................441
    msGetSliceXYZ.........................................................................................444
    msGetSlicePlane ........................................................................................445
Streamline Graphs ............................................................................................446
    mfStreamLine2, msStreamLine2 ...............................................................447
    mfStreamDashedLine2, msStreamDashedLine2 .......................................450
    mfStreamRibbon2, msStreamRibbon2 ......................................................452
    mfStreamTube2, msStreamTube2..............................................................454
    mfStreamArrow2, msStreamArrow2 .........................................................456
    mfStreamLine3, msStreamLine3 ...............................................................458
    mfStreamDashedLine3, msStreamDashedLine3 .......................................461
    mfStreamRibbon3, msStreamRibbon3 ......................................................463
    mfStreamTube3, msStreamTube3..............................................................465
10   MATFOR 4 in Fortran Reference Guide


            mfStreamArrow3, msStreamArrow3 .........................................................467
        Triangular Surface Graphs ...............................................................................470
            mfTriSurf, msTriSurf .................................................................................471
            mfTriMesh, msTriMesh .............................................................................473
            mfTriContour, msTriContour.....................................................................475
            mfPatch, msPatch.......................................................................................478
        Unstructured Grids ...........................................................................................480
            mfTetSurf, msTetSurf.................................................................................481
            mfTetMesh, msTetMesh.............................................................................484
            mfTetContour, msTetContour ....................................................................486
            mfTetIsoSurface, msTetIsoSurface ............................................................489
            mfTetSliceXYZ, msTetSliceXYZ..............................................................492
            mfTetSlicePlane, msTetSlicePlane.............................................................495
            msGetTetIsoSurface...................................................................................498
           msGetTetSliceXYZ....................................................................................499
           msGetTetSlicePlane ...................................................................................500
        Unstructured Streamlines .................................................................................501
           mfTriStreamLine, msTriStreamLine..........................................................502
           mfTriStreamDashLine, msTriStreamDashLine .........................................505
           mfTriStreamRibbon, msTriStreamRibbon.................................................507
           mfTriStreamTube, msTriStreamTube ........................................................509
           mfTriStreamArrow, msTriStreamArrow....................................................511
           mfTetStreamLine, msTetStreamLine .........................................................514
           mfTetStreamDashLine, msTetStreamDashLine.........................................517
           mfTetStreamRibbon, msTetStreamRibbon ................................................519
           mfTetStreamTube, msTetStreamTube........................................................521
           mfTetStreamArrow, msTetStreamArrow ...................................................523
        Unstructured Point Set......................................................................................526
           mfPoint, msPoint........................................................................................527
           mfDelaunay, msDelaunay, mfGetDelaunay, msGetDelaunay ...................529
           mfDelaunay3, msDelaunay3, mfGetDelaunay3, msGetDelaunay3 ..........532
        Velocity Vectors...............................................................................................534
           mfQuiver, msQuiver ..................................................................................535
           mfQuiver3, msQuiver3 ..............................................................................537
        Image ................................................................................................................540
           mfImage, msImage ....................................................................................541
           mfImRead ..................................................................................................543
           msImWrite .................................................................................................544
                                                                                          Table of Contents            11


Elementary 2D/3D Objects...............................................................................545
    mfCircle, msCircle.....................................................................................546
    mfSquare, msSquare ..................................................................................548
    mfMolecule, msMolecule ..........................................................................550
    mfFastMolecule, msFastMolecule.............................................................554
    mfSphere, msSphere ..................................................................................558
    mfCube, msCube........................................................................................560
    mfCylinder, msCylinder.............................................................................562
    mfCone, msCone........................................................................................565
    mfAxisMark, msAxisMark ........................................................................567
Property Setting ................................................................................................569
    msGSet.......................................................................................................570
    msDrawMaterial ........................................................................................573
    msDrawTexture..........................................................................................576
   mfIsValidDraw...........................................................................................578
   mfGetCurrentDraw ....................................................................................579
   msRemoveDraw.........................................................................................581
   msSetDrawName .......................................................................................582
Graphics Viewer Manipulation ........................................................................583
   msPrintPreview ..........................................................................................584
   msEditorDrawList......................................................................................586
   msEditorMaterial .......................................................................................587
   msEditorColormap.....................................................................................588
   msEditorTransform ....................................................................................589
   msEditorAxis .............................................................................................590
   msEditorColorbar.......................................................................................591
   msEditorBackground .................................................................................592
Simple GUI.......................................................................................................593
     msShowMessage........................................................................................594
     mfInputString .............................................................................................595
     mfInputValue..............................................................................................596
     mfInputVector ............................................................................................597
     mfInputMatrix............................................................................................598
     mfFileDialog, mfOpenFileDialog..............................................................600
     mfSaveFileDialog ......................................................................................602
     mfInputYesNo ............................................................................................603
12       MATFOR 4 in Fortran Reference Guide


     Extensions of MATFOR ....................................................................................................... 605

             Tecplot FileIO ..................................................................................................606
                mfTecOpenFile, msTecCloseFile...............................................................607
                mfTecReadTitle, mfTecWriteTitle .............................................................609
                msTecReadVarName, msTecReadBlock....................................................610
                mfTecReadVarCount, mfTecReadBlockCount ..........................................613
                msTecWriteVarNames................................................................................614
                msTecWriteIJKBlock, msTecWriteTriBlock, msTecWriteTetBlock .........615
             MATLAB Interface ..........................................................................................618
                mfDoMATLAB, msDoMATLAB..............................................................619
                mfMATLABServer, msMATLABServer...................................................621


     MATFOR GUI System........................................................................................................... 623

             Initialization......................................................................................................624
                  msUIInitialize ............................................................................................625
                  msUIMainLoop..........................................................................................626
             Property Setting ................................................................................................627
                  mfUIGetPropertyString..............................................................................628
                  msUISetPropertyString ..............................................................................629
                  mfUIGetPropertyInteger ............................................................................630
                  msUISetPropertyInteger ............................................................................631
                  mfUIGetPropertyDouble............................................................................632
                  msUISetPropertyDouble ............................................................................633
             Callback Setting................................................................................................634
                  msUISetOnClick ........................................................................................635
                  msUISetOnDoubleClick ............................................................................636
                  msUISetOnTabChanged ............................................................................637
                  msUISetOnResize ......................................................................................638
                  msUISetOnTextChanged ...........................................................................639
                  msUISetOnReturnPressed..........................................................................640
                  msUISetOnValueChanged .........................................................................641
                  msUISetOnScrollReleased.........................................................................642
             UI Components.................................................................................................643
                  MainForm ..................................................................................................644
                  MenuItem...................................................................................................645
                  MatforWindow...........................................................................................646
                  TabControl .................................................................................................647
                  Panel...........................................................................................................649
                                                                                                                  Table of Contents               13


                Button.........................................................................................................651
                Label ..........................................................................................................653
                RadioButton ...............................................................................................655
                CheckBox...................................................................................................656
                Edit.............................................................................................................658
                SpinEdit......................................................................................................659
                ListBox.......................................................................................................661
                ComboBox .................................................................................................663
                Slider ..........................................................................................................665
                ScrollBar ....................................................................................................667
                ProgressBar ................................................................................................669
                Image..........................................................................................................671
                Memo .........................................................................................................673


Index...................................................................................................................................... 675
14   MATFOR 4 in Fortran Reference Guide
                                                                       Chapter 1 Introduction     15



CHAPTER 1


Introduction
MATFOR has two main documentations: namely the MATFOR User’s Guide, and the
MATFOR Reference Guide.

MATFOR User’s Guide provides an overview on MATFOR concepts such as an
introduction to the mfArray with a focus on its structures and syntax, an introduction to using
linear algebra, and a quick overview on graphical procedures.

MATFOR Reference Guide provides a detailed description of the procedures available in
MATFOR. The descriptions include information such as what modules do, procedure syntax,
and input & output data types. Examples are included for most procedures. The Reference
Guide is frequently updated. Please download the latest copy from the MATFOR web page.

This reference guide was written for users who have some background knowledge in
programming with Fortran. For more information on Fortran, please refer to your compiler's
documentation.
16     MATFOR 4 in Fortran Reference Guide




     Typographical Conventions

     Before you start using this guide, it is important to understand the terms and
     typographical conventions used in the documentation.

     The following kinds of formatting in the text identify special information.




     Formatting Convention                          Type of Information

     Special Bold                                   Used to emphasize the importance of a
                                                    point or a title.

     Emphasis and codes                             Represent variable expressions such as
                                                    parameters, procedures and example
                                                    codes.
                                                                      Chapter 1 Introduction   17




Procedure Descriptions
Convention
The descriptions of MATFOR procedures follow a fixed format. The general format
is listed and described below.


Procedure Name

<Summary of procedure>




Module

<This section describes the modules to be included in order to use the procedure.>

e.g. use fml




Syntax

<This section describes most commonly used formats of the procedure. Generally,
MATFOR procedures accept mfArrays as input and output arguments. If an
argument type is not specified, it is an mfArray. Wherever it is convenient, other
data types are supported as input arguments and are noted in this section.

For example:

call msAxis('on') supports a string data type containing 'on' as input. The
input could also be an mfArray containing the string 'on'.>




Descriptions

<This section provides more detailed descriptions of the argument type and
application of the procedures.>
18     MATFOR 4 in Fortran Reference Guide



     Example

     <This section usually presents a piece of code that uses the current procedure and the
     result of the program.>




     See Also
     <This section suggests a list of related procedures.>
                                                             Chapter 1 Introduction   19




MATFOR Procedure Naming
Convention


               MATFOR procedures are provided in function formats and
               subroutine formats. Two types of prefixes classify MATFOR
               procedures: procedures with an “mf” prefix, and procedures with
               an “ms” prefix. Standard MATFOR function format procedures
               have the prefix “mf”, and subroutine format procedures have the
               prefix “ms”. By default, MATFOR procedures use mfArrays as
               input and output arguments.




               Procedures with an “mf” prefix

               Most MATFOR procedures that return a single argument as output
               are prefixed with “mf”. These procedures have a function format
               of the form:



               out = mfProcedure([mfArray, …]),

               where out is the output argument and [mfArray, …] is the input
               argument. For example, y = mfSin(x), l = mfIsEmpty(a).




  Functions that return only mfArray as the output argument will also have a
  corresponding subroutine of the format:



               call msProcedure(mfOut(y, …), x, …),

               where x and y are mfArrays. y is output, and x is input.

               For example, procedure y = mfSin(x) computes sin(x) and
20   MATFOR 4 in Fortran Reference Guide


                      returns the result in mfArray y. It has a corresponding subroutine
                      counterpart using the same input and output arguments with the
                      format:



                      call msSin(mfOut(y), x)




                      Procedures with an “ms” prefix

                      Procedures prefixed with "ms" are subroutines. There are three
                      types of subroutine formats — subroutines that do not return a
                      value, subroutines that return a single output, and subroutines that
                      accept multiple input and output arguments. Function mfOut is
                      used to specify the output arguments.



                      The subroutines have the following general format:

                      call msSubroutine(mfOut([mfArray]out1,…),
                      [mfArray]in1,…),

                      where [mfArray]out1,… is the list of output arguments and
                      [mfArray]in1,… is the list of input arguments. The input and
                      output arguments are optional.

                      Examples:

                      call msViewPause()

                      call msSurf(x, y, z)

                      call msSubplot(2, 2, 1)

                      call msCos(mfOut(y), x)

                      call msLU(mfOut(l, u), a)

                      call msMeshgrid(mfOut(a, b), m, n)
                                                                Chapter 1 Introduction   21




MATFOR Parameters



The table below lists the MATFOR parameters provided for your convenience.
Parameters mf() and MF_COL are mfArrays, while the rest of the parameters are
double precision data.




Parameter           Data Type       Descriptions

mf()                mfArray         Null mfArray

MF_COL              mfArray         Colon ‘:’ operator

MF_I                Complex(8)      (0.0, 1.0)

MF_PI               Real(8)         π

MF_EPS              Real(8)         Smallest positive number.

MF_INF              Real(8)         Positive infinity number.

MF_NAN              Real(8)         Not a number.

MF_E                Real(8)         Natural logarithm number.

MF_REALMAX          Real(8)         Largest representable number.

MF_REALMIN          Real(8)         Smallest representable number.
22   MATFOR 4 in Fortran Reference Guide
                                                                Chapter 2 Essential Functions   23



CHAPTER 2


Essential Functions
This chapter introduces the essential set of MATFOR routines. The procedures are
listed below:




mfArray Manipulation

mfIsEmpty                     Return true if mfArray is empty.

mfIsNumeric                   Return true if mfArray is numerical.

mfIsReal                      Return true if mfArray is real.

mfIsComplex                   Return true if mfArray is complex.

mfIsLogical                   Return true if mfArray is logical.

mf                            Convert Fortran variable to mfArray.

mfOut                         Specify a list of mfArrays as output of a procedure.

mfSize                        Return the total number of elements in an mfArray.

mfNDims                       Return the number of dimensions of an mfArray.

mfShape                       Return the number of elements in each dimension of an
                              mfArray.

mfAll                         Determination of all elements.

mfAny                         Determination of any element.

mfLength                      Retrieve the number of elements of the largest extent of
                              an mfArray.




Equivalency

msAssign                      Assign variable to mfArray.

msPointer                     Assign mfArray target to Fortran pointer.

mfEquiv                       Share memory storage between an mfArray and a
                              Fortran variable.
24    MATFOR 4 in Fortran Reference Guide




     Memory Management

     msReturnArray                  Set status flag of mfArray to temporary.

     msInitArgs                     Reserve mfArray for computation within procedures.

     msFreeArgs                     Free mfArray for internal housekeeping.




     Display

     msDisplay                      Display mfArray data on a console window.

     msFormat                       Specify displaying format of mfArray.




     FileIO

     mfLoad                         Load binary file into mfArray.

     mfLoad.m                       Load MATFOR binary file into MATLAB workspace.

     mfLoadAscii                    Load ASCII file into mfArray.

     mfLoadCsv                      Load a CSV file into mfArray.

     msSave                         Save mfArray as binary file.

     msSave.m                       Save MATLAB matrix into a MATFOR binary file.

     msSaveAscii                    Save mfArray as ASCII file.

     msSaveCsv                      Save mfArray into a CSV file.
                       Chapter 2 Essential Functions   25




mfArray manipulation
26       MATFOR 4 in Fortran Reference Guide



     mfIsEmpty, mfIsLogical, mfIsReal, mfIsComplex,

     mfIsNumeric
     Return logical true or false for mfArray inquiry.


     Module
     fml


     Syntax
     l   =   mfIsEmpty(a)
     l   =   mfIsLogical(a)
     l   =   mfIsReal(a)
     l   =   mfIsComplex(a)
     l   =   mfIsNumeric(a)



     Descriptions
     Functions mfIsEmpty, mfIsLogical, mfIsReal, mfIsComplex, and
     mfIsNumeric are a set of mfArray inquiry functions. These functions compare mfArrays or
     inquire the status of an mfArray and return a logical true or false. They can be directly
     applied in a control if there is a statement. For example, if (mfIsEmpty(a))...

     h = mfIsEmpty(a) returns a logical true if mfArray a is empty, i.e. null, and logical
     false otherwise.

     h = mfIsLogical(a) returns a logical true if mfArray a is logical and logical false
     otherwise.

     h = mfIsReal(a) returns a logical true if mfArray a is real and logical false otherwise.

     h = mfIsComplex(a) returns a logical true if mfArray a is complex and logical false
     otherwise.

     h = mfIsNumeric(a) returns a logical true if mfArray a is numeric and logical false
     otherwise.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray):: a, b, c, d, e
     ! Construct an empty mfArray.
                                                 Chapter 2 Essential Functions   27

a = mf()
!Writes a output message if a is empty.
if (mfIsEmpty(a)) write (*,*) 'a is empty'
!   Construct three numerical mfArrays.
b   = 5.2
c   = 5.2
d   = (2, 2)
!Writes output message if b is real, b and c are equal, or d is
!numeric or complex
if (mfIsReal(b))    write (*,*) 'b is real'
if (mfIsNumeric(c)) write (*,*) 'c is numeric'
if (mfIsComplex(d)) write (*,*) 'd is complex'
! Construct a logical mfArray.
e = mfMagic(3) > 5
!Writes output message if e is logical.
if (mfIsLogical(e)) write (*,*) 'e is logical'
!Deallocate mfArrays.
call msFreeArgs(a, b, c, d, e)
end program example


Result
a is empty
 b is real
 c is numeric
 d is complex
 e is logical


See Also
28      MATFOR 4 in Fortran Reference Guide



     mf
     Convert Fortran data to mfArray.


     Module
     fml


     Syntax
     a = mf([b])



     Descriptions
     Procedure mf converts Fortran data types into mfArrays. This is useful in procedure calls
     where MATFOR restricts the input argument to mfArray type.

     a = mf()
     Return an empty mfArray.

     a = mf(b)
     Convert type real(8), complex(8), integer or character strings argument b into an mfArray and
     return the resulting mfArray to argument a.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: lt
     real(8) :: A(3,3)
     ! Initialize A by using the random_number
     ! procedure provided by Fortran.
     call random_number(A)
     ! Display the content of A by using MATFOR
     ! display() procedure.
     call msDisplay(mf(A), 'A')
     ! Extract the lower triangular of A by
     ! using the mfTril() procedure provided by
     ! MATFOR. Enclose A using mf().
     lt = mfTril(mf(A))
     call msDisplay(lt, 'Lower Triangular of A')
     call msFreeArgs(lt)
     end program example


     Result
     A =
                             Chapter 2 Essential Functions   29


  0.0000   0.6669   0.3354
  0.0255   0.9631   0.9153
  0.3525   0.8383   0.7959

Lower Triangular of A =

  0.0000   0.0000   0.0000
  0.0255   0.9631   0.0000
  0.3525   0.8383   0.7959


See Also
30      MATFOR 4 in Fortran Reference Guide



     mfOut
     Specify a list of mfArrays as output of a function.


     Module
     fml


     Syntax
     mfOut(a, b, c, ...)



     Descriptions
     Procedure msOut specifies a list of mfArrays as the output of a subroutine. It differentiates
     the output arguments from the input arguments in a procedure call. Note that procedure
     mfOut encloses only mfArrays.

     For example, you can use function msFind to retrieve the row indices, column indices, and
     non-zero values of an mfArray as shown below:
     mfFind(mfOut(i, j, v), x)
     The procedure returns three mfArrays in this usage. To get the three mfArrays i, j, and v, you
     must enclose them with mfOut in your procedure call. This automatically triggers procedure
     msFind to return the specified mfArrays.



     Example

     Code
     program example
            use fml
            implicit none
            type(mfArray) :: a, i, j
            ! Construct a 3-by-3 random mfArray
            a = mfRand(3)
         ! Find the element which is grater than 0.5 in mfArray a and
         ! output its index vector
         call msFind(mfOut(i, j), a > 0.5d0)
         call msDisplay(a, "a", i, "i", j, "j")
     end program


     Result
     a =

        0.9997      0.3917      0.6628
        0.8225      0.7557      0.7853
        0.4772      0.1380      0.5110

      i =
       1
           Chapter 2 Essential Functions   31

 2
 2
 1
 2
 3
j =
 1
 1
 2
 3
 3
 3


See Also
32      MATFOR 4 in Fortran Reference Guide



     mfSize, msSize
     Return total number of elements in an mfArray.


     Module
     fml


     Syntax
     s = mfSize(a)
     b = mfSize(a, IDIM)

     call msSize(mfOut(m1, m2, ..., mn), a)



     Descriptions
     Procedure mfSize returns the total number of elements in an mfArray.

     s = mfSize(a) returns the number of elements in a.

     b = mfSize(a, IDIM) returns the length of the dimension specified by scalar IDIM.

     call msSize(mfOut(m1, m2, ..., mn), a) returns the lengths of the first n
     dimensions of a.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: a
     integer :: s
     a = mfRand(4,3)
     s = mfSize(a)
     call msDisplay(a, 'mfRand(4,3)', mf(s), 'mfSize(a)')

     s = mfSize(a, 1)
     call msDisplay(mf(s), 'mfSize(a, 1)')
     s = mfSize(a, 2)
     call msDisplay(mf(s), 'mfSize(a, 2)')
     call msFreeArgs(a)
     end program example


     Result
     mfRand(4,3) =
                             Chapter 2 Essential Functions   33


  0.7620   0.6455   0.6531
  0.7638   0.2717   0.7014
  0.0894   0.9876   0.4027
  0.3090   0.3181   0.6760

mfSize(a) =
 12
mfSize(a, 1) =
 4
mfSize(a, 2) =
 3


See Also
mfNDims, mfLength
34      MATFOR 4 in Fortran Reference Guide



     mfNDims
     Return number of dimensions of an mfArray.


     Module
     fml


     Syntax
     r = mfNDims(a)



     Descriptions
     Procedure mfNDims returns the number of dimensions of an mfArray. Each mfArray has a
     minimum value of 2. (i.e. scalar, vector and matrix mfArrays have mfNDims = 2)



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: a, b
     integer :: c
     ! Scalar
     a = 3
     b = mfNDims(a)
     call msDisplay(b, 'Scalar mfArray has mfNDims')
     ! Vector
     a = (/1, 2, 3/)
     write(*,*) 'Vector mfArray has mfNDims ='
     write(*,'(/,I3,/)') mfNDims(a)
     ! Matrix
     a = mfMagic(3)
     b = mfNDims(a)
     call msDisplay(b, 'Matrix mfArray has mfNDims')
     ! Three-dimensional mfArray
     a = mfReshape(mfColon(1,8), (/2,2,2/))
     b = mfNDims(a)
     call msDisplay(b, 'Three-dimensional mfArray has mfNDims')
     ! Deallocates mfArray
     call msFreeArgs(a, b)
     end program example


     Result
     Scalar mfArray has mfNDims =          2
      Vector mfArray has mfNDims =          2
      Matrix mfArray has mfNDims =          2
      Three-dimensional mfArray has mfNDims =                    3
                   Chapter 2 Essential Functions   35



See Also
mfSize, mfLength
36       MATFOR 4 in Fortran Reference Guide



     mfShape
     Return number of elements in each dimension of an mfArray.


     Module
     fml


     Syntax
     s = mfShape(x)



     Descriptions
     s = mfShape(x)
     • Procedure mfShape returns an integer array whose size is equal to the dimension of the
         mfArray.
     •   s is an integer vector, while argument x is an mfArray.
     •   Note that scalars, vectors and matrix mfArrays have a rank of 2.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, s
     ! Scalar mfArray
     x = 2
     s = mfShape(x)
     call msDisplay( x, 'x', s, 'mfShape(x)')
     ! Vector mfArray
     x = (/2, 3/)
     s = mfShape(x)
     call msDisplay( x, 'x', s, 'mfShape(x)')
     ! Matrix mfArray
     x = mfMagic(2)
     s = mfShape(x)
     call msDisplay( x, 'x', s, 'mfShpae(x)')
     ! Three-dimensional mfArray
     x = mfRand(2, 2, 2)
     s = mfShape(x)
     call msDisplay( x, 'x', s, 'mfShape(x)')
     ! Deallocate mfArray
     call msFreeArgs(x, s)
     end program example


     Result
                     Chapter 2 Essential Functions   37

x =
 2
Shape(x) =
 1 1
x =
 2 3
Shape(x) =
 1 2
x =
 1 3
 4 2
Shape(x) =
 2 2
x (:,:,1) =

  0.0341    0.7507
  0.8502    0.1210

x (:,:,2) =

  0.2173    0.2558
  0.4833    0.7332

Shape(x) =
 2 2 2


See Also
mfReshape
38       MATFOR 4 in Fortran Reference Guide



     mfAll, msAll
     Return logical true if all elements of mfArray are nonzero.


     Module
     fml


     Syntax
     l = mfAll(a[, IDIM])



     Descriptions
     Function mfAll determines if all elements of an mfArray are non-zero.

     l = mfAll(x)
     • l is a logical mfArray, containing logical element(s).
     •   If x is a vector, mfAll returns a scalar containing logical 1 if all elements of x are
         non-zero, and logical 0 otherwise.
     •   If x is a matrix, mfAll is applied to each column of x, returning a row vector
         containing 0's or 1's.

     l = mfAll(x, IDIM)            operates on the dimension of x specified by IDIM.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, y, z
     logical :: b
     x = mfMagic(3)
     ! Check if all elements of x are greater than 2.
     b = mfAll(x>2)
     y = mfAll(x>2, 1)
     z = mfAll(x>2, 2)

     call msDisplay(mf(b), 'mfAll(x > 2)', y, 'mfAll(x>2, 1)', z, 'mfAll(x>2,
     2)')

     ! Deallocates mfArrays
     call msFreeArgs(x, y, z)
     end program example
                 Chapter 2 Essential Functions   39


Result
mfAll(x > 2) =
 0
mfAll(x, 1) =
 1 0 0
mfAll(x, 2) =
 0
 1
 0


See Also
mfAny
40       MATFOR 4 in Fortran Reference Guide



     mfAny, msAny
     Return logical true if any element of mfArray is nonzero.


     Module
     fml


     Syntax
     l = mfAny(x[, IDIM])



     Descriptions
     Function mfAny determines if any element of an mfArray is nonzero.

     l = mfAny(x)
     • l is a logical mfArray, containing logical elements.
     •   If x is a vector, mfAny returns a scalar containing logical 1 if any element of x is
         nonzero, and logical 0 otherwise.
     •   If x is a matrix, mfAny is applied to each column of x, returning a row vector
         containing 0's and 1's.

     l = mfAny(x, IDIM) operates on the dimension of x specified by IDIM.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, y, b
     x = mfMagic(3)
     ! Check if any element of x is more than 5.
     b = mfAny(x>7)
     call msDisplay(x, 'x', b, 'mfAny(x > 7)')
     y = mfAny(x>7, 1)
     call msDisplay(y, 'mfAny(x>7, 1)')
     y = mfAny(x>7, 2)
     call msDisplay(y, 'mfAny(x>7, 2)')
     ! Deallocates mfArrays
     call msFreeArgs(x, y)
     end program example


     Result
     x =
                  Chapter 2 Essential Functions   41

 8 1 6
 3 5 7
 4 9 2
mfAny(x > 7) =
 1
mfAny(x>7, 1) =
 1 1 0
mfAny(x>7, 2) =
 1
 0
 1


See Also
mfAll
42      MATFOR 4 in Fortran Reference Guide



     mfLength
     Retrieve number of elements of the largest extent of an mfArray.


     Module
     fml


     Syntax
     l = mfLength(a)



     Descriptions
     Procedure mfLength returns the largest extent of an mfArray.

     l = mfLength(a) returns an integer scalar containing the largest extent of mfArray a. If a is
     matrix, mfLength(a)returns mfMax(mfShape(a)).



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: a
     integer :: l
     a = mfOnes(2, 5)
     l = mfLength(a)
     call msDisplay(a, 'a', mf(l), 'mfLength(a)')
     call msFreeArgs(a)
     end program example


     Result
     a =
       1 1 1      1 1
       1 1 1      1 1
      mfLength(a) =
       5


     See Also
     mfSize, mfNDims
                 Chapter 2 Essential Functions   43




mfArray access
44      MATFOR 4 in Fortran Reference Guide



     mfMatSub, mfS
     Retrieve rows and columns of elements from vector or matrix mfArray.


     Module
     fml


     Syntax
     sub_Array = mfMatSub(A, row, column)



     Descriptions
     Procedure mfMatSub retrieves elements from an mfArray. The arguments (except the first
     one) specify the subscripts of the elements

     Notice that MATFOR also provides the abbreviated name mfS for this procedure.

     For example, if A is a vector mfArray, mfMatSub(A, 1.to.100.step.2)would return a vector
     containing the 1st, 3rd, 5th, ..., and 99th elements of A.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: x, y, z
     integer :: i
     x = reshape((/(i, i= 1, 24)/), (/2, 3, 4/))
     call msDisplay(x, 'x')
     ! Get x <= 12
     y = mfS(x, x <= 12)
     call msDisplay(y, 'mfS(x, x <= 12)')
     ! y = x(1:24) using 1x24 replace 2x3x4
     y = mfS(x, 1.to.24)
     call msDisplay(y, 'mfS(x, 1.to.24)')
     ! y = x(1:2, 1:12) using 2x12 replace 2x3x4
     y = mfS(x, 1.to.2, 1.to.12)
     call msDisplay(y, 'mfS(x, 1.to.2, 1.to.12)')
     ! y = x(1:2, 1:12:3)
     y = mfS(x, 1.to.2, 1.to.12.step.3)
     call msDisplay(y, 'mfS(x, 1.to.2, 1.to.12.step.3)')
     ! y = x(24:1)
     y = mfS(x, MF_COL)
     call msDisplay(y, 'mfS(x, MF_COL)')
     ! y = x(1, 2, 3)
     y = mfS(x, 1, 2, 3)
                                                 Chapter 2 Essential Functions   45

call msDisplay(y, 'mfS(x, 1, 2, 3)')
! Get element using arbitrary index
y = mfS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))
call msDisplay(y, 'mfS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))')
! Set element in y which <= 12 and >= 6 to   0
y = x
!call msAssign(mfS(y, y <= 12 .and. y >= 6   ), 0)
call msAssign(mfS(y, mfAND(y <= 12,y >= 6)   ), 0)
call msDisplay(y, 'msAssign(mfS(y, y <= 12   .and. y >= 6), 0)')
! y(1:24) = 0 using 1x24 replace 2x3x4
y = x
call msAssign(mfS(y, 1.to.24), 0)
call msDisplay(y, 'msAssign(mfS(y, 1.to.24), 0)')
! y(1:2, 1:12) = 0 using 1x24 replace 2x3x4
y = x
call msAssign(mfS(y, 1.to.2, 1.to.12), 0)
call msDisplay(y, 'msAssign(mfS(y, 1.to.2, 1.to.12), 0)')
! y(1:2, 1:12:3) = 0 using 1x24 replace 2x3x4
y = x
call msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)
call msDisplay(y, 'msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)')
! y(1:2, 1:3:2, 1:4:3) = reshape((/(i, i = 31, 38)/), (/2, 2, 2/))
y = x
z = reshape((/(i, i = 31, 38)/), (/2, 2, 2/))
call msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)
call msDisplay(y, 'msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3),
z)')
! y(24:1) = .t.(/(i, i= 25, 48)/)
y = x
call msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))
call msDisplay(y, 'msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))')
! y(1, 2, 3) = 60
y = x
call msAssign(mfS(y, 1, 2, 3), 60)
call msDisplay(y, 'msAssign(mfS(y, 1, 2, 3), 60)')
! Set element using arbitrary index
y = x
z = reshape((/(i, i = 101, 112)/), (/2, 2, 3/))
call msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/))), z)
call msDisplay(y, 'msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4,
1, 3/))), z)')
call msFreeArgs(x, y)
end program example


Result
x(:,:,1) =
 1 3 5
 2 4 6
x(:,:,2) =
  7 9 11
  8 10 12
x(:,:,3) =
 13 15 17
 14 16 18
46     MATFOR 4 in Fortran Reference Guide

     x(:,:,4) =
      19 21 23
      20 22 24
     mfS(x, x <= 12) =
       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
     mfS(x, 1.to.24) =
     column 1 to 19 ...
       1 2   3 4 5    6             7    8   9 10 11 12 13 14 15 16   17 18 19
     column 20 to 24
       20 21 22 23 24
     mfS(x, 1.to.2, 1.to.12) =
       1   3    5    7 9 11 13 15 17 19 21 23
       2   4    6    8 10 12 14 16 18 20 22 24
     mfS(x, 1.to.2, 1.to.12.step.3) =
       1   7 13 19
       2   8 14 20
     mfS(x, MF_COL) =
       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
     mfS(x, 1, 2, 3) =
      15
     mfS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,1) =
      24 20
                                                Chapter 2 Essential Functions   47

23 19
mfS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,2) =
6 2
5 1
mfS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,3) =
18 14
17 13
msAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,1) =
1 3 5
2 4 0
msAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,2) =
0 0 0
0 0 0
msAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,3) =
13 15 17
14 16 18
msAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,4) =
19 21 23
20 22 24
msAssign(mfS(y, 1.to.24), 0)(:,:,1) =
0 3 5
2 4 6
msAssign(mfS(y, 1.to.24), 0)(:,:,2) =
 7 9 11
 8 10 12
msAssign(mfS(y, 1.to.24), 0)(:,:,3) =
13 15 17
14 16 18
msAssign(mfS(y, 1.to.24), 0)(:,:,4) =
19 21 23
20 22 24
msAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,1) =
0 0 0
0 0 0
msAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,2) =
0 0 0
0 0 0
msAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,3) =
0 0 0
0 0 0
msAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,4) =
0 0 0
0 0 0
msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,1) =
0 3 5
48    MATFOR 4 in Fortran Reference Guide

     0 4 6
     msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,2) =
      0 9 11
      0 10 12
     msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,3) =
      0 15 17
      0 16 18
     msAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,4) =
      0 21 23
      0 22 24
     msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,1) =
     31    3 33
     32    4 34
     msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,2) =
      7 9 11
      8 10 12
     msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,3) =
     13 15 17
     14 16 18
     msAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,4) =
     35 21 37
     36 22 38
     msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,1) =
     25 27 29
     26 28 30
     msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,2) =
     31 33 35
     32 34 36
     msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,3) =
     37 39 41
     38 40 42
     msAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,4) =
     43 45 47
     44 46 48
     msAssign(mfS(y, 1, 2, 3), 60)(:,:,1) =
     1 3 5
     2 4 6
     msAssign(mfS(y, 1, 2, 3), 60)(:,:,2) =
      7 9 11
      8 10 12
     msAssign(mfS(y, 1, 2, 3), 60)(:,:,3) =
     13 60 17
     14 16 18
     msAssign(mfS(y, 1, 2, 3), 60)(:,:,4) =
     19 21 23
                                                 Chapter 2 Essential Functions   49

 20 22 24
 msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/))), z)(:,:,1)
=
 108       3 106
 107       4 105
 msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/))), z)(:,:,2)
=
  7 9 11
  8 10 12
 msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/))), z)(:,:,3)
=
 112       15 110
 111       16 109
 msAssign(mfS(y, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/))), z)(:,:,4)
=
 104       21 102
 103       22 101


See Also
50    MATFOR 4 in Fortran Reference Guide




     Equivalency
                                                                 Chapter 2 Essential Functions    51



msAssign
Assign the values of an mfArray to another.


Module
fml


Syntax
call msAssign(a, b)


Descriptions
ProceduremsAssign(a, b)assigns the values of mfArray b to mfArray a. This is
equivalent to the statement a = b.

Note that when you assign one mfArray to another mfArray, there is no memory copying
involved. However, when you assign an mfArray to a Fortran data type, the Fortran compiler
accomplishes the task by creating a temporary storage space in the stack memory. When the
array size involved is large, stack overflow may occur. To avoid large data, it is advisable to
use msAssign(a, F)or a = mf(F)instead of a = F.

Example

Code
program example
use fml
implicit none
type (mfArray) :: a,b
real(8) :: F(2,5)
call   random_number(F)
call   msAssign(a, F) !Avoids stack memory copy.
call   msAssign(b,a)
call   msDisplay(a, 'a',b,'b')
!Deallocate mfArray
call msFreeArgs(a)
end program example

Result
a =
   0.0000      0.3525     0.9631      0.3354      0.7959
   0.0255      0.6669     0.8383      0.9153      0.8327

 b =
   0.0000      0.3525     0.9631      0.3354      0.7959
   0.0255      0.6669     0.8383      0.9153      0.8327


See Also
Shape, Size, mfSize
52      MATFOR 4 in Fortran Reference Guide



     msPointer
     Assign pointer to mfArray.


     Module
     fml


     Syntax
     call msPointer(a, P)

     a : mfArray
     P : real(8) or complex(8) pointer



     Descriptions
     Procedure msPointer assigns a real(8) or complex(8) pointer to a target mfArray.

     call msPointer(a, P)
     • Procedure msPointer associates pointer P and mfArray a, i.e the memory space
         occupied by mfArray a becomes the target of pointer P. Pointer P automatically assumes
         the shape of mfArray a.

     Warning:
     Deallocating pointer P would lead to exception error.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: a, z
     real(8), pointer :: pd(:,:)
     complex(8), pointer :: pz(:,:)
     a = mfOnes(3, 3)
     z = mfComplex(a, a)
     call msDisplay(a, 'a')
     ! pd targets a
     call msPointer(a, pd)
     ! a(3, 3) has been set to 5.0.
     pd(3, 3) = 5.0
     call msDisplay(a, 'a')
     call msDisplay(z, 'z')
     ! pz targets z
     call msPointer(z, pz)
                                                Chapter 2 Essential Functions   53

! z(3, 3) has been set to 5.0+5.0i
pz(3, 3) = cmplx(5.0, 5.0)
call msDisplay(z, 'z')
!Deallocate mfArray
call msFreeArgs(a, z)
end program example


Result
a =
 1 1 1
 1 1 1
 1 1 1
a =
 1 1 1
 1 1 1
 1 1 5
z =

1.0000 +1.0000i   1.0000 +1.0000i    1.0000 +1.0000i
1.0000 +1.0000i   1.0000 +1.0000i    1.0000 +1.0000i
1.0000 +1.0000i   1.0000 +1.0000i    1.0000 +1.0000i

z =

1.0000 +1.0000i   1.0000 +1.0000i    1.0000 +1.0000i
1.0000 +1.0000i   1.0000 +1.0000i    1.0000 +1.0000i
1.0000 +1.0000i   1.0000 +1.0000i    5.0000 +5.0000i


See Also
mfEquiv
54       MATFOR 4 in Fortran Reference Guide



     mfEquiv
     Share memory storage between an mfArray and a Fortran variable.


     Module
     fml


     Syntax
     a = mfEquiv(T)
     a = mfEquiv(Z)

     a : mfArray
     T : real(8) array or scalar
     Z : complex(8) array or scalar



     Descriptions
     Procedure mfEquiv is provided for sharing memory storage between a Fortran variable and
     an mfArray.

     a = mfEquiv(T)
     • Procedure mfEquiv returns a restricted mfArray a which shares the same memory
         location as Fortran variable T.
     •   Variable T can be 1) real(8) array or scalar or 2) complex(8) array or scalar.
     •   Use mfEquiv when you have an existing Fortran array. The Fortran variable must not be
        a temporary variable. It must be explicitly declared. The following operation is invalid:
     a = mfEquiv(dble(A))
     ! dble(A) returns a temporary variable.

     Restrictions:
     MATFOR enforces a few restrictions on the operations of an mfArray when it is constructed by
     using procedure mfEquiv.
     • Procedure msFreeArgs releases and disassociates the restricted mfArray from the
         Fortran variable but does not deallocate the memory space occupied by the Fortran
         variable.
     •   Operations that change the shape, data type or rank of the restricted mfArray are invalid.
     •   The restricted mfArray cannot be used as a returned argument in procedures (functions
         and subroutines). e.g.

     function(A, B) result (out)
     real (8) :: A(3,4)
     out = mfEquiv(A)
     ! This is illegal, out will be null.
                                                                 Chapter 2 Essential Functions   55


•    Deallocating the associated Fortran array invalids the mfArray.



Example

Code
program example
use fml
implicit none
type (mfArray) :: t
real(8) :: A(3,3)
integer :: i
A = dble(ReShape( (/(i,i=1,9)/), (/3,3/)) )
t = mfEquiv(A)
call msDisplay(t, 't')
call msDisplay(mf(A), 'A')
A = A - 1
call msDisplay(t, 't')
call msDisplay(mf(A), 'A')
! If you use the msFreeArgs routine on t,
! t is Deallocated, but A is still valid and usable.
call msFreeArgs(t)
call msDisplay(mf(A), 'A')
end program example


Result
t =
    1 4 7
    2 5 8
    3 6 9
A =
    1 4 7
    2 5 8
    3 6 9
t =
    0 3 6
    1 4 7
    2 5 8
A =
    0 3 6
    1 4 7
    2 5 8
A =
    0 3 6
    1 4 7
    2 5 8


See Also
msPointer
56    MATFOR 4 in Fortran Reference Guide




     Memory Management
                                                                 Chapter 2 Essential Functions    57



msReturnArray
Set status flag of mfArray to temporary.


Module
fml


Syntax
call msReturnArray(a)



Descriptions
Procedure msReturnArray(a)sets the status flag of an mfArray to temporary. This
procedure should be added to the end of functions that use mfArrays to return values. It
ensures that temporary mfArrays created by functions or subroutines are deallocated,
preventing memory leakage.

For example, when you develop a function foo that returns mfArray t as below, it is
recommended to add the statement call msReturnArray(t)at the end of the function:

function foo(A) return (t)
implicit none
integer :: A
type (mfArray) :: t
   ! program codes
   -------------------
   -------------------
call msReturnArray(t)
return
end function foo

The statement sets the status property of the mfArray to temporary. MATFOR releases such
temporary mfArrays automatically.

More Details:
The mfArray is a dynamically allocated data object. It is good practice in Fortran to release
dynamically allocated memory space once you no longer need it. Due to the above principle, you
should clear all temporary mfArrays to prevent memory leakage.

A function developed for end-users in Fortran can be used in many possible ways. For example, a
user could write a = foo(x)or they may use it as an input to another function, as in b =
gee(foo(x)).

In the second case, the function foo returns a temporary data object. When the returned data
object is an mfArray, it should be released from memory to prevent memory leakage. MATFOR
procedures release such temporary mfArrays automatically. By specifying the statement call
msReturnArray(a, b, c, ...)at the end of your function, you set the status flag of the
58      MATFOR 4 in Fortran Reference Guide


     mfArray to temporary. MATFOR automatically clears mfArrays once it encounters temporary
     flags.



     Example

     Code
     program example
     use fml
     implicit none
     external foo
     type(mfArray) :: x, foo
     x = foo(3)
     call msDisplay(x,'X')
     call msFreeArgs(x)
     end program example
     function foo(A) result(t)
     use fml
     implicit none
     integer:: A
     type(mfArray)::t
     t = mfRand(A,A)
     call msReturnArray(t)
     return
     end function


     Result
     X =

        0.2408     0.3788      0.8362
        0.4143     0.7158      0.8167
        0.9859     0.5995      0.3267


     See Also
     msInitArgs, msFreeArgs
                                                                 Chapter 2 Essential Functions    59



msInitArgs, msFreeArgs
Set status of mfArrays in procedure development.


Module
fml


Syntax
call msInitArgs(a, b, ...)
call msFreeArgs(a, b, ...)



Descriptions
Procedures msInitArgs and msFreeArgs are used in procedure development to set the
status flags of mfArrays.

Procedure msInitArgs stops temporary mfArrays from being released by MATFOR.
Procedure msFreeArgs reverses the 'lock' action performed by procedure msInitArgs,
so that temporary mfArrays are automatically released by MATFOR. For example, when
developing a subroutine foo that accepts mfArrays a, b, and c, as below, it is
recommended to enclose the program code with call msInitArgs(a, b, c), and call
msFreeArgs(a, b, c):

Subroutine foo(a, b, c)
implicit none
type (mfArray) :: a, b, c
call msInitArgs(a, b, c)
   ! program codes
   -------------------
   -------------------
call msFreeArgs(a, b, c)
return
end Subroutine foo

More Details:
The mfArray is a dynamically allocated data object. It is good practice in Fortran to release
dynamically allocated memory space once you no longer need it. Due to the above principle,
MATFOR automatically releases all temporary mfArrays once they are passed into MATFOR
procedures. A temporary mfArray is created when you use a function without assigning its output
to a variable. For example, in the statement

call bar(foo(x)),

foo(x) returns a temporary mfArray used as input to the subroutine bar(). Such temporary
mfArrays have their status flag sets to temporary if the function developer added the statement
below at the end of the function:
60      MATFOR 4 in Fortran Reference Guide


     call msReturnArray(a)

     MATFOR automatically clears mfArrays with temporary flag 'on' in MATFOR procedures. To
     prevent temporary mfArrays from being released in subroutine code, the procedure
     msInitArgs()is used to stop MATFOR from releasing the specified mfArrays.
     msFreeArgs()is added at the end of the subroutine to enable the memory clearing action of
     MATFOR.

     In conclusion, use the procedure pair msInitArgs()and msFreeArgs()to enclose program
     code in your subroutine.



     Example

     Code
     program example
     use fml
     implicit none
     external foo
     type(mfArray) :: x, foo
     x = foo(3)
     call RandSum(x,foo(3),foo(3))
     call msDisplay(x,'X')
     call msFreeArgs(x)
     end program example
     subroutine RandSum(a,b,c)
     use fml
     implicit none
     type(mfArray)::a,b,c
     call msInitArgs(a,b,c)
     a = a + b + c
     call msFreeArgs(b,c)
     end subroutine
     function foo(A) result(t)
     use fml
     implicit none
     integer:: A
     type(mfArray)::t
     t = mfRand(A,A)
     call msReturnArray(t)
     return
     end function


     Result
     X =

        1.7950     1.5861      1.9579
        0.9590     1.2635      1.8789
        2.0209     1.4347      2.0302


     See Also
     msRelease, msReturnArray
          Chapter 2 Essential Functions   61




Display
62       MATFOR 4 in Fortran Reference Guide



     msDisplay
     Display mfArray data.


     Module
     fml


     Syntax
     call msDisplay(x[, name])
     call msDisplay(x, name[, x1 , name1, ...])



     Descriptions
     ProceduremsDisplay shows the content of mfArrays on a console window.
     call msDisplay(x) call msDisplay(x, name)
     • Displays the content of mfArray x.
     •   Argument name is a character string specifying the accompanying output message. E.g.
         call msDisplay(x, 'x')prints 'x =' on the console window followed by the content
         of mfArray x. When argument name is not specified, msDisplay prints the caption
         'ans =' followed by the content of mfArray.
     • You can specify the number of display digits by using procedure msFormat.
     call msDisplay(x, name) call msDisplay(x, name, x1, name1,...)
     • Display the content of the specified mfArrays with captions specified by the
         corresponding name strings. When multiple mfArrays are displayed, the arguments must
         be specified in pairs, i.e., one mfArray accompanied by one name string. For example,
         call msDisplay(x, 'x', y, 'y', z, 'z').
     •   The number of mfArrays displayed in a single procedure call is limited to thirty-two.



     Example

     Code
     program example
     use fml
     implicit none
     type (mfArray) :: x
     integer :: i
     x = (/(i, i=1, 5)/)
     call msDisplay(x, 'x')
     call msFreeArgs(x)
     end program example


     Result
                       Chapter 2 Essential Functions   63

x =
 1 2 3     4 5


See Also
msFormat, msGDisplay
64      MATFOR 4 in Fortran Reference Guide



     msFormat
     Specify displaying format of mfArray.


     Module
     fml


     Syntax
     call msFormat(mode)



     Descriptions
     Procedure msFormat specifies display format of mfArray.

     call msFormat("long")
     Return 8 - byte precision with procedure mfDisplay

     call msFormat("short")
     Return 4 - byte precision with procedure mfDisplay.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, y
     x = 2.02
     y = mfCos(x)
     call msFormat("short")
     call msDisplay(y, "y (short format)")
     call msFormat("long")
     call msDisplay(y, "y (long format)")
     end program

     Result
     y (short format) =

       -0.4342

      y (long format) =

       -0.434248328937034

     See Also
     msDisplay
         Chapter 2 Essential Functions   65




FileIO
66       MATFOR 4 in Fortran Reference Guide



     mfLoad
     Load binary file into mfArray.


     Module
     fml


     Syntax
     x = mfLoad(filename)


     Descriptions
     Procedure mfLoad reads data from a binary file, created by procedure msSave, into an
     mfArray.

     x = mfLoad(filename)
     • Argument filename is a Fortran string containing the name of the binary file. For
          example, x = mfLoad("y.mfb").
     •    The MATFOR binary file uses ".mfb" as a file extension.

     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, y
     x = Reshape((/1, 2, 3, 4, 5, 6/), (/2, 3/))
     ! x     is 1 3 5
     !         2 4 6
     call msSave('x.mfb', x)
     y = mfLoad('x.mfb')
     call msDisplay(x, 'x', y, 'y')
     call msFreeArgs(x, y)
     end program example


     Result
     x =
         1 3 5
         2 4 6
      y =
         1 3 5
         2 4 6


     See Also
     msSave, msSaveAscii, mfLoadAscii
                                                             Chapter 2 Essential Functions   67



mfLoad.m
Load MATFOR binary file into MATLAB workspace.


Module
mfLoad.dll


Syntax
x = mfLoad(filename)



Descriptions
Function mfLoad retrieves data from a MATFOR *.mfb binary file into a MATLAB matrix
x.

x = mfLoad(filename)
• Argument filename is a string containing the name of the source binary file. A .mfb
    extension is assumed if one is not specified.
•   You can use this function to load data saved using mfSave in MATFOR or mfSave in
    MATLAB.

Note that to use this function, ensure that the files mfLoad.m and mfLoad.dll are in your
MATLAB working directory. The two files are installed in your MATFOR directory
<MATFOR4>/tools/matlab when MATFOR is installed.



Example

See Also
msSave, mfLoad, mfSave.m
68       MATFOR 4 in Fortran Reference Guide



     mfLoadAscii
     Load an ASCII file into mfArray.


     Module
     fml


     Syntax
     x = mfLoadAscii(filename)



     Descriptions
     Procedure mfLoadAscii reads in data from an ASCII file into an mfArray.

     x = mfLoadAscii(filename)
     • The ASCII file must be in 2-D matrix format with m rows and n columns corresponding
          to an m x n matrix mfArray.
     •    Argument filename is a string containing the filename of the ASCII file. For example,
          x = mfLoadAscii("y.txt").

     You can produce an ASCII file for loading by using procedure msSaveAscii.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, y
     x = RESHAPE((/1, 2, 3, 4, 5, 6/), (/2, 3/))
     ! x     is 1 3 5
     !          2 4 6
     call msSaveAscii('x.txt', x)
     y = mfLoadAscii('x.txt')
     call msDisplay(x, 'x', y, 'y')
     call msFreeArgs(x, y)
     end program example


     Result
     x =
         1 3 5
         2 4 6
      y =
         1 3 5
                              Chapter 2 Essential Functions   69

 2 4 6


See Also
msSave, mfLoad, msSaveAscii
70       MATFOR 4 in Fortran Reference Guide



     mfLoadCsv
     Load a CSV file into mfArray.


     Module
     fml


     Syntax
     x = mfLoadCsv(filename)



     Descriptions
     Procedure mfLoadCsv reads in data from a CSV file into an mfArray.

     x = mfLoadCsv(filename)
     • A CSV file is a common text file that contains comma-delimited values.
     •   The CSV file must be in 2-D matrix format with m rows and n columns corresponding to
         an m x n matrix mfArray.
     •   Argument filename is a string containing the filename of the CSV file. For example, x
         = mfLoadCsv("y.csv").

     You can produce a CSV file for loading by using procedure msSaveCsv.



     Example
     To be referred to mfLoadAscii

     See Also
     msSaveCsv
                                                              Chapter 2 Essential Functions   71



msSave
Save mfArray into a MATFOR binary file.


Module
fml


Syntax
call msSave(filename, x)



Descriptions
Procedure msSave writes data contained in an mfArray to a binary file with extension .mfb.

call msSave(filename, x)
• Argument filename is a Fortran string containing the name of the target binary file. For
     example, call msSave("x.mfb",x).
•    Argument x is the name of the mfArray to be saved.

Example

Code
program example
use fml
implicit none
type(mfArray) :: x, y
x = RESHAPE((/1, 2, 3, 4, 5, 6/), (/2, 3/))
! x     is 1 3 5
!          2 4 6
call msSave('x.mfb', x)
y = mfLoad('x.mfb')
call msDisplay(x, 'x', y, 'y')
call msFreeArgs(x, y)
end program example


Result
x =
    1 3 5
    2 4 6
 y =
    1 3 5
    2 4 6

See Also
mfLoad, msSaveAscii, mfLoadAscii
72       MATFOR 4 in Fortran Reference Guide



     mfSave.m
     Save MATLAB matrix into a MATFOR binary file.


     Module
     mfSave.dll


     Syntax
     mfSave(filename, x)



     Descriptions
     Procedure mfSave(filename, x)saves data contained in a MATLAB matrix x as
     MATFOR *.mfb binary file format.

     •   Argument filename is a string containing the name of the target binary file. An
         extension of .mfb is assumed if one is not specified.
     •   The data saved by using this function can be reloaded into the MATLAB workspace using
         function mfLoad or retrieved in Fortran using procedure mfLoad. This facilitates
         exchange of data between Fortran and MATLAB environments.

     Note that to use this function, ensure that the files mfSave.m and mfSave.dll are in your
     MATLAB working directory. The two files are installed in your MATFOR directory
     <MATFOR4>/tools/matlab when MATFOR is installed.



     Example

     See Also
     msSave, mfLoad, mfLoad.m
                                                              Chapter 2 Essential Functions   73



msSaveAscii
Save mfArray into an ASCII file.


Module
fml


Syntax
call msSaveAscii(filename, x)



Descriptions
Procedure msSaveAscii writes data contained in an mfArray to an ASCII file with the
extension the user specified.

call msSaveAscii(filename, x)
• The data is written in a 2-D matrix format, with m rows and n columns, corresponding to
    an m-by-n matrix mfArray.
•   Argument filename is a string containing the name of the target binary file. For
    example, msSaveAscii("x.dat", x).
•   Argument x is the name of the mfArray to be saved.



Example
To be referred to mfLoadAscii

See Also
msSave, mfLoad, mfLoadAscii
74       MATFOR 4 in Fortran Reference Guide



     msSaveCsv
     Save mfArray into a CSV file.


     Module
     fml


     Syntax
     call msSaveCsv(filename, x)



     Descriptions
     Procedure msSaveCsv writes data contained in an mfArray to a CSV file with the extension
     the user specified.

     call msSaveCsv(filename, x)
     • A CSV file is a common text file that contains comma-delimited values.
     •   The data is written in a 2-D matrix format, with m rows and n columns, corresponding to
         an m-by-n matrix mfArray.
     •   Argument filename is a string containing the name of the target CSV file. For example,
         msSaveCsv("x.csv", x).
     •   Argument x is the name of the mfArray to be saved.



     Example
     To be referred to mfLoadAscii

     See Also
     mfLoadCsv
                                                       Chapter 3 Data Manipulation Functions   75



CHAPTER 3



Data Manipulation Functions
This chapter introduces a set of data manipulation functions.
76    MATFOR 4 in Fortran Reference Guide




     Basic
                                                      Chapter 3 Data Manipulation Functions   77



mfMax, msMax
Find the maximum value along different dimensions of an mfArray.


Module
fml


Syntax
a = mfMax(x[, mf(), IDIM])
a = mfMax(x, y)
call msMax(mfOut(a, i), x[, mf(), IDIM])



Descriptions
a = mfMax(x)
• For vectors, mfMax returns the largest element in x.
•   For matrices, mfMax returns a row vector containing the maximum element from each
    dimension.

y = mfMax(x, mf(), IDIM)
• operates along the dimension of x specified by scalar IDIM.

a = mfMax(x, y)
• returns an array the same size as x and y with the larger corresponding elements from x
    or y chosen. Either one can be a scalar.

For complex input x, mfMax returns the largest absolute value.



Example

Code
program example
use fml
implicit none
type(mfArray) :: x, c, y
integer(4) :: i
x = Reshape((/1, 2, 3, 4, 5, 6/), (/2, 3/))
! x     is 1 3 5
!          2 4 6
y = Reshape((/3,5,4,6,2,1/), (/2, 3/))
! y     is 3 4 2
!          5 6 1
i = mfMax(mf((/ 1, 2, 3 /)))
call msDisplay(mf(i), 'mfMax(mf((/ 1, 2, 3 /)))')
78     MATFOR 4 in Fortran Reference Guide

     c = mfMax(x, MF_NULL, 1)
     call msDisplay(x, 'x', y, 'y', c,'mfMax(x, MF_NULL, 1)')
     c = mfMax(x, MF_NULL, 2)
     call msDisplay(x, 'x', y, 'y', c,'mfMax(x, MF_NULL, 2)')
     c = mfMax(x, y)
     call msDisplay(c, 'mfMax(x, y)')
     call msFreeArgs(x, c, y)
     end program example


     Result
     mfMax(mf((/ 1, 2, 3 /))) =
      3
     x =
      1 3 5
      2 4 6
     y =
      3 4 2
      5 6 1
     mfMax(x, MF_NULL, 1) =
      2 4 6
     x =
      1 3 5
      2 4 6
     y =
      3 4 2
      5 6 1
     mfMax(x, MF_NULL, 2) =
      5
      6
     mfMax(x, y) =
      3 4 5
      5 6 6


     See Also
     mfMin
                                                      Chapter 3 Data Manipulation Functions   79



mfMin, msMin
Find the minimum value along different dimensions of an mfArray.


Module
fml


Syntax
a = mfMin(x[, mf(), IDIM])
a = mfMin(x, y)
call msMin(mfOut(a, i), x[, mf(), IDIM])



Descriptions
a = mfMin(x)
• For vectors, mfMin returns the largest element in x.
•   For matrices, mfMin returns a row vector containing the Minimum elements from each
    dimension.

a = mfMin(x, mf(), IDIM)
• operates along the dimension of x specified by scalar IDIM.

a = mfMin(x, y)
• returns an array the same size as x and y with the smaller corresponding elements from x
    or y chosen. Either one can be a scalar.

For complex input x, mfMin returns the smallest absolute value.



Example

Code
program example
use fml
implicit none
type(mfArray) :: x, c, y
integer(4) :: i
x   = Reshape((/1, 2, 3, 4, 5, 6/), (/2, 3/))
!    x    is 1 3 5
!            2 4 6
y   = Reshape((/3,5,4,6,2,1/), (/2, 3/))
!    y    is 3 4 2
!            5 6 1
i = mfMin(mf((/ 1, 2, 3 /)))
call msDisplay(mf(i), 'mfMin(mf((/ 1, 2, 3 /)))')
c = mfMin(x, MF_NULL, 1)
80     MATFOR 4 in Fortran Reference Guide

     call msDisplay(x, 'x', y, 'y', c, 'mfMin(x, MF_NULL, 1)')
     c = mfMin(x, MF_NULL, 2)
     call msDisplay(c, 'mfMin(x, MF_NULL, 2)')
     c = mfMin(x, y)
     call msDisplay(c, 'mfMin(x,y) ')
     call msFreeArgs(x, c, y)
     end program example


     Result
     mfMin(mf((/ 1, 2, 3 /))) =
      1
     x =
      1 3 5
      2 4 6
     y =
      3 4 2
      5 6 1
     mfMin(x, MF_NULL, 1) =
      1 3 5
     mfMin(x, MF_NULL, 2) =
      1
      2
     mfMin(x,y)       =
      1 3 2
      2 4 1


     See Also
     mfMax
                                                      Chapter 3 Data Manipulation Functions   81



mfProd, msProd
Find the product of mfArray elements.


Module
fml


Syntax
a = mfProd(x[, IDIM])



Descriptions
a = mfProd(x)
• For matrices, mfProd(x) returns a row vector containing the product of each column of
     mfArray x.
•    For N-dimensional arrays, mfProd(x) operates on the first non-singleton dimension.

a = mfProd(x, IDIM)
• Argument IDIM is an integer(4) scalar specifying the dimension that procedure
     mfProd(x) works along.



Example

Code
program example
use fml
implicit none
type(mfArray) :: x, y, c
integer(4) :: i
x = (/1, 2, 3/)
y = Reshape((/1, 2, 3, 4, 5, 6/), (/2, 3/))
! x is 1 3 5
!        2 4 6
i = mfProd(x)           ! returns 6
call msDisplay(x,       'x', mf(i), 'mfProd(x)')
c = mfProd(y, 1)        ! returns 2 12 30
call msDisplay(y,       'y', c, 'mfProd(y, 1)')
call msFreeArgs(x, y, c)
end program example


Result
x =
    1 2 3
 mfProd(x) =
82     MATFOR 4 in Fortran Reference Guide

      6
     y =
      1 3 5
      2 4 6
     mfProd(y, 1) =
       2 12 30


     See Also
     mfSum
                                                       Chapter 3 Data Manipulation Functions    83



mfSort, msSort
Sort elements of mfArray in ascending order.


Module
fml


Syntax
y = mfSort(x,[, IDIM])
call msSort(mfOut(y, i), x)



Descriptions
y = mfSort(x), y = mfSort(x, IDIM)
• The procedure returns to y an mfArray containing the elements of mfArray x sorted in
    ascending order along different dimensions.
•   For vector x, the elements are sorted in ascending order.
•   For matrix x, the elements in each column of x are sorted in ascending order accordingly.
    In effect, the procedure returns an mfArray y assuming the shape of x, with the elements
    in each column sorted in ascending order.
•   For n-dimensional x, the elements are sorted along the first non-singleton dimension of
    x.
•   Argument IDIM is an integer specifying the dimension to be sorted along. By default,
    IDIM = 1, corresponding to sorting along the column.
•   When x is complex, the function returns mfArray y containing sorted elements of
    mfAbs(x). Complex matches are further sorted according to mfAtan2(mfImag(x),
    mfReal(x)).

call msSort(mfOut(y, i), x)
• This format returns an additional index mfArray i, containing the indices of elements in
    x, corresponding to the sorted elements in y.

For example,


    x=816
      357
      492

call msSort(mfOut(y, i), x) returns mfArray y and i containing,

    y = 3 1 2
84       MATFOR 4 in Fortran Reference Guide


                4 5 6
                8 9 7

         i = 2 1 3
               3 2 1
               1 3 2
     •   For two values of the same magnitude, their original order is preserved.



     Example

     Code
     program example
     use fml
     implicit none
     type(mfArray) :: x, a
     x = RESHAPE((/3,5,4,6,2,1/), (/2, 3/))
     ! x     is 3 4 2
     !          5 6 1
     a = mfSort(x)
     call msDisplay(x, 'x', a, 'mfSort(x)')
     a = mfSort(x,2)
     call msDisplay(x, 'x', a, 'mfSort(x,2)')
     call msFreeArgs(x, a)
     end program example


     Result
     x =
         3 4 2
         5 6 1
     mfSort(x) =
         3 4 1
         5 6 2
     x =
         3 4 2
         5 6 1
     mfSort(x,2) =
         2 3 4
         1 5 6


     See Also
     mfSortRows
                                                          Chapter 3 Data Manipulation Functions   85



mfSortRows, msSortRows
Sort rows of mfArray in ascending order.


Module
fml


Syntax
y = mfSortRows(x[, col])
call msSortRows(mfOut(y, i), x)



Descriptions
y = mfSortRows(x), y = mfSortRows(x, col)
• The procedure returns mfArray y containing the rows of matrix mfArray x sorted in
    ascending order as a group.
•   If x contains strings, the function performs a dictionary sort.
•   When x is complex, the rows are sorted according to mfAbs(x). Complex matches are
    further sorted according to mfAtan2(mfImag(x), mfReal(x)).
•   If argument col is specified, the rows are sorted according to the columns specified in
    vector mfArray col.

For example,

    x = 8 1 6
        3 5 7
        4 9 2

    col = 3

y = mfSortRows(x, col) returns,

    y = 4 9 2
        8 1 6
        3 5 7

call msSortRows(mfOut(y,i), x)
• This format returns an additional index mfArray i, which contains the row indices after
    the corresponding rows have been swapped.



Example

Code
86       MATFOR 4 in Fortran Reference Guide

     program example
     use fml
     implicit none
     type(mfArray) :: x, y, i
     x = mfMagic(5)
     !y = mfSortRows(x)
     call msSortRows(mfOut(y, i), x)
     call msDisplay(x, 'x', y, 'Sort rows according to first column')
     call msDisplay(i, 'Corresponding index')
     call msFreeArgs(x, y, i)
     end program example


     Result
     x =
      17 24  1 8 15
      23 5   7 14 16
       4 6 13 20 22
      10 12 19 21 3
      11 18 25 2 9
     Sort rows according to first column =
       4 6 13 20 22
      10 12 19 21 3
      11 18 25 2 9
      17 24  1 8 15
      23 5   7 14 16
     Corresponding index =
     2
     3
     4
     5
     1


     See Also
     mfSort
                                                         Chapter 3 Data Manipulation Functions      87



mfSum, msSum
Find the sum of mfArray elements.


Module
fml


Syntax
a = mfSum(x[, IDIM])



Descriptions
a = mfSum(x), a = mfSum(x, IDIM)
a = mfSum(x)

For vectors, the procedure returns the sum of the elements of x. For matrices, a is a row vector
with the sum over each column. For N-dimensional arrays, a operates along the first non-singleton
dimension.

a = mfSum(X, IDIM)sums along the dimension IDIM.



Example
The following example uses the mfSum function.

Code
program example
use fml
implicit none
type(mfArray) :: x, y, c
integer(4) :: I
x = (/1, 2, 3/)
y = RESHAPE((/1, 2, 3, 4, 5, 6/), (/2, 3/))
! x     is 1 3 5
!          2 4 6
i = mfSum(x)            ! returns 6
call msDisplay(x, 'x', mf(i), 'mfSum(x)')
c = mfSum(y, 1)          ! returns 3 7 11
call msDisplay(y, 'y', c, 'mfSum(y, 1)')
call msFreeArgs(x, y, c)
end program example


Result
x =
  1 2 3
 mfSum(x) =
  6
88     MATFOR 4 in Fortran Reference Guide


     y =
      1 3 5
      2 4 6
     mfSum(y, 1) =
       3      7 11


     See Also
     mfProd
                         Chapter 3 Data Manipulation Functions   89




Fast Fourier Transform
90       MATFOR 4 in Fortran Reference Guide



     mfFFT, mfIFFT
     Compute the discrete Fourier transform and         the inverse discrete Fourier transform.


     Module
     fml


     Syntax
     y = mfFFT(x)
     y = mfFFT(x[, n])
     y = mfFFT(x[, mf(), dim])

     The syntax is the same between _mfFFT and _mfIFFT.



     Descriptions
     Procedure mfFFT computes the discrete Fourier transform of mfArray x using fast Fourier
     transform algorithm.

     y = mfFFT(x)
     • This procedure returns y, the discrete Fourier transform of mfArray x.
     •   If x is a matrix, the operation is applied in each column of x.

     y = mfFFT(x[, n])
     • This procedure returns the discrete Fourier transform of mfArray x given the length n.
     •   The length of x is adjusted according to n; either to be truncated or to be padded with
         zeros.

     y = mfFFT(x[, n, dim])
     • This procedure returns the discrete Fourier transform of mfArray x given the length n and
         the dimension dim.
     •   Argument dim is an integer(4) scalar specifying the dimension that procedure mfFFT
         works along. If dim = 1, the operation is applied along x dimension. If dim = 2, the
         operation is applied along y dimension and etc.
     •   If n is not specified, a null value mf() will be used by default.



     Example

     Code
     Program fft
     use fml
     use fgl
     implicit none
                                         Chapter 3 Data Manipulation Functions   91

integer(4), parameter :: n = 1000, tmax = 10
type(mfArray) :: t, f, x1, x2, y1, y2
t = mfLinspace( 0, tmax, n )
f = mfLinspace( 0, n/tmax, n )
x1 = mfCos( t * 2d0 * MF_PI ) + mfSin( t * 2d0 * MF_PI * 1.746d0 + t )
+ 0.2d0 * mfRand(1,n)
y1 = mfFFT(x1)
! remove the freq above 1.2
y2 = y1
call msAssign( mfS( y2, (tmax * 6 / 5).to.n ), 0 )
! do reverse
x2 = mfIFFT( y2 )
x2 = mfReal( x2 )
call msSubplot( 3, 1, 1 )
call msTitle('orig')
call msPlot( t, x1)
call   msSubplot( 3, 1, 2 )
call   msTitle('FFT')
call   msPlot( f, mfAbs(y1) )
call   msAxis( 0, 10, 0, 0 )
call msSubplot( 3, 1, 3 )
call msTitle('low pass with cutoff freq = 1.5')
call msPlot( t, x2 )
call msViewPause()
end Program fft


See Also
mfFFT2, mfIFFT2, mfFFTShift
92       MATFOR 4 in Fortran Reference Guide



     mfFFT2, mfIFFT2
     Compute the two-dimensional discrete Fourier transform             and the two-dimensional
     inverse discrete Fourier transform.


     Module
     fml


     Syntax
     y = mfFFT2(x)
     y = mfFFT2(x[, m, n])

     The syntax is the same between _mfFFT2 and _mfIFFT2.



     Descriptions
     Procedure mfFFT computes the two-dimensional inverse discrete Fourier transform of
     mfArray x using fast Fourier transform algorithm.

     y = mfFFT(x)
     • This procedure returns y, the two-dimensional discrete Fourier transform of mfArray x.
     y = mfFFT2(x[, m, n])
     • This procedure returns the two-dimensional discrete Fourier transform of mfArray x
         given m and n to be the length of row and column.
     •   The shape of x is adjusted according to m and n; either to be truncated or to be padded
         with zeros.



     Example

     Code
     Program fft2
     use fml
     use fgl
     implicit none
     type(mfArray) :: im, imf
     ! ******************************************************************
     ! load data
     ! ******************************************************************
     im = mfImRead( mf('ancad.bmp') )
     im = mfS( im, MF_COL, MF_COL, 1)-128.0d0
     ! ******************************************************************
     ! FFT2
     ! ******************************************************************
     imf = mfFFT2(im)
                                         Chapter 3 Data Manipulation Functions   93

imf = mfFFTShift(imf)
! ******************************************************************
! Draw
! ******************************************************************
call   msSubplot(1,2,1)
call   msFastPColor(im)
call   msColormap('gray')
call   msAxis('equal')
call   msSubplot(1,2,2)
call   msFastPColor(mfAbs(imf))
call   msColormap('gray')
call   msColormapRange(0,50000)
call   msAxis('equal')
call msViewPause()
end Program fft2


See Also
mfFFT, mfIFFT, mfFFTShift
94       MATFOR 4 in Fortran Reference Guide



     mfFFTShift, mfIFFTShift
     Shift zero frequency components of discrete Fourier transform and inverse discrete Fourier
     transform to the center of the matrix.


     Module
     fml


     Syntax
     y = mfFFTShift(x)
     y = mfFFTShift(x[, dim])

     The syntax is the same between _mfFFTShift and _mfIFFTShift. _mfIFFTShift
     undoes what was done with _mfFFTShift.



     Descriptions
     Procedure mfFFTShift moves the zero frequency components along the dimension to the
     center of the mfArray.

     y = mfFFTShift(x)
     • This procedure shifts the zero frequency components to the middle of the mfArray.
     •   mfArray x is the output of fast Fourier transform.
     •   If x is a vector, the procedure swaps the left-half space with the right-half space. If x is a
         matrix, the procedure swaps the left-half space with the right-half space, then the top-half
         space with the bottom-half space.


                  For one dimension x                           For multiple dimensions x




     y = mfFFT(x[, dim])
     • This procedure shifts the zero frequency components to the middle of the mfArray along
                                                      Chapter 3 Data Manipulation Functions   95


   the dimension specified. For dim = 1, the operation is applied along x dimension. For
   dim = 2, the operation is applied along y dimension and so on.



Example
To be referred to mfFFT2

See Also
mfFFT, mfFFT2
96    MATFOR 4 in Fortran Reference Guide




     Cartographic Functions
                                                            Chapter 3 Data Manipulation Functions   97



msProj4, msProj4Inv
Perform cartographic projection and its inverse operation.


Module
fgl


Syntax
call msProj4(mfOut(x,y), proj_name, lon_0, u, v[, options])
call msProj4Inv(mfOut(u,v),proj_name, lon_0, x, y[, options] )



Descriptions
Procedure msProj4 performs cartographic projection by converting geographic longitude
and latitude coordinates into Cartesian coordinates in the form of mfArray x and y.
• proj_name is the selection of cartographic projection. For example, use "robin" for
       Robinson projection, and "lcc" for Lambert Conformal Conic projection. Available project
       names are listed in the table below.
•      Argument lon_0 sets the central meridian for the projection. The normal geographic range
       for longitude is from 180W to 180E.
•      mfArrays u and v are the respective geographic longitude and latitude coordinates.
•      mfArrays x, y, are the Cartesian coordinates output from the projection.
•      Argument options give additional information to be passed to the proj4 engine. It is in
       the form of string.
Cylindrical Projections
proj_name             Projection
merc                  Mercator Projection
tmerc                 Transverse Mercator Projection
cc                    Central Cylindrical Projection
tcc                   Transverse Central Cylindrical Projection
mill                  Miller Projection
cea                   Lambert Cylindrical Equal Area Projection
gall                  Gall Stereographic Projection
tcea                  Transverse Cylindrical Equal Area Projection
eqc                   Transverse Cylindrical Equal Area Projection
cass                  Cassini Projection
Pseudocylindrical Projections
proj_name             Projection
sinu                  Sinusoidal Projection
98         MATFOR 4 in Fortran Reference Guide


     moll                 Mollweide Projection
     robin                Robinson Projection
     eck1                 Eckert I Projection
     eck2                 Eckert II Projection
     eck3                 Eckert III Projection
     eck4                 Eckert IV Projection
     eck5                 Eckert V Projection
     eck6                 Eckert VI Projection
     aatano               Hatano Asymmetrical EqualArea Projection
     loxim                Loximuthal Projection
     mbtfpp               McBrydeThomas FlatPolar Parabolic Projection
     mbtfpq               McBrydeThomas FlatPolar Quartic Projection
     mbtfps               McBrydeThomas FlatPolar Sinusoidal Projection
     putp2                Putnins P Projection
     putp5                Putnins P Projection
     qua_aut              Quartic Authalic Projection
     wink1                Winkel I Projection
     boggs                Boggs Eumorphic Projection
     collg                Collignon Projection
     denoy                Denoyer Semi Elliptical Projection
     crast                Craster Parabolic Projection
     Conic Projections
     proj_name            Projection
     lcc                  Lambert Conformal Conic Projection
     eqdc                 Equidistant Conic Projection
     aea                  Albers Equal Area Projection
     leac                 Lambert Equal Area Projection
     poly                 Polyconic American Projection
     rpoly                Rectangular Polyconic Projection
     bonne                Bonne Projection
     Azimuthal Projections
     proj_name            Projection
     stere                Stereographic Projection
     gnom                 Gnomonic Projection
     ortho                Orthographic Projection
     airy                 Airy Projection
     laea                 Lambert Azimuthal Equal Area Projection
                                                      Chapter 3 Data Manipulation Functions    99


aeqd              Azimuthal Equidistant Projection
hammer            Hammer Projection
wag7              Wagner VII Projection
aitoff            Aito Projection
wintri            Winkel Tripel Projection
Miscellaneous Projections
proj_name         Projection
august            August Epicycloidal Projection
bacon             Bacon Globular Projection
nicol             Nicolosi Globular Projection
apian             Apian Globular I Projection
ortel             Ortelius Oval Projection
vandg             Van der Grinten I Projection
vandg2            Van der Grinten II Projection
vandg3            Van der Grinten III Projection
vandg4            Van der Grinten IV Projection
lagrng            Lagrange Projection




Complete details including technical usage and execution of program proj4 can be referred to
http://proj.maptools.org/



Example

Code
program example
use fgl
use fml
implicit none
integer(4), parameter :: N1 = 36, N2 = 18
integer(4), parameter :: LON_0 = 120
type(mfArray) :: x, y, z, u, v, tu, tv
type(mfArray) :: h
type(mfArray) :: pathX,pathY,wave,roX,roY,h2
call msFigure('Robin')
z = mfZeros( N2+1, N1+1 )
!Create geographic mesh
call msCreateGeoidData( mfOut( u, v, tu, tv ), &
       LON_0-180, LON_0+180, -90, 90 ,N1,N2)
! robin map projection
call msProj4( mfOut(x, y), 'robin', LON_0, u, v )
!Draw geographic mesh
h = mfSurf(x, y, z)
call DrawImgMap(h)
100      MATFOR 4 in Fortran Reference Guide

      !Draw two path
      call msHold('on')
      pathX = .t.(mfLinspace(-60,300,30).vc.mfLinspace(-60,300,30))
      pathY = .t.(mfLinspace(5,35,30).vc.mfLinspace(-35,5,30))
      wave = mfCos(pathY)*3d0
      pathY = pathY + wave
      call msProj4( mfOut(rox, roy), 'robin', LON_0, pathX, pathY )
      call msPlot(rox,roy,'ro-')
      call msHold('off')
      call   msView( '2' )
      call   msAxis('equal')
      call   msAxis('clipping', 'on')
      call   msAxisWall('off')
      call msFigure('3D Earth')
      call msCreateGeoid3Data( mfOut( x, y, z, tu, tv), -180, 180, -90, 90 )
      h = mfSurf(x, y, z)
      call DrawImgMap(h)
      call Draw3DPath(pathX, pathY)
      call msAxis('equal')
      ! Pause program execution
      call msViewPause()
      ! Deallocate mfArray
      call msFreeArgs( x, y, z, u, v, tu, tv )
      call msFreeArgs( h,pathX,pathY,wave,roX,roY,h2 )
      contains
      subroutine DrawImgMap(h)
         type(mfArray), intent(in) :: h
         call msDrawTexture(h, mf('map'), mf('earth.png'), &
             mf('coord_s'), tu, mf('coord_t'), tv )
         call msDrawMaterial(h, mf('surf'), &
            mf('smooth'), mf('on'), &
             mf('colormap'), mf('off'), &
             mf('ambient'), mf(0), &
             mf('diffuse'), mf(25), &
             mf('specular'), mf(85) )
         call msDrawMaterial(h, mf('edge'), &
             mf('trans'), mf(80), &
             mf('smooth'), mf('on'), &
             mf('colormap'), mf('off'), &
             mf('color'), mf( (/1,1,1/) ) )
      end subroutine DrawImgMap
      subroutine Draw3DPath( pathX, pathY)
         implicit none
         type(mfArray), intent(in) :: pathX, pathY
         type(mfArray) ::x, y, z, c, r, th, phi,h
         r = 1.1d0
         th = pathX * MF_PI / 180
         phi = pathY * MF_PI / 180
         x   =   r * mfCos( th ) * mfCos( phi )
         y   =   r * mfSin( th ) * mfCos( phi )
         z   =   r * mfSin( phi )
         c   =   x*y-z
         !Draw path
         call msHold('on')
         h = mfPlot3(x,y,z,c)
         call msDrawMaterial(h,mf('edge'),mf('line_width'),mf(3))
         call msHold('off')
         call msFreeArgs(x, y, z, r, th, phi,h)
      end subroutine Draw3DPath
                      Chapter 3 Data Manipulation Functions   101


end program example


Result




See Also
102       MATFOR 4 in Fortran Reference Guide



      msCreateGeoidData
      2-D geoid data.


      Module
      fgl


      Syntax
      call msCreateGeoidData(mfOut(x,y), lon0, lon1, lat0, lat1[, nlon,
      nlat ] );
      call msCreateGeoidData(mfOut(x, y, tu, tv), lon0, lon1, lat0, lat1[, nlon,
      nlat ] );



      Descriptions
      Procedure msCreateGeoidData creates the geoid data for 2-D mesh plots.
      • Arguments lon0 and lon1 specify the geographic longitude range. The normal
          geographic longitude ranges from -180 to +180.
      •   Arguments lat0 and lat1 specify the geographic latitude range. The normal
          geographic latitude ranges from -90 to +90.
      •   nlon and nlat represent respective number of meridians and number of parallels to be
          plotted. By default, nlon=36, nlat=18.
      •   The output variables x , y, tu, tv are matrix mfArray in the shape of (nlon+1) by
          (nlat+1).



      Example
      To be referred to msProj4

      See Also
      msProj4
                                                      Chapter 3 Data Manipulation Functions   103



msCreateGeoid3Data
3-D geoid data.


Module
fgl


Syntax
call msCreateGeoid3Data(mfOut(x,y,z), lon0, lon1, lat0, lat1[, nlon,
nlat ] );
call msCreateGeoid3Data(mfOut(x, y, z, tu, tv), lon0, lon1, lat0, lat1[,
nlon, nlat ] );



Descriptions
Procedure msCreateGeoid3Data creates the geoid data for 3-D mesh plots.
• Arguments lon0 and lon1 specify the geographic range for longitude. The normal
    geographic longitude ranges from -180 to +180.
•   Arguments lat0 and lat1 specify the geographic range for latitude. The normal
    geographic latitude ranges from -90 to +90.
•   nlon and nlat represent respective number of meridians and number of parallels to be
    plotted. By default, nlon=36, nlat=18.
•   The output variables x , y, z, tu, tv are matrix mfArray in the shape of (nlon+1) by
    (nlat+1).



Example
To be referred to msProj4

See Also
msProj4
104       MATFOR 4 in Fortran Reference Guide



      msCreateCoastlineData
      2-D coastline data.


      Module
      fgl


      Syntax
      call msCreateCoastlineData(mfOut(x,y)[, lon0, lon1, lat0, lat1])



      Descriptions
      Procedure msCreateCoastlineData creates coastline data for 2-D plots.
      • This procedure returns mfArray x and y. You may use procedure msPlot to draw the
          coastline.
      •   Arguments lon0 and lon1, lat0 and lat1 specify the geographic ranges for
          longitude and latitude respectively.

      You can set geoid label on the axis object using procedure msAxis('geoid_label',
      'on').



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y
      !Create 2D coastline data
      call msCreateCoastlineData( mfOut(x,y), -180, 180, -90, 90 )
      !plot 2D linear graph
      call msPlot( x, y)
      call msTitle('2D Coastline')
      call msAxis('geoid_label', 'off')
      call msViewPause()
      end program example


      Result
                         Chapter 3 Data Manipulation Functions   105




See Also
msCreateCoastline3Data
106       MATFOR 4 in Fortran Reference Guide



      msCreateCoastline3Data
      3-D coastline data.


      Module
      fgl


      Syntax
      call msCreateCoastline3Data(mfOut(x,y,z)[, lon0, lon1, lat0, lat1])



      Descriptions
      Procedure msCreateCoastline3Data creates coastline data for 3-D plots.
      • This procedure returns mfArray x y and z. You may use procedure msPlot3 to draw
          the coastline.
      •   Arguments lon0 and lon1, lat0 and lat1 specify the geographic ranges for
          longitude and latitude respectively.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, z
      !Create 3D coastline data
      call msCreateCoastline3Data( mfOut(x, y, z), -180, 180, -90, 90 )
      !plot 3D linear graph
      call msPlot3( x, y, z )
      call msColormapRange(-1d0,1d0)
      call msTitle('3D Coastline')
      call msViewPause()
      end program example


      Result
                        Chapter 3 Data Manipulation Functions   107




See Also
msCreateCoastlineData
108   MATFOR 4 in Fortran Reference Guide
                                                  Chapter 4 Arithmetic & Relational Operators   109




CHAPTER 4


Arithmetic & Relational

Operators
This chapter describes the operators and functions available for matrix and array
manipulation.



Operator Precedence

Arithmetic Operators

Relational Operators
110       MATFOR 4 in Fortran Reference Guide




      Operator Precedence


      The table below lists the MATFOR operator precedence. Operators having the
      same symbol as Fortran operators also share the same precedence level. All
      MATFOR-defined operators occupy the lowest precedence level.
      Note that operators having the same precedence level are evaluated from left to
      right.




      Operators           Descriptions                           Precedence

          .h.             mfArray complex transpose                  Highest

          .t.             mfArray transpose

          **              mfArray power

          *               mfArray multiplication

          /               mfArray right division

          +               mfArray addition or unary plus

          -               mfArray subtraction or unary minus

          >=              mfArray greater than or equal to
                          comparison

          >               mfArray greater than comparison

          <=              mfArray less than or equal to

          <               mfArray less than comparison

          /=              mfArray inequality comparison

          ==              mfArray equality comparison

          .hc.            Horizontal concatenation
                                Chapter 4 Arithmetic & Relational Operators   111


.vc.   Vertical concatenation            Lowest
112        MATFOR 4 in Fortran Reference Guide




      Arithmetic Operators
      Arithmetic operators mean symbols of addition, subtraction, multiplication and division.


      Module
      use fml
      or
      use mod_ops




      Syntax
      type (mfArray) :: x, y, z
      integer :: n


      z = x + y
      z = + x
      z = x – y
      z = - x
      z = x*y
      z = x/y
      z = x**y
      z = x**n
      z = mfMul(x, y)
      z = mfLDiv(x, y)
      z = mfRDiv(x, y)
      z = .t.x
      z = .h.x




      Descriptions
      Arithmetic operators provided by MATFOR include both array
      and       matrix        operators.         Array       operators         operate
      element-by-element on the mfArrays while matrix operators
      operate on whole mfArrays.
      The following lists the operators available with a brief
                                               Chapter 4 Arithmetic & Relational Operators   113


description of their operation.



+               Array addition or unary plus


                x + y adds mfArrays x and y. Unless one is scalar, the two
                mfArrays must be the same size. A scalar can be added to
                mfArrays of any size.
114        MATFOR 4 in Fortran Reference Guide




      -                         Array subtraction or unary minus

                                x – y subtracts mfArray y from x. Unless one is scalar, the
                                two mfArrays must be the same size. A scalar can subtract
                                and be subtracted from mfArrays of any size.



      *                         Array multiplication

                                x * y returns element-by-element the multiplication of
                                mfArrays x and y. Unless one is scalar, the two mfArrays
                                must be the same size. A scalar can be multiplied with an
                                mfArray of any size.



      mfMul                     Matrix multiplication

                                mfMul(x, y) returns the matrix product of mfArrays x
                                and y, where x is an m-by-p matrix and y is a p-by-n
                                matrix. The product of the matrix multiplication is an
                                m-by-n mfArray.



      mfRDiv                    Matrix right division

                                mfRDiv(x, y) returns an mfArray approximately equal to
                                x*mfInv(y). The result is the same
                                as .t.( mfLDiv((.t.y), (.t.x))).



      mfLDiv                    Matrix left division

                                mfLDiv(y, x) returns an mfArray approximately equal to
                                mfInv(y)*x. Depending on the structure of y,
                                MATFOR overloads several methods for solving the
                                simultaneous linear equation.



      **                        Array power
                         Chapter 4 Arithmetic & Relational Operators   115


x**y returns an mfArray containing elements of x(i,j)
raised to the power of corresponding elements of y(i,j).
Unless one is scalar, the two mfArrays must be the same
size.


x**n, where n is a Fortran scalar, returns an mfArray
containing the elemens of x raised to the power of n.
116          MATFOR 4 in Fortran Reference Guide




      .t.,     mfTranspose        Array transpose

                                  .t.x returns an mfArray containing the transpose of
                                  mfArray x. In a transpose operation, ai,j and aj,i are
                                  interchanged.
                                  Complex elements are not conjugated.
                                  You can also use the msTranspose procedure to
                                  perform the same operation.
                                  c = .t. a
                                  c = mfTranspose(a)
                                  call msTranspose(mfOut(c), a)



      .h.,    mfCTranspose        Complex conjugate transpose

                                  .h.x returns      an mfArray containing the complex
                                  conjugate transpose of mfArray x. If x is real, this
                                  operation returns the same result as .t.x.
                                  When performing linear algebra operations on complex
                                  matrices, it is almost always the complex conjugate
                                  transpose (also called the Hermitian transpose) that is
                                  needed.
                                  You can also use the mfCTranspose procedure to
                                  perform the same operation.
                                  c = .h. a
                                  c =    mfCTranspose(a)
                                  call msCTranspose(mfOut(c), a)




      See Also
      Relational Operators
                                                 Chapter 4 Arithmetic & Relational Operators   117




Relational Operators

Module
use mod_ops




Syntax
type (mfArray) :: x, y, z


z = x == y
z = x >= y
z = x > y
z = x <= y
z = x < y
z = x /= y




Descriptions
The relational operators ==, >=, >, <=, and /=, perform element-by-element
comparisons between two mfArrays.
The returned logical mfArray records the result of the comparison. Each element
records a logical true(1) if the relationship is true, and logical false(0)
otherwise.


Note that unless one is scalar, the two mfArrays x and y must be the same size. The
scalar will be expanded into an mfArray the same size as the other mfArray.



==           mfArray equality comparison
118        MATFOR 4 in Fortran Reference Guide


                 x == y checks if each element of x equals the corresponding element of
                 y. The operator tests both real and imaginary parts of the elements.
                 When you use the equality (= =) operator in an if statement, use the
                 all function to enclose it. The all function ensures that the equality
                 condition is satisfied by all elements of the returned mfArray.



      >=         mfArray greater than or equal to comparison

                 x >= y checks if each element of x is more than or equal to the
                 corresponding element of y. The function returns 1 if the relation is true
                 and 0 otherwise. The operator only compares the real part of the
                 elements.
                                                      Chapter 4 Arithmetic & Relational Operators   119




>          mfArray greater than comparison

           x > y checks if each element of x is greater than the corresponding
           element of y. The function returns 1 if the relation is true and 0
           otherwise. The operator only compares the real part of the elements.



<=         mfArray less than or equal to comparison

           x <= y checks if each element of x is less than or equal to the
           corresponding element of y. The function returns 1 if the relation is true
           and 0 otherwise. The operator only compares the real part of the
           elements.



<          mfArray less than comparison

           x < y checks if each element of x is less than the corresponding element
           of y. The function returns 1 if the relation is true and 0 otherwise. The
           operator only compares the real part of the elements.



/=         mfArray inequality comparison

           x /= y checks if each element of x is different from the corresponding
           element of y. The operator tests both real and imaginary parts of the
           elements.




See Also
Arithmetic Operators, Any, All
120   MATFOR 4 in Fortran Reference Guide
                                                        Chapter 5 Elementary Math Functions   121



CHAPTER 5




Elementary Math Functions

This chapter introduces a set of elementary math functions including trigonometric,
exponential, complex, rounding and remainder. The functions are listed below:



Trigonometric

mfACos                  Inverse cosine function
mfACosh                 Inverse hyperbolic cosine function
mfACot                  Inverse cotangent function
mfACoth                 Inverse hyperbolic cotangent function
mfACsc                  Inverse cosecant function
mfACsch                 Inverse hyperbolic cosecant function
mfASec                  Inverse secant function.
mfASech                 Inverse hyperbolic secant function.
mfASin                  Inverse sine function.
mfASinh                 Inverse hyperbolic sine function.
mfATan                  Inverse tangent function.
mfATan2                 Four quadrant arctangent function
mfATanh                 Inverse hyperbolic tangent function
mfCos                   Cosine function
mfCosh                  Hyperbolic cosine function
mfCot                   Cotangent function
mfCoth                  Hyperbolic cotangent function
mfCsc                   Cosecant function
mfCsch                  Hyperbolic cosecant function
mfSec                   Secant function
mfSech                  Hyperbolic secant function
122       MATFOR 4 in Fortran Reference Guide


      mfSin                    Sine function
      mfSinh                   Hyperbolic sine function
      mfTan                    Tangent function
      mfTanh                   Hyperbolic tangent function



      Exponential

      mfExp                    Exponential function
      mfLog                    Natural logarithm
      mfLog10                  Common logarithm (base 10)
      mfLog2                   Base 2 Logarithmic and floating point dissection
      mfPow2                   Base 2 power and floating point number scaling
      mfSqrt                   Square Root function



      Complex

      mfAbs                    Absolute of real and complex value
      mfAngle                  Phase angle of complex
      mfComplex                Convert input number to complex
      mfConj                   Conjugate of complex
      mfImag                   Imaginary part of complex
      mfReal                   Real part of complex



      Rounding and Remainder

      mfCeil                   Round towards positive infinity
      mfFix                    Round towards zero
      mfFloor                  Round towards minus infinity
      mfMod                    Modulus (signed remainder after division)
      mfRem                    Remainder after division
      mfRound                  Round towards nearest integer
      mfSign                   Signum function
               Chapter 5 Elementary Math Functions   123




Trigonometry
124       MATFOR 4 in Fortran Reference Guide



      mfACos, msACos
      Request inverse cosine function.


      Module
      fml


      Syntax
      y = mfACos(x)



      Descriptions
      Procedure mfACos(x) returns the arccosine of the mfArray x, in radians, where

      cos-1(x) = -i*log[x + i*(1-x2)1/2]

      The function domain and range includes real and complex data.
      For |x| <= 1, the function result is real and lies between 0 and π.
      For |x| >1, the function returns a complex value.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 2.02d0
      y = mfACos(x)
      call msDisplay(x, 'x', y, 'mfACos(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         2.0200

       mfACos(x) =

       0.0000 +1.3284i


      See Also
      mfACosh, mfCos
                                                     Chapter 5 Elementary Math Functions   125



mfACosh, msACosh
Request inverse hyperbolic cosine function.


Module
fml


Syntax
y = mfACosh(x)



Descriptions
Procedure mfACosh(x) returns element-by-element the inverse hyperbolic cosine of the
mfArray x, in radians, where

cosh-1(x) = log[x + (x2-1)1/2]

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = (2, -2)
y = mfACosh(x)
call msDisplay(x, 'x', y, 'mfACosh(x)')
call msFreeArgs(x, y)
end program example


Result
x =

 2.0000 -2.0000i

 mfACosh(x) =

 1.7343 -0.8165i


See Also
mfCos, mfCosh
126       MATFOR 4 in Fortran Reference Guide



      mfACot, msACot
      Request inverse cotangent function.


      Module
      fml


      Syntax
      y = mfACot(x)



      Descriptions
      Procedure mfACot(x) returns element-by-element the arccotangent of the mfArray x, in
      radians, where

      cot-1(x) = tan-1(1/x)

      The function domain and range include real and complex data.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = (-5, -5)
      y = mfACot(x)
      call msDisplay(x, 'x', y, 'mfACot(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

      -5.0000 -5.0000i

       mfACot(x) =

      -0.1007 +0.0993i


      See Also
      mfACoth, mfCot, mfCoth
                                                     Chapter 5 Elementary Math Functions   127



mfACoth, msACoth
Request inverse hyperbolic cotangent function.


Module
fml


Syntax
y = mfACoth(x)



Descriptions
Procedure mfACoth(x) returns element-by-element the inverse hyperbolic cotangent of the
mfArray x in radians, where

coth-1(x) = tanh-1(1/x)

The function domain and range include real and complex data.
For |x| <= 1, the function result is complex or infinity.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.5d0
y = mfACoth(x)
call msDisplay(x, 'x', y, 'mfACoth(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.5000

 mfACoth(x) =

 0.5493 -1.5708i


See Also
mfACot, mfCot, mfCoth
128         MATFOR 4 in Fortran Reference Guide



      mfACsc, msACsc
      Request inverse cosecant function.


      Module
      fml


      Syntax
      y = mfACsc(x)



      Descriptions
      Procedure mfACsc(x) returns element-by-element the inverse cosecant of the mfArray x in
      radians, where

      csc-1(x) = sin-1(1/x)

      The function domain and range include real and complex data.
      For |x| < 1, the function result is complex or NaN.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 3.0d0
      y = mfACsc(x)
      call msDisplay(x, 'x', y, 'mfACsc(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =
        3
       mfACsc(x) =

         0.3398


      See Also
      mfACsch, mfCsc, mfCsch
                                                     Chapter 5 Elementary Math Functions   129



mfACsch, msACsch
Request inverse hyperbolic cosecant function.


Module
fml


Syntax
y = mfACsch(x)



Descriptions
Procedure mfACsch(x) returns element-by-element the inverse hyperbolic cosecant of the
mfArray x in radians, where

csch-1(x) = sinh-1(1/x)

The function domain and range include real and complex data.
For x = 0, the function result is infinity.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.5d0
y = mfACsch(x)
call msDisplay(x, 'x', y, 'mfACsch(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.5000

 mfACsch(x) =

   1.4436


See Also
mfACsc, mfCsc, mfCsch
130       MATFOR 4 in Fortran Reference Guide



      mfASec, msASec
      Request inverse secant function.


      Module
      fml


      Syntax
      y = mfASec(x)



      Descriptions
      Procedure mfASec(x) returns element-by-element the inverse secant of the mfArray x in
      radians, where

      sec-1(x) = cos-1(1/x)

      The function domain and range include real and complex data.
      For |x| < 1, the function result is complex or NaN.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 0.1d0
      y = mfASec(x)
      call msDisplay(x, 'x', y, 'mfASec(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         0.1000

       mfASec(x) =

       0.0000 +2.9932i


      See Also
      mfASech, mfSec, mfSech
                                                     Chapter 5 Elementary Math Functions   131



mfASech, msASech
Request inverse hyperbolic secant function.


Module
fml


Syntax
y = mfASech(x)



Descriptions
Procedure mfASech(x) returns element-by-element the inverse hyperbolic secant of the
mfArray x in radians, where

sech-1(x) = cosh-1(1/x)

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.1d0
y = mfASech(x)
call msDisplay(x, 'x', y, 'mfASech(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.1000

 mfASech(x) =

   2.9932


See Also
mfASec, mfSec, mfSech
132       MATFOR 4 in Fortran Reference Guide



      mfASin, msASin
      Request inverse sine function.


      Module
      fml


      Syntax
      y = mfASin(x)



      Descriptions
      Procedure mfASin(x) returns element-by-element the arcsine of the mfArray x in radians,
      where

      sin-1(x) = -i*log[i*x+(1-x2)1/2]

      The function domain and range include real and complex data.
      For real |x| < 1, the function result is real and lies in the range [-π/2, π/2].
      For real |x| >1, the function returns a complex value.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 0.5d0
      y = mfASin(x)
      call msDisplay(x, 'x', y, 'mfASin(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         0.5000

       mfASin(x) =

         0.5236


      See Also
      mfASinh, mfSin, mfSinh
Chapter 5 Elementary Math Functions   133
134       MATFOR 4 in Fortran Reference Guide



      mfASinh, msASinh
      Request inverse hyperbolic sine function.


      Module
      fml


      Syntax
      y = mfASinh(x)



      Descriptions
      Procedure mfASinh(x) returns element-by-element the inverse hyperbolic sine of the
      mfArray x in radians, where

      sinh-1(x) = log[x +(x2+1)1/2].

      The function domain and range include real and complex data.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = (2.d0, -2.d0)
      y = mfASinh(x)
      call msDisplay(x, 'x', y, 'mfASinh(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

       2.0000 -2.0000i

       mfASinh(x) =

       1.7343 -0.7542i


      See Also
      mfASin, mfSin, mfSinh
                                                     Chapter 5 Elementary Math Functions   135



mfATan, msATan
Request inverse tangent function.


Module
fml


Syntax
y = mfATan(x)



Descriptions
Procedure mfATan(x) returns element-by-element the inverse tangent of the mfArray x in
radians, where

tan-1(x) = (i/2)* log((i+x)/(i-x))

The function domain and range include real and complex data.
For real x, the result lies in the range [-π/2, π/2].



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.154d0
y = mfATan(x)
call msDisplay(x, 'x', y, 'mfATan(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.1540

 mfATan(x) =

   0.1528


See Also
mfATan2, mfATanh, mfTan, mfTanh
136       MATFOR 4 in Fortran Reference Guide



      mfATan2, msATan2
      Request four quadrant arctangent function.


      Module
      fml


      Syntax
      z = mfATan2(y, x)



      Descriptions
      Procedure mfATan2(y, x) returns an mfArray z containing element-by-element the
      principal value of the complex number defined by mfArrays y and x, where y is the
      imaginary part and x is the real part.
      For x approaching 0, the function result is approximately mfATan(y/x). However, in contrast
      to mfATan(y/x), which is limited to the range -π/2 <= mfATan(y/x) <= π/2, the function result
      lies in the range of -mfATan2(y,x) in the four quadrants.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 0.5d0
      y = mfATan2(x, x)
      call msDisplay(x, 'x', y, 'mfATan2(x, x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         0.5000

       mfATan2(x, x) =

         0.7854


      See Also
      mfATan, mfATanh, mfTan, mfTanh
                                                     Chapter 5 Elementary Math Functions   137



mfATanh, msATanh
Request inverse hyperbolic tangent function.


Module
fml


Syntax
y = mfATanh(x)



Descriptions
Procedure mfATanh(x) returns element-by-element the inverse hyperbolic tangent of the
mfArray x in radians, where

tan-1(x) = (1/2)* log((1+x)/(1-x))

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 1.5782d0
y = mfATanh(x)
call msDisplay(x, 'x', y, 'mfATanh(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   1.5782

 mfATanh(x) =

 0.7475 -1.5708i


See Also
mfATan, mfATan2, mfTan, mfTanh
138       MATFOR 4 in Fortran Reference Guide



      mfCos, msCos
      Request cosine function.


      Module
      fml


      Syntax
      y = mfCos(x)



      Descriptions
      Procedure mfCos(x) returns element-by-element the circular cosine of mfArray x, where x
      is in radians.

      The function domain and range include real and complex data.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = (3.14d0, -3.14d0)
      y = mfCos(x)
      call msDisplay(x, 'x', y, 'mfCos(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

       3.1400 -3.1400i

       mfCos(x) =

      -11.5736 +0.0184i


      See Also
      mfACos, mfACosh, mfCosh
                                                     Chapter 5 Elementary Math Functions   139



mfCosh, msCosh
Request hyperbolic cosine function.


Module
fml


Syntax
y = mfCosh(x)



Descriptions
Procedure mfCosh(x) returns element-by-element the hyperbolic cosine of mfArray x,
where x is in radians.

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.1d0
y = mfCosh(x)
call msDisplay(x, 'x', y, 'mfCosh(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.1000

 mfCosh(x) =

   1.0050


See Also
mfACos, mfACosh, mfCos
140       MATFOR 4 in Fortran Reference Guide



      mfCot, msCot
      Request cotangent function.


      Module
      fml


      Syntax
      y = mfCot(x)



      Descriptions
      Procedure mfCot(x) returns element-by-element the cotangent of mfArray x in radians
      where

      mfCot(x) = 1/mfTan(x)

      The function domain and range include real and complex data.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 0.7d0
      y = mfCot(x)
      call msDisplay(x, 'x', y, 'mfCot(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         0.7000

       mfCot(x) =

         1.1872


      See Also
      mfCoth, mfACot, mfACoth
                                                     Chapter 5 Elementary Math Functions   141



mfCoth, msCoth
Request hyperbolic cotangent function.


Module
fml


Syntax
y = mfCoth(x)



Descriptions
Procedure mfCoth(x) returns element-by-element the hyperbolic cotangent of the mfArray
x in radians, where

mfCoth(x) = 1/mfTanh(x)

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.5d0
y = mfCoth(x)
call msDisplay(x, 'x', y, 'mfCoth(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.5000

 mfCoth(x) =

   2.1640


See Also
mfCot, mfACot, mfACoth
142         MATFOR 4 in Fortran Reference Guide



      mfCsc, msCsc
      Request cosecant function.


      Module
      fml


      Syntax
      y = mfCsc(x)



      Descriptions
      Procedure mfCsc(x) returns the element-by-element cosecant of mfArray x, where

      mfCsc(x) = 1/mfSin(x)

      The function domain and range include real and complex data. All angles are in radians.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 2.0d0
      y = mfCsc(x)
      call msDisplay(x, 'x', y, 'mfCsc(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =
        2
       mfCsc(x) =

         1.0998


      See Also
      mfCsch, mfACsc, mfACsch
                                                       Chapter 5 Elementary Math Functions   143



mfCsch, msCsch
Request hyperbolic cosecant function.


Module
fml


Syntax
y = mfCsch(x)



Descriptions
Procedure mfCsch(x) returns element-by-element the hyperbolic cosecant of mfArray x,
where

mfCsch(x) = 1/mfSinh(x)

The function domain and range include real and complex data. All angles are in radians.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 0.5d0
y = mfCsch(x)
call msDisplay(x, 'x', y, 'mfCsch(x)')
call msFreeArgs(x, y)
end program example


Result
x =

   0.5000

 mfCsch(x) =

   1.9190


See Also
mfCsc, mfACsc, mfACsch
144         MATFOR 4 in Fortran Reference Guide



      mfSec, msSec
      Request secant function.


      Module
      fml


      Syntax
      y = mfSec(x)



      Descriptions
      Procedure mfSec(x) returns element-by-element the secant of mfArray x, where

      mfSec(x) = 1/mfCos(x)

      The function domain and range include real and complex data. All angles are in radians.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = MF_PI
      y = mfSec(x)
      call msDisplay(x, 'x', y, 'mfSec(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         3.1416

       mfSec(x) =
       -1


      See Also
      mfSech, mfASec, mfASech
                                                       Chapter 5 Elementary Math Functions   145



mfSech, msSech
Request hyperbolic secant function.


Module
fml


Syntax
y = mfSech(x)



Descriptions
Procedure mfSech(x) returns element-by-element the hyperbolic secant of mfArray x,
where

mfSech(x) = 1/mfCosh(x)

The function domain and range include real and complex data. All angles are in radians.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = (-1, 4)
y = mfSech(x)
call msDisplay(x, 'x', y, 'mfSech(x)')
call msFreeArgs(x, y)
end program example


Result
x =

-1.0000 +4.0000i

 mfSech(x) =

-0.5578 -0.4918i


See Also
mfSec, mfASec, mfASech
146       MATFOR 4 in Fortran Reference Guide



      mfSin, msSin
      Request sine function.


      Module
      fml


      Syntax
      y = mfSin(x)



      Descriptions
      Procedure mfSin(x) returns element-by-element the circular sine of mfArray x.

      The function domain and range include real and complex data. All angles are in radians.



      Example

      Code
      program example
      use mod_ess
      use mod_elfun
      implicit none
      type (mfArray) :: x, y
      x = 0.5236d0
      y = mfSin(x)
      call msDisplay(x, 'x', y, 'mfSin(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         0.5236

       mfSin(x) =

         0.5000


      See Also
      mfSinh, mfASin, mfASinh
                                                     Chapter 5 Elementary Math Functions   147



mfSinh, msSinh
Request hyperbolic sine function.


Module
fml


Syntax
y = mfSinh(x)



Descriptions
Procedure mfSinh(x) returns element-by-element the hyperbolic sine of mfArray x,
where x is in radians.

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 3
y = mfSinh(x)
call msDisplay(x, 'x', y, 'mfSinh(x)')
call msFreeArgs(x, y)
end program example


Result
x =
  3
 mfSinh(x) =

   10.0179


See Also
mfSin, mfASin, mfASinh
148         MATFOR 4 in Fortran Reference Guide



      mfTan, msTan
      Request tangent function.


      Module
      fml


      Syntax
      y = mfTan(x)



      Descriptions
      Procedure mfTan(x) returns element-by-element the tangent of mfArray x.

      The function domain and range include real and complex data. All angles are in radians.

      mfTan(x) = mfSin(x)/mfCos(x).



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = 1.0d0
      y = mfTan(x)
      call msDisplay(x, 'x', y, 'mfTan(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =
        1
       mfTan(x) =

         1.5574


      See Also
      mfTanh, mfATan, mfATanh
                                                       Chapter 5 Elementary Math Functions   149



mfTanh, msTanh
Request hyperbolic tangent function.


Module
fml


Syntax
y = mfTanh(x)



Descriptions
Procedure mfTanh(x) returns element-by-element the hyperbolic tangent of mfArray x,
where

mfTanh(x) = mfSinh(x)/mfCosh(x)

The function domain and range include real and complex data. All angles are in radians.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 1
y = mfTanh(x)
call msDisplay(x, 'x', y, 'mfTanh(x)')
call msFreeArgs(x, y)
end program example


Result
x =
  1
 mfTanh(x) =

   0.7616


See Also
mfTan, mfATan, mfATanh
150     MATFOR 4 in Fortran Reference Guide




      Exponential
                                                     Chapter 5 Elementary Math Functions   151



mfExp, msExp
Request exponential function.


Module
fml


Syntax
y = mfExp(x)



Descriptions
Procedure mfExp(x) returns element-by-element the exponential of mfArray x.

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = (2.d0, 3.d0)
y = mfExp(x)
call msDisplay(x, 'x', y, 'mfExp(x)')
call msFreeArgs(x, y)
end program example


Result
x =

 2.0000 +3.0000i

 mfExp(x) =

-7.3151 +1.0427i


See Also
mfLog, mfLog10
152         MATFOR 4 in Fortran Reference Guide



      mfLog, msLog
      Request natural logarithm.


      Module
      fml


      Syntax
      y = mfLog(x)



      Descriptions
      Procedure mfLog(x) returns element-by-element the natural logarithm of mfArray x.

      The function domain and range include real and complex data.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = MF_E
      y = mfLog(x)
      call msDisplay(x, 'x', y, 'mfLog(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

         2.7183

       mfLog(x) =
        1


      See Also
      mfExp, mfLog10, mfLog2
                                                     Chapter 5 Elementary Math Functions   153



mfLog10, msLog10
Request common logarithm (base 10).


Module
fml


Syntax
y = mfLog10(x)



Descriptions
Procedure mfLog10(x) returns element-by-element the base 10 logarithm of mfArray x.

The function domain and range include real and complex data.



Example

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = 5.d0
y = mfLog10(x)
call msDisplay(x, 'x', y, 'mfLog10(x)')
call msFreeArgs(x, y)
end program example


Result
x =
  5
 mfLog10(x) =

   0.6990


See Also
mfExp, mfLog, mfLog2
154       MATFOR 4 in Fortran Reference Guide



      mfLog2, msLog2
      Base 2 logarithm and floating-point dissection.


      Module
      fml


      Syntax
      y = mfLog2(x)
      call msLog2(mfOut(f, e), x)



      Descriptions
      Procedure msLog2 computes base 2 logarithm or extract mantissa and exponent of a
      floating-point number.

      y = mfLog2(x) returns the elemental base 2 logarithm of mfArray x.

      call msLog2(mfOut(f,e),x) dissects each element of mfArray x into the binary
      floating-point format consisting of a mantissa, mfArray f, and an exponent, mfArray e, where x
            e
      = f*2 for real x. mfArray f contains real values lying in the range of 0.5 <= mfAbs(f) < 1. For
      elements of x = 0, the corresponding elements of f and e are equal to zero.



      Example
      The example below evaluates the mfLog2 of mfArray x.

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y, f, e
      ! MF_PI is MATFOR intrinsic parameter for pi.
      x = (/MF_PI, 2* MF_PI, 3* MF_PI/)
      y = mfLog2(x)
      call   msLog2(mfout(f, e), x)
      call   msDisplay(y, 'mfLog2(x)' )
      call   msDisplay(f, 'the mantissa', e, 'the exponent')
      call   msFreeArgs(x, y, f, e)
      end program example


      Result
      mfLog2(x) =

         1.6515      2.6515     3.2365

       the mantissa =
                             Chapter 5 Elementary Math Functions   155



  0.7854   0.7854   0.5890

the exponent =
 2 3 4


See Also
mfLog, mfPow2, mfLog10
156        MATFOR 4 in Fortran Reference Guide



      mfPow2, msPow2
      Base 2 power and floating point number scaling.


      Module
      fml


      Syntax
      y = mfPow2(x)
      y = mfPow2(f,e)



      Descriptions
      Procedure mfPow2 computes base 2 power or floating point number scaling.

      y = mfPow2(x) returns an mfArray y with elements computed from two raised to the power of
                                            x
      each element of mfArray x, i.e., y = 2 .

                                                                                                  e
      y = mfPow2(f, e) returns the mfArray y containing elements computed from y = f*2 . The
      result is equivalent to scaling each element of f by exponent e or adding each element of e to the
      corresponding floating-point exponent of e.



      Example
      The example below evaluates the mfPow2 of mfArray x, a 1-by-10 vector.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: x, y, z, f, e
      !   Initialize the mfArrays
      x   = 3
      f   = (/1.0, 0.5, -0.75/)
      e   = (/2, 3, 5/)
      ! Compute base 2 power y = 2**x
      y = mfPow2(x)
      ! Perform floating point scaling z = f*(2**e)
      z = mfPow2(f, e)
      ! Display the values
      call msDisplay(x, 'x', y, 'mfPow2(x)')
      call msDisplay(f, 'f', e, 'e', z, 'mfPow2(f, e)')
      ! Deallocate mfArrays
      call msFreeArgs(x, y, z, f, e)
      end program example


      Result
                            Chapter 5 Elementary Math Functions   157

x =
 3
mfPow2(x) =
 8
f =

  1.0000   0.5000 -0.7500

e =
 2 3 5
mfPow2(f, e) =
  4   4 -24


See Also
mfLog2, mfExp
158         MATFOR 4 in Fortran Reference Guide



      mfSqrt, msSqrt
      Square root function.


      Module
      fml


      Syntax
      y = mfSqrt(x)



      Descriptions
      Procedure mfSqrt(x) returns element-by-element the square root of mfArray x.

      The procedure domain includes real and complex data.
      For negative and complex elements of x, complex results are returned.



      Example
      The example below evaluates mfSqrt(-4).

      Code
      program example
      use fml
      implicit none
      type (mfArray):: x, y
      x = -4
      y = mfSqrt(x)
      call msDisplay(x, 'x', y, 'mfSqrt(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =
       -4
       mfSqrt(x) =

       0.0000 +2.0000i


      See Also
      mfExp, mfLog, mfLog2, mfLog10
          Chapter 5 Elementary Math Functions   159




Complex
160       MATFOR 4 in Fortran Reference Guide



      mfAbs, msAbs
      Absolute value of real and complex numbers.


      Module
      fml


      Syntax
      y = mfAbs(x)



      Descriptions
      Procedure mfAbs(x) returns element-by-element the absolute of mfArray x.

      For real x, mfAbs(x) returns |x|.

      For complex z = x + iy, mfAbs(z) returns the magnitude of the complex computed as
      sqrt(x2+y2).



      Example
      The example below evaluates the absolute value of complex number (2, -2)

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = (2, -2)
      y = mfAbs(x)
      call msDisplay(x, 'x', y,'mfAbs(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

       2.0000 -2.0000i

       mfAbs(x) =

         2.8284


      See Also
      mfAngle, mfSign
                                                     Chapter 5 Elementary Math Functions   161



mfAngle, msAngle
Phase angle of complex numbers.


Module
fml


Syntax
p = mfAngle(z)



Descriptions
Procedure mfAngle(z) returns an mfArray p containing the element-by-element phase
angle of complex mfArray z.



Example
The example below evaluates the phase angle of complex mfArray z over a range of value.

Code
program example
use fml
implicit none
type(mfArray) :: theta, z, x, y
x = mfColon(0, 5, 10)
y = mfColon(-2, 5, 8)
z = mfComplex(x, y)
theta = mfAngle(z)
call msDisplay(z, 'z', theta, 'mfAngle(z)')
call msFreeArgs(theta, z, x, y)
end program example


Result
z =
column     1 to     3
  0.0000 -2.0000i         5.0000 +3.0000i         10.0000 +8.0000i

 mfAngle(z) =

  -1.5708      0.5404    0.6747


See Also
mfAbs
162       MATFOR 4 in Fortran Reference Guide



      mfComplex, msComplex
      Convert input numbers into complex numbers.


      Module
      fml


      Syntax
      z = mfComplex(x, y)
      z = mfComplex(x)

      Descriptions
      Procedure mfComplex(x, y) returns a complex mfArray whose real part is specified by the
      elements of mfArray x and imaginary part is specified by elements of mfArray y i.e.
      z = x + yi.

      z = mfComplex(x) returns a complex mfArray whose real part is specified by the elements of
      mfArray x and imaginary part is zero i.e. z = x + 0i.

      Example
      The example below constructs a complex mfArray z from two real mfArrays x and y.

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: z, x, y
      x = (/-5, 7, 0/)
      y = (/ 3, 1, 2/)
      z = mfComplex(x, y)
      call msDisplay(x, 'x', y, 'y', z, 'mfComplex(x, y)')
      call msFreeArgs(x, y, z)
      end program example

      Result
      x =
       -5 7 0
       y =
        3 1 2
       mfComplex(x, y) =

      -5.0000 +3.0000i         7.0000 +1.0000i      0.0000 +2.0000i


      See Also
      mfImag, mfReal
                                                   Chapter 5 Elementary Math Functions   163



mfConj, msConj
Returns conjugate of complex numbers.


Module
fml


Syntax
c = mfConj(z)



Descriptions
Procedure mfConj(z) returns an mfArray containing the element-by-element conjugate of
complex mfArray z.



Example
The example below evaluates the conjugate of complex mfArray z.

Code
program example
use fml
implicit none
type (mfArray) :: c, z
z = (-2, 2)
c = mfConj(z)
call msDisplay(z, 'z', c, 'mfConj(z)')
call msFreeArgs(c, z)
end program example


Result
z =

-2.0000 +2.0000i

 mfConj(z) =

-2.0000 -2.0000i


See Also
mfImag, mfReal
164         MATFOR 4 in Fortran Reference Guide



      mfImag, msImag
      Returns imaginary part of complex numbers.


      Module
      fml


      Syntax
      y = mfImag(z)



      Descriptions
      Procedure mfImag(z) returns element-by-element the imaginary part of complex mfArray
      z.



      Example
      The example below gets the imaginary part of complex mfArray z.

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y
      x = (2, -2)
      y = mfImag(x)
      call msDisplay(x, 'x', y, 'mfImag(x)')
      call msFreeArgs(x, y)
      end program example


      Result
      x =

       2.0000 -2.0000i

       mfImag(x) =
       -2


      See Also
      mfReal, mfConj
                                                    Chapter 5 Elementary Math Functions   165



mfReal, msReal
Returns real part of complex numbers.


Module
fml


Syntax
x = mfReal(z)



Descriptions
Procedure mfReal(z) returns element-by-element the real part of complex mfArray z.



Example
The example below gets the real part of complex mfArray z.

Code
program example
use fml
implicit none
type (mfArray) :: z, x
z = (-2, 2)
x = mfReal(z)
call msDisplay(z, 'z', x, 'mfReal(z)' )
call msFreeArgs(z, x)
end program example


Result
z =

-2.0000 +2.0000i

 mfReal(z) =
 -2


See Also
mfImag, mfConj
166    MATFOR 4 in Fortran Reference Guide




      Rounding and Remainder
                                                        Chapter 5 Elementary Math Functions      167



mfCeil, msCeil
Round mfArray elements toward positive infinity.


Module
fml


Syntax
y = mfCeil(x)



Descriptions
Procedure mfCeil(x) returns an mfArray containing the elements of mfArray x rounded to
the nearest integer toward positive infinity. The real and imaginary parts of a complex number
are rounded independently.



Example
The example below performs the mfCeil operation on mfArray x.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, u, v
x   =   (/-1.6, 2.3/)
u   =   (3.2, 2.2)
y   =   mfCeil(x)
v   =   mfCeil(u)
call msDisplay(x, 'x', y, 'mfCeil(x)')
call msDisplay(u, 'u', v, 'mfCeil(u)')
call msFreeArgs(x, y, u, v)
end program example


Result
x =

    -1.6000    2.3000

 mfCeil(x) =
 -1 3
 u =

 3.2000 +2.2000i

 mfCeil(u) =
168      MATFOR 4 in Fortran Reference Guide

      4.0000 +3.0000i


      See Also
      mfFix, mfFloor, mfRound
                                                  Chapter 5 Elementary Math Functions   169



mfFix, msFix
Round mfArray elements toward zero.


Module
fml


Syntax
y = mfFix(x)



Descriptions
Procedure mfFix(x) returns an mfArray containing the elements of mfArray x rounded to
the nearest integer toward zero. The real and imaginary parts of a complex number are
rounded independently.



Example
The example below performs the mfFix operation on mfArray x.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, u, v
x   =   (/-1.6, 2.3/)
y   =   mfFix(x)
u   =   dcmplx(3.2, 2.2)
v   =   mfFix(u)
call msDisplay(x, 'x', y, 'mfFix(x)')
call msDisplay(u, 'u', v, 'mfFix(u)')
call msFreeArgs(x, y, u, v)
end program example


Result
x =

    -1.6000    2.3000

 mfFix(x) =
 -1 2
 u =

 3.2000 +2.2000i

 mfFix(u) =
170      MATFOR 4 in Fortran Reference Guide

      3.0000 +2.0000i


      See Also
      mfCeil, mfFloor, mfRound
                                                     Chapter 5 Elementary Math Functions     171



mfFloor, msFloor
Round mfArray elements toward minus infinity.


Module
fml


Syntax
y = mfFloor(x)



Descriptions
Procedure mfFloor(x) returns an mfArray containing the elements of mfArray x rounded
to the nearest integer toward negative infinity. The real and imaginary parts of a complex
number are rounded independently.



Example
The example below performs the mfFloor operation on mfArray x.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, u, v
x   =   (/-1.6, 2.3/)
u   =   (3.2, 2.2)
y   =   mfFloor(x)
v   =   mfFloor(u)
call msDisplay(x, 'x', y, 'mfFloor(x)')
call msDisplay(u, 'u', v, 'mfFloor(u)')
call msFreeArgs(x, y, u, v)
end program example


Result
x =

    -1.6000    2.3000

 mfFloor(x) =
 -2 2
 u =

 3.2000 +2.2000i

 mfFloor(u) =
172      MATFOR 4 in Fortran Reference Guide

      3.0000 +2.0000i


      See Also
      mfCeil, mfFix, mfRound
                                                      Chapter 5 Elementary Math Functions   173



mfMod, msMod
Returns modulus (signed remainder after division).


Module
fml


Syntax
m = mfMod(x, y)



Descriptions
Procedure mfMod(x, y) returns an mfArray containing element-by-element the signed
remainder of x, y division. The procedure uses the following algorithm:

y ≠0, mfMod(x, y) = x - y*mfFloor(x/y)
y = 0, mfMod(x, y) = x.

Note that :
• The shape of the input arguments x and y must conform.
•   mfMod(x, y) always differs from x by a multiple of y.
•   mfMod(x, y) has the same sign as y while mfRem(x,y) has the same sign as x.
•   mfMod(x, y) and mfRem(x, y) are equal if x and y are of the same sign. They differ if
    the sign of x and y are different.

Limitations: Arguments x and y should be integers. Due to the inexact representation of
floating-point numbers on a computer, real (or complex) inputs may lead to unexpected
results.



Example
The example below finds the modulus of x and y.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, m
x = (/-5, 7, -15/)
y = (/2, -3, -4/)
m = mfMod(x, y)
call msDisplay(x, 'x', y, 'y', m, 'mfMod(x,y)')
call msFreeArgs(x, y, m)
end program example
174      MATFOR 4 in Fortran Reference Guide


      Result
      x =
       -5      7 -15
      y =
       2 -3 -4
      mfMod(x,y) =
       1 -2 -3


      See Also
      mfRem
                                                      Chapter 5 Elementary Math Functions   175



mfRem, msRem
Returns remainder after division.


Module
fml


Syntax
r = mfRem(x, y)



Descriptions
Procedure mfRem(x, y) returns an mfArray containing the element-by-element remainder of
x/y division. The result lies between 0 and mfSign(x)*mfAbs(y). The input x and y are
either scalars or conformable arrays.

Note that :
• mfRem(x,y) = x - y*mfFix(x/y) for y ≠0
•    mfFix(x,y) is the integer of the quotient x/y.
• If y is zero, mfRem returns MF_NAN.
Limitations: Arguments x and y should be integers. Due to the inexact representation of
floating-point numbers on a computer, real (or complex) inputs may lead to unexpected
results.



Example
The example below finds the remainder of x/y.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, r
x = (/-5, 7, -15/)
y = (/2, -3, -4/)
r = mfRem(x,y)
call msDisplay(x, 'x', y, 'y', r, 'mfRem(x,y)')
call msFreeArgs(x, y, r)
end program example


Result
x =
    -5   7 -15
 y =
    2 -3 -4
176      MATFOR 4 in Fortran Reference Guide


      mfRem(x,y) =
      -1 1 -3


      See Also
      mfMod
                                                   Chapter 5 Elementary Math Functions   177



mfRound, msRound
Round towards nearest integer.


Module
fml


Syntax
y = mfRound(x)
call msRound(mfOut(y), x)



Descriptions
Procedure mfRound(x) rounds the elements of mfArray x to the nearest integer. The real
and imaginary parts of a complex number are rounded independently.



Example
The example below performs the round operation on mfArray x.

Code
program example
use fml
implicit none
type (mfArray) :: x, y, u, v
x = (/-1.6, 2.3/)
u = (3.2, 2.2)
y = mfRound(x)
v = mfRound(u)
call msDisplay(x, 'x', y, 'mfRound(x)')
call msDisplay(u, 'u', v, 'mfRound(u)')
call msFreeArgs(x, y, u, v)
end program example


Result
x =

  -1.6000      2.3000

 mfRound(x) =
 -2 2
 u =

 3.2000 +2.2000i

 mfRound(u) =
178      MATFOR 4 in Fortran Reference Guide


      3.0000 +2.0000i


      See Also
      mfCeil, mfFix, mfFloor
                                                     Chapter 5 Elementary Math Functions   179



mfSign, msSign
Signum function.


Module
fml


Syntax
y = mfSign(x)



Descriptions
Procedure mfSign(x) returns an mfArray y containing the element-by-element information
on the sign of each element in mfArray x.

Note that :
For elements x >0, corresponding element of y = 1.
For elements x = 0, corresponding element of y = 0.
For elements x < 0, corresponding element of y = -1.

For nonzero elements of complex x, mfSign(x) = x/mfAbs(x).

Example
The example below finds the sign of elements of mfArray x.

Code
program example
use fml
implicit none
type (mfArray) :: x, y
x = (/-5, 7, 0/)
y = mfSign(x)
call msDisplay(x, 'x', y, 'mfSign(x)')
call msFreeArgs(x, y)
end program example


Result
x =
 -5 7 0
 mfSign(x) =
 -1 1 0


See Also
mfAbs
180   MATFOR 4 in Fortran Reference Guide
                                                                  Chapter 7 Matrix Functions   181



CHAPTER 6




Elementary Matrix-manipulation
Functions

 This chapter describes the elementary matrix-manipulation functions. Please see
 below




 Matrices

 mfEye                    Identity matrix

 mfLinSpace               Constructs linearly spaced vectors.

 mfMagic                  Constructs magic matrix.

 msMeshgrid               Constructs grids for two matrices.

 mfRepmat                 Replicate and tile an array.

 mfOnes                   Arrays containing ones.

 mfRand                   Arrays containing random numbers.

 mfZeros                  Arrays containing zeros.




 Matrix Manipulation

 mfDiag                   Diagonal matrices and diagonals of a matrix.

 mfFind                   Find indices and values of nonzero elements.

 mfReshape                Change shape of an array.

 mfTril                   Returns lower triangular of an mfArray.

 mfTriu                   Returns upper triangular of an mfArray.

 mfLogical                Converts numerical values to logical.
182   MATFOR 4 in Fortran Reference Guide
           Chapter 7 Matrix Functions   183




Matrices
184       MATFOR 4 in Fortran Reference Guide



      mfEye, msEye
      Construct an identity matrix.


      Module
      fml


      Syntax
      a = mfEye(m[, n])



      Descriptions
      Procedure mfEye generates an identity matrix.

      a = mfEye(m) returns an m-by-m identity matrix for scalar m. If mfArray m contains
      information about the shape of an array, mfEye returns mfArray whose shape is specified by m.
      For example, a = mfEye(mfShape(b)).

      a = mfEye(m, n) returns an m-by-n identity matrix.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a,b
      b = mfRand(3,3)
      a = mfEye(mfShape(b))
      call msDisplay(a, 'mfEye(3,3)')
      call msFreeArgs(a,b)
      end program example


      Result
      mfEye(3,3) =
        1 0 0
        0 1 0
        0 0 1


      See Also
      mfOnes, mfZeros
                                                                   Chapter 7 Matrix Functions   185



mfColon, msColon
Construct a vector mfArray consisting of a ramp of data.


Module
fml


Syntax
x = mfColon(start[, step][, end])



Descriptions
Function mfColon constructs a regularly spaced vector mfArray. The input arguments,
start, step and end can be integers or real. For complex inputs, imaginary parts are
ignored.

x = mfColon(a, b, c)
• Vector mfArray x is constructed with elements [a, a+b, ..., a+b*m, ...,c] where m =
    mfFix((c-a)/b).
•   The procedure returns empty when b>0, a>c, or when b<0, a<c.

x = mfColon(a, c)
• Vector mfArray x is constructed with elements [a, a+1, ...,c].
•   It returns empty if a>c.



Example
The following example constructs an mfArray x by using mfColon.

Code
program example
use fml
implicit none
type (mfArray) :: x
x = mfColon(1d0, 0.5d0, 2d0)
call msDisplay (x, 'x')
call msFreeArgs(x)
end program example

Result
x =

    1.0000     1.5000     2.0000

See Also
186       MATFOR 4 in Fortran Reference Guide



      mfLinspace, msLinspace
      Construct a linearly spaced vector.


      Module
      fml


      Syntax
      a = mfLinSpace(l, u)
      a = mfLinSpace(l, u, n)



      Descriptions
      Procedure mfLinSpace generates linearly spaced row vectors.

      a = mfLinSpace(l, u) returns a row vector mfArray with 100 linearly and equally spaced
      points between l and u, where l is the initial value and u is the final value.

      a = mfLinSpace(l, u, n) generates n linearly and equally spaced points between l and u.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a
      a = mfLinspace(3, 4, 5)
      call msDisplay(a, 'mfLinspace(3, 4, 5)')
      call msFreeArgs(a)
      end program example


      Result
      mfLinspace(3, 4, 5) =

         3.0000      3.2500     3.5000      3.7500   4.0000


      See Also
      mfColon, mfMeshgrid
                                                               Chapter 7 Matrix Functions     187



mfMagic, msMagic
Construct a magic square.


Module
fml


Syntax
a = mfMagic(m)



Descriptions
Procedure mfMagic creates a magic square mfArray. A magic square is a special matrix with
equal row, column and diagonal sums.

a = mfMagic(m) generates an m-by-m magic matrix constructed from the integers 1 through m2.
This procedure produces valid magic squares for all m > 0, except for m = 2.

Example

Code
program example
use fml
implicit none
type (mfArray) :: a, rsum, csum
a = mfMagic(3)
rsum = mfSum(a, 2)
csum = mfSum(a, 1)
call msDisplay(a, 'mfMagic(3)', rsum, 'row sum', csum, 'column sum')
call msFreeArgs(a, rsum, csum)
end program example

Result
mfMagic(3) =
  8 1 6
  3 5 7
  4 9 2
 row sum =
  15
  15
  15
 column sum =
  15 15 15

See Also
mfZeros, mfOnes
188       MATFOR 4 in Fortran Reference Guide



      mfMeshgrid, msMeshgrid
      Generate x and y matrices for three-dimensional plots.


      Module
      fml


      Syntax
      call msMeshgrid(mfOut(a, b), m)
      call msMeshgrid(mfOut(a, b), m, n)
      call msMeshgrid(mfOut(a, b, c), m, n, k)



      Descriptions
      Procedure msMeshgrid generates grids from two matrices to make three-dimensional plots.

      •   call msMeshgrid(mfOut(a, b), m, n) transforms the domain specified by vectors
          m and n into matrix mfArrays a and b. The rows of output matrix a are copies of vector m
          and the columns of output matrix b are copies of vector n.

      •   call msMeshgrid(mfOut(a, b), m) is an abbreviation for call
          msMeshgrid(mfOut(a, b), m, n).

      •   call msMeshgrid(mfOut(a, b, c), m, n, k) returns three-dimensional arrays
          that can be used to evaluate functions of three variables and make three-dimensional
          volumetric plots.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: x, y, a, b
      ! Generate vectors a and b using the colon function.
      a = mfColon(-1d0, 0.5d0, 1d0)
      b = mfColon(-1.5d0, 0.3d0, 1.5d0)
      ! Use the meshgrid procedure to transform the domain
      ! specified by vectors a and b into a two-dimensional function domain.
      call msMeshgrid(mfOut(x, y), a, b)
      ! Display the generated matrices.
      call msDisplay(x, 'x', y, 'y')
      ! Release the memory occupied by the mfArrays at the
      ! end of the program.
                                                    Chapter 7 Matrix Functions   189

call msFreeArgs(x, y, a, b)
end program example


Result
x =

 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000
 -1.0000   -0.5000    0.0000    0.5000    1.0000

y =

 -1.5000   -1.5000    -1.5000   -1.5000   -1.5000
 -1.2000   -1.2000    -1.2000   -1.2000   -1.2000
 -0.9000   -0.9000    -0.9000   -0.9000   -0.9000
 -0.6000   -0.6000    -0.6000   -0.6000   -0.6000
 -0.3000   -0.3000    -0.3000   -0.3000   -0.3000
  0.0000    0.0000    0.0000    0.0000    0.0000
  0.3000    0.3000    0.3000    0.3000    0.3000
  0.6000    0.6000    0.6000    0.6000    0.6000
  0.9000    0.9000    0.9000    0.9000    0.9000
  1.2000    1.2000    1.2000    1.2000    1.2000
  1.5000    1.5000    1.5000    1.5000    1.5000


See Also
mfLinSpace, mfColon
190       MATFOR 4 in Fortran Reference Guide



      mfOnes, msOnes
      Construct a matrix of ones.


      Module
      fml


      Syntax
      a = mfOnes(m)
      a = mfOnes(m, n)
      a = mfOnes(m, n[, d3, ..., d7])



      Descriptions
      Procedure mfOnes generates a matrix containing ones.

      a = mfOnes(m) returns an m-by-m matrix of ones.

      a = mfOnes(m, n) returns an m-by-n matrix of ones.

      a = mfOnes(m, n, d3, ..., d7) returns an m-by-n-by-d3-by-...-by-d7 array of ones.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a
      a = mfOnes(3, 2)
      call msDisplay(a, 'mfOnes(3, 2)')
      call msFreeArgs(a)
      end program example


      Result
      mfOnes(3, 2) =
        1 1
        1 1
        1 1


      See Also
      mfZeros, mfEye
                                                              Chapter 7 Matrix Functions   191



mfRand, msRand
Generate mfArrays with uniformly distributed random number entries.


Module
fml


Syntax
a = mfRand(m)
a = mfRand(m, n)
a = mfRand(m, n[, d3, ..., d7])



Descriptions
Procedure mfRand randomly generates an mfArray.

a = mfRand(m) returns an m-by-m matrix with random entries chosen from a uniform
distribution on the interval (0, 1).

a = mfRand(m, n) generates an m-by-n matrix with random entries chosen from a uniform
distribution on the interval (0, 1).

a = mfRand(m, n, d3, ..., d7) generates a m-by-n-by-d3-by-...-by-d7 matrix with
random entries chosen from a uniform distribution on the interval (0,1).



Example

Code
program example
use fml
implicit none
type (mfArray) :: a
a = mfRand(3, 2)
call msDisplay(a, 'mfRand(3, 2)')
call msFreeArgs(a)
end program example

Result
mfRand(3, 2) =

   0.5497      0.0012
   0.5496      0.6887
   0.4378      0.6035

See Also
mfZeros, mfOnes, mfMagic
192       MATFOR 4 in Fortran Reference Guide



      mfRepmat, msRepmat
      Replicate and tile an array.


      Module
      fml


      Syntax
      x = mfRepmat(a, m, n)
      x = mfRepmat(a, p)

      call msRepmat(mfOut(x), a, m, n)
      call msRepmat(mfOut(x), a, p)



      Descriptions
      Procedure mfRepmat generates mfArray matrices by replicating copies of an array into a
      larger block array.

      x = mfRepmat(a, m, n) and call msRepmat(mfOut(x), a, m, n) generate an
      mfArray x consisting of m-by-n tiling of vector mfArray a copies.

      x = mfRepmat(a, p) and call msRepmat(mfOut(x), a, p) generate an mfArray
      x containing p block copies of mfArray a. Vector p contains information about the number of
      mfArray x blocks in each dimension. The information is in the form of [m, n], or
      [m, n, d3, ..., d7].



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a
      ! Create a 3-by-2 mfArray consisting of ones.
      a = mfRepmat(mf(1), mf((/3, 2/)))
      ! This is similar to mfOnes(3,2) but is much faster.
      call msDisplay (a, ' mfRepmat(mf(1), mf((/3,2/)))')
      ! Create 3-by-2 block copies of mfMagic(3)
      a = mfRepmat(mfMagic(2), mf((/3,2/)))
      call msDisplay (a, 'mfRepmat(mfMagic(2), (/3,2/))')
      ! Deallocate mfArrays.
      call msFreeArgs(a)
      end program example


      Result
                                  Chapter 7 Matrix Functions   193

mfRepmat(mf(1), mf((/3,2/))) =
 1 1
 1 1
 1 1
mfRepmat(mfMagic(2), (/3,2/)) =
 1   3     1   3
 4   2     4   2
 1   3     1   3
 4   2     4   2
 1   3     1   3
 4   2     4   2


See Also
mfMeshgrid
194       MATFOR 4 in Fortran Reference Guide



      mfZeros, msZeros
      Generate matrices with all zeros.


      Module
      fml


      Syntax
      a = mfZeros(m)
      a = mfZeros(m, n)
      a = mfZeros(m, n[, d3, ..., d7])



      Descriptions
      Procedure mfZeros generates the mfArrays of zeros. It is used to allocate memory for
      mfArrays.

      a = mfZeros(m) returns an m-by-m mfArray of zeros.

      a = mfZeros(m, n) returns an m-by-n mfArray of zeros.

      a = mfZeros(m, n, d3, ..., d7) returns an m-by-n-by-d3-by-...-by-d7 array of zeros.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a
      a = mfZeros(2, 2)
      call msDisplay(a, 'mfZeros(2, 2)')
      call msFreeArgs(a)
      end program example


      Result
      mfZeros(2, 2) =
        0 0
        0 0


      See Also
      mfOnes, mfEye
                      Chapter 7 Matrix Functions   195




Matrix Manipulation
196       MATFOR 4 in Fortran Reference Guide



      mfDiag, msDiag
      Request diagonals of a matrix.


      Module
      fml


      Syntax
      d = mfDiag(a[, k])
      a = mfDiag(d[, k])



      Descriptions
      Procedure mfDiag(a) returns a vector mfArray d containing the elements extracted from
      the main diagonal of matrix mfArray a.

      a = mfDiag(d) returns a diagonal matrix mfArray a, with its main diagonal composed of
      member elements of vector d.

      d = mfDiag(a, k) returns a vector mfArray d, containing the elements extracted from the kth
      diagonal of matrix mfArray a.

      a = mfDiag(d, k) returns a diagonal matrix a of order mfLength(d) + mfAbs(k) whose kth
      diagonal is composed of elements from vector mfArray d. k = 0 represents the main diagonal, k >
      0 is above the main diagonal, and k < 0 is below the main diagonal.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a, d, b
      ! Construct an mfArray using the magic function.
      a = mfMagic(3)
      ! Extract the 1st diagonal of mfArray a.
      d = mfDiag(a, 1)
      ! Construct an mfArray b, whose main diagonal is
      ! composed of d.
      b = mfDiag(d)
      ! Display the resulting mfArrays.
      call msDisplay(a, 'mfMagic(3)', d, 'k = 1 diagonal')
      call msDisplay(b, 'mfDiag(d)')
      ! Release the memory occupied by mfArrays a ,b, and d.
      call msFreeArgs(a, b, d)
      end program example
                   Chapter 7 Matrix Functions   197




Result
mfMagic(3) =
 8 1 6
 3 5 7
 4 9 2
k = 1 diagonal =
 1
 7
mfDiag(d) =
 1 0
 0 7


See Also
mfTriu, mfTril
198       MATFOR 4 in Fortran Reference Guide



      mfFind, msFind
      Find indices of nonzero elements.


      Module
      fml


      Syntax
      y = mfFind(x)

      call msFind(mfOut(i, j), x)
      call msFind(mfOut(i, j, v), x)



      Descriptions
      Procedure mfFind generates indices of nonzero elements.

      y = mfFind(x) returns an mfArray y containing long column indices of nonzero entries in
      mfArray x. If none are found, mfFind returns an empty matrix.

      call msFind(mfOut(i, j), x) returns two mfArrays i and j containing the row and
      column indices of nonzero entries in matrix mfArray x.

      call msFind(mfOut(i, j, v), x) returns three mfArrays i, j, and v containing the
      row indices, column indices, and nonzero entries of matrix mfArray x respectively.



      Example
      The example below retrieves the indices of non-zero elements of a matrix mfArray.

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a, i, j
      a = mfMagic(3) > 7
      call msFind(mfOut(i,j), a)
      call msDisplay(a, 'a', i, 'i', j, 'j')
      call msFreeArgs(a, i, j)
      end program example


      Result
      a =
        1 0 0
        0 0 0
        0 1 0
                                Chapter 7 Matrix Functions   199

i =
 1
 3
j =
 1
 2


See Also
mfColon, relational_operators
200           MATFOR 4 in Fortran Reference Guide



      mfLogical, msLogical
      Convert numeric values to logical values.


      Module
      fml


      Syntax
      l = mfLogical(x)



      Descriptions
      Procedure mfLogical(x) returns a logical mfArray. An element of mfArray l is assigned
      logical "true" if the corresponding element in mfArray x is nonzero, otherwise it is assigned
      "false".

      Note: Most arithmetic operations remove the logical characteristic from an array. For example,
      adding zero to a logical array.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: b, x, y, z
      x   =    mfEye(3)
      b   =    mfLogical(x)
      y   =    (/1,2,3/) .vc. (/4,5,6/) .vc. (/7,8,9/)
      z   =    mfS(y, b)
      call msDisplay(y, 'y', z, 'z')
      call msFreeArgs(b, x, y, z)
      end program example

      Result
      y =
          1 2 3
          4 5 6
          7 8 9
       z =
          1
          5
          9

      See Also
      mfZeros, mfOnes, mfMagic
                                                              Chapter 7 Matrix Functions    201



mfReshape, msReshape
Change size of an mfArray.


Module
fml


Syntax
y = mfReshape(x, m, n)
a = mfReshape(b, m[, n, d3,...,d7])



Descriptions
Procedure mfReshape reshapes arrays.

y = mfReshape(x, m, n) returns the m-by-n matrix mfArray y whose elements are taken
column-wise from mfArray x. An error occurs if x does not have m*n entries.
a = mfReshape(b, m, n, d3, ..., d7) returns the m-by-n-by-d3-...-d7 array mfArray
a whose elements are taken column-wise from mfArray b. An error occurs if b does not have
m*n*d3*...*d7 entries.



Example

Code
program example
use fml
implicit none
type(mfArray):: x, y
x = (/1, 2, 3, 4, 5, 6/)
y = mfReshape(x, (/3, 2/))
call msDisplay(x, 'x', y, 'mfReshape(x, (/3, 2/))')
call msFreeArgs(x, y)
end program example


Result
x =
  1 2 3     4 5 6
 mfReshape(x, (/3, 2/)) =
  1 4
  2 5
  3 6


See Also
mfSize
202       MATFOR 4 in Fortran Reference Guide



      mfTril
      Return the lower triangular part of a matrix.


      Module
      fml


      Syntax
      l = mfTril(a[, k])



      Descriptions
      Procedure mfTril returns the lower triangular part of a matrix.

      l = mfTril(a) returns an mfArray l containing the elements on and below the main diagonal
      of mfArray a.

      l = mfTril(a, k) returns an mfArray l containing the elements on and below the kth
      diagonal of mfArray a. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is
      below the main diagonal.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a, l, l1
      ! Construct an mfArray using the magic function.
      a = mfMagic(3)
      ! Get the lower triangular of mfArray a from the main
      ! diagonal downwards.
      l = mfTril(a)
      ! Get the lower triangular a from the 1sdiagonal downwards.
      l1 = mfTril(a, 1)
      ! Display the resulting mfArrays.
      call msDisplay(a, 'mfmagic(3)', l, 'lower triangular')
      call msDisplay(l1, 'lower triangular from k = 1')
      ! Release the memory occupied by mfArrays a, l, and l1.
      call msFreeargs(a, l, l1)
      end program example


      Result
      mfmagic(3) =
        8 1 6
        3 5 7
                                Chapter 7 Matrix Functions   203

 4 9 2
lower triangular =
 8 0 0
 3 5 0
 4 9 2
lower triangular from k = 1 =
 8 1 0
 3 5 7
 4 9 2


See Also
mfTriu, mfDiag
204       MATFOR 4 in Fortran Reference Guide



      mfTriu
      Return the upper triangular part of a matrix.


      Module
      fml


      Syntax
      u = mfTriu(a[, k])



      Descriptions
      Procedure mfTriu returns the upper triangular part of a matrix.

      u = mfTriu(a) returns an mfArray u containing the elements on and above the main diagonal
      of mfArray a.

      u = mfTriu(a, k) returns an mfArray u containing the elements on and above the kth
      diagonal of mfArray a. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is
      below the main diagonal.



      Example

      Code
      program example
      use fml
      implicit none
      type (mfArray) :: a, u, u1
      ! Construct an mfArray using the magic function.
      a = mfMagic(3)
      ! Extract the upper triangular of mfArray a from the main
      ! diagonal upwards.
      u = mfTriu(a)
      ! Extract the upper triangular a from the 1sdiagonal upwards.
      u1 = mfTriu(a, 1)
      ! Display the resulting mfArrays.
      call msDisplay(a, 'mfMagic(3)', u, 'upper triangular')
      call msDisplay(u1, 'upper triangular from k = 1')
      ! Release the memory occupied by mfArrays a, u, and u1.
      call msFreeArgs(a, u, u1)
      end program example


      Result
      mfMagic(3) =
        8 1 6
        3 5 7
                                Chapter 7 Matrix Functions   205

 4 9 2
upper triangular =
 8 1 6
 0 5 7
 0 0 2
upper triangular from k = 1 =
 0 1 6
 0 0 7
 0 0 0


See Also
mfTril, mfDiag
206   MATFOR 4 in Fortran Reference Guide
                                                                   Chapter 7 Matrix Functions   207



CHAPTER 7

Matrix Functions


 This chapter introduces a set of matrix functions for solving linear algebra
 problems, please see below:




 Matrix Analysis

                    mfDet

                    mfNorm

                    mfRank

                    mfTrace




 Linear Equations

                    mfChol

                    mfCond

                    mfInv

                    mfRcond

                    mfLu

                    mfQr
208      MATFOR 4 in Fortran Reference Guide



      Eigenvalues and singular values

                         mfEig

                         mfHess

                         mfQz

                         mfSchur

                         mfSvd




      Factorization Utilities

                         mfBalance




      Fast Fourier Transform



                         mfFFT

                         mfIFFT

                         mfFFT2

                         mfIFFT2

                         mfFFTShift

                         mfIFFTShift
                  Chapter 7 Matrix Functions   209




Matrix Analysis
210         MATFOR 4 in Fortran Reference Guide



      mfDet
      Find the determinant of a matrix.


      Module
      fml


      Syntax
      d = mfDet(x)



      Descriptions
      Procedure mfDet(x) returns a scalar mfArray containing the determinant of square matrix
      mfArray x. For matrices of modest order with small integer entries, the procedure can be
      used as a test for matrix singularity.

      Example
      The following example uses the mfDet procedure to compute the determinant of a
      non-singular square matrix mfArray x.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: x, d
      ! Construct a 3-by-3 mfArray x using vertical concatenation.
      x = (/1.0d0, 2.0d0, 3.0d0/) .vc. &
         (/7.0d0, 8.0d0, 9.0d0/) .vc. &
         (/1.0d0, 2.0d0, 4.0d0/)
      ! Compute determinant of mfArray x
      d = mfDet(x)
      ! Display value of x and determinant of x
      call msDisplay(x, 'x', d, 'mfDet(x)')
      ! Deallocate mfArrays x and d
      call msFreeArgs(x, d)
      end program example

      Result
      x =
        1 2 3
        7 8 9
        1 2 4
       mfDet(x) =
       -6

      See Also
      mfCond, mfInv, mfLu
                                                                Chapter 7 Matrix Functions   211



mfNorm
Calculate the matrix or vector norm.


Module
fml


Syntax
n = mfNorm(x[, p])



Descriptions
n = mfNorm(x), n = mfNorm(x, p)
Procedure mfNorm generates the norm value differently for matrices and vectors.

For matrices:
• mfNorm(x) returns a scalar mfArray containing the largest singular value of mfArray x.
•   mfNorm(x, p) returns a different kind of norm, depending on the value of p.
•   mfNorm(x, 1) returns the largest column sum of x.
•   mfNorm(x, 2) is equivalent to mfNorm(x). It returns the largest singular value of
    mfArray x.
•   mfNorm(x, MF_INF) returns the largest row sum of x, which is also the infinity norm of
    x.
•   mfNorm(x, "fro") returns the Frobenius norm.

For vectors:
• mfNorm(v, 1) returns a scalar mfArray equal to the sum of elements in mfArray v.
•   mfNorm(v) is the same as mfNorm(v, 2)and returns the value of
    mfSum(mfAbs(v).^2)^(1/2).



Example
The following example uses the mfNorm procedure to compute the norm of a non-singular
square matrix mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, n
! Construct a 3-by-3 mfArray x using vertical concatenation.
x = (/1.0d0, 2.0d0, 3.0d0/) .vc. &
   (/7.0d0, 8.0d0, 9.0d0/) .vc. &
   (/1.0d0, 2.0d0, 4.0d0/)
212      MATFOR 4 in Fortran Reference Guide


      ! Compute norm of mfArray x
      n = mfNorm(x)
      ! Display value of x and norm n of x
      call msDisplay(x, 'x', n, 'norm')
      ! Deallocate mfArrays x and n
      call msFreeArgs(x, n)
      end program example


      Result
      x =
       1 2 3
       7 8 9
       1 2 4
      norm =

        15.0130


      See Also
      mfCond
                                                              Chapter 7 Matrix Functions    213



mfRank
Return the rank of a matrix.


Module
fml


Syntax
r = mfRank(x[, tol])



Descriptions
For matrices, procedure mfRank(x) is used as an estimation for the number of linearly
independent rows and columns of a matrix x.

mfRank(x), mfRank(x[, tol])
• Procedure mfRank(x) returns a scalar mfArray containing the number of independent
    rows or columns of a matrix x.
•   Procedure mfRank(x) uses the default tol = mfMax(mfSize(x)) * mfNorm(x)
    * MF_EPS.
•   Procedure mfRank(x, tol) returns the singular values of matrix x that are larger than
    tol.



Example
The following example uses the mfRank procedure to compute the rank of a square matrix
mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, r
! Construct a 3-by-3 mfArray x using vertical
! concatenation.
x = (/1.0d0, 2.0d0, 3.0d0/) .vc. &
   (/7.0d0, 8.0d0, 9.0d0/) .vc. &
   (/2.0d0, 4.0d0, 6.0d0/)
! Compute the rank of mfArray x
r = mfRank(x)
! Display value of x and the rank r of x
call msDisplay(x, 'x', r, 'mfRank(x)')
! Deallocate mfArrays x and r
call msFreeArgs(x, r)
end program example
214        MATFOR 4 in Fortran Reference Guide



      Result
      x =
       1 2 3
       7 8 9
       2 4 6
      mfRank(x) =
       2


      See Also
      mfSize
                                                           Chapter 7 Matrix Functions   215



mfTrace, msTrace
Return the sum of diagonal elements.


Module
fml


Syntax
s = mfTrace(x)



Descriptions
For matrices, procedure mfTrace(x) returns the sum of diagonal elements of mfArray x,
which is equivalent to the sum of eigenvalues of mfArray x.



Example
The following example uses the mfTrace procedure to compute the sum of the diagonal
elements of the square matrix mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, s
! Construct a 3-by-3 mfArray x using vertical
! concatenation.
x = (/10.0d0, 0.0d0, 6.0d0/) .vc. &
   (/0.0d0, -3.0d0, 9.0d0/) .vc. &
   (/0.0d0, 2.0d0, 4.0d0/)
! Compute the trace of mfArray x
s = mfTrace(x)
! Display value of x and trace s of x
call msDisplay(x, 'x', s, 'mfTrace(x)')
! Deallocate mfArrays x and s
call msFreeArgs(x, s)
end program example


Result
x =
  10 0      6
   0 -3     9
   0 2      4
 mfTrace(x) =
  11

See Also
216     MATFOR 4 in Fortran Reference Guide




      Linear Equations
                                                                      Chapter 7 Matrix Functions       217



mfChol, msChol
Cholesky factorization.


Module
fml


Syntax
r = mfChol(x)

call msChol(mfOut(r, p), x)



Descriptions
Procedure mfChol(x) uses only the diagonal and upper triangle of x.

r = mfChol(x)
For matrices, if mfArray x is positively definite, then procedure mfChol(x) returns an upper
triangular mfArray r so that .h.r * r = x. If x is not a positive definite mfArray, an error occurs.

call msChol(mfOut(r, p), x)
Error is prevented from occurring when call msChol(mfOut(r, p), x) is used. If x is
positively definite, p is 0 and r is the same as above. Otherwise, p is a positively scalar mfArray
and r is an upper triangular mfArray such that: .h.r * r = mfGet(x, mfColon(1, p-1), mfColon(1,
p-1))



Example
The following example uses the mfChol procedure to derive the Cholesky factorization of a
non-positive square matrix mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, r ,p
! Construct a 3-by-3 mfArray x using vertical concatenation.
x = (/10.0d0, 2.0d0, 6.0d0/) .vc. &
   (/6.0d0, 3.0d0, 9.0d0/) .vc. &
   (/3.0d0, 2.0d0, 4.0d0/)
! Compute mfChol of mfArray x
call msChol(mfout(r, p), x)
! Display value of x, r and p
call msDisplay(x, 'x', r, 'r', p, 'p')
! Deallocate mfArrays x and r and p
call msFreeArgs(x, r, p)
end program example
218        MATFOR 4 in Fortran Reference Guide




      Result
      x =
       10     2    6
        6     3    9
        3     2    4
      r =

        3.1623         0.6325
        0.0000         1.6125

      p =
       3


      See Also
      mfLu
                                                                    Chapter 7 Matrix Functions   219



mfCond
Return condition number of a matrix.


Module
fml


Syntax
c = mfCond(x[, p])



Descriptions
For matrices, procedure mfCond returns the p-norm condition number of x.

c = mfCond(x) , c = mfCond(x, p)
• Procedure mfCond(x) returns the 2-norm condition number. It is also the ratio of the
     largest singular value of x to the smallest. A large condition number indicates a nearly
     singular mfArray x.
•    Specifying argument p returns a p-norm condition number of x, which is equal to
     mfNorm(x, p) * mfNorm(mfInv(x), p), where p is 1, 2, MF_INF or "fro".

    p = 1 The mfCond returns the 1-norm condition number.
     p = 2 The mfCond returns the 2-norm condition number.
     p = "fro" Return the Frobenius norm condition number.
     p = MF_INF Return the Infinity norm condition number.



Example
The following example uses the mfCond procedure to compute the condition number with
respect to inversion in the 2-norm of a square matrix mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, c
! Construct a 3-by-3 mfArray x using vertical concatenation.
x = (/10.0d0, 8.0d0, 6.0d0/) .vc. &
   (/5.0d0, 15.0d0, 5.0d0/) .vc. &
   (/6.0d0, 7.0d0, 8.0d0/)
! Compute the condition number with respect to inversion
! of mfArray x
c = mfCond(x)
! Display value of x and c of x
call msDisplay(x, 'x', c, 'mfCond(x)')
! Deallocate mfArrays x and c
220      MATFOR 4 in Fortran Reference Guide

      call msFreeArgs(x, c)
      end program example


      Result
      x =
       10 8      6
        5 15     5
        6 7      8
      mfCond(x) =

        8.2853


      See Also
      mfNorm
                                                              Chapter 7 Matrix Functions    221



mfInv
Return matrix inverse.


Module
fml


Syntax
out = mfInv(in)



Descriptions
For matrices, procedure mfInv(x) returns the inverse of mfArray x.

y = mfInv(x)
Procedure mfInv is applicable only for square matrices. A warning message will be printed
when x is badly scaled or nearly singular.

Example
The following example uses the mfInv procedure to compute the inverse of a matrix
mfArray x.

Code
program example
       use fml
       implicit none
       type(mfArray) :: A, InvA, I
       A = (/5.0, 1.0, 2.0, 2.0, 10.0, 3.0 , 3.0, 2.0, 5.0/)
       A = mfReshape(A, (/3, 3/))
       InvA = mfInv(A)
       call msDisplay(A, "A", InvA, "InvA")
       call msFreeArgs(A,InvA)
end program

Result
x =
   5 2      3
   1 10     2
   2 3      5
 y =

   0.2635 -0.0060 -0.1557
  -0.0060 0.1138 -0.0419
  -0.1018 -0.0659 0.2874

See Also
mfCond
222       MATFOR 4 in Fortran Reference Guide



      mfRcond
      LINPACK reciprocal condition estimator.


      Module
      fml


      Syntax
      c = mfRcond(x)



      Descriptions
      For matrices, procedure mfRcond(x) uses the LAPACK condition estimator to get an
      estimate for the reciprocal of the condition of x in the 1-norm.

      c = mfRcond(x) returns a value near 1.0 when matrix x is well conditioned and returns a value
      near 0.0 when x is badly conditioned.



      Example
      The following example uses the mfRcond procedure to compute the reciprocal of the
      condition of x in the 1-norm of a square matrix mfArray x.

      Code
      program example
            use fml
            implicit none
            type(mfArray) :: A, C
            A = (/5.0, 1.0, 2.0, 2.0, 10.0, 3.0 , 3.0, 2.0, 5.0/)
            A = mfReshape(A, (/3, 3/))
            C = mfRcond(A)
            call msDisplay(A, "A", C, "Condition")
            call msFreeArgs(A,C)
      end program


      Result
      A =
         5 2      3
         1 10     2
         2 3      5
       Condition =

         0.1374


      See Also
      mfCond, mfNorm
                                                                  Chapter 7 Matrix Functions     223



mfLu, msLu
Perform LU matrix factorization.


Module
fml


Syntax
out = mfLu(in)

call msLu(mfout(l, u), x)
call msLu(mfout(l, u, p), x)



Descriptions
Procedure mfLu(x) returns the LU decomposition of a square mfArray x.

call msLu(mfout(l, u), x)
When used, the procedure mfLu(x) returns mfArray u containing the upper triangular matrix,
and mfArray l containing product of the lower triangular matrix and permutation array, so that

x = l*u

call msLu(mfout(l, u, p), x)
When used, the procedure returns an upper triangular mfArray u, lower triangular mfArray l,
and permutation mfArray p, such that p*x = l*u.

When y = mfLu(x) is used, the procedure returns the one output from LINPACK'S ZGEFA
routine.



Example
The following example uses the mfLu procedure to compute the LU decomposition of matrix
mfArray x.

Code
program example
use fml
implicit none
type(mfArray) :: x, l, u, p
! Construct a 3-by-3 mfArray x using vertical concatenation.
x = (/1.0d0, 2.0d0, 3.0d0/) .vc. &
   (/7.0d0, 8.0d0, 9.0d0/) .vc. &
   (/1.0d0, 2.0d0, 4.0d0/)
! Compute lu decomposition of mfArray x
call msLu(mfout(l, u, p), x)
! Display value of x, l, u and p
224        MATFOR 4 in Fortran Reference Guide

      call msDisplay(x, 'x', l, 'l' ,u, 'u', p, 'p')
      call msDisplay(mfNorm(mfMul(p,x)-mfMul(l,u)),'Error')
      ! Deallocate mfArrays x, l , u, p
      call msFreeArgs(x, l, u, p)
      end program example


      Result
      x =
       1 2 3
       7 8 9
       1 2 4
      l =

        1.0000       0.0000      0.0000
        0.1429       1.0000      0.0000
        0.1429       1.0000      1.0000

      u =

        7.0000       8.0000      9.0000
        0.0000       0.8571      1.7143
        0.0000       0.0000      1.0000

      p =
       0 1 0
       1 0 0
       0 0 1
      Error =
       0


      See Also
      mfQr
                                                                Chapter 7 Matrix Functions   225



mfQr, msQr
Perform orthogonal-triangular decomposition.


Module
fml


Syntax
out = mfQr(in1[, 0])

call msQr(mfOut(q, r), a[, 0])
call msQr(mfOut(q, r, e), a[, 0])



Descriptions
Procedure mfQr returns the orthogonal-triangular decomposition of a matrix.

call msQr(mfOut(q, r), a)
• This procedure returns an upper triangular mfArray r of the same shape as a and a
    unitary mfArray matrix q, such that a = q*r.

call msQr(mfOut(q, r), a, 0)
• This procedure performs an "economy size" decomposition. If a is an m-by-n mfArray
   with
m > n, only the first n columns of q will be computed.

call msQr(mfOut(q, r, e), a)
• This procedure returns an upper triangular mfArray r, a unitary mfArray q, and a
    permutation matrix mfArray e, such that a*e = q*r.

call msQr(mfOut(q, r, e), a, 0)
• This procedure performs an "economy size" decomposition, returning a permutation
    vector e, such that q*r = mfGet(a, MF_COL, e). The column permutation e is
    chosen so that mfAbs(mfDiag(r)) is decreasing.



Example
The following example uses the mfQr procedure to compute the orthogonal-triangular
decomposition of matrix mfArray x.

Code
program example
use fml
implicit none
226      MATFOR 4 in Fortran Reference Guide

      type(mfArray) :: q, r, a, e
      ! Construct a 3-by-3 mfArray a using vertical
      ! concatenation.
      a = (/1.0d0, 2.0d0, 3.0d0/) .vc. &
         (/7.0d0, 8.0d0, 9.0d0/) .vc. &
         (/1.0d0, 2.0d0, 4.0d0/)
      ! Compute qr decomposition of mfArray a
      call msQr(mfOut(q, r, e), a)
      ! Display value of a, q, r and e
      call msDisplay(a, 'a', q, 'q' ,r, 'r', e, 'e')
      call msDisplay(mfNorm(mfMul(a,e)-mfMul(q,r)),'Error')
      ! Deallocate mfArrays a, q, r, e
      call msFreeArgs(q, r, a, e)
      end program example


      Result
      a =
       1 2 3
       7 8 9
       1 2 4
      q =

       -0.2914 0.4491 -0.8447
       -0.8742 -0.4836 0.0445
       -0.3885 0.7513  0.5335

      r =

       -10.2956     -6.7990       -8.3531
         0.0000     -2.1849       -1.4681
         0.0000      0.0000       -0.2667

      e =
       0 1 0
       0 0 1
       1 0 0

      Error =

      1.0e-14 *
        0.4378


      See Also
      mfLu
                                                                 Chapter 7 Matrix Functions     227



mfMul
Return matrix product of two mfArrays.


Module
fml


Syntax
z = mfMul(x, y)



Descriptions
Function mfMul(x, y) returns the matrix product of mfArrays x and y, where x is an
m-by-p matrix and y is a p-by-n matrix. The product of the matrix multiplication is an m-by-n
mfArray.

Example

Code
program example
use fml
implicit none
type(mfArray) :: x, y, z
x = mfMagic(3)
y = mfInv(x)
z = mfMul(x,y)
call msDisplay(x, 'x', y, 'Inv',z,'Eye')
call msFreeArgs(x, y, z)
end program example

Result
x =
  8 1 6
  3 5 7
  4 9 2
 Inv =

   0.1472 -0.1444 0.0639
  -0.0611 0.0222  0.1056
  -0.0194 0.1889 -0.1028

 Eye =

   1.0000      0.0000     0.0000
   0.0000      1.0000     0.0000
   0.0000      0.0000     1.0000

See Also
Arithmetic Operators
228       MATFOR 4 in Fortran Reference Guide



      mfRDiv, mfLDiv
      Matrix left division and right division operators.


      Module
      fml


      Syntax
      x = mfLDiv(a, b)
      x = mfRDiv(b, a)

      Descriptions
      Function mfLDiv and mfRDiv are normally used in solving systems of linear equations
      represented by (xa=b).

      x = mfLDiv(a, b) is an approximation of mfMul(mfInv(a), b).
      x = mfRDiv(b, a) is an approximation of mfMul(b, mfInv(a)).

      The two functions are related by mfLDiv(a,                b)    =   mfTranspose(mfRDiv
      ((mfTranspose(b)),(mfTranspose(a))))

      Depending on the structure of the coefficient matrix a, MATFOR uses different algorithms to
      solve the simultaneous linear equations mfLDiv(a, b) and mfRDiv(b, a). Figure 2.2
      provides an overview of the different methods used for solving the linear equation, depending on
      the structure of matrix a.

      Figure 2.2 Algorithms applicable for each type of matrix a.

      If a is an n-by-n square matrix, and b is an n-by-p matrix, then mfLDiv(a, b) is solved
      by using Gaussian elimination. MATFOR performs a structural test on matrix a to select the
      optimal factorization method. Non-symmetry and non-positive definite systems are detected
      almost immediately, hence this does not take much of the computation time.

      If a is an m-by-n rectangle matrix, and b is an m-by-p matrix, for m /= n, MATFOR uses
      the least squares method for solving the under-determined or over-determined system. There
      are two approaches to solving a least squares problem - QR and normal equations method.
      MATFOR uses the normal equations method as it requires half the arithmetic when m<n and
      much less storage space compared to the QR method.

      Note that MATFOR uses LAPACK for solving Linear Algebra equations.

      Example
      Please refer to MATFOR in Fortran User's Guide Example 3_3.

      See Also
      Arithmetic Operators
                           Chapter 7 Matrix Functions   229




Eigenvalues and singular
values
230       MATFOR 4 in Fortran Reference Guide



      mfEig, msEig
      Calculate eigenvalues and eigenvectors.


      Module
      fml


      Syntax
      e = mfEig(a[, flag])
      e = mfEig(a, b[, flag])

      call msEig(mfOut(v, d), a[, flag])
      call msEig(mfOut(v, d), a, b[, flag])



      Descriptions
      Procedure mfEig computes the eigenvalues and eigenvectors of a matrix mfArray a.

      e = mfEig(a), e = mfEig(a, flag)
      • This procedure returns a vector e containing the eigenvalues of square mfArray a.
      •   Argument flag can be a string containing 'nobalance', so that the procedure can perform
          the computation with balancing switched off. This usually produces more accurate results
         for specific problems.
      call msEig(mfOut(v, d), a), call msEig(mfOut(v, d), a, flag)
      • This procedure returns a diagonal matrix d of eigenvalues, and a full matrix mfArray v
          whose columns are the corresponding eigenvectors such that a*v = v*d.

      e = mfEig(a, b), e = mfEig(a, b, flag)
      • This procedure returns a vector containing the generalized eigenvalues of square matrix
          mfArrays a and b.
      •   The procedure specifies the algorithm used to compute eigenvalues and eigenvectors
          through the argument flag, which is specified in More Detail below.

      call msEig(mfOut(v, d), a, b), call msEig(mfOut(v, d), a, b, flag)
      • This procedure returns a diagonal matrix mfArray d of generalized eigenvalues and a full
          matrix mfArray v whose columns are the corresponding eigenvectors so that a*v =
          b*v*d.
      •   The procedure specifies the algorithm used to compute eigenvalues and eigenvectors
          through the argument flag, which is specified in More Detail below.

      More Detail
      Argument flag can be:
      • "chol" This is the default for symmetric (Hermitian) a and symmetric (Hermitian) positive
                                                                   Chapter 7 Matrix Functions   231


     definite b. The generalized eigenvalues of a and b are computed using the Cholesky
     factorization of b.
•    "qz" This uses the mfQz algorithm to compute eigenvlaues for nonsymmetrical
     (non-Hermitian) a and b.



Example
The following example uses the mfEig procedure to compute the eigenvalues and
eigenvectors of a square matrix mfArray a.

Code
program example
use fml
implicit none
type(mfArray) :: v, d, a
! Construct a 3-by-3 mfArray a using vertical concatenation.
a = (/5.0d0, 4.0d0, 3.0d0/) .vc. &
   (/2.0d0, 4.0d0, 6.0d0/) .vc. &
   (/10.0d0, 15.0d0, 25.0d0/)
! Compute eigenvalues and eigenvectors of mfArray a
call msEig(mfout(v, d), a)
! Display value of a, v and d
call msDisplay(a, 'a', v, 'v' ,d, 'd')
! Deallocate mfArrays a, v, d
call msFreeArgs(a, v, d)
end program example


Result
a =
     5 4   3
     2 4   6
    10 15 25
v =

    -0.1512 -0.9354 0.5446
    -0.2317 0.2120 -0.7954
    -0.9610 0.2830  0.2660

d =

    30.1904       0.0000        0.0000
     0.0000       3.1857        0.0000
     0.0000       0.0000        0.6238


See Also
mfBalance, mfHess, mfQz, mfSchur
232       MATFOR 4 in Fortran Reference Guide



      mfHess, msHess
      Produce Hessenberg form of a matrix.


      Module
      fml


      Syntax
      h = mfHess(a)

      call msHess(mfOut(p, h), a)



      Descriptions
      Procedure mfHess returns the Hessenberg form of an mfArray.

      h = mfHess(a)
      This procedure returns an mfArray h with zeros below the first sub diagonal and has the same
      eigenvalues as a. If the original mfArray a is symmetric or Hermitian, h will be tridiagonal.

      call msHess(mfOut(p, h), a)
      This procedure produces an unitary matrix p and a Hessenberg matrix h so that a = p*h*.h.p
      and .h.p*p results in the identity matrix.



      Example
      The following example uses the mfHess procedure to compute the Hessenberg form of a
      square matrix mfArray a.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: a, p, h
      ! Construct a 3-by-3 mfArray a using vertical concatenation.
      a = (/5.0d0, 4.0d0, 3.0d0/) .vc. &
         (/9.0d0, 8.0d0, 7.0d0/) .vc. &
         (/5.0d0, 1.0d0, 2.0d0/)
      ! Compute the Hessenberg form of mfArray a
      call msHess(mfout(p, h), a)
      ! Display value of a, p and h
      call msDisplay(a, 'a', p, 'p' , h, 'h')
      ! Deallocate mfArrays a, p, h
      call msFreeArgs(a, p, h)
      end program example


      Result
                                 Chapter 7 Matrix Functions   233

a =
 5 4 3
 9 8 7
 5 1 2
p =

  1.0000     0.0000 0.0000
  0.0000    -0.8742 -0.4856
  0.0000    -0.4856 0.8742

h =

   5.0000    -4.9536    0.6799
 -10.2956     9.9811   -2.5660
   0.0000     3.4340   0.0189


See Also
234       MATFOR 4 in Fortran Reference Guide



      mfQz, msQz
      Perform QZ factorization for generalized eigenvalues.


      Module
      fml


      Syntax
      aa = mfQz(a, b[, flag])

      call msQz(mfOut(aa[, bb, q, z, v]), a, b[, flag])



      Descriptions
      Procedure mfQz performs QZ factorization for generalized eigenvalues of square mfArrays.

      call msQz(mfOut(aa, bb, q, z, v), a, b)
      This procedure returns upper triangular mfArrays aa and bb, the left and right transformed
      mfArrays q and z, and the generalized eigenvector mfArray v, such that q*a*z = aa, and
      q*b*z = bb.

      call msQz(mfOut(aa, bb, q, z, v), a, b[, flag])
      This procedure depends on the value of flag:
      • "complex" produces a possibly complex decomposition with a triangular aa. This is the
          default option.
      •   "real" produces a real decomposition with a quasitriangular aa, containing 1-by-1 and
          2-by-2 blocks on its diagonal.



      Example
      The following example uses the mfQz procedure to compute the QZ factorization of square
      matrices in mfArray a and b.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: aa, bb, q, z, v, a, b
      ! Construct a 3-by-3 mfArray a and b using vertical
      ! concatenation.
      a = (/4.0d0, 2.0d0, 3.0d0/) .vc. &
         (/7.0d0, 8.0d0, 9.0d0/) .vc. &
         (/5.0d0, 2.0d0, 4.0d0/)
      b = (/3.0d0, 5.0d0, 7.0d0/) .vc. &
         (/2.0d0, 1.0d0, 1.0d0/) .vc. &
         (/3.0d0, 2.0d0, 5.0d0/)
                                                  Chapter 7 Matrix Functions   235

! Compute qz factorization of mfArray a and b
call msQz(mfOut(aa, bb, q, z, v ), a, b)
! Display values of aa, bb, q, z and v
call msDisplay(aa, 'aa', bb, 'bb' ,q, 'q', z, 'z', v, 'v')
! Deallocate mfArrays a, b, aa, bb, q, z, v
call msFreeArgs(a, b, aa, bb, q, z, v)
end program example


Result
aa =
column     1 to   3
 6.3661 +0.0000i      -9.8642 +0.0000i   10.4110 +0.0000i
 0.0000 +0.0000i      -1.4632 +0.0000i    4.2403 +0.0000i
 0.0000 +0.0000i       0.0000 +0.0000i    1.2882 +0.0000i

bb =

2.3112 +0.0000i -6.1276 +0.0000i 6.0482 +0.0000i
0.0000 +0.0000i 4.3735 +0.0000i -4.9870 +0.0000i
0.0000 +0.0000i 0.0000 +0.0000i 1.8797 +0.0000i

q =

-0.4555 +0.0000i -0.7072 +0.0000i -0.5407 +0.0000i
 0.6410 +0.0000i -0.6820 +0.0000i 0.3521 +0.0000i
-0.6178 +0.0000i -0.1862 +0.0000i 0.7640 +0.0000i

z =

-0.9116 +0.0000i 0.4095 +0.0000i 0.0353 +0.0000i
-0.1805 +0.0000i -0.3219 +0.0000i -0.9294 +0.0000i
 0.3693 +0.0000i 0.8536 +0.0000i -0.3674 +0.0000i

v =

-1.0000 +0.0000i -0.7564 +0.0000i 0.0489 +0.0000i
-0.1980 +0.0000i -0.4240 +0.0000i -1.0000 +0.0000i
 0.4051 +0.0000i 1.0000 +0.0000i 0.8466 +0.0000i


See Also
mfEig
236       MATFOR 4 in Fortran Reference Guide



      mfSchur, msSchur
      Perform Schur decomposition.


      Module
      fml


      Syntax
      qt = mfSchur(a[, flag])

      call msSchur(mfOut(u, qt), a)



      Descriptions
      Procedure mfSchur performs the Schur decomposition on a square matrix mfArray.

      qt = mfSchur(a), qt = mfSchur(a, flag)
      • This procedure returns a quasitriangular Schur mfArray matrix qt. If a is complex,
          mfSchur returns the complex Schur form in matrix qt. The complex Schur form is an
          upper triangular matrix containing the eigenvalues of a on the diagonal.
      •   This procedure returns a Schur matrix qt in one of two forms for real matrix a,
          depending on the value of flag.
      •   If flag is "complex", qt is triangular. If a has complex eigenvalues, qt is complex. If
          flag is "real", qt has real eigenvalues on the diagonal. Complex eigenvalues are located
          in 2-by-2 blocks on the diagonal. By default, flag is "real".

      call msSchur(mfOut(u, qt), a)
      • This procedure returns a unitary matrix u and a quasitriangular Schur matrix mfArray qt
          such that a = u*qt*.h.u and .h.u*u is an identity matrix given by mfEye(Shape(u)).



      Example
      The following example uses the mfSchur procedure to compute the Schur decomposition of
      a square matrix mfArray a.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: u, qt, a
      ! Construct a 3-by-3 mfArray a using vertical
      ! concatenation.
      a = (/3.0d0, 4.0d0, 3.0d0/) .vc. &
         (/2.0d0, 1.0d0, 4.0d0/) .vc. &
         (/6.0d0, 2.0d0, 2.0d0/)
                                                 Chapter 7 Matrix Functions   237


! Compute the Schur decomposition of mfArray a
call msSchur(mfOut(u, qt), a)
! Displays values of a, u and qt
call msDisplay(a, 'a', u, 'u' , qt, 'qt')
! Deallocate mfArrays a, u, qt
call msFreeArgs(a, u, qt)
end program example


Result
a =
 3 4 3
 2 1 4
 6 2 2
u =

  0.6118    0.7878 -0.0707
  0.4634   -0.4295 -0.7751
  0.6410   -0.4415 0.6279

qt =

  9.1729    1.2110 -0.5957
  0.0000   -1.5865 -1.4934
  0.0000    2.4025 -1.5865


See Also
238       MATFOR 4 in Fortran Reference Guide



      mfSvd, msSvd
      Perform singular value decomposition.


      Module
      fml


      Syntax
      s = mfSvd(a)

      call msSvd(mfOut(u, s, v), a[, 0])



      Descriptions
      Procedure mfSvd performs singular value decomposition on matrix mfArray a.

      s = mfSvd(a) returns an mfArray vector containing singular values.

      call msSvd(mfOut(u, s, v), a) returns two unitary matrices u and v, and a diagonal
      matrix s such that a = u*s*.h.v . Diagonal matrix s has the same shape as a and contains
      nonnegative elements in decreasing order.

      call msSvd(mfOut(u, s, v), a, 0) returns the "economy size" decomposition. If a is
      m-by-n and m > n, then only the first n columns of u are computed. s is n-by-n.



      Example
      The following example uses the mfSvd procedure to compute the singular value
      decomposition of a square matrix mfArray a.

      Code
      program example
      use fml
      implicit none
      type(mfArray) :: a, u, s, v
      ! Construct a 3-by-3 mfArray a using vertical
      ! concatenation.
      a = (/10.0d0, 20.0d0, 30.0d0/) .vc. &
         (/7.0d0, 8.0d0, 9.0d0/)    .vc. &
         (/5.0d0, 15.0d0, 25.0d0/)
      ! Compute singular value decomposition of mfArray a
      call msSvd(mfOut(u, s, v), a)
      ! Display value of a, u, s and v
      call msDisplay(a, 'a', u, 'u' ,s, 's', v, 'v')
      ! Deallocate mfArrays a, u, s, v
      call msFreeArgs(a, u, s, v)
      end program example
                              Chapter 7 Matrix Functions   239



Result
a =
 10 20 30
  7 8   9
  5 15 25
u =

 -0.7568 -0.1344 -0.6397
 -0.2688 -0.8280 0.4921
 -0.5958 0.5444   0.5905

s =

  49.4333   0.0000   0.0000
   0.0000   5.0350   0.0000
   0.0000   0.0000   0.0000

v =

 -0.2514 -0.8776 0.4082
 -0.5305 -0.2279 -0.8165
 -0.8095 0.4219   0.4082


See Also
240     MATFOR 4 in Fortran Reference Guide




      Factorization Utilities
                                                              Chapter 7 Matrix Functions    241



mfBalance, msBalance
Perform diagonal scaling to improve eigenvalue accuracy.


Module
fml


Syntax
b = mfBalance(a)

call msBalance(mfOut(t, b), a)



Descriptions
For matrices, procedure mfBalance performs diagonal scaling to improve the eigenvalue
accuracy.

b = mfBalance(a) returns the balanced matrix mfArray b.

call msBalance(mfOut(t, b), a) returns a similarity transformation t, such that
b = mfLDiv(t, a*t) has, as closely as possible, approximately equal row and column norms.



Example
The following example uses the mfBalance procedure to find the balanced matrix mfArray
b of the original mfArray a.

Code
program example
use fml
implicit none
type(mfArray) :: a, b
! Construct a 3-by-3 mfArray a using vertical concatenation.
a = (/100.0d0, 200.0d0, 300.0d0/) .vc. &
   (/4.0d0, 5.0d0, 6.0d0 /)     .vc. &
   (/7.0d0, 8.0d0, 9.0d0 /)
! Compute the balanced matrix b of mfArray a
b = mfBalance(a)
! Display values of a and b
call msDisplay(a, 'a', b, 'mfBalance(a)')
! Deallocate mfArrays a and b
call msFreeArgs(a, b)
end program example


Result
a =
  100 200      300
242      MATFOR 4 in Fortran Reference Guide

         4       5   6
         7       8   9
      mfBalance(a) =

        100.0000         25.0000      37.5000
         32.0000          5.0000       6.0000
         56.0000          8.0000       9.0000


      See Also
      mfEig
                                                                      Chapter 8 Sparse Array   243



CHAPTER 8


Sparse Array

A Sparse Array is an array in which most of its entries are zeros and only very few
entries are in practice used. This is particularly in use for large scale simulations.
MATFOR mfSparse is a Sparse Array defined by MATFOR that can be used for
Sparse Array creation, manipulations and solution to linear system.
This chapter describes the Sparse functions available, as listed below:



msSpAdd              Add one or multiple real entries to the sparse array.

msSpSet              Set one or multiple entries in the sparse array.

mfSpGet              Get a specific element from a sparse array.

mfSpGetM             Get number of row, number of column from a sparse array


mfSpGetNNZ           Get number of nonzero elements of a sparse array.

mfSpGetRow           Get row indices, column indices of nonzero elements in a
                     sparse array.

mfSpGetVal           Get values of nonzero elements in a sparse array.

msSpGetIdx           Get row indices, column indices and values of nonzero
                     elements in a sparse array.

msSpDisplay          Display sparse array data.

msSpExport           Export sparse array data.

mfSpImport           Export sparse array data.

mfSpEigs             Find the eigenvalues and eigenvectors of a sparse array.

mfSpLDiv             Solve a sparse array system of linear equations.

mfSpMul              Multiply a sparse array onto an mfArray.

mfSpSize             Return total number of elements in a sparse array.
244     MATFOR 4 in Fortran Reference Guide


      mfSpToFull         Convert a sparse array into a full array.

      mfFullToSp         Convert a full array into a sparse array.

      mfSpy              Draw patterns of a sparse array.
               Chapter 8 Sparse Array   245




Sparse Array
246       MATFOR 4 in Fortran Reference Guide



      mfSpCreate
      Create a sparse matrix.


      Module
      spml


      Syntax
      spA = mfSpCreate(m, n)



      Descriptions
      Procedure spA = mfSpCreate(m, n) creates an m-by-n matrix with sparse internal
      representation. Argument m is a m x 1 matrix that represents the number of column and n is a
      1 x n matrix that represents the number of row.



      Example
      To be referred to mfSpy

      See Also
      mfSpy
                                                                  Chapter 8 Sparse Array   247



msSpAdd
Add one or multiple real entries to the sparse array.


Module
spml


Syntax
call msSpAdd(spA, row, col, value)

call msSpAdd(spA, rindex, cindex, values)



Descriptions
Procedure msSpAdd adds one or multiple real entries to the sparse array.

call msSpAdd(spA, row, col, value)
• Add a real entry into the sparse array.
call msSpAdd(spA, rindex, cindex, values)
• Add real entries into the sparse array.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: rindex(4), cindex(4)
     real(8) :: values(4)
     type(mfSparse) :: sp
     rindex = (/1, 2, 2, 3/)
     cindex = (/3, 1, 3, 2/)
     values = (/-1.5, -0.5, 0.5, 1.5/)
     ! Add multi elements.
     call msSpAdd(sp, rindex, cindex, values)
     call msSpDisplay(sp, "oringal sparse array sp")
     ! Add single element sp(1, 1) = -2
     call msSpAdd(sp, 1, 1, -2.0d0)
     ! Add single element sp(3, 2) = 2
     call msSpAdd(sp, 3, 2, 2.0d0)
     call msSpDisplay(sp, "modified sp")


end program


Result
oringal sparse array sp =
248      MATFOR 4 in Fortran Reference Guide


      oringal    sparse   array    sp(1,3)     =   -1.500000e+000 ;
      oringal    sparse   array    sp(2,1)     =   -5.000000e-001 ;
      oringal    sparse   array    sp(2,3)     =   5.000000e-001 ;
      oringal    sparse   array    sp(3,2)     =   1.500000e+000 ;
      modified sp =
      modified    sp(1,1)    =   -2.000000e+000 ;
      modified    sp(1,3)    =   -1.500000e+000 ;
      modified    sp(2,1)    =   -5.000000e-001 ;
      modified    sp(2,3)    =   5.000000e-001 ;
      modified    sp(3,2)    =   3.500000e+000 ;


      See Also
      msSpSet
                                                                  Chapter 8 Sparse Array   249



msSpSet
Set one or multiple entries in the sparse array.


Module
spml


Syntax
call msSpSet(spA, row, col, value)

call msSpSet(spA, rindex, cindex, values)



Descriptions
Procedure msSpSet sets one or multiple entries in the sparse array.

call msSpSet(spA, row, col, value)
• Set a real entry into the sparse array.
call msSpSet(spA, rindex, cindex, values)
• Set real entries into the sparse array.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: rindex(4), cindex(4), mr(3), mc(3)
     real(8) :: values(4), mv(3)
     type(mfSparse) :: a
     ! Create sparse array a.
     rindex = (/1, 2, 3, 3/)
     cindex = (/1, 3, 2, 3/)
     values = (/9, 8, 7, 6/)
     call msSpAdd(a, rindex, cindex, values)
     call msSpDisplay(a, "oringal sparse array a")
     ! Set single element a(1, 1) = -9
     call msSpSet(a, 1, 1, -9.0d0)
     call msSpDisplay(a, "modified a")
     ! Set multi elements.
     mr = (/2, 3, 3/)
     mc = (/3, 2, 3/)
     mv = (/-8, -7, -6/)
     call msSpSet(a, mr, mc, mv)
     call msSpDisplay(a, "modified a")
end program example
250      MATFOR 4 in Fortran Reference Guide


      Result
      oringal sparse array a =
      oringal    sparse   array    a(1,1)      =   9.000000e+000   ;
      oringal    sparse   array    a(2,3)      =   8.000000e+000   ;
      oringal    sparse   array    a(3,2)      =   7.000000e+000   ;
      oringal    sparse   array    a(3,3)      =   6.000000e+000   ;
      modified a =
      modified    a(1,1)   =   -9.000000e+000 ;
      modified    a(2,3)   =   8.000000e+000 ;
      modified    a(3,2)   =   7.000000e+000 ;
      modified    a(3,3)   =   6.000000e+000 ;
      modified a =
      modified    a(1,1)   =   -9.000000e+000        ;
      modified    a(2,3)   =   -8.000000e+000        ;
      modified    a(3,2)   =   -7.000000e+000        ;
      modified    a(3,3)   =   -6.000000e+000        ;


      See Also
      msSpAdd
                                                                Chapter 8 Sparse Array     251



mfSpGet
Get a specific element from a sparse array.


Module
spml


Syntax
value = mfSpGet(spA, rowIdx, colIdx)



Descriptions
Procedure msSpGet gets a specific element from a sparse array. The return type is a real
number.

value = mfSpGet(spA, rowIdx, colIdx)
• Get a specific element given row and column indices from a sparse array.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: RowIdx(5), ColIdx(5)
     real(8) :: Values(5)
     integer(4) :: m, n, nnz
     real(8) :: value
     type(mfSparse) :: sp,sp2
     ! Create a sparse matrix
     RowIdx = (/1, 2, 2, 3, 3/)
     ColIdx = (/3, 1, 2, 3, 4/)
     Values = (/-1.5, -0.9, 0.7, 1.8, 2.3/)
     call msSpAdd(sp, RowIdx, ColIdx, Values)
     call msSpDisplay(sp, "sp")
     ! Get number of row of sparse matrix
     m = mfSpGetM(sp)
     write(*,*) "m = ", m
     ! Get number of column of sparse matrix
     n = mfSpGetN(sp)
     write(*,*) "n = ", n
     ! Get number of nonzero elements of sparse matrix
     nnz = mfSpGetNNZ(sp)
     write(*,*) "nnz = ", nnz
     ! Get value of sp(2, 1)
     value = mfSpGet(sp, 2, 1)
     write(*,*) "sp(2, 1) = ", value
252      MATFOR 4 in Fortran Reference Guide

      end program


      Result
      sp =
      sp(1,3)    =   -1.500000e+000 ;
      sp(2,1)    =   -9.000000e-001 ;
      sp(2,2)    =   7.000000e-001 ;
      sp(3,3)    =   1.800000e+000 ;
      sp(3,4)    =   2.300000e+000 ;
      m =         3
      n =         4
      nnz =         5
      sp(2, 1) = -0.899999976158142


      See Also
      mfSpGetRow, mfSpGetCol, mfSpGetVal, msSpGetIdx
                                                           Chapter 8 Sparse Array    253



mfSpGetM, mfSpGetN
Get number of row, number of column from a sparse array.


Module
spml


Syntax
m = mfSpGetM(spA)

n = mfSpGetN(spA)



Descriptions
Procedure msSpGetM gets respective number of row and column of a sparse array. The
return type is a real number.

m = mfSpGetM(spA)
• Get number of row of mfSparse spA.

n = mfSpGetN(spA)
• Get number of column of mfSparse spA.



Example
To be referred to mfSpGet

Code
Program Main
     use fml
     use spml
     implicit none
     integer(4) :: RowIdx(5), ColIdx(5)
     real(8) :: values(5)
     type(mfArray) :: m
     integer(4) :: n
     type(mfSparse) :: sp
     ! Create a sparse matrix
     RowIdx = (/1, 1, 3, 4, 5/)
     ColIdx = (/1, 3, 1, 2, 3/)
     values = (/5.1, 1.2, 4.3, 2.4, 7.5/)
     call msSpAdd(sp, RowIdx, ColIdx, values)
     call msSPDisplay(sp, 'sp')
     ! Get number of row of sp
     m = mfSpGetM(sp)
     call msDisplay(m, 'm')
     ! Get number of column of sp
     n = mfSpGetN(sp)
     write(*,'(1x,A3,/,/,I3)') 'n =', n
254        MATFOR 4 in Fortran Reference Guide

      end Program Main


      Result
      sp =
      sp(1,1)     =   5.100000e+000      ;
      sp(1,3)     =   1.200000e+000      ;
      sp(3,1)     =   4.300000e+000      ;
      sp(4,2)     =   2.400000e+000      ;
      sp(5,3)     =   7.500000e+000      ;
      m =
       5
      n =
       3


      See Also
      mfSpGetRow, mfSpGetCol, mfSpGetVal, msSpGetIdx
                                                              Chapter 8 Sparse Array      255



mfSpGetNNZ
Get number of nonzero elements of a sparse array.


Module
spml


Syntax
nnz = mfSpGetNNZ(spA)



Descriptions
Procedure msSpGetNNZ gets number of nonzero elements of a sparse array. The return type
is a real number.

nnz = mfSpGetNNZ(spA)
• Get number of nonzero elements of mfSparse spA.



Example
To be referred to mfSpGet

Code
Program Main
     use fml
     use spml
     implicit none
     integer(4) :: RowIdx(5), ColIdx(5)
     real(8) :: values(5)
     integer(4) :: nnz
     type(mfSparse) :: sp
     ! Create a sparse matrix
     RowIdx = (/1, 1, 3, 4, 5/)
     ColIdx = (/1, 3, 1, 2, 3/)
     values = (/5.1, 1.2, 4.3, 2.4, 7.5/)
     call msSpAdd(sp, RowIdx, ColIdx, values)
     call msSPDisplay(sp, 'sp')
     ! Get number of nonzero elements of sp
     nnz = mfSpGetNNZ(sp)
     write(*,*) 'nnz =', nnz
end Program Main


Result
sp =
 sp(1,1)   =   5.100000e+000    ;
 sp(1,3)   =   1.200000e+000    ;
 sp(3,1)   =   4.300000e+000    ;
 sp(4,2)   =   2.400000e+000    ;
 sp(5,3)   =   7.500000e+000    ;
256      MATFOR 4 in Fortran Reference Guide

      nnz =              5


      See Also
      mfSpGetRow, mfSpGetCol, mfSpGetVal, msSpGetIdx
                                                                  Chapter 8 Sparse Array   257



mfSpGetRow, mfSpGetCol
Get row indices, column indices of nonzero elements in a sparse array.


Module
spml


Syntax
RowIdx = mfSpGetRow(spA)

ColIdx = mfSpGetCol(spA)



Descriptions
Procedure msSpGetRow and msSpGetCol get row indices and column indices of a sparse
array. The return type is an mfArray.

RowIdx = mfSpGetRow(spA)
• Get row indices of nonzero elements in a sparse array.

ColIdx = mfSpGetCol(spA)
• Get column indices of nonzero elements in a sparse array.



Example

Code
program example
     use fml
     use spml
     implicit none
     type(mfArray) :: RowIdx, ColIdx, Values
     type(mfSparse) :: sp
     ! Create a sparse matrix
     call msSpAdd(sp, 1, 4, 53.0d0)
     call msSpAdd(sp, 2, 3, 27.0d0)
     call msSpAdd(sp, 3, 2, 16.0d0)
     call msSpAdd(sp, 4, 5, 91.0d0)
     call msSpAdd(sp, 5, 1, 14.0d0)
     call msSpDisplay(sp, "sp")
     ! Get row indices of nonzero elements in given sparse matrix
     RowIdx = mfSpGetRow(sp)
    call msDisplay(RowIdx, "Row indices of nonzero elements in sp")
     ! Get column indices of nonzero elements in given sparse matrix
     ColIdx = mfSpGetCol(sp)
    call msDisplay(ColIdx, "Column indices of nonzero elements in sp")
     ! Get nonzero values in given sparse matrix
     Values = mfSpGetVal(sp)
    call msDisplay(Values, "Nonzero values in sp")
258        MATFOR 4 in Fortran Reference Guide


      end program


      Result
      sp =
      sp(1,4)     =   5.300000e+001      ;
      sp(2,3)     =   2.700000e+001      ;
      sp(3,2)     =   1.600000e+001      ;
      sp(4,5)     =   9.100000e+001      ;
      sp(5,1)     =   1.400000e+001      ;
      Row indices of nonzero elements in sp =
       1
       2
       3
       4
       5
      Column indices of nonzero elements in sp =
       4
       3
       2
       5
       1
      Nonzero values in sp =
       53
       27
       16
       91
       14


      See Also
      Get, GetM, GetN, GetNNZ
                                                           Chapter 8 Sparse Array      259



mfSpGetVal
Get values of nonzero elements in a sparse array.


Module
spml


Syntax
Values = mfSpGetVal(spA)

call msSpGetVal(mfOut(RowIdx, ColIdx, Values), spA)



Descriptions
Procedure msSpGetVal gets values of nonzero elements from a sparse array. The return
type is an mfArray.

ValIdx = mfSpGetVal(spA)
• Get nonzero values of a sparse array.



Example
To be referred to mfSpGetRow

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: RowIdx(5), ColIdx(5)
     real(8) :: values(5)
     type(mfArray) :: NonZeroVal
     type(mfSparse) :: sp
     ! Create a sparse matrix
     RowIdx = (/1, 1, 3, 4, 5/)
     ColIdx = (/1, 3, 1, 2, 3/)
     values = (/5.1, 1.2, 4.3, 2.4, 7.5/)
     call msSpAdd(sp, RowIdx, ColIdx, values)
     call msSpDisplay(sp, "sp")
    ! Get nonzero values in sp
    NonZeroVal = mfSpGetVal(sp)
    call msDisplay(NonZeroVal,'NonZero Values')
end program example


Result
sp =
 sp(1,1)    =   5.100000e+000    ;
 sp(1,3)    =   1.200000e+000    ;
 sp(3,1)    =   4.300000e+000    ;
 sp(4,2)    =   2.400000e+000    ;
260      MATFOR 4 in Fortran Reference Guide

      sp(5,3) = 7.500000e+000 ;
      NonZero Values =

        5.1000
        1.2000
        4.3000
        2.4000
        7.5000


      See Also
      mfSpGet, mfSpGetM, mfSpGetN, mfSpGetNNZ
                                                                  Chapter 8 Sparse Array     261



msSpGetIdx
Get row indices, column indices and values of nonzero elements in a sparse array.


Module
spml


Syntax
call msSpGetIdx(mfOut(RowIdx, ColIdx, Values), spA)



Descriptions
Procedure msSpGetIdx gets row indices, column indices, and values of nonzero elements
in a sparse array at the same time. The return values are type mfArray.

call msSpGetIdx(mfOut(RowIdx, ColIdx, Values), spA)
• Get row indices, column indices, and values of nonzero elements in a sparse array all at
    once.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: RowIdx(5), ColIdx(5)
     real(8) :: values(5)
     type(mfArray) :: growidx, gcolidx, gval
     type(mfSparse) :: sp
     ! Create a sparse matrix
     RowIdx = (/1, 1, 3, 4, 5/)
     ColIdx = (/1, 3, 1, 2, 3/)
     Values = (/5.1, 1.2, 4.3, 2.4, 7.5/)
     call msSpAdd(sp, RowIdx, ColIdx, Values)
     call msSpDisplay(sp, "sp")
    ! Get row/column indices and values of nonzero elements in sp
    call msSpGetIdx(mfOut(growidx, gcolidx, gval), sp)
    call msDisplay(growidx, 'nonzero elements row index')
    call msDisplay(gcolidx, 'nonzero elements column index')
    call msDisplay(gval, 'nonzero elements values')
end program example


Result
sp =
 sp(1,1)    =   5.100000e+000    ;
 sp(1,3)    =   1.200000e+000    ;
 sp(3,1)    =   4.300000e+000    ;
 sp(4,2)    =   2.400000e+000    ;
262        MATFOR 4 in Fortran Reference Guide

      sp(5,3) = 7.500000e+000 ;
      nonzero elements row index =
       1
       1
       3
       4
       5
      nonzero elements column index =
       1
       3
       1
       2
       3
      nonzero elements values =

        5.1000
        1.2000
        4.3000
        2.4000
        7.5000


      See Also
      mfSpGet, mfSpGetM, mfSpGetN, mfSpGetNNZ
                                                                Chapter 8 Sparse Array   263



msSpDisplay
Display sparse array data.


Module
spml


Syntax
call msSpDisplay(spA)
call msSpDisplay(spA, name)
call msSpDisplay(spA1, name1, spA2, name2[, spA3, name3])



Descriptions
Procedure msSpDisplay shows the entries of a sparse array under MS-DOS console
window.

mfSpDisplay(x) displays the entries of mfSparse spA, with the caption 'ans ='.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: rindex(6), cindex(6)
     real(8) :: values(6)
     type(mfSparse) :: a
     rindex = (/1, 1, 1, 2, 2, 2/)
     cindex = (/1, 2, 3, 1, 2, 3/)
     values = (/1, 2, 3, 4, 5, 6/)
     call msSpAdd(a, rindex, cindex, values)
     call msSpDisplay(a, "a")
end program example


Result
a =
 a(1,1)    =   1.000000e+000   ;
 a(1,2)    =   2.000000e+000   ;
 a(1,3)    =   3.000000e+000   ;
 a(2,1)    =   4.000000e+000   ;
 a(2,2)    =   5.000000e+000   ;
 a(2,3)    =   6.000000e+000   ;


See Also
mfDisplay
264       MATFOR 4 in Fortran Reference Guide



      msSpExport
      Export sparse array data.


      Module
      spml


      Syntax
      call msSpExport(sp, filename)



      Descriptions
      Procedure msSpExport exports sparse array data to a file.



      Example

      Code
      program example
           use fml
           use spml
           implicit none
           integer(4) :: rindex(4), cindex(4)
           real(8) :: values(4)
           type(mfSparse) :: a
           rindex = (/1, 1, 2, 2/)
           cindex = (/1, 2, 1, 2/)
           values = (/1, 2, 3, 4/)
           call msSpAdd(a, rindex, cindex, values)
           ! Export sparse array a to a.txt
           call msSpExport(a, "a.txt")
      end program example


      See Also
      mfSpImport
                                                              Chapter 8 Sparse Array   265



mfSpImport
Import sparse array data.


Module
spml


Syntax
spA = mfSpImport(filename);



Descriptions
Procedure msSpImport imports sparse array data from a file.



Example

Code
program example
     use fml
     use spml
     implicit none
     integer(4) :: rindex(4), cindex(4)
     real(8) :: values(4)
     type(mfSparse) :: a, b
     rindex = (/1, 1, 2, 2/)
     cindex = (/1, 2, 1, 2/)
     values = (/1, 2, 3, 4/)
     call msSpAdd(a, rindex, cindex, values)
     ! Export sparse array a to a.txt.
     call msSpExport(a, "a.txt")
     ! Import sparse array b from a.txt.
     b = mfSpImport("a.txt")
     ! Display sparse b.
     call msSpDisplay(b, "b")
end program example


Result
b =
 b(1,1)    =   1.000000e+000   ;
 b(1,2)    =   2.000000e+000   ;
 b(2,1)    =   3.000000e+000   ;
 b(2,2)    =   4.000000e+000   ;


See Also
msSpExport
266       MATFOR 4 in Fortran Reference Guide



      mfSpEigs
      Find the eigenvalues and eigenvectors of a sparse array.


      Module
      spml


      Syntax
      eig = mfSpEigs(spA[, N, opt ])

      call msSpEigs(mfOut(val, vec), spA[, N, opt])



      Descriptions
      Procedure msSpEigs computes the eigenvalues and eigenvectors of a sparse array.

      eig = mfSpEigs(spA, N, opt)
      • This procedure returns a vector eig containing the eigenvalues of mfSparse spA.
      •   Argument N is the number of eigenvalues based on the option given in opt.
      •   Argument opt can be:
          LM: the N largest eigenvalues of mfSparse spA.
          SM: the N smallest eigenvalues of mfSparse spA.

      call msSpEigs(mfOut(val, vec), spA, N, opt)
      • This procedure returns a vector of eigenvalues val, and a full matrix mfArray vec
          whose columns are the corresponding eigenvectors, spA*vec = val*vec.

      Note: MATFOR uses ARPACK for computing eigen problems, but it uses
      mfEig(mfSpToFull(spA))when NCV - N < 2such that NCV is the number of column
      in spA.



      Example

      Code
      program example
           use fml
           use spml
           implicit none
           integer(4) :: rindex(7), cindex(7)
           real(8) :: values(7)
           type(mfArray) :: value, vector
           type(mfSparse) :: a
           rindex = (/1, 2, 3, 3, 4, 4, 5/)
           cindex = (/5, 2, 1, 3, 1, 3, 4/)
           values = (/19, 21, 44, 32, 88, 64, 90/)
           call msSpAdd(a, rindex, cindex, values)
                                                            Chapter 8 Sparse Array   267

    call msSpDisplay(a, "a")
    ! Evaluate eigenvalue and eigenvector of sparse array a.
    call msSpEigs(mfOut(value, vector), a)
    ! Display eigenvalue and eigenvector.
    call msDisplay(value, "value", vector, "vector")
end program example


Result
a =
a(1,5)     =   1.900000e+001   ;
a(2,2)     =   2.100000e+001   ;
a(3,1)     =   4.400000e+001   ;
a(3,3)     =   3.200000e+001   ;
a(4,1)     =   8.800000e+001   ;
a(4,3)     =   6.400000e+001   ;
a(5,4)     =   9.000000e+001   ;
value =

 66.2673       +0.0000i
-17.1337       +44.4662i
-17.1337       -44.4662i
  0.0000       +0.0000i
 21.0000       +0.0000i
vector =
column     1 to      4 ...
0.2161     +0.0000i 0.1167         +0.3028i 0.1167    -0.3028i   0.0000   +0.0000i
0.0000     +0.0000i 0.0000         +0.0000i 0.0000    +0.0000i   1.0000   +0.0000i
0.2775     +0.0000i 0.0775         -0.2011i 0.0775    +0.2011i   0.0000   +0.0000i
0.5550     +0.0000i 0.1550         -0.4021i 0.1550    +0.4021i   0.0000   +0.0000i
0.7538     +0.0000i -0.8139        +0.0000i -0.8139   +0.0000i   0.0000   +0.0000i

column     5 to      5
 0.5882    +0.0000i
 0.0000    +0.0000i
-0.8087    +0.0000i
 0.0000    +0.0000i
 0.0000    +0.0000i


See Also
mfEig
268       MATFOR 4 in Fortran Reference Guide



      mfSpLDiv
      Solve a sparse array system of linear equations.


      Module
      spml


      Syntax
      X = mfSpLDiv(spA, b)

      call msSpLDiv(mfOut(X), spA, b)



      Descriptions
      Procedure msSSpLDiv is normally used in solving an mfSprse array system of linear
      equations represented by Ax = b.

      Note: MATFOR uses SPOOLES for solving sparse Linear Algebra equations.



      Example

      Code
      program example
           use fml
           use spml
           implicit none
           integer(4) :: rindex(4), cindex(4)
           real(8) :: values(4)
           type(mfArray) :: x, b
           type(mfSparse) :: A
           ! Create sparse array A.
           rindex = (/1, 1, 2, 2/)
           cindex = (/1, 2 ,1 ,2/)
           values = (/1, 2, 3, 2/)
           call msSpAdd(A, rindex, cindex, values)
           call msSpDisplay(A, "A")
           ! Create mfArray b.
           b = (/3.0, 5.0/)
           b = mfReshape(b, (/2, 1/))
           ! Evaluate mfArray x that satisfies Ax = b.
           x = mfSpLDiv(A, b)
           call msDisplay(b, "b", x, "x")
      end program example


      Result
      A =
       A(1,1) = 1.000000e+000 ;
       A(1,2) = 2.000000e+000 ;
                           Chapter 8 Sparse Array   269

A(2,1) = 3.000000e+000 ;
A(2,2) = 2.000000e+000 ;
b =
 3
 5
x =
 1
 1


See Also
mfLDiv
270       MATFOR 4 in Fortran Reference Guide



      mfSpMul
      Multiply a sparse array onto an mfArray.


      Module
      spml


      Syntax
      c = mfSpMul(spA, B)

      call msSpMul(mfOut(c), spA, B)



      Descriptions
      Procedure mfSpMul returns the matrix product of mfSparse spA and mfArray B, where
      spA is an m-by-p matrix and B is a p-by-n matrix. The product of the matrix multiplication is
      an m-by-n mfArray.



      Example

      Code
      program example
             use fml
             use spml
             implicit none
             integer(4) :: rindex(3), cindex(3)
             real(8) :: values(3)
             type(mfArray) :: y, m
             type(mfSparse) :: x
             ! Create sparse array x.
             rindex = (/1, 2, 3/)
             cindex = (/1, 2, 1/)
             values = (/1, 2, 3/)
             call msSpAdd(x, rindex, cindex, values)
             call msSpDisplay(x, "x")
             ! Create mfArray y.
             y = mfOnes(2, 4)
             ! Evaluate mfArray m that satisfies x * y = m.
             m = mfSpMul(x, y)
             call msDisplay(y, "y", m, "m")
      end program example


      Result
      x =
       x(1,1) = 1.000000e+000 ;
       x(2,2) = 2.000000e+000 ;
       x(3,1) = 3.000000e+000 ;
       y =
               Chapter 8 Sparse Array   271


 1 1 1     1
 1 1 1     1
m =
 1 1 1     1
 2 2 2     2
 3 3 3     3


See Also
mfMul
272       MATFOR 4 in Fortran Reference Guide



      mfSpSize
      Return total number of elements in a sparse array.


      Module
      spml


      Syntax
      n = mfSpSize(spA)

      m = mfSpSize(spA, IDIM)

      call msSpSize(mfOut(nRow, nCol), spA)



      Descriptions
      Procedure mfSpSize returns the total number of elements in a sparse array.

      n = mfSpSize(spA) returns the number of elements in mfSparse spA.

      m = mfSpSize(spA, IDIM) returns the length of the dimension specified by the scalar
      IDIM.

      call msSpSize(mfOut(nRow, nCol), spA) returns the lengths of row and column
      dimensions of mfSparse spA.



      Example

      Code
      program example
           use spml
           use fml
           implicit none
           integer(4) :: k, m, n
           integer(4) :: rindex(3), cindex(3)
           real(8) :: values(3)
           type(mfSparse) :: a
           ! Create sparse array a.
           rindex = (/1, 3, 2/)
           cindex = (/2, 2, 5/)
           values = (/3, 5, 6/)
           call msSpAdd(a, rindex, cindex, values)
           call msSpDisplay(a, "a")
           ! Compute number elements in a.
           k = mfSpSize(a)
           call msDisplay(mf(k), "mfSpSize(a)")
           ! Compute number of row in a.
           m = mfSpSize(a, 1)
           call msDisplay(mf(m), "mfSpSize(a, 1)")
                                                Chapter 8 Sparse Array   273


      ! Compute number of column in a.
      n = mfSpSize(a, 2)
      call msDisplay(mf(n), "mfSpSize(a, 2)")
end program


Result
a =
a(1,2) = 3.000000e+000 ;
a(2,5) = 6.000000e+000 ;
a(3,2) = 5.000000e+000 ;
mfSpSize(a) =
 15
mfSpSize(a, 1) =
 3
mfSpSize(a, 2) =
 5


See Also
mfSize
274       MATFOR 4 in Fortran Reference Guide



      mfSpToFull
      Convert a sparse array into a full array.


      Module
      spml


      Syntax
      A = mfSpToFull(spA)

      call msSpToFull(mfOut(A), spA)



      Descriptions
      Procedure msSpToFull converts an mfSparse spA to a full mfArray A.
      If spA is a full matrix, it will remain unchanged.



      Example

      Code
      program example
           use fml
           use spml
           implicit none
           integer(4) :: rindex(5), cindex(5)
           real(8) :: values(5)
           type(mfArray) :: FULL
           type(mfSparse) :: SP
           ! Create sparse array SP.
           rindex = (/1, 1, 2, 3, 3/)
           cindex = (/1, 3, 2, 1, 3/)
           values = (/3, 2, 7, 5, 4/)
           call msSpAdd(SP, rindex, cindex, values)
           call msSpDisplay(SP, "SP")
          ! Convert sparse array SP into mfArray FULL.
          FULL = mfSpToFull(SP)
          call msDisplay(FULL, "FULL")
      end program example


      Result
      SP =
       SP(1,1)    =   3.000000e+000      ;
       SP(1,3)    =   2.000000e+000      ;
       SP(2,2)    =   7.000000e+000      ;
       SP(3,1)    =   5.000000e+000      ;
       SP(3,3)    =   4.000000e+000      ;
       FULL =
        3 0 2
        0 7 0
             Chapter 8 Sparse Array   275

 5 0 4


See Also
mfFullToSp
276       MATFOR 4 in Fortran Reference Guide



      mfFullToSp
      Convert a full array into a sparse array.


      Module
      spml


      Syntax
      spA = mfFullToSp(A)

      call msFullToSp(mfOut(spA), A)



      Descriptions
      Procedure msFullToSp converts a full mfArray A to an mfSparse spA.
      If A is a sparse matrix, it will remain unchanged.



      Example

      Code
      program example
           use spml
           use fml
           implicit none
           type(mfArray) :: full
           type(mfSparse) :: sp
           ! Create mfArray.
           full = mfRand(2, 3)
           call msAssign(mfS(full,MF_COL,2),0d0)
           ! Convert mfArray to sparse array.
           sp = mfFullToSp(full)
           ! Display mfArray.
           call msDisplay(full, "full")
           ! Display sparse array.
           call msSpDisplay(sp, "sp")
      end program example


      Result
      full =

         0.5742      0.0000      0.9509
         0.9433      0.0000      0.9647

      sp =
       sp(1,1) = 5.741892e-001 ;
       sp(1,3) = 9.508580e-001 ;
       sp(2,1) = 9.432698e-001 ;
                            Chapter 8 Sparse Array   277

sp(2,3) = 9.646586e-001 ;


See Also
mfSpToFull
278       MATFOR 4 in Fortran Reference Guide



      mfSpy, msSpy
      Draw pattern of a sparse array.


      Module
      spml


      Syntax
      h = mfSpy(sp)
      call msSpy(sp)



      Descriptions
      Procedure mfSpy shows the sparsity pattern of the given sparse array sp, in which the
      nonzero elements are plotted.



      Example
      The example plots a 100 by 100 sparse array.

      Code
      program example
          use fml
          use fgl
          use spml
          implicit none
          integer(4) :: i,j,c
          real(8) :: values
          type(mfSparse) :: a
          values = 10d0
          a = mfSpCreate(100,100)
           do i=1,100
              call msSpSet(a,i,i,values)
           end do
           j=1
           do i=10,70
               call msSpSet(a,j,i,values)
               call msSpSet(a,i,j,values)
                j=j+1;
           end do
           c = j;
           do j=71,100
              call msSpSet(a,c,j,values)
              call msSpSet(a,j,c,values)
           end do
           !Show Graph of Sparse array a
           call msSpy(a);
           call msAxis('equal');
          call msColormap('spy');
          call msColorbar('on');
           call msViewPause();
                      Chapter 8 Sparse Array   279


end program example


Result




See Also
mfSpToFull
280   MATFOR 4 in Fortran Reference Guide
                                                  Chapter 9 Visualization Routines   281



 CHAPTER 9




MATFOR Visualization Routines


 Windows Frame and Figure

 Figure


 msFigure                   Create figure in Graphics Viewer.
 msCloseFigure              Close figure in Graphics Viewer.
 mfFigureCount              Number of figures in graphics viewer.

 Window Frame


 mfWindowCaption            Graphics Viewer title.
 mfWindowSize               Graphics Viewer frame size.
 mfWindowPos                Graphics Viewer frame position.

 Display


 msGDisplay                 Display mfArray data on a MATFOR Data
                            Viewer.
 msDrawNow                  Draw all pending graphs in current figure.
 msViewPause                Pause program execution.

 Configuration


 msSaveConfig               Save display configuration.
 msLoadConfig               Load pre-saved display configuration.

 Recording
282       MATFOR 4 in Fortran Reference Guide


      mfRecordStart/                    Record animation as AVI file or MATFOR mfa
      mfRecordEnd                       file.
      mfExportImage                     Save figure graph as picture file.



      Subplot

      Plot Creation and Control


      mfSubplot                         Create subplot in active figure.
      msClearSubplot                    Remove all draws in specified subplot.
      msHold                            Hold previous graph on plot space.
      mfIsHold                          Return status of plot space.

      Plot Annotation and Appearance


      mfTitle                           Graph title.
      mfXLabel                          X-axis label.
      mfYLabel                          Y-axis label.
      mfZLabel                          Z-axis label.
      mfText                            2-D text annotation
      mfAnnotation                      3-D text annotation
      msShading                         Shading methodology of surface object.
      msColorbar                        Display color scale.
      msColormap                        Colormap type.
      mfColormapRange                   Range of colormap.
      mfBackgroundColor                 Background color of plot space.

      Axis Control


      mfAxis                            Manipulate axis object.
      mfAxis2DMode                      Switch display mode to 2D mode.
      mfAxis3DMode                      Switch display mode to 3D mode.
      mfAxis2DDependency                Set axis dependency of 2D display mode.
      mfAxis3DDependency                Set axis dependency of 3D display mode.
      mfAxis2DRange                     Set the axis range of 2D display mode.
      mfAxis3DRange                     Set the axis range of 3D display mode.
      msAxis2DPosition                  Set axis position in the plot window.
                                            Chapter 9 Visualization Routines   283


msAxisWall            Manipulate the axis wall object.
msAxisGrid            Display grid lines.


Object & Camera


Object Manipulation


msObjRotateX          Rotate draw object in degrees about the x-axis
                      using the right hand rule.
msObjRotateY          Rotate draw object in degrees about the y-axis
                      using the right hand rule.
msObjRotateZ          Rotate draw object in degrees about the z-axis
                      using the right hand rule.
msObjRotateWXYZ       Rotate draw object in degrees about an arbitrary
                      axis.
mfObjScale            Scale of draw object.
mfObjPosition         Position of draw object in world coordinates.
mfObjOrigin           Origin of draw object.
mfObjOrientation      Return WXYZ orientation of draw object.

Camera Manipulation


mfCamAngle            Set the camera view angle.
mfCamAzElRoll         Set the camera view direction.
mfCamDistance         Set the camera distance.
mfCamProj             Set the camera projection mode.
mfCamFocal            Set the camera focal point.
mfCamZoom             Zoom the displaying object in or out.
mfGetCamViewParam     Retrieve camera configuration values of an
                      object.
msSetCamViewParam     Set camera configuration values for the display
                      object.
msView                Viewpoint specification.


Graphics


Linear Graphs
284       MATFOR 4 in Fortran Reference Guide


      mfPlot                              2-D linear graphs.
      mfPlot3                             3-D linear graphs.
      mfRibbon                            3-D ribbons.
      mfTube                              3-D tubes.
      mfStem                              2-D stem graphs.
      mfBar                               2-D vertical bars.
      mfBarh                              2-D horizontal bars.
      mfBar3                              3-D vertical bars.
      mfBar3h                             3-D horizontal bars.

      Surface Graphs


      mfSurf                              Surface plot.
      mfMesh                              Mesh plot.
      mfSurfc                             Combined plot of surface and contour3.
      mfMeshc                             Combined plot of mesh and contour3.
      mfPColor
      mfFastPColor                        Pseudocolor plot of a matrix.
      mfContour                           2-D contour.
      mfContour3                          3-D contour.
      mfSolidContour                      2-D solid contour.
      mfSolidContour3                     3-D solid contour.
      mfOutline                           Wireframe outline corners.
      mfIsoSurface                        3-D plot isovalue surface from volume data.
                                          3-D iso-value surface plots from volumetric
      mfGetIsoSurface                     data.

      Slice Graphs


      mfSliceXYZ                          Display orthogonal slice-planes through
                                          volumetric data.
      mfSliceIJK                          Display orthogonal slice-planes along i, j or k
                                          indices.
      mfSlicePlane                        Display orthogonal slice-planes along arbitrary
                                          direction.
      mfGetSliceXYZ                       Retreive orthogonal slice-plane(s) through
                                          volumetric data.
                                                  Chapter 9 Visualization Routines   285


mfGetSliceIJK               Retrieve orthogonal slice-plane(s) along i, j or
                            k indices.
mfGetSlicePlane             Retrieve orthogonal slice-plane(s) along
                            arbitrary direction.

Streamline Graphs


mfStreamLine2               Streamlines from 2-D vector data.
mfStreamDashedLine2         Stream of dashed lines from 2-D vector data.
mfStreamRibbon2             Stream of ribbons from 2-D vector data.
mfStreamArrow2              Stream of arrows from 2-D vector data.
mfStreamTube2               Stream of tubes from 2-D vector data.
mfStreamLine3               Streamlines from 3-D vector data.
mfStreamDashedLine3         Stream of dashed lines from 3-D vector data.
mfStreamRibbon3             Stream of ribbons from 3-D vector data.
mfStreamTube3               Stream of tubes from 3-D vector data.
mfStreamArrow3              Stream of arrows from 3-D vector data.

Triangular Surface Graphs


mfTriSurf                   Polygonal surface plot.
mfTriMesh                   Polygonal mesh plot.
mfTriContour                Contour on polygonal plot.
mfPatch                     Add patch on 2-D or 3-D coordinates.

Unstructured Grids


mfTetSurf                   Polyhedral surface plot.
mfTetMesh                   Polyhedral mesh plot.
mfTetContour                Contour on polyhedral plot.
mfTetIsoSurface             Poyhedral isosurface plot.
                            Orthogonal slice-planes through volumetric
mfTetSliceXYZ               data.
286       MATFOR 4 in Fortran Reference Guide


      mfTetSlicePlane                     Orthogonal slice-planes along an arbitrary
                                          direction.
                                          3-D iso-value surface plots from polyhedral
      msGetTetIsoSurface                  data.
                                          Orthogonal slice-planes through polyhedral
      msGetTetSliceXYZ                    data.
      msGetTetSlicePlane                  Orthogonal slice-planes along an arbitrary
                                          direction.

      Unstructured Streamlines


      mfTriStreamLine                     Create streamlines from two-dimensional
                                          unstructured mesh data.
      mfTriStreamDashedLine               Create stream dashed-lines from
                                          two-dimensional unstructured mesh data.
      mfTriStreamRibbon                   Create stream ribbons from two-dimensional
                                          unstructured mesh data.
      mfTriStreamTube                     Create stream tubes from two-dimensional
                                          unstructured mesh data.
      mfTriStreamArrow                    Create stream arrows from two-dimensional
                                          unstructured mesh data.
      mfTetStreamLine                     Create streamlines from three-dimensional
                                          unstructured mesh data.
      mfTetStreamDashedLine               Create stream dashed-lines from
                                          three-dimensional unstructured mesh data.
      mfTetStreamRibbon                   Create stream ribbons from three-dimensional
                                          unstructured mesh data.
      mfTetStreamTube                     Create stream tubes from three-dimensional
                                          unstructured mesh data.
      mfTetStreamArrow                    Create stream arrows from three-dimensional
                                          unstructured mesh data.

      Unstructured Point Set


      mfPoint                             Display input points in 3-D space.
      mfDelaunay                          Display 2-D Delaunay triangulation of input
                                          points.
                                           Chapter 9 Visualization Routines   287


mfDelaunay3        Display 3-D Delaunay triangulation of input
                   points.
mfGetDelaunay      Retreive 2-D Delaunay triangulation of input
                   points.
mfGetDelaunay3     Retreive 3-D Delaunay triangulation of input
                   points.

Velocity Vectors


mfQuiver           2-D velocity vectors.
mfQuiver3          3-D velocity vectors.

Image


Image              Display image file.
mfImRead           Read in image file.
mfImWrite          Write to image file.




2-D&3-D Objects


mfCircle           Draw a circle
mfSquare           Draw a square.
mfMolecule         Draw stick and ball model of molecules.
mfSphere           Draw a sphere.
mfCube             Draw a cube.
mfCylinder         Draw a cylinder.
mfCone             Draw a cone.
mfAxisMark         3-directional mark on arbitrary point.

Property Setting


msGSet             Set property of specified graph.
msDrawMaterial     Set draw object's transparency reflectance,
                   ambient reflectance, diffuse reflectance and
                   specular reflectance.
msDrawTexture      Texture mapping.
288       MATFOR 4 in Fortran Reference Guide


      mfIsValidDraw                       Check validity of draw object.
      mfGetCurrentDraw                    Return handle of current draw object.
      msRemoveDraw                        Remove draw object from plot space.
      msSetDrawName                       Name of draw object.

      Graphics Viewer Manipulation


      mfPrintPreview                      Pop up print preview dialog box.
      mfEditorDrawList                    Pop up draw-list editor.
      mfEditorMaterial                    Pop up material editor.
      mfEditorColormap                    Pop up colormap editor.
      mfEditorTransform                   Pop up transformation editor.
      mfEditorAxis                        Pop up axis editor.
      mfEditorColorbar                    Pop up colorbar editor.
      mfEditorBackground                  Pop up background editor.




      Simple GUI


      msShowMessage                       Pop up message dialog box.
      mfInputString                       Pop up string insertion dialog box.
      mfInputValue                        Pop up value insertion dialog box.
      mfInputVector                       Pop up vector insertion dialog box.
      mfInputMatrix                       Pop up matrix insertion dialog box.
      mfFileDialog                        Pop up file open dialog box.
      mfInputYesNo                        Pop up yes-no query dialog box.
         Chapter 9 Visualization Routines   289




Figure
290       MATFOR 4 in Fortran Reference Guide



      mfFigure, msFigure
      Create figure in Graphics Viewer.


      Module
      fgl


      Syntax
      call   msFigure(figure_id)
      call   msFigure(figure_name)
      call   msFigure(figure_id, figure_name)
      id =   mfFigure()



      Descriptions
      Procedure mfFigure creates a new figure with ID specified by argument figure_id and
      with name specified by argument figure_name. The ID and name of the figure is
      displayed on the figure tab.

      call msFigure()
      • If argument figure_id is not provided, it creates a new figure with an automatically
          selected figure ID.

      id = mfFigure(...)
      • If the procedure is used in function format, it will return the figure ID once the figure is
          created.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y1, y2, y3
      integer :: num
      x = mfLinspace(-MF_PI, MF_PI, 100)
      y1 = mfSin(x)
      y2 = mfCos(x)
      y3 = mfLinspace(-1, 1, 100)
      ! Create figure 1 and plot x, y1
      call msFigure(1)
      call msPlot(x, y1)
      call msAxis(mf((/-MF_PI, MF_PI, -1.0d0, 1.0d0/)))
      ! Returns number of figures
      num = mfFigureCount()
                                             Chapter 9 Visualization Routines   291

call msDisplay(mf(num), 'mfFigureCount()')
call msViewPause()
! Create figure 2 and plot x, y2
call msFigure(2)
call msPlot(x, y2, 'r')
call msAxis(mf((/-MF_PI, MF_PI, -1.0d0, 1.0d0/)))
! Returns number of figures
num = mfFigureCount()
call msDisplay(mf(num), 'mfFigureCount()')
call msViewPause()
! Create figure 3 and plot x, y3
call msFigure(3)
call msPlot(x, y3, 'g')
call msAxis(mf((/-MF_PI, MF_PI, -1.0d0, 1.0d0/)))
! Returns number of figures
num = mfFigureCount()
call msDisplay(mf(num), 'mfFigureCount()')
call msViewPause()
! Close figure 2
call msCloseFigure(2)
! Returns number of figures
num = mfFigureCount()
call msDisplay(mf(num), 'mfFigureCount()')
call msViewPause()
call msFreeArgs(x, y1, y2, y3)
end program example


See Also
mfCloseFigure, mfFigureCount
292       MATFOR 4 in Fortran Reference Guide



      msCloseFigure
      Close figure in Graphics Viewer.


      Module
      fgl


      Syntax
      call msCloseFigure(figure_id)



      Descriptions
      Procedure msCloseFigure closes the target figure specified by argument figure_id.



      Example
      To be referred to mfFigure

      See Also
      mfFigure, mfFigureCount
                                                       Chapter 9 Visualization Routines   293



mfFigureCount
Number of figures in Graphics Viewer.


Module
fgl


Syntax
num = mfFigureCount()



Descriptions
Procedure mfFigureCount returns the number of figures that are in the Graphics Viewer.



Example
To be referred to mfFigure

See Also
mfFigure, msCloseFigure
294    MATFOR 4 in Fortran Reference Guide




      Window Frame
                                                         Chapter 9 Visualization Routines   295



mfWindowCaption, msWindowCaption
Graphics Viewer title.


Module
fgl


Syntax
title = mfWindowCaption()

call msWindowCaption(title)



Descriptions
Procedure mfWindowCaption sets the caption on the top window panel of the Graphics
Viewer.

title = mfWindowCaption()
• It can also be used as an inquiry procedure if given no argument.

call msWindowCaption(title)
• Argument title can be a string or an mfArray containing a string.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: x, y
x = mfLinspace(0, 2*MF_PI, 101)
y = mfSin(x)
call msPlot(x, y)
call msWindowCaption('Example Change WindowCaption to 2D Plot')
call msViewPause()
call msFreeArgs(x, y)
end program example


See Also
mfWindowSize, mfWindowPos
296       MATFOR 4 in Fortran Reference Guide



      mfWindowSize, msWindowSize
      Graphics Viewer frame size.


      Module
      fgl


      Syntax
      size = mfWindowSize()

      call msWindowSize(width, height)
      call msWindowSize(size)



      Descriptions
      Procedure mfWindowSize sets the frame size of the Graphics Viewer.

      call msWindowSize(width, height)
      • Arguments width and height can be integer scalars or mfArrays containing integer
          scalars.

      msWindowSize(size)
      • Argument size is a 1x2 mfArray.

      size = mfWindowSize()
      • It can be used as an inquiry function for the frame size if no argument is specified. The
          return argument size is a double vector in the format [width, height].



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y
      x = mfLinspace(0, 2*MF_PI, 101)
      y = mfSin(x)
      call msPlot(x, y)
      call msWindowSize(600, 600)
      call msViewPause()
      call msFreeArgs(x, y)
      end program example

      See Also
                                                           Chapter 9 Visualization Routines   297



mfWindowPos, msWindowPos
Graphics Viewer frame position.


Module
fgl


Syntax
pos = mfWindowPos()

call msWindowPos(x, y)
call msWindowPos(pos)



Descriptions
Procedure mfWindowPos sets the frame position of the Graphics Viewer.

call msWindowPos(x, y)
• Arguments x and y can be integer scalars or mfArrays containing integer scalars.

call msWindowPos(pos)
• Argument pos is a 1x2 mfArray.

pos = mfWindowPos()
• It can be used as an inquiry function for the frame position if no argument is specified.
    The return argument pos is a integer vector in the format [x, y].



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: x, y
x = mfLinspace(0, 2*MF_PI, 101)
y = mfSin(x)
call msPlot(x, y)
call msWindowPos(220, 0)
call msViewPause()
call msFreeArgs(x, y)
end program example

See Also
mfWindowSize
298     MATFOR 4 in Fortran Reference Guide



      Display
                                                          Chapter 9 Visualization Routines     299



msGDisplay
Display mfArray data on a MATFOR Data Viewer.


Module
fgl


Syntax
call msGDisplay(x)
call msGDisplay(x, "name"[, x1, "name1", ...])

Descriptions
Procedure msGDisplay displays your mfArray data on a Data Viewer.

You can output single or multiple mfArray data to the Data Viewer.

call msGDisplay(x), call msGDisplay(x , "name")
• Display data of mfArray x on Data Viewer.
•   Character string "name" specifies the label on the spreadsheet tab displaying data of x.

call msGDisplay(x, "name", x1, "name1", ...)
• Display multiple datasets x, x1, ...), on the Data Viewer, labeled with "name",
    "name1", ... respectively. The arguments must be specified in pairs.

Example
Code
program example
use fgl
use fml
implicit none
type (mfArray):: x, y, z
integer :: i
x = (/(i, i=1, 10)/)
y = (/(i, i=-10, -1)/)
z = mfComplex(x,y)
! Next, display the data of X, Y and Z on a MATFOR Data
! Viewer.
call msGDisplay(x, 'x', y, 'y', z, 'z')
! Pause program to display Data Viewer
call msViewPause
! Deallocate mfArrays
call msFreeArgs(x, y, z)
end program example

See Also
msDisplay
300       MATFOR 4 in Fortran Reference Guide



      msDrawNow
      Draw all pending graphs.


      Module
      fgl


      Syntax
      call msDrawNow()


      Descriptions
      Procedure msDrawNow draws all pending graphics on the current Figure.

      The procedure is used mainly for animation, it does not pause program execution. As a result,
      the Figure is displayed, updated, and flushed almost immediately. Animation results when
      msDrawNow is used within a do loop in which the graphics object is continuously being
      updated.

      Example
      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, h
      integer :: i
      x = mfLinspace(-MF_PI, MF_PI, 50)
      y = mfSin(x)
      ! Create an initial copy of the graph to be animated.
      ! This is recommended as you can obtain the current
      ! graphics handle and use erase mode for the animation.
      h = mfPlot(x, y)
      call msAxis(mf((/-MF_PI, MF_PI, -1d0, 1d0/)))
      ! Use a Do Loop to animate the sin(x) curve. Note,
      ! msGSet continuously updates the specified data and
      ! sleep slows down the program execution.
      do i = 1, 100
         y = mfSin(x+0.1d0*i)
         call msGSet(h, 'ydata', y)
         call msDrawNow()
      end do
      ! Pause the program to continue displaying the
      ! Graphics Viewer after the Do Loop ends.
      call msViewPause()
      ! Deallocate mfArrays
      call msFreeArgs(x, y, h)
      end program example

      See Also
      msViewPause
                                                          Chapter 9 Visualization Routines       301



msViewPause
Pause program execution.


Module
fgl


Syntax
call msViewPause()



Descriptions
Procedure msViewPause pauses program execution for graphical display.

Use this procedure wherever you wish to pause a program to visualize your data. To continue
your program execution, you can click on the "Continue" button located at the top right corner
of the Graphics Viewer.

You must add at least one line of call msViewPause() after each set of graphical
creation routines. If the procedure were left out, you would only see a flash as the Graphics
Viewer is opened and closed almost immediately by the program.



Example
To be referred to msDrawNow

See Also
302     MATFOR 4 in Fortran Reference Guide




      Configuration
                                                   Chapter 9 Visualization Routines   303



msSaveConfig
Save display configuration.


Module
fgl


Syntax
call msSaveConfig(filename, config)



Descriptions
Procedure msSaveConfig saves the display configuration into a MATFOR defined
configuration file (*.mfcg) with the filename given.

Argument config is a string that can be "all", "axis", "background", "colorbar" or
"colormap".



Example

See Also
msLoadConfig
304       MATFOR 4 in Fortran Reference Guide



      msLoadConfig
      Load pre-saved display configuration.


      Module
      fgl


      Syntax
      call msLoadConfig(filename, config)



      Descriptions
      Procedure msLoadConfig loads the pre-saved configuration file (*.mfcg) with the
      specified configuration type.

      Argument config is a string that can be "all", "axis", "background", "colorbar", "colormap"
      or "material".



      Example

      Code
      program example
            use fml
            use fgl
            implicit none
            type(mfArray) :: x,y,z,h
            !Create Surface Data to draw
            call msCreateSurfData(mfOut(x,y,z),1,30,30)
            call msFigure('Save Config')
            !Load Previous saved setting(Colorbar,Axis...)
            call msLoadConfig('graphic.mfcg','all')
            call   msSurf(x,y,z)
            call   msAxis3DDependency('xyz_depend',2,1)
            call   msAxis('xtick_format','%-3.1e')
            call   msXLabel('First Axis')
            call   msYLabel('Second Axis')
            call   msZLabel('Third Axis')
            call msViewPause()
            !Save Current setting before program exit
            !If user change property like axis wall color will be saved
            call msSaveConfig('graphic.mfcg','all')
      end program example


      See Also
      msSaveConfig
            Chapter 9 Visualization Routines   305




Recording
306       MATFOR 4 in Fortran Reference Guide



      msRecordStart, msRecordEnd
      Record animation as an avi file or multiple bitmap files.


      Module
      fgl


      Syntax
      call msRecordStart(filename[, property1, value1, ...])
      call msRecordEnd()



      Descriptions
      Procedures msRecordStart and msRecordEnd are built-in MATFOR procedures for
      recording visualized data as avi animation files.
      call msRecordStart(filename, property1, value1, property2, value2,
      property3, value3)
      • Records the animations as avi files.
      •   Argument filename can take the following values.
                                                         Chapter 9 Visualization Routines   307


     Value      Meaning

    “*.avi”    Example: “filename.avi”.
                    Record the current animation in an avi file.
                    Avi or video recording uses frame capturing method to
                    capture the animation playing on the current Graphics
                    Viewer. The recorder automatically detects the type of video
                    compression utilities available in your system and presents a
                    drop-list for you to choose.

    “*.mfa”    Example: “filename.mfa”.

                    Record the current animation as an mfa file. The mfa file
                    format is a MATFOR-specific record of all data used for
                    generating the current animation on the Graphics Viewer.
                    You can playback the animation by using MATFOR
                    mfPlayer at a later time.
                    Using mfPlayer, you can perform graphical manipulations
                    on the animation, such as zoom in/out, rotation, colormap
                    adjustment, etc.

    “*.bmp”    Example: “filename.bmp”.

                    Save each frame of the animation into a bitmap file. The
                    name of each bitmap file is set to be the input file name
                    followed by four digits starting from 0000 counting up. In
                    the example, the names of the first two bitmap files would
                    be “filename0000.bmp” and “filename0001.bmp”.
“*.tif”
               Example: “filename.tif”.

                    Save each frame of the animation into a TIFF file. The
                    naming method of the saved files is similar to saving as
                    bitmap files.




•   The optional arguments property1,property2 and property3 and the
    corresponding arguments value1,value2 and value3 can take the following values.

    Property      Meaning
308        MATFOR 4 in Fortran Reference Guide


      “framerate”          Specify the number of frames captured per second. The
                           argument applies only when the animation file is saved in avi
                           format. By default, MATFOR records avi file at 15 frames per
                           second. The recommended range is 5 to 30 frames per second.
                           The higher the frame rate, the faster the frames are looped
                           through. Likewise, smaller frame rate slows down the
                           animation.



           “width”         Specify the width of the captured figure frame. The argument
                           applies only when the animation is saved in avi format or bmp
                           format. Without specifying the argument, the captured figure
                           frame will have the exact same width as the displaying figure
                           frame.

           “height”        Specify the height of the captured figure frame. The argument
                           applies only when the animation is saved in avi format or bmp
                           format. Without specifying the argument, the captured figure
                           frame will have the exact same height as the displaying figure
                           frame.


      call msRecordEnd()
      • Stop the recording.
      The general syntax of the recording procedures is as follows:

      call msRecordStart('animation.avi')

      or

      call msRecordStart('animation.bmp')
         ------- <animation codes>
      call msRecordEnd()



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, b, c, x, y, z, indxi, indxj, h
      integer :: i
      a = mfLinspace(-3, 7, 51)
                                           Chapter 9 Visualization Routines   309

b = mfLinspace(-2, 8, 51)
call msMeshgrid(mfout(x, y), a, b)
! Next, initialize indxi and indxj using Meshgrid.
! Compute z using indxi and indxj.
! Note, a 'd0' is added to the integers, to ensure
! double precision. MATFOR uses only double precision
! data.
c = mfColon(1, 51)
call msMeshgrid(mfout(indxi, indxj), c)
z = 3d0*mfSin((indxi+1)/10d0)*mfCos((indxj+1)/10d0) &
   + 2d0*mfSin((indxi+indxj)/10d0)
! Plot a mesh grid using mfArray x, y and z for the grid
! intersections.
h = mfMesh(x, y, z)
! Start record of an animation using avi file format
! Records scarf.avi in the Debug directory
call msRecordStart('scarf.avi')
! Animate the mesh using a do loop.
do i = 1, 10
    z = 3d0*mfSin((indxi+i+1)/10d0)*mfCos((indxj+1-i)/10d0) &
       + 2d0*mfSin((indxi+indxj+i)/10d0)
! Update z
  call msGSet(h, 'zdata', z)
! Update Graphics Viewer
  call msDrawNow()
end do
! end video record
call msRecordEnd()
! Pause to display the graph.
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


See Also
msGSet, mfFigure
310       MATFOR 4 in Fortran Reference Guide



      msExportImage
      Save figure graph as picture file.


      Module
      fgl


      Syntax
      call msExportImage(filename[, width, height])



      Descriptions
      Procedure msExportImage saves the graph(s) in the current figure as a picture file. You
      can choose the picture format by specifying the extension in argument filename. For
      example, "filename.bmp" would save it as a bitmap file. The supported formats are:
      BMP, JPEG, TIFF, PS and PNG.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, b, c, x, y, z, indxi, indxj, h
      integer :: i,j
      character*4 FileNameID
      a = mfLinspace(-3, 7, 51)
      b = mfLinspace(-2, 8, 51)
      call msMeshgrid(mfout(x, y), a, b)
      c = mfColon(1, 51)
      call msMeshgrid(mfout(indxi, indxj), c)
      z = 3d0*mfSin((indxi+1)/10d0)*mfCos((indxj+1)/10d0) &
         + 2d0*mfSin((indxi+indxj)/10d0)
      ! Plot a mesh grid using mfArray x, y and z for the grid
      ! intersections.
      h = mfMesh(x, y, z)
      ! Animate the mesh using a do loop.
      do i = 1, 10
          write(FileNameID,'(I4)')i
          do j=1,4
              if(FileNameID(j:j).eq.' ')FileNameID(j:j)='0'
          end do
          z = 3d0*mfSin((indxi+i+1)/10d0)*mfCos((indxj+1-i)/10d0) &
             + 2d0*mfSin((indxi+indxj+i)/10d0)
      ! Update z
        call msGSet(h, 'zdata', z)
      ! Update Graphics Viewer
        call msDrawNow()
      ! Export Visualization Result to JPG file.
                                           Chapter 9 Visualization Routines   311

  call msExportImage('exImg'//FileNameID//'.jpg',640,480)
end do
! Pause to display the graph.
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


See Also
312     MATFOR 4 in Fortran Reference Guide




      Plot Creation and Control
                                                            Chapter 9 Visualization Routines        313



mfSubplot, msSubplot
Create subplots in an active figure.


Module
fgl


Syntax
call msSubplot(m, n, p)

call msSubplot(formatString, p)



Descriptions
Procedure mfSubplot divides the plot space of Graphics Viewer into m-by-n rectangular
subplot spaces, as specified by the m, n arguments.

Each subplot space is numbered column-wise so that a subplot space at position (2, 1) is
numbered 2 and (2, 2) is numbered 4. The current subplot is set to the subplot number, given
p. Any subsequent operations will be performed on the current subplot.


      (1, 1)           (1, 2)
   subplot 1         subplot 3
      (2, 1)           (2, 2)
   subplot 2         subplot 4


A more powerful subplot division can be specified using mfSubplot(formatString, p).
formatString is a string of subplot format specified using numbers, commas, and open/closed
braces ([,]) that represents column width/row height ratios. For example, mfSubplot('4,6[5,5]',
1) divides the plot space into left and right subplots with width ratio of 4:6. The right subplot
is then divided into top and bottom subplots with height ratio of 5:5. The current subplot is set
to subplot 1.


 subplot 1     subplot 2
               subplot 3


To select another subplot within the same layout, a null string can be used for formatString
argument. For example, mfSubplot(" ", 2) will set the current subplot to subplot 2.

mfSubplot("3, 3, 4", 2) creates three subplots under plot space with width ration of
3:3:4. And the current subplot is set to subplot 2.
 subplot 1     subplot 2   subplot 3
314      MATFOR 4 in Fortran Reference Guide




      Example

      Code
      program example
          use fml
          use fgl
          implicit none
          type(mfArray) :: x, y1, y2,h(4)
          integer i
          x = mfLinspace(0, 2*MF_PI, 101)
          y1 = mfSin(x)
          y2 = mfASin(y1)
          ! Divide the plotting space into 1 on left 2 on right sub-plot spaces,
          ! and specify the subplot space 1 or left sub-plot as current.
          call msSubplot("4, 6[4, 6[5, 5]]", 1)
          ! Plot and label the graph.
          h(1) = mfPlot(x, y1)
          !call msPlot(x, y1)
          call msTitle("1: Graph of sin(x)")
          call msXLabel("Angle in Radians, x")
          ! Next, specify subplot space p=2, or the right-top subplot
          ! space as current.
          call msSubplot("", 2)
          ! Again, plot and label the graph.
          !call msPlot(y1, y2, "r")
          h(2) = mfPlot(y1, y2, "r")
          call msTitle("2: Graph of Arcsine(x)")
          call msXLabel("sin(x)")
          ! Finally, specify subplot space p=3, or the right-bottom subplot
          ! space as current.
          call msSubplot("", 3)
          ! Again, plot and label the graph.
          h(3) = mfPlot(x, y1+y2, "g")
          call msTitle("3: Difference Plot")
          call msXLabel("sin(x)")
          call msSubplot("", 4)
          h(4) = mfPlot(x, y1-y2, "y")
          call msTitle("4: Subplot 4")
          ! Pause the program to display the graphs.
          call msViewPause()
          !Animation
          do i=1,100
              y1 = mfSin(x+i*1d-1)
              y2 = mfASin(y1)
              call msGSet(h(1),'ydata',y1)
              call msGSet(h(2),'ydata',y2)
              call msGSet(h(3),'ydata',y1+y2)
              call msGSet(h(4),'ydata',y1-y2)
              call msDrawNow()
          end do
          !Remove 3rd Subplot ID
          call msShowMessage("Remove 3rd Subplot ID")
          call msSubplot("",3)
          call msClearSubplot()
          call msViewPause()
          !Free Memory resource
          call msFreeArgs(x, y1, y2)
                                Chapter 9 Visualization Routines   315

    do i=1,4
        call msFreeArgs(h(i))
    end do
end program example


Result




See Also
msClearSubplot
316       MATFOR 4 in Fortran Reference Guide



      msClearSubplot
      Remove all drawings from specified subplot.


      Module
      fgl


      Syntax
      call msClearSubplot()



      Descriptions
      Procedure msClearSubplot removes all drawings from the current subplot.



      Example
      To be referred to msSubplot

      See Also
      mfSubplot
                                                         Chapter 9 Visualization Routines      317



msHold
Hold previous graph on plot space.


Module
fgl


Syntax
call msHold(mode)



Descriptions
Procedure msHold holds the current graph in plot space so that it would not be overwritten
by the next graph creation. Subsequent graphs are drawn one after another in the plot space.

Argument mode is a string containing "on" or "off".



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: x, y1, y2, a
x = mfLinspace(0, 2*MF_PI, 100)
y1 = mfSin(x)
y2 = mfCos(x)
! Plot y1 = mfSin(x)
call msPlot(x, y1)
call msAxis(mf((/0d0, 2*MF_PI, -1d0, 1d0/)))
! Hold the figure for plotting
call msHold('on')
! Plot y2 = mfCos(x) to the same figure
call msPlot(x, y2, 'r')
call msHold('off')
! Pause the figure for viewing
call msViewPause()
! Deallocates the mfArrays
call msFreeArgs(x, y1, y2)

end program example


Result
318      MATFOR 4 in Fortran Reference Guide




      See Also
      mfIsHold
                                                       Chapter 9 Visualization Routines     319



mfIsHold
Return status of plot space.


Module
fgl


Syntax
status = mfIsHold()



Descriptions
Procedure mfIsHold returns the status of the current plot space. The output is an mfArray
containing logical data. Returns true if the plot space is on hold, false otherwise.



Example
To be referred to msHold

See Also
msHold
320     MATFOR 4 in Fortran Reference Guide




      Plot Annotation and
      Appearance
                                                                Chapter 9 Visualization Routines      321



mfTitle, mfXLabel, mfYLabel, mfZLabel
Label the axis objects.


Module
fgl


Syntax
title = mfTitle()
xlabel = mfXLabel()
ylabel = mfYLabel()
zlabel = mfZLabel()

call   msTitle(title[, color][, font_size])
call   msXLabel(xlabel)
call   msYLabel(ylabel)
call   msZLabel(zlabel)



Descriptions
Procedures mfTitle, mfXLabel, mfYLabel and mfZLabel annotate a graph with title,
x-axis label, y-axis label and z-axis label respectively. By default, x-axis is labeled as "X
Axis", y-axis is labeled as "Y Axis" and z-axis label is labeled as "Z Axis".

You can also annotate the graph through Axis Setting ->Axis ->Label on the Graphics Viewer.

title = mfTitle()
xlabel = mfXLabel()
ylabel = mfYLabel()
zlabel = mfZLabel()
They can also be used as inquiry procedures to retrieve the title and labels that are set by users.

call msTitle(title, color, font_size)
• Set the rgb color code and the font size of the title by specifying arguments color and
    font_size. The rgb color code is specified as [r, g, b] where 0 < r, g, b < 1.



Example

Code
program example
use fml
use fgl
implicit none
integer i
type(mfArray) :: x, y, ht(5)
322      MATFOR 4 in Fortran Reference Guide

      x = mfLinspace(0, 2*MF_PI, 51)
      y = mfSin(x)
      ! Plot the x, y curve using msPlot.
      call msPlot(x, y, 'rx-')
      ! Annotate the graph with title, x-axis label and y-axis label.
      call msTitle('Graph of sin(x)')
      call msXLabel('x in radians')
      call msYLabel('sin(x)')
      ! Add 2d Text annotation
      ht(1) = mfText(mf('Left Bottom corner'),mf((/0d0,0.02d0/)), &
                mf((/1,0,0/)),mf(5))
      call msGSet(ht(1),'just','left')
      ht(2) = mfText(mf('Left Top corner'),mf((/0d0,1d0/)), &
                mf((/1,1,0/)),mf(5))
      call msGSet(ht(2),'just','left')
      ht(3) = mfText(mf('Right Top corner'),mf((/1d0,1d0/)), &
                mf((/0,1,0/)),mf(5))
      call msGSet(ht(3),'just','right')
      ht(4) = mfText(mf('Right Bottom corner'),mf((/1d0,0.02d0/)), &
                mf((/0,1,1/)),mf(5))
      call msGSet(ht(4),'just','right')
      ht(5) = mfText(mf('Center'),mf((/0.5d0,0.5d0/)), &
                mf((/1,1,1/)),mf(4))
      call msGSet(ht(5),'just','center')
      ! Pause program execution.
      call msViewpause
      ! Deallocate mfArray
      call msFreeArgs(x, y)
      do i=1,5
         call msFreeArgs(ht(i))
      end do
      end program example


      Result




      See Also
      mfCaption
                                                           Chapter 9 Visualization Routines      323



mfText, msText
2-D text annotation on the location specified in the subplot window.


Module
fgl


Syntax
handle = mfText(text[, loc][, color][, font_size])



Descriptions
Procedure mfText places two-dimensional text on the current subplot.
call msText(text, loc, color, font_size)
• Argument text can be a string or an mfArray containing a string.
•   Argument loc is a 1-by-2 vector in the format [m, n]. Each element contains a value
    ranging from 0 to 1. Specifying m as 0 would place the text annotation at the left-most
    position of the subplot window, and specifying n as 0 would place the text annotation at
    the bottom of the subplot window. For example, the vector [0, 0] would place the text
    annotation on the bottom-left corner of the subplot, and vector [0.5, 0.5] would place the
    text annotation in the center of the plot space.

•   You can set the color and the font size through arguments color and font_size.
    Argument color contains the rgb color code which is specified as [r, g, b] where 0 < r, g,
    b < 1.

h = mfText(...)
• Handle h retrieves a handle to the text annotation created by mfText(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the text annotation through handle h with procedure msGSet.

The properties available are:

1. text 2. location 3. color 4. font_size 5. just

Example
To be referred to mfTitle

See Also
mfAnnotation
324       MATFOR 4 in Fortran Reference Guide



      mfAnnotation, msAnnotation
      3-D text annotation on the location specified in the axes.


      Module
      fgl


      Syntax
      handle = mfAnnotation(text[, loc][, color][, font_size])



      Descriptions
      Procedure mfAnnotation places a three-dimensional text annotation in the axes.

      call msAnnotation(text, loc, color, font_size)
      • Argument text can be a string or an mfArray containing a string.
      •   Argument loc is a 1-by-3 vector in the format [m, n, p] where m, n, p are the actual
         coordinate of the text annotation on the axes.
      h = mfAnnotation(...)
      • Handle h retrieves a handle to the text annotation created by mfAnnotation(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
          current graphics object.

      You can specify properties of the text annotation through handle h with procedure msGSet.

      The properties available are:

      1. text 2. location 3. color 4. font_size 5. offset (2x1 array)



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: m, x, y, z, cm, zz
      type(mfArray) :: maxid,maxz, minid, minz, LocMax, LocMin, ha
      m = mfLinspace(-3, 3, 30)
      call msMeshGrid(mfOut(x, y), m)
      z = mfSin(x) * mfCos(y) / ( x*(x-0.5d0) + (y+0.5d0)*y + 1)
      ! Find Max Z-value and it's Coordinate
      zz = mfReshape(z,900,1)
      call msMax(mfOut(maxz,maxid),zz,MF_NULL,1)
      LocMax = mfS(x,maxid).vc.mfS(y,maxid).vc.maxz
                                           Chapter 9 Visualization Routines   325

!Find Min Z-value and it's Coordinate
call msMin(mfOut(minz,minid),zz,MF_NULL,1)
LocMin = mfS(x,minid).vc.mfS(y,minid).vc.minz
call msSurf(x, y, z)
call msAxis(-3.0d0, 3.0d0, -3.0d0, 3.0d0, -0.4d0, 0.6d0)
!Draw Maximum text annotation
call msAnnotation(mf('Maximum'), LocMax,mf((/0,0,1/)),mf(7))
!Draw Minimum text annotation
ha = mfAnnotation(mf('Minimum'), LocMin,mf((/1,0,0/)),mf(5))
!Change offset of Minimum text annotation
call msGSet(ha,'offset',mf(-15d0).vc.mf(-10d0))
call msViewPause()
call msFreeArgs(m, x, y, z, zz)
call msFreeArgs(maxid,maxz, minid, minz, LocMax, LocMin, ha)
end program example


Result




See Also
mfText
326       MATFOR 4 in Fortran Reference Guide



      msShading
      Shading methodology of surface object.


      Module
      fgl


      Syntax
      call msShading(mode)
      call msShading(handle, mode)



      Descriptions
      Procedure msShading sets the shading mode for all drawings in the plot space.

      call msShading(mode)
      • Specify shading type for procedures mfSurf and mfMesh. The options available are
         listed in the table below.

          Value         Meaning

         “mesh”         Set the surface object to a surface composed of quadrilateral
                        outlines. The color of point is adjusted to reflect the z-height of
                        the corresponding point.

         “flat”         Set the surface object to a surface composed of colored
                        quadrilaterals with uniform color.

        “facet”         Same as “flat” but with mesh outlines.

        “interp”        Apply interpolated shading to the surface plot, thus producing a
                        surface that presents a smooth color variation across the surface.




      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: a, x, y, z, h
                                           Chapter 9 Visualization Routines   327


a = mfLinspace(-3, 3, 30)
call msMeshGrid( mfOut(x, y), a)
z = mfSin(x) * mfCos(y) / ( x*(x-0.5d0) + (y+0.5d0)*y + 1)
call   msSubplot(2, 2, 1)
call   msSurf(x, y, z)
call   msShading('facet')
call   msTitle('facet')
call   msCamZoom(1.2d0)
call   msSubplot(2, 2, 2)
call   msSurf(x, y, z)
call   msShading('flat')
call   msTitle('flat')
call   msCamZoom(1.2d0)
call   msSubplot(2, 2, 3)
call   msSurf(x, y, z)
call   msShading('interp')
call   msTitle('interp')
call   msCamZoom(1.2d0)
call msSubplot(2, 2, 4)
h = mfSurf(x, y, z)
call msTitle('mesh')
call msCamZoom(1.2d0)
!pass handle to msShading subroutine
call msShading(h,mf('mesh'))
call msViewPause()
call msFreeArgs(a, x, y, z, h)
end program example


Result




See Also
msDrawMaterial
328       MATFOR 4 in Fortran Reference Guide



      msColorbar
      Display color scale.


      Module
      fgl


      Syntax
      call msColorbar(mode)
      call msColorbar(property, value)



      Descriptions
      Procedure msColorbar controls the colorbar through specification of argument mode.

      A colorbar displays the current color map and acts as a color scale showing the relationship
      between graphics data and color. In the case of a surface object, it shows the relationship
      between color and height of the surface object. You can also select the colorbar setting from
      the menu and toolbar functions of the Graphics Viewer.

      call msColorbar(mode)
      call msColorbar(property, value)

      Argument mode can be:

          mode        Meaning

          “on”        Display a colorbar on the Graphics Viewer.

         “off”        Hide the colorbar.

        “vert”        Display a vertical colorbar.

        “horz”        Display a horizontal colorbar.



      Argument property can be:

             Property           Meaning

        “label_count”         Number of labels displayed on the colorbar.

        “label_color”         Color of the colorbar labels. Corresponding argument value is
                              a 1-by-3 mfArray contains the rgb codes.
                                              Chapter 9 Visualization Routines   329


     “title”         Title of the colorbar.


Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: m, x, y, z, h, bakcolor,color1,color2
m = mfLinspace(-3, 3, 30)
call msMeshGrid(mfOut(x, y), m)
z = mfSin(x) * mfCos(y) / ( x*(x-0.5d0) + (y+0.5d0)*y + 1)
call msSurf(x, y, z)
call msAxis(-3.0d0, 3.0d0, -3.0d0, 3.0d0, -0.4d0, 0.6d0)
!Show Colorbar
call msColorbar('on')
call msColorbar(mf('label_count'),mf(12))
call msColorbar(mf('label_color'),mf((/1,0,0/)))
call msColorbar(mf('title'),mf('Field 1'))
!Save background color
bakcolor = mfBackgroundColor()
!Get two color variable
color1 = mfS(bakcolor,2.to.4)
color2 = mfS(bakcolor,5.to.7)
!Change background color's blue channel to decrease 0.3d0
call msAssign(mfS(color1,3),mfS(color1,3)-0.3d0)
!Change background color
call msBackgroundColor(color1,color2);
call msViewPause()
call msFreeArgs(m, x, y, z, bakcolor,color1,color2)
end program example

Result




See Also
330       MATFOR 4 in Fortran Reference Guide



      msColormap
      Colormap type.


      Module
      fgl


      Syntax
      call   msColormap(type)
      call   msColormap(colormap)
      call   msColormap(colormap_file)
      call   msColormap(property, value)



      Descriptions
      Procedure msColormap specifies the colormap type used for drawing surface objects.

      call msColormap(type)
      • Argument type specifies the type of colormap used. The argument can be an mfArray
         containing a string specifying the type of colormap or a character string. MATFOR
         provides the following types of colormapping:


          Value         Meaning

          “jet”         Range from blue to red, and pass through the colors cyan,
                        yellow, and orange.(default)

         “gray”         Return a linear grayscale colormap.

          “hot”         Vary smoothly from black, through shades of red, orange, and

                        yellow, to white.

         “cool”         Vary smoothly from cyan to magenta.

        “copper”        Vary smoothly from black to bright copper.

          “hsv”         Vary the hue component of the hue-saturation-value color
                        model.

        “spring”        Consist of colors that are shades of magenta and yellow.

        “summer”        Consist of colors that are shades of green and yellow.
                                                           Chapter 9 Visualization Routines       331


  “autumn”        Vary smoothly from red, through orange, to yellow.

  “winter”        Consist of colors that are shades of blue and green.



call msColormap(colormap)
• Allows users to customize the colormap through the argument colormap which is an
   m-by-3 matrix consisting of m sets of rgb color code. The rgb color code is specified as [r,
   g, b], where 0 < r, g, b < 1.

call msColormap(colormap_file)
• Allows users to load pre-saved colormap files. The pre-saved colormap file can be created,
   added, imported and exported using the colormap setting dialog box. For example, create
   a colormap "mycolor", add to the warehouse or export as mycolor.mfcm. Then, call
   msColormap('mycolor.mfcm')

call msColormap(property, value)
• Allows users to specify properties of the colormap. MATFOR provides the following
   properties of colormapping:


  Property                                   Values

   ‘kind’         ‘linear’, ‘step1’, ‘step2’.

  ‘undef’         ‘Clamp’, ‘no_drawing’, color (1 by 3 mfArray ) .

  ‘range’         min_max (1 by 2 mfArray).




Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: x, u, v, z, h
type(mfArray) :: mcolor,mv
x = mfLinspace(-3, 3, 25)
call msMeshgrid(mfout(u, v), x)
z = 3*((1-u)**2)*mfExp(-(u**2)-((v+1)**2))          &
   - (10*(u/5-(u**3)-(v**5))*mfExp(-(u**2)-(v**2))) &
   - mfExp(-(u+1)**2-v**2)/3
332      MATFOR 4 in Fortran Reference Guide

      call msSubPlot(2, 2, 1)
      call mstitle('Spring')
      h = mfSurf(u, v, z)
      call msColorMap('spring')
      call msColormapRange(-5d0,5d0);
      call msCamZoom(1.2d0)
      call msSubPlot(2, 2, 2)
      call mstitle('Summer')
      h = mfSurf(u, v, z)
      call msColorMap('summer')
      ! Specify the range between -4 and 5
      call msDrawColormap(h, mf('range'), mf((/-4d0, 5d0/)))
      ! Color undefined area to white
      call msDrawColormap(h, mf('undef'), mf((/1,1,1/)))
      call msCamZoom(1.2d0)
      call msSubPlot(2, 2, 3)
      call mstitle('Colormap File')
      h = mfSurf(u, v, z)
      call msColorMap('mycolor.mfcm')
      call msCamZoom(1.2d0)
      call msSubPlot(2, 2, 4)
      call mstitle('Customize')
      h = mfSurf(u, v, z)
      mv = .T.mfLinSpace(1, 0, 64)
      mcolor = mv.hc.mv.hc.mv
      call msColorMap(mcolor)
      call msCamZoom(1.2d0)
      call msViewPause()
      call msFreeArgs(x, u, v, z)
      end program example


      Result




      See Also
      msDrawColormap, msColormapRange
                                                          Chapter 9 Visualization Routines       333



mfColormapRange, msColormapRange
Range of color map.


Module
fgl


Syntax
range = mfColormapRange()
call msColormapRange(min, max)
call msColormapRange([min, max])
call msColormapRange("auto")



Descriptions
Procedure mfColormapRange sets the range of color map.

call msColormapRange(min, max), call msColormapRange([min, max])
• Arguments min and max specify the minimum and maximum of the range.
•   The range can also be input as a vector containing the min and max of the range.

range = mfColormapRange()
• It can also be used as an inquiry procedure to retrieve the color map range in the format of
    [min, max]if no argument is specified.



Example
To be referred to msColormap.

See Also
msColormap, msDrawColormap
334       MATFOR 4 in Fortran Reference Guide



      msDrawColormap
      Change colormap properties.


      Module
      fgl


      Syntax
      call   msDrawColormap(h,       colormap)
      call   msDrawColormap(h,       type)
      call   msDrawColormap(h,       colormap_file)
      call   msDrawColormap(h,       property, value)



      Descriptions
      Procedure msDrawColormap changes the properties of colormap given the object handler
      h.

      Please refer to msColormapfor argument specification.



      Example
      To be referred to msColormap

      See Also
      msColormap, msColormapRange
                                                            Chapter 9 Visualization Routines   335



msLegendBox
Display legend box in the plot window


Module
fgl


Syntax
call msLegendBox(mode)
call msLegendBox(property, value[, property2, value2,...])



Descriptions
Procedure msLegendBox displays legend box in current plot window.

call msLegendBox(mode)
• Argument mode is a string containing 'on' or 'off'. Legend off removes the legend box
   from the plot window.

call msLegendBox(property, value[, property2, value2,...])
• Arguments property and value can be:

         Property           Meaning

         “title”           An mfArray containing a string specifies the title of the
                           legend box.

         “width”           An mfArray containing a real number specifies the
                           width of the legend box.

      “height”             An mfArray containing a real number specifies the
                           height of the legend box.

         “pos_x”           An mfArray containing a real number ranges from 0 to
                           1. Specifying value as 0 would place the legend box at
                           the right-most position of the plot window.

         “pos_y”           An mfArray containing a real number ranges from 0 to
                           1. Specifying value as 0 would place the legend box at
                           the top of the plot window.
336      MATFOR 4 in Fortran Reference Guide


      Example
      Code
      program example
         use fml
         use fgl
         implicit none
         type(mfArray) :: x, y1, y2
         type(mfArray) :: h1,h2,h3
          x = mfColon(0, 0.25, 50)
          y1 = x*mfSin(x)
          y2 = mfSin(x)
          ! Plot the graphs
          h1 = mfPlot(x, y1, 'b-')
          call   msHold('on');
          h2 =   mfPlot(x, y2, 'r-')
          h3 =   mfPlot(x,y2-y1,'g-')
          call   msHold('off')
          call   msTitle('Three Plot')
          call   msLegendBox('on')
          call   msLegendBox('title','My Legend')
          call   msLegendBox(mf('pos_x'),mf(0.6))
          call   msLegendBox(mf('pos_y'),mf(0.6))
          call   msLegendBox(mf('width'),mf(0.2))
          call   msLegendBox(mf('height'),mf(0.2))
          call msAddLegend(h1,mf('Plot 1 blue'))
          call msAddLegend(h2,mf('Plot 2 red'))
          call msAddLegend(h3,mf('Plot 3 green'))
          ! Pause the program for drawing
          call msViewPause()
          call msRemoveLegend(h2)
          call msViewPause()
      end program example


      Result




      See Also
      mfAddLegend, mfRemoveLegend
                                                        Chapter 9 Visualization Routines   337



msAddLegend
Add legend to the legend box.


Module
fgl


Syntax
call msAddLegend(h, label [, h2, label2, ...] )



Descriptions
Procedure mfAddLegend associates given handle with the label.



Example
To be referred to msLegendBox

See Also
msRemoveLegend, msLegendBox
338       MATFOR 4 in Fortran Reference Guide



      msRemoveLegend, msRemoveAllLegend
      Remove legends from the legend box.


      Module
      fgl


      Syntax
      call msRemoveLegend(h [,h2, ...] )
      call msRemoveAllLegend()



      Descriptions
      Procedures mfRemoveLegend and mfRemoveAllLegend remove the specified or all legends
      from the legend box in the plot window.



      Example
      To be referred to msLegendBox

      See Also
      msAddLegend, msLegendBox
                                                            Chapter 9 Visualization Routines      339



mfBackgroundColor, msBackgroundColor
Background color of plot space.


Module
fgl


Syntax
call msBackgroundColor(r, g, b)
call msBackgroundColor(color)
call msBackgroundColor(color1, color2)
colorCode = mfBackgroundColor()



Descriptions
Procedure mfBackgroundColor sets the background color of the plot space.

call msBackgroundColor(r, g, b)
• Arguments r, g, b contain a real number within the range 0 to 1 specifying the rgb code
    of the background color. For example, call msBackgroundColor(1, 1, 1) sets
    the background color to white.

call msBackgroundColor(color)
• Argument color is a 1-by-3 mfArray containing the rgb color codes where 0 < r, g, b <
    1. For example, call msBackgroundColor(mfV(1, 0, 1)).

call msBackgroundColor(color1, color2)
• This procedure creates an easy gradient for the background using two colors. Argument
    color1 and color2 are 1-by-3 mfArrays containing the rgb color where 0 < r, g, b < 1.
    For example, call msBackgroundColor(mfV(0.5, 0.5, 0.5),
    mfV(1,0,1)).

colorCode = mfBackgroundColor()
• This procedure retrieves the color code of the current plot space in the format of [r, g, b],
    where 0 < r, g, b < 1.



Example
To be referred to msColorbar

See Also
340     MATFOR 4 in Fortran Reference Guide




      Axis Control
                                                          Chapter 9 Visualization Routines     341



mfAxis, msAxis
Manipulate the axis object.


Module
fgl


Syntax
xyzrange = mfAxis()

call   msAxis(xyzrange)
call   msAxis(x_min, x_max, y_min, y_max[, z_min, z_max])
call   msAxis(mode)
call   msAxis(property, value)



Descriptions
Procedure mfAxis sets the properties of the x-axis, y-axis and z-axis, such as the range,
mode and color. It can also be used as an inquiry function for the range of the axes.

xyzrange = mfAxis()
• Retrieves the range of the axis objects. The output argument xyzrange is a vector in the
    format [x_min, x_max, y_min, y_max, z_min, z_max].

call msAxis(xyzrange)
call msAxis(x_min, x_max, y_min, y_max)
call msAxis(x_min, x_max, y_min, y_max, z_min, z_max)
• Sets the ranges of the axis objects. The input data can be provided in two ways: through a
    vector xyzrange in which the ranges of the axes objects are specified or in the
    element-by-element way.
•   Argument xyzrange is a vector in the format [x_min, x_max, y_min, y_max, z_min,
    z_max].
•   Arguments x_min,x_max,y_min,y_max,z_min,z_max specify the displaying
    ranges of the x-axis, y-axis and z-axis.

call msAxis(mode)
call msAxis(property, value)
• Sets the mode and property of the axis objects.
Argument mode can be:

       mode         Meaning

       “on”        Display the tick marks, labeling and background of the current
                   axis object.
342      MATFOR 4 in Fortran Reference Guide


          “off”         Remove the tick marks, labeling and background of the current
                        axis object.

        “Normal”        Restore the current axis object to its full size and remove any
                        restrictions on scaling.

         “equal”        Use the same aspect ratio for each axis of the axis object. In
                        other words, tick marks of equal increments have the same size
                        on all axes.

         “Auto”         Set axes scaling to automatic mode. MATFOR sets the limits,
                        minimum and maximum of each axis based on the extents of the
                        graphs plotted. It is the default setting.


      Argument property can be:

             property             Meaning

         “axis_color”           Color of all three axes. The corresponding argument
                                value is an mfArray containing a string that specifies
                                the color, e.g. “y”, or a 1-by-3 mfArray contains the
                                rgb codes.

        "xaxis_color"           Color of the x-axis. The corresponding argument
                                value is an mfArray containing a string that specifies
                                the color, e.g. “y”, or a 1-by-3 mfArray contains the
                                rgb codes.

        "yaxis_color"           Color of the y-axis. The corresponding argument
                                value is an mfArray containing a string that specifies
                                the color, e.g. “y”, or a 1-by-3 mfArray contains the
                                rgb codes.

        “zaxis_color”           Color of the z-axis. The corresponding argument
                                value is an mfArray containing a string that specifies
                                the color, e.g. “y”, or a 1-by-3 mfArray contains the
                                rgb codes.

        “xtick_custom”          Customized tick label for x-axis. The corresponding
                                arguments are a vector containing locations of the tick
                                                       Chapter 9 Visualization Routines   343


                  marks and a string containing labels of the tick marks.

“ytick_custom”    Customized tick label for y-axis. The corresponding
                  arguments are a vector containing locations of the tick
                  marks and a string containing labels of the tick marks.

“ztick_custom”    Customized tick label for z-axis. The corresponding
                  arguments are a vector containing locations of the tick
                  marks and a string containing labels of the tick marks.

“xtick_format”    Tick format of x-axis. The corresponding argument
                  value is a printf style format string*.

“ytick_format”    Tick format of y-axis. The corresponding argument
                  value is a printf style format string*.

“zxtick_format”   Tick format of z-axis. The corresponding argument
                  value is a printf style format string*.

 “xtick_space”    Interval between tick marks of the x-axis.

 “ytick_space”    Interval between tick marks of the y-axis.

 “ztick_space”    Interval between tick marks of the z-axis.

“xtick_anchor”    Where one tick marks is placed and, other tick marks
                  are placed relative to this point.

“ytick_anchor”    Where one tick marks is placed and, other tick marks
                  are placed relative to this point.

“ztick_anchor”    Where one tick marks is placed and, other tick marks
                  are placed relative to this point.

  “clipping”      Sets the cropping mode “on” or “off”. Graphs are
                  cropped if it exceeds the min value and/or max value of
                  the particular axis setting.

    “tight”       Sets the axes boundary to fit in axes range and sets yzx
                  ratio to 1.

 “geoid_label”    Display geoid labels on current axis object. The
344       MATFOR 4 in Fortran Reference Guide


                                 corresponding argument is “on” or “off”.


      * printf Format String:
      Code      Format
      %c character
      %d signed integers
      %i signed integers
      %e scientific notation, with a lowercase "e"
      %E scientific notation, with a uppercase "E"
      %f floating point
      %g use %e or %f, whichever is shorter
      %G use %E or %f, whichever is shorter



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: a, b, c, x, y, z, indxi, indxj
      type (mfArray) :: range
      a = mfLinspace(-7, 7, 51)
      b = mfLinspace(-2, 3, 51)
      c = mfColon(1, 51)
      call msMeshgrid(mfout(x, y), a, b)
      call msMeshgrid(mfout(indxi, indxj), c)
      z = 1*mfSin((indxi+1)/10)*mfCos((indxj+1)/10) &
         + 2*mfSin((indxi+indxj)/10)
      call msSubplot(1,2,1)
      call msSurf(x, y, z)
      !Switch display mode to 2D mode
      call msAxis2DMode()
      call msAxis2DRange(-7, 5, -2, 3)
      !Set Axis clipping on
      call msAxis('clipping', 'on')
      !Set axis dependency of 2D display mode
      call msAxis2DDependency('xy_tight',3.5d0)
      call msAxis('xtick_format','%-3.1e')
      call msAxis('ytick_format','%4.3g')
      range = mfAxis2DRange()
      call msDisplay(range,'2D Axis range')
      call msSubplot(1,2,2)
      call msSurf(x, y, z)
      !Set Axis range
      call msAxis(-7, 5, -2, 3, -5, 5)
      !Set Axis clipping off
      call msAxis('clipping', 'off')
      !Switch display mode to 3D mode
      call msAxis3DMode()
                                           Chapter 9 Visualization Routines   345

!Set axis dependency of 3D display mode
call msAxis3DDependency('xyz_depend',1d0,0.5d0)
call msAxis('xtick_format','%-3.1e')
call msAxis('ytick_format','%4.3g')
call msAxis("ztick_custom",mfLinspace(-5,5,5), &
   "B0|B1|Z0|T0|T1")
range = mfAxis3DRange()
call msDisplay(range,'3D Axis range')
call msViewPause()
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


Result




See Also
346       MATFOR 4 in Fortran Reference Guide



      msAxis2DMode
      Switch display mode to 2D mode.


      Module
      fgl


      Syntax
      call msAxis2DMode()



      Descriptions
      Procedure msAxis2DMode switches display mode to 2D mode. This procedure will only
      take effect when calling after the last graphic function.



      Example
      To be referred to mfAxis

      See Also
      msAxis3DMode, msAxis2DDependency, msAxis3DDependency
                                                  Chapter 9 Visualization Routines   347



msAxis3DMode
Switch display mode to 3D mode.


Module
fgl


Syntax
call msAxis3DMode()



Descriptions
Procedure msAxis3DMode switches display mode to 3D mode. This procedure will only
take effect when calling after the last graphic function.



Example
To be referred to mfAxis

See Also
msAxis2DMode, msAxis2DDependency, msAxis3DDependency
348       MATFOR 4 in Fortran Reference Guide



      msAxis2DDependency
      Set axis dependency of 2D display mode.


      Module
      fgl


      Syntax
      call msAxis2DDependency(mode)
      call msAxis2DDependency(mode, y2xratio)



      Descriptions
      Procedure msAxis2DDependency sets axis dependency of 2D display mode.

      call mfAxis2DDependency(mode, y2xratio)
      • Argument mode can take the following values.

          Value                 Meaning

               “indep”              In this mode, the units of x-axis and y-axis
                                    are independent. The graph will be
                                    normalized to fit the whole area of the
                                    display window.

            “xy_depend”             In this mode, the units of x-axis and y-axis
                                    are dependent to each other. If the ratio
                                    y2xratio is equal to 1, the graph has the
                                    same unit length.
                                    y2xratio determines the display ratio
                                    between y-axis unit and x-axis unit. For
                                    example, if y2xratio = 2, the display
                                    length of vector (0,1) is 2-times long of
                                    the vector (1,0) in the display window.

            “xy_tight”              See xy_depend.
                                    Sets the axis limits to the range of the
                                    axis.


      •   Argument y2xratio determines the display ratio of units in y-axis and x-axis in
          "xy_depend" mode. It has no effect in "indep" mode. The default vaule is 1.0.
                                   Chapter 9 Visualization Routines   349


Example
To be referred to mfAxis

See Also
msAxis3DMode, msAxis2DDependency
350       MATFOR 4 in Fortran Reference Guide



      msAxis3DDependency
      Set axis dependency of 3D display mode.


      Module
      fgl


      Syntax
      call msAxis3DDependency(mode)
      call msAxis3DDependency(mode, y2xratio, z2xratio)



      Descriptions
      Procedure msAxis3DDependency sets axis dependency of 3D display mode.

      call mfAxis3DDependency(mode, y2xratio, z2xratio)
      • Argument mode can take the following values.

        Value               Meaning

            “indep”              In this mode, the units of x-axis, y-axis and
                                 z-axis are independent. The display size of the
                                 graph in x-, y- and z-dimension will be
                                 normalized by the ratio y2xratio and z2xratio.
                                 For example, if y2xratio=2, z2xratio=3, the
                                 bounding box of the graph will be the size of
                                 1x2x3 in the display window.
                                                       Chapter 9 Visualization Routines   351


    “xyz_depend”           In this mode, the units of x-axis, y-axis and
                           z-axis are dependent to each other. if the ratio
                           y2xratio and z2xratio are both equal to 1, the
                           graph   has    the   same     unit     length      in    all
                           three-axes.

                           y2xratio determines the display ratio between
                           y-axis unit and x-axis unit. For example, if
                           y2xratio = 2, the display length of vector (0,1)
                           is 2-times long of the vector (1,0) in the
                           display window.
                           z2xratio determines the display ratio between
                           z-axis unit and x-axis unit. For example, if
                           z2xratio = 2, the display length of vector
                           (0,0,1) is 2-times long of the vector (1,0,0)
                           in the display window.

     “xy_depend”           In this mode, the units of x-axis, y-axis are
                           dependent to each other but and the unit of
                           z-axis is independent to x-axis and y-axis. It
                           is a mixed mode. The unit behavior between
                           x-axis and y-axis are like “xyz_depend” mode
                           and The unit behavior between z-axis and x-axis
                           are like “indep” mode.


•    Argument y2xratio determines the display size ratio between y-dimension and
     x-dimension in "indep" mode. Argument y2xratio also determines the display ratio
     of units in y-axis and x-axis in "xyz_depend" and "xy_depend" modes. The default
     vaule is 1.0.
•    Argument z2xratio determines the display size ratio between z-dimension and
     x-dimension in "indep" and "xyz_depend" modes. The default vaule is 1.0.



Example
To be referred to mfAxis

See Also
msAxis2DMode, msAxis3DMode, msAxis2DDependency
352       MATFOR 4 in Fortran Reference Guide



      mfAxis2DRange
      Set the axis range of 2D display mode.


      Module
      fgl


      Syntax
      xyrange = mfAxis2DRange()
      call msAxis2DRange(xyrange)
      call msAxis2DRange(x_min, x_max, y_min, y_max)



      Descriptions
      Procedure mfAxis2DRange set the axis range of 2D display mode.

      xyrange = mfAxis2DRange()
      • Retrieves the ranges of the axis objects. The output argument xyrange is a vector in the
          format [x_min, x_max, y_min, y_max].

      call mfAxis2DRange(xyrange)
      call mfAxis2DRange(x_min, x_max, y_min, y_max)
      • Set the ranges of the axis objects. The input data can be provided in two ways: through a
          vector xyzrange in which the ranges of the axes objects are specified, or in the
          element-by-element way.
      •   Argument xyrange is a vector in the format [x_min, x_max, y_min, y_max].
      •   Arguments x_min,x_max,y_min,y_max specify the displaying ranges of the x-axis
          and y-axis.
      •   You can specify x_min,x_max,y_min,y_max by MF_AUTO_RANGE as a special
          parameter to let visualization to automatically determine the data range bound for you.



      Example
      To be referred to mfAxis

      See Also
      msAxis, msAxis3DRange
                                                          Chapter 9 Visualization Routines    353



mfAxis3DRange
Set the axis range of 3D display mode.


Module
fgl


Syntax
xyzrange = mfAxis3DRange()
call msAxis3DRange(xyzrange)
call msAxis3DRange(x_min, x_max, y_min, y_max, z_min, z_max)



Descriptions
Procedure mfAxis3DRange set the axis range of 3D display mode.

xyzrange = mfAxis3DRange()
• Retrieves the ranges of the axis objects. The output argument xyzrange is a vector in
    the format [x_min, x_max, y_min, y_max, z_min, z_max].

call mfAxis3DRange(xyzrange)
call mfAxis3DRange(x_min, x_max, y_min, y_max, z_min, z_max)
• Set the ranges of the axis objects. The input data can be provided in two ways: through a
    vector xyzrange in which the ranges of the axes objects are specified, or in the
    element-by-element way.
•   Argument xyrange is a vector in the format [x_min, x_max, y_min, y_max, z_min,
    z_max].
•   Arguments x_min,x_max,y_min,y_max,z_min,z_max specify the displaying
    ranges of x-axis, y-axis, z-axis.
•   You can specify x_min,x_max,y_min,y_max,z_min,z_max by
    MF_AUTO_RANGE as a special parameter to let vizulization to automatically determine
    the data range bound for you.



Example
To be referred to mfAxis

See Also
msAxis, msAxis2DRange
354       MATFOR 4 in Fortran Reference Guide



      msAxis2DPosition
      Set axis position in the plot window


      Module
      fgl


      Syntax
      call msAxis2DPosition(pos_x1, pos_x2, pos_y1, pos_y2)



      Descriptions
      Procedure msAxis2DPosition sets the axis box position on current plot window.

      call msAxis2DPosition(pos_x1, pos_x2, pos_y1, pos_y2)
      • Argument pos_x1, pos_x2, pos_y1, pos_y2 are four real numbers ranging from
          0 to 1. They represent the coordinates of the axis box on current plot window. For
          example, specifying x1=0, y1=0 would place the axis box at the very left bottom corner
          of the plot window.

      •   Argument pos_x1 indicates the distance along x-coordinate from the left bottom corner
          of the plot window to the left bottom corner of the axis box.
      •   Argument pos_x2 indicates the distance along x-coordinate from the left bottom corner
          of the plot window to the right bottom corner of the axis box.
      •   Argument pos_y1 indicates the distance along y-coordinate from the left bottom corner
          of the plot window to the left bottom corner of the axis box.
      •   Argument pos_y2 indicates the distance along y-coordinate from the left bottom corner
          of the plot window to the left top corner of the axis box.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      !call msSubplot(1,2,1)
      !Draw red circle
      call msCircle(mf((/0, 0, 0/)), mf(0.5), mf((/1, 0, 0/)))
      call msAxis("equal")
      !Draw first 2D Plot at right-bottom corner
      call msAxis2DPosition( mf((/0.1, 0.7, 0.1, 0.7/)) )
      !call msSubplot(1,2,2)
      !Draw green circle
                                             Chapter 9 Visualization Routines   355

!call   msCircle(mf((/0, 0, 0/)), mf(0.5), mf((/0, 1, 0/)))
!call   msAxis("equal")
!Draw   second 2D Plot at top side
!call   msAxis2DPosition( mf((/0.2, 1.0, 0.5, 1.0/)) )
! Pause the program for display
call msViewPause()
end program example


Result




See Also
mfAxis
356       MATFOR 4 in Fortran Reference Guide



      msAxisWall
      Manipulate the axis wall object.


      Module
      fgl


      Syntax
      call msAxisWall(mode)
      call msAxisWall(property, value)



      Descriptions
      Procedure msAxisWall sets the color of the three axis-wall objects and switches them on or
      off. The axis-wall object represents the three axis planes.

      call msAxisWall(mode)
      • Switches the three axis-planes on or off. Argument mode is either "on" or "off".

      call msAxisWall(property, value)
      • Sets the color of the axis-wall object. Argument property can be a string specified as
          "color" and argument value contains the rgb color code which is specified as [r, g, b]
          where 0 < r, g, b < 1.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: u, v, x, z
      x = mfLinspace(-3, 3, 25)
      call msMeshgrid(mfout(u, v), x)
      z = 3*((1-u)**2)*mfExp(-(u**2)-((v+1)**2))          &
         - (10*(u/5-(u**3)-(v**5))*mfExp(-(u**2)-(v**2))) &
         - mfExp(-(u+1)**2-v**2)/3
      call msSurf(u, v, z)
      call msAxisWall('color', mf((/1, 1, 0/)))
      call msViewPause()
      call msFreeArgs(u, v, x, z)
      end program example


      Result
           Chapter 9 Visualization Routines   357




See Also
358       MATFOR 4 in Fortran Reference Guide



      msAxisGrid
      Display grid lines.


      Module
      fgl


      Syntax
      call msAxisGrid(axis, mode)
      call msAxisGrid(property, value)



      Descriptions
      Procedure msAxisGrid sets the properties of the axis grid objects, such as the width, color
      and pattern.

      call msAxisGrid(axis, mode)
      • Switch an axis on or off. Argument axis can be "xaxis", "yaxis" or "zaxis" which
          corresponds to the three axes respectively. Argument mode is either "on or "off".

      call msAxisGrid(property, value)
      • Sets a property of the axis grid objects.
      Argument property can be:

          property           Meaning

         “width”            Line width. Corresponding argument value is a scalar integer
                            value.

         “color”            Line color. Corresponding argument value can be an mfArray
                            containing a string specifies the color, e.g. “y”, or a 1-by-3
                            mfArray contains the rgb codes.

        “pattern”           Line pattern. Corresponding argument value can be an
                            mfArray containing the string that is specified as “solid",
                            "dashed", "dotted" or "dashdot".


      Example

      Code
      program example
      use fml
      use fgl
      implicit none
                                              Chapter 9 Visualization Routines   359


type(mfArray) :: u, v, x, z
x = mfLinspace(-3, 3, 25)
call msMeshgrid(mfout(u, v), x)
z = 3*((1-u)**2)*mfExp(-(u**2)-((v+1)**2))          &
   - (10*(u/5-(u**3)-(v**5))*mfExp(-(u**2)-(v**2))) &
   - mfExp(-(u+1)**2-v**2)/3
call   msSurf(u, v, z)
call   msAxisGrid('width', mf(2))
call   msAxisGrid('color', mf((/1, 0, 0/)))
call   msAxisGrid('pattern', 'dashed')
call   msViewPause()
call msFreeArgs(u, v, x, z)
end program example


Result




See Also
360     MATFOR 4 in Fortran Reference Guide




      Object Manipulation
                                                            Chapter 9 Visualization Routines       361



msObjRotateX, msObjRotateY, msObjRotateZ
Rotate the draw object in degrees about the x-axis, y-axis and z-axis using the right hand rule.


Module
fgl


Syntax
call msObjRotateX(handle, angle)
call msObjRotateY(handle, angle)
call msObjRotateZ(handle, angle)



Descriptions
Procedures msObjRotateX, msObjRotateY and msObjRotateZ rotate the draw
object that is associated with argument handle in degrees about the x-, y-, z-axes
respectively using the right hand rule. The axes are the draw object's axes.

If you want to rotate about the world x-, y- and z-axes, use msObjRotateWXYZ(handle,
angle, 1, 0, 0),msObjRotateWXYZ(handle, angle, 0, 1, 0) and
msObjRotateWXYZ(handle, angle, 0, 0, 1).



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h, h2, color2
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/0, 1, 0/)
color2 = (/1, 0, 0/)
call msSubplot(1,2,1)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msSubplot(1,2,2)
h2 = mfCube(center, cubesize, color2)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msViewPause()
call   msSubplot(1,2,1)
call   msObjRotateX(h, 30)
call   msSubplot(1,2,2)
call   msObjRotateWXYZ(h2, 30, 1, 0, 0)
call   msViewPause()
call msSubplot(1,2,1)
362      MATFOR 4 in Fortran Reference Guide

      call   msObjRotateY(h, 30)
      call   msSubplot(1,2,2)
      call   msObjRotateWXYZ(h2, 20, 0, 1, 0)
      call   msViewPause()
      call   msSubplot(1,2,1)
      call   msObjRotateZ(h, 30)
      call   msSubplot(1,2,2)
      call   msObjRotateWXYZ(h2, 20, 0, 0, 1)
      call   msViewPause()
      call msFreeArgs(center, cubesize, h)
      end program example


      Result




      See Also
                                                             Chapter 9 Visualization Routines     363



msObjRotateWXYZ
Rotate the draw object in degrees about an arbitrary axis.


Module
fgl


Syntax
call msObjRotateWXYZ(h, angle, x, y, z)



Descriptions
Procedure msObjRotateWXYZ rotates the draw object about an arbitrary axis specified by
arguments x, y and z.

In other words, (x, y, z) specifies the axis the object will rotate along. To rotate along each
individual axis, please use msObjRotateX, msObjRotateY and msObjRotateZ.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/1, 0, 0/)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msViewPause()
call msObjRotateWXYZ(h, 30, 1, 1, 1)
call msHold('off')
call msViewPause()
call msFreeArgs(center, cubesize, h)
end program example


Result
364      MATFOR 4 in Fortran Reference Guide




      See Also
      msObjRotateX
                                                            Chapter 9 Visualization Routines       365



mfObjScale, msObjScale
Return or modify the draw object scale.


Module
fgl


Syntax
scale = mfObjScale(handle)
call msObjScale(handle, scale)
call msObjScale(handle, x, y, z)



Descriptions
Procedure msObjScale resets the scale independently on the x-, y- and z-axes. A scale of
zero is illegal and will be replaced with one.

scale = mfObjScale(handle)
It can also be used as an inquiry procedure to retrieve the scale of the draw object if only the
handle associated with the draw object is given.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/0, 0, 1/)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msViewPause()
call msObjScale(h, 1.5d0, 1.5d0, 1.5d0)
call msDisplay(mfObjScale(h),'Scale')
call msViewPause()
call msFreeArgs(center, cubesize, color, h)
end program example


Result
366      MATFOR 4 in Fortran Reference Guide




      See Also
                                                              Chapter 9 Visualization Routines        367



mfObjPosition, msObjPosition
Return or modify position of the draw object in world coordinates.


Module
fgl


Syntax
position = mfObjPosition(handle)
call msObjPosition(handle, [x, y, z])



Descriptions
Procedure mfObjPosition sets the position of the draw object that is associated with
argument handle to world coordinates specified in argument [x, y, z].

position = mfObjPosition(handle)
It can also be used as an inquiry procedure to retrieve the position of the draw object if only the
handle associated with the draw object is given.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/1, 1, 0/)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msViewPause()
call msObjPosition(h, 0.1d0, 0.1d0, 0.1d0)
call msDisplay(mfObjPosition(h),'Position')
call msViewPause()
call msFreeArgs(center, cubesize, color, h)
end program example


Result
368      MATFOR 4 in Fortran Reference Guide




      See Also
                                                            Chapter 9 Visualization Routines        369



mfObjOrigin, msObjOrigin
Return or modify origin of the draw object.


Module
fgl


Syntax
origin = mfObjOrigin(handle)
call msObjOrigin(handle, [x, y, z])



Descriptions
Procedure mfObjOrigin sets the origin of the draw object. All rotations performed on the
draw object pivot around the origin. Note that the origin is relative to the position of the
object; whenever the object moves, the origin moves along with it so that they maintain a
constant relationship relative to each other.

origin = mfObjOrigin(handle)
It can also be used as an inquiry procedure to retrieve the origin of the draw object if only the
handle associated with the draw object is given.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/0.75, 0.0, 0.75/)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
! Set origin (0.0d0, 0.15d0, 0.0d0)
call msObjOrigin(h, 0.0d0, 0.15d0, 0.0d0)
call msDisplay(mfObjOrigin(h),'Origin')
call msViewPause()
call   msObjRotateX(h, 30)
call   msViewPause()
call   msObjRotateY(h, 30)
call   msViewPause()
call   msObjRotateZ(h, 10)
call   msViewPause()
call msFreeArgs(center, cubesize, color, h)
370      MATFOR 4 in Fortran Reference Guide

      end program example


      Result




      See Also
                                                               Chapter 9 Visualization Routines          371



mfObjOrientation, msObjOrientation
Return or modify WXYZ orientation of the draw object.


Module
fgl


Syntax
orientation = mfObjOrientation(handle)
call msObjOrientation(handle, [x, y, z])



Descriptions
Procedure mfObjOrientation sets the WXYZ orientation of the draw object as a vector
of x, y and z rotation. The order in which these rotations are performed is Rotate z, Rotate
x and then Rotate y.

orientation = mfObjOrientation(handle)
It can also be used as an inquiry procedure to retrieve the orientation of the draw object if only the
handle associated with the draw object is given.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: center, cubesize, color, h
center = (/0, 0, 0/)
cubesize = (/0.2, 0.3, 0.4/)
color = (/0.0, 0.75, 0.75/)
h = mfCube(center, cubesize, color)
call msAxis('equal')
call msAxis(-0.3d0, 0.3d0, -0.4d0, 0.4d0, -0.5d0, 0.5d0)
call msViewPause()
call msObjOrientation(h, 15, 15, 15)
call msDisplay(mfObjOrientation(h),'Orientation')
call msViewPause()
call msFreeArgs(center, cubesize, color, h)
end program example


Result
372      MATFOR 4 in Fortran Reference Guide




      See Also
                                                         Chapter 9 Visualization Routines   373



mfObjectModel, msObjectModel
Import a 3-D object.


Module
fgl


Syntax
h = mfObjectModel( filename[, loc][, scale][, orientation] )
call msObjectModel( filename[, loc][, scale][, orientation] )



Descriptions
Procedure mfObjectModel loads a 3-D object into an mfArray.

call msObjectModel( filename )
call msObjectModel( filename, loc, scale, orientation )
• Argument filename is a string containing the filename of the object file. MATFOR
    supports file formats with extension .obj, .stl and .3ds.
•   Argument loc is a 1-by-3 vector in the format [m, n, p] where m, n, p are the actual
    coordinate of the object on the axes.
•   Argument scale sets the scale for the draw object.
•   Argument orientation is a 1-by-3 vector that specifies the angle-rotation along x, y
    and z dimensions.

You can retrieve properties of the object through handle h with procedure mfObjPosition,
mfObjScale and mfObjOrientation.



Example

Code
program example
      use fml
      use fgl
      implicit none
      type(mfArray)::x,y,z,h
      call msFigure('Satellite')
       call msSubplot(1,2,1)
       !Read the Satellite object
       h = mfObjectModel( 'Satellite.obj', mf((/0, 0, 0/)), mf(0.002))
       call msDrawMaterial(h, mf('surf'), mf('ambient'), &
              mf(0), mf('diffuse'), mf(100))
       call msDrawMaterial(h, mf('edge'), mf('trans'), mf(90))
      call msAxis('equal')
      call msAxis(-1, 1, -1, 1, -1, 1)
374      MATFOR 4 in Fortran Reference Guide

          call msSubplot(1,2,2)
          !Read the Satellite object
          h = mfObjectModel( 'Satellite.obj', mf((/0, 0, 0/)), mf(0.002))
          call msDrawMaterial(h, mf('surf'), mf('ambient'), &
                 mf(0), mf('diffuse'), mf(100))
          call msDrawMaterial(h, mf('edge'), mf('trans'), mf(90))
         call msAxis('equal')
         call msAxis(-1, 1, -1, 1, -1, 1)
          !Rotate the Satellite object
          call msObjRotateX(h,30)
          call msObjRotateY(h,30)
          call msObjRotateZ(h,10)
          call msViewPause()
      end program example


      Result




      See Also
      mfObjPosition, mfObjScale, and mfOrientation
                      Chapter 9 Visualization Routines   375




Camera Manipulation
376       MATFOR 4 in Fortran Reference Guide



      msView
      Viewpoint specification.


      Module
      fgl


      Syntax
      call msView(az, el)
      call msView(az, el, roll)
      call msView(mode)



      Descriptions
      Procedure msView specifies the orientation of an axis object. The orientation of the axis
      object is determined by the azimuth az and elevation el of the viewing angle from a
      viewpoint. Argument roll determines the upward direction of the camera.

                                        Z




                                                                       roll


                                                                   Camera
                                                      elevation
                                                                               X
                                            azimuth




                        -Y


      Argument mode can be "2", "3", "home", "top", "bottom", "front", "back",
      "left" or "right".



      Example
                                                Chapter 9 Visualization Routines   377



Code
program example
use fml
use fgl
implicit none
type(mfArray) :: x, y, z, a
z = mfLinspace(0, 10*MF_PI, 315)
x = mfExp(-z/20)*mfCos(z)
y = mfExp(-z/20)*mfSin(z)
!Plot a 3-D line graph using mfPlot3() routine and title it.
call msFigure('View')
call msSubplot(1,2,1)
call msPlot3(x, y, z)
call msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call msView('3')
call   msSubplot(1,2,2)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msView('2')
call   msAxis2DDependency('xy_tight',1)
call   msFigure('CamAngle')
call   msSubplot(1, 2, 1)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msCamAngle(50d0)
call   msDisplay(mfCamAngle(),'Modify Angle')
call   msSubplot(1, 2, 2)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msDisplay(mfCamAngle(),'Original Angle')
call   msFigure('AzElRoll')
call   msSubplot(1, 2, 1)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msCamAzElRoll(30d0,20d0,10d0)
call msDisplay(mfCamAzElRoll(),'Modify AzElRoll')
call   msSubplot(1, 2, 2)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msDisplay(mfCamAzElRoll(),'Original AzElRoll')
call   msFigure('Distance')
call   msSubplot(1, 2, 1)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msCamDistance(6d0)
call   msDisplay(mfCamDistance(),'Modify Distance')
call   msSubplot(1, 2, 2)
call   msPlot3(x, y, z)
call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
call   msCamProj('perspective')
call   msDisplay(mfCamDistance(),'Original Distance')
call msFigure('Focal')
378      MATFOR 4 in Fortran Reference Guide

      call   msSubplot(1, 2, 1)
      call   msPlot3(x, y, z)
      call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
      call   msCamProj('perspective')
      call   msCamFocal(mf((/4d0,5d0,6d0/)))
      call   msDisplay(mfCamFocal(),'Modify Focal')
      call   msSubplot(1, 2, 2)
      call   msPlot3(x, y, z)
      call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
      call   msCamProj('perspective')
      call   msDisplay(mfCamFocal(),'Original Focal')
      call   msFigure('Zoom')
      call   msSubplot(1, 2, 1)
      call   msPlot3(x, y, z)
      call   msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
      call   msCamZoom(1.5d0)
      call   msDisplay(mfCamZoom(),'Modify Zoom')
      call msSubplot(1, 2, 2)
      call msPlot3(x, y, z)
      call msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
      call msDisplay(mfCamZoom(),'Original Zoom')
      !Pauses the program to display graph.
      call msViewPause()
      !Deallocate mfArray
      call msFreeArgs(x, y, z)
      end program example


      Result




      See Also
                                                          Chapter 9 Visualization Routines       379



mfCamAngle, msCamAngle
Set the camera view angle.


Module
fgl


Syntax
angle = mfCamAngle()
call msCamAngle(angle)



Descriptions
Procedure mfCamAngle sets the camera view angle, which is the angular height of the
camera view measured in degrees.

The default angle is 10 degrees. This procedure has no effect when used in parallel projection
mode.

angle = mfCamFieldAngle()
• It can also be used an inquiry function to retrieve the view angle of the camera.



Example
To be referred to msView

See Also
msCamProj, msCamDistance, msCamZoom
380       MATFOR 4 in Fortran Reference Guide



      mfCamAzElRoll
      Set the camera view direction.


      Module
      fgl


      Syntax
      vdir   = mfCamAzElRoll()
      call   msCamAzElRoll(az, el)
      call   msCamAzElRoll(az, el, roll)
      call   msCamAzElRoll([az, el])


      Descriptions
      Procedure msCamAzElRoll specifies the view direction of a camera object.

                                        Z




                                                                      roll


                                                                  Camera
                                                      elevation
                                                                              X
                                            azimuth




                        -Y

      The view direction of a camera object is determined by the azimuth az, elevation el, and
      roll roll of the viewing angle from a viewpoint.

      Example
      To be referred to msView


      See Also
      mfView
                                                          Chapter 9 Visualization Routines      381



mfCamDistance
Set the camera distance.


Module
fgl


Syntax
dist = mfCamDistance()
call msCamDistance(dist)



Descriptions
Procedure msCamDistance sets the distance between the camera and the focal point. This
procedure has no effect when used in parallel projection mode.

dist = mfCamFieldAngle()
• It can also be used an inquiry function to retrieve the distance between the camera and the
    focal point.



Example
To be referred to msView

See Also
msCamProj, msCamAngle, msCamZoom, msCamFocal
382       MATFOR 4 in Fortran Reference Guide



      mfCamProj, msCamProj
      Set the camera projection mode.


      Module
      fgl


      Syntax
      mode = mfCamProj()
      call msCamProj(mode)



      Descriptions
      Procedure msCamProj sets the camera projection mode to be either perspective or parallel
      projection. Argument mode can be "orthographic" or "perspective".

      mode = mfCamProj()
      • It can also be used an inquiry function to retrieve the camera projection mode. The output
          argument is a logical mfArray whose value is true if the projection mode is orthographic,
          false otherwise.



      Example
      To be referred to msView

      See Also
      msView, msCamAzElRoll, msCamZoom, msCamAngle, msCamDistance
                                                           Chapter 9 Visualization Routines   383



mfCamFocal
Set the camera focal point.


Module
fgl


Syntax
fp = mfCamFocal()
call msCamFocal(fp)



Descriptions
Procedure msCamFocal sets the camera focal point using a 3x1 vector fp.

fp = mfCamFocal()
• It can also be used an inquiry function to retrieve the camera focal point.



Example
To be referred to msView

See Also
msView, msCamAzElRoll
384       MATFOR 4 in Fortran Reference Guide



      mfCamZoom, msCamZoom
      Zoom in on or out of the displayed object.


      Module
      fgl


      Syntax
      zf = mfCamZoom()
      call msCamZoom(zf)



      Descriptions
      Procedure msCamZoom zooms in on or out of the displayed object.

      •   In perspective mode, it decreases the view angle by the specified zoom factor zf.
      •   In parallel mode, it decreases the parallel scale by the specified zoom factor zf.

      A value greater than 1 is a zoom-in, whereas a value less than 1 is a zoom-out.



      Example
      To be referred to msView

      See Also
      msCamProj, msAngle, msCamDistance
                                                     Chapter 9 Visualization Routines   385



mfGetCamViewParam
Retrieve camera configuration values of an object.


Module
fgl


Syntax
h = mfGetCamViewParam(mode)
call msGetCamViewParam(mfOut(h),mode)



Descriptions
Procedure mfGetCamViewParam returns various camera configuration values of an object.

Argument mode is a string. For return values specification details, please refer to
msSetCamViewParam.



Example

Code
program example
      use fml
      use fgl
      implicit none
      type(mfArray):: x,y,z,h
      !Create Surface Data to draw
      call msCreateSurfData(mfOut(x,y,z),1,30,30)
      call msFigure("Get Camera")
      call msSurf(x,y,z)
      !Change first Camera angle
      call msCamAzElRoll(mf((/30.0,20.0,10.0/)))
      !Get first Camera's view direction
      h = mfGetCamViewParam('view_dir')
      call   msFigure('Set Camera')
      call   msSurf(x,y,z)
      !Set   second Camera's view direction
      call   msSetCamViewParam(mf('view_dir'),h)
      call msViewPause()
end program example


See Also
mfSetCamViewParam
386       MATFOR 4 in Fortran Reference Guide



      msSetCamViewParam
      Set camera configuration values for the display object.


      Module
      fgl


      Syntax
      call msSetCamViewParam(mode,value)



      Descriptions
      Procedure msSetCamViewParam sets various camera configuration values of the display
      object.

      Argument mode and value are specified as the following:

             mode         value

            “all”         A 1-by-9 mfArray contains all values of camera configuration. The
                          sequence of the output values goes vertically down this table.

       “view_dir”         A 1-by-3 mfArray contains the view direction of a camera object
                          which is determined by the azimuth, elevation and roll of the viewing
                          angle from a viewpoint.

         “focal”          A 1-by-3 mfArray contains the camera focal point.

            “zoom”        A 1-by-1 mfArray contains the room values of the display object.

       “distance”         A 1-by-1 mfArray contains the distance between the camera and the
                          focal point.

         “angle”          A 1-by-1 mfArray contains the angular height of the camera view
                          measured in degrees.




      Example

      See Also
      mfGetCamViewParam
                Chapter 9 Visualization Routines   387




Linear Graphs
388           MATFOR 4 in Fortran Reference Guide



      mfPlot, msPlot
      Plot two-dimensional linear graphs.


      Module
      fgl


      Syntax
      handle = mfPlot(y[, linespec])
      handle = mfPlot(x, y[, linespec])
      handle = mfPlot(x1, y1, linespec1, x2, y2, linespec2, ...)

      call msPlot(y)
      call msPlot(y, linespec)



      Descriptions
      Procedure mfPlot generates two-dimensional line graphs.

      call msPlot(y)
      call msPlot(y, linespec)
      • Plot elements of vector y against their indices. If y is a matrix, multiple lines are plotted
              from each column of y.
      •       Argument linespec contains special characters that specify line color and marker type
              of the graph. For example, "yo", specifies a graph drawn from yellow-colored, circular
              markers. linespec can be an mfArray containing the special characters or a character
              string. Refer to linespec for a list of special characters applicable for line specifications.


      Linespec


          The table below lists the linespec characters.




          Character       Line color    Character      Marker Type        Character    Line Type

          y               yellow        .              point              -            solid

          m                magenta      o              circle             :            dotted

          c                cyan         x              x-mark             -.           dashdot

          r                red          +              plus               --           dashed

          g               green         s              square
                                                               Chapter 9 Visualization Routines   389


    b               blue           d          diamond

    w               white          v          triangle down

    k               black          ^          triangle up



[h1, h2, h3, ...] = mfPlot(...)
h = mfPlot(...)
• Handles h1, h2, h3, ... retrieve the respective handles to the plot objects created by
        mfPlot(...).
•       If only one handle h is given, the procedure returns the handles in a vector mfArray.
•       Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
        current graphics object.

You can specify properties of the plot object through handle h with procedure msGSet.


Properties available are:

1. linespec
2. symbol_scale: The size of the legend. By default, legend size is 1, a half is 0.5.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: x, y1, y2, h
x = mfColon(0, 0.25d0, 50)
y1 = x*mfSin(x)
y2 = mfSin(x)
! Plot the graphs
call msPlot(x, y1, 'b-', x, y2, 'r-')
call msHold('on')
h = mfPlot(x,y2-y1,'g-')
call msHold('off')
! Pause the program for drawing
call msViewPause()
call msGSet(h,'linespec','g+')
! Pause the program for drawing
call msViewPause()
! Deallocates mfArrays
call msFreeArgs(x, y1, y2, h)
end program example
390      MATFOR 4 in Fortran Reference Guide




      Result




      See Also
      mfPlot3
                                                         Chapter 9 Visualization Routines    391



mfPlot3, msPlot3
Plot three-dimensional linear graphs.


Module
fgl


Syntax
handle = mfPlot3(x, y, z[, c])
handle = mfPlot3(xyz[, c])

call msPlot3(x, y, z)
call msPlot3(x, y, z, c)



Descriptions
Procedure mfPlot3 draws three-dimensional linear graphs.

call msPlot3(x, y, z)
call msPlot3(x, y, z, c)
• If arguments x, y and z are vectors, mfPlot3 draws a line whose x-, y-, and z-
    coordinates are elements of arguments x, y and z respectively.
•   If arguments x, y and z are matrices, mfPlot3 draws multiple lines from the columns
    of x, y and z matrices.
•   Shape of each argument must be conformed.
•   Complex data is not supported.
•   Argument c contains the corresponding scalar values of the coordinates x, y and z. By
    default, c = z.

call msPlot3(xyz)
call msPlot3(xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfPlot3(...)
• Handle h retrieves a handle to the three-dimensional linear graph objects created by
    mfPlot3(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the graphics objects through handle h with procedure msGSet.

The property available is:
392       MATFOR 4 in Fortran Reference Guide


      1. xyz : Vertex vectors.

      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, z, h
      z = mfLinspace(0, 10*MF_PI, 101)
      x = mfCos(z)
      y = mfExp(-z/20)*mfSin(z)
      call msAxis(mf((/-1, 1, -1, 1, 0, 32/)))
      ! Plot the three-dimensional graph
      h = mfPlot3(x, y, z)
      ! Specify the viewpoint
      call msView(60,30)
      ! Pause program for graphics display
      call msViewPause()
      !Change Vertex vectors
      x = mfSin(z)
      call msGSet(h,'xyz',(.t.x).hc.(.t.y).hc.(.t.z))
      call msViewPause()
      ! Deallocate memory
      call msFreeArgs(x, y, z, h)
      end program example


      Result




      See Also
      mfViewPause, mfAxis, mfSubplot, mfView, mfSurf, mfMesh
                                                              Chapter 9 Visualization Routines   393



mfRibbon, msRibbon
Plot three-dimensional ribbons.


Module
fgl


Syntax
handle = mfRibbon(x, y, z[, c])
handle = mfRibbon(xyz[, c])

call msRibbon(x, y, z[, c])
call msRibbon(xyz[, c])



Descriptions
Procedure mfRibbon draws three-dimensional ribbons.

call msRibbon(x, y, z)
call msRibbon(x, y, z, c)
• If arguments x, y and z are vectors, mfRibbon draws a ribbon whose x-, y-, and
    z-coordinates are elements of the respective arguments.
•   If arguments x, y and z are matrices, mfRibbon draws multiple ribbons from the
    columns of the argument matrices.
•   Shape of each argument must be conformed.
•   Complex data is not supported.
•   Argument c contains the corresponding scalar values of the coordinates x, y and z. By
    default, c = z.

call msRibbon(xyz)
call msRibbon(xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfRibbon(...)
• Handle h retrieves a handle to the three-dimensional ribbon objects created by
    mfRibbon(...).
•   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
    current graphics object.

You can specify properties of the graphics objects through handle h with procedure msGSet.
The properties available are:

1. sizefactor: The width of the ribbon object. By default, sizefactor is 1.
394       MATFOR 4 in Fortran Reference Guide


      2. xyz: Vertex vectors.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, z, h, c, h2
      z = mfLinspace(0, 10*MF_PI, 100)
      x = z*mfSin(z)
      y = z*mfCos(z)
      call msSubplot(1,2,1)
      call msRibbon(x, y, z)
      call msAxis(-32, 32, -32, 32, 0, 34)
      call msSubplot(1,2,2)
      h =mfTube(x, y, z, z)
      call msAxis(-32, 32, -32, 32, 0, 34)
      x = z*mfCos(z)
      y = z*mfSin(z)
      c = mfCos(z)
      call msGSet(h,'sizefactor',2d0)
      call msGSet(h,'xyz',(.t.x).hc.(.t.y).hc.(.t.z))
      call msGSet(h,'cdata',.t.c)
      call msViewPause()
      call msFreeArgs(x, y, z, h, c)
      end program example


      Result




      See Also
                                                            Chapter 9 Visualization Routines   395



mfTube, msTube
Plot three-dimensional tubes.


Module
fgl


Syntax
handle = mfTube(x, y, z[, c])
handle = mfTube(xyz[, c])

call msTube(x, y, z[, c])
call msTube(xyz[, c])



Descriptions
Procedure mfTube draws three-dimensional tubes.

call msTube(x, y, z)
call msTube(x, y, z, c)
• If arguments x, y and z are vectors, mfTube draws a tube whose x-, y-, and z-
    coordinates are elements of the respective arguments.
•   If arguments x, y and z are matrices, mfTube draws multiple tubes from the columns of
    the argument matrices.
•   Shape of each argument must be conformed.
•   Complex data is not supported.
•   Argument c contains the corresponding scalar values of the coordinates x, y and z. By
    default, c = z.

call msTube(xyz)
call msTube(xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTube(...)
• Handle h retrieves a handle to the three-dimensional tube objects created by
    mfTube(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the graphics objects through handle h with procedure msGSet.

The properties available are:
396       MATFOR 4 in Fortran Reference Guide


      1. sizefactor: The diameter of the tube objects. By default, size factor is 1.
      2. xyz: Vertex vectors.



      Example
      To be referred to mfRibbon

      See Also
      mfRibbon
                                                                  Chapter 9 Visualization Routines   397



mfStem, msStem
Plot two-dimensional stem graphs.


Module
fgl


Syntax
handle = mfStem(y[, linespec])
handle = mfStem(x, y[, linespec])
handle = mfStem(x1, y1, linespec1, x2, y2, linespec2, ...)

call msStem(y)
call msStem(y, linespec)



Descriptions
Procedure mfStem generates two-dimensional stem graphs.

call msStem(y)
call msStem(y, linespec)
• Plot elements of vector y against their indices. If y is a matrix, multiple lines are plotted
        from each column of y.
•       Argument linespec contains special characters that specify line colors and marker
        types of the graph. For example, "yo", specifies a graph drawn from yellow-colored,
        circular markers. linespec can be an mfArray containing the special characters or a
        character string. Refer to linespec for a list of special characters applicable for line
        specifications.



Linespec


    The table below lists the linespec characters.




    Character       Line color    Character     Marker Type         Character    Line Type

    y               yellow        .             point               -            solid

    m               magenta       o             circle              :            dotted

    c               cyan          x             x-mark              -.           dashdot
398           MATFOR 4 in Fortran Reference Guide


          r               red            +          plus               --          dashed

          g               green          s          square

          b               blue           d          diamond

          w               white          v          triangle down

          k               black          ^          triangle up



      [h1, h2, h3, ...] = mfStem(...)
      h = mfStem(...)
      • Handles h1, h2, h3, ... retrieve respective handles to the plot objects created by
              mfStem(...).
      •       If only one handle h is given, the procedure returns the handle in a vector mfArray.
      •       Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of
              current graphics object.

      You can specify properties of the plot object through handle h with procedure msGSet.


      The property available is:

      1. linespec
      2. symbol_scale: The size of the legend. By default, legend size is 1, a half is 0.5.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: x, y1, y2, h
      x = mfColon(0, 0.2d0, 10)
      y1 = x*mfSin(x)
      y2 = mfSin(x)
      ! Plot the Stem
      call msStem(x, y1, 'bo-', x, y2, 'r')
      call msHold('on')
      h = mfStem(x,y2-y1,'g')
      call msHold('off')
      ! Pause the program for drawing
      call msViewPause()
      ! Deallocates mfArrays
      call msFreeArgs(x, y1, y2, h)
      end program example
           Chapter 9 Visualization Routines   399




Result




See Also
mfPlot
400          MATFOR 4 in Fortran Reference Guide



      mfBar
      Plot two-dimensional vertical bars.


      Module
      fgl


      Syntax
      handle      =   mfBar(x,y)
      handle      =   mfBar(y)
      handle      =   mfBar(x,y[, width])
      handle      =   mfBar(...[, color])
      handle      =   mfBar(...[,'group'])
      handle      =   mfBar(...[,'stack'])

      call msBar(y)
      call msBar(x,y)
      call msBar(y, color)



      Descriptions
      Procedure mfBar plots vertical bars in two-dimensional space.

      call msBar(y)
      call msBar(y, color)
      • Plot elements of vector y against their indices. If y is a matrix, multiple bars are plotted
             from each raw of y.
      •      Argument color contains special characters that specify bar colors. For example, 'r',
             specifies a graph drawn from red-colored. The Color table below contains a list of special
             characters applicable for color specifications.

      Color
      Character         y        m          c         r         g       b         w         k
      Line            yellow   magenta    cyan       red       green   blue     white    black
      color



      You can specify colors of the plot object through handle h with procedure msColorbar or
      msDrawMaterial.


      call msBar(x,y)
      • Plot elements of vector y specified at x. If y is a matrix, multiple bars are plotted from
                                                          Chapter 9 Visualization Routines     401


    each raw of y. Each element in vector x specifies the location for the corresponding raw
    in y.

h = mfBar(...)
• The procedure returns the handle h in a vector mfArray.
•   Argument width sets the bar width that ranges from 0 to 1. For example, width = 1 sets
    bars in the same group touching one another.
•   Argument 'group' groups and displays elements in each raw of y side by side. This is
    set by default for the display.
•   Argument 'stack' displays elements in each raw of y in one bar.



Example

Code
Program bar
use fml
use fgl
implicit none
type(mfArray) :: d1, d2, d3, d4
d1 = mfColon(1,20) * mfSqrt( mfColon(20,-1,1) )
d2 = mfMagic(5)
d3 = mfCreateSurfData( 1, 5, 5 )
call msFigure('bar')
call msBar(d1, 1)
call msFigure('bar')
call msBar(d2)
call msFigure('barh')
call msBarh( d2, 'stack' )
call msFigure('barh')
call msBarh( mfColon(10,5,30), d2 )
call msFigure('bar3')
call msBar3( d2 )
call msFigure('bar3')
call msBar3( d3 )
call msFigure('bar3')
call msBar3( d2, 'group' )
call msAxis3DDependency('xy_depend', 1, 10)
call   msFigure('bar3h')
call   msBar3h( d2, 'stack' )
call   msAxis3DDependency('xz_depend', 10, 1)
call   msAxis( 0, 0, 0, 0, 0, 6 )
call msViewPause
end Program bar


Result
402      MATFOR 4 in Fortran Reference Guide




      See Also
      mfBarh, mfBar3
                                                                 Chapter 9 Visualization Routines   403



mfBarh
Plot two-dimensional horizontal bars.


Module
fgl


Syntax
handle      =   mfBarh(x,y)
handle      =   mfBarh(y)
handle      =   mfBarh(x,y[, width])
handle      =   mfBarh(...[, color])
handle      =   mfBarh(...[,'group'])
handle      =   mfBarh(...[,'stack'])

call msBarh(y)
call msBarh(x,y)
call msBarh(y, color)



Descriptions
Procedure mfBarh plots horizontal bars in two-dimensional space.

call msBarh(y)
call msBarh(y, color)
• Plot elements of vector y against their indices. If y is a matrix, multiple bars are plotted
       from each raw of y.
•      Argument color contains special characters that specify bar colors. For example, 'r',
       specifies a graph drawn from red-colored. The Color table below contains a list of special
       characters applicable for color specifications.

Color
Character         y        m          c         r         g          b         w         k
Line            yellow   magenta    cyan       red       green      blue     white     black
color



You can specify colors of the plot object through handle h with procedure msColorbar or
procedure msDrawMaterial.


call msBarh(x,y)
• Plot elements of vector y specified at x. If y is a matrix, multiple bars are plotted from
404       MATFOR 4 in Fortran Reference Guide


          each raw of y. Each element in vector x specifies the location for the corresponding raw
          in y.

      h = mfBarh(...)
      • The procedure returns the handle h in a vector mfArray.
      •   Argument width sets the bar width that ranges from 0 to 1. For example, width = 1 sets
          bars in the same group touching one another.
      •   Argument 'group' groups and displays elements in each raw of y side by side. This is
          set by default for the display.
      •   Argument 'stack' displays elements in each raw of y in one bar.



      Example
      To be referred to mfBar

      See Also
      mfBar, mfBar3h
                                                                 Chapter 9 Visualization Routines   405



mfBar3
Plot three-dimensional vertical bars.


Module
fgl


Syntax
handle      =   mfBar3(x,y)
handle      =   mfBar3(y)
handle      =   mfBar3(x,y[, width])
handle      =   mfBar3(...[, color])
handle      =   mfBar3(...[,'detach'])
handle      =   mfBar3(...[,'group'])
handle      =   mfBar3(...[,'stack'])

call msBar3(y)
call msBar3(x,y)
call msBar3(y, color)



Descriptions
Procedure mfBar3 plots vertical bars in three-dimensional space.

call msBar3(y)
call msBar3(y, color)
• Plot elements of vector y against their indices. If y is a matrix, multiple bars are plotted
       from each raw of y.
•      Argument color contains special characters that specify bar colors. For example, 'r',
       specifies a graph drawn from red-colored. The Color table below contains a list of special
       characters applicable for color specifications.

Color
Character         y        m          c         r         g          b         w         k
Line            yellow   magenta    cyan       red       green      blue     white     black
color



You can specify colors of the plot object through handle h with procedure msColorbar or
procedure msDrawMaterial .


call msBar3(x,y)
• Plot elements of vector y specified at x. If y is a matrix, multiple bars are plotted from
406       MATFOR 4 in Fortran Reference Guide


          each raw of y. Each element in vector x specifies the location for the corresponding raw
          in y.

      h = mfBar3(...)
      • The procedure returns the handle h in a vector mfArray.
      •   Argument width sets the bar width that ranges from 0 to 1. For example, width = 1 sets
          bars in the same group touching one another.
      •   Argument 'detach' displays elements of y separately. This is set by default for the
          display.
      •   Argument 'group' groups and displays elements in each raw of y side by side.
      •   Argument 'stack' displays elements in each raw of y in one bar.



      Example
      To be referred to mfBar

      See Also
      mfBarh, mfBar
                                                                 Chapter 9 Visualization Routines   407



mfBar3h
Plot three-dimensional horizontal bars.


Module
fgl


Syntax
handle      =   mfBar3h(x,y)
handle      =   mfBar3h(y)
handle      =   mfBar3h(x,y[, width])
handle      =   mfBar3h(...[, color])
handle      =   mfBar3h(...[,'detach'])
handle      =   mfBar3h(...[,'group'])
handle      =   mfBar3h(...[,'stack'])

call msBar3h(y)
call msBar3h(x,y)
call msBar3h(y, color)



Descriptions
Procedure mfBar3h plots horizontal bars in three-dimensional space.

call msBar3h(y)
call msBar3h(y, color)
• Plot elements of vector y against their indices. If y is a matrix, multiple bars are plotted
       from each raw of y.
•      Argument color contains special characters that specify bar colors. For example, 'r',
       specifies a graph drawn from red-colored. The Color table below contains a list of special
       characters applicable for color specifications.

Color
Character         y        m          c         r         g          b         w         k
Line            yellow   magenta    cyan       red       green      blue     white     black
color



You can specify colors of the plot objects through handle h with procedure msColorbar or
procedure msDrawMaterial.


call msBar3h(x,y)
• Plot elements of vector y specified at x. If y is a matrix, multiple bars are plotted from
408       MATFOR 4 in Fortran Reference Guide


          each raw of y. Each element in vector x specifies the location for the corresponding raw
          in y.

      h = mfBar3h(...)
      • The procedure returns the handle h in a vector mfArray.
      •   Argument width sets the bar width that ranges from 0 to 1. For example, width = 1 sets
          bars in the same group touching one another.
      •   Argument 'detach' displays elements of y separately. This is set by default for the
          display.
      •   Argument 'group' groups and displays elements in each raw of y side by side.
      •   Argument 'stack' displays elements in each raw of y in one bar.



      Example
      To be referred to mfBar

      See Also
      mfBar3, mfBarh
                 Chapter 9 Visualization Routines   409




Surface Graphs
410       MATFOR 4 in Fortran Reference Guide



      mfSurf, msSurf
      Create surface plots.


      Module
      fgl


      Syntax
      handle = mfSurf(z[, c])
      handle = mfSurf(x, y, z[, c])

      call msSurf(x, y, z[, c])
      call msSurf(z[, c])



      Descriptions
      Procedure mfSurf creates three-dimensional graphs composed of colored quadrilateral
      surfaces. You can choose amongst several shading options including mesh, flat, faceted, and
      interpolated. The options can be set using procedure mfShading or through the menu and
      toolbar functions of the Graphics Viewer. Note that mesh surfaces can also be plotted using
      procedure mfMesh.

      call msSurf(x, y, z)
      call msSurf(x, y, z, c)
      • Plot surface objects from arguments x, y and z. The arguments x, y and z contain the
          respective coordinates of the surface object's grid intersections.
      •   x, y and z are matrices, hence the size of x and y should be conformed to that of z. The
          grid intersections are given by (x(i,j), y(i,j), z(i,j)).
      •   By default, the color of the surface is proportional to the z coordinates of the surface
          object. Specifying argument c overrides the default color scale.
      •   By default, mfSurf draws surfaces with faceted shading.

      call msSurf(z)
      call msSurf(z, c)
      • Creates a three-dimensional surface from the m-by-n matrix z. Arguments x and y are
          set to the default msMeshgrid(mfOut(x,y), mfColon(1,n),
          mfColon(1,m)).Argument z is a single-valued matrix defined over a rectangular grid
          formed by x and y.



      h = mfSurf(...)
      • Handle h retrieves a handle to the surface object created by mfSurf(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
                                                        Chapter 9 Visualization Routines    411


   current graphics object.
You can specify the properties of surface objects through handle h with procedure msGSet.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: a, b, c, x, y, z, indxi, indxj
a = mfLinspace(-3, 7, 51)
b = mfLinspace(-2, 8, 51)
c = mfColon(1, 51)
call msMeshgrid(mfout(x, y), a, b)
call msMeshgrid(mfout(indxi, indxj), c)
z = 3*mfSin((indxi+1)/10)*mfCos((indxj+1)/10) &
   + 2*mfSin((indxi+indxj)/10)
! Plot a surf using mfArray x, y and z
call msSurf(x, y, z)
! Pause to display the graph
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


Result




See Also
mfViewPause, mfAxis, mfSubplot, mfView, mfMesh, mfPlot3
412       MATFOR 4 in Fortran Reference Guide



      mfMesh, msMesh
      Create mesh plots.


      Module
      fgl


      Syntax
      handle = mfMesh(z[, c])
      handle = mfMesh(x, y, z[, c])

      call msMesh(z[, c])
      call msMesh(x, y, z[, c])



      Descriptions
      Procedure mfMesh plots a three-dimensional mesh surface consisting of criss-crossed lines
      that looks like a net draped over the surface defined by your data.

      call msMesh(x, y, z)
      call msMesh(x, y, z, c)
      • Plot surface objects from arguments x,y and z. The arguments x,y and z contain the
          respective coordinates of the surface object's grid intersections.
      •   x,y and z are matrices, hence their shapes should conform. The grid intersections are given
          by (x(i,j), y(i,j), z(i,j)).
      •   By default, the color of the wire-frame grid is proportional to the z coordinates of the
          surface object. Specifying argument c overrides the default color scale.

      call msMesh(z)
      call msMesh(z, c)
      • Creates a three-dimensional surface from the m-by-n matrix z. Arguments x and y are
          set to the default msMeshgrid(mfOut(x,y), mfColon(1,n),
          mfColon(1,m)). Argument z is a single-valued matrix defined over a rectangular grid
          formed by x and y.

      h = mfMesh(...)
      • Handle h retrieves a handle to the mesh surface object created by mfMesh(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
         current graphics object.
      You can specify properties of the surface objects through handle h with procedure procedure
      msGSet.
                                                Chapter 9 Visualization Routines   413


Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: a, b, c, x, y, z, indxi, indxj
a = mfLinspace(-3, 7, 51)
b = mfLinspace(-2, 8, 51)
c = mfColon(1, 51)
call msMeshgrid(mfout(x, y), a, b)
call msMeshgrid(mfout(indxi, indxj), c)
z = 3*mfSin((indxi+1)/10)*mfCos((indxj+1)/10) &
   + 2*mfSin((indxi+indxj)/10)
! Plot a mesh grid using mfArray x, y and z for the grid
! intersections.
call msMesh(x, y, z)
! Pause to display the graph
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


Result




See Also
mfViewPause, mfAxis, mfSubplot, mfView, mfSurf, mfPlot3
414       MATFOR 4 in Fortran Reference Guide



      mfSurfc, msSurfc
      Create plots combined of surface and contour3.


      Module
      fgl


      Syntax
      handle = mfSurfc(z[, c])
      handle = mfSurfc(x, y, z[, c])

      call msSurfc(mfOut(h1, h2), z[, c])
      call msSurfc(mfOut(h1, h2), x, y, z[, c])



      Descriptions
      Procedure mfSurfc draws a contour below the surface object.

      call msSurfc(z) draws a contour below the surface object created by mfSurf(z).

      call msSurfc(x, y, z) draws a contour below the surface object created by mfSurf(x,
      y, z).

      call msSurfc(mfOut(h1, h2), ...)
      • Handles h1 and h2 retrieve the handles to the surface object and contour object created
          by mfSurfc(...)respectively.
      •   If only one handle h is given, the procedure returns two handles in a vector mfArray.
          mfS(h,1) represents the mesh object and mfS(h,2) represents the contour object.
      •   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
          contour graphics object.
      You can specify properties of the surface object through handle h with procedure msGSet.
      For properties, see the description on mfSurf.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, b, c, x, y, z, indxi, indxj
      a = mfLinspace(-3, 7, 51)
      b = mfLinspace(-2, 8, 51)
      c = mfColon(1, 51)
      call msMeshgrid(mfout(x, y), a, b)
                                           Chapter 9 Visualization Routines   415

call msMeshgrid(mfout(indxi, indxj), c)
z = 3*mfSin((indxi+1)/10)*mfCos((indxj+1)/10) &
   + 2*mfSin((indxi+indxj)/10)
! Plot a surf using mfArray x, y and z and Plot Contour below the surf
call msSurfc(x, y, z)
! Pause to display the graph
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


Result




See Also
mfSurf
416       MATFOR 4 in Fortran Reference Guide



      mfMeshc, msMeshc
      Create plots combined of mesh and contour3.


      Module
      fgl


      Syntax
      handle = mfMeshc(z[, c])
      handle = msMeshc(x, y, z[, c])

      call msMeshc(mfOut(h1, h2), z[, c])
      call msMeshc(mfOut(h1, h2), x, y, z[, c])



      Descriptions
      Procedure mfMeshc draws a contour below the meshed surface object.

      call msMeshc(z) draws a contour below the meshed surface object created by
      mfSurf(z).
      call msMeshc(x, y, z) draws a contour below the meshed surface object created by
      mfSurf(x, y, z).

      call msSurfc(mfOut(h1, h2), ...)
      • Handles h1 and h2 retrieve the handles to the meshed surface object and contour object
          created by mfMeshc(...) respectively.
      •   If only one handle h is given, the procedure returns two handles in a vector mfArray.
          mfS(h,1) represents the mesh object and mfS(h,2) represents the contour object.
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          contour graphics object.

      You can specify properties of the surface object through handle h with procedure msGSet.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, b, c, x, y, z, indxi, indxj
      a = mfLinspace(-3, 7, 51)
      b = mfLinspace(-2, 8, 51)
      c = mfColon(1, 51)
      call msMeshgrid(mfout(x, y), a, b)
                                           Chapter 9 Visualization Routines   417

call msMeshgrid(mfout(indxi, indxj), c)
z = 3*mfSin((indxi+1)/10)*mfCos((indxj+1)/10) &
   + 2*mfSin((indxi+indxj)/10)
! Plot a mesh grid using mfArray x, y and z for the grid
! intersections and Plot Contour below the mesh
call msMeshc(x, y, z)
! Pause to display the graph
call msViewPause()
! Deallocate mfArray
call msFreeArgs(a, b, c, x, y, z, indxi, indxj)
end program example


Result




See Also
mfMesh
418       MATFOR 4 in Fortran Reference Guide



      mfPColor, msPColor
      Create pseudocolor plots.


      Module
      fgl


      Syntax
      handle = mfPColor(c)
      handle = mfPColor(x,y,c)

      call msPColor(c)
      call msPColor(x, y, c)



      Descriptions
      Procedure mfPColor produces a pseudocolor plot of matrix mfArray c by mapping the
      elements of c to the current colormap. This procedure is equivalent to a top-view of
      mfSurf.

      call msPColor(c)
      • The procedure displays matrix mfArray c as a checker-board plot with elements of c
          specifying each cell of the plot, mapped to the index of the current colormap.
      •   The smallest and largest elements of matrix c correspond to the minimum and maximum
          indices of the colormap.
      •   By default, the shading is "faceted", with each cell containing a constant color. Each
          element of matrix c specifies the color of a rectangular patch in the image.

      call msPColor(x, y, c)
      • Draws the checker-board plot on the grid defined by arguments x and y. The arguments
          x and y can be vectors or matrices.

      h = mfPColor(...)
      • Handle h retrieves a handle to the pseudocolor plot object created by
          mfPColor(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the pseudocolor plot object through handle h with procedure
      msGSet.



      Example
                                             Chapter 9 Visualization Routines   419



Code
program example
use fml
use fgl
implicit none
type(mfArray) :: theta, phi, x, y, z
theta = mfLinspace(-MF_PI, MF_PI, 31)
phi = .t. theta /4
x = mfMul(mfSin(phi), mfCos(theta))
y = mfMul(mfSin(phi), mfSin(theta))
z = mfMul(mfSin(phi), mfOnes(1,31))
! Plot the surface object using X, Y and Z
call msSubplot(1,2,1)
call msPColor(x, y, z)
call msAxis('equal')
call msCamZoom(0.8d0)
call   msSubplot(1,2,2)
call   msFastPColor(x,mf((/5d0,10d0,5d0,10d0/)))
call   msAxis('equal')
call   msCamZoom(0.8d0)
! Pause the program for display
call msViewPause()
! Deallocate mfArray
call msFreeArgs(x, y, z)
end program example


Result




See Also
mfSurf
420       MATFOR 4 in Fortran Reference Guide



      mfFastPColor, msFastPColor
      Create pseudocolor plots.


      Module
      fgl


      Syntax
      handle = mfFastPColor(c)
      handle = mfFastPColor(c, extent)

      call msFastPColor(c)
      call msFastPColor(c, extent)



      Descriptions
      Procedure mfFastPColor produces a pseudocolor plot of matrix mfArray c by mapping
      the elements of c to current colormap. This procedure is equivalent to a top-view of
      mfSurf.

      call msFastPColor(c)
      • The procedure displays matrix mfArray c as a checker-board plot with elements of c
          specifying each cell of the plot, mapped to the index of the current colormap.
      •   The smallest and largest elements of matrix c correspond to the minimum and maximum
          indices of the colormap.

      call msFastPColor(x, y, c)
      • The procedure draws a checker-board plot using extent (a 1 by 4 vector defined by [Xmin,
          Xmax, Ymin, Ymax]), where each element of extend represents the boundary of matrix
          c.
      (Xmin, Ymax)                          (Xmax, Ymax)




      (Xmin, Ymin)                          (Xmax, Ymin)


      h = mfFastPColor(...)
                                                           Chapter 9 Visualization Routines   421


•   Handle h retrieves a handle to the pseudocolor plot object created by
    mfFastPColor(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the pseudocolor plot object through handle h with procedure
msGSet.



Example
To be referred to mfPColor

See Also
mfPColor, mfSurf
422       MATFOR 4 in Fortran Reference Guide



      mfContour, msContour
      Plot two-dimensional line contours.


      Module
      fgl


      Syntax
      handle = mfContour(c)
      handle = mfContour(x, y, c)

      call msContour(c)
      call msContour(x, y, c)



      Descriptions
      Procedure mfContour plots constant value lines in two-dimensional space.
      handle = mfContour(x, y, c)
      • Generate two-dimensional contour lines of matrix c. The values plotted are selected
          automatically.
      •   Argument c is assumed to contain data representing the scalar values.
      •   Arguments x and y specify the corresponding coordinates of the scalar values.
      •   Similar to mfSurf and mfMesh,the colors of the contour lines are selected based on the
          current colormap.

      call msContour(c)
      • The scalar value c is assumed to be defined over a geometrically rectangular grid where x
          = mfColon(1, n) and y = mfColon(1, m).

      h = mfContour(...)
      • Handle h retrieves a handle to the contour object created by mfContour(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
          current graphics object.

      You can specify properties of the contour object through handle h with procedure msGSet.

      See mfContour3 for available properties.



      Example

      Code
      program example
      use fml
                                              Chapter 9 Visualization Routines   423

use fgl
implicit none
type(mfArray) :: a, x, y, z
a = mfLinspace(-MF_PI, MF_PI, 50)
call msMeshgrid(mfout(x, y) ,a)
z = (1/mfCosh(x))*mfCos(y+MF_PI/2)
! Draw a 2-D contour plot
call msContour(z)
call msAxis('equal')
call msCamZoom(0.8d0)
! Pause the program to display the graphics
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(a, x, y, z)
end program example


Result




See Also
mfSolidContour, mfContour3
424       MATFOR 4 in Fortran Reference Guide



      mfContour3, msContour3
      Plot three-dimensional line contours.


      Module
      fgl


      Syntax
      handle = mfContour3(z[, c])
      handle = mfContour3(x, y, z[, c])

      call msContour3(z, c)
      call msContour3(x, y, z, c)



      Descriptions
      Procedure mfContour3 plots constant value lines of matrix z in three-dimensional space.
      The values plotted are selected automatically.

      call msContour3(z, c)
      call msContour3(x, y, z, c)
      • This procedure is similar to mfContour. The contour lines are presented in
          three-dimensional perspective reflecting their scalar values. The values plotted are
          selected automatically.

      h = mfContour3(...)
      • Handle h retrieves a handle to the three-dimensional contour object created by
          mfContour3(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the three-dimensional contour object through handle h with
      procedure msGSet.

      The properties available are:

      1. iso: iso-values, a vector containing an iso-value set. Setting this property will replace the
      default set of contour lines.
      2. autolevel: given the number of levels, it will automatically generate iso-value sets.
      3. label: "on" or "off"



      Example

      Code
                                                Chapter 9 Visualization Routines   425

program example
use fml
use fgl
implicit none
type(mfArray) :: a, x, y, z, h
a = mfLinspace(-MF_PI, MF_PI, 50)
call msMeshgrid(mfout(x, y) ,a)
z = (1/mfCosh(x))*mfCos(y+MF_PI/2)
! Draw a 3-D contour plot
h = mfContour3(z)
!Set Contour's label On
call msGSet(h,'label','on')
! Pause the program to display the graphics
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(a, x, y, z, h)
end program example


Result




See Also
mfContour, mfSolidContour, mfSolidContour3, mfTriContour
426       MATFOR 4 in Fortran Reference Guide



      mfSolidContour, msSolidContour
      Plot two-dimensional solid contours.


      Module
      fgl


      Syntax
      handle = mfSolidContour(c)
      handle = mfSolidContour(x, y, c)

      call msSolidContour(c)
      call msSolidContour(x, y, c)



      Descriptions
      Procedure mfSolidContour colors areas that are in between constant value lines in
      two-dimensional space.

      handle = mfSolidContour(x, y, c)
      • The values plotted are selected automatically.
      •   Argument c is assumed to contain data representing the scalar values.
      •   Arguments x and y specify the corresponding x-, y- coordinates of the scalar values.
      •   Similar to mfSurf and mfMesh, the surface colors are selected based on the current
          colormap.

      call msSolidContour(c)
      • The scalar value c is assumed to be defined over a geometrically rectangular grid where x
          = mfColon(1, n) and y = mfColon(1, m).

      h = mfSolidContour(...)
      • Handle h retrieves a handle to the contour object created by
          mfSolidContour(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the contour object through handle h with procedure msGSet.
      The properties available are:

      1. iso: iso-values, a vector containing an iso-value set. Setting this property will replace the
      default set of contour lines.
      2. autolevel: given the number of levels, it will automatically generate iso-value sets.
      3. label: "on" or "off"4. clipping: "on" or "off"
                                              Chapter 9 Visualization Routines   427



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: a, x, y, z
a = mfLinspace(-MF_PI, MF_PI, 50)
call msMeshgrid(mfout(x, y) ,a)
z = (1/mfCosh(x))*mfCos(y+MF_PI/2)
! Draw a 2-D solidcontour
call msSolidContour(z)
call msAxis('equal')
call msCamZoom(0.8d0)
! Pause the program to display the graphics
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(a, x, y, z)
end program example


Result




See Also
428       MATFOR 4 in Fortran Reference Guide



      mfSolidContour3, msSolidContour3
      Plot three-dimensional solid contours.


      Module
      fgl


      Syntax
      handle = mfSolidContour3(z[, c])
      handle = mfSolidContour3(x, y, z[, c])

      call msSolidContour3(z, c)
      call msSolidContour3(x, y, z, c)



      Descriptions
      Procedure mfSolidContour3 colors areas that are in between the constant value lines in
      three-dimensional space.

      call msSolidContour3(x, y, z, c)
      call msSolidContour3(z, c)
      • This procedure is similar to mfSolidContour. The areas are presented in
          three-dimensional perspective reflecting their scalar values specified in argument c.

      h = mfSolidContour3(...)
      • Handle h retrieves a handle to the three-dimensional contour object created by
          mfSolidContour3(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the three-dimensional contour object through handle h with
      procedure msGSet.

      The properties available are:

      1. iso: iso-values, a vector containing an iso-value set.
      2. autolevel: given the number of levels, it will automatically generate iso-value sets.
      3. label: "on" or "off".
      4. clipping: "on" or "off": setting clipping "on" will erase the excess iso-value specified.
      By default, clipping is set to "off".



      Example

      Code
                                                Chapter 9 Visualization Routines   429

program example
use fml
use fgl
implicit none
type(mfArray) :: a, x, y, z, iso, h1, h2
a = mfLinspace(-MF_PI, MF_PI, 50)
call msMeshgrid(mfout(x, y) ,a)
z = (1/mfCosh(x))*mfCos(y+MF_PI/2)
! Draw a 3-D solidcontour
call msSubplot(1,2,1)
h1 = mfSolidContour3(z)
call msGSet(h1,'label','on')
call msSubplot(1,2,2)
h2 = mfSolidContour3(z)
call msGSet(h2,'label','on')
iso = mfLinspace(-0.6d0,0.6d0,8)
call msGSet(h2,'iso',iso)
call msGSet(h2,'clipping','on')
! Pause the program to display the graphics
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(a, x, y, z, iso, h1, h2)
end program example


Result




See Also
mfContour, mfContour3, mfSolidContour, mfSolidContour, mfTriContour
430       MATFOR 4 in Fortran Reference Guide



      mfOutline, msOutline
      Create wireframe outline boundaries.


      Module
      fgl


      Syntax
      handle = mfOutline(x, y, z)
      handle = mfOutline(z)



      Descriptions
      Procedure mfOutline generates a wireframe outline boundary for a given data set.
      Arguments x,y and z specify the corresponding coordinates of the points in the data set.

      handle = mfOutline(...)
      • Handle h retrieves a handle to the outline object created by mfOutline(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the outline object through handle h with procedure msGSet.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, x, y, z, h1, h2
      a = mfLinspace(-MF_PI, MF_PI, 35)
      call msMeshgrid(mfOut(x, y) ,a)
      z = (1/mfCosh(x))*mfCos(y+MF_PI/2)
      ! Draw a 3-D surface
      h1 = mfSurf(x,y,z)
      call msHold('on')
      h2 = mfOutline(x,y,z)
      call msHold('off')
      !Change material of surface and outline
      call msDrawMaterial(h1,mf('edge'),mf('visible'),mf('off'))
      call msDrawMaterial(h1,mf('surf'),mf('colormap'),mf('off'), &
      mf('diffuse'),mf(20),mf('specular'),mf(90),mf('ambient'),mf(0))
      call msDrawMaterial(h2,mf('edge'),mf('color'),mf((/1,0,0/)))
      ! Pause the program to display the graphics
      call msViewPause()
                                      Chapter 9 Visualization Routines   431

! Deallocate mfArrays
call msFreeArgs(a, x, y, z, h1, h2)
end program example


Result




See Also
432       MATFOR 4 in Fortran Reference Guide



      mfIsoSurface, msIsoSurface
      Create three-dimensional iso-value surface plots from volumetric data.


      Module
      fgl


      Syntax
      handle = mfIsoSurface(c, isovalue)
      handle = mfIsoSurface(x, y, z, c, isovalue)

      call msIsoSurface(c, isovalue)
      call msIsoSurface(x, y, z, c, isovalue)



      Descriptions
      Procedure mfIsoSurface creates 3-D graphs composed of isosurface data from the
      volumetric data c at the isosurface value specified in argument isovalue.

      call msIsoSurface(c, isovalue)
      • The coordinates for volume c are of a geometrically rectangular grid where x =
          mfColon(1, n) and y = mfColon(1, m) and z = mfColon(1, p).

      call msIsoSurface(x, y, z, c, isovalue)
      • The arguments x,y and z define the coordinates for the volume c.

      h = mfIsoSurface(...)
      • Handle h retrieves a handle to the isosurface object created by mfIsoSurface(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the isosurface object through handle h with procedure msGSet.

      The properties available are:

      1. iso: iso-values, a vector containing an iso-value set.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
                                               Chapter 9 Visualization Routines   433

type(mfArray) :: x, y, z, v, v2, a, b, c, h
type(mfArray) :: g_tri,g_x,g_y,g_z,g_c
a = mfLinspace(-2, 2.2d0, 21)
b = mfLinspace(-2, 2.25d0, 17)
c = mfLinspace(-1.5d0, 1.6d0, 31)
call msMeshgrid(mfout(y, x, z), b, a, c)
v = 2*mfCos(x**2)*mfExp(-(y**2)-(z**2))
call msSubplot(1,2,1)
! Plot IsoSurface and Set Transparency to 70
h = mfIsoSurface(x, y, z, v, mf((/1.0, 0.6, 0.3/)))
call msDrawMaterial(h, mf('surf'), mf('trans'), mf(70))
! Set Colorbar
call msColorbar('on')
call msSubplot(1,2,2)
!Get IsoSurface data and draw it.
call msGetIsoSurface(mfOut(g_tri,g_x,g_y,g_z,g_c),&
   x, y, z, v, mf(0.4d0))
v2 = 2*mfSin(g_x**2)*mfExp(-(g_y**2)-(g_z**2))
h = mfTriSurf(g_tri,g_x,g_y,g_z,v2)
call msDrawMaterial(h, mf('edge'),mf('visible'),mf('off'))
call msDrawMaterial(h,mf('surf'),mf('smooth'),mf('on'),&
                 mf('ambient'),mf(0),&
                 mf('diffuse'),mf(100),&
                 mf('specular'),mf(0))
call msColorbar('on')
! Pause the program for display
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(x, y, z, v, a, b, c, h)
call msFreeArgs(g_tri,g_x,g_y,g_z,g_c,v2)
end program example


Result




See Also
msViewPause, mfAxis, mfSubplot, mfView, mfMesh, mfSurf
434       MATFOR 4 in Fortran Reference Guide



      msGetIsoSurface
      Retrieve three-dimensional iso-value surface plots from volumetric data.


      Module
      fgl


      Syntax
      call msGetIsoSurface(mfOut(tri,x,y,z,c),c, iso)
      call msGetIsoSurface(mfOut(tri,x,y,z,c),x, y, z, c, iso)



      Descriptions
      Procedure mfGetIsoSurface retrieves 3-D graphs composed of isosurface data from the
      volumetric data c. It returns the triangular mesh tri and the vertex vectors of isourface.

      For details on the input arguments, please refer to the description of procedure
      mfIsoSurface.



      Example
      To be referred to mfIsoSurface

      See Also
      mfIsoSurface
               Chapter 9 Visualization Routines   435




Slice Graphs
436       MATFOR 4 in Fortran Reference Guide



      mfSliceXYZ, msSliceXYZ
      Display orthogonal slice-planes through volumetric data.


      Module
      fgl


      Syntax
      handle = mfSliceXYZ([x, y, z,] c, Sx, Sy, Sz)

      call msSliceXYZ([x, y, z,] c, Sx, Sy, Sz)



      Descriptions
      Procedure mfSliceXYZ displays orthogonal slice-planes of a specified set of volumetric
      data. The information on the slice-planes can be retrieved using procedure
      msGetSliceXYZ.

      call msSliceXYZ(x, y, z, c, Sx, Sy, Sz)
      • Displays orthogonal slice-planes along the x-, y- and z- directions specified by points in
          vector mfArrays Sx, Sy and Sz.
      •   Substitute mf() for any of the direction vectors Sx, Sy or Sz that you are not drawing
          any slice along. E.g. call msSliceXYZ(x, y, z, v, Sx, mf(), Sz) draws slices
          along the x-axis as specified by Sx and along the z-axis as specified by Sz.
      •   The arguments x, y and z define the corresponding coordinates of scalar values mfArray
          c,where c is an m-by-n-by-p three-dimensional array.
      •   The arguments x, y and z must be of the same shape as c and be monotonic and
          three-dimensional plaid as if produced by procedure mfMeshgrid.
      •   The color at each point is determined by three-dimensional interpolation of the elements
          of volume c, mapped onto the current colormap.

      call msSliceXYZ(c, Sx, Sy, Sz)
      • Assumes x is composed of mfColon(1, n) vectors, y is composed of mfColon(1, m)
          vectors, and z is composed of mfColon(1, p) vectors.

      h = mfSliceXYZ(...)
      • Handle h retrieves a handle to the volumetric slice object created by
          mfSliceXYZ(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the volumetric slice objects through handle h with procedure
                                                               Chapter 9 Visualization Routines   437


msGSet.

The properties available are:

1. slicex: specifies the slice-planes along the x direction.
2. slicey: specifies the slice-planes along the y direction.
3. slicez: specifies the slice-planes along the z direction.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: nx, ny, nz, x, y, z, c
type(mfArray) :: stri,sx,sy,sz,sc
nx = mfLinspace(-2, 2.2d0, 21)
ny = mfLinspace(-2, 2.25d0, 17)
nz = mfLinspace(-1.5d0, 1.6d0, 31)
call msMeshgrid(mfout(y, x, z), ny, nx, nz)
c = 2*mfCos(x**2)*mfExp(-(y**2)-(z**2))
call msSliceXYZ(x, y, z, c, mf((/-1.0d0, 1.0d0/)), mf(0), mf())
call msHold('on')
call msGetSliceXYZ(mfOut(stri,sx,sy,sz,sc), &
                 x, y, z, c, mf(),mf(),mf(-.75d0))
call msTriContour(stri,sx,sy,sz,sc)
call msHold('off')
call msViewPause()
call msFreeArgs(nx, ny, nz, x, y, z, c)
call msFreeArgs(stri,sx,sy,sz,sc)
end program example


Result
438      MATFOR 4 in Fortran Reference Guide




      See Also
      mfSliceIJK, mfSlicePlane, mfGetSliceXYZ
                                                               Chapter 9 Visualization Routines   439



mfSliceIJK, msSliceIJK
Display orthogonal slice-planes along the i, j or k indices.


Module
fgl


Syntax
handle = mfSliceIJK(x, y, z, c, Si, Sj, Sk)
handle = mfSliceIJK(c, Si, Sj, Sk)

call msSliceIJK(x, y, z, c, Si, Sj, Sk)
call mfSliceIJK(c, Si, Sj, Sk)



Descriptions
Procedure mfSliceIJK displays slice-planes along i, j and k which are index of x, index of
y and index of z respectively.

call msSliceIJK(x, y, z, c, Si, Sj, Sk)
• Displays slice-planes along arbitrary indices specified by mfArrays Si,Sj and Sk.
•   Use mf() to substitute any of the index vectors Si,Sj or Sk if you are not drawing any
    slice along the respective index. For example, call msSliceIJK(x, y, z, c, Si,
    mf(), Sk) draws slices along indices of x as specified by Si and z as specified by Sk.
•   Arguments x, y and z define the corresponding coordinates of volumetric data c, where
    c is an m-by-n-by-p three-dimensional array.
•   Arguments x, y and z must be of the same shape as c and be monotonic and
    three-dimensional plaid as if produced by procedure mfMeshgrid.

h = mfSliceIJK(c, Sx, Sy, Sz)
• Handle h retrieves a handle to the slice objects created by mfSliceIJK(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the slice objects through handle h with procedure msGSet.

The properties available are:

1. slicei: specifies indices of x.
2. slicej: specifies indices of y.
3. slicek: specifies indices of z.



Example
440      MATFOR 4 in Fortran Reference Guide



      Code
      program Example
      use fml
      use fgl
      implicit none
      type(mfArray) :: nu, nv, nw, u, v, w, x, y, z, c, h
      nu = mfLinspace(0, 1.5d0*MF_PI, 20)
      nv = mfLinspace(0, 2*MF_PI, 20)
      nw = mfLinspace(0, 1, 20)
      call msMeshGrid( mfOut(u, v, w), nu, nv, nw )
      x = ( 1 + 0.6d0 * mfCos(v) ) * mfCos(u)
      y = ( 1 + 0.6d0 * mfCos(v) ) * mfSin(u)
      z = w
      c = 1 - ( x ** 2 + y ** 2 + z ** 2)
      h = mfSliceIJK(x, y, z, c, mf((/4, 8, 12, 16/)), &
                  mf((/4, 8, 12, 16/)), mf((/8, 16/)))
      call msAxis('equal')
      !call msCamZoom(1.5d0)
      call msViewPause()
      call msFreeArgs(nu, nv, u, v, x, y, z, c, h)
      end program example


      Result




      See Also
                                                               Chapter 9 Visualization Routines   441



mfSlicePlane, msSlicePlane
Display orthogonal slice-planes along arbitrary directions.


Module
fgl


Syntax
handle = mfSlicePlane(x, y, z, c, plane)
handle = mfSlicePlane(c, plane)

call msSlicePlane(x, y, z, c, plane)
call msSlicePlane(c, plane)



Descriptions
Procedure mfSlice displays orthogonal slice-planes of a specified set of volumetric data
along an arbitrary direction. The information on the slice-planes can be retrieved by using
procedure msGetSlicePlane.

call msSlicePlane(x, y, z, c, plane)
• Displays orthogonal slice-planes along the direction specified by plane.
•   The arguments x, y and z are structured grid data which define the corresponding
    coordinates of scalar values specified in argument c, where c is an m-by-n-by-p
    three-dimensional array.
•   Argument plane is a vector of size 4 representing the coefficients of the sliced plane
    equation, i.e. [a, b, c, d], where ax + by + cz + d = 0.
•   The arguments x, y and z must be of the same shape as c and be monotonic and
    three-dimensional plaid as if produced by procedure mfMeshgrid.
•   The color at each point is determined by three-dimensional interpolation onto the
    elements of volume c, mapped to the current colormap.

call msSlicePlane(c, plane)
• Assumes x is composed of mfColon(1, n) vectors, y is composed of mfColon(1, m)
    vectors, and z is composed of mfColon(1, p) vectors.

h = mfSlicePlane(...)
• Handle h retrieves a handle to the volumetric slice objects created by
    mfSlicePlane(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.
442       MATFOR 4 in Fortran Reference Guide


      You can specify properties of the volumetric slice objects through handle h with procedure
      msGSet.

      The property available is:

      1. plane



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: nx, ny, nz, x, y, z, c
      type(mfArray) :: stri,sx,sy,sz,sc
      nx = mfLinspace(-2, 2.2d0, 21)
      ny = mfLinspace(-2, 2.25d0, 17)
      nz = mfLinspace(-1.5d0, 1.6d0, 31)
      call msMeshgrid(mfout(y, x, z), ny, nx, nz)
      c = 2*mfCos(x**2)*mfExp(-(y**2)-(z**2))
      call msSlicePlane(x, y, z, c, mf((/1, 0, -1, 0/)))
      call msHold('on')
      call msGetSlicePlane(mfOut(stri,sx,sy,sz,sc), &
                       x, y, z, c, mf((/1, 1, 0, 0/)))
      call msTriContour(stri,sx,sy,sz,sc)
      call msHold('off')
      call msViewPause()
      call msFreeArgs(nx, ny, nz, x, y, z, c)

      end program example


      Result
                           Chapter 9 Visualization Routines   443




See Also
mfSlice, mfGetSlicePlane
444       MATFOR 4 in Fortran Reference Guide



      msGetSliceXYZ
      Retrieve orthogonal slice-planes through volumetric data.


      Module
      fgl


      Syntax
      call msGetSliceXYZ(mfOut(tri,x,y,z,c), [x, y, z, ]c, Sx, Sy, Sz)



      Descriptions
      Procedure mfGetSliceXYZ retrieves orthogonal slice-planes of a specified set of
      volumetric data. It returns the triangular mesh tri and the vertex vectors of the sliced-planes
      defined in the n-by-3 matrix xyz.
      For details on the input arguments, refer to the description of procedure mfSliceXYZ.



      Example
      To be referred to mfSliceXYZ

      See Also
      mfSliceXYZ
                                                               Chapter 9 Visualization Routines   445



msGetSlicePlane
Retrieve orthogonal slice-planes along an arbitrary direction.


Module
fgl


Syntax
call msGetSlicePlane(mfOut(tri,x,y,z,c), [x, y, z,] c, planes)



Descriptions
Procedure mfGetSlicePlane retrieves orthogonal slice-planes of a specified set of
volumetric data along an arbitrary direction. It returns the triangular mesh tri and the vertex
vectors of the sliced-planes defined in the n-by-3 matrix xyz.

call msGetSlicePlane(mfOut(tri,x,y,z,c), x, y, z, c, planes)
• Retrieve the triangular mesh tri. With tri and the coordinates xyz, you may use
    mfTriSurf to plot the triangular surface.
•   The arguments x, y and z are structured grid data which define the corresponding
    coordinates of scalar values specified in argument c, where c is an m-by-n-by-p
    three-dimensional array.
•   Argument plane is a vector of size 4 representing the coefficients of the sliced plane
    equation, i.e. [a, b, c, d], where ax + by + cz + d = 0.
•   The arguments x, y and z must be of the same shape as c and be monotonic and
    three-dimensional plaid as if produced by procedure mfMeshgrid.

For details on the input arguments, refer to the description of procedure mfSlicePlane.



Example
To be referred to mfSlicePlane

See Also
mfSlicePlane
446     MATFOR 4 in Fortran Reference Guide




      Streamline Graphs
                                                          Chapter 9 Visualization Routines    447



mfStreamLine2, msStreamLine2
Create stream lines from two-dimensional vector data.


Module
fgl


Syntax
handle = mfStreamLine2(x, y, u, v, Sx, Sy)
handle = mfStreamLine2(u, v, Sx, Sy)

call msStreamLine2(x, y, u, v, Sx, Sy)
call msStreamLine2(u, v, Sx, Sy)



Descriptions
Procedure mfStreamLine2 creates stream lines from two-dimensional vector components
u and v .

call msStreamLine2(x, y, u, v, Sx, Sy)
• Arguments u and v are two-dimensional orthogonal vector components corresponding to
    the x- and y-directions respectively.
•   Arguments x and y define the coordinates for u and v and must be monotonic and
    two-dimensional plaid (as if produced by mfMeshgrid).
•   Arguments Sx and Sy define the starting positions of the stream lines.

call msStreamLine2(u, v, Sx, Sy)
• Arguments x and y are derived from mfMeshgrid(mfOut(x, y), mfColon(1,
    n), mfColon(1, m)), where n and m are dimensions of u.

h = mfStreamLine2(...)
• Handle h retrieves a handle to the stream lines created by mfStreamLine2(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the stream lines through handle h with procedure msGSet.

The properties available are:
1. start: an n-by-2 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream lines.
3. steplength: step length of the stream lines; the smaller the steplength is, the smoother
the stream lines are.
By default, MATFOR uses sizefactor=1 and steplength=0.5.
448      MATFOR 4 in Fortran Reference Guide



      Example

      Code
      program Example
         use fml
         use fgl
         implicit none
         type(mfArray) :: x, y, v, u, sx, sy
         type(mfArray) :: h, px, py
         px = mfLinspace( -2, 2, 20 )
         py = mfLinspace( -2, 2, 20 )
         call msMeshgrid( mfOut( x, y), px, py)
         u = mfSin( 2 * x * y )
         v = mfCos( 2 * x - y )
         sx = mfLinspace( -2, 2, 10 )
         sy = mfLinspace( 0, 0, 10 )
         call msSubplot(2,2,1)
         call msTitle("Stream Line")
         call msColormapRange(-2.d0,2.d0)
         h = mfStreamLine2(x, y, u, v, sx, sy)
         call msGSet( h, "steplength", 0.25d0 )
         call msSubplot(2,2,2)
         call msTitle("Stream Dashed Line")
         call msColormapRange(-2.d0,2.d0)
         h = mfStreamDashedLine2(x, y, u, v, sx, sy)
         call msGSet( h, "steplength", 0.25d0 )
         call msDrawMaterial(h,mf('surf'),mf('colormap'), &
                mf('off'),mf('color'),mf((/0,0,0/)))
         call msSubplot(2,2,3)
         call msTitle("Stream Ribbon")
         call msColormapRange(-2.d0,2.d0)
         h = mfStreamRibbon2(x, y, u, v, sx, sy)
         call msGSet( h, "steplength", 0.25d0 )
         call msGSet( h, "sizefactor", 0.02d0 )
         call msSubplot(2,2,4)
         call msTitle("Stream Tube")
         call msColormapRange(-2.d0,2.d0)
         h = mfStreamTube2(x, y, u, v, sx, sy)
         call msGSet( h, "steplength", 0.25d0 )
         call msGSet( h, "sizefactor", 0.01d0 )
         call msDrawMaterial(h,mf('surf'),mf('ambient'),mf(0), &
            mf('diffuse'),mf(100),mf('specular'),mf(0))
         call msViewPause()
         call msFreeArgs(x, y, v, u, h, px, py, sx, sy)
      end program Example


      Result
           Chapter 9 Visualization Routines   449




See Also
mfQuiver
450       MATFOR 4 in Fortran Reference Guide



      mfStreamDashedLine2, msStreamDashedLine2
      Create stream dashed-lines from two-dimensional vector data.


      Module
      fgl


      Syntax
      handle = mfStreamDashedLine2(x, y, u, v, Sx, Sy)
      handle = mfStreamDashedLine2(u, v, Sx, Sy)

      call msStreamDashedLine2(x, y, u, v, Sx, Sy)
      call msStreamDashedLine2(u, v, Sx, Sy)



      Descriptions
      Procedure mfStreamDashedLine2 creates stream dashed-lines from two-dimensional
      vector components u and v .

      call msStreamDashedLine2(x, y, u, v, Sx, Sy)
      • Arguments u and v are two-dimensional orthogonal vector components corresponding to
          the x- and y-directions respectively.
      •   Arguments x and y define the coordinates for u and v and must be monotonic and
          two-dimensional plaid (as if produced by mfMeshgrid).
      •   Arguments Sx and Sy define the starting positions of the stream dashed-lines.

      call msStreamDashedLine2(u, v, Sx, Sy)
      • Arguments x and y are derived from mfMeshgrid(mfOut(x, y), mfColon(1,
          n), mfColon(1, m)), where n and m are dimensions of u.

      h = mfStreamDashedLine2(...)
      • Handle h retrieves a handle to the stream dashed-lines created by
          mfStreamDashedLine2(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the stream dashed-lines through handle h with procedure
      msGSet.

      The properties available are:
      1. start: an n-by-2 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream dashed-lines.
      3. steplength: step length of the stream dashed-lines; the smaller the steplength is, the
      smoother the stream dashed-lines are.
                                             Chapter 9 Visualization Routines   451


By default, MATFOR uses sizefactor=1 and steplength=0.5.



Example
To be referred to mfStreamLine2

See Also
mfQuiver
452       MATFOR 4 in Fortran Reference Guide



      mfStreamRibbon2, msStreamRibbon2
      Create stream ribbons from two-dimensional vector data.


      Module
      fgl


      Syntax
      handle = mfStreamRibbon2(x, y, u, v, Sx, Sy)
      handle = mfStreamRibbon2(u, v, Sx, Sy)

      call msStreamRibbon2(x, y, u, v, Sx, Sy)
      call msStreamRibbon2(u, v, Sx, Sy)



      Descriptions
      Procedure mfStreamRibbon2 creates stream ribbons from two-dimensional vector
      components u and v .

      call msStreamRibbon2(x, y, u, v, Sx, Sy)
      • Arguments u and v are two-dimensional orthogonal vector components corresponding to
          the x- and y-directions respectively.
      •   Arguments x and y define the coordinates for u and v and must be monotonic and
          two-dimensional plaid (as if produced by mfMeshgrid).
      •   Arguments Sx and Sy define the starting positions of the stream ribbons.

      call msStreamRibbon2(u, v, Sx, Sy)
      • Arguments x and y are derived from mfMeshgrid(mfOut(x, y), mfColon(1,
          n), mfColon(1, m)), where n and m are dimensions of u.

      h = mfStreamRibbon2(...)
      • Handle h retrieves a handle to the stream ribbons created by
          mfStreamRibbon2(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the stream ribbons through handle h with procedure msGSet.

      The properties available are:
      1. start: an n-by-2 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream ribbons.
      3. steplength: step length of the stream ribbons; the smaller the steplength is, the
      smoother the stream ribbons are.
      By default, MATFOR uses sizefactor=1 and steplength=0.5.
                                  Chapter 9 Visualization Routines   453




Example
To be referred to mfStreamLine2

See Also
mfQuiver
454       MATFOR 4 in Fortran Reference Guide



      mfStreamTube2, msStreamTube2
      Create stream tubes from two-dimensional vector data.


      Module
      fgl


      Syntax
      handle = mfStreamTube2(x, y, u, v, Sx, Sy)
      handle = mfStreamTube2(u, v, Sx, Sy)

      call msStreamTube2(x, y, u, v, Sx, Sy)
      call msStreamTube2(u, v, Sx, Sy)



      Descriptions
      Procedure mfStreamTube2 creates stream tubes from two-dimensional vector components
      u and v .

      call msStreamTube2(x, y, u, v, Sx, Sy)
      • Arguments u and v are two-dimensional orthogonal vector components corresponding to
          the x- and y-directions respectively.
      •   Arguments x and y define the coordinates for u and v and must be monotonic and
          two-dimensional plaid (as if produced by mfMeshgrid).
      •   Arguments Sx and Sy define the starting positions of the stream tubes.

      call msStreamTube2(u, v, Sx, Sy)
      • Arguments x and y are derived from mfMeshgrid(mfOut(x, y), mfColon(1,
          n), mfColon(1, m)), where n and m are dimensions of u.

      h = mfStreamTube2(...)
      • Handle h retrieves a handle to the stream tubes created by mfStreamTube2(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the stream tubes through handle h with procedure msGSet.

      The properties available are:
      1. start: an n-by-2 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream tubes.
      3. steplength: step length of the stream tubes.
      By default, sizefactor=1 and steplength=0.5.
                                  Chapter 9 Visualization Routines   455


Example
To be referred to mfStreamLine2

See Also
mfQuiver
456       MATFOR 4 in Fortran Reference Guide



      mfStreamArrow2, msStreamArrow2
      Create stream arrows from two-dimensional vector data.


      Module
      fgl


      Syntax
      handle = mfStreamArrow2(x, y, u, v, Sx, Sy)
      handle = mfStreamArrow2(u, v, Sx, Sy)

      call msStreamArrow2(x, y, u, v, Sx, Sy)
      call msStreamArrow2(u, v, Sx, Sy)



      Descriptions
      Procedure mfStreamArrow2 creates stream arrows from two-dimensional vector
      components u and v .

      call msStreamArrow2(x, y, u, v, Sx, Sy)
      • Arguments u and v are two-dimensional orthogonal vector components corresponding to
          the x- and y-directions respectively.
      •   Arguments x and y define the coordinates for u and v and must be monotonic and
          two-dimensional plaid (as if produced by mfMeshgrid).
      •   Arguments Sx and Sy define the starting positions of the stream arrows.

      call msStreamArrow2(u, v, Sx, Sy)
      • Arguments x and y are derived from mfMeshgrid(mfOut(x, y), mfColon(1,
          n), mfColon(1, m)), where n and m are dimensions of u.

      h = mfStreamArrow2(...)
      • Handle h retrieves a handle to the stream arrows created by mfStreamArrow2(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the stream arrows through handle h with procedure msGSet.

      The properties available are:
      1. start: an n-by-2 matrix containing starting points coordinates.
      2. arrowsize: thickness of the stream arrows.
      3. arrowstep: step length of the stream arrows; the smaller the steplength is, the smoother
      the stream arrows are.
      By default, MATFOR uses arrowsize=1 and arrowstep=0.5.
                                              Chapter 9 Visualization Routines   457



Example

Code
program Example
   use fml
   use fgl
   implicit none
   type(mfArray) :: x, y, v, u, sx, sy
   type(mfArray) :: h, px, py
   px = mfLinspace( -2, 2, 20 )
   py = mfLinspace( -2, 2, 20 )
   call msMeshgrid( mfOut( x, y ), px, py )
   u = mfSin( 2 * x * y )
   v = mfCos( 2 * x - y )
   sx = mfLinspace( -1, 1, 10 )
   sy = mfLinspace( 0, 0, 10 )
    call msTitle("Stream Arrow")
    call msColormapRange(-2d0,2d0)
    h = mfStreamArrow2(x, y, u, v, sx, sy)
    call msGSet( h, "arrowsize", 0.15d0 )
    call msGSet( h, "arrowstep", 0.25d0 )
    call msHold("on")
    h = mfStreamTube2(x, y, u, v, sx, sy)
    call msGSet( h, "steplength", 0.25d0 )
    call msGSet( h, "sizefactor", 0.01d0)
    call msDrawMaterial(h,"surf","trans",70d0)
   call msViewPause()
   call msFreeArgs(x, y, v, u, h, px, py, sx, sy)
end program Example


Result




See Also
mfQuiver
458       MATFOR 4 in Fortran Reference Guide



      mfStreamLine, msStreamLine, mfStreamLine3,

      msStreamLine3
      Create stream lines from three-dimensional vector data.


      Module
      fgl


      Syntax
      handle = mfStreamLine(x, y, z, u, v, w, Sx, Sy, Sz)
      handle = mfStreamLine(u, v, w, Sx, Sy, Sz)

      call msStreamLine(x, y, z, u, v, w, Sx, Sy, Sz)
      call msStreamLine(u, v, w, Sx, Sy, Sz)



      Descriptions
      Procedure mfStreamLine creates stream lines from three-dimensional vector components
      u, v and w.

      call msStreamLine(x, y, z, u, v, w, Sx, Sy, Sz)
      • Arguments u, v and w are three-dimensional orthogonal vector components
          corresponding to the x-, y- and z- directions respectively.
      •   Arguments x, y and z define the coordinates for u, v and w and must be monotonic and
          three-dimensional plaid (as if produced by mfMeshgrid).
      •   Arguments Sx, Sy and Sz define the starting positions of the stream lines.

      call msStreamLine(u, v, w, Sx, Sy, Sz)
      • Arguments x, y and z are derived from mfMeshgrid(mfOut(x, y, z),
          mfColon(1, n), mfColon(1, m), mfColon(1, p)), where n, m and p are
          dimensions of u.

      h = mfStreamLine(...)
      • Handle h retrieves a handle to the stream lines created by mfStreamLine(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the stream lines through handle h with procedure msGSet.

      The properties available are:
      1. start: an n-by-3 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream lines.
                                                  Chapter 9 Visualization Routines   459


3. steplength: step length of the stream lines.
By default, sizefactor=1 and steplength=0.5.



Example

Code
program Example
   use fml
   use fgl
   implicit none
   type(mfArray) :: x, y, z, v, u, w, sx, sy, sz
   type(mfArray) :: h, px, py, pz
   px = mfLinspace( -2, 2, 20 )
   py = mfLinspace( -2, 2, 20 )
   pz = mfLinspace( -2, 2, 20 )
   call msMeshgrid( mfOut( x, y, z ), px, py, pz )
   u = mfSin( 2 * x * y * z )
   v = mfCos( 2 * x - y )
   w = mfCos( x + y - z )
   sx = mfLinspace( -2, 2, 10 )
   sy = mfLinspace( 0, 0, 10 )
   sz = mfLinspace( 0, 0, 10 )
   call msSubplot(2,2,1)
   call msTitle("Stream Line")
   call msColormapRange(-2.d0,2.d0)
   h = mfStreamLine(x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.25d0 )
   call msSubplot(2,2,2)
   call msTitle("Stream Dashed Line")
   call msColormapRange(-2.d0,2.d0)
   h = mfStreamDashedLine(x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.25d0 )
   call msDrawMaterial(h,mf('surf'),mf('colormap'), &
          mf('off'),mf('color'),mf((/0,0,0/)))
   call msSubplot(2,2,3)
   call msTitle("Stream Ribbon")
   call msColormapRange(-2.d0,2.d0)
   h = mfStreamRibbon(x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.25d0 )
   call msGSet( h, "sizefactor", 0.02d0 )
   call msSubplot(2,2,4)
   call msTitle("Stream Tube")
   call msColormapRange(-2.d0,2.d0)
   h = mfStreamTube(x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.25d0 )
   call msGSet( h, "sizefactor", 0.01d0 )
   call msDrawMaterial(h,mf('surf'),mf('ambient'),mf(0), &
      mf('diffuse'),mf(100),mf('specular'),mf(0))
   call msViewPause()
   call msFreeArgs(x, y, z, v, u, w, h, px, py, pz,sx, sy, sz)
end program Example


Result
460      MATFOR 4 in Fortran Reference Guide




      See Also
      mfQuiver, mfQuiver3
                                                            Chapter 9 Visualization Routines   461



mfStreamDashedLine, msStreamDashedLine,

mfStreamDashedLine3, msStreamDashedLine3
Create stream dashed-lines from three-dimensional vector data.


Module
fgl


Syntax
handle = mfStreamDashedLine(x, y, z, u, v, w, Sx, Sy, Sz)
handle = mfStreamDashedLine(u, v, w, Sx, Sy, Sz)

call msStreamDashedLine(x, y, z, u, v, w, Sx, Sy, Sz)
call msStreamDashedLine(u, v, w, Sx, Sy, Sz)



Descriptions
Procedure mfStreamDashedLine creates stream dashed-lines from three-dimensional
vector components u, v and w.

call msStreamDashedLine(x, y, z, u, v, w, Sx, Sy, Sz)
• Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to the x-, y- and z- direction respectively.
•   Arguments x, y and z define the coordinates for u, v and w and must be monotonic and
    three-dimensional plaid (as if produced by mfMeshgrid).
•   Arguments Sx, Sy and Sz define the starting positions of the stream dashed-lines.

call msStreamDashedLine(u, v, w, Sx, Sy, Sz)
• Arguments x, y and z are derived from mfMeshgrid(mfOut(x, y, z),
    mfColon(1, n), mfColon(1, m), mfColon(1, p)), where n, m and p are
    dimensions of u.

h = mfStreamDashedLine(...)
• Handle h retrieves a handle to the stream dashed-lines created by
    mfStreamDashedLine(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the stream dashed-lines through handle h with procedure
msGSet.
462       MATFOR 4 in Fortran Reference Guide


      The properties available are:
      1. start: an n-by-3 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream dashed-lines.
      3. steplength: step length of the stream dashed-lines.
      By default, sizefactor=1and steplength=0.5.



      Example
      To be referred to msStreamLine

      See Also
                                                            Chapter 9 Visualization Routines   463



mfStreamRibbon, msStreamRibbon, mfStreamRibbon3,

msStreamRibbon3
Create stream ribbons from three-dimensional vector data.


Module
fgl


Syntax
handle = mfStreamRibbon(x, y, z, u, v, w, Sx, Sy, Sz)
handle = mfStreamRibbon(u, v, w, Sx, Sy, Sz)

call msStreamRibbon(x, y, z, u, v, w, Sx, Sy, Sz)
call msStreamRibbon(u, v, w, Sx, Sy, Sz)



Descriptions
Procedure mfStreamRibbon creates stream ribbons from three-dimensional vector
components u, v and w.

call msStreamRibbon(x, y, z, u, v, w, Sx, Sy, Sz)
• Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to the x-, y- and z- direction respectively.
•   Arguments x, y and z define the coordinates for u, v and w and must be monotonic and
    three-dimensional plaid (as if produced by mfMeshgrid).
•   Arguments Sx, Sy and Sz define the starting positions of the stream ribbons.

call msStreamRibbon(u, v, w, Sx, Sy, Sz)
• Arguments x, y and z are derived from mfMeshgrid(mfOut(x, y, z),
    mfColon(1, n), mfColon(1, m), mfColon(1, p)), where n, m and p are
    dimensions of u.

h = mfStreamRibbon(...)
• Handle h retrieves a handle to the stream ribbons created by
    mfStreamRibbon(...).
•   Alternatively, you use procedure h = mfGetCurrentDraw() to retrieve the handle of
    the current graphics object.

You can specify properties of the stream ribbons through handle h with procedure msGSet.


The properties available are:
464       MATFOR 4 in Fortran Reference Guide


      1. start: an n-by-3 matrix containing starting points coordinates.
      2. sizefactor: thickness of the stream ribbons.
      3. steplength: step length of the stream ribbons.
      By default, sizefactor=1and steplength=0.5.



      Example
      To be referred to msStreamLine

      See Also
                                                             Chapter 9 Visualization Routines   465



mfStreamTube, msStreamTube, mfStreamTube3,

msStreamTube3
Create stream tubes from three-dimensional vector data.


Module
fgl


Syntax
handle = mfStreamTube(x, y, z, u, v, w, Sx, Sy, Sz)
handle = mfStreamTube(u, v, w, Sx, Sy, Sz)

call msStreamTube(x, y, z, u, v, w, Sx, Sy, Sz)
call msStreamTube(u, v, w, Sx, Sy, Sz)



Descriptions
Procedure mfStreamTube creates stream tubes from three-dimensional vector components
u, v and w.

call msStreamTube(x, y, z, u, v, w, Sx, Sy, Sz)
• Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to the x-, y- and z- direction respectively.
•   Arguments x, y and z define the coordinates for u, v and w and must be monotonic and
    three-dimensional plaid (as if produced by mfMeshgrid).
•   Arguments Sx, Sy and Sz define the starting positions of the stream tubes.

call msStreamTube(u, v, w, Sx, Sy, Sz)
• Arguments x, y and z are derived from mfMeshgrid(mfOut(x, y, z),
    mfColon(1, n), mfColon(1, m), mfColon(1, p)), where n, m and p are
    dimensions of u.

h = mfStreamTube(...)
• Handle h retrieves a handle to the stream tubes created by mfStreamTube(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the stream tubes through handle h with procedure msGSet.


The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
466       MATFOR 4 in Fortran Reference Guide


      2. sizefactor: thickness of the stream tubes.
      3. steplength: step length of the stream tubes.
      By default, sizefactor=1and steplength=0.5.



      Example
      To be referred to msStreamLine

      See Also
                                                             Chapter 9 Visualization Routines   467



mfStreamArrow, msStreamArrow, mfStreamArrow3,

msStreamArrow3
Create stream arrows from three-dimensional vector data.


Module
fgl


Syntax
handle = mfStreamArrow(x, y, z, u, v, w, Sx, Sy, Sz)
handle = mfStreamArrow(u, v, w, Sx, Sy, Sz)

call msStreamArrow(x, y, z, u, v, w, Sx, Sy, Sz)
call msStreamArrow(u, v, w, Sx, Sy, Sz)



Descriptions
Procedure mfStreamArrow creates stream arrows from three-dimensional vector
components u, v and w.

call msStreamArrow(x, y, z, u, v, w, Sx, Sy, Sz)
• Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to the x-, y- and z- direction respectively.
•   Arguments x, y and z define the coordinates for u, v and w and must be monotonic and
    three-dimensional plaid (as if produced by mfMeshgrid).
•   Arguments Sx, Sy and Sz define the starting positions of the stream arrows.

call msStreamArrow(u, v, w, Sx, Sy, Sz)
• Arguments x, y and z are derived from mfMeshgrid(mfOut(x, y, z),
    mfColon(1, n), mfColon(1, m), mfColon(1, p)), where n, m and p are
    dimensions of u.

h = mfStreamArrow(...)
• Handle h retrieves a handle to the stream arrows created by mfStreamArrow(...).
•   Alternatively, you use procedure h = mfGetCurrentDraw() to retrieve the handle of
    the current graphics object.

You can specify properties of the stream arrows through handle h with procedure msGSet.


The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
468      MATFOR 4 in Fortran Reference Guide


      2. arrowsize: thickness of the stream arrows.
      3. arrowstep: step length of the stream arrows.
      By default, arrowsize=1and arrowstep=0.5.

      Example
      Code
      program Example
         use fml
         use fgl
         implicit none
         type(mfArray) :: x, y, z, v, u, w, sx, sy, sz
         type(mfArray) :: h, px, py, pz
         px = mfLinspace( -2, 2, 20 )
         py = mfLinspace( -2, 2, 20 )
         pz = mfLinspace( -2, 2, 20 )
         call msMeshgrid( mfOut( x, y, z ), px, py, pz )
         u = mfSin( 2 * x * y * z )
         v = mfCos( 2 * x - y )
         w = mfCos( x + y - z )
         sx = mfLinspace( -1, 1, 10 )
         sy = mfLinspace( 0, 0, 10 )
         sz = mfLinspace( 0, 0, 10 )
          call msTitle("Stream Arrow")
          call msColormapRange(-2d0,2d0)
          h = mfStreamArrow(x, y, z, u, v, w, sx, sy, sz)
          call msGSet( h, "arrowsize", 0.15d0 )
          call msGSet( h, "arrowstep", 0.25d0 )
          call msHold("on")
          h = mfStreamTube(x, y, z, u, v, w, sx, sy, sz)
          call msGSet( h, "steplength", 0.25d0 )
          call msGSet( h, "sizefactor", 0.01d0)
          call msDrawMaterial(h,"surf","trans",70d0)
         call msViewPause()
         call msFreeArgs(x, y, z, v, u, w, h, px, py, pz,sx, sy, sz)
      end program Example

      Result




      See Also
Chapter 9 Visualization Routines   469
470     MATFOR 4 in Fortran Reference Guide




      Triangular Surface Graphs
                                                           Chapter 9 Visualization Routines   471



mfTriSurf, msTriSurf
Create polygonal surface plots.


Module
fgl


Syntax
handle = mfTriSurf(tri, x, y, z[, c])
handle = mfTriSurf(tri, xyz[, c])

call msTriSurf(tri, x, y, z[, c])
call msTriSurf(tri, xyz[, c])



Descriptions
Procedure mfTriSurf displays polygons defined by a face matrix. The polygons must be
convex polygons.

call msTriSurf(tri, x, y, z)
call msTriSurf(tri, x, y, z, c)
• Display the polygons defined by an m-by-n face matrix tri as a surface object, where m
    is the number of polygons to be drawn and n is the number of edges of each polygon. For
    example, a 4-by-3 face matrix tri draws a surface object of 4 triangles, while a 3-by-4
    face matrix tri draws a surface object of 3 quadrilaterals.
•   Each row of face matrix tri contains indices to x,y and z vertex vectors that define a
    single polygonal face.
•   As with procedure mfSurf, the color scale is assumed to be proportional to the surface
    height specified by vertex z.
•   Argument c overrides the default color specification and defines the new edge color.
•   The shapes of the four mfArrays x,y,z and c should be conformed.
•   Note that you can use mfSurf to plot the polygons and switch the shading mode using
    the toolbar function shading mode.

call msTriSurf(tri, xyz)
call msTriSurf(tri, xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTriSurf(...)
• Handle h retrieves a handle to the polygonal surface object created by
    mfTriSurf(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
472         MATFOR 4 in Fortran Reference Guide


          current graphics object.

      You can specify properties of the polygonal surface object through handle h with procedure
      msGSet.

      The properties available are:
      1. tri
      2. xyz

      Example
      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: tri, x, y, z, c
      x =    mfRand(400,1)
      y =    mfRand(400,1)
      z =    1 - ((x-0.5d0)**2 + (y-0.5d0)**2)
      c =    mfSin(z) * mfCos(z)
      tri    = mfGetDelaunay(x, y)
      call msTitle('msTriSurf')
      call msTriSurf(tri, x, y, z)
      call msViewPause()
      call msFreeArgs(tri, x, y, z, c)
      end program example

      Result




      See Also
      mfTriMesh
                                                           Chapter 9 Visualization Routines   473



mfTriMesh, msTriMesh
Create polygonal mesh plots.


Module
fgl


Syntax
handle = mfTriMesh(tri, x, y, z[, c])
handle = mfTriMesh(tri, xyz[, c])

call msTriMesh(tri, x, y, z[, c])
call msTriMesh(tri, xyz[, c])



Descriptions
Procedure mfTriMesh displays polygons in a mesh defined by a face matrix. The polygons
must be convex polygons.

call msTriMesh(tri, x, y, z)
call msTriMesh(tri, x, y, z, c)
• Display the polygons defined by an m-by-n face matrix tri as a meshed surface object,
    where m is the number of polygons to be drawn and n is the number of edges of each
    polygon. For example, a 4-by-3 face matrix tri draws a surface object of 4 triangles,
    while a 3-by-4 face matrix tri draws a surface object of 3 quadrilaterals.
•   Each row of face matrix tri contains indices to x,y and z vertex vectors that define a
    single polygonal face.
•   As with the procedure mfSurf, the color scale is assumed to be proportional to the
    surface height specified by vertex z.
•   Argument c overrides the default color specification and defines the new edge color.
•   The shapes of the four mfArrays x,y,z and c should be conformed.
•   Note that you can use mfMesh to plot the polygons and switch the shading mode using
    the toolbar function shading mode.

call msTriMesh(tri, xyz)
call msTriMesh(tri, xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTriMesh(...)
• Handle h retrieves a handle to the polygonal meshed surface object created by
    mfTriMesh.
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
474         MATFOR 4 in Fortran Reference Guide


          current graphics object.

      You can specify properties of the polygonal meshed surface object through handle h with
      procedure msGSet.

      The properties available are:
      1. tri
      2. xyz

      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: tri, x, y, z, c
      x =    mfRand(400,1)
      y =    mfRand(400,1)
      z =    1 - ((x-0.5d0)**2 + (y-0.5d0)**2)
      c =    mfSin(z) * mfCos(z)
      tri    = mfGetDelaunay(x, y)
      call msTitle('msTriMesh')
      call msTriMesh(tri, x, y, z)
      call msViewPause()
      call msFreeArgs(tri, x, y, z, c)
      end program example


      Result




      See Also
      mfTriSurf
                                                          Chapter 9 Visualization Routines    475



mfTriContour, msTriContour
Create contours on polygonal plots.


Module
fgl


Syntax
handle = mfTriContour(tri, x, y, z[, c])
handle = mfTriContour(tri, xyz[, c])

call msTriContour(tri, x, y, z[, c])
call msTriContour(tri, xyz[, c])



Descriptions
Procedure mfTriSurface plots contour lines of matrix z on the polygons defined by a face
matrix. The polygons must be convex polygons.

call msTriContour(tri, x, y, z)
call msTriContour(tri, x, y, z, c)
• Generate contour lines on the polygons for selected scalar values. The values plotted are
    selected automatically.
•   As with procedures mfTriSurf and mfTriMesh, the polygons are defined by an
    m-by-n face matrix tri. Each row of face matrix tri contains indices to x, y and z
    vertex vectors that define a single polygonal face.
•   As with the Surface Graphs procedures, the color scale is assumed to be proportional to
    the surface height specified by vertex z.
•   Argument c overrides the default edge color specification, and defines the new edge
    color.
•   The shapes of the four mfArrays x, y, z and c should be conformed.

call msTriContour(tri, xyz)
call msTriContour(tri, xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTriContour(...)
• Handle h retrieves a handle to the contour line objects created by
    mfTriContour(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the contour line objects through handle h with procedure
476         MATFOR 4 in Fortran Reference Guide


      msGSet.

      The properties available are:

      1. tri
      2. xyz
      3. iso: iso-values, a vector containing iso-value set. Setting this property will replace default
      set of contour lines.
      4. autolevel: given number of levels, it will generate the iso-value set automatically. 5.
      clipping: "on" or "off"6. Label: "on" or "off"



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: tri, x, y, z, c,h
      x =    mfRand(400, 1)
      y =    mfRand(400, 1)
      z =    1 - ((x-0.5d0)**2 + (y-0.5d0)**2)
      c =    mfSin(z) * mfCos(z)
      tri    = mfGetDelaunay(x, y)
      call msSubplot(1,2,1)
      call msTriContour(tri, x, y, z, c)
      call msTitle('TriContour')
      call msSubplot(1,2,2)
      h=mfTriContour(tri, x, y, z, c)
      call msGSet(h,'label','on')
      call msGSet(h,'iso',mf((/0.46d0,0.47d0,0.48d0,0.49d0/)))
      call msGSet(h,'clipping','on')
      call msTitle('TriContour with clipping')
      call msViewPause()
      call msFreeArgs(tri, x, y, z, c, h)
      end program example


      Result
            Chapter 9 Visualization Routines   477




See Also
mfTriMesh
478       MATFOR 4 in Fortran Reference Guide



      mfPatch, msPatch
      Add patches on 2-D or 3-D coordinates.


      Module
      fgl


      Syntax
      handle = mfPatch(x, y, c)
      handle = mfPatch(x, y, z, c)

      call msPatch(x, y, c)
      call msPatch(x, y, z, c)



      Descriptions
      Procedure mfPatch adds a patch (filled 2-D polygon) on the coordinates specified by
      arguments x and y. Notice that only convex polygons can be accepted.

      call msPatch(x, y)
      call msPatch(x, y, c)
      • Add patches on the vertices defined by arguments x and y.
      •   If arguments x and y are matrices, then each column defines a single patch.
      •   Argument c defines the color scale for the vertices that determine the interior color of the
          patch.
      •   The shapes of the three mfArrays x,y and c should be conformed.

      call msPatch(x, y, z)
      call msPatch(x, y, z, c)
      • Add patches on the 3-D coordinates defined by arguments x,y and z.
      •   If x,y and z are matrices of the same size, then each column defines a single patch.
      •   The color scale is assumed to be proportional to the surface height specified by vertex z
          and is used to determine the interior color of the added patch.
      •   If argument c is defined, it overrides the default color specification and defines the new
          color scale for the vertices.
      •   The shapes of the four mfArrays x,y,z and c should be conformed.



      Example

      Code
      program example
      use fml
      use fgl
                                              Chapter 9 Visualization Routines   479

implicit none
type (mfArray) :: x, y, c, h
real(8) :: p, q
p = 0.5d0*sqrt(3.0d0)
q = 1.5d0
x = (/0.0d0, p, p, 0.0d0, -p, -p /) .vc. &
   (/2*p, 3*p, 3*p, 2*p, p, p    /) .vc. &
   (/4*p, 5*p, 5*p, 4*p, 3*p, 3*p/) .vc. &
    (/p, 2*p, 2*p, p, 0.0d0, 0.0d0/) .vc. &
   (/3*p, 4*p, 4*p, 3*p, 2*p, 2*p/) .vc. &
   (/p, 2*p, 2*p, p, 0.0d0, 0.0d0/) .vc. &
   (/3*p, 4*p, 4*p, 3*p, 2*p, 2*p/)
y = (/-1.0d0, -0.5d0, 0.5d0, 1.0d0, 0.5d0, -0.5d0/) .vc. &
   (/-1.0d0, -0.5d0, 0.5d0, 1.0d0, 0.5d0, -0.5d0/) .vc. &
    (/-1.0d0, -0.5d0, 0.5d0, 1.0d0, 0.5d0, -0.5d0/) .vc. &
   (/-1.0d0+q, -0.5d0+q, 0.5d0+q, 1.0d0+q, 0.5d0+q, -0.5d0+q/) .vc. &
   (/-1.0d0+q, -0.5d0+q, 0.5d0+q, 1.0d0+q, 0.5d0+q, -0.5d0+q/) .vc. &
   (/-1.0d0-q, -0.5d0-q, 0.5d0-q, 1.0d0-q, 0.5d0-q, -0.5d0-q/) .vc. &
   (/-1.0d0-q, -0.5d0-q, 0.5d0-q, 1.0d0-q, 0.5d0-q, -0.5d0-q/)
c = (/1, 1, 1, 1, 1, 1/) .vc. &
   (/2, 2, 2, 2, 2, 2/) .vc. &
   (/3, 3, 3, 3, 3, 3/) .vc. &
    (/4, 4, 4, 4, 4, 4/) .vc. &
    (/5, 5, 5, 5, 5, 5/) .vc. &
    (/6, 6, 6, 6, 6, 6/) .vc. &
    (/7, 7, 7, 7, 7, 7/)
x = .t. x
y = .t. y
c = .t. c
h = mfPatch(x, y, c)
call msView('2')
call msAxis('equal')
call msViewPause()
call msFreeArgs(x, y, c, h)
end program example


Result




See Also
480     MATFOR 4 in Fortran Reference Guide




      Unstructured Grids
                                                           Chapter 9 Visualization Routines   481



mfTetSurf, msTetSurf
Create polyhedral surface plots.


Module
fgl


Syntax
handle = mfTetSurf(tet, x, y, z[, c])
handle = mfTetSurf(tet, xyz[, c])

call msTetSurf(tet, x, y, z[, c])
call msTetSurf(tet, xyz[, c])



Descriptions
Procedure mfTetSurf displays polyhedrons defined by a cell matrix.

call msTetSurf(tet, x, y, z)
call msTetSurf(tet, x, y, z, c)
• Display the polyhedrons defined by an m-by-k cell matrix tet as a polyhedral object,
    where m is the number of polyhedrons to be drawn. There are four different types of
    polyhedrons depending on the value of k, as illustrated below.


                                                                       5
                                        4
                                                                                  3
                            3                                    4
                                            2

                                                                                      2
                                1                                     1
                        Tetrahedron (k=4)                             Pyramid (k=5)

                                    6                                                 7
                                                                          8
                                                                                  6
                                        5   3                    5
                        4
                                                                              4           3

                                                2                                     2
                                    1                                 1
                            Wedge (k=6)                              Hexahedron (k=8)
482           MATFOR 4 in Fortran Reference Guide



      •   Each row of cell matrix tet contains indices to x,y and z vertex vectors that define a
          single polyhedron.
      •   As with procedure mfSurf, the edge color is assumed to be proportional to the surface
          height specified by vertex z.
      •   Argument c overrides the default color specification.
      •   The shapes of the four mfArrays x,y,z and c should be conformed.
      •   Note that you can use either mfTetSurf or mfTetMesh to plot the polygons and
          switch the shading mode using the toolbar function shading mode.

      call msTetSurf(tet, xyz)
      call msTetSurf(tet, xyz, c)
      • Vertex vectors are defined in the n-by-3 matrix xyz where n is the number of vertices.

      h = mfTetSurf(...)
      • Handle h retrieves a handle to the polyhedral object created by mfTetSurf(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the polyhedral object through handle h with procedure
      msGSet.

      The properties available are:

      1. tet
      2. xyz



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: tet, x, y, z, c
      x   =    mfRand(500,1)
      y   =    mfRand(500,1)
      z   =    mfRand(500,1)
      c   =    1 - ((x - 0.5d0) ** 2 + (y - 0.5d0) ** 2 + (z - 0.5d0) ** 2)
      tet = mfGetDelaunay3(x, y, z)
      call msTetSurf(tet, x, y, z)
      call msViewPause()
      call msFreeArgs(tet, x, y, z, c)
      end program example
            Chapter 9 Visualization Routines   483



Result




See Also
mfTetMesh
484       MATFOR 4 in Fortran Reference Guide



      mfTetMesh, msTetMesh
      Create polyhedral mesh plots.


      Module
      fgl


      Syntax
      handle = mfTetMesh(tet, x, y, z[, c])
      handle = mfTetMesh(tet, xyz[, c])



      Descriptions
      Procedure mfTetMesh displays polyhedrons defined by a cell matrix.

      call msTetMesh(tet, x, y, z)
      call msTetMesh(tet, x, y, z, c)
      • Display the polyhedrons defined by an m-by-k cell matrix tet as a meshed polyhedral
          object, where m is the number of polyhedrons to be drawn. There are four different types
          of polyhedrons depending on the value of k as illustrated below.


                                                                             5
                                               4
                                                                                         3
                                   3                                   4
                                                   2

                                                                                             2
                                       1                                     1
                               Tetrahedron (k=4)                             Pyramid (k=5)

                                           6                                                 7
                                                                                 8
                                                                                         6
                                               5   3                   5
                               4
                                                                                     4           3

                                                       2                                     2
                                           1                                 1
                                   Wedge (k=6)                             Hexahedron (k=8)




      •   Each row of cell matrix tet contains indices to x,y and z vertex vectors that define a
          single polyhedron.
                                                          Chapter 9 Visualization Routines   485


•   As with procedure mfTetMesh,the edge color is assumed to be proportional to the
    surface height specified by vertex z.
•   Argument c overrides the default color specification and defines the new edge color.
•   The shapes of the four mfArrays x,y,z and c should be conformed.
•   Note that you can use either mfTetSurf or mfTetMesh to plot the polygons and
    switch the shading mode using the toolbar function shading mode.

call msTetMesh(tet, xyz) call msTetMesh(tet, xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTetMesh(...)
• Handle h retrieves a handle to the polyhedral object created by mfTetMesh(...).
•   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
    current graphics object.

You can specify properties of the polyhedral object through handle h with procedure
msGSet.

The properties available are:

1. tet
2. xyz



Example

See Also
mfTetSurf
486       MATFOR 4 in Fortran Reference Guide



      mfTetContour, msTetContour
      Create contours on polyhedral plots.


      Module
      fgl


      Syntax
      handle = mfTetContour(tet, x, y, z[, c])
      handle = mfTetContour(tet, xyz[, c])

      call msTetContour(tet, x, y, z[, c])
      call msTetContour(tet, xyz[, c])



      Descriptions
      Procedure mfTetSurface plots contour lines on the surface of the polyhedral object
      defined by a face matrix.

      call msTetContour(tet, x, y, z)
      call msTetContour(tet, x, y, z, c)
      • Display the polyhedrons defined by an m-by-k cell matrix tet as a meshed polyhedral
          object, where m is the number of polyhedrons to be drawn. There are four different types
          of polyhedrons depending on the value of k as illustrated below.

                                                                             5
                                              4
                                                                                         3
                                  3                                    4
                                                  2

                                                                                             2
                                      1                                      1
                              Tetrahedron (k=4)                              Pyramid (k=5)

                                          6                                                  7
                                                                                 8
                                                                                         6
                                              5   3                    5
                              4
                                                                                     4           3

                                                      2                                      2
                                          1                                  1
                                  Wedge (k=6)                              Hexahedron (k=8)
                                                            Chapter 9 Visualization Routines        487



•   Generate contour lines of matrix z on the surface of the polyhedral object for selected
    scalar values. The values plotted are selected automatically.
•   Similar to procedures mfTetSurf and mfTetMesh,the polyhedral object is the
    combination of the polyhedrons defined by a m-by-n face matrix tet.Each row of face
    matrix tet contains indices into x,y and z vertex vectors to define a single polyhedron.
•   The color scale is assumed to be proportional to the surface height specified by vertex z.
•   Argument c overrides the default color specification and defines the new edge color.
•   The shapes of the four mfArrays x,y,z and c should be conformed.

call msTetContour(tet, xyz)
call msTetContour(tet, xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfTetContour(...)
• Handle h retrieves a handle to the contour line objects created by
    mfTetContour(...).
•   Alternatively, use procedure h = mfGetCurrentDraw()to retrieve the handle of the
    current graphics object.

You can specify properties of the contour line objects through handle h with procedure
msGSet.

The properties available are:

1. tet
2. xyz
3. iso: iso-values, a vector containing iso-value set. Setting this property will replace default
set of contour lines.
4. autolevel: given number of levels, it will generate the iso-value set automatically.
5. clipping: "on" or "off"
6. label " "on" or "off"

Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: tet, x, y, z, c, h
x   =   mfRand(500,1)
y   =   mfRand(500,1)
z   =   mfRand(500,1)
c   =   1 - ((x - 0.5d0) ** 2 + (y - 0.5d0) ** 2 + (z - 0.5d0) ** 2)
tet = mfGetDelaunay3(x, y, z)
488      MATFOR 4 in Fortran Reference Guide


      h = mfTetContour(tet, x, y, z, c)
      call msGSet(h,'label','on')
      call msViewPause()
      call msFreeArgs(tet, x, y, z, c, h)
      end program example


      Result




      See Also
      mfTetMesh
                                                          Chapter 9 Visualization Routines     489



mfTetIsoSurface, msTetIsoSurface
Create polyhedral isosurface plots.


Module
fgl


Syntax
handle = mfTetIsoSurface(tet, x, y, z, c, isovalue)
handle = mfTetIsoSurface(tet, xyz, c, isovalue)

call msTetIsoSurface(tet, x, y, z, c, isovalue)
call msTetIsoSurface(tet, xyz, c, isovalue)



Descriptions
Procedure mfTetIsoSurface creates 3-D graphs composed of isosurface data from the
polyhedral data c at the isosurface value specified in argument isovalue.

call msTetIsoSurface(x, y, z, c, isovalue)
• Display the polyhedrons defined by a m-by-k cell matrix tet as a meshed polyhedral
    object, where m is the number of polyhedrons to be drawn. There are four different types
    of polyhedrons depending on the value of k as illustrated below.


                                                                       5
                                        4
                                                                                   3
                            3                                    4
                                            2

                                                                                       2
                                1                                      1
                        Tetrahedron (k=4)                              Pyramid (k=5)

                                    6                                                  7
                                                                           8
                                                                                   6
                                        5   3                    5
                        4
                                                                               4           3

                                                2                                      2
                                    1                                  1
                            Wedge (k=6)                              Hexahedron (k=8)
490           MATFOR 4 in Fortran Reference Guide



      •   The arguments x,y and z define the coordinates for the volume c.

      h = mfTetIsoSurface(...)
      • Handle h retrieves a handle to the isosurface object created by
          mfTetIsoSurface(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the isosurface object through handle h with procedure msGSet.

      The properties available are:

      1. iso: iso-value, a vector containing iso-value sets.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: tet, x, y, z, c
      type(mfArray) :: g_tri,g_x,g_y,g_z,g_c,v2,h
      x   =    mfRand(500,1)
      y   =    mfRand(500,1)
      z   =    mfRand(500,1)
      c   =    1 - ((x - 0.5d0) ** 2 + (y - 0.5d0) ** 2 + (z - 0.5d0) ** 2)
      tet = mfGetDelaunay3(x, y, z)
      call msSubplot(1,2,1)
      call msTetIsoSurface(tet, x, y, z, c, mf((/0.8d0, 0.7d0, 0.6d0/)))
      call msColorbar('on')
      call msSubplot(1,2,2)
      !Get IsoSurface data and draw it.
      call msGetTetIsoSurface(mfOut(g_tri,g_x,g_y,g_z,g_c),&
             tet, x, y, z, c, mf(0.75d0))
      v2 = 1 - ((g_x - 0.5d0) ** 2 + (g_y - 0.5d0) ** 2 - (g_z - 0.5d0) ** 2)
      h = mfTriSurf(g_tri,g_x,g_y,g_z,v2)
      call msDrawMaterial(h, mf('edge'),mf('visible'),mf('off'))
      call msDrawMaterial(h,mf('surf'),mf('smooth'),mf('on'),&
                       mf('ambient'),mf(0),&
                       mf('diffuse'),mf(100),&
                       mf('specular'),mf(0))
      call msColorbar('on')
      call msViewPause()
      call msFreeArgs(tet, x, y, z, c)
      call msFreeArgs(g_tri,g_x,g_y,g_z,g_c,v2,h)
      end program example


      Result
           Chapter 9 Visualization Routines   491




See Also
492       MATFOR 4 in Fortran Reference Guide



      mfTetSliceXYZ, msTetSliceXYZ
      Display orthogonal slice-planes through volumetric data.


      Module
      fgl


      Syntax
      handle = mfTetSliceXYZ(tet, x, y, z, c, Sx, Sy, Sz)
      handle = mfTetSliceXYZ(tet, xyz, c, Sx, Sy, Sz)

      call msTetSliceXYZ(tet, x, y, z, c, Sx, Sy, Sz)
      call msTetSliceXYZ(tet, xyz, c, Sx, Sy, Sz)



      Descriptions
      Procedure mfTetSliceXYZ displays orthogonal slice-planes of a specified set of
      polyhedral data. The information on the slice-planes can be retrieved by using procedure
      mfGetTetSliceXYZ.

      call msTetSliceXYZ(tet, x, y, z, c, Sx, Sy, Sz)
      • Display the polyhedrons defined by an m-by-k cell matrix tet as a meshed polyhedral
          object, where m is the number of polyhedrons to be drawn. There are four different types
          of polyhedrons depending on the value of k as illustrated below.

                                                                             5
                                              4
                                                                                         3
                                  3                                    4
                                                  2

                                                                                             2
                                      1                                      1
                              Tetrahedron (k=4)                              Pyramid (k=5)

                                          6                                                  7
                                                                                 8
                                                                                         6
                                              5   3                    5
                              4
                                                                                     4           3

                                                      2                                      2
                                          1                                  1
                                  Wedge (k=6)                              Hexahedron (k=8)
                                                               Chapter 9 Visualization Routines   493



•   Displays orthogonal slice-planes along the x, y and z directions specified by points in
    vector mfArrays Sx,Sy and Sz
•   Use mf() to substitute any of the direction vectors Sx, Sy or Sz if you are not drawing
    any slice along the respective direction. E.g. call msSliceXYZ(x, y, z, v, Sx, mf(), Sz)
    draws slices along the x-axis as specified by Sx and z-axis as specified by Sz.
•   The arguments x,y and z define the corresponding coordinates of scalar values mfArray
    c, where c is an m-by-n-by-p three-dimensional array.
•   The arguments x,y and z must be of the same shape as c and are monotonic and
    three-dimensional plaid as if produced by procedure mfMeshgrid.
•   The color at each point is determined by three-dimensional interpolation into the elements
    of volume c, mapped to the current colormap.

call msTetSliceXYZ(tet, xyz, c, Sx, Sy, Sz)
• Vertex vectors are defined in the n-by-3 matrix xyz where n is the number of vertices.

h = mfTetSliceXYZ(...)
• Handle h retrieves a handle to the volumetric slice object created by
    mfTetSliceXYZ(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the volumetric slice objects through handle h with procedure
msGSet.

The properties available are:

1. tet
2. slicex: specifies the slice-planes along the x direction.
3. slicey: specifies the slice-planes along the y direction.
4. slicez: specifies the slice-planes along the z direction.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: nx, ny, nz, x, y, z, c, tet
type(mfArray) :: stri,sx,sy,sz,sc
nx = mfLinspace(-2, 2.2d0, 21)
ny = mfLinspace(-2, 2.25d0, 17)
nz = mfLinspace(-1.5d0, 1.6d0, 31)
call msMeshgrid(mfout(y, x, z), ny, nx, nz)
494      MATFOR 4 in Fortran Reference Guide

      c = 2*mfCos(x**2)*mfExp(-(y**2)-(z**2))
      tet = mfGetDelaunay3(x, y, z);
      call msTetSliceXYZ(tet, x, y, z, c, mf((/-1.0d0, 1.0d0/)), &
                   mf(0), mf())
      call msHold('on')
      call msGetTetSliceXYZ(mfOut(stri,sx,sy,sz,sc), &
                       tet, x, y, z, c, mf(),mf(),mf(-.75d0))
      call msTriContour(stri,sx,sy,sz,sc)
      call msHold('off')
      call msViewPause()
      call msFreeArgs(nx, ny, nz, x, y, z, c)
      call msFreeArgs(stri,sx,sy,sz,sc)
      end program example


      Result




      See Also
      mfTetSlicePlane, mfTetIsoSurface, msGetTetSliceXYZ
                                                           Chapter 9 Visualization Routines       495



mfTetSlicePlane, msTetSlicePlane
Display orthogonal slice-planes along an arbitrary direction.


Module
fgl


Syntax
handle = mfTetSlicePlane(tet, x, y, z, c, plane)
handle = mfTetSlicePlane(tet, xyz, c, plane)

call msTetSlicePlane(tet, x, y, z, c, plane)
call msTetSlicePlane(tet, xyz, c, plane)



Descriptions
Procedure mfTetSlicePlane displays orthogonal slice-planes of a specified set of
polyhedral data along arbitrary direction. The information on the slice-planes can be retrieved
by using procedure mfGetTetSlicePlane.

call msTetSlicePlane(tet, x, y, z, c, plane)
• Display the polyhedrons defined by an m-by-k cell matrix tet as a meshed polyhedral
    object, where m is the number of polyhedrons to be drawn. There are four different types
    of polyhedrons depending on the value of k as illustrated below.

                                                                       5
                                        4
                                                                                   3
                            3                                    4
                                            2

                                                                                       2
                                1                                      1
                        Tetrahedron (k=4)                              Pyramid (k=5)

                                    6                                                  7
                                                                           8
                                                                                   6
                                        5   3                    5
                        4
                                                                               4           3

                                                2                                      2
                                    1                                  1
                            Wedge (k=6)                              Hexahedron (k=8)
496       MATFOR 4 in Fortran Reference Guide



      •   Displays orthogonal slice-planes along the direction specified by plane.
      •   The arguments x,y and z are structured grid data which define the corresponding
          coordinates of scalar values specified in argument c, where c is a m-by-n-by-p
          three-dimensional array.
      •   Argument plane is a vector of size 4 representing the coefficients of the sliced plane
          equation, i.e. [a, b, c, d], where ax + by + cz + d = 0.
      •   The arguments x,y and z must be of the same shape as c and are monotonic and
          three-dimensional plaid as if produced by procedure mfMeshgrid.
      •   The color at each point is determined by three-dimensional interpolation into the elements
          of volume c, mapped to the current colormap.

      call msTetSlicePlane(tet, xyz, c, plane)
      • Vertex vectors are defined in the n-by-3 matrix xyz where n is the number of vertices.

      h = mfTetSlicePlane(...)
      • Handle h retrieves a handle to the volumetric slice objects created by
          mfTetSlicePlane(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the volumetric slice objects through handle h with procedure
      msGSet.
      The properties available are:
      1. tet
      2. plane



      Example

      Code
      program Example_msTetSlicePlane
      use fml
      use fgl
      implicit none
      type(mfArray) :: nx, ny, nz, x, y, z, c, tet
      type(mfArray) :: stri,sx,sy,sz,sc
      nx = mfLinspace(-2, 2.2d0, 21)
      ny = mfLinspace(-2, 2.25d0, 17)
      nz = mfLinspace(-1.5d0, 1.6d0, 31)
      call msMeshgrid(mfout(y, x, z), ny, nx, nz)
      c = 2*mfCos(x**2)*mfExp(-(y**2)-(z**2))
      tet = mfGetDelaunay3(x, y, z)
      call msTetSlicePlane(tet, x, y, z, c, mf((/1, 0, -1, 0/)))
      call msHold('on')
      call msGetTetSlicePlane(mfOut(stri,sx,sy,sz,sc), &
                                                    Chapter 9 Visualization Routines   497

                 tet, x, y, z, c, mf((/1, 1, 0, 0/)))
call msTriContour(stri,sx,sy,sz,sc)
call msHold('off')
call msViewPause()
call msFreeArgs(nx, ny, nz, x, y, z, c, tet)

end program Example_msTetSlicePlane


Result




See Also
mfSlicePlane, mfGetSlicePlane, mfGetTetSlicePlane
498       MATFOR 4 in Fortran Reference Guide



      msGetTetIsoSurface
      Retrieve three-dimensional iso-value surface plots from polyhedral data.


      Module
      fgl


      Syntax
      call msGetTetIsoSurface(mfOut(tri,x,y,z,c),tet, xyz, c, iso)
      call msGetTetIsoSurface(mfOut(tri,xyz,c),tet, x, y, z, c, iso)



      Descriptions
      Procedure mfGetTetIsoSurface retrieves 3-D graphs composed of isosurface data from
      the data c. It returns the triangular mesh tri and the vertex vectors of isosurface defined in
      the n-by-3 matrix xyz.
      For details on the input arguments, please refer to the description of procedure
      mfTetIsoSurface.



      Example
      To be referred to mfTetIsoSurface

      See Also
      mfTetIsoSurface
                                                            Chapter 9 Visualization Routines      499



msGetTetSliceXYZ
Retrieve orthogonal slice-planes through polyhedral data.


Module
fgl


Syntax
call msGetTetSliceXYZ(mfOut(tri,x,y,z,c), tet, x, y, z, c, Sx, Sy, Sz)



Descriptions
Procedure mfGetTetSliceXYZ retrieves orthogonal slice-planes of a specified set of
polyhedral data. It returns the triangular mesh tri and the vertex vectors of the sliced-planes
defined in the n-by-3 matrix xyz.
For details on the input arguments, refer to the description of procedure mfTetSliceXYZ.



Example
To be referred to mfTetSliceXYZ

See Also
mfTetSliceXYZ
500       MATFOR 4 in Fortran Reference Guide



      msGetTetSlicePlane
      Retrieve orthogonal slice-planes along an arbitrary direction.


      Module
      fgl


      Syntax
      call msGetTetSlicePlane(mfOut(tri,x,y,z,c), tet, x, y, z, c, planes)



      Descriptions
      Procedure mfGetTetSlicePlane retrieves orthogonal slice-planes of a specified set of
      polyhedral data along an arbitrary direction. It returns the triangular mesh tri and the vertex
      vectors of the sliced-planes defined in the n-by-3 matrix xyz.

      call msGetTetSlicePlane(mfOut(tri,x,y,z,c), x, y, z, c, planes)
      • Retrieve the triangular mesh tri. With tri and the coordinates xyz, you may use
          mfTriSurf to plot the triangular surface.
      •   The arguments x, y and z are structured grid data which define the corresponding
          coordinates of scalar values specified in argument c, where c is an m-by-n-by-p
          three-dimensional array.
      •   Argument plane is a vector of size 4 representing the coefficients of the sliced plane
          equation, i.e. [a, b, c, d], where ax + by + cz + d = 0.
      •   The arguments x, y and z must be of the same shape as c and be monotonic and
          three-dimensional plaid as if produced by procedure mfMeshgrid.

      For details on the input            arguments,    refer   to   the   description   of   procedure
      mfTetSlicePlane.



      Example
      To be referred to mfTetSlicePlane

      See Also
      mfTetSlicePlane
                           Chapter 9 Visualization Routines   501




Unstructured Streamlines
502       MATFOR 4 in Fortran Reference Guide



      mfTriStreamLine, msTriStreamLine
      Create streamlines from two-dimensional unstructured mesh data.


      Module
      fgl


      Syntax
      handle = mfTriStreamline(tri, x, y, u, v, Sx, Sy)
      handle = mfTriStreamline(tri, xy, uv, Sxy)

      call msTriStreamline(tri, x, y, u, v, Sx, Sy)
      call msTriStreamline(tri, xy, uv, Sxy)



      Descriptions
      Procedure mfTriStreamLine creates streamlines from two-dimensional unstructured
      mesh data.

      handel = mfTriStreamLine(tri, x, y, u, v, Sx, Sy)
      • Argument tri is an m-by-n face matrix, where m is the number of polygons and n is the
          number of edges on each polygon. For example; a 4-by-3 face matrix tri draws a
          streamline object of 4 triangles, while a 3-by-4 face matrix tri draws a streamline object
          of 3 quadrilaterals.
      •   Arguments x and y are n-by-1 vectors contain the x- and y- coordinates of the respective
          points.
      •   Arguments u and w are two-dimensional orthogonal vector components corresponding to
          the x- and y- directions respectively.
      •   Arguments Sx and Sy are vectors defining starting positions of the streamlines.

      handel = mfTriStreamLine(tri, xy, uv, Sxy)
      • Argument xy and uv are both defined in the n-by-2 matrix where n is the number of
          vertices.
      •   Argument Sxy is an s-by-2 matrix where s is the number of streamlines.

      You can also specify properties of the streamline objects through handle h with procedure
      msGSet.

      The properties available are:
      1. start: an s-by-2 matrix containing starting points coordinates.
      2. sizefactor: thickness of the streamlines.
      3. steplength: step length of the streamlines.
      By default, sizefactor=1 and steplength=0.5.
                                           Chapter 9 Visualization Routines   503



Example

Code
program Example
   use fml
   use fgl
   implicit none
   type(mfArray) :: h, tri, tet, x, y, z, u, v, w, sx, sy, sz

   x = mfRand( 500, 1 ) * 4 - 2
   y = mfRand( 500, 1 ) * 4 - 2
   z = mfZeros( 500, 1 )
   u = mfSin( 2 * x * y )
   v = mfCos( 2 * x - y )
   w = z
   sx = mfLinspace( -2, 2, 20 )
   sy = mfLinspace( 0, 0, 20 )
   sz = mfLinspace( 0, 0, 20 )
   tri = mfGetDelaunay( x, y )
    call msSubplot(2,2,1)
    call msTitle("Tri Stream Line")
    call msColormapRange(-2d0,2d0)
    h = mfTriStreamLine(tri, x, y, u, v, sx, sy)
   call msGSet( h, "steplength", 0.2d0 )
    call msSubplot(2,2,2)
    call msTitle("Tri Stream Dashed Line")
    call msColormapRange(-2d0,2d0)
    h = mfTriStreamDashedLine(tri, x, y, u, v, sx, sy)
   call msGSet( h, "steplength", 0.2d0 )
    call msDrawMaterial(h,mf('surf'),mf('colormap'), &
          mf('off'),mf('color'),mf((/0,0,0/)))
    call msSubplot(2,2,3)
    call msTitle("Tri Stream Ribbon")
    call msColormapRange(-2d0,2d0)
    h = mfTriStreamRibbon(tri, x, y, u, v, sx, sy)
   call msGSet( h, "steplength", 0.2d0 )
    call msGSet( h, "sizefactor", 0.01d0 )
    call msSubplot(2,2,4)
    call msTitle("Tri Stream Tube")
   call msQuiver( x, y, u, v, mf(0.15) )
   call msHold("on")
   h = mfTriMesh( tri, x, y, z )
   call msDrawMaterial( h, "edge", "trans", 90d0 )
   call msDrawMaterial( h, "surf", "visible", "off")
   h = mfTriStreamTube( tri, x, y, u, v, sx, sy )
   call msGSet( h, "steplength", 0.2d0 )
   call msGSet( h, "sizefactor", 0.003d0 )
   call msAxis("2")
   call msColormapRange( -2, 2 )
   call msViewPause()
   call msFreeArgs(h, tri, tet, x, y, z, u, v, w, sx, sy, sz)
end program Example


Result
504      MATFOR 4 in Fortran Reference Guide




      See Also
      mfTriMesh, mfTriStreamDashLine, mfTriStreamRibbon, mfTriStreamTube,
      mfTriStreamArrow
                                                          Chapter 9 Visualization Routines     505



mfTriStreamDashLine, msTriStreamDashLine
Create stream dashed-lines from two-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTriStreamDashLine(tri, x, y, u, v, Sx, Sy)
handle = mfTriStreamDashLine(tri, xy, uv, Sxy)

call msTriStreamline(tri, x, y, u, v, Sx, Sy)
call msTriStreamline(tri, xy, uv, Sxy)



Descriptions
Procedure mfTriStreamDashLine creates stream dashed-lines from two-dimensional
unstructured mesh data.

handel = mfTriStreamDashLine(tri, x, y, u, v, Sx, Sy)
• Argument tri is an m-by-n face matrix, where m is the number of polygons and n is the
    number of edges on each polygon. For example; a 4-by-3 face matrix tri draws a stream
    dashed-line object of 4 triangles, while a 3-by-4 face matrix tri draws a stream
    dashed-line object of 3 quadrilaterals.
•   Arguments x and y are n-by-1 vectors contain the x- and y- coordinates of the respective
    points.
•   Arguments u and w are two-dimensional orthogonal vector components corresponding to
    the x- and y- directions respectively.
•   Arguments Sx and Sy are vectors defining starting positions of the stream dashed-lines.

handel = mfTriStreamDashLine(tri, xy, uv, Sxy)
• Argument xy and uv are both defined in the n-by-2 matrix where n is the number of
    vertices.
•   Argument Sxy is an s-by-2 matrix where s is the number of stream dashed-lines.

You can also specify properties of the streamline objects through handle h with procedure
msGSet.

The properties available are:
1. start: an s-by-2 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream dashed-lines.
3. steplength: step length of the stream dashed-lines.
By default, sizefactor=1 and steplength=0.5.
506       MATFOR 4 in Fortran Reference Guide



      Example
      To be referred to mfTriStreamLine

      See Also
      mfTriMesh, mfTriStreamLine, mfTriStreamRibbon, mfTriStreamTube,
      mfTriStreamArrow
                                                                Chapter 9 Visualization Routines     507



mfTriStreamRibbon, msTriStreamRibbon
Create stream ribbons from two-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTriStreamRibbon(tri, x, y, u, v, Sx, Sy)
handle = mfTriStreamRibbon(tri, xy, uv, Sxy)

call msTriStreamRibbon(tri, x, y, u, v, Sx, Sy)
call msTriStreamRibbon(tri, xy, uv, Sxy)



Descriptions
Procedure mfTriStreamRibbon                  creates   stream   ribbons    from    two-dimensional
unstructured mesh data.

handel = mfTriStreamRibbon(tri, x, y, u, v, Sx, Sy)
• Argument tri is an m-by-n face matrix, where m is the number of polygons and n is the
    number of edges on each polygon. For example; a 4-by-3 face matrix tri draws a stream
    ribbon object of 4 triangles, while a 3-by-4 face matrix tri draws a stream ribbon object
    of 3 quadrilaterals.
•   Arguments x and y are n-by-1 vectors contain the x- and y- coordinates of the respective
    points.
•   Arguments u and w are two-dimensional orthogonal vector components corresponding to
    the x- and y- directions respectively.
•   Arguments Sx and Sy are vectors defining starting positions of the stream ribbons.

handel = mfTriStreamRibbon(tri, xy, uv, Sxy)
• Argument xy and uv are both defined in the n-by-2 matrix where n is the number of
    vertices.
•   Argument Sxy is an s-by-2 matrix where s is the number of stream ribbons.

You can also specify properties of the streamline objects through handle h with procedure
msGSet.

The properties available are:
1. start: an s-by-2 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream ribbons.
3. steplength: step length of the stream ribbons.
By default, sizefactor=1 and steplength=0.5.
508       MATFOR 4 in Fortran Reference Guide



      Example
      To be referred to mfTriStreamLine



      See Also
      mfTriMesh, mfTriStreamDashLine, mfTriStreamLine, mfTriStreamTube,
      mfTriStreamArrow
                                                           Chapter 9 Visualization Routines      509



mfTriStreamTube, msTriStreamTube
Create stream tubes from two-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTriStreamTube(tri, x, y, u, v, Sx, Sy)
handle = mfTriStreamTube(tri, xy, uv, Sxy)

call msTriStreamTube(tri, x, y, u, v, Sx, Sy)
call msTriStreamTube(tri, xy, uv, Sxy)



Descriptions
Procedure mfTriStreamTube creates stream tubes from two-dimensional unstructured
mesh data.

handel = mfTriStreamTube(tri, x, y, u, v, Sx, Sy)
• Argument tri is an m-by-n face matrix, where m is the number of polygons and n is the
    number of edges on each polygon. For example; a 4-by-3 face matrix tri draws a stream
    tube object of 4 triangles, while a 3-by-4 face matrix tri draws a stream tube object of 3
    quadrilaterals.
•   Arguments x and y are n-by-1 vectors contain the x- and y- coordinates of the respective
    points.
•   Arguments u and w are two-dimensional orthogonal vector components corresponding to
    the x- and y- directions respectively.
•   Arguments Sx and Sy are vectors defining starting positions of the stream tubes.

handel = mfTriStreamTube(tri, xy, uv, Sxy)
• Argument xy and uv are both defined in the n-by-2 matrix where n is the number of
    vertices.
•   Argument Sxy is an s-by-2 matrix where s is the number of stream tubes.

You can also specify properties of the streamline objects through handle h with procedure
msGSet.

The properties available are:
1. start: an s-by-2 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream tubes.
3. steplength: step length of the stream tubes.
By default, sizefactor=1 and steplength=0.5.
510       MATFOR 4 in Fortran Reference Guide



      Example
      To be referred to mfTriStreamLine

      See Also
      mfTriMesh, mfTriStreamDashLine, mfTriStreamRibbon, mfTriStreamLine,
      mfTriStreamArrow
                                                          Chapter 9 Visualization Routines     511



mfTriStreamArrow, msTriStreamArrow
Create stream arrows from two-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTriStreamArrow(tri, x, y, u, v, Sx, Sy)
handle = mfTriStreamArrow(tri, xy, uv, Sxy)

call msTriStreamArrow(tri, x, y, u, v, Sx, Sy)
call msTriStreamArrow(tri, xy, uv, Sxy)



Descriptions
Procedure mfTriStreamArrow creates stream arrows from two-dimensional unstructured
mesh data.

handel = mfTriStreamArrow(tri, x, y, u, v, Sx, Sy)
• Argument tri is an m-by-n face matrix, where m is the number of polygons and n is the
    number of edges on each polygon. For example; a 4-by-3 face matrix tri draws a stream
    arrow object of 4 triangles, while a 3-by-4 face matrix tri draws a stream arrow object
    of 3 quadrilaterals.
•   Arguments x and y are n-by-1 vectors contain the x- and y- coordinates of the respective
    points.
•   Arguments u and w are two-dimensional orthogonal vector components corresponding to
    the x- and y- directions respectively.
•   Arguments Sx and Sy are vectors defining starting positions of the stream arrows.

handel = mfTriStreamArrow(tri, xy, uv, Sxy)
• Argument xy and uv are both defined in the n-by-2 matrix where n is the number of
    vertices.
•   Argument Sxy is an s-by-2 matrix where s is the number of stream arrows.

You can also specify properties of the streamline objects through handle h with procedure
msGSet.

The properties available are:
1. start: an s-by-2 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream arrows.
3. steplength: step length of the stream arrows.
By default, sizefactor=1 and steplength=0.5.
512      MATFOR 4 in Fortran Reference Guide



      Example

      Code
      program Example
         use fml
         use fgl
         implicit none
         type(mfArray) :: h, tri, x, y, z, u, v, w, sx, sy, sz
         x = mfRand( 500, 1 ) * 4 - 2
         y = mfRand( 500, 1 ) * 4 - 2
         z = mfZeros( 500, 1 )
         u = mfSin( 2 * x * y )
         v = mfCos( 2 * x - y )
         w = z
         sx = mfLinspace( -1, 1, 10 )
         sy = mfLinspace( 0, 0, 10 )
         sz = mfLinspace( 0, 0, 10 )
         tri = mfGetDelaunay( x, y )

          call msTitle("Tri Stream Arrow")
          call msColormapRange(-2, 2)
          h = mfTriStreamArrow(tri, x, y, u, v, sx, sy)
          call msGSet( h, "arrowsize", 0.15d0 )
          call msGSet( h, "arrowstep", 0.25d0 )
          call msHold("on")
         h = mfTriMesh( tri, x, y, z )
         call msDrawMaterial( h, mf("edge"), mf("colormap"), mf("off"), &
             mf("color"), mf((/0.8,0.8,0.8/)) )
         call msDrawMaterial( h, "surf", "visible", "off")
          h = mfTriStreamTube(tri, x, y, u, v, sx, sy)
          call msGSet( h, "steplength", 0.25d0 )
          call msGSet( h, "sizefactor", 0.01d0 )
          call msDrawMaterial(h,"surf","trans",70d0)
          call msAxis("2")
         call msViewPause()
         call msFreeArgs(h, tri, x, y, z, u, v, w, sx, sy, sz)
      end program Example


      Result
                                               Chapter 9 Visualization Routines   513




See Also
mfTriMesh, mfTriStreamDashLine, mfTriStreamRibbon, mfTriStreamTube,
mfTriStreamLine
514       MATFOR 4 in Fortran Reference Guide



      mfTetStreamLine, msTetStreamLine
      Create streamlines from three-dimensional unstructured mesh data.


      Module
      fgl


      Syntax
      handle = mfTetStreamline(tet, x,y,z, u,v,w, Sx,Sy,Sz)
      handle = mfTetStreamline(tet, xyz, uvw, Sxyz)

      call msTetStreamline(tet, x,y,z, u,v,w, Sx,Sy,Sz)
      call msTetStreamline(tet, xyz, uvw, Sxyz)



      Descriptions
      Procedure mfTetStreamLine creates streamlines from three-dimensional unstructured
      mesh data.

      handel = mfTetStreamLine(tet, x, y, z, u, v, w, Sx, Sy, Sz)
      • Argument tet is an m-by-k cell matrix, where m is the number of polyhedrons and k is
          the number of vertices on each polyhedron.
      •   Arguments x, y and z are n-by-1 vectors contain the x-, y-, and z- coordinates of the
          respective unstructured grid points.
      •   Arguments u, v and w are three-dimensional orthogonal vector components
          corresponding to x, y and z.
      •   Arguments Sx, Sy and Sz are vectors defining starting positions of the streamlines.

      handel = mfTetStreamLine(tet, xyz, uvw, Sxyz)
      • Argument xyz and uvw are both defined in the n-by-3 matrix where n is the number of
          vertices.
      •   Argument Sxyz is an s-by-3 matrix where s is the number of streamlines.

      You can also specify properties of the streamlines through handle h with procedure msGSet.

      The properties available are:
      1. start: an n-by-3 matrix containing starting points coordinates.
      2. sizefactor: thickness of the streamlines.
      3. steplength: step length of the streamlines.
      By default, sizefactor=1 and steplength=0.5.



      Example
                                           Chapter 9 Visualization Routines   515


Code
program Example
   use fml
   use fgl
   implicit none
   type(mfArray) :: h, tet, x, y, z, u, v, w, sx, sy, sz
   x = mfRand( 4000, 1 ) * 4 - 2
   y = mfRand( 4000, 1 ) * 4 - 2
   z = mfRand( 4000, 1 ) * 4 - 2
   u = mfSin( 2 * x * y * z )
   v = mfCos( 2 * x - y )
   w = mfCos( x + y - z )
   sx = mfLinspace( -2, 2, 20 )
   sy = mfLinspace( 0, 0, 20 )
   sz = mfLinspace( 0, 0, 20 )
   tet = mfGetDelaunay3( x, y, z )
    call msSubplot(2,2,1)
    call msTitle("Tet Stream Line")
    call msColormapRange(-2d0,2d0)
    h = mfTetStreamLine(tet, x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.2d0 )
    call msSubplot(2,2,2)
    call msTitle("Tet Stream Dashed Line")
    call msColormapRange(-2d0,2d0)
    h = mfTetStreamDashedLine(tet, x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.2d0 )
    call msDrawMaterial(h,mf('surf'),mf('colormap'), &
          mf('off'),mf('color'),mf((/0,0,0/)))
    call msSubplot(2,2,3)
    call msTitle("Tet Stream Ribbon")
    call msColormapRange(-2d0,2d0)
    h = mfTetStreamRibbon(tet, x, y, z, u, v, w, sx, sy, sz)
   call msGSet( h, "steplength", 0.2d0 )
    call msGSet( h, "sizefactor", 0.01d0 )
    call msSubplot(2,2,4)
    call msTitle("Tet Stream Tube")
   h = mfTetSurf( tet, x, y, z )
   call msDrawMaterial( h, "both", "trans", 90d0 )
   call msHold("on")
   h = mfTetStreamTube( tet, x, y, z, u, v, w, sx, sy, sz )
   call msGSet( h, "steplength", 0.1d0 )
   call msGSet( h, "sizefactor", 0.005d0 )
   call msColormapRange( -2, 2 )
   call msViewPause()
   call msFreeArgs(h, tet, x, y, z, u, v, w, sx, sy, sz)
end program Example


Result
516      MATFOR 4 in Fortran Reference Guide




      See Also
      mfTetMesh, mfTetStreamDashLine, mfTetStreamRibbon, mfTetStreamTube,
      mfTetStreamArrow
                                                          Chapter 9 Visualization Routines   517



mfTetStreamDashLine, msTetStreamDashLine
Create stream dashed-lines from three-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTetStreamDashline(tet, x,y,z, u,v,w, Sx,Sy,Sz)
handle = mfTetStreamDashline(tet, xyz, uvw, Sxyz)

call msTetStreamDashline(tet, x,y,z, u,v,w, Sx,Sy,Sz)
call msTetStreamDashline(tet, xyz, uvw, Sxyz)



Descriptions
Procedure mfTetStreamDashline creates stream dashed-lines from three-dimensional
unstructured mesh data.

handel = mfTetStreamDashline(tet, x, y, z, u, v, w, Sx, Sy, Sz)
• Argument tet is an m-by-k cell matrix, where m is the number of polyhedrons and k is
    the number of vertices on each polyhedron.
•   Arguments x, y and z are n-by-1 vectors contain the x-, y-, and z- coordinates of the
    respective unstructured grid points.
•   Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to x, y and z.
•   Arguments Sx, Sy and Sz are vectors defining starting positions of the stream
    dashed-lines.

handel = mfTetStreamDashline(tet, xyz, uvw, Sxyz)
• Argument xyz and uvw are both defined in the n-by-3 matrix where n is the number of
    vertices.
•   Argument Sxyz is an s-by-3 matrix where s is the number of stream dashed-lines.

You can also specify properties of the stream dashed-lines through handle h with procedure
msGSet.

The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream dashed-lines.
3. steplength: step length of the stream dashed-lines.
By default, sizefactor=1 and steplength=0.5.
518       MATFOR 4 in Fortran Reference Guide


      Example
      To be referred to mfTetStreamLine

      See Also
      mfTetMesh, mfTetStreamLine, mfTetStreamRibbon, mfTetStreamTube,
      mfTetStreamArrow
                                                          Chapter 9 Visualization Routines   519



mfTetStreamRibbon, msTetStreamRibbon
Create stream ribbons from three-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTetStreamRibbon(tet, x,y,z, u,v,w, Sx,Sy,Sz)
handle = mfTetStreamRibbon(tet, xyz, uvw, Sxyz)

call msTetStreamRibbon(tet, x,y,z, u,v,w, Sx,Sy,Sz)
call msTetStreamRibbon(tet, xyz, uvw, Sxyz)



Descriptions
Procedure mfTetStreamRibbon creates stream ribbons from three-dimensional
unstructured mesh data.

handel = mfTetStreamRibbon(tet, x, y, z, u, v, w, Sx, Sy, Sz)
• Argument tet is an m-by-k cell matrix, where m is the number of polyhedrons and k is
    the number of vertices on each polyhedron.
•   Arguments x, y and z are n-by-1 vectors contain the x-, y-, and z- coordinates of the
    respective unstructured grid points.
•   Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to x, y and z.
•   Arguments Sx, Sy and Sz are vectors defining starting positions of the stream ribbons.

handel = mfTetStreamRibbon(tet, xyz, uvw, Sxyz)
• Argument xyz and uvw are both defined in the n-by-3 matrix where n is the number of
    vertices.
•   Argument Sxyz is an s-by-3 matrix where s is the number of stream ribbons.

You can also specify properties of the stream ribbons through handle h with procedure
msGSet.

The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream ribbons.
3. steplength: step length of the stream ribbons.
By default, sizefactor=1 and steplength=0.5.



Example
520       MATFOR 4 in Fortran Reference Guide


      To be referred to mfTetStreamLine

      See Also
      mfTetMesh, mfTetStreamDashLine, mfTetStreamLine, mfTetStreamTube,
      mfTetStreamArrow
                                                          Chapter 9 Visualization Routines   521



mfTetStreamTube, msTetStreamTube
Create stream tubes from three-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTetStreamTube(tet, x,y,z, u,v,w, Sx,Sy,Sz)
handle = mfTetStreamTube(tet, xyz, uvw, Sxyz)

call msTetStreamTube(tet, x,y,z, u,v,w, Sx,Sy,Sz)
call msTetStreamTube(tet, xyz, uvw, Sxyz)



Descriptions
Procedure mfTetStreamTube creates stream tubes from three-dimensional unstructured
mesh data.

handel = mfTetStreamTube(tet, x, y, z, u, v, w, Sx, Sy, Sz)
• Argument tet is an m-by-k cell matrix, where m is the number of polyhedrons and k is
    the number of vertices on each polyhedron.
•   Arguments x, y and z are n-by-1 vectors contain the x-, y-, and z- coordinates of the
    respective unstructured grid points.
•   Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to x, y and z.
•   Arguments Sx, Sy and Sz are vectors defining starting positions of the stream tubes.

handel = mfTetStreamTube(tet, xyz, uvw, Sxyz)
• Argument xyz and uvw are both defined in the n-by-3 matrix where n is the number of
    vertices.
•   Argument Sxyz is an s-by-3 matrix where s is the number of stream tubes.

You can also specify properties of the stream tubes through handle h with procedure
msGSet.

The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream tubes.
3. steplength: step length of the stream tubes.
By default, sizefactor=1 and steplength=0.5.



Example
522       MATFOR 4 in Fortran Reference Guide


      To be referred to mfTetStreamLine

      See Also
      mfTetMesh, mfTetStreamDashLine, mfTetStreamRibbon, mfTetStreamLine,
      mfTetStreamArrow
                                                          Chapter 9 Visualization Routines   523



mfTetStreamArrow, msTetStreamArrow
Create stream arrows from three-dimensional unstructured mesh data.


Module
fgl


Syntax
handle = mfTetStreamArrow(tet, x,y,z, u,v,w, Sx,Sy,Sz)
handle = mfTetStreamArrow(tet, xyz, uvw, Sxyz)

call msTetStreamArrow(tet, x,y,z, u,v,w, Sx,Sy,Sz)
call msTetStreamArrow(tet, xyz, uvw, Sxyz)



Descriptions
Procedure mfTetStreamArrow creates stream arrows from three-dimensional unstructured
mesh data.

handel = mfTetStreamArrow(tet, x, y, z, u, v, w, Sx, Sy, Sz)
• Argument tet is an m-by-k cell matrix, where m is the number of polyhedrons and k is
    the number of vertices on each polyhedron.
•   Arguments x, y and z are n-by-1 vectors contain the x-, y-, and z- coordinates of the
    respective unstructured grid points.
•   Arguments u, v and w are three-dimensional orthogonal vector components
    corresponding to x, y and z.
•   Arguments Sx, Sy and Sz are vectors defining starting positions of the stream arrows.

handel = mfTetStreamArrow(tet, xyz, uvw, Sxyz)
• Argument xyz and uvw are both defined in the n-by-3 matrix where n is the number of
    vertices.
•   Argument Sxyz is an s-by-3 matrix where s is the number of stream arrows.

You can also specify properties of the stream arrows through handle h with procedure
msGSet.

The properties available are:
1. start: an n-by-3 matrix containing starting points coordinates.
2. sizefactor: thickness of the stream arrows.
3. steplength: step length of the stream arrows.
By default, sizefactor=1 and steplength=0.5.



Example
524      MATFOR 4 in Fortran Reference Guide



      Code
      program Example
         use fml
         use fgl
         implicit none
         type(mfArray) :: h, tet, x, y, z, u, v, w, sx, sy, sz
         x = mfRand( 4000, 1 ) * 4 - 2
         y = mfRand( 4000, 1 ) * 4 - 2
         z = mfRand( 4000, 1 ) * 4 - 2
         u = mfSin( 2 * x * y * z )
         v = mfCos( 2 * x - y )
         w = mfCos( x + y - z )
         sx = mfLinspace( -2, 2, 20 )
         sy = mfLinspace( 0, 0, 20 )
         sz = mfLinspace( 0, 0, 20 )
         tet = mfGetDelaunay3( x, y, z )
          call msTitle("Tet Stream Arrow")
          call msColormapRange(-2,2)
          h = mfTetStreamArrow(tet, x, y, z, u, v, w, sx, sy, sz)
          call msGSet( h, "arrowsize", 0.15d0 )
          call msGSet( h, "arrowstep", 0.25d0 )
          call msHold("on")
          h = mfTetMesh( tet, x, y, z )
          call msDrawMaterial( h, mf("edge"), mf("colormap"), mf("off"), &
              mf("color"), mf((/0.8,0.8,0.8/)) )
          call msDrawMaterial( h, "surf", "visible", "off")
          h = mfTetStreamTube(tet, x, y, z, u, v, w, sx, sy, sz)
          call msGSet( h, "steplength", 0.25d0 )
          call msGSet( h, "sizefactor", 0.01d0 )
          call msDrawMaterial(h,"surf","trans",70d0)
         call msViewPause()
         call msFreeArgs(h, tet, x, y, z, u, v, w, sx, sy, sz)
      end program Example


      Result
                                               Chapter 9 Visualization Routines   525




See Also
mfTetMesh, mfTetStreamDashLine, mfTetStreamRibbon, mfTetStreamTube,
mfTetStreamLine
526     MATFOR 4 in Fortran Reference Guide




      Unstructured Point Set
                                                            Chapter 9 Visualization Routines   527



mfPoint, msPoint
Display input points in three-dimensional space.


Module
fgl


Syntax
handle = mfPoint(x, y, z[, c])
handle = mfPoint(xyz[, c])

call msPoint(x, y, z[, c])
call msPoint(xyz[, c])



Descriptions
Procedure mfPoint plots a set of input points in three-dimensional space.

call msPoint(x, y, z)
call msPoint(x, y, z, c)
• Arguments x, y and z contain the x-, y-, and z- coordinates of the respective points.
    They can be either matrices or vectors of the same shape.
•   By default, the scalar value of each point is the height specified in argument z.
    Specifying the scalar vector c overrides the default scalar values.

call msPoint(xyz)
call msPoint(xyz, c)
• Vertex vectors are defined in the n-by-3 matrix xyz.

h = mfPoint(...)
• Handle h retrieves a handle to the points created by mfPoint(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the points through handle h with procedure msGSet.

The property available is:
1. xyz
2. point_size



Example

Code
program Example
528      MATFOR 4 in Fortran Reference Guide

          use fml
          use fgl
          implicit none
          type(mfArray) :: x, y, xy, z, xyz
          integer nPoint,i,j
          nPoint = 2000
          ! Specify locations of three balls
          x = mfRand(nPoint,1) * MF_PI * 2 - MF_PI
          y = mfRand(nPoint,1) * MF_PI * 2 - MF_PI
          xy = x + y
          z = mfSin(x) * mfCos(y) - mfSin(xy)
          xyz = x.hc.y.hc.z
          call msPoint(xyz)
          ! Pause program to view
          call msViewPause()
          call msFreeArgs(x, y, xy, z, xyz)
         end program Example


      Result




      See Also
                                                            Chapter 9 Visualization Routines    529



mfDelaunay, msDelaunay, mfGetDelaunay, msGetDelaunay
2-D Delaunay triangulation of input points.


Module
fgl


Syntax
h = mfDelaunay(x, y[, bx1, bx2, ...])
tri = mfGetDelaunay(x, y[, p1, p2, ...])

call msGetDelaunay(mfOut(tri), x, y[, p1, p2, ...])



Descriptions
Procedure mfDelaunay is a filter that constructs a two-dimensional Delaunay triangulation
from a set of input points. You may use procedure mfGetDelaunay to retrieve the
triangular mesh output of the filter.

h = mfDelaunay(x, y, bx1, by1, bx2, by2, bx3, by3)
• Arguments x and y specify the x- and y- coordinates of the input points.
•   You may define the boundaries which the Delaunay triangulation is constructed upon.
    Each boundary is defined by two vertex vectors specified in the arguments. For instance,
    arguments bx1 and by1 define the first boundary, arguments bx2 and by2 define the
    second boundary and so on.
•   Notice that the order of the boundary points determines how the Delaunay triangulation is
    constructed. If the boundary points are specified counterclockwise, then the Delaunay
    triangulation is constructed within the boundary; if the boundary points are specified
    clockwise, then the Delaunay triangulation is constructed beyond the boundary. On the
    other hand, an unexpected result may arise if a false order of boundary points is given.

tri = mfGetDelaunay(x, y, bx1, by1, bx2, by2, bx3, by3)
call msGetDelaunay(mfOut(tri), x, y, bx1, by1, bx2, by2, bx3, by3)
• Retrieve the triangular mesh tri. With tri and the coordinates xyz, you may use
    mfTriSurf to plot the triangular surface.

h = mfDelaunay(...)
• Handle h retrieves a handle to the polygonal surface object created by
    mfDelaunay(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.
530         MATFOR 4 in Fortran Reference Guide


      You can specify properties of the polygonal surface object through handle h with procedure
      msGSet.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, n, h
      type (mfArray) :: bx1, by1, bx2, by2, bx3, by3
      integer :: i
      real(8) :: rx, ry
      bx1    = .t. (/ -5, 5, 5, 1, 1, -1, -1, -5/)
      by1    = .t. (/ -5, -5, 5, 5, 2, 2, 5, 5/)
      bx2    = .t. (/ -3, -3, -1 /)
      by2    = .t. (/ -3, -1, -3 /)
      n =    .t. mfLinspace(0, -1.9*MF_PI, 10)
      bx3    = 2.5d0 + mfCos(n)
      by3    = mfSin(n)

      x = mfZeros(30,1)
      y = mfZeros(30,1)
      call random_seed()
      do i=1,30
          do while (.true.)
              call random_number(rx)
              call random_number(ry)
              rx= rx*10 - 5
              ry= ry*10 - 5
              if ( (rx<5 .or. rx>-5 ) .and. (ry<5 .or. ry>-5) .and. (rx<-1 .or.
      rx>1 .or. ry<2) &
                    .and. (rx<-3 .or. ry<-3 .or. rx + ry > -2) .and.
      ( (rx-2.5d0)**2 + ry**2 > 1) ) then
                  exit
              end if
          end do
          call msAssign(mfS(x,i,1), rx)
          call msAssign(mfS(y,i,1), ry)
      end do
      call msFigure('Delaunay');
      call msSubplot(1, 2, 1)
      call msTitle('Delaunay')
      h = mfDelaunay(x, y)
      call msAxis('equal')
      call msSubplot(1, 2, 2)
      call msTitle('Constrained Delaunay')
      h = mfDelaunay(x, y, bx1, by1, bx2, by2, bx3, by3)
      call msHold('on')
      h = mfPlot(bx1, by1, "or", bx2, by2, "or", x, y, "xb")
      call msAxis('equal')
      call msViewPause()
      call msFreeArgs(x, y, n, h, bx1, by1, bx2, by2, bx3, by3)
      end program example


      Result
           Chapter 9 Visualization Routines   531




See Also
532         MATFOR 4 in Fortran Reference Guide



      mfDelaunay3, msDelaunay3, mfGetDelaunay3,

      msGetDelaunay3
      3-D Delaunay triangulation of input points.


      Module
      fgl


      Syntax
      h =    mfDelaunay3(x, y, z)
      h =    mfDelaunay3(xyz)
      tet    = mfGetDelaunay3(x, y, z)
      tet    = mfGetDelaunay3(xyz)

      call msGetDelaunay3(mfOut(tet), x, y, z)



      Descriptions
      Procedure mfDelaunay3 is a filter that constructs a three-dimensional Delaunay
      triangulation from a set of input points. You may use procedure to retrieve the tetrahedral
      mesh output of the filter.

      h = mfDelaunay3(x, y, z)
      tet = mfGetDelaunay3(x, y, z)
      • Arguments x,y and z specify the x-, y- and z- coordinates of the input points.

      h = mfDelaunay3(xyz)
      tet = mfGetDelaunay3(xyz)
      • Vertex vectors xyz are defined in the n-by-3 matrix.

      tet = mfGetDelaunay3(xyz)
      • Retrieve the tetrahedral mesh tet. With tet and the coordinates xyz, you may use
          mfTetSurf to plot the tetrahedral surface.

      h = mfDelaunay3(...)
      • Handle h retrieves a handle to the polyhedral object created by mfDelaunay3(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
          current graphics object.

      You can specify properties of the polyhedral object through handle h with procedure
      msGSet.
                                           Chapter 9 Visualization Routines   533


Example

Code
Program example
use fgl
use fml
implicit none
type(mfArray) :: xyz, h
xyz = mfRand(30, 3)
call msFigure('Delaunay 3D')
call msTitle('Delaunay 3D')
h = mfDelaunay3( xyz )
call msDrawMaterial(h, 'surf', 'trans', 50)
call msDrawMaterial(h,'edge','line_style','dashed')
call msHold('on')
!h = mfSphere( xyz, mf(0.02), mf((/0, 0, 1/)) )
call msViewPause()
call msFreeArgs(xyz, h)
end Program example


Result




See Also
534     MATFOR 4 in Fortran Reference Guide




      Velocity Vectors
                                                            Chapter 9 Visualization Routines   535



mfQuiver, msQuiver
Plot two-dimensional velocity vectors.


Module
fgl


Syntax
handle = mfQuiver(x, y, u, v[, scale])
handle = mfQuiver(u, v[, scale])



Descriptions
Procedure mfQuiver plots velocity vectors as arrows with components (u, v) at the points
(x, y).

handle = mfQuiver(x, y, u, v)
handle = mfQuiver(x, y, u, v, scale)
• mfArrays x and y contain positions of the velocity vectors, while the mfArrays u and v
    contain the corresponding velocity components.
•   You can control the vector scaling by specifying argument scale. Specifying scale as
    0.5 would reduce the relative length of the vector by half.
•   The shapes of the four mfArrays x,y,u and v must conform, i.e. all are m-by-n
    mfArrays.

handle = mfQuiver(u, v)
handle = mfQuiver(u, v, scale)
• Velocity vectors are plotted over a geometrically rectangular grid where x = mfColon(1,
    n) and y = mfColon(1, m).

h = mfQuiver(...)
• Handle h retrieves a handle to the quiver object created by mfQuiver(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the quiver object through handle h with procedure msGSet.



Example

Code
program example
use fml
use fgl
536      MATFOR 4 in Fortran Reference Guide

      implicit none
      type(mfArray) :: u, v, x, y, a
      a = mfLinspace(1, 10, 8)
      call msMeshgrid(mfout(x, y), a)
      u = 4*mfCos(y)
      v = 4*mfOnes(8, 8)
      call   msQuiver(x, y, u, v, mf(0.2))
      call   msAxis('equal')
      call   msCamZoom(0.8d0)
      call   msViewPause()
      call msFreeArgs(u, v, x, y, a)
      end program example


      Result




      See Also
      mfQuiver3
                                                           Chapter 9 Visualization Routines   537



mfQuiver3, msQuiver3
Plot three-dimensional velocity vectors.


Module
fgl


Syntax
handle = mfQuiver3(x, y, z, u, v, w[, scale])
handle = mfQuiver3(z, u, v, w[, scale])



Descriptions
Procedure mfQuiver3 plots velocity vectors as arrows with components (u, v, w) at the
points (x, y, z)in three-dimensional space.

handle = mfQuiver3(x, y, z, u, v, w)
handle = mfQuiver3(x, y, z, u, v, w, scale)
• mfArrays x, y and z contain corresponding positions of velocity vectors, which are
    specified by mfArrays u, v and w corresponding to the three-dimensional orthogonal
    velocity components.
•   You can control the vector scaling by specifying argument scale. Specifying scale as
    0.5 would reduce the relative length of the vector by half. By default, scale = 0.
•   The shapes of the four mfArrays x, y, u and v must be conformed, i.e. All are m-by-n
    mfArrays.

call msQuiver3(z, u, v, w)
call msQuiver3(z, u, v, w, scale)
• mfArray z, u, v, w are assumed to be defined over a geometrically rectangular grid
    [x,y], where x = mfColon(1, n) and y = mfColon(1, m).

h = mfQuiver3(...)
• Handle h retrieves a handle to the velocity vector objects created by
    mfQuiver3(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the velocity vector objects through handle h with procedure
msGSet.

The property available is:

1. symbol: "arrow", "cone" or "flat_arrow"
538      MATFOR 4 in Fortran Reference Guide




      Example

      Code
      program Example_mfQuiver3
        use fml
        use fgl
      implicit none
        type(mfArray) :: a, b, c, x, y, z, v, u, w, h1, h2, t,p
       a = mfLinspace(-2, 1.6d0, 4)
       b = mfLinspace(-2, 1, 3)
       c = mfLinspace(-2, 1.84d0, 5)
       call msMeshgrid(mfout(x, y, z), a, b, c)
       u = mfOnes(3, 4, 5)
       v = 0.4d0*(z**2)
       w = mfExp(0.5d0*x)
       call msFigure('Quiver3')
       h1=mfQuiver3(x, y, z, u, v, w)
       ! Let vector color as colomap
       call msDrawMaterial(h1, mf('edge'), mf('colormap'), mf('on'))
       call msColormapRange(0, 3)
       call msColorbar('on')
       call msView(-30, 50)
       call msFigure('Quiver Surf')
       call msMeshgrid(mfout(t,p), a, b)
       t = mfCos(t)
       call msMesh(t)
       call msHold('on')
       h2 = mfQuiver3(t, mfS(u,MF_COL,MF_COL,5), &
            mfS(v,MF_COL,MF_COL,5), mfS(w,MF_COL,MF_COL,5))
       call msDrawMaterial(h2, mf('edge'), mf('colormap'), mf('on'))
       call msColormapRange(0, 3)
       call msColorbar('on')
       call msView(-30, 50)
        call msViewPause()
        call msFreeArgs(a, b, c, x, y, z, v, u, w, h1, h2, t, p)
      end program Example_mfQuiver3


      Result
           Chapter 9 Visualization Routines   539




See Also
mfQuiver
540    MATFOR 4 in Fortran Reference Guide




      Image
                                                           Chapter 9 Visualization Routines    541



mfImage, msImage
Displays image files.


Module
fgl


Syntax
handle = mfImage(img [, pos])
handle = mfImage(filename [, pos])



Descriptions
Procedure mfImage displays an image file in the plot space.
handle = mfImage(img [, pos])
• Argument img is an m-by-n-by-3 matrix containing the image pixel and the rgb color
    codes. Use m-by-n matrix for gray scale image.
•   img can be saved into mfArray format using Procedure mfLoad.
•   Argument pos is a 4 by 3 or a 4 by 2 (with z value equals to 0) matrix specifying the
    location of the image. By default, the pos value is [0,0,0; w,0,0; 0,h,0; w,h,0] where w
    and h are the width and height of the input image respectively.

handle = mfImage(filename [, pos])
• Argument filename is the name of the image file.

You can specify properties of the image objects through handle h with procedure msGSet.

The properties available are:
1. position
2. filename
3. cdata



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: ax, h, bx, pos
integer i
call msSubplot(1,2,1)
ax = mfImRead('ancad.bmp')
h = mfImage(ax)
call msAssign(bx,mfS(ax, 320.to.350, 25.to.200, MF_COL) )
542      MATFOR 4 in Fortran Reference Guide

      call msAxis("equal")
      call msSubplot(1,2,2)
      call msImWrite('test.bmp',bx)
      pos =
      mf((/15,0,-10/)).vc.mf((/185,0,-10/)).vc.mf((/0,60,10/)).vc.mf((/200,
      60,0/))
      h = mfImage(mfImRead('test.bmp'),pos)
      call msView("3")
      !Pauses the program to display graph.
      call msViewPause()
      do i=1,5
         call msSubplot(1,2,2)
         call msAssign(mfS(pos,1,1),mfS(pos,1,1)-5*i)
         call msAssign(mfS(pos,1,2),mfS(pos,1,2)-10*i)
         call msAssign(mfS(pos,3,2),mfS(pos,3,2)+10*i)
         call msGSet(h,"position",pos)
         call msDrawNow()
      end do
      call msViewPause()
      !Deallocate mfArray
      call msFreeArgs(ax,h,bx,pos)
      end program example


      Result




      See Also
      mfImRead, mfImWrite
                                                     Chapter 9 Visualization Routines   543



mfImRead
Read in an image file.


Module
fgl


Syntax
ax = mfImRead(filename)



Descriptions
Procedure mfImRead reads in an image file with the name specified by argument
filename and stores it in argument ax which is an m-by-n-by-3 matrix storing the rgb
color codes.

The supported file formats are: bmp, jpeg and png.



Example
To be referred to mfImage

See Also
mfImage, mfImWrite
544       MATFOR 4 in Fortran Reference Guide



      msImWrite
      Write to an image file.


      Module
      fgl


      Syntax
      call msImWrite(filename, ax)



      Descriptions
      Procedure msImWrite writes the rgb color codes stored in the m-by-n-by-3 matrix ax into a
      file with the name specified by argument filename.

      The supported file formats are: bmp, jpeg and png.



      Example
      To be referred to mfImage

      See Also
                           Chapter 9 Visualization Routines   545




Elementary 2D/3D Objects
546       MATFOR 4 in Fortran Reference Guide



      mfCircle, msCircle
      Draw a circle.


      Module
      fgl


      Syntax
      h = mfCircle([loc][, rad][, color][, resolution])

      call msCircle([loc][, rad][, color][, resolution])



      Descriptions
      Procedure mfCircle draws a circle with center at loc, radius specified as rad, color
      specified as color and resolution level specified as resolution. All arguments are
      optional.

      call msCircle(loc, rad, color, resolution)
            Argument       Meaning
                loc        A 1-by-2 mfArray containing the x- and y- coordinates of the
                           circle center. By default, argument loc is set to [0,0].
               rad         An mfArray containing a real number specifies the radius of
                           the circle. By default, argument radius is set to 0.5.
               color       An mfArray containing a string specifies the color, e.g. “y”
                           for yellow, or a 1-by-3 mfArray contains the rgb codes. By
                           default, argument color is set to white.
            resolution     An mfArray containing the number of polygons used for
                           modeling the circular object. The higher the polygon number,
                           the smoother a circle appears. The lower the polygon number,
                           the faster a circle is rendered. By default, the circle is set to a
                           resolution = 64.



      h = mfCircle(...)
      • Handle h retrieves a handle to the circle object created by mfCircle(...).
      •   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
         current graphics object.
      You can specify properties of the circle object through handle h with procedure msGSet.

      The properties available are:
                                              Chapter 9 Visualization Routines   547


1. location
2. radius
3. color
4. resolution

Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: loc,color,rad

! Center at (10,20), (17.5,20), (32.5,20)
loc = (/10d0, 20d0/).vc.(/17.5d0,20d0/).vc.(/32.5d0,20d0/)
! Color is red, green, blue
color = (/1,0,0/).vc.(/0,1,0/).vc.(/0,0,1/)
!radius is 2.5, 5, 10
rad = .t.(/2.5d0,5d0,10d0/)
! resolution = 64 by default
call msCircle(loc, rad, color)
call msAxis('equal')
! Pause the program for display
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(loc,color,rad)

end program example

Result




See Also
mfShpere
548        MATFOR 4 in Fortran Reference Guide



      mfSquare, msSquare
      Draw a square.


      Module
      fgl


      Syntax
      h = mfSquare([loc][, size][, color])

      call msSquare([loc][, size][, color])



      Descriptions
      Procedure mfSquare draws a square with center at loc, size specified as size, and color
      specified as color. All arguments are optional.

      call msSquare(loc, size, color)
          Argument       Meaning

            loc         A 1-by-2 mfArray contains the x- and y- coordinates of the square
                        center By default, argument loc is set to [0,0].

            size        A 1-by-2 mfArray specifies the length and width of a square. By
                        default, argument Size is set to [1,1].

           color        An mfArray containing a string specifies the color, e.g. “y”, or a
                        1-by-3 mfArray containing the rgb codes. By default, argument
                        color is set to grey.



      h = mfSquare(...)
      • Handle h retrieves a handle to the square object created by mfSquare(...).
      •    Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
           current graphics object.

      You can specify properties of the square object through handle h with procedure msGSet.

      The properties available are:

      1. location
      2. size
      3. color
                                              Chapter 9 Visualization Routines   549



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: loc, size,color

! Center at (10,20), (17.5,20), (32.5,20)
loc = (/10d0, 20d0/).vc.(/17.5d0,20d0/).vc.(/32.5d0,20d0/)
size = .t.(/5d0,10d0,20d0/)
! Color is red, green, blue
color = (/1,0,0/).vc.(/0,1,0/).vc.(/0,0,1/)
call msSquare(loc, size, color)
call msAxis('equal')
! Pause the program for display
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(loc, size,color)
end program example


Result




See Also
mfCube
550       MATFOR 4 in Fortran Reference Guide



      mfMolecule, msMolecule
      Draw stick-and-ball models of molecules.


      Module
      fgl


      Syntax
      h = mfMolecule(loc, conn[, rad][, color][, stick_rad][, stick_col][,
      resolution])

      call msMolecule(loc, conn[, rad][, color][, stick_rad][, stick_col][,
      resolution])



      Descriptions
      Procedure mfMolecule enables you to create three-dimensional stick and ball models of
      molecules.

      call msMolecule(loc, conn, rad, color, stick_rad, stick_col,
      resolution)
      • Draw n balls specified by argument loc and m sticks specified by argument conn.
          Argument rad specifies the radius of each ball, argument color specifies the color of
          each ball, argument stick_rad specifies the cylindrical radius of each stick, argument
          stick_col specifies the color of the sticks, and argument resolution specifies the
          smoothness of the ball objects.
      •   Argument loc is an n-by-3 array containing the three-dimensional Cartesian coordinates
          (x, y, z) of each ball center, hence specifying the spatial relationship of each ball. Each
          ball is numbered according to their respective row index. Thus, row number 1 specifies
          ball number 1. The first column contains the x-coordinates, the second column contains
          the y-coordinates, and the third the z-coordinates. For example, the array below specifies
          three balls whose centers are located at (0,0,0), (1,1,1) and (0,1,0) respectively.

      Argument loc:
                          x            y           z
            ball 1        0            0           0
            ball 2        1            1           1
            ball 3        0            1           0



      •   Argument conn is an m-by-2 array specifying m number of sticks and the balls
          connected by each stick. Each stick connects two balls and is labeled according to its row
                                                             Chapter 9 Visualization Routines       551


    number. Columns of the argument conn contain the indices of the balls that each stick
    connects. For example, the array below specifies 3 sticks connecting ball 1 and ball 2, ball
    3 and ball 1, ball 2 and ball 3.

Argument conn:
                ball index     ball index
    stick 1          1              2
    stick 2          3              1
    stick 3          2              3



•   Argument rad is a scalar specifying the radius of all balls or an n-by-1 array specifying
    the radius of each individual ball. By default, all balls are drawn with a radius of 0.5. As
    an example, the array below specifies three balls of different sizes, with radius 1, 2, and 3
    respectively.

Argument rad:
                    radius
    ball 1            1
    ball 2            2
    ball 3            3



•   Argument color contains a string specifying the color of all the balls or an n-by-3 array
    containing the rgb color code of each ball. The rgb color code is specified as [r, g, b]
    where 0 < r, g, b < 1. For example, the array below specifies three balls of red, green and
    blue respectively.

Argument color:
                     r           g           b
    ball 1          0.8         0.1         0.1
    ball 2          0.1         0.8         0.1
    ball 3          0.1         0.1         0.8


h = mfMolecule(...)
• Handle h retrieves a handle to the molecule objects created by mfMolecule(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
   current graphics object.
You can specify properties of the molecule objects through handle h with procedure
msGSet.
552       MATFOR 4 in Fortran Reference Guide



      The properties available are:

      1. location
      2. connective
      3. radius
      4. color
      5. stick_radius
      6. stick_color
      7. resolution



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: loc, conn, rad, color, stick_rad, stick_col, h
      ! Specify locations of three balls using vcat
      loc = reshape((/0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 0.0/), &
                  (/3,3/))
      ! Specify three sticks and their connections
      conn = reshape((/1.0, 1.0, 2.0, 2.0, 3.0, 3.0/), &
                  (/3,2/))
      ! Specify the radius of each ball at radius=0.25,0.35,0.5
      rad = (/0.25, 0.35, 0.5/)
      ! Set the color of each ball to red, green and blue
      color = reshape((/0.8, 0.1, 0.1, 0.1, 0.8, 0.1, 0.1, 0.1, 0.8/), &
                   (/3,3/))
      ! Set the cylindrical radius to 0.1
      stick_rad = 0.1d0
      ! Set the color of the stick to grey
      stick_col = (/0.7, 0.7, 0.7/)
      call msAxis(mf((/-0.5d0, 1.6d0, -0.3d0, 1.6d0, -0.5d0, 1.35d0/)))
      ! Draw the molecules
      h = mfMolecule(loc, conn, rad, color, stick_rad, stick_col)
      ! Pause program to view
      call msViewPause()
      ! Deallocate mfArrays
      call msFreeArgs(loc, conn, rad, color, stick_rad, stick_col)
      end program example


      Result
           Chapter 9 Visualization Routines   553




See Also
mfSphere
554       MATFOR 4 in Fortran Reference Guide



      mfFastMolecule, msFastMolecule
      Draw stick-and-ball models of molecules.


      Module
      fgl


      Syntax
      h = mfFastMolecule(loc, conn[, rad][, color])

      call msFastMolecule(loc, conn[, rad][, color])



      Descriptions
      Procedure mfFastMolecule enables                 you   to   quickly   create    three-dimensional
      stick-and-ball models of molecules.

      call msFastMolecule(loc, conn, rad, color)
      • Draw n balls specified by argument loc and m sticks specified by argument conn.
          Argument rad specifies the radius of each ball, argument color specifies the color of
          each ball.
      •   Argument loc is an n-by-3 array containing the three-dimensional Cartesian coordinates
          (x, y, z) of each ball center, hence specifying the spatial relationship of each ball. Each
          ball is numbered according to their respective row index. Thus, row number 1 specifies
          ball number 1. The first column contains the x-coordinates, the second column contains
          the y-coordinates, and the third the z-coordinates. For example, the array below specifies
          three balls whose center are located at (0,0,0), (1,1,1) and (0,1,0) respectively.

      Argument loc:
                          x            y           z
            ball 1        0            0           0
            ball 2        1            1           1
            ball 3        0            1           0



      •   Argument conn is an m-by-2 array specifying m number of sticks and the balls
          connected by each stick. Each stick connects two balls and is labeled according to its row
          number. Columns of the argument conn contain the indices of the balls that each stick
          connects. For example, the array below specifies 3 sticks connecting ball 1 and ball 2, ball
          3 and ball 1, ball 2 and ball 3.

      Argument conn:
                                                             Chapter 9 Visualization Routines        555


                ball index      ball index
    stick 1          1               2
    stick 2          3               1
    stick 3          2               3



•   Argument rad is a scalar specifying the radius of all balls or an n-by-1 array specifying
    the radius of each individual ball respectively. By default, all balls are drawn with a radius
    of 0.5. As an example, the array below specifies three balls of different sizes, with radius
    1, 2 and 3 respectively.

Argument rad:
                  radius
    ball 1          1
    ball 2          2
    ball 3           3



•   Argument color contains a string specifying the color of all the balls or an n-by-3 array
    containing the rgb color code of each ball. The rgb color code is specified as [r, g, b]
    where 0 < r, g, b < 1. For example, the array below specifies three balls of red, green and
    blue respectively.

Argument color:
                   r             g            b
    ball 1        0.8           0.1          0.1
    ball 2        0.1           0.8          0.1
    ball 3        0.1           0.1          0.8


h = mfFastMolecule(...)
• Handle h retrieves a handle to the molecule objects created by
    mfFastMolecule(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the molecule objects through handle h with procedure
msGSet.

The properties available are:

1. location
556       MATFOR 4 in Fortran Reference Guide


      2. connective
      3. radius
      4. color



      Example

      Code
      program Example_msFastMolecule
          use fml
          use fgl
          implicit none
          type(mfArray) :: loc, conn, rad, color, h
           ! Specify locations of three balls using vcat
           loc = Reshape((/0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 0.0/), &
                 (/3,3/))
           ! Specify three sticks and their connections
           conn = Reshape((/1.0, 1.0, 2.0, 2.0, 3.0, 3.0/), &
                 (/3,2/))
           ! Specify the radius of each ball at radius=0.5,0.7,1.0
           rad = (/0.25, 0.35, 0.5/)
           ! Set the color of each ball to red, green and blue
           color = Reshape((/0.8, 0.1, 0.1, 0.1, 0.8, 0.1, 0.1, 0.1, 0.8/), &
                   (/3,3/))
           call msAxis(-0.5d0, 1.6d0, -0.3d0, 1.6d0, -0.5d0, 1.35d0)
           ! Draw the molecules
           h = mfFastMolecule(loc, conn, rad, color)
           ! Pause program to view
           call msViewPause()
      end program Example_msFastMolecule


      Result
           Chapter 9 Visualization Routines   557




See Also
mfSphere
558         MATFOR 4 in Fortran Reference Guide



      mfSphere, msSphere
      Draw a sphere.


      Module
      fgl


      Syntax
      h = mfSphere([loc][, radius][, color][, resolution])

      call msSphere([loc][, radius][, color][, resolution])



      Descriptions
      Procedure mfSphere draws a sphere with center at loc, radius specified by radius,
      color specified by color and resolution level specified by resolution. All arguments
      are optional.

      call msSphere(loc, radius, color, resolution)
         Argument    Meaning
               loc          A 1-by-3 mfArray containing the x-, y- and z-
                            coordinates of the sphere center. By default, argument
                            loc is set to [0,0,0].
            radius          An mfArray containing a real number specifies the
                            radius of the sphere. By default, argument radius is set to
                            0.5.
             color          An mfArray containing a string specifies the color, e.g.
                            “y”, or a 1-by-3 mfArray contains the rgb codes. By
                            default, argument color is set to grey.
          resolution An mfArray containing the number of polygons used for
                     modeling the circular object. The higher the polygon
                     number, the smoother a sphere appears. The lower the
                     polygon number, the faster a sphere is rendered. By
                     default, the sphere is set to a resolution = 64.

      h = mfSphere(...)
      • Handle h retrieves a handle to the sphere object created by mfSphere(...).
      •    Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
           current graphics object.

      You can specify properties of the sphere object through handle h with procedure msGSet.
                                           Chapter 9 Visualization Routines   559



The properties available are:

1. location
2. radius
3. color
4. resolution

Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: zeros, color
zeros =(/0, 0, 0/)
color = (/0, 1, 0/)
! Center at (0,0,0), Radius = 0.5, Color = 'green'
call msSphere(zeros, mf(1), color)
! Remove current Axis
call msAxis('off')
call msAxis('equal')
! Pause the program for display
call msViewPause()
! Deallocate mfArray
call msFreeArgs(zeros)
end program example

Result




See Also
mfCylinder, mfMolecule, mfCube
560        MATFOR 4 in Fortran Reference Guide



      mfCube, msCube
      Draw a cube.


      Module
      fgl


      Syntax
      h = mfCube([loc][, size][, color])

      call msCube([loc][, size][, color])



      Descriptions
      Procedure mfCube draws a cube with center at loc, size specified by size, and color
      specified by color. All arguments are optional.

      call msCube(loc, size, color)
          Argument       Meaning

            loc         A 1-by-3 mfArray contains the x-, y- and z- coordinates of the
                        cube center. By default, argument loc is set to [0,0,0].

            size        A 1-by-3 mfArray specifies the length , width and height of a
                        cube. By default, argument Size is set to [1,1,1].

           color        An mfArray containing a string specifies the color, e.g. “y”, or a
                        1-by-3 mfArray containing the rgb codes. By default, argument
                        color is set to grey.



      h = mfCube(...)
      • Handle h retrieves a handle to the cube object created by mfCube(...).
      •    Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
           current graphics object.

      You can specify properties of the cube object through handle h with procedure msGSet.

      The properties available are:

      1. location
      2. size
      3. color
                                           Chapter 9 Visualization Routines   561



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: zeros, cubesize, color
zeros = (/ 0, 0, 0 /)
cubesize = (/ 0.2, 0.3, 0.4 /)
color = (/ 0, 1, 0 /)
! Cube with center at (0,0,0), size of 0.2x0.3x0.4,
! and green in color
call msCube(zeros, cubesize, color)
call msAxis('equal')
! Pause the program for display
call msViewPause()
! Deallocate mfArrays
call msFreeArgs(zeros, cubesize, color)
end program example


Result




See Also
mfCylinder, mfSphere, mfCone
562       MATFOR 4 in Fortran Reference Guide



      mfCylinder, msCylinder
      Draw a cylinder.


      Module
      fgl


      Syntax
      h = mfCylinder([loc][, radius][, height][, color][, resolution])

      call msCylinder([loc][, radius][, height][, color][, resolution])



      Descriptions
      Procedure mfCylinder draws a cylinder with center at loc, radius specified by radius,
      height specified by height, color specified by color and resolution level specified by
      resolution. All arguments are optional.

      call msCylinder(loc, radius, height, color, resolution)
        Argument          Meaning

             loc         A 1-by-3 mfArray contains the x-, y- and z- coordinates of the
                         cylinder center. By default, argument loc is set to [0, 0, 0].

            radius       An mfArray containing a real number specifies the radius of the
                         cylinder. By default, argument radius is set to 0.5.

            height       An mfArray containing a real number specifies the height of the
                         cylinder. By default, argument height is set to 1.0.

            color        An mfArray containing a string specifies the color, e.g.
                         “y”, or a 1-by-3 mfArray contains the rgb codes. By
                         default, argument color is set to grey.
       resolution An mfArray contains the number of polygons used for modeling
                         the circular object. The higher the polygon number, the
                         smoother a sphere appears. The lower the polygon number, the
                         faster a sphere is rendered. By default, the sphere is set to a
                         resolution = 64.




      h = mfCylinder(...)
      • Handle h retrieves a handle to the cylinder object created by mfCylinder(...).
                                                        Chapter 9 Visualization Routines    563


•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the cylinder object through handle h with procedure msGSet.

The properties available are:

1.location
2.radius
3.height
4.color
5.resolution



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: zeros, color
zeros = (/ 0, 0, 0 /)
color = (/ 1, 0, 0 /)
! Cube with center at (0,0,0), radius = 0.5, height = 0.5,
! and red in color
call msCylinder(zeros, mf(0.5), mf(0.5), color)
! Pause the program for display
call msViewPause()
! Deallocate mfArrays zeros, color
call msFreeArgs(zeros, color)
end program


Result
564      MATFOR 4 in Fortran Reference Guide




      See Also
      mfSphere, mfCone, mfCube
                                                        Chapter 9 Visualization Routines   565



mfCone, msCone
Draw a cone.


Module
fgl


Syntax
h = mfCone([loc][, radius][, height][, color][, resolution])

call msCone([loc][, radius][, height][, color][, resolution])



Descriptions
Procedure mfCone draws a cone with center at loc, radius specified by radius, height
specified by height, color specified by color and resolution level specified by
resolution. All arguments are optional.
call msCone(loc, radius, height, color, resolution)

h = mfCone(...)
• Handle h retrieves a handle to the cone object created by mfCone(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the cone object through handle h with procedure msGSet.

The properties available are:

1.location
2.radius
3.height
4.color
5.resolution



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: zeros, color
zeros = (/ 0., 0., 0. /)
color = (/ 0., 1., 0. /)
! Cone with location (0,0,0), radius = 0.5, height = 1.0,
566      MATFOR 4 in Fortran Reference Guide

      ! color = green.
      call msCone(zeros, mf(0.5), mf(1.0), color)
      ! Pause the program for display
      call msViewPause()
      ! Deallocate mfArrays
      call msFreeArgs(zeros, color)
      end program


      Result




      See Also
      mfCylinder, mfSphere, mfCube
                                                               Chapter 9 Visualization Routines   567



mfAxisMark, msAxisMark
3-directional axis mark on arbitrary point.


Module
fgl


Syntax
h = mfAxisMark([loc][, length][, radius])

call msAxisMark([loc][, length][, radius])



Descriptions
Procedure mfAxisMark draws a 3-directional axis mark on any arbitrary point in the plot
space.

call msAxisMark(loc, length, radius)
• Draws a 3-directional axis mark on the point specified by argument loc with length
    specified by argument length and thickness specified by argument radius.
•   By default, location is [0, 0, 0], length is 1 and radius is 0.1.

h = mfAxisMark(...)
• Handle h retrieves a handle to the axis mark object created by mfAxisMark(...).
•   Alternatively, use procedure h = mfGetCurrentDraw() to retrieve the handle of the
    current graphics object.

You can specify properties of the molecules object through handle h with procedure msGSet.

The properties available are:

1. symmetric = "on" or "off". If symmetric is on, the axes extend to negative values.
2. location
3. length
4. radius



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: cubesize, center, h, loc, length, radius
568      MATFOR 4 in Fortran Reference Guide

      cubesize = (/4, 4, 4/)
      center = (/0, 0, 0/)
      loc = mf((/-1.0d0, -3.0d0, 2.1d0/))
      length = 1
      radius = 0.05
      h = mfCube(center, cubesize, 'b')
      call msObjOrientation(h, 15, 15, 15)
      call msHold('on')
      h = mfAxisMark(loc, length, radius)
      call msObjOrientation(h, 15, 15, 15)
      call msGSet(h,'symmetric',mf(1))
      call msViewPause()
      call msFreeArgs(cubesize, center, h)
      end program example


      Result




      See Also
                   Chapter 9 Visualization Routines   569




Property Setting
570       MATFOR 4 in Fortran Reference Guide



      msGSet
      Set property of specified graph.


      Module
      fgl


      Syntax
      call msGSet(handle, property, value[, property2, value2, ...])



      Descriptions
      Procedure msGSet sets the property of a graphics object whose handle is given by handle.
      You can set various properties of a graph object through the procedure.

      call msGSet(handle, property, value)
      • Argument property is a string specifying the target property to be updated. Argument
          value is an mfArray containing the data to be updated. For example, you can input
          "xdata" for x-coordinate, "ydata" for y-coordinate, "zdata" for z-coordinate if
          you want to update the coordinates of a graphics object.

      call msGSet(handle, property, value, property2, value2, ...)
      • Multiple properties can be updated in one statement as above.
      •   The table below lists the common properties available for updating through procedure
          msGSet.


               Property      Description                         Apply to

               "xdata"       Specify x data as target for        Almost all two-dimensional
                             updating                            and three-dimensional
                                                                 graphics objects

               "ydata"       Specify y data as target for        Almost all two-dimensional
                             updating                            and three-dimensional
                                                                 graphics objects

               "zdata"       Specify z data as target for        Almost all three-dimensional
                             updating                            graphics objects
                                                             Chapter 9 Visualization Routines        571


         "cdata"        Specify color vector, c as target     Almost all two-dimensional
                        for updating                          and three-dimensional
                                                              graphics objects

         "udata"        Specify velocity in x-direction, u    mfQuiver, mfQuiver3,
                        as target for updating.               mfStreamLine, etc.

         "vdata"        Specify velocity in y-direction, v    mfQuiver, mfQuiver3,
                        as target for updating.               mfStreamLine, etc.

         "wdata"        Specify velocity in z-direction, w    mfQuiver3,
                        as target for updating.               mfStreamLine


Note: Not all of the available properties are listed here. Please refer to the description of each
graphical procedure for a supplementary list of properties.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray):: x, y, h
integer::i
!Construct and initialize the mfArrays for plotting.
x = mfLinspace(-MF_PI, MF_Pi, 30)
y = mfCos(x)
!Plot the initial figure and get its handle.
call msPlot(x, y, 'ro')
h=mfGetCurrentDraw()
!Set up an iteration loop for the range of data you
!wish to observe through animation.
Do i=1,1000
  y=mfCos(x+0.02d0*i)
   !Within the iteration loop, use procedure msGSet to update
   !the targeted data of the current draw.
   call msGSet(h, 'ydata', y)
   !Update the current Graphics Viewer by using procedure
   !msDrawNow.
   call msDrawNow()
end do
!Pause the program to observe figure.
call msViewPause()
!Deallocate mfArray
call msFreeArgs(x, y, h)
572      MATFOR 4 in Fortran Reference Guide

      end program example


      Result




      See Also
                                                            Chapter 9 Visualization Routines        573



msDrawMaterial
Set transparency, ambient, diffuse and specular reflectance of a draw object.


Module
fgl


Syntax
call msDrawMaterial(handle, target, property1, value1[, property2,
value2, ...])



Descriptions
Procedure msDrawMaterial sets the color component, transparency reflectance, ambient
reflectance, diffuse reflectance and specular reflectance of the draw object's surface and edges.
Each reflectance is specified as a level of intensity ranging from 0 to 100. The resultant
lighting effect is produced by applying the intensity levels of the reflectance to the color
component.

For example, if the intensity of the draw object's ambient reflectance is set to be 50 and the
color component is set to be [1, 1, 1], the draw object's ambient color component becomes
[0.5, 0.5, 0.5].

call msDrawMaterial(handle, target, property, value)
• You can perform the operation on the draw object's surface, edge or both by specifying
    argument target as "surf", "edge" or "both".
•   Arguments property and value can be:

         Property          Meaning

          “trans”
                           Transparency reflectance. The
                           corresponding argument value can be an
                           integer or an mfArray containing an integer
                           that ranges from 0 to 100.

         “ambient”
                           Ambient reflectance. The corresponding
                           argument value can be an integer or an
                           mfArray containing an integer that ranges
                           from 0 to 100.

         “diffuse”         Diffuse reflectance. The corresponding argument
                           value can be an integer or an mfArray
                           containing an integer that ranges from 0 to
574      MATFOR 4 in Fortran Reference Guide


                               100.
           “specular”
                                Specular reflectance. The corresponding
                                argument value can be an integer or an
                                mfArray containing an integer that ranges
                                from 0 to 100.

                “color”
                                Color component. The corresponding
                                argument value can be an mfArray containing
                                the rgb vector [r, g, b].

           “colormap”
                                Turn the colormap on or off. The
                                corresponding argument value can be an
                                mfArray containing the string that is
                                specified as “on” or “off”.

            “visible”
                                Turn the surface or edge on or off. The
                                corresponding argument value can be an
                                mfArray containing the string that is
                                specified as “on” or “off”.

             “smooth”
                                Interpolate to Gouraud shading. The
                                corresponding argument value can be an
                                mfArray containing the string that is
                                specified as “on” or “off”.

          “line_width”
                                Line width of edge. The corresponding
                                argument value can be an integer or an
                                mfArray containing an integer.

          “line_style”
                                Line style of edge. The corresponding
                                argument value can be an mfArray containing
                                a string that is specified as "solid",
                                "dashed", "dotted" or "dashdot".




      Example

      Code
      program example
      use fgl
      use fml
                                              Chapter 9 Visualization Routines   575

implicit none
type (mfArray) :: a, x, y, z, h, v
a = mfLinspace(-3, 3, 30)
call msMeshGrid( mfOut(x, y), a)
z = mfSin(x) * mfCos(y) / ( x*(x-0.5d0) + (y+0.5d0)*y + 1)
h = mfSurf(x, y, z)
call msDrawMaterial(h, mf('surf'), mf('visible'), mf('on'), &
                                  mf('smooth'), mf('on'),                  &
                                  mf('colormap'), mf('on'), &
                                  mf('ambient'), mf(0),     &
                                  mf('diffuse'), mf(75),                   &
                                  mf('specular'), mf(25))
call msDrawMaterial(h, mf('edge'), mf('color'), mf((/1,0,0/)),             &
                                  mf('smooth'), mf('on'),                  &
                                  mf('colormap'), mf('off'),               &
                                  mf('ambient'), mf(0),     &
                                  mf('diffuse'), mf(0),     &
                                  mf('diffuse'), mf(0),     &
                                  mf('specular'), mf(0),                   &
                                  mf('trans'), mf(90))
!Set name of draw object
call msSetDrawName(h,'My Surf 1')
call msViewPause()
!Get Object handle's status
v = mfIsValidDraw(h)
if(mfAny(v)) print *,'Draw object is valid'
!Remove Object handle
call msRemoveDraw(h)
v = mfIsValidDraw(h)
if(.not.mfAny(v))print *,'Draw object is invalid'
call msFreeArgs(a, x, y, z, h, v)
end program example


Result




See Also
576       MATFOR 4 in Fortran Reference Guide



      msDrawTexture
      Set texture mapping.


      Module
      fgl


      Syntax
      call msDrawTexture(handle, property1, value1[, property2, value2, ...])



      Descriptions
      Procedure msDrawTexture places a texture on a graphics object by mapping the texture
      coordinates to the object's coordinates. The texture coordinates comprise of two coordinates,
      namely the s- and t-coordinates, which are vectors of values ranging from 0 to 1. They
      correspond to the object's x- and y-coordinates in order to determine which texel (texture
      element) in the texture is mapped to which vertex.

      call msDrawTexture(handle, property, value)
      • Arguments property and value can be:

          Property           Meaning

          "enable"        Enabling or disabling the texture-mapping. The
                          corresponding argument value can be “on” or
                          “off”.
            "map"         Specifying the texture file. The corresponding
                          argument value specifies the name of a bitmap
                          file (e.g. texture.bmp).
         "coord_s"        Texture’s s-coordinate. The corresponding argument
                          value is a vector of values ranging from 0 to
                          1, which specifies the way of mapping.
         "coord_t"        Texture’s t-coordinate. The corresponding
                          argument value is a vector of values ranging
                          from 0 to 1, which specifies the way of mapping.




      Example

      Code
      program example
                                           Chapter 9 Visualization Routines   577

use fgl
use fml
implicit none
type (mfArray) :: a, x, y, z, h
a = mfLinspace(-3, 3, 30)
call msMeshGrid( mfOut(x, y), a)
z = mfSin(x) * mfCos(y) / ( x*(x-0.5d0) + (y+0.5d0)*y + 1)
h = mfSurf(x, y, z)
call msDrawTexture(h, 'map', 'ancad.bmp')
call msDrawMaterial(h, mf('surf'), mf('smooth'), mf('on'),              &
                                  mf('colormap'), mf('on'), &
                                  mf('ambient'), mf(0),     &
                                  mf('diffuse'), mf(15),                &
                                  mf('specular'), mf(85))
call msDrawMaterial(h, 'edge', 'visible', 'off')
call msViewPause()
call msFreeArgs(a, x, y, z, h)
end program example


Result




See Also
578       MATFOR 4 in Fortran Reference Guide



      mfIsValidDraw
      Check validity of draw object.


      Module
      fgl


      Syntax
      validity = mfIsValidDraw(handle)



      Descriptions
      Procedure mfIsValidDraw returns the validity of a draw object which is associated with
      argument handle. The output is an mfArray containing logical data. It returns true if the
      draw object still exists, false otherwise.



      Example
      To be referred to msDrawMaterial

      See Also
                                                     Chapter 9 Visualization Routines   579



mfGetCurrentDraw
Return handle of current draw object.


Module
fgl


Syntax
handle = mfGetCurrentDraw()



Descriptions
Procedure mfGetCurrentDraw returns the handle of current draw object.



Example

Code
program example
use fml
use fgl
implicit none
type (mfArray) :: a, b, c, x, y, z, theta, phi, h
integer :: i
a = mfLinspace(-MF_PI/2, MF_PI/2, 31)
b = mfLinspace(-MF_PI, MF_PI, 31)
c = mfOnes(31, 31)
call msMeshgrid(mfout(phi, theta), a, b)
x = mfCos(phi)*mfCos(theta)
y = mfCos(phi)*mfSin(theta)
z = mfSin(phi)
! Plot the graph you wish to animate
call msSurf(x, y, z)
call msAxis(mf((/-MF_PI, MF_PI, -MF_PI, MF_PI, -MF_PI, MF_PI/)))
call msShading('interp')
call msAxis('off')
! Get handle of current draw
h = mfGetCurrentDraw()
! Use a Do Loop to change the value of x, y and z.
do i =1 ,30
  x = mfCos(phi)*mfCos(theta+i*0.1d0)
  y = mfCos(phi)*mfSin(theta+i*0.1d0)+0.05d0*i
  z = mfSin(phi)+mfSin(c*i)
  ! Set the x,y, and z-data of the current graph
  call msGSet(h, mf('xdata'), x, mf('ydata'), y, mf('zdata'), z)
  ! Draw graph on Graphics Viewer
  call msDrawNow()
end do
! Pause program to view graph. If this statement is
! not added, the Graphics Viewer closes once animation
! is completed.
Call msViewPause()
580      MATFOR 4 in Fortran Reference Guide

      ! Deallocate mfArrays
      Call msFreeArgs(a, b, c, x, y, z, theta, phi, h)
      end program example


      See Also
                                                             Chapter 9 Visualization Routines   581



msRemoveDraw
Remove draw object from plot space.


Module
fgl


Syntax
call msRemoveDraw(handle1[, handle2, ...])



Descriptions
Procedure msRemoveDraw removes specific draw objects from the plot space.

call msRemoveDraw(handle1, handle2, ...)
Removes the draw objects associated with the handles specified in the arguments.



Example
To be referred to msDrawMaterial

See Also
582       MATFOR 4 in Fortran Reference Guide



      msSetDrawName
      Name draw object.


      Module
      fgl


      Syntax
      call msSetDrawName(handle, name)



      Descriptions
      Procedure msSetDrawName sets the name of the draw object associated with argument
      handle. By default, the name of a draw object is set to its draw type followed by an
      incremental integer.

      The purpose of giving each draw object a name is to distinguish between the draw objects. It
      allows you to perform operations (e.g. custom shading or view draw object data) on a specific
      draw object from object list view window when there are multiple draw objects presented in
      the same subplot. All the draw objects are listed in Object List View Window.



      Example
      To be referred to msDrawMaterial

      See Also
                               Chapter 9 Visualization Routines   583




Graphics Viewer Manipulation
584       MATFOR 4 in Fortran Reference Guide



      msPrintPreview
      Pop up print preview dialog box.


      Module
      fgl


      Syntax
      call msPrintPreview()



      Descriptions
      Procedure msPrintPreview pops up a dialog box showing current figure as it will be
      printed.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type (mfArray) :: x, y, z
      !Create surface data for plot
      call msCreateSurfData( mfOut(x, y, z), 1, 30, 30 )
      !Plot a surf using mfArray x, y and z
      call msSubplot(1,2,1)
      call msSurf(x, y, z)
      call msSubplot(1,2,2)
      call msSolidContour(x, y, z)
      !Show print preview window
      call msPrintPreview()
      !Pause to display the graph
      call msViewPause()
      end program example


      Result
           Chapter 9 Visualization Routines   585




See Also
586       MATFOR 4 in Fortran Reference Guide



      msEditorDrawList
      Pop up draw-list editor.


      Module
      fgl


      Syntax
      call msEditorDrawList()



      Descriptions
      Procedure msEditorDrawList creates a draw-list dialog box that enables the user to edit
      objects' material, colormap, and transformation settings from the global scope.



      Example
      Code
      Please refer to the gsurf demo under <MATFOR4>\gui_demo

      Result




      See Also
                                                     Chapter 9 Visualization Routines    587



msEditorMaterial
Pop up material editor.


Module
fgl


Syntax
call msEditorMaterial()



Descriptions
Procedure msEditorMaterial creates a dialog box that enables the user to edit objects'
material settings.



Example

Code
Please refer to the gsurf demo under <MATFOR4>\gui_demo


Result




See Also
588       MATFOR 4 in Fortran Reference Guide



      msEditorColormap
      Pop up colormap editor.


      Module
      fgl


      Syntax
      call msEditorColormap()



      Descriptions
      Procedure msEditorColormap creates a dialog box that enables the user to edit objects'
      colormap settings.



      Example

      Code
      Please refer to the gsurf demo under <MATFOR4>\gui_demo


      Result




      See Also
                                                      Chapter 9 Visualization Routines    589



msEditorTransform
Pop up transformation editor.


Module
fgl


Syntax
call msEditorTransform()



Descriptions
Procedure msEditorTransform creates a dialog box that enables the user to edit objects'
transformation settings.



Example

Code
Please refer to the gsurf demo under <MATFOR4>\gui_demo


Result




See Also
590       MATFOR 4 in Fortran Reference Guide



      msEditorAxis
      Pop up axis editor.


      Module
      fgl


      Syntax
      call msEditorAxis()



      Descriptions
      Procedure msEditorAxis creates a dialog box that enables the user to edit objects' axis
      settings.



      Example

      Code
      Please refer to the gsurf demo under <MATFOR4>\gui_demo


      Result




      See Also
                                                     Chapter 9 Visualization Routines    591



msEditorColorbar
Pop up colorbar editor.


Module
fgl


Syntax
call msEditorColorbar()



Descriptions
Procedure msEditorColorbar creates a dialog box that enables the user to edit colorbar
settings.

Example

Code
Please refer to the gsurf demo under <MATFOR4>\gui_demo


Result




See Also
592       MATFOR 4 in Fortran Reference Guide



      msEditorBackground
      Pop up background editor.


      Module
      fgl


      Syntax
      call msEditorBackground()



      Descriptions
      Procedure msEditorBackground creates a dialog box that enables the user to manipulate
      background colors.



      Example

      Code
      Please refer to the gsurf demo under <MATFOR4>\gui_demo


      Result




      See Also
             Chapter 9 Visualization Routines   593




Simple GUI
594       MATFOR 4 in Fortran Reference Guide



      msShowMessage
      Pop up message dialog box.


      Module
      fgl


      Syntax
      call msShowMessage(msg)



      Descriptions
      Procedure msShowMessage pops up a dialog box displaying a message.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
            call msShowMessage("Show Message Test")
      end program


      Result




      See Also
                                                          Chapter 9 Visualization Routines      595



mfInputString
Pop up input string insertion dialog box.


Module
fgl


Syntax
call msInputString(mfOut(str, is_ok),msg ,string_value)



Descriptions
Procedure mfInputString pops up a dialog box displaying the prompt msg, with
string_value in the textbox. This procedure has two return arguments; str returns the
entered string value, is_ok returns 1 if the OK button is clicked, and 0 if the Cancel button
is clicked.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: str, is_ok;
call msInputString(mfOut(str, is_ok), "Input Name", "Ancad")
call msShowMessage(str);
call msDisplay(is_ok,"Is ok")
end program


Result




See Also
596       MATFOR 4 in Fortran Reference Guide



      mfInputValue
      Pop up value insertion dialog box.


      Module
      fgl


      Syntax
      call msInputValue(mfOut(num, is_ok),msg ,number_value)



      Descriptions
      Procedure mfInputValue pops up a dialog box displaying the prompt msg, with
      number_value in the textbox. This procedure has two return arguments; num returns the
      entered number value, is_ok returns 1 if the OK button is clicked, and 0 if the Cancel button
      is clicked.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: val, is_ok;
      call msInputValue(mfOut(val, is_ok), "Input Number", 10)
      call msDisplay(val, "Number", is_ok, "Is ok")
      end program


      Result




      See Also
                                                          Chapter 9 Visualization Routines      597



mfInputVector
Pop up vector insertion dialog box.


Module
fgl


Syntax
call msInputVector(mfOut(vec, is_ok),msg ,vector_value)



Descriptions
Procedure mfInputVector pops up a dialog box displaying the prompt msg, with
vector_value in the textbox. This procedure has two return arguments; vec returns the
entered vector value, is_ok returns 1 if the OK button is clicked, and 0 if the Cancel button
is clicked.



Example

Code
program example
use fml
use fgl
implicit none

type(mfArray) :: vec, is_ok;
call msInputVector(mfOut(vec,is_ok), "Input Vector", mf((/1, 2, 3, 4,
5/)))
call msDisplay(vec,"Vector",is_ok,"Is ok")
end program


Result




See Also
598       MATFOR 4 in Fortran Reference Guide



      mfInputMatrix
      Pop up matrix insertion dialog box.


      Module
      fgl


      Syntax
      call msInputMatrix(mfOut(matrix, is_ok),msg ,matrix_value)



      Descriptions
      Procedure mfInputMatrix pops up a dialog box displaying the prompt msg, with
      matrix_value in the table. This procedure has two return arguments; matrix returns the
      entered matrix value, is_ok returns 1 if the OK button is clicked, and 0 if the Cancel button
      is clicked.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: x, m, is_ok
      real(8) :: a(5, 3)
      integer :: i
      x=reshape((/(i, i=1,15)/),(/5,3/))
      call msInputMatrix(mfOut(m,is_ok), "Input Matrix", x)
      call msDisplay(m,"Matrix",is_ok,"Is ok")
      end program


      Result
           Chapter 9 Visualization Routines   599




See Also
600       MATFOR 4 in Fortran Reference Guide



      mfFileDialog, mfOpenFileDialog
      Pop up file open dialog box.


      Module
      fgl


      Syntax
      string = mfFileDialog(filename, filefilter)



      Descriptions
      Procedure mfFileDialog pops up a file open dialog box for locating a file.



      Example

      Code
      program example
      use fml
      use fgl
      implicit none
      type(mfArray) :: a, str, is_ok;
            str = mfFileDialog("x.txt", "*.txt")
            a = mfLoadAscii(str)
            call msDisplay(a, "a")
          call msSaveFileDialog(mfOut(str, is_ok), "y.txt", "*.txt")
          !If user press save button
          if (mfAny(is_ok)) then
              a = a + 1
              call msSaveAscii(str, a)
              call msDisplay(mfLoadAscii(str), "a+1", is_ok, "Is ok")
          end if
      end program


      Result
                   Chapter 9 Visualization Routines   601




See Also
mfSaveFileDialog
602       MATFOR 4 in Fortran Reference Guide



      mfSaveFileDialog
      Pop up file save dialog box.


      Module
      fgl


      Syntax
      call msSaveFileDialog(mfOut(str,is_ok),filename, filefilter)



      Descriptions
      Procedure mfSaveFileDialog pops up a file-save dialog box for locating the directory
      the file filename will be saved. This procedure has two return arguments; str returns the
      directory of the saved file, is_ok returns 1 if the OK button is clicked, and 0 if the Cancel
      button is clicked.



      Example
      To be referred to mfFileDialog

      See Also
      mfFileDialog
                                                    Chapter 9 Visualization Routines   603



mfInputYesNo
Pop up yes-no query dialog box.


Module
fgl


Syntax
value = mfInputYesNo(msg, default_value)



Descriptions
Procedure mfInputYesNo pops up a yes-no dialog box. The chosen option is passed back
to the output argument value.

Argument default_value can be either 0 or 1.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray) :: val;
      val = mfInputYesNo("yes or no")
      if(mfAny(val))then
         print *,'You press Yes.'
      else
         print *,'You press No.'
      end if
      call msDisplay(val, "val")
end program


Result




See Also
604   MATFOR 4 in Fortran Reference Guide
                                                         Chapter 10 MATFOR Extensions   605



CHAPTER 10


Extensions of MATFOR
This chapter introduces advanced MATFOR routines that enable users to use
external data or programs.




Tecplot FileIO

mfTecOpenFile/                 Open Tecplot files for reading or writing
mfTecCloseFile

mfTecReadTitle/                Read and write title of Tecplot files.
mfTecWriteTitle

mfTecReadVarName/              Retrieve data information from Tecplot files.

mfTecReadBlock

                               Retrieve number of variables and blocks from
mfTecReadVarCount/
                               Tecplot files.
mfTecReadBlockCount

mfTecWriteVarNames             Write variable names to Tecplot files.

mfTecWriteIJKBlock/            Write data information to Tecplot files.
mfTecWriteTriBlock/
mfTecWriteTetBlock

MATLAB Interface

mfDoMATLAB                     Execute MATLAB functions.

mfMATLABServer                 Perform MATLAB actions in MATFOR programs.
606     MATFOR 4 in Fortran Reference Guide




      Tecplot FileIO
                                                            Chapter 10 MATFOR Extensions           607



mfTecOpenFile, msTecCloseFile
Open a Tecplot file for reading or writing.


Module
fgl


Syntax
h = mfTecOpenFile( filename, 'r' )
h = mfTecOpenFile( filename, 'w' )

call msTecCloseFile(h)



Descriptions
Procedure mfTecOpenFile opens a Tecplot file for reading 'r', or writing 'w'. This
procedure returns a file handler. When opening a file in write mode, the file will be created
automatically if it does not exist. When finishing working with the file, you can close it using
procedure msTecCloseFile.



Example

Code
Program TecPlot
use fml
use fgl
implicit none
type(mfArray)      :: tri, tet, x, y, z, c
type(mfArray)      :: h, tec
type(mfArray)      :: fname, title
type(mfArray)      :: values, atype
integer(4) ::      nb, nv
! create unstructure tetra data
x = mfRand(500,1)
y = mfRand(500,1)
z = mfRand(500,1)
c = 1 - (x-0.5d0)**2d0 - (y-0.5d0)**2d0 - (z-0.5d0)**2d0
tet = mfGetDelaunay3(x, y, z)
! write to Tecplot file
tec = mfTecOpenFile( 'tetsurf.plt', 'w' )
call msTecWriteTitle( tec, 'TET-SURF' )
call msTecWriteVarNames( tec, 'X', 'Y', 'Z', 'C' )
call msTecWriteTetBlock( tec, tet, x, y, z, c )
call msTecCloseFile( tec )
!read from Tecplot file
tec = mfTecOpenFile( 'tetsurf.plt', 'r' )
title = mfTecReadTitle( tec )
nb = mfTecReadBlockCount( tec )
nv = mfTecReadVarCount( tec )
call msDisplay( title, 'title', mf(nb), 'nb', mf(nv), 'nv' )
608      MATFOR 4 in Fortran Reference Guide

      call msTecReadBlock( mfOut( values, atype, tri ), tec, 1 )
      call msTecCloseFile( tec )
      x = mfS( values, MF_COL, 1.to.1          )
      y = mfS( values, MF_COL, 2.to.2          )
      z = mfS( values, MF_COL, 3.to.3          )
      c = mfS( values, MF_COL, 4.to.4          )
      call msTetSurf( tri, x, y, z, c          )
      call msTitle( title )
      call msViewPause
      call msFreeArgs(tri, tet, x, y, z, c)
      call msFreeArgs(h, tec, fname, title, values, atype)
      end Program TecPlot


      See Also
                                                       Chapter 10 MATFOR Extensions       609



mfTecReadTitle, mfTecWriteTitle
Read and write title of a Tecplot file.


Module
fgl


Syntax
title = mfTecReadTitle( h )

call msTecReadTitle(mfOut(title),h)
call msTecWriteTitle( h, title )



Descriptions
Procedure mfTecReadTitle reads the title from a Tecplot file. It returns a string or an
mfArray that contains a string.

Procedure mfTecWriteTitle appends the title to the Tecplot file given file handler h.



Example
To be referred to mfTecOpenFile

See Also
mfTecOpenFile, mfTecCloseFile
610       MATFOR 4 in Fortran Reference Guide



      msTecReadVarName, msTecReadBlock
      Retrieve data information from a Tecplot file.


      Module
      fgl


      Syntax
      call msTecReadVarName( mfOut( varname, min_max ), h, var_idx)
      call msTecReadBlock( mfOut( values, type, tri ), h, block_idx)



      Descriptions
      Procedure msTecReadVarName retrieves variable information from a Tecplot file given a
      file handler h and the variable index. It returns a variable name and a 2 by 1 vector that
      contains minimum and maximum values of the variable.

      Procedure mfTecReadBlock retrieves block information from a Tecplot file given a file
      handler h and the block index. It returns block values, type of polyhedrons and connectivity
      values in the shapes specified below:

       Element Type           values            type                 tri
       Triangle               nn x nv           MF_TEC_TRI           ne x 3
       Quadrilateral          nn x nv           MF_TEC_QUAD          ne x 4


       Tetrahedron            nn x nv           MF_TEC_TET           ne x 4


       Brick                  nn x nv           MF_TEC_BRICK         ne x 8


       IJK                    m x n x p x nv    MF_TEC_IJK           Mf() or
                                                                     MF_NULL


      *nn = number of nodes.
      *nv = number of variables.
      *ne = number of elements.
      *m = number of points in 1st dimension.
      *n = number of points in 2nd dimension.
      *p = number of points in 3rd dimension.



      Example

      Code
                                             Chapter 10 MATFOR Extensions   611

Program tecread
use fml
use fgl
implicit none
type(mfArray)   :: x, y, z, c, h
type(mfArray)   :: fname, title
type(mfArray)   :: tec
type(mfArray)   :: values1, values2, atype, tri
type(mfArray)   :: min_max
integer(4) ::   nb, nv, tectype
! ******************************************************************
! load data
! ******************************************************************
fname = mfFileDialog( '', '*.plt;*.dat' )
tec = mfTecOpenFile( fname, mf('r') )
title = mfTecReadTitle( tec )
nb = mfTecReadBlockCount( tec )
nv = mfTecReadVarCount( tec )
call msDisplay( title, 'title', mf(nb), 'nb', mf(nv), 'nv' )
if (nb<1 .or. nv<3) then
   call msShowMessage( 'No valid block')
   stop
end if
call   msTecReadBlock( mfOut( values1, atype, tri ), tec, 1 )
call   msTecReadVarName(mfOut( values2, min_max ), tec, 4)
call   msGDisplay( values1, 'values1' )
call   msDisplay( atype, 'atype' )
call msTecCloseFile( tec )
! ******************************************************************
! draw data
! ******************************************************************

tectype = atype
select case (tectype)
case (MF_TEC_IJK)
   x = mfS( values1, MF_COL, MF_COL, MF_COL, 1.to.1 )
   y = mfS( values1, MF_COL, MF_COL, MF_COL, 2.to.2 )
   z = mfS( values1, MF_COL, MF_COL, MF_COL, 3.to.3 )
   if (nv<4) then
       c = z
   else
       c = mfS( values1, MF_COL, MF_COL, MF_COL, 4.to.4 )
   end if
   call msSurf( x, y, z, c )
case (MF_TEC_TRI, MF_TEC_QUAD, MF_TEC_TET, MF_TEC_BRICK)
   x = mfS( values1, MF_COL, 1.to.1 )
   y = mfS( values1, MF_COL, 2.to.2 )
   z = mfS( values1, MF_COL, 3.to.3 )
   if (nv<4) then
       c = z
   else
       c = mfS( values1, MF_COL, 4.to.4 )
   end if
   if (tectype==MF_TEC_TRI .or. tectype==MF_TEC_QUAD) then
       call msTriSurf( tri, x, y, z, c )
       call msGDisplay( tri, 'tri' )
   else
       call msTetSurf( tri, x, y, z, c )
       call msGDisplay( tri, 'tet' )
   end if
end select
612      MATFOR 4 in Fortran Reference Guide


      call msTitle( title )
      call msViewPause
      end Program tecread


      See Also
      msTecWriteVarNames, mfTecWriteIJKBlock, mfTecWriteTriBlock,
      mfTecWriteTetBlock
                                                           Chapter 10 MATFOR Extensions   613



mfTecReadVarCount, mfTecReadBlockCount
Retrieve number of variables and blocks from a Tecplot file.


Module
fgl


Syntax
nv = mfTecReadVarCount( h )
nb = mfTecReadBlockCount( h )



Descriptions
Procedure mfTecReadVarCount returns a scalar mfArray containing number of variables
in the Tecplot file specified by the file handler h.

Procedure mfTecReadBlockCount returns a scalar mfArray containing number of blocks
in the Tecplot file specified by the file handler h.



Example
To be referred to mfTecReadVarName

See Also
msTecReadVarName, msTecReadBlock
614       MATFOR 4 in Fortran Reference Guide



      msTecWriteVarNames
      Write variable names to a Tecplot file.


      Module
      fgl


      Syntax

      call msTecWriteVarNames( h, name1[, name2, name3...] )



      Descriptions
      Procedure msTecWriteVarNames writes variable names to a Tecplot file given the file
      handler h.



      Example
      To be referred to mfTecWriteIJKBlock

      See Also
      msTecReadVarName
                                                            Chapter 10 MATFOR Extensions        615



msTecWriteIJKBlock, msTecWriteTriBlock,

msTecWriteTetBlock
Write data information to a Tecplot file.


Module
fgl


Syntax

call msTecWriteIJKBlock( h, var1[, var2, var3...])
call msTecWriteTriBlock( h, tri[, var1, var2, var3...])
call msTecWriteTetBlock( h, tet[, var1, var2, var3...])



Descriptions
Procedure msTecWriteIJKBlock writes data values to a Tecplot file given the file
handler h.
• The shapes of all variables should be conformed.

Procedure msTecWriteTriBlock writes data values and connectivity values to a Tecplot
file given the file handler h.
• tri is a surface object defined by an m-by-n face matrix, where m is the number of polygons
    to be drawn and n is the number of edges of each polygon.
•   The shapes of all variables should be conformed.

Procedure msTecWriteTetBlock writes data values and connectivity values to a Tecplot
file given the file handler h.
• tet is a polyhedral object defined by an m-by-k cell matrix, where m is the number of
    polyhedrons to be drawn and k is the number nodes of each polyhedron.
•   The shapes of all variables should be conformed.



Example

Code
Program tecwrite
use fml
use fgl
implicit none
type(mfArray) :: tri, tet, x, y, z, c
type(mfArray) :: h, tec
!******************************************************************
616         MATFOR 4 in Fortran Reference Guide

      ! create surf data
      !******************************************************************
      call msFigure('Surf')
      call msCreateSurfData( mfOut( x, y, z ), 6, 30, 28 )
      c = mfCreateSurfData( 1, 30, 28 )
      h = mfSolidContour3( x, y, z, c )
      call msDrawMaterial( h, 'surf', 'smooth', 'on' )
      call msDrawMaterial( h, mf('edge'), mf('trans'), mf(70) )
      !******************************************************************
      ! write to Tecplot
      !******************************************************************
      tec = mfTecOpenFile( 'surf.plt', 'w' )
      call msTecWriteTitle( tec, 'SURF' )
      call msTecWriteVarNames( tec, 'X', 'Y', 'Z', 'C' )
      call msTecWriteIJKBlock( tec, x, y, z, c )
      ! write multi-block
      call msTecWriteIJKBlock( tec, x, y, z * 2, c )
      call msTecCloseFile( tec )
      call msDrawNow()
      call msShowMessage( 'Data has been written to the Tecplot file: surf.plt' )
      !******************************************************************
      ! create unstructure surf data
      !******************************************************************
      call msFigure('TriSurf')
      x =    mfRand(400,1)
      y =    mfRand(400,1)
      z =    1 - (x-0.5d0)**2d0 - (y-0.5d0)**2d0
      c =    mfSin(x) * mfCos(y) * z
      tri    = mfGetDelaunay(x, y)
      h = mfTriContour(tri, x, y, z, c)
      call msDrawMaterial( h, 'surf', 'smooth', 'on' )
      call msDrawMaterial( h, mf('edge'), mf('trans'), mf(70) )
      !******************************************************************
      ! write to Tecplot
      !******************************************************************
      tec = mfTecOpenFile( 'trisurf.plt', 'w' )
      call msTecWriteTitle( tec, 'TRI-SURF' )
      call msTecWriteVarNames( tec, 'X', 'Y', 'Z', 'C' )
      call msTecWriteTriBlock( tec, tri, x, y, z, c )
      call msTecCloseFile( tec )
      call msDrawNow()
      call msShowMessage( 'Data has been written to the Tecplot file:
      trisurf.plt' )
      !******************************************************************
      ! create unstructure tetra data
      !******************************************************************
      call msFigure('TetSurf')
      x =    mfRand(500,1)
      y =    mfRand(500,1)
      z =    mfRand(500,1)
      c =    1 - (x-0.5d0)**2d0 - (y-0.5d0)**2d0 - (z-0.5d0)**2d0
      tet    = mfGetDelaunay3(x, y, z)
      h = mfTetContour(tet, x, y, z, c)
      call msDrawMaterial( h, 'surf', 'smooth', 'on' )
      call msDrawMaterial( h, mf('edge'), mf('trans'), mf(70) )
      !******************************************************************
      ! write to Tecplot
                                           Chapter 10 MATFOR Extensions   617

!******************************************************************
tec = mfTecOpenFile( 'tetsurf.plt', 'w' )
call msTecWriteTitle( tec, 'TET-SURF' )
call msTecWriteVarNames( tec, 'X', 'Y', 'Z', 'C')
call msTecWriteTetBlock( tec, tet, x, y, z, c )
call msTecCloseFile( tec )
call msDrawNow()
call msShowMessage( 'Data has been written to the Tecplot file:
tetsurf.plt' )

call msViewPause
end Program tecwrite


See Also
msTecReadBlock
618     MATFOR 4 in Fortran Reference Guide




      MATLAB Interface
                                                       Chapter 10 MATFOR Extensions   619



mfDoMATLAB, msDoMATLAB
Execute MATLAB functions.


Module
fml


Syntax
h = mfDoMATLAB( func_str, p[, p2, .... ])



Descriptions
Procedure mfDoMATLAB executes MATLAB functions and MATLAB script files from
MATFOR programs.

h = mfDoMATLAB(func_str, p[, p2, .... ])
• Argument func_str is a string containing the name of the MATLAB function.
•   Argument p is the input argument(s) corresponding to the function func_str.



Example

Code
program example
use fml
use fgl
implicit none
type(mfArray):: x, y
!Create 5*5 magic matrix in MATLAB and save result to mfArray x
call msMATLABServer( "setvar", "in0", 5 )
call msMATLABServer( "command", "out0 = magic( in0 );" )
call msMATLABServer(mfOut(x), "getvar", "out0" )
!x = mfDoMATLAB("magic", mf(5))
call msDisplay(x)
!Execute eig function in MATLAB
y = mfDoMATLAB("eig", x)
call msDisplay(y)
!Execute surf function in MATLAB to show magic matrix
call msDoMATLAB("surf", x)
!The same graphic result in MATFOR
call msSurf(x)
call msViewPause()
end program example


Result
620      MATFOR 4 in Fortran Reference Guide




      See Also
      mfMATLABServer
                                                       Chapter 10 MATFOR Extensions   621



mfMATLABServer, msMATLABServer
Perform MATLAB actions from MATFOR programs.


Module
fml


Syntax
call msMATLABServer(action, input[, input2, ...])

call msMATLABServer("setvar", "var", val)
val = mfMATLABServer("getvar", "var")



Descriptions
Procedure mfMATLABServer performs MATLAB actions from MATFOR programs.

call msMATLABServer(action, input[, intput2, ...])
• Argument action specifies the type of the MATLAB action used. The action types
   currently supported by MATFOR are:


      Action            Inputs            Meaning

  “visible”     “on” or “off”           Control the visibility of MATLAB Command
                                        Window.

  “command”     “command_name”          Execute the given MATLAB command.

  “script”      “file_name”             Execute the given MATLAB script file.



call msMATLABServer("setvar", "var", val)
• Set the variable to the given value val under MATLAB Command Window.

val = mfMATLABServer("getvar", "var")
• Retrieve the value of the variable under MATLAB Command Window.



Example
To be referred to mfDoMATLAB.

See Also
mfDoMATLAB
622   MATFOR 4 in Fortran Reference Guide
                    Chapter 11 MATFOR GUI System   623



CHAPTER 11


MATFOR GUI System
624     MATFOR 4 in Fortran Reference Guide




      Initialization
                                                      Chapter 11 MATFOR GUI System           625



msUIInitialize
Initialize the MATFOR GUI system.


Module
mxui


Syntax
call msUIInitialize



Descriptions
Procedure msUIInitialize is to initialize the MATFOR GUI system. It would create a
main window according to a given MFUI file. The default MFUI filename is the same as the
name of the executable but with the extension name ".mfui".

The user can assign a custom MFUI file by adding the parameters "-ui custom.mfui" in the
command line, where the name custom.mfui is the name of the custom MFUI file.

This procedure should be called before other MATFOR graphics procedures. If this procedure
is not called in the whole program and some graphics procedures are used, the system will
automatically create a MATFOR Graphic Viewer to represent the visualization results.



Example

See Also
mfUIMainLoop
626       MATFOR 4 in Fortran Reference Guide



      msUIMainLoop
      Enters the main event loop of the MATFOR GUI system.


      Module
      mxui


      Syntax
      call msUIMainLoop



      Descriptions
      Enters the main event loop and waits until the main window is closed. It is necessary to call
      this function to start event handling. The main event loop receives events from the MATFOR
      GUI system and dispatches them to the application callback functions.

      Generally speaking, procedure msUIMainLoop is a correspondence of procedure
      msUIInitialize. Users should call msUIMainLoop when all initialization is done.

      Also, users should avoid calling mfViewPause if the function mfUIMainLoop has been
      called.



      Example

      See Also
      mfUIInitialize, mfViewPause
                   Chapter 11 MATFOR GUI System   627




Property Setting
628       MATFOR 4 in Fortran Reference Guide



      mfUIGetPropertyString
      Get the string property of a UI component.


      Module
      mxui


      Syntax
      value = mfUIGetPropertyString( ctrlname, propname[, defvalue] )



      Descriptions
      Function mfUIGetPropertyString gets the string property of a given UI component.

      value = mfUIGetPropertyString( ctrlname, propname[, defvalue] )
      • ctrlname is a string name of a UI component.
      •   propname describes the property being inquired.
      •   defvalue is the default value if the inquired property doesn't exist.
      •   value is the returned value of the inquired property.



      Example

      See Also
      mfUISetPropertyString, mfUIGetPropertyInteger, mfUISetPropertyInteger,
      mfUIGetPropertyDouble, mfUISetPropertyDouble
                                                  Chapter 11 MATFOR GUI System     629



msUISetPropertyString
Set the string property of a UI component.


Module
mxui


Syntax
call msUISetPropertyString( ctrlname, propname, value )



Descriptions
Function mfUISetPropertyString sets the string property of a given UI component.

call msUISetPropertyString( ctrlname, propname, value )
• ctrlname is a string name of a UI component.
•   propname describes the property to be set.
•   value is the value the property is set to.



Example

See Also
mfUIGetPropertyString, mfUIGetPropertyInteger, mfUISetPropertyInteger,
mfUIGetPropertyDouble, mfUISetPropertyDouble
630       MATFOR 4 in Fortran Reference Guide



      mfUIGetPropertyInteger
      Get the integer property of a UI component


      Module
      mxui


      Syntax
      value = mfUIGetPropertyInteger( ctrlname, propname[, defvalue] )



      Descriptions
      Function mfUIGetPropertyInteger gets the integer property of a given UI component.

      value = mfUIGetPropertyInteger( ctrlname, propname[, defvalue] )
      • ctrlname is a string name of a UI component.
      •   propname describes the property being inquired.
      •   defvalue is the default value if the inquired property doesn't exist.
      •   value is the returned value of the inquired property.



      Example

      See Also
      mfUISetPropertyInteger, mfUIGetPropertyString, mfUISetPropertyString,
      mfUIGetPropertyDouble, mfUISetPropertyDouble
                                                  Chapter 11 MATFOR GUI System      631



msUISetPropertyInteger
Set the integer property of a UI component


Module
mxui


Syntax
call msUISetPropertyInteger( ctrlname, propname, value )



Descriptions
Function mfUISetPropertyInteger sets the integer property of a given UI component

call msUISetPropertyInteger( ctrlname, propname, value )
• ctrlname is a string name of a UI component.
•   propname describes the property to be set.
•   value is the value the property is set to.



Example

See Also
mfUIGetPropertyInteger, mfUIGetPropertyString, mfUISetPropertyString,
mfUIGetPropertyDouble, mfUISetPropertyDouble
632       MATFOR 4 in Fortran Reference Guide



      mfUIGetPropertyDouble
      Get the double property of UI component


      Module
      mxui


      Syntax
      value = mfUIGetPropertyDouble( ctrlname, propname[, defvalue] )



      Descriptions
      Function mfUIGetPropertyDouble gets the double property of a given UI component

      value = mfUIGetPropertyDouble( ctrlname, propname[, defvalue] )
      • ctrlname is a string name of a UI component.
      •   propname describes the property being inquired.
      •   defvalue is the default value if the inquired property doesn't exist.
      •   value is the returned value of the inquired property.



      Example

      See Also
      mfUISetPropertyDouble, mfUIGetPropertyString, mfUISetPropertyString,
      mfUIGetPropertyInteger, mfUISetPropertyInteger
                                                 Chapter 11 MATFOR GUI System     633



msUISetPropertyDouble
Set the double property of a UI component


Module
mxui


Syntax
call msUISetPropertyDouble( ctrlname, propname, value )



Descriptions
Function mfUISetPropertyDouble sets the double property of a given UI component

call msUISetPropertyDouble( ctrlname, propname, value )
• ctrlname is a string name of a UI component.
•   propname describes the property to be set.
•   value is the value the property is set to.



Example

See Also
mfUIGetPropertyDouble, mfUIGetPropertyString, mfUISetPropertyString,
mfUIGetPropertyInteger, mfUISetPropertyInteger
634     MATFOR 4 in Fortran Reference Guide




      Callback Setting
                                                           Chapter 11 MATFOR GUI System           635



msUISetOnClick
Set the callback function of a UI component for a Click event.


Module
mxui


Syntax
call msUISetOnClick( ctrlname, callback )



Descriptions
Function mfUISetOnClick sets the callback function of a UI component for a Click
event. Once the user clicks the UI component, the callback function will be called to handle
this event.

The Click event is available for the MenuItem, Panel, Button, Label,
RadioButton, CheckBox, ListBox, ProgressBar and Image components.

call msUISetOnClick( ctrlname, callback )
• ctrlname is a string name of a UI component.
•   callback is the callback function that handles the corresponding event. Please refer to the
    callback function section to see how to declare the prototype of a callback function.



Example

See Also
636       MATFOR 4 in Fortran Reference Guide



      msUISetOnDoubleClick
      Set the callback function of a UI component for a DoubleClick event.


      Module
      mxui


      Syntax
      call msUISetOnDoubleClick( ctrlname, callback )



      Descriptions
      Function mfUISetOnDoubleClick sets the callback function of a UI component for a
      DoubleClick event. Once the user double-clicks the UI component, the callback function
      will be called to handle this event.

      The DoubleClick event is available for the Panel, Label, ListBox,
      ProgressBar and Image components.

      call msUISetOnDoubleClick( ctrlname, callback )
      • ctrlname is a string name of a UI component.
      •   callback is the callback function that handles the corresponding event. Please refer to the
          callback function section to see how to declare the prototype of a callback function.



      Example

      See Also
                                                           Chapter 11 MATFOR GUI System           637



msUISetOnTabChanged
Set the callback function of a UI component for a TabChanged event.


Module
mxui


Syntax
call msUISetOnTabChanged( ctrlname, callback )



Descriptions
Function mfUISetOnTabChanged sets the callback function of a UI component for a
TabChanged event. Once the user switches the tabsheet of the TabControl component, the
callback function will be called to handle this event.

The TabChanged event is available for the TabControl component.

call msUISetOnTabChanged( ctrlname, callback )
• ctrlname is a string name of a UI component.
•   callback is the callback function that handles the corresponding event. Please refer to the
    callback function section to see how to declare the prototype of a callback function.



Example

See Also
638       MATFOR 4 in Fortran Reference Guide



      msUISetOnResize
      Set the callback function of a UI component for a Resize event.


      Module
      mxui


      Syntax
      call msUISetOnResize( ctrlname, callback )



      Descriptions
      Function mfUISetOnResize sets the callback function of a UI component for a Resize
      event. Once the user resizes the UI component, the callback function will be called to handle
      this event.

      The Resize event is available for the MainForm and Panel components.

      call msUISetOnResize( ctrlname, callback )
      • ctrlname is a string name of a UI component.
      •   callback is the callback function that handles the corresponding event. Please refer to the
          callback function section to see how to declare the prototype of a callback function.



      Example

      See Also
                                                           Chapter 11 MATFOR GUI System           639



msUISetOnTextChanged
Set the callback function of a UI component for a TextChanged event.


Module
mxui


Syntax
call msUISetOnTextChanged( ctrlname, callback )



Descriptions
Function mfUISetOnTextChanged sets the callback function of a UI component for a
TextChanged event. Once the user changes the text in the UI component, the callback
function will be called to handle this event.

The TextChanged event is available for the Edit and ComboBox components.

call msUISetOnTextChanged( ctrlname, callback )
• ctrlname is a string name of a UI component.
•   callback is the callback function that handles the corresponding event. Please refer to the
    callback function section to see how to declare the prototype of a callback function.



Example

See Also
640       MATFOR 4 in Fortran Reference Guide



      msUISetOnReturnPressed
      Set the callback function of a UI component for a ReturnPressed event.


      Module
      mxui


      Syntax
      call msUISetOnReturnPressed( ctrlname, callback )



      Descriptions
      Function mfUISetOnReturnPressed sets the callback function of a UI component for a
      ReturnPressed event. Once the user presses the return key in the Edit component,
      the callback function will be called to handle this event.

      The ReturnPressed event is available for the Edit component.

      call msUISetOnReturnPressed( ctrlname, callback )
      • ctrlname is a string name of a UI component.
      •   callback is the callback function that handles the corresponding event. Please refer to the
          callback function section to see how to declare the prototype of a callback function.



      Example

      See Also
                                                           Chapter 11 MATFOR GUI System           641



msUISetOnValueChanged
Set the callback function of a UI component for a ValueChanged event.


Module
mxui


Syntax
call msUISetOnValueChanged( ctrlname, callback )



Descriptions
Function mfUISetOnValueChanged sets the callback function of a UI component for a
ValueChanged event. Once user changes the value of the UI component, the callback
function will be called to handle this event.

The ValueChanged event is available in the SpinEdit, Slider and ScrollBar
components.

call msUISetOnValueChanged( ctrlname, callback )
• ctrlname is a string name of a UI component.
•   callback is the callback function that handles the corresponding event. Please refer to the
    callback function section to see how to declare the prototype of a callback function.



Example

See Also
642       MATFOR 4 in Fortran Reference Guide



      msUISetOnScrollReleased
      Set the callback function of a UI component for a ScrollReleased event.


      Module
      mxui


      Syntax
      call msUISetOnScrollReleased( ctrlname, callback )



      Descriptions
      Function mfUISetOnScrollReleased sets the callback function of a UI component for
      a ScrollReleased event. Once user releases the scroll button of the Slider or
      ScrollBar components, the callback function will be called to handle this event.

      The ScrollReleased event is available in the Slider and ScrollBar components.

      call msUISetOnScrollReleased( ctrlname, callback )
      • ctrlname is a string name of a UI component.
      •   callback is the callback function that handles the corresponding event. Please refer to the
          callback function section to see how to declare the prototype of a callback function.



      Example

      See Also
                Chapter 11 MATFOR GUI System   643




UI Components
644       MATFOR 4 in Fortran Reference Guide



      MainForm
      The base main window of the application. When this main window is closed, the application
      exits.


      Properties
           Property                     Value                                Description
        caption             string                             specifies the caption of the window
        color               string, e.g. "#FF0000" for red     specifies the background color of the
                                                               component
        font                font                               specifies the font of the component
        fontcolor           string, e.g. "#FF0000" for red     specifies the font color of the
                                                               component
        height              integer                            specifies the vertical size of the
                                                               component in pixels.
        icon                encoded image                      specifies the icon that appears when the
                                                               form is minimized.
        name                string                             specifies the name of the component.
                                                               Use name to refer to this component
                                                               when getting or setting property values.
        tag                 integer                            has no predefined meaning. It is
                                                               provided for the convenience of
                                                               developers, which can be used for
                                                               storing an additional integer value.
        width               integer                            specifies the horizontal size of the
                                                               component in pixels.


      Event(s)
                    Event                                        Description
        OnResize                          Occurs immediately after the component is resized.
                                                      Chapter 11 MATFOR GUI System             645



MenuItem
The menu item of the window menu


Properties
    Property                   Value                             Description
 caption             string                         specifies the caption of menu item
 name                string                         specifies the name of the component.
                                                    Use name to refer to this component
                                                    when getting or setting property values.
 tag                 integer                        has no predefined meaning. It is
                                                    provided for the convenience of
                                                    developers, which can be used for
                                                    storing an additional integer value.


Event(s)
             Event                                    Description
 OnClick                        Occurs when the user clicks the component.
646         MATFOR 4 in Fortran Reference Guide



      MatforWindow
      A customized MATFOR component in which Matfor graphics functions represent their
      visualization results.


      Properties
             Property                      Value                              Description
        align                  "alNone", "alClient", "alTop",    specifies the alignment of the
                               "alBottom", "alLeft", "alRight"   component.
        height                 integer                           specifies the vertical size of the
                                                                 component in pixels.
        name                   string                            specifies the name of the component.
                                                                 Use name to refer to this component
                                                                 when getting or setting property
                                                                 values.
        tag                    integer                           has no predefined meaning. It is
                                                                 provided for the convenience of
                                                                 developers, which can be used for
                                                                 storing an additional integer value.
        width                  integer                           specifies the horizontal size of the
                                                                 component in pixels.
        x                      integer                           specifies the horizontal coordinate of
                                                                 the component relative to its parent.
        y                      integer                           specifies the vertical coordinate of the
                                                                 component relative to its parent.


      Event(s)
                     Event                                       Description
        None
                                                          Chapter 11 MATFOR GUI System               647



TabControl
A tab set that has the appearance of notebook dividers.


Properties
      Property                     Value                               Description
  align               "alNone", "alClient", "alTop",      specifies the alignment of the
                      "alBottom", "alLeft", "alRight"     component.
  currentpage         integer                             determines which page displays in the
                                                          TabControl. The first page starts from
                                                          1.
  font                font                                specifies the font of the component
  fontcolor           string, e.g. "#FF0000" for red      specifies the font color of the
                                                          component
  height              integer                             specifies the vertical size of the
                                                          component in pixels.
  margin              integer                             specifies the size of the margin around
                                                          the inner page.
  name                string                              specifies the name of the component.
                                                          Use name to refer to this component
                                                          when getting or setting property
                                                          values.
  pagetitle           string                              specifies the text that identify the
                                                          individual page of the TabControl.
  tabposition         "tpTop", "tpBottom"                 determines whether tabs appear at the
                                                          top or bottom.
  tag                 integer                             has no predefined meaning. It is
                                                          provided for the convenience of
                                                          developers, which can be used for
                                                          storing an additional integer value.
  width               integer                             specifies the horizontal size of the
                                                          component in pixels.
  x                   integer                             specifies the horizontal coordinate of
                                                          the component relative to its parent.
  y                   integer                             specifies the vertical coordinate of the
                                                          component relative to its parent.


Event(s)
648    MATFOR 4 in Fortran Reference Guide


                Event                                         Description
      OnTabChanged                    Occurs after a new tab is selected.
                                                       Chapter 11 MATFOR GUI System              649



Panel
A panel component.


Properties
     Property                    Value                               Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 alignspace          integer                           specifies the distance, in pixels,
                                                       between the aligned components on
                                                       this panel.
 bevelstyle          "bsRaised", "bsPlain",            determines the display style of the
                     "bsSunken", "bsGroove",           panel.
                     "bsRidge"
 bevelwidth          integer                           determines the width, in pixels, of the
                                                       panel bevels.
 borderwidth         integer                           specifies the distance, in pixels,
                                                       between the inner component and the
                                                       panel bevels..
 caption             string                            specifies the caption of the
                                                       component.
 color               string, e.g. "#FF0000" for red    specifies the background color of the
                                                       component
 font                font                              specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red    specifies the font color of the
                                                       component
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
650        MATFOR 4 in Fortran Reference Guide


       x                     integer                             specifies the horizontal coordinate of
                                                                 the component relative to its parent.
       y                     integer                             specifies the vertical coordinate of the
                                                                 component relative to its parent.


      Event(s)
                    Event                                        Description
       OnClick                            Occurs when the user clicks the component.
       OnDoubleClick                      Occurs when the user double-clicks the component.
       OnResize                           Occurs immediately after the component is resized.
                                                        Chapter 11 MATFOR GUI System               651



Button
A button component.


Properties
        Property                  Value                               Description
 align                "alNone", "alClient", "alTop",    specifies the alignment of the
                      "alBottom", "alLeft", "alRight"   component.
 allowallup           boolean                           specifies whether all buttons in the
                                                        same group can be unselected at the
                                                        same time.
 caption              string                            specifies the caption of the
                                                        component.
 color                string, e.g. "#FF0000" for red    specifies the background color of the
                                                        component
 down                 boolean                           specifies whether the button is selected
                                                        (down) or unselected (up).
 flat                 boolean                           determines whether the button
                                                        removes the raised border when the
                                                        button is unselected.
 font                 font                              specifies the font of the component
 fontcolor            string, e.g. "#FF0000" for red    specifies the font color of the
                                                        component
 glyph                encoded image                     specifies the bitmap that appears on
                                                        the button.
 groupindex           integer                           allows buttons to work together as a
                                                        group. When groupindex is 0, the
                                                        button behaves as a normal
                                                        pushbutton. When groupindex is
                                                        greater than 0, the buttons which have
                                                        the same groupindex are regarded as
                                                        the same group. When the user clicks
                                                        one of these buttons, it remains
                                                        selected until the user clicks another
                                                        button belonging to the same group.
 height               integer                           specifies the vertical size of the
                                                        component in pixels.
 name                 string                            specifies the name of the component.
652        MATFOR 4 in Fortran Reference Guide


                                                                Use name to refer to this component
                                                                when getting or setting property
                                                                values.
       tag                   integer                            has no predefined meaning. It is
                                                                provided for the convenience of
                                                                developers, which can be used for
                                                                storing an additional integer value.
       width                 integer                            specifies the horizontal size of the
                                                                component in pixels.
       x                     integer                            specifies the horizontal coordinate of
                                                                the component relative to its parent.
       y                     integer                            specifies the vertical coordinate of the
                                                                component relative to its parent.


      Event(s)
                    Event                                       Description
       OnClick                            Occurs when the user clicks the component.
                                                        Chapter 11 MATFOR GUI System               653



Label
A label component.


Properties
     Property                     Value                              Description
 align               "alNone", "alClient", "alTop",     specifies the alignment of the
                     "alBottom", "alLeft", "alRight"    component.
 caption             string                             specifies the text to display.
 color               string, e.g. "#FF0000" for red     specifies the background color of the
                                                        component
 font                font                               specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red     specifies the font color of the
                                                        component
 halign              "haLeft", "haCenter", 'haRight"    specifies the horizontal placement of
                                                        the text within the label
 height              integer                            specifies the vertical size of the
                                                        component in pixels.
 name                string                             specifies the name of the component.
                                                        Use name to refer to this component
                                                        when getting or setting property
                                                        values.
 tag                 integer                            has no predefined meaning. It is
                                                        provided for the convenience of
                                                        developers, which can be used for
                                                        storing an additional integer value.
 valign              "vaTop", "vaMiddle",               specifies the vertical placement of the
                     "vaBottom"                         text within the label
 width               integer                            specifies the horizontal size of the
                                                        component in pixels.
 x                   integer                            specifies the horizontal coordinate of
                                                        the component relative to its parent.
 y                   integer                            specifies the vertical coordinate of the
                                                        component relative to its parent.


Event(s)
             Event                                      Description
 OnClick                          Occurs when the user clicks the component.
654    MATFOR 4 in Fortran Reference Guide


      OnDoubleClick                   Occurs when the user double-clicks the component.
                                                       Chapter 11 MATFOR GUI System               655



RadioButton
A radio button component.


Properties
     Property                    Value                              Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 caption             string                            specifies the text to display.
 checked             boolean                           determines whether the option
                                                       represented by the radio button is
                                                       selected.
 color               string, e.g. "#FF0000" for red    specifies the background color of the
                                                       component
 font                font                              specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red    specifies the font color of the
                                                       component
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
 x                   integer                           specifies the horizontal coordinate of
                                                       the component relative to its parent.
 y                   integer                           specifies the vertical coordinate of the
                                                       component relative to its parent.


Event(s)
             Event                                     Description
 OnClick                         Occurs when the user clicks the component.
656        MATFOR 4 in Fortran Reference Guide



      CheckBox
      A check box component.


      Properties
            Property                      Value                             Description
       align                 "alNone", "alClient", "alTop",    specifies the alignment of the
                             "alBottom", "alLeft", "alRight"   component.
       caption               string                            specifies the text to display.
       checked               boolean                           determines whether the option
                                                               represented by the check box is
                                                               selected.
       color                 string, e.g. "#FF0000" for red    specifies the background color of the
                                                               component
       font                  font                              specifies the font of the component
       fontcolor             string, e.g. "#FF0000" for red    specifies the font color of the
                                                               component
       height                integer                           specifies the vertical size of the
                                                               component in pixels.
       name                  string                            specifies the name of the component.
                                                               Use name to refer to this component
                                                               when getting or setting property
                                                               values.
       state                 "cbUnchecked", "cbChecked",       indicates whether the check box is
                             "cbGrayed"                        deselected, selected, or grayed.
       tag                   integer                           has no predefined meaning. It is
                                                               provided for the convenience of
                                                               developers, which can be used for
                                                               storing an additional integer value.
       tristate              boolean                           determines whether check box can be
                                                               in a "grayed" state.
       width                 integer                           specifies the horizontal size of the
                                                               component in pixels.
       x                     integer                           specifies the horizontal coordinate of
                                                               the component relative to its parent.
       y                     integer                           specifies the vertical coordinate of the
                                                               component relative to its parent.
                                         Chapter 11 MATFOR GUI System   657


Event(s)
           Event                         Description
 OnClick           Occurs when the user clicks the component.
658        MATFOR 4 in Fortran Reference Guide



      Edit
      An edit component.


      Properties
            Property                      Value                              Description
       align                 "alNone", "alClient", "alTop",     specifies the alignment of the
                             "alBottom", "alLeft", "alRight"    component.
       color                 string, e.g. "#FF0000" for red     specifies the background color of the
                                                                component
       font                  font                               specifies the font of the component
       fontcolor             string, e.g. "#FF0000" for red     specifies the font color of the
                                                                component
       height                integer                            specifies the vertical size of the
                                                                component in pixels.
       name                  string                             specifies the name of the component.
                                                                Use name to refer to this component
                                                                when getting or setting property
                                                                values.
       tag                   integer                            has no predefined meaning. It is
                                                                provided for the convenience of
                                                                developers, which can be used for
                                                                storing an additional integer value.
       text                  string                             specifies the text in the component
       width                 integer                            specifies the horizontal size of the
                                                                component in pixels.
       x                     integer                            specifies the horizontal coordinate of
                                                                the component relative to its parent.
       y                     integer                            specifies the vertical coordinate of the
                                                                component relative to its parent.


      Event(s)
                    Event                                       Description
       OnReturnPressed                    Occurs when return key pressed.
       OnTextChanged                      Occurs when the text of the component has changed.
                                                       Chapter 11 MATFOR GUI System               659



SpinEdit
A spin edit component.


Properties
     Property                    Value                              Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 color               string, e.g. "#FF0000" for red    specifies the background color of the
                                                       component
 font                font                              specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red    specifies the font color of the
                                                       component
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 max                 integer                           specifies the maximum value the user
                                                       can enter into the spin edit component.
 min                 integer                           specifies the minimum value the user
                                                       can enter into the spin edit component.
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 text                string                            specifies the text in the component
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
 x                   integer                           specifies the horizontal coordinate of
                                                       the component relative to its parent.
 y                   integer                           specifies the vertical coordinate of the
                                                       component relative to its parent.


Event(s)
             Event                                     Description
 OnValueChanged                  Occurs when the value of the component has changed.
660   MATFOR 4 in Fortran Reference Guide
                                                          Chapter 11 MATFOR GUI System               661



ListBox
A list box component.


Properties
     Property                       Value                              Description
 align                  "alNone", "alClient", "alTop",    specifies the alignment of the
                        "alBottom", "alLeft", "alRight"   component.
 color                  string, e.g. "#FF0000" for red    specifies the background color of the
                                                          component
 font                   font                              specifies the font of the component
 fontcolor              string, e.g. "#FF0000" for red    specifies the font color of the
                                                          component
 height                 integer                           specifies the vertical size of the
                                                          component in pixels.
 itemindex              integer                           specifies the ordinal number of the
                                                          selected item in the list box.
 items                  string                            contains the strings that appear in
                                                          the list box. The items are separated
                                                          by linefeed character "\n".
 name                   string                            specifies the name of the component.
                                                          Use name to refer to this component
                                                          when getting or setting property
                                                          values.
 tag                    integer                           has no predefined meaning. It is
                                                          provided for the convenience of
                                                          developers, which can be used for
                                                          storing an additional integer value.
 text                   string                            specifies the text of the selected item.
 width                  integer                           specifies the horizontal size of the
                                                          component in pixels.
 x                      integer                           specifies the horizontal coordinate of
                                                          the component relative to its parent.
 y                      integer                           specifies the vertical coordinate of the
                                                          component relative to its parent.


Event(s)
             Event                                        Description
662    MATFOR 4 in Fortran Reference Guide


      OnClick                         Occurs when the user clicks the component.
      OnDoubleClick                   Occurs when the user double-clicks the component.
                                                       Chapter 11 MATFOR GUI System               663



ComboBox
A combo box component.


Properties
     Property                    Value                              Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 color               string, e.g. "#FF0000" for red    specifies the background color of the
                                                       component
 font                font                              specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red    specifies the font color of the
                                                       component
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 itemindex           integer                           specifies the ordinal number of the
                                                       selected item in the list box.
 items               string                            contains the strings that appear in
                                                       the list box. The items are separated
                                                       by linefeed character "\n".
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 text                string                            specifies the text of the selected item.
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
 x                   integer                           specifies the horizontal coordinate of
                                                       the component relative to its parent.
 y                   integer                           specifies the vertical coordinate of the
                                                       component relative to its parent.


Event(s)
             Event                                     Description
664    MATFOR 4 in Fortran Reference Guide


      OnTextChanged                   Occurs when the text of the component has changed.
                                                        Chapter 11 MATFOR GUI System                 665



Slider
A slider component.


Properties
     Property                     Value                              Description
 align                "alNone", "alClient", "alTop",    specifies the alignment of the
                      "alBottom", "alLeft", "alRight"   component.
 height               integer                           specifies the vertical size of the
                                                        component in pixels.
 max                  integer                           specifies the maximum value of the
                                                        component.
 min                  integer                           specifies the minimum value of the
                                                        component.
 name                 string                            specifies the name of the component.
                                                        Use name to refer to this component
                                                        when getting or setting property
                                                        values.
 orientation          "otHorizontal", "otVertical"      specifies whether the component is
                                                        horizontal or vertical.
 position             integer                           specifies the current position (value)
                                                        of the progress bar.
 tag                  integer                           has no predefined meaning. It is
                                                        provided for the convenience of
                                                        developers, which can be used for
                                                        storing an additional integer value.
 tickinterval integer                                   specifies the tick interval on the slider.
 tickmarks            "tmNone", "tmTopLeft",            specifies the location of the tick
                      "tmBottomRight", "tmBoth"         marks.
 value                integer                           is the same as the property
                                                        position.
 width                integer                           specifies the horizontal size of the
                                                        component in pixels.
 x                    integer                           specifies the horizontal coordinate of
                                                        the component relative to its parent.
 y                    integer                           specifies the vertical coordinate of the
                                                        component relative to its parent.
Event(s)
666     MATFOR 4 in Fortran Reference Guide


                 Event                                        Description
      OnScrollReleased                 Occurs when the user finishes the scrolling. (Windows only)
      OnValueChanged                   Occurs when the value of the component has changed.
                                                        Chapter 11 MATFOR GUI System              667



ScrollBar
A scroll bar component.


Properties
     Property                    Value                              Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 max                 integer                           specifies the maximum value of the
                                                       component.
 min                 integer                           specifies the minimum value of the
                                                       component.
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 orientation         "otHorizontal", "otVertical"      specifies whether the component is
                                                       horizontal or vertical.
 position            integer                           specifies the current position (value)
                                                       of the progress bar.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 value               integer                           is the same as the property
                                                       position.
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
 x                   integer                           specifies the horizontal coordinate of
                                                       the component relative to its parent.
 y                   integer                           specifies the vertical coordinate of the
                                                       component relative to its parent.


Event(s)
             Event                                      Description
 OnScrollReleased                Occurs when the user finishes the scrolling. (Windows Only)
668    MATFOR 4 in Fortran Reference Guide


      OnValueChanged                  Occurs when the value of the component has changed.
                                                      Chapter 11 MATFOR GUI System               669



ProgressBar
A progress bar component.


Properties
     Property                   Value                              Description
 align              "alNone", "alClient", "alTop",    specifies the alignment of the
                    "alBottom", "alLeft", "alRight"   component.
 color              string, e.g. "#FF0000" for red    specifies the background color of the
                                                      component
 font               font                              specifies the font of the component
 fontcolor          string, e.g. "#FF0000" for red    specifies the font color of the
                                                      component
 height             integer                           specifies the vertical size of the
                                                      component in pixels.
 labelpos           "lpNone", "lpCenter", "lpRight"   specifies the label position of the
                                                      progress bar.
 max                integer                           specifies the maximum value of the
                                                      component.
 min                integer                           specifies the minimum value of the
                                                      component.
 name               string                            specifies the name of the component.
                                                      Use name to refer to this component
                                                      when getting or setting property
                                                      values.
 position           integer                           specifies the current position (value)
                                                      of the progress bar.
 tag                integer                           has no predefined meaning. It is
                                                      provided for the convenience of
                                                      developers, which can be used for
                                                      storing an additional integer value.
 value              integer                           is the same as the property
                                                      position.
 width              integer                           specifies the horizontal size of the
                                                      component in pixels.
 x                  integer                           specifies the horizontal coordinate of
                                                      the component relative to its parent.
 y                  integer                           specifies the vertical coordinate of the
670       MATFOR 4 in Fortran Reference Guide


                                                               component relative to its parent.


      Event(s)
                   Event                                       Description
       OnClick                           Occurs when the user clicks the component.
       OnDoubleClick                     Occurs when the user double-clicks the component.
                                         (XWindow Only)
                                                        Chapter 11 MATFOR GUI System               671



Image
A image component.


Properties
     Property                     Value                              Description
 align               "alNone", "alClient", "alTop",     specifies the alignment of the
                     "alBottom", "alLeft", "alRight"    component.
 halign              "haLeft", "haCenter", 'haRight"    specifies the horizontal placement of
                                                        the text within the label
 height              integer                            specifies the vertical size of the
                                                        component in pixels.
 name                string                             specifies the name of the component.
                                                        Use name to refer to this component
                                                        when getting or setting property
                                                        values.
 picture             encoded image                      specifies the bitmap that appears on
                                                        the image.
 stretch             boolean                            indicates whether the image should be
                                                        resized to fit the bounds of the image
                                                        component.
 tag                 integer                            has no predefined meaning. It is
                                                        provided for the convenience of
                                                        developers, which can be used for
                                                        storing an additional integer value.
 valign              "vaTop", "vaMiddle",               specifies the vertical placement of the
                     "vaBottom"                         text within the label
 width               integer                            specifies the horizontal size of the
                                                        component in pixels.
 x                   integer                            specifies the horizontal coordinate of
                                                        the component relative to its parent.
 y                   integer                            specifies the vertical coordinate of the
                                                        component relative to its parent.


Event(s)
             Event                                      Description
 OnClick                          Occurs when the user clicks the component.
 OnDoubleClick                    Occurs when the user double-clicks the component.
672   MATFOR 4 in Fortran Reference Guide
                                                       Chapter 11 MATFOR GUI System               673



Memo
A multiline edit component.


Properties
     Property                    Value                              Description
 align               "alNone", "alClient", "alTop",    specifies the alignment of the
                     "alBottom", "alLeft", "alRight"   component.
 color               string, e.g. "#FF0000" for red    specifies the background color of the
                                                       component
 font                font                              specifies the font of the component
 fontcolor           string, e.g. "#FF0000" for red    specifies the font color of the
                                                       component
 height              integer                           specifies the vertical size of the
                                                       component in pixels.
 name                string                            specifies the name of the component.
                                                       Use name to refer to this component
                                                       when getting or setting property
                                                       values.
 readonly            boolean                           determines whether the user can
                                                       change the text of the component.
 tag                 integer                           has no predefined meaning. It is
                                                       provided for the convenience of
                                                       developers, which can be used for
                                                       storing an additional integer value.
 text                string                            specifies the text in the component
 width               integer                           specifies the horizontal size of the
                                                       component in pixels.
 wordwrap            boolean                           determines whether the component
                                                       inserts soft linefeed text wraps at the
                                                       right margin.
 x                   integer                           specifies the horizontal coordinate of
                                                       the component relative to its parent.
 y                   integer                           specifies the vertical coordinate of the
                                                       component relative to its parent.


Event(s)
             Event                                     Description
674    MATFOR 4 in Fortran Reference Guide


      None
                                                                                                         Index           675




Index
A                                                           F
All .................................................119    Factorization Utilities .....................240
Any..................................................119    Fast Fourier Transform .....................89
Arithmetic & Relational Operators.109                       Figure..............................................290
Arithmetic Operators ......109, 112, 119                    FileIO................................................65
Axis Control....................................341
                                                            G
B                                                           Graphics Viewer Manipulation.......584
Basic..................................................76
                                                            I
Button..............................................651
                                                            Image ......................................541, 671
C                                                           Initialization....................................624
Callback Setting ..............................634          Introduction.......................................15
Camera Manipulation......................376
                                                            L
Cartographic Functions.....................96
                                                            Label ...............................................653
CheckBox........................................656
                                                            Linear Equations.............................216
ComboBox ......................................663
                                                            Linear Graphs .................................388
Complex..........................................159
                                                            Linespec..389, 398, 401, 404, 406, 408
Configuration ..................................303
                                                            ListBox ...........................................661
D
                                                            M
Data Manipulation Functions............75
                                                            MainForm .......................................644
Display ................................24, 61, 299
                                                            MATFOR Visualization Routines...281
Documentations ................................15
                                                            MatforWindow................................646
E                                                           MATLAB Interface.........................618
Edit..................................................658   Matrices ..................................181, 183
Eigenvalues and singular values .....229                    Matrix Analysis...............................209
Elementary 2D/3D Objects .............546                   Matrix Function ..............................207
Elementary Math Functions............121                    Matrix Manipulation...............181, 195
Elementary Matrix-manipulation                              Memo..............................................673
Functions.........................................181       Memory Management.................24, 56
Equivalency.................................23, 50          MenuItem........................................645
Essential Functions ...........................23           mf......................................................28
Exponential .....................................150        mfAbs .....................................122, 160
Extensions of MATFOR .................605                   mfACos...................................121, 124
676        MATFOR 4 in Fortran Reference Guide


      mfACosh .................................121, 125         mfColon ..........................................185
      mfACot ...................................121, 126        mfColormapRange..........................334
      mfACoth .................................121, 127         mfComplex .............................122, 162
      mfACsc ...................................121, 128        mfCond ...................207, 219, 243, 605
      mfACsch .................................121, 129         mfCone ...........................................566
      mfAll .........................................38, 119    mfConj ....................................122, 163
      mfAngle ..................................122, 161        mfContour.......................................423
      mfAnnotation ..................................325        mfContour3.....................................425
      mfAny .......................................40, 119      mfCos......................................121, 138
      mfArray access..................................43        mfCosh....................................121, 139
      mfArray manipulation.................23, 25               mfCot ......................................121, 140
      mfAsec ............................................121    mfCoth ....................................121, 141
      mfASec ...........................................130     mfCsc......................................121, 142
      mfASech .................................121, 131         mfCsch....................................121, 143
      mfASin....................................121, 132        mfCube ...........................................561
      mfASinh..................................121, 134         mfCylinder......................................563
      mfATan....................................121, 135        mfDelaunay.....................................530
      mfATan2..................................121, 136         mfDelaunay3...................................533
      mfATanh..................................121, 137         mfDet ......................................207, 210
      mfAxis.............................................342    mfDiag ....................................181, 196
      mfAxis2DRange .............................353            mfDoMATLAB...............................619
      mfAxis3DRange .............................354            mfEig ..............................208, 230, 243
      mfAxisMark....................................568         mfEquiv ............................................54
      mfBackgroundColor .......................340              mfExp .....................................122, 151
      mfBalance .......................208, 241, 244            mfEye......................................181, 184
      mfBar ..............................................401   mfFastMolecule ..............................555
      mfBar3 ............................................406    mfFastPColor..................................421
      mfBar3h ..........................................408     mfFFT ...............................................90
      mfBarh ............................................404    mfFFT2 .............................................92
      mfCamAngle...................................380          mfFFTShift .......................................94
      mfCamAzElRoll .............................381            mfFigure .........................................291
      mfCamDistance...............................382           mfFigureCount................................294
      mfCamFocal....................................384         mfFileDialog...................................601
      mfCamProj......................................383        mfFind.....................................181, 198
      mfCamZoom ...................................385          mfFix.......................................122, 169
      mfCeil .....................................122, 167      mfFloor ...................................122, 171
      mfChol ....................207, 217, 243, 605             mfFullToSp .....................................276
      mfCircle ..........................................547    mfGetCamViewParam....................386
                                                                                                   Index           677


mfGetCurrentDraw .........................580            mfMatSub .........................................44
mfGetDelaunay ...............................530         mfMax...............................................77
mfGetDelaunay3 .............................533          mfMesh ...........................................413
mfHess ............................208, 232, 243         mfMeshc .........................................417
mfIFFT..............................................90   mfMeshgrid.............................181, 188
mfIFFT2............................................92    mfMin ...............................................79
mfIFFTShift ......................................94     mfMod ....................................122, 173
mfImag....................................122, 164       mfMolecule.....................................551
mfImage ..........................................542    mfMul .............................................227
mfImRead .......................................544      mfNDims ..........................................34
mfInputMatrix.................................599        mfNorm...................207, 211, 243, 605
mfInputString ..................................596      mfObjectModel...............................374
mfInputValue...................................597       mfObjOrientation............................372
mfInputVector .................................598       mfObjOrigin ...................................370
mfInputYesNo .................................604        mfObjPosition.................................368
mfInv...............................207, 221, 243        mfObjScale .....................................366
mfIsComplex.....................................26       mfOnes....................................181, 190
mfIsEmpty.........................................26     mfOpenFileDialog ..........................601
mfIsHold .........................................320    mfOut................................................30
mfIsLogical .......................................26    mfOutline........................................431
mfIsNumeric .....................................26      mfPatch ...........................................479
mfIsoSurface ...................................433      mfPColor.........................................419
mfIsReal............................................26   mfPlot .............................................389
mfIsValidDraw................................579         mfPlot3 ...........................................392
mfLDiv............................................228    mfPoint ...........................................528
mfLength...........................................42    mfPow2...................................122, 156
mfLinspace..............................181, 186         mfProd ..............................................81
mfLoad..............................................66   mfQr........................207, 225, 243, 605
mfLoad.m..........................................67     mfQuiver.........................................536
mfLoadAscii .....................................68      mfQuiver3.......................................538
mfLoadCsv........................................70      mfQz ...............................208, 234, 243
mfLog......................................122, 152      mfRand ...................................181, 191
mfLog10..................................122, 153        mfRank ...................207, 213, 243, 605
mfLog2....................................122, 154       mfRcond .................207, 222, 243, 605
mfLogical................................181, 200        mfRDiv ...........................................228
mfLu................................207, 223, 243        mfReal.....................................122, 165
mfMagic..................................181, 187        mfRem ....................................122, 175
mfMATLABServer .........................621              mfRepmat ...............................181, 192
678        MATFOR 4 in Fortran Reference Guide


      mfReshape...............................181, 201            mfSquare.........................................549
      mfRibbon ........................................394        mfStem............................................398
      mfRound .................................122, 177           mfStreamArrow ..............................468
      mfS....................................................44   mfStreamArrow2 ............................457
      mfSave.m ..........................................72       mfStreamArrow3 ............................468
      mfSaveFileDialog ...........................603             mfStreamDashedLine .....................462
      mfSchur...................................208, 236          mfStreamDashedLine2 ...................451
      mfSec ......................................121, 144        mfStreamDashedLine3 ...................462
      mfSech ....................................121, 145         mfStreamLine .................................459
      mfShape ............................................36      mfStreamLine2 ...............................448
      mfSign.....................................122, 179         mfStreamLine3 ...............................459
      mfSin.......................................122, 146        mfStreamRibbon.............................464
      mfSinh.....................................122, 147         mfStreamRibbon2...........................453
      mfSize ...............................................32    mfStreamRibbon3...........................464
      mfSliceIJK ......................................440        mfStreamTube.................................466
      mfSlicePlane ...................................442         mfStreamTube2...............................455
      mfSliceXYZ....................................437           mfStreamTube3...............................466
      mfSolidContour...............................427            mfSubplot .......................................314
      mfSolidContour3.............................429             mfSum...............................................87
      mfSort ...............................................83    mfSurf .............................................411
      mfSortRows ......................................85         mfSurfc ...........................................415
      mfSpCreate .....................................246         mfSvd..............................208, 238, 244
      mfSpEigs.........................................266        mfTan ......................................122, 148
      mfSpGet ..........................................251       mfTanh ....................................122, 149
      mfSpGetCol ....................................257          mfTecOpenFile ...............................607
      mfSpGetM.......................................253          mfTecReadBlockCount...................613
      mfSpGetN .......................................253         mfTecReadTitle ..............................609
      mfSpGetNNZ..................................255             mfTecReadVarCount.......................613
      mfSpGetRow...................................257            mfTecWriteTitle..............................609
      mfSpGetVal.....................................259          mfTetContour..................................487
      mfSphere .........................................559       mfTetIsoSurface..............................490
      mfSpImport .....................................265         mfTetMesh......................................485
      mfSpLDiv .......................................268         mfTetSlicePlane..............................496
      mfSpMul .........................................270        mfTetSliceXYZ...............................493
      mfSpSize .........................................272       mfTetStreamArrow .........................524
      mfSpToFull .....................................274         mfTetStreamDashLine ....................518
      mfSpy..............................................278      mfTetStreamLine ............................515
      mfSqrt .....................................122, 158        mfTetStreamRibbon........................520
                                                                                                     Index           679


mfTetStreamTube............................522             msASec ...........................................130
mfTetSurf ........................................482      msASech .........................................131
mfText .............................................324    msASin ...........................................132
mfTitle.............................................322    msASinh .........................................134
mfTrace ...................207, 215, 243, 605              msAssign...........................................51
mfTriContour ..................................476         msATan ...........................................135
mfTril ......................................181, 202      msATan2 .........................................136
mfTriMesh ......................................474        msATanh .........................................137
mfTriStreamArrow..........................512              msAxis ............................................342
mfTriStreamDashLine.....................506                msAxis2DDependency ...................349
mfTriStreamLine.............................503            msAxis2DMode..............................347
mfTriStreamRibbon ........................508              msAxis2DPosition ..........................355
mfTriStreamTube ............................510            msAxis3DDependency ...................351
mfTriSurf ........................................472      msAxis3DMode..............................348
mfTriu .....................................181, 204       msAxisGrid.....................................359
mfTube ............................................396     msAxisMark ...................................568
mfUIGetPropertyDouble.................632                  msAxisWall.....................................357
mfUIGetPropertyInteger .................630                msBackgroundColor .......................340
mfUIGetPropertyString...................628                msBalance.......................................241
mfWindowCaption..........................296               msCamAngle ..................................380
mfWindowPos.................................298            msCamProj .....................................383
mfWindowSize................................297            msCamZoom...................................385
mfXLabel ........................................322       msCeil .............................................167
mfYLabel ........................................322       msChol............................................217
mfZeros ...................................181, 194        msCircle..........................................547
mfZLabel.........................................322       msClearSubplot...............................317
msAbs .............................................160     msCloseFigure ................................293
msACos...........................................124       msColon..........................................185
msACosh.........................................125        msColorbar .....................................329
msACot ...........................................126      msColormap....................................331
msACoth .........................................127       msColormapRange .........................334
msACsc ...........................................128      msComplex .....................................162
msACsch .........................................129       msCone ...........................................566
msAddLegend .................................338           msConj............................................163
msAll.................................................38   msContour.......................................423
msAngle ..........................................161      msContour3.....................................425
msAnnotation..................................325          msCos .............................................138
msAny ...............................................40    msCosh ...........................................139
680        MATFOR 4 in Fortran Reference Guide


      msCot ..............................................140   msGDisplay ....................................300
      msCoth ............................................141    msGetDelaunay...............................530
      msCreateCoastline3Data.................106                msGetDelaunay3.............................533
      msCreateCoastlineData...................104               msGetIsoSurface.............................435
      msCreateGeoid3Data ......................103              msGetSlicePlane .............................446
      msCreateGeoidData ........................102             msGetSliceXYZ..............................445
      msCsc..............................................142    msGetTetIsoSurface........................499
      msCsch............................................143     msGetTetSlicePlane........................501
      msCube ...........................................561     msGetTetSliceXYZ.........................500
      msCylinder......................................563       msGSet............................................571
      msDelaunay.....................................530        msHess............................................232
      msDelaunay3...................................533         msHold............................................318
      msDiag ............................................196    msImag ...........................................164
      msDisplay .........................................62     msImage..........................................542
      msDoMATLAB...............................619              msImWrite ......................................545
      msDrawColormap ...........................335             msInitArgs ........................................59
      msDrawMaterial .............................574           msIsoSurface...................................433
      msDrawNow ...................................301          msLegendBox .................................336
      msDrawTexture...............................577           msLinspace .....................................186
      msEditorAxis ..................................591        msLoadConfig ................................305
      msEditorBackground ......................593              msLog .............................................152
      msEditorColorbar............................592           msLog10 .........................................153
      msEditorColormap..........................589             msLog2 ...........................................154
      msEditorDrawList...........................587            msLogical .......................................200
      msEditorMaterial ............................588          msLu ...............................................223
      msEditorTransform .........................590            msMagic .........................................187
      msEig ..............................................230   msMATLABServer.........................621
      msExp .............................................151    msMax ..............................................77
      msExportImage ...............................311          msMesh...........................................413
      msEye..............................................184    msMeshc .........................................417
      msFastMolecule ..............................555          msMeshgrid ....................................188
      msFastPColor..................................421         msMin ...............................................79
      msFigure .........................................291     msMod ............................................173
      msFind.............................................198    msMolecule.....................................551
      msFix...............................................169   msObjectModel...............................374
      msFloor ...........................................171    msObjOrientation ...........................372
      msFormat ..........................................64     msObjOrigin ...................................370
      msFreeArgs .......................................59      msObjPosition.................................368
                                                                                                     Index           681


msObjRotateWXYZ .......................364                msSaveCsv........................................74
msObjRotateX.................................362          msSchur ..........................................236
msObjRotateY.................................362          msSec..............................................144
msObjRotateZ .................................362         msSech............................................145
msObjScale .....................................366       msSetCamViewParam ....................387
msOnes............................................190     msSetDrawName ............................583
msOutline........................................431      msShading.......................................327
msPatch ...........................................479    msShowMessage.............................595
msPColor.........................................419      msSign ............................................179
msPlot .............................................389   msSin ..............................................146
msPlot3 ...........................................392    msSinh ............................................147
msPoint ...........................................528    msSize...............................................32
msPointer ..........................................52    msSliceIJK......................................440
msPow2...........................................156      msSlicePlane...................................442
msPrintPreview ...............................585         msSliceXYZ ...................................437
msProd ..............................................81   msSolidContour ..............................427
msProj4 .............................................97   msSolidContour3 ............................429
msProj4Inv........................................97      msSort ...............................................83
msQr................................................225   msSortRows......................................85
msQuiver.........................................536      msSpAdd.........................................247
msQuiver3.......................................538       msSpDisplay ...................................263
msQz ...............................................234   msSpExport.....................................264
msRand ...........................................191     msSpGetIdx ....................................261
msReal.............................................165    msSphere.........................................559
msRecordEnd..................................307          msSpSet ..........................................249
msRecordStart.................................307         msSpy .............................................278
msRem ............................................175     msSqrt .............................................158
msRemoveAllLegend .....................339                msSquare.........................................549
msRemoveDraw..............................582             msStem ...........................................398
msRemoveLegend...........................339              msStreamArrow ..............................468
msRepmat .......................................192       msStreamArrow2 ............................457
msReshape ......................................201       msStreamArrow3 ............................468
msReturnArray..................................57         msStreamDashedLine .....................462
msRibbon ........................................394      msStreamDashedLine2 ...................451
msRound .........................................177      msStreamDashedLine3 ...................462
msSave ..............................................71   msStreamLine .................................459
msSaveAscii......................................73       msStreamLine2 ...............................448
msSaveConfig .................................304         msStreamLine3 ...............................459
682        MATFOR 4 in Fortran Reference Guide


      msStreamRibbon.............................464            msTriStreamTube............................510
      msStreamRibbon2...........................453             msTriSurf ........................................472
      msStreamRibbon3...........................464             msTube............................................396
      msStreamTube.................................466          msUIInitialize .................................625
      msStreamTube2...............................455           msUIMainLoop...............................626
      msStreamTube3...............................466           msUISetOnClick.............................635
      msSubplot .......................................314      msUISetOnDoubleClick .................636
      msSum...............................................87    msUISetOnResize...........................638
      msSurf .............................................411   msUISetOnReturnPressed ..............640
      msSurfc ...........................................415    msUISetOnScrollReleased .............642
      msSvd..............................................238    msUISetOnTabChanged .................637
      msTan ..............................................148   msUISetOnTextChanged ................639
      msTanh ............................................149    msUISetOnValueChanged ..............641
      msTecCloseFile...............................607          msUISetPropertyDouble.................633
      msTecReadBlock ............................610            msUISetPropertyInteger .................631
      msTecReadVarName.......................610                msUISetPropertyString...................629
      msTecWriteIJKBlock......................615               msView ...........................................377
      msTecWriteTetBlock.......................615              msViewPause..................................302
      msTecWriteTriBlock.......................615              msWindowCaption .........................296
      msTecWriteVarNames.....................614                msWindowPos ................................298
      msTetContour..................................487         msWindowSize ...............................297
      msTetIsoSurface..............................490          msZeros...........................................194
      msTetMesh......................................485
                                                                O
      msTetSlicePlane..............................496
                                                                Object Manipulation .......................361
      msTetSliceXYZ...............................493
                                                                Operator Precedence......... 21, 109, 110
      msTetStreamArrow .........................524
      msTetStreamDashLine ....................518               P
      msTetStreamLine ............................515           Panel ...............................................649
      msTetStreamRibbon........................520              Plot Annotation and Appearance ....321
      msTetStreamTube ...........................522            Plot Creation and Control ...............313
      msTetSurf........................................482      Procedure Descriptions Convention .17
      msText.............................................324    ProgressBar.....................................669
      msTrace...........................................215     Property Setting ......................570, 627
      msTriContour ..................................476
      msTriMesh ......................................474       R
      msTriStreamArrow .........................512             RadioButton....................................655
      msTriStreamLine.....................503, 506              Recording........................................306
      msTriStreamRibbon ........................508             Relational Operators ....... 109, 116, 117
                                                                                                  Index          683


Rounding and Remainder ...............166                   Triangular Surface Graphs..............471
                                                            Trigonometry ..................................123
S
                                                            Typographical Conventions ..............16
ScrollBar .........................................667
Simple GUI .....................................594         U
Slice Graphs ....................................436        UI Components...............................643
Slider ...............................................665   Unstructured Grids..........................481
Sparse Array....................................243         Unstructured Point Set....................527
Sparse Array....................................245         Unstructured Streamlines................502
SpinEdit...........................................659
                                                            V
Streamline Graphs...........................447
                                                            Velocity Vectors ..............................535
Surface Graphs................................410
                                                            W
T
                                                            Window Frame ...............................295
TabControl ......................................647
Tecplot FileIO .................................606