FOGSAA PairwiseAligner implementation (biopython#4784)

* scaffold FOGSAA and add setter for PairwiseAligner.algorithm

* add first version of FOGSAA scoring

* add restrictions to algorithm setter and support matrix scoring in FOGSAA

* add test for running fogsaa with matrix scoring

* Remove algorithm setter in lieu of FOGSAA_Mode, scaffold PathGenerator for FOGSAA

* Add basic support for FOGSAA alignment

* Add FOGSAA alignment with matrix scoring

* Add more restrictions to FOGSAA parameters.

These restrictions come from the queue data structure used not from the
algorithm itself. Changing the priority queue implementation may ease
these restrictions at a possible loss to performance.

* Change FOGSAA priority queue implementation to a max heap

This allows for the queue sort doubles, which in turn removes the
requirement of integer scores in FOGSAA.

* Allocate memory once, fix affine gaps, remove threshold

* more fixes

* Add error checking, debugging code, and fix lower bounds

* add support for different affine gaps on edges

* remove debug printfs, warn on invalid parameters

* fix floating point comparison bugs

* only copy cells of optimal path in fogsaa align

* stop using different macros for fogsaa cell types

* fix fogsaa docstrings, iterator, and reset algorithm on set_mode

* mention fogsaa in Tutorial/chapter_pairwise.rst

* fix fogsaa documentation in Doc/Tutorial/chapter_pairwise.rst

* fix typo

Bio/Align/__init__.py

@@ -3771,7 +3771,16 @@ class PairwiseAligner(_pairwisealigner.PairwiseAligner):
     and the mismatch and gap scores are zero.  Based on the values of the gap
     scores, a PairwiseAligner object automatically chooses the appropriate
     alignment algorithm (the Needleman-Wunsch, Smith-Waterman, Gotoh, or
-    Waterman-Smith-Beyer global or local alignment algorithm).
+    Waterman-Smith-Beyer global or local alignment algorithm, or the Fast
+    Optimal Global Sequence Alignment Algorithm).
+
+    The Fast Optimal Global Sequence Alignment Algorithm (FOGSAA) will never be
+    automatically selected. If you wish to use FOGSAA, you must set the "mode"
+    attribute to "fogsaa". As its name suggests, it only finds global
+    alignments and cannot be used for local alignment. FOGSAA will raise a
+    warning and may return incorrect results if the match score is less than
+    the mismatch score or any gap score or if any gap score is greater than the
+    mismatch score.
 
     Calling the "score" method on the aligner with two sequences as arguments
     will calculate the alignment score between the two sequences.