General Operations

These are generic subroutines which should be valid for every class

IXFcreate

This is a generic interface to the IXFcreate_class method.

The Create operation strictly takes all the elements required to define a class and creates the resulting object. If an element of the object is another class then it requires that the structure element is already valid. If you wish to define a class with a fewer number of elements than are in the structure, or if you wish to implicitly define a sub-object in the create operation then it will be necessary to overload the IXFcreate interface with your new subroutine. For example if you wish to create a dataset_1d object from just an x, signal and error array then you will have to write a subroutine for eg IXFcreate_xse_d1d and interface it to IXFcreate at the top of the IXMdataset_1d module.

F90 syntax

 use IXMclass
 type(IXTclass)::object
 
 various :: element_1,element_2,...,element_N
 
 call IXFcreate(object,element_1,element_2,...,element_N,status)

for example with class=datum_array

 use IXMdatum_array
 type(IXTdatum_array)::datumarray
 
 real(dp)::signal(30),error(30)

where signal and error are filled arrays

 ! using generic interface
 call IXFcreate(datumarray,signal,error,status)

 ! using class specific method
 call IXFcreate_datum_array(datumarray,signal,error,status)

IXFset

This is a generic interface to the IXFset_class method.

The Set operation can only be performed on a properly filled or 'valid' object. It takes an optional number of arguments to modify the object contents. IXFcheck is called at the end to determine that the edited structure is correctly formed. Error flags are raised if there is any inconsistency. The optional arguments must always be specified by keywords.

The general calling syntax of the subroutine is: call IXFset_class(object,status,option_1=arg_1...,option_N=arg_N,ref=reference_object)

The 'ref' argument is used to copy the values of a reference object to another. In this case the object being modified does not have to be initialised, but the refence object must be valid, otherwise the subroutine will fail.

This operation is valid for all classes.

F90 syntax

 use IXMclass
 
 type(IXTclass):: object1, object_ref
 
 integer(i4b):: arg_1
 
 real(dp):: arg_2
 
 type(IXTstatus)::status
 
 call IXFset(object1,status,option_1=arg_1,option_2=arg_2)
 
 call IXFset(object1,status,ref=object_ref)

if a ref argument is passed as well as other arguments, the object will initially take on the attributes of the reference object, and then the other arguments will be changed

 call IXFset(object1,option_1=arg_1,status,ref=object_ref)

For example with class=dataset_1d where w1 and w1ref are existing dataset_1d objects

 use IXMdataset_1d
 
 type(IXTdataset_1d):: w1, w1ref
 
 character(len=short_len)::newx_units='meV' 
 
 type(IXTstatus)::status
 
 !using generic interface
 call IXFset(w1,status,x_units=newx_units)
 
 !using class specific method
 
 call IXFset_dataset_1d(w1,status,ref=w1ref)

IXFcheck

This is a generic interface to the IXFcheck_class method.

A Check operation will determine that an object has been created properly, eg. with an appropriate number of elements in its arrays for either a point or histogram dataset. Error flags are raised if there is any inconsistency.

The interface MUST be used if you want to check an array of structures.

F90 syntax

 use IXMclass
 
 type(IXTclass):: object
 
 type(IXTstatus)::status
 
 call IXFcheck(object,status)

For example with class=dataset_2d

 use IXMdataset_2d
 
 type(IXTdataset_2d):: dataset_2d
 
 type(IXTstatus)::status
 
 ! using generic interface
 call IXFcheck(dataset_2d,status)
 
 ! using class specific method
 call IXFcheck_dataset_2d(dataset_2d,status)

IXFget

This is a generic interface to the IXFget_class method.

This routine will 'get' elements from an object according to which elements have been requested. Array arguments to be filled from the object must be the same length as those they are receiving, otherwise error flags are raised if there is any inconsistency. The optional arguments must always be specified by keywords.

IXFget_class(object,status,option_1=arg_1...,option_N=arg_N,wout=copy)

The wout argument is special. If you want to make a copy of an object then this is the resultant object.

F90 SYNTAX

 type IXTclass
 integer(i4b),pointer::array_pointer(:)=>NULL()
 real(dp)::real_var=0.0
 character(len=short_len)::string='object'
 end type IXTclass
 :
 type(IXTclass)::object,o_copy
 real(dp):: real_var
 integer(i4b)::array(:)
 character(len=short_len)::string_out
 array(:) must be of same length as array_pointer(:)
 ! using generic interface
 ! fills supplied array with contents of object%array_pointer and real_var with object%real_var value
 IXFget(object,status,array=array_pointer,real_var=real_var)  
 
 ! fills string_out with value of object%string and copies object into o_copy
 IXFget(object,status,string=string_out,wout=o_copy)
 
 ! using class specific method
 ! fills supplied array with contents of object%array_pointer and real_var with object%real_var value
 IXFget_class(object,status,array=array,real_var=real_var)

 ! fills string_out with value of object%string and copies object into o_copy
 IXFget_class(object,status,string=string_out,wout=o_copy)

IXFget_alloc

This is a generic interface to the IXFget_class method

IXFget_alloc can be called with all the same arguments as IXFget, but the pointer array elements can be allocatable arrays, the arrays are allocated to the appropriate length and IXFget_class is called underneath to fill them up.

IXFget_alloc_class(object,status,option_1=arg_1...,option_N=arg_N)

class=dataset_2d

F90 syntax

 use IXMdataset_2d
 
 type(IXTdataset_2d)::object
 real(dp),allocatable::y_array
 
 IXFget_alloc_dataset_2d(object,status,y_alloc=y_array)

IXFget_ptr

very dangerous function, not implemented in all classes

This routine will fill a pointer argument with the pointer of an object array element according to the keyword argument it is called with.

IXFget_ptr_class(object,option_1=arg_1...,option_N=arg_N)

class=dataset_1d

F90 syntax

 use IXMdataset_1d
 
 type(IXTdataset_1d)::object
 real(dp),pointer::xptr_out(:)
 
 IXFget_ptr_dataset_1d(object,x_ptr=xptr_out)

IXFdestroy

his is a generic interface to the IXFdestroy_class method.

A Destroy operation will deallocate all the memory of any arrays in an object and mark it as invalid. It will also recursively destroy any sub-objects contained therein. The object will still exist and it's pointers will be NULL. Objects without any arrays will only be marked as invalid. All other elements in the data structure such as character strings and logicals will be set to their default values.

If this operation is called on an array of structures, the individual structures will be destroyed but the array will not be deallocated. In this case the interface MUST be used. If you want to deallocate the array as well the IXFdealloc subroutine must be called instead.

F90 syntax

 use IXMclass
 type(IXTclass):: object

 type(IXTstatus)::status

 call IXFdestroy(object,status)
 For example with class=dataset_1d
 use IXMdataset_1d
 type(IXTdataset_1d):: d1d, array_d1d(:)

 type(IXTstatus)::status

 ! using generic interface
 call IXFdestroy(d1d,status)
 call IXFdestroy(array_d1d,status)
 
 ! using class specific method
 call IXFdestroy_dataset_1d(d1d,status)

IXFcopy

This is a generic interface to the IXFcopy_class method.

The copy operation will make a copy of an object. It is a built-in subroutine which is not defined in any of the modules. It requires that a properly written IXFset subroutine has been defined, with a ref argument. Otherwise the library will not compile.

If you wish to copy an array of structures the interface must be used. The lengths of the arrays MUST be the same length, otherwise an error flag is raised.

F90 syntax

 use IXMclass
 type(IXTclass)::object_orig,object_copy 
 
 type(IXTstatus)::status
 
 call IXFcopy(object_orig,object_copy,status)
 For example with class=dataset_2d
 use IXMdataset_2d
 
 type(IXTdataset_2d):: d2d_orig,d2d_copy,array_orig(:),array_copy(:) 
 
 type(IXTstatus)::status
 
 ! using generic interface
 call IXFcopy(d2d_orig,d2d_copy,status)
 call IXFcopy(array_orig,array_copy,status)
 
 ! using class specific method
 call IXFcopy_dataset_2d(d2d_orig,d2d_copy,status)

Arithmetic Operations

These are specific subroutines which are valid on certain classes only

BinaryOperations

IXFplus

This is a generic interface to the IXFplus_class method.

This subroutine will add together two objects, an object to a scalar array of the same dimensionality (ie a 2d array to an IXTdataset_2d object) or an object to a scalar.

In the special case of an IXTdataset_2d object, it will add an array of IXTdataset_1d objects.

F90 syntax

use IXMclass
type(IXTclass)::class1,class2,result
real(dp)::scalar
type(IXTstatus)::status
:
call IXFplus(result,class1,class2,status)
call IXFplus(result,class1,scalar,status)
call IXFplus(result,scalar,class1,status)

For example with class=dataset_2d where w2,w2 are appropriately filled IXTdataset_2d objects and arrayd1d is an appropriately filled array of IXTdataset_1d objects.

use IXMdataset_2d 
use IXMdataset_1d
type(IXTdataset_2d):: w1,w2, wres
type(IXTdataset_1d):: arrayd1d(:)
real(dp)::scalar,scalar2d(:,:)
type(IXTstatus)::status

!using generic interface
! types/types and types/scalars
call IXFplus(wres,w1,w2,status) ! wres=w1+w2
call IXFplus(wres,scalar,w1,status) ! wres=scalar+w1
call IXFplus(wres,w1,scalar,status) ! wres=w1+scalar
! types/arrays
call IXFplus(wres,scalar2d,w1,status) ! wres=scalar2d+w1
call IXFplus(wres,w1,scalar2d,status) ! wres=w1+scalar2d
! types/arrays of types
call IXFplus(wres,arrayd1d,w2,status) ! wres=w2+arrayd1d
call IXFplus(wres,w2,arrayd1d,status) ! wres=arrayd1d+w2 

!using class specific method

! types/types and types/scalars
call IXFplus_dataset_2d(wres,w1,w2,status) ! wres=w1+w2
call IXFplus_dataset_2d(wres,scalar,w1,status) ! wres=scalar+w1
call IXFplus_dataset_2d(wres,w1,scalar,status) ! wres=w1+scalar
! types/arrays
call IXFplus_dataset_2d(wres,scalar2d,w1,status) ! wres=scalar2d+w1
call IXFplus_dataset_2d(wres,w1,scalar2d,status) ! wres=w1+scalar2d
! types/arrays of types
call IXFplus_dataset_2d(wres,arrayd1d,w2,status) ! wres=w2+arrayd1d
call IXFplus_dataset_2d(wres,w2,arrayd1d,status) ! wres=arrayd1d+w2 

IXFminus

This is a generic interface to the IXFminus_class method.

This subroutine will subtract two objects, an object from a scalar array of the same dimensionality (ie a 2d array to an IXTdataset_2d object) or an object from a scalar.

In the special case of an IXTdataset_2d object, it will subtract an array of IXTdataset_1d objects.

F90 syntax

use IXMclass
type(IXTclass)::class1,class2,result
real(dp)::scalar
type(IXTstatus)::status
:
call IXFminus(result,class1,class2,status)
call IXFminus(result,class1,scalar,status)
call IXFminus(result,scalar,class1,status)

For example with class=dataset_2d where w2,w2 are appropriately filled IXTdataset_2d objects and arrayd1d is an appropriately filled array of IXTdataset_1d objects.

use IXMdataset_2d
use IXMdataset_1d
type(IXTdataset_2d):: w1,w2, wres
type(IXTdataset_1d):: arrayd1d(:)
real(dp)::scalar,scalar2d(:,:)
type(IXTstatus)::status
:
!using generic interface
! types/types and types/scalars
call IXFminus(wres,w1,w2,status) ! wres=w1-w2
call IXFminus(wres,scalar,w1,status) ! wres=scalar-w1
call IXFminus(wres,w1,scalar,status) ! wres=w1-scalar
! types/arrays
call IXFminus(wres,scalar2d,w1,status) ! wres=scalar2d-w1
call IXFminus(wres,w1,scalar2d,status) ! wres=w1-scalar2d
! types/arrays of types
call IXFminus(wres,arrayd1d,w2,status) ! wres=w2-arrayd1d
call IXFminus(wres,w2,arrayd1d,status) ! wres=arrayd1d-w2 

!using class specific method
! types/types and types/scalars
call IXFminus_dataset_2d(wres,w1,w2,status) ! wres=w1-w2
call IXFminus_dataset_2d(wres,scalar,w1,status) ! wres=scalar-w1
call IXFminus_dataset_2d(wres,w1,scalar,status) ! wres=w1-scalar
! types/arrays
call IXFminus_dataset_2d(wres,scalar2d,w1,status) ! wres=scalar2d-w1
call IXFminus_dataset_2d(wres,w1,scalar2d,status) ! wres=w1-scalar2d
! types/arrays of types
call IXFminus_dataset_2d(wres,arrayd1d,w2,status) ! wres=w2-arrayd1d
call IXFminus_dataset_2d(wres,w2,arrayd1d,status) ! wres=arrayd1d-w2 

IXFtimes

This is a generic interface to the IXFtimes_class method.

This subroutine will multiply together two objects, an object with a scalar array of the same dimensionality (ie a 2d array with an IXTdataset_2d object) or an object with a scalar.

In the special case of an IXTdataset_2d object, it will multiply an array of IXTdataset_1d objects.

F90 syntax

use IXMclass
type(IXTclass)::class1,class2,result
real(dp)::scalar
type(IXTstatus)::status
:
call IXFtimes(result,class1,class2,status)
call IXFtimes(result,class1,scalar,status)
call IXFtimes(result,scalar,class1,status)

For example with class=dataset_2d where w2,w2 are appropriately filled IXTdataset_2d objects and arrayd1d is an appropriately filled array of IXTdataset_1d objects.

use IXMdataset_2d 
use IXMdataset_1d
type(IXTdataset_2d):: w1,w2, wres
type(IXTdataset_1d):: arrayd1d(:)
real(dp)::scalar,scalar2d(:,:)
type(IXTstatus)::status
:
!using generic interface
! types/types and types/scalars
call IXFtimes(wres,w1,w2,status) ! wres=w1*w2
call IXFtimes(wres,scalar,w1,status) ! wres=scalar*w1
call IXFtimes(wres,w1,scalar,status) ! wres=w1*scalar
! types/arrays
call IXFtimes(wres,scalar2d,w1,status) ! wres=scalar2d*w1
call IXFtimes(wres,w1,scalar2d,status) ! wres=w1*scalar2d
! types/arrays of types
call IXFtimes(wres,arrayd1d,w2,status) ! wres=w2*arrayd1d
call IXFtimes(wres,w2,arrayd1d,status) ! wres=arrayd1d*w2 

!using class specific method
! types/types and types/scalars
call IXFtimes_dataset_2d(wres,w1,w2,status) ! wres=w1*w2
call IXFtimes_dataset_2d(wres,scalar,w1,status) ! wres=scalar*w1
call IXFtimes_dataset_2d(wres,w1,scalar,status) ! wres=w1*scalar
! types/arrays
call IXFtimes_dataset_2d(wres,scalar2d,w1,status) ! wres=scalar2d*w1
call IXFtimes_dataset_2d(wres,w1,scalar2d,status) ! wres=w1*scalar2d
! types/arrays of types
call IXFtimes_dataset_2d(wres,arrayd1d,w2,status) ! wres=w2*arrayd1d
call IXFtimes_dataset_2d(wres,w2,arrayd1d,status) ! wres=arrayd1d*w2 

IXFdivide

This is a generic interface to the IXFdivide_class method.

This subroutine will divide one objects by another, an object by a scalar array of the same dimensionality (ie a 2d array by an IXTdataset_2d object) or an object by a scalar.

In the special case of an IXTdataset_2d object, it will divide an array of IXTdataset_1d objects.

F90 syntax

use IXMclass
type(IXTclass)::class1,class2,result
real(dp)::scalar
type(IXTstatus)::status
:
call IXFdivide(result,class1,class2,status)
call IXFdivide(result,class1,scalar,status)
call IXFdivide(result,scalar,class1,status)

For example with class=dataset_2d where w2,w2 are appropriately filled IXTdataset_2d objects and arrayd1d is an appropriately filled array of IXTdataset_1d objects.

use IXMdataset_2d 
use IXMdataset_1d
type(IXTdataset_2d):: w1,w2, wres
type(IXTdataset_1d):: arrayd1d(:)
real(dp)::scalar,scalar2d(:,:)
type(IXTstatus)::status
:
!using generic interface
! types/types and types/scalars
call IXFdivide(wres,w1,w2,status) ! wres=w1/w2
call IXFdivide(wres,scalar,w1,status) ! wres=scalar/w1
call IXFdivide(wres,w1,scalar,status) ! wres=w1/scalar
! types/arrays
call IXFdivide(wres,scalar2d,w1,status) ! wres=scalar2d/w1
call IXFdivide(wres,w1,scalar2d,status) ! wres=w1/scalar2d
! types/arrays of types
call IXFdivide(wres,arrayd1d,w2,status) ! wres=w2/arrayd1d
call IXFdivide(wres,w2,arrayd1d,status) ! wres=arrayd1d/w2 

!using class specific method
! types/types and types/scalars
call IXFdivide_dataset_2d(wres,w1,w2,status) ! wres=w1/w2
call IXFdivide_dataset_2d(wres,scalar,w1,status) ! wres=scalar/w1
call IXFdivide_dataset_2d(wres,w1,scalar,status) ! wres=w1/scalar
! types/arrays
call IXFdivide_dataset_2d(wres,scalar2d,w1,status) ! wres=scalar2d/w1
call IXFdivide_dataset_2d(wres,w1,scalar2d,status) ! wres=w1/scalar2d
! types/arrays of types
call IXFdivide_dataset_2d(wres,arrayd1d,w2,status) ! wres=w2/arrayd1d
call IXFdivide_dataset_2d(wres,w2,arrayd1d,status) ! wres=arrayd1d/w2 

IXFpower

This is a generic interface to the IXFpower_class method.

This subroutine will raise one object to the power of another object or an object to the power of a scalar.

F90 syntax

use IXMclass
type(IXTclass)::class1,class2,result
real(dp)::scalar
type(IXTstatus)::status
:
call IXFpower(result,class1,class2,status)
call IXFpower(result,class1,scalar,status)
call IXFpower(result,scalar,class1,status)
For example with class=dataset_2d where w2,w2 are appropriately filled IXTdataset_2d objects 
use IXMdataset_2d
type(IXTdataset_2d):: w1,w2, wres
real(dp)::scalar
type(IXTstatus)::status
:

!using generic interface

! types/types and types/scalars
call IXFpower(wres,w1,w2,status) ! wres=w1^w2
call IXFpower(wres,scalar,w1,status) ! wres=scalar^w1
call IXFpower(wres,w1,scalar,status) ! wres=w1^scalar

!using class specific method

! types/types and types/scalars
call IXFpower_dataset_2d(wres,w1,w2,status) ! wres=w1^w2
call IXFpower_dataset_2d(wres,scalar,w1,status) ! wres=scalar^w1
call IXFpower_dataset_2d(wres,w1,scalar,status) ! wres=w1^scalar 

UnaryOperations

There are eight different unary operations which can be performed on an object

The general calling syntax of the subroutine is (see below for further details):

call IXFoperation_class(result, object, status)

Each of these subroutines can also be called through the Unary Operations Interface.

Operations:

• log - takes the natural logarithm of an object
• exp - takes the exponential of an object
• sin - takes the sine of an object
• cos - takes the cosine of an object
• tan - takes the tangent of an object
• sinh - takes the hyperbolic sine of an object
• cosh - takes the hyperbolic cosine of an object
• tanh - takes the hyperbolic tangent of an object

Classes for which operations are valid:

• IXTdatum
• IXTdatum_array
• IXTdataset_1d
• IXTdataset_2d

F90 syntax

use IXMclass
type(IXTclass):: object, result
type(IXTstatus)::status
call IXFoperation_class(result,object,status)

For example with operation=sinh class=dataset_1d

use IXMdataset_1d

type(IXTdataset_1d):: w1, wres
type(IXTstatus)::status

call IXFsinh_dataset_1d(wres,w1,status)