Вы находитесь на странице: 1из 683
Reference Guide MATFOR 4 in Fortran

Reference Guide

MATFOR 4 in Fortran

2

MATFOR 4 in Fortran Reference Guide

Contents

Contents

2

Introduction

15

Typographical Conventions Procedure Descriptions Convention MATFOR Procedure Naming Convention MATFOR Parameters

16

17

19

21

Essential Functions

23

mfArray manipulation

25

mfIsEmpty, mfIsLogical, mfIsReal, mfIsComplex, mfIsNumeric mf mfOut

26

28

30

mfSize, msSize 32 mfNDims 34

mfShape

36

mfAll, msAll

38

mfAny, msAny 40 mfLength 42

43

mfMatSub, mfS 44

50

msAssign 51

52

msPointer

mfEquiv 54

56

msReturnArray 57

mfArray access

Equivalency

Memory Management

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 Arithmetic Operators Relational Operators

110

112

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

Table of Contents

5

mfSqrt, msSqrt Complex mfAbs, msAbs mfAngle, msAngle mfComplex, msComplex mfConj, msConj mfImag, msImag mfReal, msReal

158

159

160

161

162

163

164

165

Rounding and Remainder mfCeil, msCeil mfFix, msFix mfFloor, msFloor

166

167

169

171

mfMod,

msMod

173

mfRem,

msRem

175

mfRound, msRound mfSign, msSign

177

179

Elementary Matrix-manipulation Functions

181

Matrices mfEye, msEye mfColon, msColon mfLinspace, msLinspace mfMagic, msMagic

183

184

185

186

187

mfMeshgrid, msMeshgrid

188

mfOnes,

msOnes

190

mfRand, msRand mfRepmat, msRepmat mfZeros, msZeros Matrix Manipulation mfDiag, msDiag mfFind, msFind mfLogical, msLogical mfReshape, msReshape mfTril mfTriu

191

192

194

195

196

198

200

201

202

204

6

MATFOR 4 in Fortran Reference Guide

Matrix Functions

207

Matrix Analysis

209

mfDet

210

mfNorm 211 mfRank 213

215

Linear Equations 216 mfChol, msChol 217

219

mfInv 221 mfRcond 222

mfLu, msLu 223

mfTrace, msTrace

mfCond

mfQr, msQr

225

mfMul

227

mfRDiv, mfLDiv 228

Eigenvalues and singular values 229

230

mfHess, msHess 232

234

mfSchur, msSchur 236

mfEig, msEig

mfQz, msQz

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

263

msSpDisplay

msSpExport 264

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

292

mfFigureCount 293

294

mfWindowCaption, msWindowCaption 295

296

mfWindowPos, msWindowPos 297 Display 298 msGDisplay 299

Window Frame

msCloseFigure

mfWindowSize, msWindowSize

msDrawNow

300

msViewPause

301

Configuration 302

303

msLoadConfig 304

msSaveConfig

Recording

305

msRecordStart, msRecordEnd

306

msExportImage

310

Plot Creation and Control 312 mfSubplot, msSubplot 313 msClearSubplot 316 msHold 317

319

Plot Annotation and Appearance 320

mfTitle, mfXLabel, mfYLabel, mfZLabel 321

mfIsHold

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

358

Object Manipulation 360

msAxisGrid

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

380

mfCamAzElRoll

mfCamDistance 381

382

mfCamProj, msCamProj

mfCamFocal 383

mfCamZoom, msCamZoom

384

mfGetCamViewParam

385

msSetCamViewParam 386

387

Linear Graphs

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

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

480

mfTetSurf, msTetSurf 481

mfTetMesh, msTetMesh 484

Unstructured Grids

mfTetContour, msTetContour

486

mfTetIsoSurface, msTetIsoSurface

489

mfTetSliceXYZ, msTetSliceXYZ 492

mfTetSlicePlane, msTetSlicePlane 495 msGetTetIsoSurface 498 msGetTetSliceXYZ 499

msGetTetSlicePlane

500

Unstructured Streamlines

501

mfTriStreamLine, msTriStreamLine 502

505

mfTriStreamRibbon, msTriStreamRibbon 507

509

mfTriStreamArrow, msTriStreamArrow 511

514

mfTetStreamDashLine, msTetStreamDashLine 517

519

mfTetStreamTube, msTetStreamTube 521

523

Unstructured Point Set 526

mfPoint, msPoint 527

mfTriStreamDashLine, msTriStreamDashLine

mfTriStreamTube, msTriStreamTube

mfTetStreamLine, msTetStreamLine

mfTetStreamRibbon, msTetStreamRibbon

mfTetStreamArrow, msTetStreamArrow

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

mfCube, msCube 560

mfCylinder, msCylinder 562 mfCone, msCone 565

558

mfAxisMark, msAxisMark

567

Property Setting

569

msGSet 570

573

msDrawTexture 576 mfIsValidDraw 578

mfGetCurrentDraw

msDrawMaterial

579

msRemoveDraw 581

msSetDrawName

582

Graphics Viewer Manipulation

583

msPrintPreview

584

msEditorDrawList 586

msEditorMaterial

587

msEditorColormap 588

msEditorTransform

589

msEditorAxis

590

msEditorColorbar 591

592

Simple GUI 593

msShowMessage 594

595

mfInputValue 596

597

mfInputMatrix 598

mfFileDialog, mfOpenFileDialog 600

msEditorBackground

mfInputString

mfInputVector

mfSaveFileDialog

602

mfInputYesNo

603

12

MATFOR 4 in Fortran Reference Guide

Extensions of MATFOR

605

Tecplot FileIO

606

mfTecOpenFile, msTecCloseFile 607

mfTecReadTitle, mfTecWriteTitle

msTecReadVarName, msTecReadBlock 610

mfTecReadVarCount,

609

mfTecReadBlockCount

613

msTecWriteVarNames 614

msTecWriteIJKBlock, msTecWriteTriBlock, msTecWriteTetBlock

615

MATLAB Interface

618

mfDoMATLAB, msDoMATLAB 619 mfMATLABServer, msMATLABServer 621

MATFOR GUI System

623

Initialization 624

msUIInitialize

msUIMainLoop 626

627

mfUIGetPropertyString 628

msUISetPropertyString

mfUIGetPropertyInteger 630

629

625

Property Setting

631

mfUIGetPropertyDouble 632

msUISetPropertyDouble

633

msUISetPropertyInteger

Callback Setting 634

msUISetOnClick

635

msUISetOnDoubleClick

636

msUISetOnTabChanged

637

msUISetOnResize

638

msUISetOnTextChanged

639

msUISetOnReturnPressed 640

641

msUISetOnScrollReleased 642 UI Components 643

644

MenuItem 645

MatforWindow 646

647

msUISetOnValueChanged

MainForm

TabControl

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

C HAPTER

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

Special Bold

Emphasis and codes

Type of Information

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

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

C HAPTER

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

pr ogram example

use fml

implicit none

ty pe (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))

if (mfIsNumeric(c)) write (*,*) 'c is numeric' if (mfIsComplex(d)) write (*,*) 'd is complex'

write (*,*) 'b is real'

!

Construct a logical mfArray.

e

= mfMagic(3) > 5

!Writes output message if e is logical. if (mfIsLogical(e)) write (*,*) 'e is logical'

!Deallocate mfArrays.

ca ll msFreeArgs(a, b, c, d, e)

e nd 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

pr ogram example

use fml

im plicit none

type (mfArray) :: lt

re

al(8) :: A(3,3)

!

Initialize A by using the random_number

!

procedure provided by Fortran.

ca

ll random_number(A)

!

Display the content of A by using MATFOR

!

display() procedure.

ca

ll 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')

ca ll msFreeArgs(lt)

e nd 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

L ower 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

pr ogram 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") e nd program

Result

a

=

0.9997

0.3917 0.6628

0.8225

0.7557 0.7853

0.4772

0.1380 0.5110

i =

Chapter 2 Essential Functions

31

j

2

2

1

2

3

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, dimensions of a.

Example

Code

pr ogram example

use fml

im plicit none

type (mfArray) :: a

in

teger :: s

a

= mfRand(4,3)

s

= mfSize(a)

, mn),

a)

returns the lengths of the first

n

call msDisplay(a, 'mfRand(4,3)', mf(s), 'mfSize(a)')

s

= mfSize(a, 1)

ca

ll msDisplay(mf(s), 'mfSize(a, 1)')

s

= mfSize(a, 2)

ca

ll msDisplay(mf(s), 'mfSize(a, 2)')

ca

ll msFreeArgs(a)

e nd program example

Result

mf Rand(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

m fSize(a) =

12

m fSize(a, 1) =

4

m fSize(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

pr ogram example

use fml

im plicit none

type (mfArray) :: a, b

in

teger :: c

!

Scalar

a

= 3

b

= mfNDims(a)

ca

ll msDisplay(b, 'Scalar mfArray has mfNDims')

!

Vector

a

= (/1, 2, 3/)

write(*,*) 'Vector mfArray has mfNDims ='

wr

ite(*,'(/,I3,/)') mfNDims(a)

!

Matrix

a

= mfMagic(3)

b

= mfNDims(a)

ca

ll msDisplay(b, 'Matrix mfArray has mfNDims')

!

Three-dimensional mfArray

a

= mfReshape(mfColon(1,8), (/2,2,2/))

b

= mfNDims(a)

ca

ll msDisplay(b, 'Three-dimensional mfArray has mfNDims')

!

Deallocates mfArray

ca

ll msFreeArgs(a, b)

e nd program example

Result Scalar mfArray has mfNDims = Vector mfArray has mfNDims = Matrix mfArray has mfNDims =

2

2

2

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

pr ogram example

use fml

im

plicit none

ty

pe(mfArray) :: x, s

!

Scalar mfArray

x

= 2

s

= mfShape(x)

ca

ll msDisplay( x, 'x', s, 'mfShape(x)')

!

Vector mfArray

x

= (/2, 3/)

s

= mfShape(x)

ca

ll msDisplay( x, 'x', s, 'mfShape(x)')

!

Matrix mfArray

x

= mfMagic(2)

s

= mfShape(x)

ca

ll msDisplay( x, 'x', s, 'mfShpae(x)')

!

Three-dimensional mfArray

x

= mfRand(2, 2, 2)

s

= mfShape(x)

ca

ll msDisplay( x, 'x', s, 'mfShape(x)')

!

Deallocate mfArray

ca

ll msFreeArgs(x, s)

e nd program example

Result

Chapter 2 Essential Functions

37

x

2

=

S hape(x) =

1 1

x =

2 3

S hape(x) =

1

x

1

4

=

2

3

2

S hape(x) =

2 2

x

(:,:,1) =

0.0341

0.7507

0.8502

0.1210

x

(:,:,2) =

0.2173

0.2558

0.4833

0.7332

S hape(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

pr ogram example

use fml

im plicit none

type(mfArray) :: x, y, z

lo

gical :: 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

ca

ll msFreeArgs(x, y, z)

e nd program example

Chapter 2 Essential Functions

39

Result mf All(x > 2) =

0

m fAll(x, 1) =

1

0

0

m fAll(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

pr ogram example

use fml

im

plicit none

ty

pe(mfArray) :: x, y, b

x

= mfMagic(3)

!

Check if any element of x is more than 5.

b

= mfAny(x>7)

ca

ll msDisplay(x, 'x', b, 'mfAny(x > 7)')

y

= mfAny(x>7, 1)

call msDisplay(y, 'mfAny(x>7, 1)')

y

= mfAny(x>7, 2)

ca

ll msDisplay(y, 'mfAny(x>7, 2)')

!

Deallocates mfArrays

ca

ll msFreeArgs(x, y)

e nd program example

Result

Chapter 2 Essential Functions

41

8

3

4

1

5

9

6

7

2

m fAny(x > 7) =

1

m fAny(x>7, 1) =

1 1

0

m fAny(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

pr ogram example

use fml

im plicit none

type (mfArray) :: a

in

teger :: l

a

= mfOnes(2, 5)

l

= mfLength(a)

ca

ll msDisplay(a, 'a', mf(l), 'mfLength(a)')

ca

ll msFreeArgs(a)

e nd program example

Result

a

=

1 1

1

1

1

1 1

1

1

1

m fLength(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

pr ogram example

use fml

im plicit none

type (mfArray) :: x, y, z

in

teger :: i

x

= reshape((/(i, i= 1, 24)/), (/2, 3, 4/))

ca

ll msDisplay(x, 'x')

!

Get x <= 12

y

= mfS(x, x <= 12)

ca

ll msDisplay(y, 'mfS(x, x <= 12)')

!

y = x(1:24) using 1x24 replace 2x3x4

y

= mfS(x, 1.to.24)

ca

ll 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)

ca

ll 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)

ca

ll msDisplay(y, 'mfS(x, 1.to.2, 1.to.12.step.3)')

!

y = x(24:1)

y

= mfS(x, MF_COL)

ca

ll msDisplay(y, 'mfS(x, MF_COL)')

!

y = x(1, 2, 3)

Chapter 2 Essential Functions

45

ca

ll 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/)))

ca

ll 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)

ca

ll 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)

ca ll 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)

ca ll 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)

ca ll 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)/))

ca ll 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)

ca ll 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)')

ca ll msFreeArgs(x, y)

e nd program example

Result x( :,:,1) =

3

4

1

2

5

6

x (:,:,2) =

7

8 10 12

x (:,:,3) =

13 15 17

9 11

46

MATFOR 4 in Fortran Reference Guide

x (:,:,4) =

19 21 23

20 22 24

m fS(x, x <= 12) =

1

2

3

4

5

6

7

8

9

10

11

12

m fS(x, 1.to.24) =

column

1 2

1 to 19

3

4

5

6

7

8

column 20 to 24

20 21 22 23 24

m fS(x, 1.to.2, 1.to.12) =

9 10

11 12 13 14 15 16

17 18 19

1 3

5

7

9

11 13 15

17 19 21 23

2 4

6

8 10

12 14 16

18 20 22 24

m fS(x, 1.to.2, 1.to.12.step.3) =

1 7 13 19

2 8 14 20

m fS(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

m fS(x, 1, 2, 3) =

15

m fS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,1) =

Chapter 2 Essential Functions

47

23 19

m fS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,2) =

6

5

2

1

m fS(x, mf((/2, 1/)), mf((/3, 1/)), mf((/4, 1, 3/)))(:,:,3) =

18

17

14

13

m sAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,1) =

1

2

3

4

5

0

m sAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,2) =

0

0

0

0

0

0

m sAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,3) =

13 15 17

14 16 18

m sAssign(mfS(y, y <= 12 .and. y >= 6), 0)(:,:,4) =

19 21 23

20 22 24

m sAssign(mfS(y, 1.to.24), 0)(:,:,1) =

0

2

3

4

5

6

m sAssign(mfS(y, 1.to.24), 0)(:,:,2) =

7

8 10 12

9 11

m sAssign(mfS(y, 1.to.24), 0)(:,:,3) =

13 15 17

14 16 18

m sAssign(mfS(y, 1.to.24), 0)(:,:,4) =

19 21 23

20 22 24

m sAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,1) =

0

0

0

0

0

0

m sAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,2) =

0

0

0

0

0

0

m sAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,3) =

0

0

0

0

0

0

m sAssign(mfS(y, 1.to.2, 1.to.12), 0)(:,:,4) =

0

0

0

0

0

0

m sAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,1) =

48

MATFOR 4 in Fortran Reference Guide

0 4

6

m sAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,2) =

0

0 10 12

9 11

m sAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,3) =

0

0

15 17

16 18

m sAssign(mfS(y, 1.to.2, 1.to.12.step.3), 0)(:,:,4) =

0

21 23

0

22 24

m sAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,1) =

31 3 33

32 4 34

m sAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,2) =

7 9 11

8 10 12

m sAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,3) =

13 15 17

14 16 18

m sAssign(mfS(y, 1.to.2, 1.to.3.step.2, 1.to.4.step.3), z)(:,:,4) =

35 21 37

36 22 38

m sAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,1) =

25 27 29

26 28 30

m sAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,2) =

31 33 35

32 34 36

m sAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,3) =

37 39 41

38 40 42

m sAssign(mfS(y, MF_COL), .t.(/(i, i= 25, 48)/))(:,:,4) =

43 45 47

44 46 48

m sAssign(mfS(y, 1, 2, 3), 60)(:,:,1) =

1

2

3

4

5

6

m sAssign(mfS(y, 1, 2, 3), 60)(:,:,2) =

7 9 11

8 10 12

m sAssign(mfS(y, 1, 2, 3), 60)(:,:,3) =

13 60 17

14 16 18

m sAssign(mfS(y, 1, 2, 3), 60)(:,:,4) =

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

8 10 12

9 11

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

pr ogram example

use fml

im plicit none

type (mfArray) :: a,b

re al(8) :: F(2,5)

call random_number(F) call msAssign(a, F) !Avoids stack memory copy. call msAssign(b,a)

ca ll msDisplay(a, 'a',b,'b')

!Deallocate mfArray

ca ll msFreeArgs(a)

e nd 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

pr ogram example

use fml im plicit none

type (mfArray) :: a, z real(8), pointer :: pd(:,:) co mplex(8), pointer :: pz(:,:)

a

= mfOnes(3, 3)

z

= mfComplex(a, a)

ca

ll msDisplay(a, 'a')

!

pd targets a

ca

ll msPointer(a, pd)

! a(3, 3) has been set to 5.0. pd(3, 3) = 5.0

ca

ll msDisplay(a, 'a')

ca

ll msDisplay(z, 'z')

!

pz targets z

ca

ll 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) ca ll msDisplay(z, 'z')

!Deallocate mfArray ca ll msFreeArgs(a, z)

e nd program example

Result

a

=

1

1

1

1

1

1

a

1

1

1

=

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