FunctionCompile

✖
`FunctionCompile`

[Experimental]

✖

FunctionCompile[f]

generates a compiled code function from a pure function.

✖

FunctionCompile[{f₁,f₂,…}]

generates a list of compiled code functions from a list of pure functions.

✖

FunctionCompile[k₁f₁,k₂f₂,…]

generates an association of compiled code functions from an association of Wolfram Language functions.

✖

FunctionCompile[defs,fspec]

uses the local auxiliary definitions defs.

Details and Options

The function f is typically specified as a Function pure function. The variables in the Function object are typically annotated with Typed.
The CompiledCodeFunction objects created by FunctionCompile can be applied to suitable arguments just like the uncompiled functions.
Inside f, KernelFunction can be used to indicate functions that should directly use the Wolfram Engine rather than being compiled into low-level code.
Inside f, DownValuesFunction can be used to compile definitions attached to a symbol.
The function f can be specified purely as the name of a function that exists as a declaration in the compiler environment.
In FunctionCompile[defs,fspec], calls from fspec can be made to local auxiliary definitions defs. These definitions are only used for this call to FunctionCompile.
Auxiliary definitions used inside fspec can also be provided by giving a CompilerEnvironment option.
The code in the CompiledCodeFunction object can be output for external purposes using FunctionCompileExportLibrary and related functions.
When the option TargetSystem is used to specify additional architectures, this helps the output to be moved between different platforms without having to run the compilation again.
The following options can be given:

CompilerEnvironment	Automatic	an environment of definitions for compilation
CompilerOptions	Automatic	detailed options for the compilation pipeline
CompilerRuntimeErrorAction	Automatic	the behavior when there is an unrecoverable error while executing low-level code
ProgressReporting	Automatic	how to report progress during the compilation
TargetSystem	Inherited	machine architectures for code generation
UseEmbeddedLibrary	False	create and embed a shared library for this architecture

Possible settings for TargetSystem are:

	Automatic	generate additional code for key machine architectures
	All	generate additional code for all machine architectures
	trg	generate additional code for machine architecture trg
	{trg₁,trg₂,…}	generate additional code for machine architectures {trg₁,trg₂,…}

The possible values of TargetSystem are given in the list $TargetSystems.
Possible values for CompilerRuntimeErrorAction are:

	Automatic	rerun the computation in the Wolfram Engine if it avoids compiler-specific code
	"Evaluate"	always rerun the computation in the Wolfram Engine
	None	return a failure object that represents the error
	fun	apply fun to the failure object and return the result

Examples

open allclose all

Basic Examples (6)Summary of the most common use cases

Compile a Function into a compiled code function:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-ck3oom

Out[1]=1

The CompiledCodeFunction evaluates with an argument of the correct type:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-lj8jw2

Out[2]=2

If unexpected arguments are given, an error results:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-vyw6nk

Out[3]=3

Many common operations are supported in compiled code:

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-nyeyo3

Out[4]=4

In[5]:=5

✖

https://wolfram.com/xid/0i1l6t7rm-kevm7k

Out[5]=5

In[6]:=6

✖

https://wolfram.com/xid/0i1l6t7rm-3td1u1

Out[6]=6

In[7]:=7

✖

https://wolfram.com/xid/0i1l6t7rm-7ahy10

Out[7]=7

Information can extract the type of the CompiledCodeFunction:

In[8]:=8

✖

https://wolfram.com/xid/0i1l6t7rm-1gxwf0

Out[8]=8

Several functions can be compiled with FunctionCompile:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-xps8uh

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-6shpp7

Out[2]=2

It can be useful to use an association to hold the functions:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-siwiy

Out[3]=3

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-gvuufv

Out[4]=4

Auxiliary definitions can be given with FunctionDeclaration:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-g03

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-iqgrsb

Out[2]=2

New types can be added with TypeDeclaration:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-b6mfdn

Compile a function that instantiates a product type and then extracts a field:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-8f4kzn

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-2zmsdp

Out[3]=3

FunctionCompile will create a function from the name of a declaration in the compiler environment:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-rkk9ze

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-krmevz

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-87gbvi

Out[3]=3

If FunctionCompile is unable to compile something, it issues a message that typically contains a button to show the source of the error:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-egst63

Out[1]=1

Clicking the source button typically opens a user interface that can help to locate the error:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-3owia0

Scope (12)Survey of the scope of standard use cases

A wide range of native types are supported:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-culzes

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-n2xybm

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-ny83c7

Out[3]=3

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-g18hht

Out[4]=4

In[5]:=5

✖

https://wolfram.com/xid/0i1l6t7rm-kpewx1

Out[5]=5

Compound types are also supported:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-kxar7k

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-bj3avc

Out[2]=2

Function types are also supported:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-re18oz

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-x3lxve

Passing in the function and integer arguments carries out the required computation:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-2bgit8

Out[3]=3

The Wolfram Engine can be called using KernelFunction. This defines a function in the Wolfram Engine:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-nobfu5

Use KernelFunction to call the user-defined function from compiled code:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-ovnc84

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-0cmlw4

Out[3]=3

Functions can be passed around as data:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-c19cmx

The first argument selects which nested function is used:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-equn9e

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-76u9z1

Out[3]=3

Nested functions can refer to variables in an outer scope:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-u7j8dd

Out[1]=1

Nested functions that refer to variables in an outer scope can be used as function arguments:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-583ekq

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-eqwam2

Out[2]=2

Print can be used to see the inside of a computation:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-3t26w2

Out[1]=1

A CompiledCodeFunction can be passed as arguments to other CompiledCodeFunction expressions.

Define a function:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-1hyxhc

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-skt5rb

Out[2]=2

This function takes a function as an argument:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-ytlffm

Out[3]=3

This passes the first function as an argument to the second:

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-f6h27j

Out[4]=4

Work with functions that use := to set up DownValues for their declarations:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-5w8nnd

The FunctionDeclaration gives the function a name and a type and states that the implementation comes from the DownValues:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-38oyl1

Now a function that uses this declaration is compiled:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-7ugg89

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-1wzmrs

Out[4]=4

A CompiledCodeFunction contains low-level code to allow serialization and deserialization on a machine of the same architecture:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-3okfpf

Out[1]=1

Compilation results can be saved using Once:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-y1cejk

Out[1]=1

This can be advantageous if the compilation is not very quick:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-oihv98

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-gypkjw

Out[3]=3

Options (6)Common values & functionality for each option

CompilerEnvironment (1)

Create a compiler environment and add a function definition:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-frh

Use a compiler environment in a compilation:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-x1j2b1

Out[3]=3

In[4]:=4

✖

https://wolfram.com/xid/0i1l6t7rm-kmtem

Out[4]=4

CompilerRuntimeErrorAction (1)

The behavior of errors when executing low-level code is governed by the CompilerRuntimeErrorAction:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-1x62pk

Out[1]=1

When there is an error, the function is rerun in the evaluator:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-tlqpj

Out[2]=2

If the function contains compiler-specific code, it is not rerun in the evaluator:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-ldi21z

Out[4]=4

A setting of "Evaluate" always reruns in the evaluator:

In[5]:=5

✖

https://wolfram.com/xid/0i1l6t7rm-6pl3qo

Out[6]=6

A setting of None never reruns in the evaluator:

In[7]:=7

✖

https://wolfram.com/xid/0i1l6t7rm-0z566q

Out[8]=8

A function can be given to obtain custom behavior:

In[9]:=9

✖

https://wolfram.com/xid/0i1l6t7rm-8ea4dq

Out[10]=10

ProgressReporting (1)

Progress during a compilation is reported:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-6cy6wj

✖

https://wolfram.com/xid/0i1l6t7rm-b570dn

This can be suppressed by setting the option ProgressReporting to False.

The default value of ProgressReporting is Automatic, which means that the global setting $ProgressReporting is used. If this is set to False, then no progress reporting takes place.

TargetSystem (2)

Create a compiled code function that can run on machine architectures additional to the current one:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-vy17xx

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-y7iv7f

Out[2]=2

Create a compiled code function that can run on all possible machine architecture platforms:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-wn0fe

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-bzbsjb

Out[2]=2

The compiled code function can be moved to machines with these $SystemID settings and it will be ready to run without having to recompile the original code.

Note that CreateCompilerEnvironment can be used to generate multiple target systems, and this can decrease the time to carry out cross-compilation.

UseEmbeddedLibrary (1)

Create a CompiledCodeFunction that embeds a shared library for the current platform:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-w2cczx

Out[1]=1

The code function now includes an embedded library:

In[2]:=2

✖

https://wolfram.com/xid/0i1l6t7rm-u2jpjj

Out[2]=2

The library will be used when the code function is loaded from a file. This makes loading faster:

In[3]:=3

✖

https://wolfram.com/xid/0i1l6t7rm-4mm7to

Out[4]=4

The restored code function works as expected:

In[5]:=5

✖

https://wolfram.com/xid/0i1l6t7rm-uvkfas

Out[5]=5

Properties & Relations (1)Properties of the function, and connections to other functions

TypeOf is a quick way to check if something may compile, because it just determines the type of its argument:

In[1]:=1

✖

https://wolfram.com/xid/0i1l6t7rm-kegnam

Out[1]=1

Possible Issues (4)Common pitfalls and unexpected behavior

Errors (3)

If an error takes place while computing a function with the low-level code, the computation is run in the Wolfram Engine if it avoids compiler-specific code:

In[1]:=1