Wolfram Language & System Documentation Center

DownValuesFunction

represents a function that uses definitions attached to sym when compiling.

Details

DownValuesFunction can be used directly in compiled code.
DownValuesFunction can be used in compiled declarations specified by FunctionDeclaration.
DownValuesFunction specifications typically use Typed to give type annotations.
When DownValuesFunction is compiled, it creates a function from symbol declarations and compiles it.
Declarations that use DownValuesFunction can use polymorphic types.
The following pattern constructs are supported:

	_	match an argument
	x_	match an argument assigning to the name x
	_h	match if the head is h
	x_?test	match if test[x] evaluates to True
	p/;cond	match if cond evaluates to True
	Except[p]	match if p does not match
	p₁\|p₂	match if one of p_i matches
	f[g[p]]	match a compound expression (for inert expressions and packed arrays)
	__,___	match a sequence (for inert expressions)

Examples

open all close all

Basic Examples (2)

Define a squaring function in the Wolfram Engine:

Wolfram Language code: square[x_] := x ^ 2

Use its downvalues to create a compiled function for the integer-typed case:

Wolfram Language code:

funcComp = FunctionCompile[
	Function[Typed[arg, "MachineInteger"], 
	Typed[DownValuesFunction[square], {"MachineInteger"} -> "MachineInteger"][arg]
	]
	]

Apply the compiled function to an integer argument:

Wolfram Language code: funcComp[100]

Define the factorial function using recursive downvalues:

Wolfram Language code:

factorial[0] = factorial[1] = 1;
factorial[n_] := n * factorial[n - 1]

Use FunctionDeclaration to associate the factorial with an integer-type signature and its downvalue implementation:

Wolfram Language code:

factorialC = FunctionCompile[
	FunctionDeclaration[factorial, Typed[{"MachineInteger"} -> "MachineInteger"]@DownValuesFunction[factorial]
	], 
	Function[Typed[arg, "MachineInteger"], factorial[arg]]
	]

Call the compiled function on an integer input:

Wolfram Language code: factorialC[10]

Scope (13)

Multiple Definitions (1)

Several definitions attached to the same symbol can be used:

Wolfram Language code:

f2[x_, y_] /; x > y := y
f2[x_, 2] := x
f2[x_, y_]  := x + y

Compile a function that uses the definitions:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"], Typed[a2, "MachineInteger"]}, Typed[DownValuesFunction[f2], {"MachineInteger", "MachineInteger"} -> "MachineInteger"][a1, a2]]]

This calls the definition that uses a condition:

Wolfram Language code: cf[55, 22]

This calls the definition that uses a literal 2:

Wolfram Language code: cf[1, 2]

This calls the last catchall definition:

Wolfram Language code: cf[55, 200]

Multiple Declarations (1)

Definitions attached to a symbol can be used in more than one declaration with different types:

Wolfram Language code: funA[x_, y_] := x + y

Make two declarations with different types and compile functions that use each:

Wolfram Language code:

decls = {
	FunctionDeclaration[funA, Typed[{"MachineInteger", "MachineInteger"} -> "MachineInteger"]@
	DownValuesFunction[funA]
	], 
	FunctionDeclaration[funA, 
	Typed[{"Real64", "Real64"} -> "Real64"]@
	DownValuesFunction[funA]
	]
	};
cfs = FunctionCompile[decls, <|
	"int" -> Function[{Typed[a1, "MachineInteger"], Typed[a2, "MachineInteger"]}, 
	funA[a1, a2]
	], 
	"real" -> Function[{Typed[a1, "Real64"], Typed[a2, "Real64"]}, funA[a1, a2]
	]
	|>]

Call the integer case:

Wolfram Language code: cfs["int"][2, 3]

Call the real case:

Wolfram Language code: cfs["real"][2.5, 3.25]

Polymorphic Declarations (1)

Definitions attached to a symbol can be declared with a polymorphic type:

Wolfram Language code: funB[x_, y_] := x + y

Make a polymorphic declaration and compile functions that use it for different types:

Wolfram Language code:

decl = FunctionDeclaration[ funB, Typed[ForAllType[t, {t, t} -> t]]@DownValuesFunction[funB]];
cfs = FunctionCompile[ {decl}, <|"int" -> Function[{Typed[a1, "MachineInteger"], Typed[a2, "MachineInteger"]}, funB[a1, a2]], "real" -> Function[{Typed[a1, "Real64"], Typed[a2, "Real64"]}, funB[a1, a2]]|>]

Call the integer case:

Wolfram Language code: cfs["int"][2, 3]

Call the real case:

Wolfram Language code: cfs["real"][2.5, 3.25]

Recursive Calls (1)

Function declarations that use a symbol definition can call themselves:

Wolfram Language code:

fact[0] := 1
fact[n_] := n * fact[n - 1]

Make a declaration and compile a function that uses it:

Wolfram Language code:

decl = FunctionDeclaration[fact, Typed[{"MachineInteger"} -> "MachineInteger"]@DownValuesFunction[fact]];
cf = FunctionCompile[{decl}, Function[{Typed[a1, "MachineInteger"]}, fact[a1]]]

Call the function:

Wolfram Language code: cf[10]

Unnamed Patterns (1)

A pattern argument does not need a name:

Wolfram Language code: unnamedPattern[_] := "noName"

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"]}, Typed[ DownValuesFunction[unnamedPattern], {"MachineInteger"} -> "String"][a1]]]

Call the function with different values:

Wolfram Language code: cf[1]

Repeated Patterns (1)

If the same name appears more than once in a definition, when called, the value must be the same:

Wolfram Language code:

repeatedPattern[x_, x_] := {x}
repeatedPattern[x_, y_] := {x, y}

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"], Typed[a2, "MachineInteger"]}, Typed[DownValuesFunction[repeatedPattern], {"MachineInteger", "MachineInteger"} -> "PackedArray"::["MachineInteger", 1]][a1, a2]]]

Call the function with different values:

Wolfram Language code: cf[1, 2]

Call the function with the same value and it uses the definition for the same value:

Wolfram Language code: cf[3, 3]

Matching the Head (1)

A pattern can be written to match the head:

Wolfram Language code:

headMatch[x_Real] := "Real"
headMatch[x_] := "NotReal"

Make a polymorphic declaration that uses the definition:

Wolfram Language code: decl = FunctionDeclaration[headMatch, Typed[ForAllType["e", {"e"} -> "String"]]@DownValuesFunction[headMatch]];

Compile a function that uses the declaration with an argument that does not match the head:

Wolfram Language code: cf = FunctionCompile[{decl}, Function[{Typed[a1, "MachineInteger"]}, headMatch[a1]]];

Call the function with an integer and that uses the definition that does not match the head:

Wolfram Language code: cf[1]

Compile a function that uses the declaration with an argument that does match the head:

Wolfram Language code: cf = FunctionCompile[{decl}, Function[{Typed[a1, "Real64"]}, headMatch[a1]]];

Call the function with a real and that uses the definition that matches the head:

Wolfram Language code: cf[1.5]

Pattern Test (1)

Compiled patterns can use PatternTest:

Wolfram Language code:

patternTest[x_ ? EvenQ] := {0, x}
patternTest[x_] := {1, x}

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"]}, Typed[DownValuesFunction[patternTest], {"MachineInteger"} -> "PackedArray"::["MachineInteger", 1]][a1]]];

The input is even:

Wolfram Language code: cf[2]

The input is odd:

Wolfram Language code: cf[21]

Condition (1)

Compiled patterns can use Condition:

Wolfram Language code:

conditionPattern[x_, y_] /; x > y := {y, x}
conditionPattern[x_, y_] := {x, y}

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"], Typed[a2, "MachineInteger"]}, Typed[DownValuesFunction[conditionPattern], {"MachineInteger", "MachineInteger"} -> "PackedArray"::["MachineInteger", 1]][a1, a2]]];

The input has arguments in order:

Wolfram Language code: cf[1, 2]

The input has arguments not in order, so in the output, they are reversed:

Wolfram Language code: cf[7, 3]

Except (1)

Compiled patterns can use Except:

Wolfram Language code:

exceptPattern[Except[y_ ? EvenQ]] := {y, 0}
exceptPattern[y_] := {y}

Make a declaration and compile a function that uses it:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"]}, Typed[DownValuesFunction[exceptPattern], {"MachineInteger"} -> "PackedArray"::["MachineInteger", 1]][a1]]];

The argument is even, so the first definition is not used:

Wolfram Language code: cf[20]

The argument is odd, so the first definition is used:

Wolfram Language code: cf[3]

Wolfram Language code:

exceptPattern2[y : Except[_ ? EvenQ, y_ /; y > 20]] := {y, 0}
exceptPattern2[y_] := {y}

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "MachineInteger"]}, Typed[DownValuesFunction[exceptPattern2], {"MachineInteger"} -> "PackedArray"::["MachineInteger", 1]][a1]]];

The argument is even and greater than 20, so the first definition is not used:

Wolfram Language code: cf[24]

The argument is odd and greater than 20, so the first definition is used:

Wolfram Language code: cf[25]

The argument is odd but less than 20, so the first definition is not used:

Wolfram Language code: cf[3]

Alternatives (1)

Compiled patterns can use Alternatives:

Wolfram Language code: alternativesPattern[x : (_Integer | _Real)] := x

Make a declaration:

Wolfram Language code:

decl = FunctionDeclaration[alternativesPattern, Typed[ForAllType["e", {"e"} -> "e"]]@DownValuesFunction[alternativesPattern]];

Compile a function to use the declaration:

Wolfram Language code: cf = FunctionCompile[{decl}, Function[{Typed[a1, "MachineInteger"]}, alternativesPattern[a1]]];

This function matches the input, so a result is generated:

Wolfram Language code: cf[1]

Compile a function with a different type to use the declaration:

Wolfram Language code: cf = FunctionCompile[{decl}, Function[{Typed[a1, "Real64"]}, alternativesPattern[a1]]];

This function also matches the input, so a result is generated:

Wolfram Language code: cf[1.5]

Compound Patterns (1)

Compilation supports compounds patterns for certain types such as "InertExpression" and "PackedArray":

Wolfram Language code:

compoundPattern[{x_, y_}] := x[y]
compoundPattern[x_] := x

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "InertExpression"]}, Typed[DownValuesFunction[compoundPattern], {"InertExpression"} -> "InertExpression"][a1]]];

This function matches the input so a result is generated:

Wolfram Language code: cf[{f, x}]

Compile a function with a different type to use the declaration:

Wolfram Language code: cf[{a, b, c}]

Sequences (1)

Compilation supports certain sequence patterns for "InertExpression":

Wolfram Language code:

sequencePattern[{x_, y__}] := x[y]
sequencePattern[_] := InertExpression[$Failed]

Compile a function that uses the definition:

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "InertExpression"]}, Typed[DownValuesFunction[sequencePattern], {"InertExpression"} -> "InertExpression"][a1]]];

This sequence gets flattened:

Wolfram Language code: cf[{f, x, y, z}]

The pattern with a sequence does not match, so this returns a failure:

Wolfram Language code: cf[{f}]

The pattern can have a compound head of any expression type:

Wolfram Language code:

sequencePattern2[f[x_, {__, x_}]] := x
sequencePattern2[_] := InertExpression[$Failed]

Wolfram Language code:

cf = FunctionCompile[Function[{Typed[a1, "InertExpression"]}, Typed[DownValuesFunction[sequencePattern2], {"InertExpression"} -> "InertExpression"][a1]]];

This matches:

Wolfram Language code: cf[f[g, {1, 2, 3, 4, g}]]

This does not match:

Wolfram Language code: cf[f[g, {1, 2, 3, 4, h}]]

Applications (1)

Symbol Definitions (1)

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

Wolfram Language code:

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:

Wolfram Language code:

decl = FunctionDeclaration[restrictFlow, Typed[{"Real64", "Real64"} -> "PackedArray"::["Real64", 2]]@DownValuesFunction[restrictFlow]];

A function that uses the symbol:

Wolfram Language code:

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:

Wolfram Language code: cf = FunctionCompile[decl, func]

Wolfram Language code: data = cf[-7, 5, 0.5, 3];

A vector plot based on the data that was created:

Wolfram Language code: ListVectorPlot[First[data]]

The compiled version is much faster:

Wolfram Language code: func[-7, 5, 0.5, 3];//RepeatedTiming

Wolfram Language code: cf[-7, 5, 0.5, 3];//RepeatedTiming

An animation of the output:

Wolfram Language code: Animate[ListVectorPlot[Part[data, i]], {i, 1, Length[data], 1}, SaveDefinitions -> True, AnimationRunning -> False]

Possible Issues (5)

Updating (1)

DownValuesFunction uses the definitions used when the compilation is carried out:

Wolfram Language code: testFun[x_] := x ^ 2

Wolfram Language code:

func = Function[Typed[arg, "MachineInteger"], Typed[DownValuesFunction[testFun], {"MachineInteger"} -> "MachineInteger"][arg]];
funcComp = FunctionCompile[func];

Wolfram Language code: funcComp[10]

Wolfram Language code: testFun[x_] := x ^ 3

The result uses the definitions in place when the compilation is done:

Wolfram Language code: funcComp[10]

Definition Restrictions (1)

If there is no definition that applies to particular arguments, a runtime error case will be added:

Wolfram Language code:

fun1[x_ ? Positive]  := 
    x

Wolfram Language code:

decl = FunctionDeclaration[fun1, Typed[{"Integer64"} -> "Integer64"]@DownValuesFunction[fun1]];
funcComp = FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun1[arg]]]

This returns a result:

Wolfram Language code: funcComp[10]

There is no definition that works for this input and hence a runtime error results:

Wolfram Language code: funcComp[-10]

Type Consistency (1)

All the branches of pattern definitions must return the same type:

Wolfram Language code:

fun10[x_ /; x > 10]  := 
    True
fun10[x_]  := 
    10

Wolfram Language code:

decl = FunctionDeclaration[fun10, Typed[{"Integer64"} -> "Integer64"]@DownValuesFunction[fun10]];
FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun10[arg]]]

All the branches of pattern definitions must compile for the arguments:

Wolfram Language code:

fun11[x_ /; x > 1]  := 
    Sin[x]
	
fun11[x_]  := 
    x

This compiles:

Wolfram Language code:

decl = FunctionDeclaration[fun11, Typed[{"Real64"} -> "Real64"]@DownValuesFunction[fun11]];
FunctionCompile[decl, Function[Typed[arg, "Real64"], fun11[arg]]]

This does not compile:

Wolfram Language code:

decl = FunctionDeclaration[fun11, Typed[{"Integer64"} -> "Integer64"]@DownValuesFunction[fun11]];
FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun11[arg]]]

Unsupported Patterns (1)

Optional patterns are not supported:

Wolfram Language code:

fun5[x_, y_ : 10]  := 
    x

Wolfram Language code:

decl = FunctionDeclaration[fun5, Typed[{"Integer64"} -> "Integer64"]@DownValueFunction[fun5]];
FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun5[arg]]]

Held patterns are not supported:

Wolfram Language code:

fun8[HoldPattern[y_]]  := 
    x

Wolfram Language code:

decl = FunctionDeclaration[fun8, Typed[{"Integer64"} -> "Integer64"]@DownValuesFunction[fun8]];
FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun8[arg]]]

Verbatim patterns are not supported:

Wolfram Language code:

fun9[Verbatim[y_]]  := 
    x

Wolfram Language code:

decl = FunctionDeclaration[fun9, Typed[{"Integer64"} -> "Integer64"]@DownValuesFunction[fun9]];
FunctionCompile[decl, Function[Typed[arg, "Integer64"], fun9[arg]]]

Sequence Patterns (1)

Sequence patterns do not support polymorphic declarations:

Wolfram Language code: fun10[{x_, y__}] := x[y]

Make a polymorphic declaration, but the compilation cannot use it:

Wolfram Language code:

decl = FunctionDeclaration[fun10, Typed[ ForAllType["e", {"e"} -> "e"]]@DownValuesFunction[fun10]];
FunctionCompile[{decl}, Function[{Typed[a1, "InertExpression"]}, fun10[a1]]];

Top

DownValuesFunction

Details

Examples

Basic Examples (2)

Scope (13)

Multiple Definitions (1)

Multiple Declarations (1)

Polymorphic Declarations (1)

Recursive Calls (1)

Unnamed Patterns (1)

Repeated Patterns (1)

Matching the Head (1)

Pattern Test (1)

Condition (1)

Except (1)

Alternatives (1)

Compound Patterns (1)

Sequences (1)

Applications (1)

Symbol Definitions (1)

Possible Issues (5)

Updating (1)

Definition Restrictions (1)

Type Consistency (1)

Unsupported Patterns (1)

Sequence Patterns (1)

See Also

Tech Notes

Related Guides

History

Text

CMS

APA

BibTeX

BibLaTeX