Maplesoft Blog

The Maplesoft blog contains posts coming from the heart of Maplesoft. Find out what is coming next in the world of Maple, and get the best tips and tricks from the Maple experts.

Latest Posts Latest Blog Posts Feed

I've had a few request to provide some more information on External Calling, so I thought I would make a few posts about it. This first post will be a high level description of External Calling and how it works, with examples coming later. As External Calling is an advanced topic, I am going to assume you know how to compile a shared library and are generally familiar with the C language. Although this first post won't require any real programming knowledge.

What is External Calling?

External Calling is the name for Maple's ability to connect to and call functions from other programming languages. Maple uses this for various reasons. We have written our own libraries in C, C++ and Java to solve particular problems. We partner with various labs around the world who have developed code, often in languages like C or C++, so external calling is used to interface with their code. We also connect to high performance libraries like NAG and BLAS to provide those high performance routines in Maple. Of course, you can use External Calling to connect Maple to your code as well.

Although Maple can call various programming languages, the most common languages we connect to are C and C++, and those are the languages I am going to focus on.

How does it work?

In Maple, you call ?define_external or use the ?ExternalCalling package. Both these methods take a description of the function that you want to call and returns a Maple procedure. Normally you would assign the procedure to a name and then call the externally defined function just like any other Maple procedure.

There are a couple different ways to use define_external to connect to a shared library, the differences are mostly concerned with how the parameters given in Maple are converted to parameters used in the external function.

  • Wrapperless external calling. With wrapperless external calling, Maple calls a function implemented in the shared library by automatically converting the values given in Maple into valid types for the external function.
  • Generated wrappers: With generated wrappers, Maple automatically generates a small C library that handles conversions from Maple values to the values used in the external function. Using generated wrappers allows Maple to handle more data types, like call back procedures.
  • Custom wrappers: A custom wrapper is a C function that you write yourself. This function accepts arguments as Maple data structures and returns a Maple data structure. You are responsible for converting the Maple data structures into whatever forms you need and converting your computed value back into a Maple data structure. Maple provides the External Calling API to assist in working with Maple from the externally defined function.

The first two forms of external calling are the easiest to do, however they are also the most limited. Internally we exclusively (I think) use the third, custom wrapper, form of external calling. That is the form I am going to talk about.

Custom Wrapper

The name "custom wrapper" is a bit of a misnomer. The function that you write does not need to "wrap" anything, it can implement anything you want. As long as you can convert the result into a Maple data structure, you can pass it back into Maple. In fact Maple also supports returning generic data, via the ?MaplePointer routines, but that is a more complex topic for a later blog post.

Your external function is simply a C function with the following calling convention:

ALGEB CustomWrapper( MKernelVector kv, ALGEB args )

ALGEB is the C data type that represents a Maple data structure. The MKernelVector is a data structure that acts as an intermediary between your external calling routines and the Maple engine. You will need to pass this structure back into the External Calling API functions. Both of these types, plus the External Calling API functions are defined in a header, maplec.h, that needs to be included in your code. I will provide more details when I provide examples.

The External Calling API

The External Calling API is a set of functions that we make available for working with the Maple Engine from external code. Maple also allows third party applications to load the Maple engine as a shared library, we call this ?OpenMaple. The External Calling functions are also available in OpenMaple, so you will often see OpenMaple used in the Maple help pages. Most functions can be used in both OpenMaple and External Calling, except for a few that are OpenMaple specific and involve starting and stopping the Maple Engine.

Maple's help system documents all the External Calling functions so you can see what is available. There is an overview of the external calling functions on this page, ?ExternalCalling,C,API. Briefly, however there are functions for converting Maple types to C and back, creating and interacting with Maple data structures (list, set, rtable, table, string, etc), creating and interacting with Maple language elements (names, procedures, etc), printing to the Maple interface, memory allocation, evaluating Maple statements and raising exceptions. There is even a C interface to the Task Programming Model.

Next Time...

In my next post I will provide some examples of using the External Calling API to actually do stuff in an externally defined procedure.  However, I am going to spend some time trying to figure out the easiest way for you to get the tools you'll need to be able to develop externally defined functions yourself, so my next post might take a bit of time.


I have always preferred the notation  for the derivative of

Green Cars...

December 15 2010 Tom 4 724 MapleSim

My father’s first car when our family moved to North America was a 1970 Buick Skylark sedan, and the color was a majestic deep green. I was seven years old at the time and this was my first experience with a green car. It’s ironic that my life in North America started with a green car and has come full circle with green cars all over the place as far as my job is concerned. But of course, today’s green car is really about highly fuel efficient cars...

Like many in the technology industry, I am a big fan of science fiction films and I’ve written in the past about how exciting it is for me to have a job where science fiction and reality literally meet. Over the past few months, several key projects from various Maple and MapleSim users caught my attention for various reasons and once again, I was forced to giggle publicly as the shear cool factor of these applications overcame my normal mature demeanor.

The Canadian Lotto649 draws are randomized the old fashioned way, the draws are held using a Ryo-Catteau Tulipe ball machine made by a well respected French Company. The draws are video recorded in a secure studio, and broadcast live.  There is no reason to suspect that these draws might not be random, but let us look at some ways we might detect it if it were not random.

You could look at the Lottery draws as a generator for a binary sequence as I did in my previous post, but as Robert Israel pointed out in the comments, that encoding can hide some non-random behavior (e.g. if the number 25 appeared in every draw, that encoding would not appear less random).

This is not really the next part in my randomness series, but more of an aside.  I used Maple's embedded components to use the Lotto649 drawing data from my last post to create a historical lottery simulator.  Basically, you fill in your prefered numbers, and it simulates you playing the lottery in every draw since 1982.

In this series of blog posts, I have picked on Baseball win-loss records already.  Looking for other sources of things that might or might not be random, I decided to look at lottery draws.  Since I live in Canada, the obvious lottery to look at is the national Lotto 6/49.

A lotto 6/49 draw consists of drawing 6 numbered balls from...

I lived in the UK before making the barely-considered decision to move to Canada.  I still have savings denominated in pounds sterling (all dutifully declared on my Canadian tax return).  Accordingly, I keep a close watch on the GBP-CAD exchange rate so I have some sense of my net worth.

When I arrived in Canada in July 2008, one pound sterling bought $2, down from $2.30 two years before that.  Today, the pound has devalued further and is worth around...

In a series of posts now imported to the Maplesoft blog (starting here), I have been talking about pseudo-random number sequences, but since part of what kicked off this series was a paper on true random number generation (with LASERS!) I thought I would share some routines I wrote that alllow you to use the two main true random number sources available on the web (neither using lasers, sadly).

I spent this past week preparing a Webex presentation to a client who was interested in using Maple for a physics course in chaos. Of the two texts selected for the course, I had one on my own bookshelf. So I scanned Steven Strogatz' text Nonlinear Dynamics and Chaos (Addison Wesley, 1994) for topics that would profit from investigation with Maple.

Boyz from the eHood...

September 21 2010 Tom 4 724

One of the best things about growing up in the “Hood” is that it feels really good when you leave. I grew up in a neighborhood called Downsview in Toronto whose claim to fame used to be it was the home to the DeHavilland Aircraft company but today is more associated with ongoing issues of crime, poverty, and many other urban illnesses. So every time I hear that someone from the Hood did something great, I take notice and I take special pride. This is the story about...

In this post I'll introduce is a nice visual test of randomness from signal processing. The main idea of this test to look at how a random sequence correlates with itself.

It's been a while since I wrote one of these random posts, but I still have a couple more I wanted to write.  In this post, I want to describe one of the tests used in the paper that initially inspired this series of posts: the Wald-Wolfowitz runs test.  This test is interesting in that it does not test for uniformity

Mea Culpa...

September 09 2010 Tom 4 724

A sign of a very successful period of work is the tally of how many email messages I’ve written that start with … “First, let me apologize for the delay in my response…” Yes, if you are the recipient of one of these notes from me, you’re probably more annoyed than pleased that I’m finding lots of very interesting things to fill up my ever-shrinking Outlook schedule. It’s been one heck of a summer, and I’m behind on countless...

Randomness and Binary Rank...

August 13 2010 John May 1837 Maple

As alluded to in my previous post in this series, one of the most straight forward ways to test if a PRNG is generating good random sequences is by examining the frequency of 0's and 1's.  This is just a couple lines in Maple using Statistics:

(**) r1 := rand(0..1):L := [seq(r1(), i=1..10000)]:
(**) n := nops(L); tally := `+`(op(L));
(**) Statistics:-ChiSquareGoodnessOfFitTest(
[n-tally, tally], [n/2, n/2], ':-output'=':-hypothesis');
5 6 7 8 9 10 11 Last Page 7 of 16