emmy.expression.compile — org.mentat/emmy 0.31.0

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

compile-fn clj/s

(compile-fn f)

(compile-fn f n)

(compile-fn f n opts)

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

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

You may also specify options in the third argument. See compile-state-fn for information on the options supported.

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.

compile-state-fn clj/s

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

(compile-state-fn f
                  params
                  initial-state
                  {:keys [mode calling-convention arity generic-params?
                          gensym-fn deterministic? cache? simplify?]
                   :or {mode *mode*
                        calling-convention :structure
                        generic-params? (boolean params)
                        gensym-fn (a/monotonic-symbol-generator 4)
                        deterministic? false
                        cache? true
                        simplify? true}})

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. If the specific value false is provided, then f is considered to be the function to compile itself, and not the producer of such a function via application of parameters.

• 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:

  • :calling-convention: May have one of the following values. (In each of these examples, assume that the initial state `(up 1 (up 2 3) (up 3 4)) has been provided.)

    • :structure: The arguments to the compiled function will have the same shape as the initial-state, and elements of that state will be made available to the function via argument destructuring in function signature, e.g.:

      (fn [[y1 [y2 y3] [y4 y5]]] [p1 ...] ...)
      

    • :primitive: The compiled function will expect a primitive array containing the state in flat form to be passed as the first argument, and will return its value by mutating its second argument, which will also be a primitive array of the same size. The parameters will be provided via a third primitive array:

      (fn [ys yps ps] ...)
      

      This is the fastest form, as no allocations are needed to destructure arguments list or to construct the return value, but requires the use of primitive arrays (not general Clojure sequences, even if mutable) by the caller. The generated code will use aget and aset on the arrays.

  • :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; moreover, the resulting compiled function will not be cached.

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

  • :cache: If falsy, the compilation cache is avoided (it will neither be consulted nor updated).

  • :deterministic? requests that the compiler expend some effort to get reproducible results down to the symbol name level for tests. It has no observable effect on the compiled function's behavior.

  • :gensym-fn allows injection of a symbol generator for unit test purposes

  • :arity records the arity selected for a compiled non-state function and is ordinarily provided automatically by compile-fn.

  • :simplify? If true, simplify the expanded function body before proceeding to subexpression elimination and successive steps. If false, skip this step. Defaults to true.

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.

Function compilations are cached with a key that attempts to capture all of the relevant information

compiler-mode clj/s

(compiler-mode)

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

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.

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.