Docs for 2.1.0 (#397)

rsokl · web-flow · commit 17fba10b38ee · 2022-01-01T14:08:48.000-05:00
* fix inaccuracte type hint

* fix docstring typos

* update changelog, nep-29 info; add save/load docs

* minor docs improvment

* mention py310
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -6,6 +6,40 @@ This is a record of all past mygrad releases and what went into them,
 in reverse chronological order. All previous releases should still be available
 on pip.
 
+.. _v2.1.0:
+
+------------------
+2.1.0 - 2022-01-01
+------------------
+
+New Functions and Utilities
+---------------------------
+
+The following differentiable functions are now supported by MyGrad, and "drop-in" overrides for their NumPy counterparts are supported as well.
+
+ - :func:`~mygrad.atleast_1d`
+ - :func:`~mygrad.atleast_2d`
+ - :func:`~mygrad.atleast_3d`
+
+Basic tensor save/load functionality has been added (thanks to @kw-0).
+
+ - :func:`~mygrad.save`
+ - :func:`~mygrad.load`
+
+Improvements
+------------
+
+- :func:`~mygrad.clip` and ``Tensor.clip`` now accept an ``out`` target, permitting in-place operations. 
+- The method ``Tensor.__index__()`` is now implemented, which permits scalar integer-valued tensors to be used to index into Python sequences.
+- Added Python 3.10 to our automated test matrix. 
+
+Compatibility-Breaking Changes
+------------------------------
+
+- In accordance with `NEP 29 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`_ we are dropping support for NumPy versions below 1.19. However, MyGrad will not drop support for Python 3.7; to remain as lightweight and flexible as possible we will support minor versions of Python up until their EOL or until our minimal NumPy dependency drops support -- whichever occurs first.
+- The interface to :func:`~mygrad.arange` was changed from ``arange(start, stop=None, step=None, ...)`` to ``arange([start,] stop[, step,], ...)``. This provides exact parity with NumPy's arange function.
+- The derivatives of :func:`~mygrad.absolute` and :func:`~mygrad.linalg.norm` have been revised such that in cases where the derivatives used to be ``nan``, those entries will now be ``0``. Both functions can now be passed ``nan_to_num=False`` to enable the previous, more rigorous behavior. See `PR #379 <https://github.com/rsokl/MyGrad/pull/379>`_ for more details.
+
 .. _v2.0.2:
 
 ------------------
diff --git a/docs/source/generated/mygrad.load.rst b/docs/source/generated/mygrad.load.rst
@@ -0,0 +1,6 @@
+mygrad.load
+===========
+
+.. currentmodule:: mygrad
+
+.. autofunction:: load
diff --git a/docs/source/generated/mygrad.save.rst b/docs/source/generated/mygrad.save.rst
@@ -0,0 +1,6 @@
+mygrad.save
+===========
+
+.. currentmodule:: mygrad
+
+.. autofunction:: save
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -114,5 +114,6 @@ during automatic differentiation
    math
    indexing
    nnet
+   io
    graph_viz
    changes
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -24,6 +24,11 @@ navigate to the MyGrad directory, then run:
 Support for Python and NumPy
 ----------------------------
 MyGrad abides by the `NEP 29 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`_ recommendation, and adopts
-a common “time window-based” policy for support of Python and NumPy versions.
-
-Accordingly, MyGrad's drop schedule for Python and NumPy can be found `here <https://numpy.org/neps/nep-0029-deprecation_policy.html#drop-schedule>`_.
+a common “time window-based” policy for support of NumPy versions. Accordingly, MyGrad's drop schedule for NumPy versions can be found `here <https://numpy.org/neps/nep-0029-deprecation_policy.html#drop-schedule>`_. 
+
+Note, however, that MyGrad will maintain a wider window of support for minor Python 
+versions than is specified by NEP 29. Because our only dependency is NumPy, and because
+we strive to remain an exceptionally lightweight and flexible dependency to our users, 
+we will support minor versions of Python until their end of life, *or* until our lowest
+supported version of NumPy drops support for that version of Python -- whichever occurs
+first.
diff --git a/docs/source/io.rst b/docs/source/io.rst
@@ -0,0 +1,12 @@
+Input and Output
+****************
+
+.. currentmodule:: mygrad
+
+NumPy binary files (NPY, NPZ)
+-----------------------------
+.. autosummary::
+   :toctree: generated/
+
+   save
+   load
diff --git a/src/mygrad/tensor_base.py b/src/mygrad/tensor_base.py
@@ -396,7 +396,7 @@ def astensor(
 }
 
 
-_REGISTERED_NO_DIFF_NUMPY_FUNCS: Set[Callable[..., np.ndarray]] = {
+_REGISTERED_NO_DIFF_NUMPY_FUNCS: Set[Callable] = {
     np.allclose,
     np.bincount,
     np.can_cast,
@@ -1528,17 +1528,20 @@ def constant(self) -> bool:
         return self._constant
 
     @property
-    def creator(self) -> Operation:
+    def creator(self) -> Optional[Operation]:
         """The ``Operation`` instance that produced ``self``.
 
         Returns
         -------
-        Operation
+        creator : Optional[Operation]
+            The operation-instance that created the tensor, or `None`.
 
         Examples
         --------
         >>> import mygrad as mg
         >>> x = mg.Tensor(3)
+        >>> x.creator is None
+        True
         >>> y = mg.Tensor(2)
         >>> z = x * y  # Multiply(x, y) -> z
         >>> z.creator
diff --git a/src/mygrad/tensor_manip/array_shape/funcs.py b/src/mygrad/tensor_manip/array_shape/funcs.py
@@ -296,7 +296,7 @@ def atleast_1d(
 
     Returns
     -------
-    ret : Tensor
+    ret : Tensor | List[Tensor]
         A tensor, or list of tensors, each with ``a.ndim >= 1``.
         Copies are made only if necessary.
 
@@ -373,7 +373,7 @@ def atleast_2d(
 
     Returns
     -------
-    ret : Tensor
+    ret : Tensor | List[Tensor]
         A tensor, or list of tensors, each with ``a.ndim >= 2``.
         Copies are made only if necessary.
 
@@ -406,7 +406,7 @@ def atleast_2d(
     >>> x.grad
     array(1.)
 
-    If any argument to ``numpy.atleast_2d`` is a Tensor, ``mygrad.atleast_1d``
+    If any argument to ``numpy.atleast_2d`` is a Tensor, ``mygrad.atleast_2d``
     will be dispatched on all of the arguments.
 
     >>> np.atleast_2d(x, 1.)
@@ -436,7 +436,7 @@ def atleast_3d(
     """
     Convert inputs to tensors with at least one dimension.
 
-    Scalar inputs are converted to 2-dimensional tensors, whilst
+    Scalar inputs are converted to 3-dimensional tensors, whilst
     higher-dimensional inputs are preserved.
 
     This docstring was adapted from ``numpy.atleast_3d``.
@@ -448,9 +448,11 @@ def atleast_3d(
 
     Returns
     -------
-    ret : Tensor
-        A tensor, or list of tensors, each with ``a.ndim >= 2``.
-        Copies are made only if necessary.
+    ret : Tensor | List[Tensor]
+        A tensor, or list of tensors, each with ``a.ndim >= 3``.
+        Copies are made only if necessary. For example, a 1-D tensor of shape ``(N,)``
+        becomes a view of shape ``(1, N, 1)``, and a 2-D tensor of shape ``(M, N)``
+        becomes a view of shape ``(M, N, 1)``.
 
     See Also
     --------
@@ -463,11 +465,15 @@ def atleast_3d(
     Tensor([[[3.]]])
 
     >>> x = mg.arange(3.0)
-    >>> mg.atleast_3d(x)
-    array([[0., 1., 2.]])
+    >>> mg.atleast_3d(x).shape
+    (1, 3, 1)
     >>> mg.atleast_3d(x).base is x
     True
 
+    >>> x = mg.arange(12.0).reshape(4,3)
+    >>> mg.atleast_3d(x).shape
+    (4, 3, 1)
+
     >>> mg.atleast_3d(1, [[1, 2]], [[[[1, 2]]]])
     [Tensor([[[1]]]), Tensor([[[1, 2]]]), Tensor([[[[1, 2]]]])]
 
@@ -481,7 +487,7 @@ def atleast_3d(
     >>> x.grad
     array(1.)
 
-    If any argument to ``numpy.atleast_3d`` is a Tensor, ``mygrad.atleast_1d``
+    If any argument to ``numpy.atleast_3d`` is a Tensor, ``mygrad.atleast_3d``
     will be dispatched on all of the arguments.
 
     >>> np.atleast_3d(x, 1.)
