Pairing functions and minor utils/typing/doc fixes

[Baharis]

Context

This PR introduces a few small technical improvements to instamatic utilities and adds a new module to instamatic.utils: pairing which implements pairing functions based on the ulam spiral (regular and hexagonal variant). The changes are mostly typing or documentation fixes, as well as a new closed attribute added to pairwise function that allows yielding the last-first pair of points alongside others:

>>> for a, b in pairwise('ABCD', closed=True)):
>>>    print('{a}{b}')

<<< 'AB'
<<< 'BC'
<<< 'CD'
<<< 'DA'  # this is not yielded in previous version or if closed=False (default)

The four new functions (two plus inverse functions) in the pairing module include:

• ulam2ij(n): return coordinates of n-th point on regular Ulam spiral;
• ij2ulam(i, j): return regular Ulam index of point (i, j) in orthogonal 2D space;
• hulam2uv(n): return coordinates of n-th point on a hexagonal Ulam spiral;
• uv2hulam(u, v): return hexagonal Ulam index of point (u, v) in hexagonal 2D space.

The hexagonal space is indexed using a "hulam" pairing, ulam spiral analogue, defined as: x axis right, y axis 60 degrees anticlockwise. Both function pairs allow for easy iterating over 2D space points (grid windows or measurement locations) on the grid space using natural numbers. The documentation of individual functions is sparse, because most of their docs is common to all of them and resides in the module __doc__. For human eye, the role of this module is best explained using the example from the if __name__ == "__main__" block:

ij / uj grid:
(-4, 4) (-3, 4) (-2, 4) (-1, 4) ( 0, 4) ( 1, 4) ( 2, 4) ( 3, 4) ( 4, 4)
(-4, 3) (-3, 3) (-2, 3) (-1, 3) ( 0, 3) ( 1, 3) ( 2, 3) ( 3, 3) ( 4, 3)
(-4, 2) (-3, 2) (-2, 2) (-1, 2) ( 0, 2) ( 1, 2) ( 2, 2) ( 3, 2) ( 4, 2)
(-4, 1) (-3, 1) (-2, 1) (-1, 1) ( 0, 1) ( 1, 1) ( 2, 1) ( 3, 1) ( 4, 1)
(-4, 0) (-3, 0) (-2, 0) (-1, 0) ( 0, 0) ( 1, 0) ( 2, 0) ( 3, 0) ( 4, 0)
(-4,-1) (-3,-1) (-2,-1) (-1,-1) ( 0,-1) ( 1,-1) ( 2,-1) ( 3,-1) ( 4,-1)
(-4,-2) (-3,-2) (-2,-2) (-1,-2) ( 0,-2) ( 1,-2) ( 2,-2) ( 3,-2) ( 4,-2)
(-4,-3) (-3,-3) (-2,-3) (-1,-3) ( 0,-3) ( 1,-3) ( 2,-3) ( 3,-3) ( 4,-3)
(-4,-4) (-3,-4) (-2,-4) (-1,-4) ( 0,-4) ( 1,-4) ( 2,-4) ( 3,-4) ( 4,-4)

Ulam index grid:
  64   63   62   61   60   59   58   57   56
  65   36   35   34   33   32   31   30   55
  66   37   16   15   14   13   12   29   54
  67   38   17    4    3    2   11   28   53
  68   39   18    5    0    1   10   27   52
  69   40   19    6    7    8    9   26   51
  70   41   20   21   22   23   24   25   50
  71   42   43   44   45   46   47   48   49
  72   73   74   75   76   77   78   79   80

Hulam index grid:
                 48  47  46  45  44  69 100 137 180
               49  27  26  25  24  43  68  99 136
             50  28  12  11  10  23  42  67  98
           51  29  13   3   2   9  22  41  66
         52  30  14   4   0   1   8  21  40
       81  53  31  15   5   6   7  20  39
    116  82  54  32  16  17  18  19  38
  157 117  83  55  33  34  35  36  37
204 158 118  84  56  57  58  59  60

The new functionality introduced here is not used by the current version of instamatic. It may seem controversial, but I have a large update that I would like to publish in October. I decided to publish this smaller update in preparation to the large publication, so that in each pull request, the review focus may remain on the main subject.

Changes

• pairwise.py: Added two Z^2 <–> N_0 pairing bijections in instamatic.utils;
• test_utils.pt: Added tests for all new functions from pairwise.py;
• iterating.py: Added close argument to pairwise to yield "last, first" pair;
• controller.py: Fixed ctrl.get_movie type hint and documentation;
• _typing.py: Added float_nm annotated type for when distance is expressed as float.

[Baharis]

As is the case with #166, I plan to merge this PR ASAP, preferably by the end of the week. My git history is somewhat tangled, and squash-merging these into main will help me prepare the ultimate update that both these PRs lead to.