emmy.differential — org.mentat/emmy 0.31.0

This namespace contains an implementation of [[Differential]], a generalized dual number type that forms the basis for the forward-mode automatic differentiation implementation in emmy.

See emmy.calculus.derivative for a fleshed-out derivative implementation using [[Differential]].

*active-tags* clj/s

bundle-element clj/s

(bundle-element primal)

(bundle-element primal tag)

(bundle-element primal tangent tag)

Generate a new [[Differential]] object with the supplied primal and tangent components, and the supplied internal tag that this [[Differential]] will carry around to prevent perturbation confusion.

If the tangent component is 0, acts as identity on primal. tangent defaults to 1.

tag defaults to a side-effecting call to fresh-tag; you can retrieve this unknown tag by calling max-order-tag.

compare clj/s

(compare a b)

Comparator that compares [[Differential]] instances with each other or non-differentials using only the [[finite-part]] of each instance. Matches the response of equiv.

Acts as [[clojure.core/compare]] for non-differentials.

compare-full clj/s

(compare-full a b)

Comparator that compares [[Differential]] instances with each other or non-differentials using all tangent terms each instance. Matches the response of eq.

Acts as [[clojure.core/compare]] for non-differentials.

d:* clj/s

(d:*)

(d:* dx)

(d:* dx dy)

Returns an object representing the product of the two objects dx and dy.

This works by multiplying out all terms:

$$(dx1 + dx2 + dx3 + ...)(dy1 + dy2 + dy3...)$$

and then collecting any duplicate terms by summing their coefficients.

Works with non-[[Differential]] instances on either or both sides, and returns a [[Differential]] only if it contains any non-zero tangent components.

d:+ clj/s

(d:+)

(d:+ dx)

(d:+ dx dy)

(d:+ dx dy & more)

Returns an object representing the sum of the two objects dx and dy. This works by summing the coefficients of all terms with the same list of tags.

Works with non-[[Differential]] instances on either or both sides, and returns a [[Differential]] only if it contains any non-zero tangent components.

d:+* clj/s

(d:+* a b c)

Identical to (d:+ a) (d:* b c), but slightly more efficient as the function is able to skip creating a [[Differential]] instance during d:* and then immediately tearing it down for d:+.

differential? clj/s

(differential? dx)

Returns true if the supplied object is an instance of [[Differential]], false otherwise.

eq clj/s

(eq _)

(eq a b)

(eq a b & more)

For non-differentials, this is identical to [[clojure.core/=]]. For [[Differential]] instances, equality acts on tangent components too.

If you want to ignore the tangent components, use equiv.

equiv clj/s

(equiv _)

(equiv a b)

(equiv a b & more)

Returns true if all of the supplied objects have equal [[finite-part]]s, false otherwise.

Use equiv if you want to compare non-differentials with [[Differential]]s and ignore all tangent components. If you do want to take the tangent components into account, prefer eq.

finite-term clj/s

(finite-term dx)

Returns the term of the supplied [[Differential]] dx that has no tags attached to it, 0 otherwise.

[[Differential]] instances with many can be decomposed many times into primal-part and tangent-part. Repeated calls to primal-part (with different tags!) will eventually yield a non-[[Differential]] value. If you know you want this, finite-term will get you there in one shot.

NOTE that this will only work with a well-formed [[Differential]], i.e., an instance with all terms sorted by their list of tags.

fresh-tag clj/s

(fresh-tag)

Returns a new, unique tag for use inside of a [[Differential]] term list.

from-terms clj/s

(from-terms tags->coefs)

Accepts a sequence of terms (i.e., pairs of [tag-list, coefficient]), and returns:

• a well-formed [[Differential]] instance, if the terms resolve to a differential with non-zero infinitesimal terms
• the original input otherwise

Duplicate (by tag list) terms are allowed; their coefficients will be summed together and removed if they sum to zero.

IPerturbed clj/s protocol

extract-tangent clj/s

(extract-tangent this tag)

If this is perturbed, return the tangent component paired with the supplied tag. Else, returns ([[emmy.value/zero-like]] this).

perturbed? clj/s

(perturbed? this)

Returns true if the supplied object has some known non-zero tangent to be extracted via [[extract-tangent]], false otherwise. (Return false by default if you can't detect a perturbation.)

replace-tag clj/s

(replace-tag this old-tag new-tag)

If this is perturbed, Returns a similar object with the perturbation modified by replacing any appearance of old-tag with new-tag. Else, return this.

lift-1 clj/s

(lift-1 f)

(lift-1 f df:dx)

Given:

• some unary function f
• a function df:dx that computes the derivative of f with respect to its single argument

Returns a new unary function that operates on both the original type of f and [[Differential]] instances.

If called without df:dx, df:dx defaults to (f :dfdx); this will return the derivative registered to a generic function defined with [[g/defgeneric]].

NOTE: df:dx has to ALREADY be able to handle [[Differential]] instances. The best way to accomplish this is by building df:dx out of already-lifted functions, and declaring them by forward reference if you need to.

lift-2 clj/s

(lift-2 f)

(lift-2 f df:dx df:dy)

Given:

• some binary function f
• a function df:dx that computes the derivative of f with respect to its single argument
• a function df:dy, similar to df:dx for the second arg

Returns a new binary function that operates on both the original type of f and [[Differential]] instances.

NOTE: df:dx and df:dy have to ALREADY be able to handle [[Differential]] instances. The best way to accomplish this is by building df:dx and df:dy out of already-lifted functions, and declaring them by forward reference if you need to.

lift-n clj/s

(lift-n f df:dx df:dx1 df:dx2)

Given:

• some function f that can handle 0, 1 or 2 arguments
• df:dx, a fn that returns the derivative wrt the single arg in the unary case
• df:dx1 and df:dx2, fns that return the derivative with respect to the first and second args in the binary case

Returns a new any-arity function that operates on both the original type of f and [[Differential]] instances.

NOTE: The n-ary case of f is populated by nested calls to the binary case. That means that this is NOT an appropriate lifting method for an n-ary function that isn't built out of associative binary calls. If you need this ability, please file an issue at the emmy issue tracker.

make-term clj/s

(make-term coef)

(make-term tags coef)

Returns a [[Differential]] term with the supplied vector-set of tags paired with coefficient coef.

tags defaults to [[uv/empty-set]]

map-coefficients clj/s

(map-coefficients f d)

Given a function f and [[Differential]] instance d, returns a new [[Differential]] generated by transforming all coefficients c of d to (f c).

Any term in the returned instance with a v/zero? coefficient will be filtered out.

max-order-tag clj/s

(max-order-tag dx)

(max-order-tag dx & dxs)

Given one or more well-formed [[Differential]] objects, returns the maximum ('highest order') tag found in the highest-order term of any of the [[Differential]] instances.

If there is NO maximal tag (i.e., if you provide [[Differential]] instances with no non-zero tangent parts, or all non-[[Differential]]s), returns nil.

one? clj/s

(one? dx)

Returns true if the supplied instance has a [[finite-part]] that responds true to [[emmy.value/one?]], and zero coefficients on any of its tangent components; false otherwise.

NOTE: This means that one? will not do what you expect as a conditional inside some function. If you want to branch inside some function you're taking the derivative of, prefer (= 1 dx). This will only look at the [[finite-part]] and ignore the values of the tangent parts.

primal-part clj/s

(primal-part dx)

(primal-part dx tag)

Returns a [[Differential]] containing only the terms of dx that do NOT contain the supplied tag, i.e., the primal component of dx with respect to tag.

If no tag is supplied, defaults to ([[max-order-tag]] dx).

NOTE: every [[Differential]] can be factored into a dual number of the form

primal + (tangent * tag)

For each tag in any of its terms. primal-part returns this first piece, potentially simplified into a non-[[Differential]] if the primal part contains no other tags.

primal-tangent-pair clj/s

(primal-tangent-pair dx)

(primal-tangent-pair dx tag)

Returns a pair of the primal and tangent components of the supplied dx, with respect to the supplied tag. See the docs for primal-part and tangent-part for more details.

primal-tangent-pair is equivalent to

[([[primal-part]] dx tag) ([[tangent-part]] dx tag)]

but slightly more efficient if you need both.

tag-active? clj/s

(tag-active? tag)

Returns true if tag is an element of *active-tags* (and therefore pending for extraction by some nested derivative), false otherwise.

tangent-part clj/s

(tangent-part dx)

(tangent-part dx tag)

Returns a [[Differential]] containing only the terms of dx that contain the supplied tag, i.e., the tangent component of dx with respect to tag.

If no tag is supplied, defaults to ([[max-order-tag]] dx).

NOTE: Every [[Differential]] can be factored into a dual number of the form

primal + (tangent * tag)

For each tag in any of its terms. tangent-part returns a [[Differential]] representing (tangent * tag), or 0 if dx contains no terms with the supplied tag.

NOTE: the 2-arity case is similar to ([[extract-tangent]] dx tag); the only difference is that [[extract-tangent]] drops the dx tag from all terms in the returned value. Call [[extract-tangent]] if you want to drop tag.

terms:* clj/s

(terms:* xlist ylist)

Returns a vector of non-zero [[Differential]] terms that represent the product of the differential term lists xs and ys.

NOTE that this function doesn't need to call [[collect-terms]] internally because grouping is accomplished by the internal [[terms:+]] calls.

with-active-tag clj/s

(with-active-tag tag f args)

Like apply, but conj-es tag onto the dynamic variable *active-tags* inside the scope of f.

Returns the result of applying f to args.