Liking cljdoc? Tell your friends :D

emmy.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]].

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]].
raw docstring

*active-tags*clj/s

source

bundle-elementclj/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.

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]].
sourceraw docstring

compareclj/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.

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.
sourceraw docstring

compare-fullclj/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.

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.
sourceraw docstring

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.

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.
sourceraw docstring

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.

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.
sourceraw docstring

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:+.

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:+]].
sourceraw docstring

differential?clj/s

(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.
sourceraw docstring

eqclj/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.

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]].
sourceraw docstring

equivclj/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.

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]].
sourceraw docstring

finite-termclj/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.

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.
sourceraw docstring

fresh-tagclj/s

(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.
sourceraw docstring

from-termsclj/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.

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.
sourceraw docstring

IPerturbedclj/sprotocol

extract-tangentclj/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).

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.)

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-tagclj/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.

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`.
source

lift-1clj/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.

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.
sourceraw docstring

lift-2clj/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.

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.
sourceraw docstring

lift-nclj/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.

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).
sourceraw docstring

make-termclj/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]]

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

`tags` defaults to [[uv/empty-set]]
sourceraw docstring

map-coefficientsclj/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.

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.
sourceraw docstring

max-order-tagclj/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.

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.
sourceraw docstring

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.

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.
sourceraw docstring

primal-partclj/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.

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.
sourceraw docstring

primal-tangent-pairclj/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.

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.
sourceraw docstring

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.

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

tangent-partclj/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.

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`.
sourceraw docstring

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.

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.
sourceraw docstring

with-active-tagclj/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.

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`.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close