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.
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]].
(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.
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 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.
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 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.
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:*)(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.
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:+)(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.
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.
(differential? dx)Returns true if the supplied object is an instance of Differential, false
otherwise.
Returns true if the supplied object is an instance of [[Differential]], false otherwise.
(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.
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 _)(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.
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 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.
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)Returns a new, unique tag for use inside of a Differential term list.
Returns a new, unique tag for use inside of a [[Differential]] term list.
(from-terms tags->coefs)Accepts a sequence of terms (ie, pairs of [tag-list, coefficient]), and
returns:
Differential instance, if the terms resolve to a
differential with non-zero infinitesimal termsDuplicate (by tag list) terms are allowed; their coefficients will be summed together and removed if they sum to zero.
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.
(extract-tangent this tag)If this is perturbed, return the tangent component paired with the
supplied tag. Else, returns ([[sicmutils.value/zero-like]] this).
If `this` is perturbed, return the tangent component paired with the supplied tag. Else, returns `([[sicmutils.value/zero-like]] this)`.
(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.)
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 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.
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 f)(lift-1 f df:dx)Given:
fdf:dx that computes the derivative of f with respect to its
single argumentReturns 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.
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 f)(lift-2 f df:dx df:dy)Given:
fdf:dx that computes the derivative of f with respect to its
single argumentdf:dy, similar to df:dx for the second argReturns 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.
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 f df:dx df:dx1 df:dx2)Given:
f that can handle 0, 1 or 2 argumentsdf:dx, a fn that returns the derivative wrt the single arg in the unary casedf:dx1 and df:dx2, fns that return the derivative with respect to the
first and second args in the binary caseReturns 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.
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](https://github.com/sicmutils/sicmutils/issues).
(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]]
Returns a [[Differential]] term with the supplied vector-set of `tags` paired with coefficient `coef`. `tags` defaults to [[uv/empty-set]]
(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.
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-[[Differential]]s), returns nil.(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.
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 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.
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 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.
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? tag)Returns true if tag is an element of *active-tags* (and therefore pending
for extraction by some nested derivative), false otherwise.
Returns true if `tag` is an element of [[*active-tags*]] (and therefore pending for extraction by some nested derivative), false otherwise.
(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.
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`.(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.
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`.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |