Update the release notes and docs (#320)

Some functions mentioned in the release notes were not previous emitted anywhere in the Sphinx, so autosummary entries have been added for those too.

This also adds versionadded entries for the new functions.

clifford/tools/g3c/__init__.py

@@ -69,6 +69,13 @@
     project_points_to_sphere
     project_points_to_circle
     project_points_to_line
+    iterative_closest_points_on_circles
+    closest_point_on_line_from_circle
+    closest_point_on_circle_from_line
+    iterative_closest_points_circle_line
+    iterative_furthest_points_on_circles
+    sphere_beyond_plane
+    sphere_behind_plane
 
 Misc
 --------------------
@@ -107,6 +114,7 @@
     interpret_multivector_as_object
     normalise_TR_to_unit_T
     scale_TR_translation
+    val_unsign_sphere
 
 
 Root Finding
@@ -150,6 +158,14 @@
     rotor_between_planes
     val_rotor_rotor_between_planes
 
+Submodules
+--------------------
+.. autosummary::
+    :toctree: generated/
+    
+    object_fitting
+
+
 """
 
 import math
@@ -410,6 +426,9 @@ def iterative_closest_points_on_circles(C1, C2, niterations=20):
     """
     Given two circles C1 and C2 this calculates the closest
     points on each of them to the other
+
+    .. versionchanged:: 1.3
+        Renamed from ``closest_points_on_circles``
     """
     cav = average_objects([C1, C2])
     cav2 = average_objects([C1, -C2])
@@ -433,6 +452,8 @@ def closest_point_on_line_from_circle(C, L, eps=1E-6):
     """
     Returns the point on the line L that is closest to the circle C
     Uses the algorithm described in Appendix A of Andreas Aristidou's PhD thesis
+
+    .. versionadded:: 1.3
     """
     return project_points_to_line([closest_point_on_circle_from_line(C, L, eps=eps)], L)[0]
 
@@ -441,6 +462,8 @@ def closest_point_on_circle_from_line(C, L, eps=1E-6):
     """
     Returns the point on the circle C that is closest to the line L
     Uses the algorithm described in Appendix A of Andreas Aristidou's PhD thesis
+
+    .. versionadded:: 1.3
     """
     phi = (C^einf).normal()
     B = meet(L, phi)
@@ -496,6 +519,9 @@ def iterative_closest_points_circle_line(C, L, niterations=20):
     This is an iterative algorithm based on heuristics
     Nonetheless it appears to give results on par with
     :func:`closest_point_on_circle_from_line`.
+
+    .. versionchanged:: 1.3
+        Renamed from ``closest_points_circle_line``
     """
     cav = average_objects([C, L])
     cav2 = average_objects([C, -L])
@@ -521,6 +547,9 @@ def iterative_furthest_points_on_circles(C1, C2, niterations=20):
     """
     Given two circles C1 and C2 this calculates the closest
     points on each of them to the other
+
+    .. versionchanged:: 1.3
+        Renamed from ``furthest_points_on_circles``
     """
     P2 = random_conformal_point()
     P1 = project_points_to_circle([P2], C1, closest=False)[0](1)

clifford/tools/g3c/object_fitting.py

@@ -1,3 +1,21 @@
+"""
+Tools for fitting geometric primitives to point clouds
+
+Object Fitting
+==========================================================
+
+.. autosummary::
+    :toctree: generated/
+
+    fit_circle
+    val_fit_circle
+    fit_line
+    val_fit_line
+    fit_sphere
+    val_fit_sphere
+    fit_plane
+    val_fit_plane
+"""
 
 from . import *
 

docs/changelog.rst

@@ -19,6 +19,17 @@ Changes in 1.3.x
    ``Cl(6)`` is 20\ |times| faster. This is achieved by deferring product JIT
    compilation until the product is used for the first time.
  * A new :mod:`clifford.transformations` module for linear transformations.
+ * Two new :doc:`predefined-algebras`, :mod:`clifford.dpga` and :mod:`clifford.dg3c`.
+ * Additional testing and assorted improvements for :mod:`clifford.tools.g3c`.
+ * :mod:`clifford.tools.g3c`:
+
+   * :func:`~clifford.tools.g3c.closest_point_on_circle_from_line` has now been implemented
+     roughly following the procedure described in Appendix A of
+     `Andreas Aristidou's PhD thesis <https://www.repository.cam.ac.uk/handle/1810/237554>`_.
+   * :func:`~clifford.tools.g3c.closest_point_on_line_from_circle` has now also been added,
+     projecting the result of :func:`~clifford.tools.g3c.closest_point_on_circle_from_line`
+     to the line.
+
 
 Bugs fixed
 ----------
@@ -31,6 +42,18 @@ Bugs fixed
    input, rather than silenltly producing nonsense.
  * :func:`Layout.parse_multivector` supports basis vector names which do not
    start with e.
+ * :mod:`clifford.tools.g3c`:
+
+   * :func:`~clifford.tools.g3c.val_midpoint_between_lines` now handles the case that
+     the two lines are touching.
+   * :func:`~clifford.tools.g3c.object_fitting.val_fit_circle` now correctly selects the first and
+     second eigenvalue regardless of order.
+   * :func:`~clifford.tools.g3c.sphere_beyond_plane` now tested and correct.
+   * :func:`~clifford.tools.g3c.sphere_behind_plane` now tested and correct.
+   * :func:`~clifford.tools.g3c.val_unsign_sphere` is now jitted, as it should have
+     been from the start.
+   * :func:`~clifford.tools.g3c.get_nearest_plane_point` correctly returns the conformal
+     point rather than the 3D point.
 
 Compatibility notes
 -------------------
@@ -46,6 +69,18 @@ Compatibility notes
  * The ``imt_prod_mask``, ``omt_prod_mask``, and ``lcmt_prod_mask`` attributes
    of :class:`Layout` objects have been removed, as these were an unnecessary
    intermediate computation that had no need to be public.
+ * :mod:`clifford.tools.g3c`:
+
+   * ``closest_points_on_circles`` has been renamed to
+     :func:`~clifford.tools.g3c.iterative_closest_points_on_circles`.
+   * ``closest_points_circle_line`` has been renamed to
+     :func:`~clifford.tools.g3c.iterative_closest_points_circle_line`.
+   * ``furthest_points_on_circles`` has been renamed to
+     :func:`~clifford.tools.g3c.iterative_furthest_points_on_circles`.
+ * This will be the last release to support :mod:`numba` versions below 0.49.0.
+ * While this release is compatible with :mod:`numba` version 0.49.0, it is
+   recommended to use 0.48.0 which does not emit as many warnings. See the
+   :doc:`installation` instructions for how to follow this guidance.
 
 
 Changes in 1.2.x