FunctionCompile

FunctionCompile[f]

generates a compiled code function from a pure function.

FunctionCompile[{f1,f2,…}]

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

FunctionCompile[k1f1,k2f2,…]

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 Automatican environment of definitions for compilation
    CompilerOptionsAutomaticdetailed options for the compilation pipeline
    TargetSystem Inheritedmachine architectures for code generation
    UseEmbeddedLibrary Falsecreate and embed a shared library for this architecture
  • Possible settings for TargetSystem are:
  • Automaticgenerate additional code for key machine architectures
    Allgenerate additional code for all machine architectures
    trggenerate additional code for machine architecture trg
    {trg1,trg2,…}generate additional code for machine architectures {trg1,trg2,…}

Examples

open allclose all

Basic Examples  (5)

Compile a Function into a compiled code function:

The CompiledCodeFunction evaluates with an argument of the correct type:

If unexpected arguments are given, an error results:

Many common operations are supported in compiled code:

Information can extract the signature of the CompiledCodeFunction:

Several functions can be compiled with FunctionCompile:

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

Auxiliary definitions can be given with FunctionDeclaration:

New types can be added with TypeDeclaration:

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

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

Scope  (11)

A wide range of native types are supported:

Compound types are also supported:

Function types are also supported:

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

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

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

Functions can be nested inside functions:

Functions can be passed around as data:

The first argument selects which nested function is used:

Nested functions can refer to variables in an outer scope:

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

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

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

Define a function:

This function takes a function as an argument:

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

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

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

Now a function that uses this declaration is compiled:

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

Options  (4)

CompilerEnvironment  (1)

Create a compiler environment and add a function definition:

Use a compiler environment in a compilation:

TargetSystem  (2)

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

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

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.

UseEmbeddedLibrary  (1)

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

The code function now includes an embedded library:

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

The restored code function works as expected:

Possible Issues  (4)

Errors  (3)

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

There is no error here:

Here is an error while running the function. The computation is terminated, a message is issued and the Wolfram Engine is used to compute the result:

Integer constants are typed as the native machine integer:

Use Typed to specify a particular type:

Returning a function from CompiledCodeFunction is not supported:

Functions nested inside a CompiledCodeFunction can return functions:

Creating Functions  (1)

FunctionCompile cannot create a function if there is more than one declaration:

If Typed is used the compilation can work:

FunctionCompile cannot create a function if there is a polymorphic declaration:

If Typed is used the compilation can work:

Neat Examples  (2)

Nested functions can be used to implement recursive definitions:

Declarations that use a symbol declaration are useful if the declaration is used more than once:

A FunctionDeclaration that refers to the symbol:

A function that uses the symbol:

Compiled code for the function:

A vector plot based on the data that was created:

The compiled version is much faster:

An animation of the output:

Wolfram Research (2019), FunctionCompile, Wolfram Language function, https://reference.wolfram.com/language/ref/FunctionCompile.html (updated 2021).

Text

Wolfram Research (2019), FunctionCompile, Wolfram Language function, https://reference.wolfram.com/language/ref/FunctionCompile.html (updated 2021).

CMS

Wolfram Language. 2019. "FunctionCompile." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2021. https://reference.wolfram.com/language/ref/FunctionCompile.html.

APA

Wolfram Language. (2019). FunctionCompile. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/FunctionCompile.html

BibTeX

@misc{reference.wolfram_2023_functioncompile, author="Wolfram Research", title="{FunctionCompile}", year="2021", howpublished="\url{https://reference.wolfram.com/language/ref/FunctionCompile.html}", note=[Accessed: 04-October-2023 ]}

BibLaTeX

@online{reference.wolfram_2023_functioncompile, organization={Wolfram Research}, title={FunctionCompile}, year={2021}, url={https://reference.wolfram.com/language/ref/FunctionCompile.html}, note=[Accessed: 04-October-2023 ]}