sicmutils.expression.compile — sicmutils 0.22.0

This namespace contains tools for compiling functions implemented with the numeric operations defined in sicmutils.generic down to fast, native functions.

compile-fn clj/s

(compile-fn f)

(compile-fn f n)

Memoized version of compile-fn*. See that function's docs for more detail.

NOTE: that this function makes use of a global compilation cache, keyed by the vector [f n *mode*]. See compile-fn* to avoid the cache.

compile-fn* clj/s

(compile-fn* f)

(compile-fn* f n)

Returns a compiled, simplified version of f, given a function f of arity n (ie, able to accept n symbolic arguments).

n defaults to ([[f/arity]] f).

The returned, compiled function expects n Double (or js/Number) arguments. The function body is simplified and all common subexpressions identified during compilation are extracted and computed only once.

NOTE: this function uses no cache. To take advantage of the global compilation cache, see compile-fn.

compile-state-fn clj/s

(compile-state-fn f params initial-state)

(compile-state-fn f params initial-state opts)

Version of compile-state-fn* memoized on the f parameter only. See that function's docs for more detail.

NOTE that this function makes use of a global compilation cache, keyed by the value of f. Passing in the same f twice, even with different arguments for param and initial-state and different compilation modes, will return the cached value. See compile-state-fn* to avoid the cache.

compile-state-fn* clj/s

(compile-state-fn* f params initial-state)

(compile-state-fn* f
                   params
                   initial-state
                   {:keys [generic-params? gensym-fn mode]
                    :or {generic-params? true gensym-fn gensym}
                    :as opts})

Returns a compiled, simplified function with signature (f state params), given:

• a state function that can accept a symbolic arguments

• params; really any sequence of count equal to the number of arguments taken by f. The values are ignored.

• initial-state: Some structure of the same shape as the argument expected by the fn returned by the state function f. Only the shape matters; the values are ignored.

• an optional argument opts. Options accepted are:

  • :flatten?: if true (default), the returned function will have signature (f <flattened-state> [params]). If false, the first arg of the returned function will be expected to have the same shape as initial-state

  • :generic-params?: if true (default), the returned function will take a second argument for the parameters of the state derivative and keep params generic. If false, the returned function will take a single state argument, and the supplied params will be hardcoded.

  • :mode: Explicitly set the compilation mode to one of the values in valid-modes. Explicit alternative to dynamically binding [[mode]].

The returned, compiled function expects all Double (or js/Number) for all state primitives. The function body is simplified and all common subexpressions identified during compilation are extracted and computed only once.

NOTE this function uses no cache. To take advantage of the global compilation cache, see compile-state-fn.

compiler-mode clj/s

(compiler-mode)

Validates and returns the dynamically bound compilation [[mode]]. Throws on an invalid setting.

cse-form clj/s

(cse-form expr)

(cse-form expr opts)

Given a symbolic expression expr, returns a new expression potentially wrapped in a let binding with one binding per extracted common subexpression.

Optional Arguments

:symbol-generator: side-effecting function that returns a new, unique symbol on each invocation. These generated symbols are used to create unique binding names for extracted subexpressions. sortable-gensym by default.

NOTE that the symbols should appear in sorted order! Otherwise we can't guarantee that the binding sequence won't contain entries that reference previous entries, resulting in "Unable to resolve symbol" errors.

:deterministic?: if true, the function will order the let-binding contents by sorting the string representations of each term before assignment. If false the function won't guarantee a consistent variable naming convention in the returned function. For tests, we recommend :deterministic? true.

extract-common-subexpressions clj/s

(extract-common-subexpressions expr continue)

(extract-common-subexpressions expr
                               continue
                               {:keys [symbol-generator deterministic?]
                                :or {symbol-generator sortable-gensym}})

Considers an S-expression from the point of view of optimizing its evaluation by isolating common subexpressions into auxiliary variables.

Accepts:

• A symbolic expression expr
• a continuation fn continue of two arguments:
  • a new equivalent expression with possibly some subexpressions replaced by new variables (delivered by the supplied generator, see below)
  • a seq of pairs of [aux variable, subexpression] used to reconstitute the value.

Calls the continuation at completion and returns the continuation's value.

Optional Arguments

:symbol-generator: side-effecting function that returns a new, unique variable name on each invocation. sortable-gensym by default.

NOTE that the symbols should appear in sorted order! Otherwise we can't guarantee that the binding sequence passed to continue won't contain entries that reference previous entries.

:deterministic?: if true, the function will assign aux variables by sorting the string representations of each term before assignment. Otherwise, the nondeterministic order of hash maps inside this function won't guarantee a consistent variable naming convention in the returned function. For tests, set :deterministic? true.

sci-eval clj/s

(sci-eval f-form)

Given an unevaluated source code form f-form representing a function, evaluates f-form using the bindings in [[sci-context]].

Generate these forms by setting *mode* to :source.

set-compiler-mode! clj/s

(set-compiler-mode! mode)

Set the default compilation mode by supplying an entry from valid-modes.

sortable-gensym clj/s

valid-modes clj/s

Set of all supported compilation modes.

validate-mode! clj/s

(validate-mode! mode)

Given a keyword mode specifying a compilation mode, returns mode if valid, and throws otherwise.