Introduction

The ToExternal package provides the capability of converting numerical Maple procedures into C code, compiling them, and linking them into the currently running kernel. This can be seen as a faster evalhf, as it is primarily designed for numerical computations.

In addition it can automatically be used by dsolve/numeric  for IVP and BVP problems, and pdsolve/numeric  for 1-time, 1-space dimension problems.

 Requirements & Limitations

The ToExternal package is a tool that ties together a number of things, but has strict requirements for use:

• Maple 9.5 or newer: Required for automatic use by dsolve and pdsolve numerical solution (the core package will run in Maple 9.0, but with no automatic use).
• A compiler: Currently only two compilers are supported, gcc  on UNIX, and mingw (or cygwin)   on Windows.

At this time, the intersection between the classes of functions that ToExternal can handle, and those that evalhf can handle is quite large, but there are the following major differences:

• 1) ToExternal can handle float and integer data, and Matrices/Vectors of float and integer data, but is not currently set up to handle general multi-dimensional Arrays or any Matrix/Vector/Array storage of anything other than float and integer data.
• 2) ToExternal cannot use any Maple global variables (evalhf can).
• 3) ToExternal cannot handle userinfo messages (evalhf can).
• 4) ToExternal can work with integer data and arrays of integer data as integer data, not by emulating it with floating point operations (evalhf cannot).
• 5) ToExternal cannot handle functions in a function call (evalhf can).
• 6) ToExternal cannot currently return Vectors or Matrices of data (evalhf can)

These restrictions are largely a limitation resulting from the primary application area of interest, namely fast solution of ODE and PDE problems.

 Setup for Use & Platform Issues

On all platforms, the library and help files should be unpacked in a single directory, and that directory should be added to Maple's libname on startup.

The easiest way to do this is by adding the line:

        libname := "installed directory",libname:

to your ~/.mapleinit  file (on UNIX) or   your maple.ini  file (on Windows - if not present this needs to be put in your Users directory)

On UNIX, you are now done, but for Windows there are additional steps needed to prepare it for use (due to operating system limitations).

1) You need to tell ToExternal the path to your mingw bin directory. If you installed mingw in "C:\Program Files\mingw" this can be accomplished (in Maple) with the command:

         ToExternal:-SetOption(mingw,compiler_path,"C:\\Program Files\\mingw\\bin");  

2) You need to set a temp directory. If, for example, you want to use "C:\temp" this can be accomplished with:

         ToExternal:-SetOption(mingw,temp_directory,"C:\\Temp");  

And now you should be ready to run.

Important : Why the extra requirements on Windows?

The second requirement is by far the ugliest. The problem is that under Windows it is not possible to delete a shared library while it is in use (Windows locks it), and unfortunately it is in use by Maple until after Maple is closed (so code running in Maple cannot remove it).

What this means is that any shared libraries created under Windows will accumulate, and never be deleted.

In addition, the Maple system directory is the default current directory when launching Maple, so it would be used for the shared libraries.

Choosing a temporary directory to place these in is useful, as then they can be cleaned out easily.

Once no Maple sessions are running that use the shared libraries, simply delete them all via " del m2c*.dll " from the temporary directory.

The first requirement is due to DOS shell limitations and PATH limitations (as the compile is a command line process).

Interface-specific issues:

When running ToExternal calls in Windows in the GUI, a dos shell will pop up whenever a system command (read as "call to the compiler") is run. This is not very pretty, but it is another O/S limitation.

 Functions

There are currently only 3 top-level functions available in the package, and these are:

• HotLink : This is the primary function, and it is responsible for the process of converting, compiling, and linking one or more Maple functions into compiled code.
• SetOption/GetOption : These functions are required only for set-up of the ToExternal package

 Automatic use by dsolve/numeric and pdsolve/numeric

Use of ToExternal by dsolve/numeric and pdsolve/numeric is accomplished through environment variable settings.

Maple's default IVP and DAE solvers can be set to use ToExternal by setting:

>	_Env_ivpnumeric_ToExternal := true:

Maple's default BVP solver can be set to use ToExternal by setting:

>	_Env_bvpnumeric_ToExternal := true:

And Maple's default PDE solver can be set to use ToExternal by setting:

>	_Env_pdenumeric_ToExternal := true:

In all cases, problems which cannot use ToExternal (for example, and ODE system involving Bessel functions) will be detected, and the default method will be used instead.

Detection of the success of the use of ToExternal can be accomplished by setting the infolevel of the following to 1:

>	infolevel[ToExternal:-HotLink] := 0:

>