Difference between revisions of "Special Subroutines"

From LIBISIS
Jump to navigation Jump to search
 
(3 intermediate revisions by the same user not shown)
Line 349: Line 349:
  
 
===IXFvalid===
 
===IXFvalid===
 +
This function will return''' '.true.' '''if the object is properly populated or valid, and''' '.false.' '''if it is not. If applied to an array of objects, it will only return '.true.' if '''every''' object is valid.
 +
 +
 +
'''F90 SYNTAX'''
 +
 +
 +
<pre>type(IXTclass)::object,object_array(:)
 +
logical::result
 +
 +
! checks for validity of object
 +
result=IXFvalid(object)
 +
 +
<b>! checks for validity of array of objects/b>
 +
result=IXFvalid(object_array)</pre>
 +
 
===IXFmark_valid===
 
===IXFmark_valid===
 +
 +
 +
This is a generic interface to the IXFmark_valid_class method.
 +
 +
 +
This subroutine is used inside a class method to mark an object as valid. It does not check the objects validity. Essentially it does the opposite to IXFclear_valid. This can be called provided an IXTbase has been defined in the class. An object is marked as invalid in its IXTbase. If this subroutine is applied on an array of objects it will mark all objects in that array as valid.
 +
 +
 +
'''F90 SYNTAX'''
 +
 +
<pre>type IXTclass
 +
  type(IXTbase)::base
 +
  integer(i4b),pointer::array_pointer(:)=>NULL()
 +
end type IXTclass
 +
:
 +
type(IXTclass)::object
 +
type(IXTclass),allocatable::object_array(:)
 +
 +
! using generic interface
 +
call IXFmark_valid(object)
 +
call IXFmark_valid(object_array)
 +
 +
! using class specific method
 +
call IXFmark_valid_class(object)
 +
call IXFmark_valid_class(object_array)</pre>
 +
 
===IXFclear_valid===
 
===IXFclear_valid===
 +
 +
 +
his is a generic interface to the IXFclear_valid_class method.
 +
 +
 +
This subroutine is used inside a class method to clear an objects validity or mark an object as invalid. Essentially it does the opposite to IXFmark_valid. This can be called provided an IXTbase has been defined in the class. An object is marked as invalid in its IXTbase. If this subroutine is applied on an array of objects it will mark all objects in that array as invalid.
 +
 +
 +
'''F90 SYNTAX'''
 +
 +
 +
<pre>type IXTclass
 +
  type(IXTbase)::base
 +
  integer(i4b),pointer::array_pointer(:)=>NULL()
 +
end type IXTclass
 +
:
 +
type(IXTclass)::object
 +
type(IXTclass),allocatable::object_array(:)
 +
 +
! using generic interface
 +
call IXFclear_valid(object)
 +
call IXFclear_valid(object_array)
 +
 +
! using class specific method
 +
call IXFclear_valid_class(object)
 +
call IXFclear_valid_class(object_array)</pre>
  
 
==other==
 
==other==
  
−
IXFdisplay
+
===IXFdisplay===
−
IXFpopulate_file
+
 
 +
 
 +
This is a generic interface to the IXFdisplay_class method.
 +
 
 +
 
 +
This subroutine will exhaustively print out the contents of an object to the defined screen, be that a matlab prompt, a fortran command window or a linux windows terminal. It can be passed an array of objects, but it will only print out the first five objects in the array.
 +
 
 +
 
 +
'''F90 syntax'''
 +
 
 +
 
 +
<pre>use IXMclass
 +
type(IXTclass)::object,object_array(:)
 +
type(IXTstatus)::status
 +
 
 +
! using generic interface
 +
call IXFdisplay(object,status)
 +
call IXFdisplay(object_array,status)
 +
 
 +
! using generic interface
 +
call IXFdisplay_class(object,status)
 +
call IXFdisplay_class(object_array,status)</pre>
 +
 
 +
 
 +
===IXFpopulate_file===
 +
 
 +
 
 +
This is a generic interface to the IXFpopulate_file_class method.
 +
 
 +
 
 +
This subroutine will generically populate an object from a binary nexus or XML file which has been defined in an IXTdata_source object, and MUST have the top handle as the classname of the object, ie if an IXTsource object is to be loaded from file, then the NEXUS entryname must be 'source'.
 +
 
 +
 
 +
'''F90 syntax'''
 +
 
 +
 
 +
<pre>use IXMclass
 +
type(IXTclass):: object
 +
type(IXTdata_source)::dso
 +
type(IXTstatus)::status
 +
 
 +
! using generic interface
 +
call IXFpopulate_file(object,dso,status)
 +
 
 +
! using class specific method
 +
call IXFpopulate_file_class(object,dso,status)</pre>

Latest revision as of 13:44, 2 April 2008

Memory Specific

There are three types of arrays used in the data structure and associated subroutines:


  • Array pointers
  • Allocatable arrays of objects
  • Standard FORTRAN allocatable arrays


Standard Fortran arrays are not declared as elements in the data structures but can be used temporarily in subroutines. There is a set of subroutines which can be used in these types as well as the built-in functions allocate() and deallocate().

Valid Functions

The following subroutines are valid for certain types of array of type real and integer:


array pointers and arrays of objects:

  • IXFalloc for arrays and arrays of objects
  • IXFrealloc for arrays and arrays of objects
  • IXFallocdims for arrays only
  • IXFreallocdims for arrays only
  • IXFdealloc for arrays and arrays of objects


standard FORTRAN allocatable arrays of type real and integer

  • IXFallocFortran
  • IXFreallocFortran
  • IXFallocdimsFortran
  • IXFreallocdimsFortran
  • IXFdeallocFortran


IXFalloc

This routine will allocate space to an n-dimensional array pointer (n=1-4) contained in a class, or allocate an allocatable array of objects (1 dimension only). If an array pointer is an argument it will assign matlab or fortran memory depending on which level access to the library is made from. Allocatable arrays of objects are not mirrored in matlab memory in the same way, so allocation is dealt with purely in fortran.


In the following example the class used must contain an array_pointer element in its definition. real & integer types are valid

F90 SYNTAX 

 type IXTclass
 integer(i4b),pointer::array_pointer(:)=>NULL()
 integer(i4b),pointer::array2d_pointer(:,:)=>NULL()
 integer(i4b),pointer::array3d_pointer(:,:,:)=>NULL()
 integer(i4b),pointer::array4d_pointer(:,:,:,:)=>NULL()
end type IXTclass
:
type(IXTclass)::object
type(IXTclass),allocatable::object_array(:)

type(IXTstatus)::status

integer(i4b) :: n1,n2,n3,n4

n1=25

! allocates object%array_pointer to a length 25 etc...
call IXFalloc(object%array_pointer,n1,status)
call IXFalloc(object%array2d_pointer,n1,n2,status)
call IXFalloc(object%array3d_pointer,n1,n2,n3,status)
call IXFalloc(object%array4d_pointer,n1,n2,n3,n4,status)

! allocates an array of 25 objects
call IXFalloc(object_array,n1,status)

IXFrealloc

This routine will reallocate space to a 1-dimensional array pointer contained in a class, or reallocate an allocatable array of objects. If the array pointer is unallocated then IXFalloc will be called internally. If the array is already allocated, the array length will be adjusted to the new length, and the contents preserved if the preserve argument is '.true.'.


If an array pointer is an argument it will assign matlab or fortran memory depending on which level access to the library is made from. Allocatable arrays of objects are not mirrored in matlab memory in the same way, so allocation is dealt with purely in fortran.


F90 SYNTAX 

type IXTclass
 integer(i4b),pointer::array_pointer(:)=>NULL()
end type IXTclass
:
type(IXTclass)::object
type(IXTclass),allocatable::object_array(:)

type(IXTstatus)::status

integer(i4b) :: size_of_array

logical::preserve

size_of_array=25 

! reallocates object%array_pointer to a length 25
call IXFrealloc(object%array_pointer,size_of_array,preserve,status)

! reallocates an array of 25 objects
call IXFrealloc(object_array,size_of_array,preserve,status)

IXFallocdims

This routine will allocate space to a 2/3/4-dimensional array pointer contained in a class In the following example the class used must contain an array_pointer element in its definition of appropriate dimensionality.


F90 SYNTAX 


type IXTclass
 integer(i4b),pointer::array2d_pointer(:,:)=>NULL()
 integer(i4b),pointer::array3d_pointer(:,:,:)=>NULL()
end type IXTclass
:

type(IXTclass)::object

type(IXTstatus)::status

integer(i4b) :: dim_2(2),dim_3(3)
allocates an n-dimensional array (n=2,3,4) depending on length of appropriately filled dimension array
object%array_pointer must be of appropriate dimensionality

dim_2=(/ 200,100 /)
dim_3=(/ 300,200,100 /)

! allocates a 200 by 100 element array
call IXFallocdims(object%array2d_pointer,dim_2,status)
call IXFallocdims(object%array2d_pointer,(/ 200,100 /),status)

! allocates a 300 by 200 by 100 element array
call IXFallocdims(object%array3d_pointer,dim_3,status)
call IXFallocdims(object%array3d_pointer,(/ 300,200,100 /),status)

IXFreallocdims

This routine will reallocate space to a 2/3/4-dimensional array pointer contained in a class. If the array pointer is unallocated then IXFallocdims will be called internally. If the array is allocated the array length will be adjusted to the new length, and the contents preserved if the preserve argument is '.true.'. In the following example the class used must contain an array_pointer element in its definition.


F90 SYNTAX 


type IXTclass
  integer(i4b),pointer::array2d_pointer(:,:)=>NULL()
  integer(i4b),pointer::array3d_pointer(:,:,:)=>NULL()
end type IXTclass
:

type(IXTclass)::object

type(IXTstatus)::status

integer(i4b) :: dim_2(2),dim_3(3)

logical::preserve


  • reallocates an n-dimensional array (n=2,3,4) depending on length of appropriately filled dimension array
  • object%array_pointer must be of appropriate dimensionality


dim_2=(/ 200,100 /)
dim_3=(/ 300,200,100 /)

! reallocates a 200 by 100 element array
call IXFallocdims(object%array2d_pointer,dim_2,preserve,status)
call IXFallocdims(object%array2d_pointer,(/ 200,100 /),preserve,status)

! reallocates a 300 by 200 by 100 element array
call IXFreallocdims(object%array3d_pointer,dim_3,preserve,status)
call IXFreallocdims(object%array3d_pointer,(/ 300,200,100 /),preserve,status)

IXFdealloc

This routine will deallocate space from an array pointer contained in a class irrespective of its dimensionality, or deallocate an allocatable array of objects.


In the following example the class used must contain an array_pointer element in its definition.


F90 SYNTAX 


type IXTclass
  integer(i4b),pointer::array_pointer(:)=>NULL()
  integer(i4b),pointer::array2d_pointer(:,:)=>NULL()
end type IXTclass
:
type(IXTclass)::object
type(IXTclass),allocatable::object_array(:)

type(IXTstatus)::status

! deallocates memory in object%array_pointer
call IXFdealloc(object%array_pointer,status)

! deallocates memory in object%2darray_pointer
call IXFdealloc(object%array2d_pointer,status)

! deallocates an allocatable array of objects
call IXFdealloc(object_array,status)

IXFallocFortran

Maximum four dimensions


F90 SYNTAX 


integer(i4b),allocatable::array(:)
integer(i4b),allocatable::array2d(:,:)
integer(i4b),allocatable::array3d(:,:,:)
integer(i4b),allocatable::array4d(:,:,:,:)
integer(i4b)::length_1,length_2,length_3,length_4
:
length_1 = 35
length_2 = 45
length_3 = 5
length_4 = 4

! allocates a 35 element array(:)
call IXFallocFortran(array, length_1 ,status)

! allocates a 35 by 45 element array2d(:,:) etc...
call IXFallocFortran(array2d, length_1,length_2 ,status)

call IXFallocFortran(array3d, length_1,length_2,length_3 ,status)

call IXFallocFortran(array4d, length_1,length_2 ,length_3,length_4 ,status)

IXFreallocFortran

Maximum 4 dimensions


F90 SYNTAX 


integer(i4b),allocatable::array(:)
integer(i4b),allocatable::array2d(:,:)
integer(i4b),allocatable::array3d(:,:,:)
integer(i4b),allocatable::array4d(:,:,:,:)
logical::preserve

integer(i4b)::length_1,length_2,length_3,length_4
:
length_1 = 35
length_2 = 45
length_3 = 5
length_4 = 4

! reallocates a 35 element array(:)
call IXFallocFortran(array, length_1 ,preserve,status)

! reallocates a 35 by 45 element array2d(:,:) etc...
call IXFallocFortran(array2d, length_1,length_2,preserve ,status)

call IXFallocFortran(array3d, length_1,length_2,length_3,preserve ,status)

call IXFallocFortran(array4d, length_1,length_2 ,length_3,length_4,preserve ,status)

IXFallocdimsFortran

F90 SYNTAX 


integer(i4b),allocatable::array(:)
integer(i4b),allocatable::array2d(:,:)
integer(i4b)::length_1,length_2
:
length_1 = 35
length_2 = 45

! allocates a 35 element array(:)
call IXFallocdimsFortran(array,(/ length_1 /),status)

! allocates a 35 by 45 element array2d(:,:)
call IXFallocdimsFortran(array2d,(/ length_1,length_2 /),status)

IXFreallocdimsFortran

F90 SYNTAX 


integer(i4b),allocatable::array(:)
integer(i4b),allocatable::array2d(:,:)
integer(i4b)::length_1,length_2
logical::preserve
:
length_1 = 35
length_2 = 45

! reallocates a 35 element array(:)
call IXFreallocdimsFortran(array,(/ length_1 /),preserve,status)

! reallocates a 35 by 45 element array2d(:,:)
call IXFreallocdimsFortran(array2d,(/ length_1,length_2 /),preserve,status)

IXFdeallocFortran

F90 SYNTAX 


integer(i4b),allocatable::array(:)
integer(i4b),allocatable::array2d(:,:)
:

! deallocates array(:)
call IXFdeallocFortran(array,status)

! deallocates array2d(:,:)
call IXFallocFortran(array2d,status)

Validity

Valid Functions

When an object has been properly populated with real data which is self-consistent it is marked as being 'valid'. There are routines to determine an objects validity and to mark an object as valid. These operations can only be used on objects which contain an IXTbase object.


  • IXFvalid for objects and arrays of objects


Subroutines which can only be used within class methods of object


  • IXFmark_valid for objects and arrays of objects
  • IXFclear_valid for objects and arrays of objects

IXFvalid

This function will return '.true.' if the object is properly populated or valid, and '.false.' if it is not. If applied to an array of objects, it will only return '.true.' if every object is valid.


F90 SYNTAX 


type(IXTclass)::object,object_array(:)
logical::result

! checks for validity of object
result=IXFvalid(object)

<b>! checks for validity of array of objects/b>
result=IXFvalid(object_array)

IXFmark_valid

This is a generic interface to the IXFmark_valid_class method.


This subroutine is used inside a class method to mark an object as valid. It does not check the objects validity. Essentially it does the opposite to IXFclear_valid. This can be called provided an IXTbase has been defined in the class. An object is marked as invalid in its IXTbase. If this subroutine is applied on an array of objects it will mark all objects in that array as valid.


F90 SYNTAX 

type IXTclass
  type(IXTbase)::base
  integer(i4b),pointer::array_pointer(:)=>NULL()
end type IXTclass
:
type(IXTclass)::object
type(IXTclass),allocatable::object_array(:)

! using generic interface
call IXFmark_valid(object)
call IXFmark_valid(object_array)

! using class specific method
call IXFmark_valid_class(object)
call IXFmark_valid_class(object_array)

IXFclear_valid

his is a generic interface to the IXFclear_valid_class method.


This subroutine is used inside a class method to clear an objects validity or mark an object as invalid. Essentially it does the opposite to IXFmark_valid. This can be called provided an IXTbase has been defined in the class. An object is marked as invalid in its IXTbase. If this subroutine is applied on an array of objects it will mark all objects in that array as invalid.


F90 SYNTAX 


type IXTclass
  type(IXTbase)::base
  integer(i4b),pointer::array_pointer(:)=>NULL()
end type IXTclass
:
type(IXTclass)::object
type(IXTclass),allocatable::object_array(:)

! using generic interface
call IXFclear_valid(object)
call IXFclear_valid(object_array)

! using class specific method
call IXFclear_valid_class(object)
call IXFclear_valid_class(object_array)

other

IXFdisplay

This is a generic interface to the IXFdisplay_class method.


This subroutine will exhaustively print out the contents of an object to the defined screen, be that a matlab prompt, a fortran command window or a linux windows terminal. It can be passed an array of objects, but it will only print out the first five objects in the array.


F90 syntax 


use IXMclass
type(IXTclass)::object,object_array(:)
type(IXTstatus)::status

! using generic interface
call IXFdisplay(object,status)
call IXFdisplay(object_array,status)

! using generic interface
call IXFdisplay_class(object,status)
call IXFdisplay_class(object_array,status)


IXFpopulate_file

This is a generic interface to the IXFpopulate_file_class method.


This subroutine will generically populate an object from a binary nexus or XML file which has been defined in an IXTdata_source object, and MUST have the top handle as the classname of the object, ie if an IXTsource object is to be loaded from file, then the NEXUS entryname must be 'source'.


F90 syntax 


use IXMclass
type(IXTclass):: object
type(IXTdata_source)::dso
type(IXTstatus)::status

! using generic interface
call IXFpopulate_file(object,dso,status)

! using class specific method
call IXFpopulate_file_class(object,dso,status)
Retrieved from "http://libisis.org/index.php?title=Special_Subroutines&oldid=2226"