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
    CompilerRuntimeErrorAction Automaticthe behavior when there is an unrecoverable error while executing low-level code
    ProgressReporting Automatichow to report progress during the compilation
    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,…}
  • Possible values for CompilerRuntimeErrorAction are:
  • Automaticrerun the computation in the Wolfram Engine if it avoids compiler-specific code
    "Evaluate"always rerun the computation in the Wolfram Engine
    Nonereturn a failure object that represents the error
    funapply fun to the failure object and return the result

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 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  (6)

CompilerEnvironment  (1)

Create a compiler environment and add a function definition:

Use a compiler environment in a compilation:

CompilerRuntimeErrorAction  (1)

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

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

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

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

A setting of None never reruns in the evaluator:

A function can be given to obtain custom behavior:

ProgressReporting  (1)

Progress during a compilation is reported:

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:

Create a compiled code function that can run on all possible machine architecture 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.

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:

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 if it avoids compiler-specific code:

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_2024_functioncompile, author="Wolfram Research", title="{FunctionCompile}", year="2021", howpublished="\url{https://reference.wolfram.com/language/ref/FunctionCompile.html}", note=[Accessed: 22-December-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_functioncompile, organization={Wolfram Research}, title={FunctionCompile}, year={2021}, url={https://reference.wolfram.com/language/ref/FunctionCompile.html}, note=[Accessed: 22-December-2024 ]}