return a properties structure of an rtable in external code - Maple Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : OpenMaple : C Application Programming Interface : RTable Manipulation : OpenMaple/C/RTableSettings

RTableGetSettings - return a properties structure of an rtable in external code

RTableGetDefaults - return the default properties structure of an rtable in external code

Calling Sequence

RTableGetSettings(kv, rts, rt)

RTableGetDefaults(kv, rts)

Parameters

kv

-

kernel handle of type MKernelVector

rts

-

pointer to an RTableSettings structure

rt

-

type ALGEB rtable object

Description

• 

These functions can be used in external code with OpenMaple or define_external.

• 

RTableGetSettings assigns the properties of the rtable rt to the supplied RTableSettings structure.

• 

RTableGetDefaults fills in the supplied RTableSettings structure with the default rtable properties, as implied by the rtable Maple command.  The num_dimensions setting has no default value, and must always be set before creating an rtable.

• 

The RTableSettings structure is defined in mpltable.h.  It contains the following settings.

SETTING

TYPE

DEFAULT

EXPLANATION

 

 

 

 

data_type

int

RTABLE_DAG

type of data in the rtable.

 

 

 

 

maple_type

ALGEB

anything

type assertion on data

 

 

 

contained in rtables

 

 

 

with data_type=RTABLE_DAG.

 

 

 

 

subtype

int

RTABLE_ARRAY

type of rtable,

 

 

 

Array, Matrix, or Vector.

 

 

 

 

storage

int

RTABLE_RECT

storage layout.

 

 

 

 

p1,p2

M_INT

0

optional parameters used

 

 

 

by some storage layouts.

 

 

 

 

order

int

RTABLE_FORTRAN

C or Fortran order indexing

 

 

 

(set to RTABLE_FORTRAN,

 

 

 

or RTABLE_C).

 

 

 

 

read_only

M_BOOL

FALSE

disallow data writes when true.

 

 

 

 

foreign

M_BOOL

FALSE

true if external program

 

 

 

manages data memory.  If the

 

 

 

pdata parameter to RTableCreate

 

 

 

is non-NULL, this field must be

 

 

 

set to TRUE.

 

 

 

 

num_dimensions

int

-1

a 5x5 rtable has 2 dimensions.

 

 

 

 

index_functions

ALGEB

MapleNULL

list of array indexing functions.

 

 

 

 

attributes

ALGEB

MapleNULL

attributes given to this rtable.

 

 

 

 

transpose

M_BOOL

FALSE

when true, transpose

 

 

 

the rtable at creation.

 

 

 

 

fill

ALGEB

0

the default value for

 

 

 

unspecified elements.

 

 

 

 

• 

The data_type field can have any of the following values.

SETTING

TYPE

EXPLANATION

 

 

 

RTABLE_DAG

ALGEB

Maple objects

RTABLE_CXDAG

ComplexFloatDAG

complex Maple objects

RTABLE_INTEGER8

char

8-bit integers

RTABLE_INTEGER16

short

16-bit integers

RTABLE_INTEGER32

int

32-bit integers

RTABLE_INTEGER64

long long

64-bit integers

RTABLE_FLOAT32

float

32-bit floating-point numbers

RTABLE_FLOAT64

double

64-bit floating-point numbers

RTABLE_COMPLEX

ComplexFloat64

64-bit complex float pair

 

 

 

• 

The subtype field can have any of the following values.

SETTING

EXPLANATION

 

 

RTABLE_ARRAY

Array

RTABLE_MATRIX

Matrix

RTABLE_COLUMN

column Vector

RTABLE_ROW

row Vector

 

 

• 

The storage field can have any of the following values.

SETTING

EXPLANATION

 

 

RTABLE_SPARSE

sparse format; a table

 

when data_type is RTABLE_DAG, otherwise

 

the index and data vector format used

 

by NAG.  p2 can be set to RTABLE_SPARSE_UPPER

 

to exclude storing entries below the diagonal

 

using this format.  Similarly, p2 can be set

 

to RTABLE_SPARSE_LOWER to exclude entries

 

above the diagonal.  By default p2 is

 

RTABLE_SPARSE_DEFAULT, which allows storage

 

of all entries.

 

 

RTABLE_EMPTY

no storage (usually used in

 

combination with an indexing

 

function like IdentityMatrix where

 

the values can be derived without

 

needing to be stored.

 

 

RTABLE_DIAG

only the diagonal entries

 

are stored.

 

 

RTABLE_BAND

banded storage;

 

where p1 and p2 refer to the

 

number of non-zero subdiagonals

 

and superdiagonals.

 

 

RTABLE_RECT

dense rectangular storage.

 

 

RTABLE_UPPTRI

only the upper triangle

 

(including the diagonal) is stored.

 

 

RTABLE_UPPTRIMINUS

the upper triangle

 

excluding the diagonal is stored.

 

 

RTABLE_UPPTRIPLUS

the upper triangle

 

plus the one subdiagonal is stored.

 

 

RTABLE_LOWTRI

only the lower triangle

 

(including the diagonal) is stored.

 

 

RTABLE_LOWTRIMINUS

the lower triangle

 

excluding the diagonal is stored.

 

 

RTABLE_LOWTRIPLUS

the lower triangle

 

plus the one superdiagonal is stored.

 

 

RTABLE_SCALAR

a single entry is stored.

 

 

• 

The subtype field can have any of the following values.

SETTING

EXPLANATION

 

 

RTABLE_ARRAY

Array

RTABLE_MATRIX

Matrix

RTABLE_COLUMN

column Vector

RTABLE_ROW

row Vector

 

 

• 

Usually the indexing function is used in conjunction with a non-dense storage.  For example, identity is commonly used with RTABLE_EMPTY storage, and symmetric is commonly used with RTABLE_UPPTRI storage. The index_functions field can have any of the following values.

SETTING

EXPLANATION

 

 

object of type ALGEB

the name or expression sequence of

 

indexing functions.

 

 

RTABLE_INDEX_ZERO

zero indexing function.

 

 

RTABLE_INDEX_BAND

band indexing function.

 

p1 and p2 must be set to indicate

 

the number of subdiagonals and

 

superdiagonals.

 

 

RTABLE_INDEX_CONSTANT

constant indexing function.

 

The fill value is used to denote

 

the constant stored in every entry

 

of the rtable.  Usually used in

 

combination with RTABLE_EMPTY storage.

 

 

RTABLE_INDEX_DIAGONAL

diagonal indexing function.

 

 

RTABLE_INDEX_SCALAR

scalar indexing function.

 

Uses the fill value for the main

 

diagonal entry.  If subtype is a

 

Vector format, then p1 is additionally

 

used to indicate which entry is filled

 

(instead of the diagonal).

 

 

RTABLE_INDEX_ANTIHERMITIAN

antihermitian indexing function.

 

 

RTABLE_INDEX_HERMITIAN

hermitian indexing function.

 

 

RTABLE_INDEX_UPPHESSEN

Hessenberg[upper] indexing function.

 

 

RTABLE_INDEX_LOWHESSEN

Hessenberg[lower] indexing function.

 

 

RTABLE_INDEX_IDENTITY

identity indexing function.

 

 

RTABLE_INDEX_ANTISYMMETRIC

antisymmetric indexing function.

 

 

RTABLE_INDEX_SYMMETRIC

symmetric indexing function.

 

 

RTABLE_INDEX_LOWTRI

triangular[lower] indexing function.

 

 

RTABLE_INDEX_UPPTRI

triangular[upper] indexing function.

 

 

RTABLE_INDEX_UNIUPPTRI

triangular[upper,unit] indexing function.

 

 

RTABLE_INDEX_UNILOWTRI

triangular[lower,unit] indexing function.

 

 

RTABLE_INDEX_UNIT

unit indexing function.

 

 

Examples

    #include <stdlib.h>

    #include "maplec.h"

    ALGEB M_DECL MyRandomDiagonal( MKernelVector kv, ALGEB *args )

    {

    M_INT argc, n, i;

    RTableSettings rts;

    M_INT bounds[4];

    ALGEB rt;

    INTEGER32 *data, slice;

    FLOAT64 density;

    argc = MapleNumArgs(kv,(ALGEB)args);

    if( argc != 2 ) {

        MapleRaiseError(kv,"two arguments expected");

            return( NULL );

        }

    n = MapleToM_INT(kv,args[1]);

    density = MapleToFloat64(kv,args[2]);

    slice = (INTEGER32)(density * 32767);

    RTableGetDefaults(kv,&rts);

    rts.num_dimensions = 2;

    rts.subtype = RTABLE_MATRIX;

    rts.data_type = RTABLE_INTEGER32;

    rts.storage = RTABLE_DIAG;

    rts.index_functions = (ALGEB)RTABLE_INDEX_DIAGONAL;

    rts.fill = ToMapleInteger(kv,-1);

    rts.order = RTABLE_C;

    rts.read_only = TRUE;

    rts.attributes = ToMapleName(kv,"MyRand",TRUE);

    bounds[0] = 1;

    bounds[1] = n;

    bounds[2] = 1;

    bounds[3] = n;

    rt = RTableCreate(kv,&rts,NULL,bounds);

    data = (INTEGER32*)RTableDataBlock(kv,rt);

    for( i=0; i<n; ++i ) {

        if( rand() % 32767 <= slice )

        data[i] = rand();

    }

    return( rt );

    }

Execute the external function from Maple.

withExternalCalling&colon;

dll:=ExternalLibraryNameHelpExamples&colon;

diag:=DefineExternalMyRandomDiagonal&comma;dll&colon;

M:=diag6&comma;0.6

M:=187241548700000010000001446567804000000201284860400000010000001

(1)

M1&comma;1:=9

Error, cannot assign to a read-only Matrix

See Also

CustomWrapper, define_external, OpenMaple, OpenMaple/C/API, OpenMaple/C/Examples, rtable


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam