define_external(...,WRAPPER,...) - Maple Programming Help

Home : Support : Online Help : Programming : Calling External Routines : define_external/WRAPPER

define_external(...,WRAPPER,...)

generate and compile a C translation wrapper used by define_external

 Calling Sequence define_external(...,WRAPPER,...)

Description

 • When the WRAPPER option is used with define_external, a C file is created, compiled and linked into Maple.  This new library, called a wrapper library, contains the code necessary to translate Maple data types into data types recognized by C programs.
 • A C compiler is required to use this feature.  See COMPILE_OPTIONS for a description of the various settings available for configuring Maple to automatically compile the generated wrappers.
 • In addition to the data structures supported by wrapperless external call, generated wrappers support procedures (callbacks), structures, and unions.
 • A structure is a non-homogeneous collection of members, corresponding to a struct in C.
 STRUCT( member1::descriptor1, ..., memberN::descriptorN, options);
 • A union is similar to a structure, except that all the members start at the same memory address, hence only one member of the union is valid at any given time.
 UNION( member1::descriptor1, ..., memberN::descriptorN, options);
 • Each member::descriptor pair describes one member of the structure or union.  The descriptor is any of the basic external types recognized by define_external.
 • The options are used to specify what kind of data type the wrapper should expect for conversion purposes.  Valid options are TABLE and LIST.  Only one of these options can be specified, and once the wrapper has been generated only the declared type is accepted.  When tables are used, the member names correspond to table indices.  When lists are used, the member ordering is used to determine which element is accessed.  Lists are considered read-only.
 • A Maple procedure can be passed as an argument to an external function.
 PROC( arg1::descriptor1, ..., argN::descriptorN, RETURN::descriptor, options);

Examples

The following example shows how to declare an external function that takes callback parameters.  The external function is an implementation of Newton's method for finding a root of the given function, $f$.  The derivative of $f$, fprime must also be provided.  The initial guess is continuously improved until the absolute value of $f\left(\mathrm{guess}\right)$ is less than or equal to the given tolerance.  If a good solution cannot be found in 100 iterations, the computation aborts and 0 is returned, otherwise the improved guess is returned.  The external C function is defined as follows.

 #include #include double newton( double ( f ) (double), double ( fprime ) (double), double guess, double tolerance ) { int count = 0; while( fabs(f(guess)) > tolerance && count++ < 100 ) guess = guess - f(guess)/fprime(guess); return( count>=100 ? 0 : guess ); }

The Maple definition is:

 > $\mathrm{newton}≔\mathrm{define_external}\left('\mathrm{newton}','f'::\left(\mathrm{PROC}\left('x'::\left(\mathrm{float}[8]\right),'\mathrm{RETURN}'::\left(\mathrm{float}[8]\right)\right)\right),'\mathrm{fprime}'::\left(\mathrm{PROC}\left('x'::\left(\mathrm{float}[8]\right),'\mathrm{RETURN}'::\left(\mathrm{float}[8]\right)\right)\right),'\mathrm{guess}'::\left(\mathrm{float}[8]\right),'\mathrm{tolerance}'::\left(\mathrm{float}[8]\right),'\mathrm{RETURN}'::\left(\mathrm{float}[8]\right),'\mathrm{WRAPPER}',\mathrm{LIB}="c:/shared/newton.dll"\right):$

Pick an equation and find its derivative.

 > $f≔{x}^{4}+2{x}^{3}-14{x}^{2}+2x+1$
 ${f}{:=}{{x}}^{{4}}{+}{2}{}{{x}}^{{3}}{-}{14}{}{{x}}^{{2}}{+}{2}{}{x}{+}{1}$ (1)
 > $\mathrm{fprime}≔\frac{\partial }{\partial x}f$
 ${\mathrm{fprime}}{:=}{4}{}{{x}}^{{3}}{+}{6}{}{{x}}^{{2}}{-}{28}{}{x}{+}{2}$ (2)

The external function expects procedure arguments, so turn the above polynomials into procedures.

 > $f≔\mathrm{unapply}\left(f,x\right)$
 ${f}{:=}{x}{→}{{x}}^{{4}}{+}{2}{}{{x}}^{{3}}{-}{14}{}{{x}}^{{2}}{+}{2}{}{x}{+}{1}$ (3)
 > $\mathrm{fprime}≔\mathrm{unapply}\left(\mathrm{fprime},x\right)$
 ${\mathrm{fprime}}{:=}{x}{→}{4}{}{{x}}^{{3}}{+}{6}{}{{x}}^{{2}}{-}{28}{}{x}{+}{2}$ (4)

Call the external function to find the root.

 > $r≔\mathrm{newton}\left(f,\mathrm{fprime},1,1.{10}^{-9}\right)$
 ${r}{:=}{0.362199992775959822}$ (5)

Verify that this is a root.

 > $f\left(r\right)$
 ${-}{1.0}{}{{10}}^{{-9}}$ (6)