Rename emmy.differential => emmy.dual (#180)

Author: sritchie

CHANGELOG.md

@@ -2,7 +2,10 @@
 
 ## [unreleased]
 
-This PR:
+- #180 renames `emmy.differential` to `emmy.dual`, since the file now contains a
+  proper dual number implementation, not a truncated multivariate power series.
+
+- #179:
 
   - Moves the `IPerturbed` implementation for functions to `emmy.function`, out
     of `emmy.calculus.derivative`

src/emmy/abstract/function.cljc

@@ -12,7 +12,7 @@
   (:refer-clojure :exclude [name])
   (:require #?(:clj [clojure.pprint :as pprint])
             [emmy.abstract.number :as an]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.matrix :as m]
@@ -262,7 +262,7 @@
   And returns a folding function (designed for use
   with [[emmy.structure/fold-chain]]) that
 
-  generates a new [[emmy.differential/Dual]] by applying the chain rule and
+  generates a new [[emmy.dual/Dual]] by applying the chain rule and
   summing the partial derivatives for each perturbed argument in the input
   structure."
   [f primal-s tag]
@@ -309,7 +309,7 @@
 
   and generates the proper return value for `((D f) xs)`.
 
-  In forward-mode AD this is a new [[emmy.differential/Dual]] generated by
+  In forward-mode AD this is a new [[emmy.dual/Dual]] generated by
   applying the chain rule and summing the partial derivatives for each perturbed
   argument in the input structure.
 

src/emmy/calculus/derivative.cljc

@@ -7,7 +7,7 @@
   "This namespace implements a number of differential operators like [[D]], and
   the machinery to apply [[D]] to various structures."
   (:refer-clojure :exclude [partial])
-  (:require [emmy.differential :as d]
+  (:require [emmy.dual :as d]
             [emmy.expression :as x]
             [emmy.function :as f]
             [emmy.generic :as g]
@@ -22,7 +22,7 @@
 ;; ## Single and Multivariable Calculus
 ;;
 ;; These functions put together the pieces laid out
-;; in [[emmy.differential]] and declare an interface for taking
+;; in [[emmy.dual]] and declare an interface for taking
 ;; derivatives.
 
 (defn derivative
@@ -34,7 +34,7 @@
   see [[emmy.numerical.derivative/D-numeric]].
 
   `f` must be built out of generic operations that know how to
-  handle [[emmy.differential/Differential]] inputs in addition to any types that
+  handle [[emmy.dual/Dual]] inputs in addition to any types that
   a normal `(f x)` call would present. This restriction does _not_ apply to
   operations like putting `x` into a container or destructuring; just primitive
   function calls."

src/emmy/collection.cljc

@@ -7,7 +7,7 @@
   "This namespace contains implementations of various Emmy protocols for
   native Clojure collections."
   (:require [clojure.set :as cs]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.util :as u]

src/emmy/differential.cljc src/emmy/dual.cljc

@@ -3,7 +3,7 @@
 ^#:nextjournal.clerk
 {:toc true
  :visibility :hide-ns}
-(ns emmy.differential
+(ns emmy.dual
   "This namespace contains an implementation of [[Dual]], a type that forms the
   basis for the forward-mode automatic differentiation implementation in emmy.
 
@@ -15,8 +15,8 @@
 
 ;; ## Differentials, Dual Numbers and Automatic Differentiation
 ;;
-;; This namespace develops an implementation of a type called [[Differential]].
-;; A [[Differential]] is a generalization of a type called a ["dual
+;; This namespace develops an implementation of a type called [[Dual]].
+;; A [[Dual]] is a generalization of a type called a ["dual
 ;; number"](https://en.wikipedia.org/wiki/Dual_number).
 ;;
 ;; As we'll discuss, passing these numbers as arguments to some function $f$
@@ -236,7 +236,7 @@
 ;;
 ;; The solution is to introduce a new $\varepsilon$ for every level, and allow
 ;; different $\varepsilon$ instances to multiply without annihilating. Each
-;; $\varepsilon$ is called a "tag". [[Differential]] (implemented below) is a
+;; $\varepsilon$ is called a "tag". [[Dual]] (implemented below) is a
 ;; generalized dual number that can track many tags at once, allowing nested
 ;; derivatives like the one described above to work.
 ;;
@@ -256,7 +256,7 @@
 ;; ### What Return Values are Allowed?
 ;;
 ;; Before we discuss the implementation of dual
-;; numbers (called [[Differential]]), [[emmy.tape/lift-1]], [[emmy.tape/lift-2]]
+;; numbers (called [[Dual]]), [[emmy.tape/lift-1]], [[emmy.tape/lift-2]]
 ;; and the rest of the machinery that makes this all possible; what sorts of
 ;; objects is `f` allowed to return?
 ;;

src/emmy/function.cljc

@@ -10,7 +10,7 @@
   (:refer-clojure :exclude [get get-in memoize with-meta name])
   (:require [clojure.core :as core]
             [clojure.core.match :refer [match]]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.generic :as g]
             [emmy.util :as u]
             [emmy.value :as v])

src/emmy/matrix.cljc

@@ -8,7 +8,7 @@
   to the [[Matrix]] datatype."
   (:refer-clojure :exclude [get-in some])
   (:require [clojure.core :as core]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.polynomial :as poly]

src/emmy/numerical/derivative.cljc

@@ -14,7 +14,7 @@
 
   For an implementation of [forward-mode automatic
   differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation),
-  see [[emmy.differential]] (for the backing implementation)
+  see [[emmy.dual]] (for the backing implementation)
   and [[emmy.calculus.derivative]] (for the [[emmy.operator/Operator]]
   instances that make it pleasant to use this method.)"
   (:require [emmy.abstract.function :as af]

src/emmy/operator.cljc

@@ -3,7 +3,7 @@
 (ns emmy.operator
   (:refer-clojure :exclude [get identity name])
   (:require [clojure.core :as core]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.pattern.rule :refer [rule-simplifier]]

src/emmy/polynomial.cljc

@@ -8,7 +8,7 @@
   (:require [clojure.set :as set]
             [clojure.string :as cs]
             [emmy.collection]
-            [emmy.differential :as sd]
+            [emmy.dual :as sd]
             [emmy.expression :as x]
             [emmy.expression.analyze :as a]
             [emmy.function :as f]

src/emmy/quaternion.cljc

@@ -12,7 +12,7 @@
   and [[emmy.numbers]]."
   (:refer-clojure :exclude [zero?])
   (:require [emmy.complex :as sc]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.matrix :as m]

src/emmy/sci.cljc

@@ -13,7 +13,7 @@
   minimal SCI environment should select their desired namespaces from this map."
   {'emmy.algebra.fold                   (copy-ns emmy.algebra.fold (sci/create-ns 'emmy.algebra.fold))
    'emmy.complex                        (copy-ns emmy.complex (sci/create-ns 'emmy.complex))
-   'emmy.differential                   (copy-ns emmy.differential (sci/create-ns 'emmy.differential))
+   'emmy.dual                   (copy-ns emmy.dual (sci/create-ns 'emmy.dual))
    'emmy.env                            (copy-ns emmy.env (sci/create-ns 'emmy.env))
    'emmy.expression                     (copy-ns emmy.expression (sci/create-ns 'emmy.expression))
    'emmy.function                       (copy-ns emmy.function (sci/create-ns 'emmy.function))

src/emmy/series.cljc

@@ -22,7 +22,7 @@
   Doug also has a 10-line version in Haskell on [his
   website](https://www.cs.dartmouth.edu/~doug/powser.html)."
   (:refer-clojure :exclude [identity])
-  (:require [emmy.differential :as d]
+  (:require [emmy.dual :as d]
             [emmy.expression]  ;; for the effect of the defmethod of zero? for Literals
             [emmy.function :as f]
             [emmy.generic :as g]

src/emmy/structure.cljc

@@ -6,7 +6,7 @@
 (ns emmy.structure
   (:require [clojure.string :refer [join]]
             [emmy.collection]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.numsymb]

src/emmy/tape.cljc

@@ -9,7 +9,7 @@
   AD! Don't nest [[gradient]] calls inside [[emmy.env/D]] calls."
   (:refer-clojure :exclude [compare zero?])
   (:require #?(:clj [clojure.pprint :as pprint])
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generic :as g]
             [emmy.matrix :as matrix]
@@ -26,7 +26,7 @@
 ;;
 ;; This namespace develops an implementation of "reverse-mode" automatic
 ;; differentation, in contrast with the forward mode AD implementation
-;; in [[emmy.differential]]. These two are closely related, and the
+;; in [[emmy.dual]]. These two are closely related, and the
 ;; implementations could merge once I get around to reading and
 ;; implementing [the YOLO paper](https://arxiv.org/abs/2204.10923).
 ;;
@@ -58,7 +58,7 @@
 ;; First, wrap all inputs to the function in an instance of a type called
 ;; a [[TapeCell]]. This type holds
 ;;
-;;   - a "tag", used as in [[emmy.differential]] to prevent confusion
+;;   - a "tag", used as in [[emmy.dual]] to prevent confusion
 ;;     between [[TapeCell]] instances created for different nested runs of
 ;;     differentation
 ;;   - a unique ID, used to de-duplicate work in the reverse pass
@@ -331,7 +331,7 @@
 
   [<tag> <tape-or-dual-number>]
 
-  containing the tag and instance of [[emmy.differential/Dual]] or [[TapeCell]]
+  containing the tag and instance of [[emmy.dual/Dual]] or [[TapeCell]]
   associated with the inner-most call to [[with-active-tag]] in the current call
   stack.
 
@@ -358,7 +358,7 @@
 
 (defn deep-primal
   "Version of [[tape-primal]] that will descend recursively into any perturbation
-  instance returned by [[tape-primal]] or [[emmy.differential/primal]] until
+  instance returned by [[tape-primal]] or [[emmy.dual/primal]] until
   encountering a non-perturbation.
 
   Given a non-perturbation, acts as identity."
@@ -535,7 +535,7 @@
 ;;
 ;; TODO [[->partials]] really should depend on `fmap`, as should so many other
 ;; things in the library. Without this we can't generically support output
-;; values like maps or quaternions. [[emmy.differential/extract-tangent]] does
+;; values like maps or quaternions. [[emmy.dual/extract-tangent]] does
 ;; this for forward-mode, I believe.
 
 (declare ->partials)
@@ -643,7 +643,7 @@
 ;; output-walking.
 ;;
 ;; I am sure we are going to need to glom on to the [[replace-tag]] machinery as
-;; well. [[emmy.differential/extract-tangent]] is similar to what we want. Maybe
+;; well. [[emmy.dual/extract-tangent]] is similar to what we want. Maybe
 ;; we can share?
 
 (defn ^:no-doc interpret
@@ -718,12 +718,12 @@
 ;; ## Lifted Functions
 
 ;; [[lift-1]] and [[lift-2]] "lift", or augment, unary or binary functions with
-;; the ability to handle [[emmy.differential/Dual]] and [[TapeCell]] instances
+;; the ability to handle [[emmy.dual/Dual]] and [[TapeCell]] instances
 ;; in addition to whatever other types they previously supported.
 ;;
-;; Forward-mode support for [[emmy.differential/Dual]] is an implementation of
+;; Forward-mode support for [[emmy.dual/Dual]] is an implementation of
 ;; the single and multivariable Taylor series expansion methods discussed at the
-;; beginning of [[emmy.differential]].
+;; beginning of [[emmy.dual]].
 ;;
 ;; To support reverse-mode automatic differentiation, When a unary or binary
 ;; function `f` encounters a [[TapeCell]] `x` (and `y` in the binary case) it
@@ -745,12 +745,12 @@
 
 ;; There is a subtlety here, noted in the docstrings below. [[lift-1]]
 ;; and [[lift-2]] really are able to lift functions like [[clojure.core/+]] that
-;; can't accept [[emmy.differential/Dual]] and [[TapeCell]]s. But the
+;; can't accept [[emmy.dual/Dual]] and [[TapeCell]]s. But the
 ;; first-order derivatives that you have to supply _do_ have to be able to take
 ;; instances of these types.
 ;;
-;; This is because, for example, the [[emmy.differential/tangent]] of [[Dual]]
-;; might still be a [[Dual]], and will hit the first-order derivative via the
+;; This is because, for example, the [[emmy.dual/tangent]] of [[emmy.dual/Dual]]
+;; might still be a [[emmy.dual/Dual]], and will hit the first-order derivative via the
 ;; chain rule.
 ;;
 ;; Magically this will all Just Work if you pass an already-lifted function, or
@@ -764,14 +764,14 @@
     single argument
 
   Returns a new unary function that operates on both the original type of
-  `f`, [[TapeCell]] and [[emmy.differential/Dual]] instances.
+  `f`, [[TapeCell]] and [[emmy.dual/Dual]] instances.
 
   If called without `df:dx`, `df:dx` defaults to `(f :dfdx)`; this will return
   the derivative registered to a generic function defined
   with [[emmy.util.def/defgeneric]].
 
   NOTE: `df:dx` has to ALREADY be able to handle [[TapeCell]]
-  and [[emmy.differential/Dual]] instances. The best way to accomplish this is
+  and [[emmy.dual/Dual]] 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."
   ([f]
@@ -804,10 +804,10 @@
   - 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`, [[TapeCell]] and [[emmy.differential/Differential]] instances.
+  `f`, [[TapeCell]] and [[emmy.dual/Dual]] instances.
 
   NOTE: `df:dx` and `df:dy` have to ALREADY be able to handle [[TapeCell]]
-  and [[emmy.differential/Dual]] instances. The best way to accomplish this is
+  and [[emmy.dual/Dual]] 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."
   ([f]
@@ -860,7 +860,7 @@
     first and second args in the binary case
 
   Returns a new any-arity function that operates on both the original type of
-  `f`, [[TapeCell]] and [[emmy.differential/Dual]] instances.
+  `f`, [[TapeCell]] and [[emmy.dual/Dual]] 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
@@ -890,7 +890,7 @@
     `differential-op` (defaults to `(lift-1 generic-op)`)
 
   installs an appropriate unary implementation of `generic-op` for `::tape` and
-  `:emmy.differential/dual` instances."
+  `:emmy.dual/dual` instances."
   ([generic-op]
    (defunary generic-op (lift-1 generic-op)))
   ([generic-op differential-op]
@@ -905,7 +905,7 @@
     `differential-op` (defaults to `(lift-2 generic-op)`)
 
   installs an appropriate binary implementation of `generic-op` between
-  `::tape`, `::emmy.differential/dual` and `::v/scalar` instances."
+  `::tape`, `::emmy.dual/dual` and `::v/scalar` instances."
   ([generic-op]
    (defbinary generic-op (lift-2 generic-op)))
   ([generic-op differential-op]

test/emmy/calculus/derivative_test.cljc

@@ -7,7 +7,7 @@
             [emmy.abstract.number :refer [literal-number]]
             [emmy.calculus.derivative :as d :refer [D partial]]
             [emmy.complex :as c]
-            [emmy.differential :as sd]
+            [emmy.dual :as sd]
             [emmy.expression :as x]
             [emmy.function :as f]
             [emmy.generic :as g :refer [acos asin atan cos sin tan
@@ -1342,7 +1342,7 @@
     ;; space.
     ;;
     ;; Doing work inside a continuation means you're actually working
-    ;; with [[emmy.differential/Differential]] instances whose tangents can
+    ;; with [[emmy.dual/Dual]] instances whose tangents can
     ;; interact. Once you break out of the continuation, as in "bug two", the
     ;; two components separately drop their tangents, so they can't talk
     ;; anymore.

test/emmy/collection_test.cljc

@@ -7,7 +7,7 @@
             [emmy.calculus.derivative :refer [D]]
             [emmy.collection :as collection]
             [emmy.complex :refer [complex I]]
-            [emmy.differential :as d]
+            [emmy.dual :as d]
             [emmy.function :as f]
             [emmy.generators :as sg]
             [emmy.generic :as g]