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]].
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]].
(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.
(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:+.
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? 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
[[Differential]]s 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]], i.e., 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]], i.e., 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 (i.e., pairs of [tag-list, coefficient]), and
returns:
Duplicate (by tag list) terms are allowed; their coefficients will be summed together and removed if they sum to zero.
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.
(extract-tangent this tag)If this is perturbed, return the tangent component paired with the
supplied tag. Else, returns ([[emmy.value/zero-like]] this).
If `this` is perturbed, return the tangent component paired with the supplied tag. Else, returns `([[emmy.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 emmy 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 [emmy issue tracker](https://github.com/mentat-collective/emmy/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]]
(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.
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 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.
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? 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.
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 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.
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 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, 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.
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:* 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.
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 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 |