sicmutils.differential — sicmutils 0.21.1

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

See sicmutils.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 cljs

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 Differentials 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, ie, 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 (ie, 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 ([[sicmutils.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 sicmutils 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]]

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 (ie, if you provide Differential instances with no non-zero tangent parts, or all non-Differentials), returns nil.

one? clj/s

(one? dx)

Returns true if the supplied instance has a [[finite-part]] that responds true to [[sicmutils.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, ie, 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, ie, 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.