FunctionCompile
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 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 {trg1,trg2,…} generate additional code for machine architectures {trg1,trg2,…} - 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 all close allBasic Examples (6)
Compile a Function into a compiled code function:
cf = FunctionCompile[Function[Typed[arg, "MachineInteger"], arg + 1]]The CompiledCodeFunction evaluates with an argument of the correct type:
cf[20]If unexpected arguments are given, an error results:
cf[True, 1.5]
Many common operations are supported in compiled code:
cf = FunctionCompile[Function[Typed[len, "MachineInteger"], Table[i, {i, len}]]]cf[20]cf = FunctionCompile[Function[Typed[n, "MachineInteger"], Nest[Sin, 10.1, n]]]cf[ 200]Information can extract the type of the CompiledCodeFunction:
cf = FunctionCompile[Function[Typed[arg, "MachineInteger"], arg + 1]];
Information[cf, "Type"]Several functions can be compiled with FunctionCompile:
cfs = FunctionCompile[{Function[Typed[arg, "Integer64"], arg + 1], Function[Typed[arg, "Integer64"], arg - 1]}]cfs[[1]][10]It can be useful to use an association to hold the functions:
cfs = FunctionCompile[<|"f1" -> Function[Typed[arg, "Integer64"], arg + 1], "f2" -> Function[Typed[arg, "Integer64"], arg - 1]|>]cfs[[1]][10]Auxiliary definitions can be given with FunctionDeclaration:
dec = FunctionDeclaration[AddTwo, Typed[{"Integer64"} -> "Integer64"]@Function[arg, 2 + arg]];
cf = FunctionCompile[dec, Function[Typed[arg, "Integer64"], AddTwo[AddTwo[arg]]]]cf[ 200]New types can be added with TypeDeclaration:
dec = TypeDeclaration["Product", "simpleProd", <|"field1" -> "MachineInteger", "field2" -> "Boolean"|>];Compile a function that instantiates a product type and then extracts a field:
cf = FunctionCompile[dec, Function[{},
With[{prod = CreateTypeInstance["simpleProd", <|"field1" -> 12, "field2" -> True|>]},
prod["field1"]]
]]cf[ ]FunctionCompile will create a function from the name of a declaration in the compiler environment:
dec = FunctionDeclaration[squareFun, Typed[{"Real64"} -> "Real64"]@Function[{arg}, arg ^ 2]];cf = FunctionCompile[dec, squareFun]cf[1.5]If FunctionCompile is unable to compile something, it issues a message that typically contains a button to show the source of the error:
cf = FunctionCompile[Function[Typed[arg, "Real64"], Module[{size = arg < 10}, Sin[size]]]]
Clicking the source button typically opens a user interface that can help to locate the error:
[image]Scope (12)
A wide range of native types are supported:
cf = FunctionCompile[Function[Typed[arg, "Boolean"], If[arg, 1, 2]]];
cf[False]cf = FunctionCompile[Function[Typed[arg, "UnsignedInteger8"], N[arg]]];
cf[20]cf = FunctionCompile[Function[Typed[arg, "Integer16"], 10 + arg]];
cf[20]cf = FunctionCompile[Function[Typed[arg, "Real64"], arg + 2]];
cf[20.2]cf = FunctionCompile[Function[Typed[arg, "Complex128"], arg + 2]];
cf[20.2 + 3.4I]Compound types are also supported:
cf = FunctionCompile[Function[Typed[arg, "PackedArray"::["MachineInteger", 1]],
Fold[Plus, arg]]];
cf[{4, 5, 6, 1, 2, 6, 3}]cf = FunctionCompile[Function[Typed[arg, "NumericArray"::["Integer16", 2]],
Max[arg]]];
cf[NumericArray[{{4, 5, 6}, {1, 2, 3}}, "Integer16"]]Function types are also supported:
cf1 = FunctionCompile[Function[Typed[arg, "MachineInteger"], arg + 1]];cf2 = FunctionCompile[Function[{Typed[fun, {"MachineInteger"} -> "MachineInteger"], Typed[arg, "MachineInteger"]}, fun[arg]]];Passing in the function and integer arguments carries out the required computation:
cf2[cf1, 20]The Wolfram Engine can be called using KernelFunction. This defines a function in the Wolfram Engine:
f[x_] := x ^ 2Use KernelFunction to call the user-defined function from compiled code:
cf = FunctionCompile[Function[Typed[arg, "MachineInteger"], Typed[KernelFunction[f], {"MachineInteger"} -> "MachineInteger"][arg]]]cf[10]Functions can be passed around as data:
cf = FunctionCompile[Function[{Typed[cond, "Boolean"], Typed[arg, "MachineInteger"]},
Module[{f, g},
f = If[cond, # + 1&, # - 1&];
g = #1[#2]&;
g[f, arg]]]];The first argument selects which nested function is used:
cf[True, 20]cf[False, 20]Nested functions can refer to variables in an outer scope:
cf = FunctionCompile[Function[{Typed[arg1, "MachineInteger"]},
Module[{f = Function[{}, arg1]},
f[]]]];
cf[10]Nested functions that refer to variables in an outer scope can be used as function arguments:
cf = FunctionCompile[Function[{Typed[arg1, "MachineInteger"]},
Module[{f1 = Function[{}, arg1], f2 = Function[f, f[]]},
f2[f1]]]]cf[ 10]Print can be used to see the inside of a computation:
cf = FunctionCompile[Function[{Typed[arg1, TypeSpecifier["PackedArray"]["MachineInteger", 1]]},
Map[(Print[#];# ^ 2)&, arg1]]];
cf[{5, 6, 2, 1, 6, 7}]
A CompiledCodeFunction can be passed as arguments to other CompiledCodeFunction expressions.
cf1 = FunctionCompile[Function[{Typed[arg, "MachineInteger"]}, If[EvenQ[arg], arg + 1, arg - 1]]]cf1[10]This function takes a function as an argument:
cf2 = FunctionCompile[Function[{Typed[fun, { "MachineInteger"} -> "MachineInteger"], Typed[lim, "MachineInteger"]}, Table[fun[i], {i, lim}]]]This passes the first function as an argument to the second:
cf2[cf1, 100]Work with functions that use := to set up DownValues for their declarations:
fun1[x_] :=
Echo[x ^ 2]The FunctionDeclaration gives the function a name and a type and states that the implementation comes from the DownValues:
decl = FunctionDeclaration[fun1, Typed[ {"MachineInteger"} -> "MachineInteger"]@DownValuesFunction[fun1]];Now a function that uses this declaration is compiled:
func = Function[{Typed[len, "Integer64"]}, Table[ fun1[i], {i, len}]];
cf = FunctionCompile[ decl, func];cf[5]A CompiledCodeFunction contains low-level code to allow serialization and deserialization on a machine of the same architecture:
cf = FunctionCompile[Function[{Typed[arg, "MachineInteger"]}, arg]];
Information[cf, "LLVMBinary"]Compilation results can be saved using Once:
cf = Once[FunctionCompile[Function[{Typed[arg, "MachineInteger"]}, arg + 2]], "Notebook"];
cf[10]This can be advantageous if the compilation is not very quick:
cf = Once[FunctionCompile[
FunctionDeclaration[flowCompute, Typed[{"Real64", "Real64"} -> "PackedArray"::["Real64", 2]]@Function[{x, y},
Module[{z},
z = 1 - 1 / (x + I y) ^ 2;
{{x, y}, {Re[z], -Im[z]}}
]]]
,
Function[{Typed[x0, "Real64"], Typed[x1, "Real64"], Typed[y0, "Real64"], Typed[y1, "Real64"]}, Table[Flatten[ Table[{flowCompute[x + d / 4, y], flowCompute[x + d / 4, -y]}, {x, x0, x1}, {y, y0, y1}], 2] , {d, 0, 3, 0.3}]]
], "Notebook"];ListVectorPlot[First[cf[-7, 5, 0.5, 3]]]Options (6)
CompilerEnvironment (1)
Create a compiler environment and add a function definition:
env = CreateCompilerEnvironment[];
CompilerEnvironmentAppendTo[env, FunctionDeclaration[addTwo, Typed[{"Integer64"} -> "Integer64"]@Function[arg, 2arg]]];Use a compiler environment in a compilation:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, addTwo[arg]], CompilerEnvironment -> env]cf[10]CompilerRuntimeErrorAction (1)
The behavior of errors when executing low-level code is governed by the CompilerRuntimeErrorAction:
cf = FunctionCompile[Function[{Typed[x, "UnsignedInteger8"], Typed[y, "UnsignedInteger8"]}, x + y], CompilerRuntimeErrorAction -> Automatic]When there is an error, the function is rerun in the evaluator:
cf[250, 250]
If the function contains compiler-specific code, it is not rerun in the evaluator:
cf = FunctionCompile[Function[{Typed[x, "UnsignedInteger8"], Typed[y, "UnsignedInteger8"]}, Module[ {ptr = ToRawPointer[x + y]}, FromRawPointer[ptr]]], CompilerRuntimeErrorAction -> Automatic];
cf[250, 250]
A setting of "Evaluate" always reruns in the evaluator:
cf = FunctionCompile[Function[{Typed[x, "UnsignedInteger8"], Typed[y, "UnsignedInteger8"]}, Module[ {ptr = ToRawPointer[x + y]}, FromRawPointer[ptr]]], CompilerRuntimeErrorAction -> "Evaluate"];
cf[250, 250]
A setting of None never reruns in the evaluator:
cf = FunctionCompile[Function[{Typed[x, "UnsignedInteger8"], Typed[y, "UnsignedInteger8"]}, x + y], CompilerRuntimeErrorAction -> None];
cf[250, 250]
A function can be given to obtain custom behavior:
cf = FunctionCompile[Function[{Typed[x, "UnsignedInteger8"], Typed[y, "UnsignedInteger8"]}, x + y], CompilerRuntimeErrorAction -> Framed];
cf[250, 250]ProgressReporting (1)
Progress during a compilation is reported:
FunctionCompile[ Function[Typed[arg, "PackedArray"::["Real64", 1]], BinCounts[arg, 1.5]]]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:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, arg], TargetSystem -> {"Windows-x86-64"}]Information[cf, "LLVMBinary"]Create a compiled code function that can run on all possible machine architecture platforms:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, arg], TargetSystem -> All]Information[cf, "LLVMBinary"]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:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, arg], UseEmbeddedLibrary -> True]The code function now includes an embedded library:
cf[[1]]["EmbeddedLibraries"]The library will be used when the code function is loaded from a file. This makes loading faster:
cf>>comp.wl;
cf1 = <<comp.wlThe restored code function works as expected:
cf1[10]Properties & Relations (1)
TypeOf is a quick way to check if something may compile, because it just determines the type of its argument:
TypeOf[Function[{Typed[x, "Real64"], Typed[y, "Integer64"]}, x + y]]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:
cf = FunctionCompile[Function[Typed[arg, "Real64"], Sqrt[arg]]]cf[10.5]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:
cf[-10.2]
Integer constants are typed as the native machine integer:
cf = FunctionCompile[Function[{Typed[arg, "Integer8"]}, arg + 10]]Use Typed to specify a particular type:
cf = FunctionCompile[Function[{Typed[arg, "Integer8"]}, arg + Typed[10, "Integer8"]]]Returning a function from CompiledCodeFunction is not supported:
FunctionCompile[Function[{}, Function[Typed[arg, "MachineInteger"], arg + 1]]]
Creating Functions (1)
FunctionCompile cannot create a function if there is more than one declaration:
dec1 = FunctionDeclaration[squareFun, Typed[{"Real64"} -> "Real64"]@Function[{arg}, arg ^ 2]];
dec2 = FunctionDeclaration[squareFun, Typed[{"Integer64"} -> "Integer64"]@Function[{arg}, arg ^ 2]];cf = FunctionCompile[{dec1, dec2}, squareFun]
If Typed is used the compilation can work:
cf = FunctionCompile[{dec1, dec2}, Typed[squareFun, {"Real64"} -> "Real64"]]FunctionCompile cannot create a function if there is a polymorphic declaration:
dec = FunctionDeclaration[squareFun, Typed[ForAllType[a, {a} -> a]]@Function[{arg}, arg ^ 2]];cf = FunctionCompile[dec, squareFun]
If Typed is used the compilation can work:
cf = FunctionCompile[dec, Typed[squareFun, {"Real64"} -> "Real64"]]Neat Examples (2)
Nested functions can be used to implement recursive definitions:
cf = FunctionCompile[Function[{Typed[arg, "MachineInteger"]},
Module[{factFun},
factFun = Function[{arg1},
If[arg1 === 1, 1, arg1 * factFun[arg1 - 1]]];
factFun[arg]]]]cf[10]Declarations that use a symbol declaration are useful if the declaration is used more than once:
restrictFlow[ x_, y_] :=
Module[{z},
z = 1 - 1 / (x + I y) ^ 2;
{{x, y}, {Re[z], -Im[z]}}
]A FunctionDeclaration that refers to the symbol:
decl = FunctionDeclaration[restrictFlow, Typed[{"Real64", "Real64"} -> "PackedArray"::["Real64", 2]]@DownValuesFunction[restrictFlow]];A function that uses the symbol:
func = Function[{Typed[x0, "Real64"], Typed[x1, "Real64"], Typed[y0, "Real64"], Typed[y1, "Real64"]}, Table[Flatten[ Table[{restrictFlow[x + d / 4, y], restrictFlow[x + d / 4, -y]}, {x, x0, x1}, {y, y0, y1}], 2] , {d, 0, 3, 0.3}]];Compiled code for the function:
cf = FunctionCompile[decl, func]data = cf[-7, 5, 0.5, 3];A vector plot based on the data that was created:
ListVectorPlot[First[data]]The compiled version is much faster:
func[-7, 5, 0.5, 3];//RepeatedTimingcf[-7, 5, 0.5, 3];//RepeatedTimingAnimate[ListVectorPlot[ Part[data, i] ], {i, 1, Length[data], 1}, SaveDefinitions -> True, AnimationRunning -> False]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