passagemath-modules 10.6.31rc3__cp314-cp314-musllinux_1_2_aarch64.whl

sage/matrix/docs.py

@@ -0,0 +1,430 @@
+# sage_setup: distribution = sagemath-modules
+r"""
+Matrices over an arbitrary ring
+
+AUTHORS:
+
+- William Stein
+
+- Martin Albrecht: conversion to Pyrex
+
+- Jaap Spies: various functions
+
+- Gary Zablackis: fixed a sign bug in generic determinant.
+
+- William Stein and Robert Bradshaw - complete restructuring.
+
+- Rob Beezer - refactor kernel functions.
+
+Elements of matrix spaces are of class ``Matrix`` (or a
+class derived from Matrix). They can be either sparse or dense, and
+can be defined over any base ring.
+
+EXAMPLES:
+
+We create the `2\times 3` matrix
+
+.. MATH::
+
+        \left(\begin{matrix} 1&2&3\\4&5&6 \end{matrix}\right)
+
+
+as an element of a matrix space over `\QQ`::
+
+    sage: M = MatrixSpace(QQ,2,3)
+    sage: A = M([1,2,3, 4,5,6]); A
+    [1 2 3]
+    [4 5 6]
+    sage: A.parent()
+    Full MatrixSpace of 2 by 3 dense matrices over Rational Field
+
+Alternatively, we could create A more directly as follows (which
+would completely avoid having to create the matrix space)::
+
+    sage: A = matrix(QQ, 2, [1,2,3, 4,5,6]); A
+    [1 2 3]
+    [4 5 6]
+
+We next change the top-right entry of `A`. Note that matrix
+indexing is `0`-based in Sage, so the top right entry is
+`(0,2)`, which should be thought of as "row number
+`0`, column number `2`".
+
+::
+
+    sage: A[0,2] = 389
+    sage: A
+    [  1   2 389]
+    [  4   5   6]
+
+Also notice how matrices print. All columns have the same width and
+entries in a given column are right justified. Next we compute the
+reduced row echelon form of `A`.
+
+::
+
+    sage: A.rref()
+    [      1       0 -1933/3]
+    [      0       1  1550/3]
+
+
+Indexing
+========
+
+Sage has quite flexible ways of extracting elements or submatrices
+from a matrix::
+
+    sage: m=[(1, -2, -1, -1,9), (1, 8, 6, 2,2), (1, 1, -1, 1,4), (-1, 2, -2, -1,4)] ; M = matrix(m)
+    sage: M
+    [ 1 -2 -1 -1  9]
+    [ 1  8  6  2  2]
+    [ 1  1 -1  1  4]
+    [-1  2 -2 -1  4]
+
+Get the 2 x 2 submatrix of M, starting at row index and column index 1::
+
+    sage: M[1:3,1:3]
+    [ 8  6]
+    [ 1 -1]
+
+Get the 2 x 3 submatrix of M starting at row index and column index 1::
+
+    sage: M[1:3,[1..3]]
+    [ 8  6  2]
+    [ 1 -1  1]
+
+Get the second column of M::
+
+    sage: M[:,1]
+    [-2]
+    [ 8]
+    [ 1]
+    [ 2]
+
+Get the first row of M::
+
+    sage: M[0,:]
+    [ 1 -2 -1 -1  9]
+
+Get the last row of M (negative numbers count from the end)::
+
+    sage: M[-1,:]
+    [-1  2 -2 -1  4]
+
+More examples::
+
+    sage: M[range(2),:]
+    [ 1 -2 -1 -1  9]
+    [ 1  8  6  2  2]
+    sage: M[range(2),4]
+    [9]
+    [2]
+    sage: M[range(3),range(5)]
+    [ 1 -2 -1 -1  9]
+    [ 1  8  6  2  2]
+    [ 1  1 -1  1  4]
+
+    sage: M[3,range(5)]
+    [-1  2 -2 -1  4]
+    sage: M[3,:]
+    [-1  2 -2 -1  4]
+    sage: M[3,4]
+    4
+
+    sage: M[-1,:]
+    [-1  2 -2 -1  4]
+
+    sage: A = matrix(ZZ,3,4, [3, 2, -5, 0, 1, -1, 1, -4, 1, 0, 1, -3]); A
+    [ 3  2 -5  0]
+    [ 1 -1  1 -4]
+    [ 1  0  1 -3]
+
+A series of three numbers, separated by colons, like ``n:m:s``, means
+numbers from ``n`` up to (but not including) ``m``, in steps of ``s``.
+So ``0:5:2`` means the sequence ``[0,2,4]``::
+
+    sage: A[:,0:4:2]
+    [ 3 -5]
+    [ 1  1]
+    [ 1  1]
+
+    sage: A[1:,0:4:2]
+    [1 1]
+    [1 1]
+
+    sage: A[2::-1,:]
+    [ 1  0  1 -3]
+    [ 1 -1  1 -4]
+    [ 3  2 -5  0]
+
+    sage: A[1:,3::-1]
+    [-4  1 -1  1]
+    [-3  1  0  1]
+
+    sage: A[1:,3::-2]
+    [-4 -1]
+    [-3  0]
+
+    sage: A[2::-1,3:1:-1]
+    [-3  1]
+    [-4  1]
+    [ 0 -5]
+
+We can also change submatrices using these indexing features::
+
+    sage: M=matrix([(1, -2, -1, -1,9), (1, 8, 6, 2,2), (1, 1, -1, 1,4), (-1, 2, -2, -1,4)]); M
+    [ 1 -2 -1 -1  9]
+    [ 1  8  6  2  2]
+    [ 1  1 -1  1  4]
+    [-1  2 -2 -1  4]
+
+Set the 2 x 2 submatrix of M, starting at row index and column index 1::
+
+    sage: M[1:3,1:3] = [[1,0],[0,1]]; M
+    [ 1 -2 -1 -1  9]
+    [ 1  1  0  2  2]
+    [ 1  0  1  1  4]
+    [-1  2 -2 -1  4]
+
+Set the 2 x 3 submatrix of M starting at row index and column index 1::
+
+    sage: M[1:3,[1..3]] = M[2:4,0:3]; M
+    [ 1 -2 -1 -1  9]
+    [ 1  1  0  1  2]
+    [ 1 -1  2 -2  4]
+    [-1  2 -2 -1  4]
+
+Set part of the first column of M::
+
+    sage: M[1:,0]=[[2],[3],[4]]; M
+    [ 1 -2 -1 -1  9]
+    [ 2  1  0  1  2]
+    [ 3 -1  2 -2  4]
+    [ 4  2 -2 -1  4]
+
+Or do a similar thing with a vector::
+
+    sage: M[1:,0]=vector([-2,-3,-4]); M
+    [ 1 -2 -1 -1  9]
+    [-2  1  0  1  2]
+    [-3 -1  2 -2  4]
+    [-4  2 -2 -1  4]
+
+Or a constant::
+
+    sage: M[1:,0]=30; M
+    [ 1 -2 -1 -1  9]
+    [30  1  0  1  2]
+    [30 -1  2 -2  4]
+    [30  2 -2 -1  4]
+
+
+Set the first row of M::
+
+    sage: M[0,:]=[[20,21,22,23,24]]; M
+    [20 21 22 23 24]
+    [30  1  0  1  2]
+    [30 -1  2 -2  4]
+    [30  2 -2 -1  4]
+    sage: M[0,:]=vector([0,1,2,3,4]); M
+    [ 0  1  2  3  4]
+    [30  1  0  1  2]
+    [30 -1  2 -2  4]
+    [30  2 -2 -1  4]
+    sage: M[0,:]=-3; M
+    [-3 -3 -3 -3 -3]
+    [30  1  0  1  2]
+    [30 -1  2 -2  4]
+    [30  2 -2 -1  4]
+
+
+    sage: A = matrix(ZZ,3,4, [3, 2, -5, 0, 1, -1, 1, -4, 1, 0, 1, -3]); A
+    [ 3  2 -5  0]
+    [ 1 -1  1 -4]
+    [ 1  0  1 -3]
+
+We can use the step feature of slices to set every other column::
+
+    sage: A[:,0:3:2] = 5; A
+    [ 5  2  5  0]
+    [ 5 -1  5 -4]
+    [ 5  0  5 -3]
+
+    sage: A[1:,0:4:2] = [[100,200],[300,400]]; A
+    [  5   2   5   0]
+    [100  -1 200  -4]
+    [300   0 400  -3]
+
+We can also count backwards to flip the matrix upside down::
+
+    sage: A[::-1,:]=A; A
+    [300   0 400  -3]
+    [100  -1 200  -4]
+    [  5   2   5   0]
+
+
+    sage: A[1:,3::-1]=[[2,3,0,1],[9,8,7,6]]; A
+    [300   0 400  -3]
+    [  1   0   3   2]
+    [  6   7   8   9]
+
+    sage: A[1:,::-2] = A[1:,::2]; A
+    [300   0 400  -3]
+    [  1   3   3   1]
+    [  6   8   8   6]
+
+    sage: A[::-1,3:1:-1] = [[4,3],[1,2],[-1,-2]]; A
+    [300   0  -2  -1]
+    [  1   3   2   1]
+    [  6   8   3   4]
+
+
+We save and load a matrix::
+
+    sage: A = matrix(Integers(8),3,range(9))
+    sage: loads(dumps(A)) == A
+    True
+
+MUTABILITY: Matrices are either immutable or not. When initially
+created, matrices are typically mutable, so one can change their
+entries. Once a matrix `A` is made immutable using
+``A.set_immutable()`` the entries of `A`
+cannot be changed, and `A` can never be made mutable again.
+However, properties of `A` such as its rank, characteristic
+polynomial, etc., are all cached so computations involving
+`A` may be more efficient. Once `A` is made
+immutable it cannot be changed back. However, one can obtain a
+mutable copy of `A` using ``copy(A)``.
+
+EXAMPLES::
+
+    sage: A = matrix(RR,2,[1,10,3.5,2])
+    sage: A.set_immutable()
+    sage: copy(A) is A
+    False
+
+The echelon form method always returns immutable matrices with
+known rank.
+
+EXAMPLES::
+
+    sage: A = matrix(Integers(8),3,range(9))
+    sage: A.determinant()
+    0
+    sage: A[0,0] = 5
+    sage: A.determinant()
+    1
+    sage: A.set_immutable()
+    sage: A[0,0] = 5
+    Traceback (most recent call last):
+    ...
+    ValueError: matrix is immutable; please change a copy instead (i.e., use copy(M) to change a copy of M).
+
+Implementation and Design
+-------------------------
+
+Class Diagram (an x means that class is currently supported)::
+
+    x Matrix
+    x   Matrix_sparse
+    x     Matrix_generic_sparse
+    x     Matrix_integer_sparse
+    x     Matrix_rational_sparse
+          Matrix_cyclo_sparse
+    x     Matrix_modn_sparse
+          Matrix_RR_sparse
+          Matrix_CC_sparse
+          Matrix_RDF_sparse
+          Matrix_CDF_sparse
+
+    x  Matrix_dense
+    x     Matrix_generic_dense
+    x     Matrix_integer_dense
+    x     Matrix_rational_dense
+          Matrix_cyclo_dense    -- idea: restrict scalars to QQ, compute charpoly there, then factor
+    x     Matrix_modn_dense
+          Matrix_RR_dense
+          Matrix_CC_dense
+    x     Matrix_real_double_dense
+    x     Matrix_complex_double_dense
+    x     Matrix_complex_ball_dense
+
+The corresponding files in the sage/matrix library code directory
+are named
+
+::
+
+              [matrix] [base ring] [dense or sparse].
+
+::
+
+    New matrices types can only be implemented in Cython.
+
+    *********** LEVEL 1  **********
+    NON-OPTIONAL
+    For each base field it is *absolutely* essential to completely
+    implement the following functionality for that base ring:
+
+       * __cinit__     -- should use check_allocarray from cysignals.memory
+                          (only needed if allocate memory)
+       * __init__      -- this signature: 'def __init__(self, parent, entries, copy, coerce)'
+       * __dealloc__   -- use sig_free (only needed if allocate memory)
+       * set_unsafe(self, size_t i, size_t j, x) -- doesn't do bounds or any other checks; assumes x is in self._base_ring
+       * get_unsafe(self, size_t i, size_t j) -- doesn't do checks
+       * __richcmp__    -- always the same (I don't know why its needed -- bug in PYREX)
+
+    Note that the __init__ function must construct the all zero matrix if ``entries == None``.
+
+    *********** LEVEL 2  **********
+
+    IMPORTANT (and *highly* recommended):
+
+    After getting the special class with all level 1 functionality to
+    work, implement all of the following (they should not change
+    functionality, except speed (always faster!) in any way):
+
+       * def _pickle(self):
+              return data, version
+       * def _unpickle(self, data, int version)
+              reconstruct matrix from given data and version; may assume _parent, _nrows, and _ncols are set.
+              Use version numbers >= 0 so if you change the pickle strategy then
+              old objects still unpickle.
+       * cdef _list -- list of underlying elements (need not be a copy)
+       * cdef _dict -- sparse dictionary of underlying elements
+       * cdef _add_ -- add two matrices with identical parents
+       * _matrix_times_matrix_c_impl -- multiply two matrices with compatible dimensions and
+                                        identical base rings (both sparse or both dense)
+       * cpdef _richcmp_ -- compare two matrices with identical parents
+       * cdef _lmul_c_impl -- multiply this matrix on the right by a scalar, i.e., self * scalar
+       * cdef _rmul_c_impl -- multiply this matrix on the left by a scalar, i.e., scalar * self
+       * __copy__
+       * __neg__
+
+    The list and dict returned by _list and _dict will *not* be changed
+    by any internal algorithms and are not accessible to the user.
+
+    *********** LEVEL 3  **********
+    OPTIONAL:
+
+       * cdef _sub_
+       * __invert__
+       * _multiply_classical
+       * __deepcopy__
+
+    Further special support:
+       * Matrix windows -- to support Strassen multiplication for a given base ring.
+       * Other functions, e.g., transpose, for which knowing the
+         specific representation can be helpful.
+
+    .. NOTE::
+
+       - For caching, use self.fetch and self.cache.
+
+       - Any method that can change the matrix should call
+         ``check_mutability()`` first.  There are also many fast cdef'd bounds checking methods.
+
+       - Kernels of matrices
+         Implement only a left_kernel() or right_kernel() method, whichever requires
+         the least overhead (usually meaning little or no transposing).  Let the
+         methods in the matrix2 class handle left, right, generic kernel distinctions.
+"""

sage/matrix/echelon_matrix.pyx

@@ -0,0 +1,155 @@
+# sage_setup: distribution = sagemath-modules
+r"""
+Echelon matrices over finite fields.
+"""
+# ****************************************************************************
+#       Copyright (C) 2014 Vincent Delecroix <20100.delecroix@gmail.com>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from sage.matrix.matrix0 cimport Matrix
+
+
+def reduced_echelon_matrix_iterator(K, k, n, bint sparse=False, bint copy=True, bint set_immutable=False):
+    r"""
+    An iterator over `(k,n)` reduced echelon matrices over the finite field `K`.
+
+    INPUT:
+
+    - ``K`` -- a finite field
+
+    - ``k`` -- number of rows (or the size of the subspace)
+
+    - ``n`` -- number of columns (or the dimension of the ambient space)
+
+    - ``sparse`` -- boolean (default: ``False``)
+
+    - ``copy`` -- boolean (default: ``True``); if set to ``False`` then
+      iterator yields the same matrix over and over (but with different
+      entries).  Default is ``True`` which is safer but might be slower.
+
+    - ``set_immutable`` -- boolean; if set to ``True`` then the output matrices
+      are immutable. This option automatically turns ``copy`` into ``True``.
+
+
+    .. NOTE::
+
+        We ensure that the iteration order is so that all matrices with given
+        pivot columns are generated consecutively. Furthermore, the order in
+        which the pivot columns appear is lexicographic.
+
+        It would be faster to generate the pivots columns following a Gray code.
+        There would be only one pivot changing at a time, avoiding the possibly
+        expensive ``m0.__copy__()``. However that would modify the generation
+        order some functions depend upon.
+
+    EXAMPLES::
+
+        sage: from sage.matrix.echelon_matrix import reduced_echelon_matrix_iterator
+        sage: it = reduced_echelon_matrix_iterator(GF(2), 2, 3)
+        sage: for m in it:
+        ....:     print(m)
+        ....:     print(m.pivots())
+        ....:     print("*******")
+        [1 0 0]
+        [0 1 0]
+        (0, 1)
+        *******
+        [1 0 0]
+        [0 1 1]
+        (0, 1)
+        *******
+        [1 0 1]
+        [0 1 0]
+        (0, 1)
+        *******
+        [1 0 1]
+        [0 1 1]
+        (0, 1)
+        *******
+        [1 0 0]
+        [0 0 1]
+        (0, 2)
+        *******
+        [1 1 0]
+        [0 0 1]
+        (0, 2)
+        *******
+        [0 1 0]
+        [0 0 1]
+        (1, 2)
+        *******
+
+    TESTS:
+
+    Testing cardinalities::
+
+        sage: q = 71
+        sage: F = GF(q)
+        sage: len(list(reduced_echelon_matrix_iterator(F, 1, 3, copy=False))) == q**2+q+1
+        True
+        sage: len(list(reduced_echelon_matrix_iterator(F, 2, 3, copy=False))) == q**2+q+1
+        True
+
+    Testing options::
+
+        sage: it = reduced_echelon_matrix_iterator(GF(4, 'z'), 2, 4, copy=False)                    # needs sage.rings.finite_rings
+        sage: next(it) is next(it)                                                                  # needs sage.rings.finite_rings
+        True
+        sage: for a in it: pass
+
+        sage: it = reduced_echelon_matrix_iterator(GF(4, 'z'), 2, 4, set_immutable=True)            # needs sage.rings.finite_rings
+        sage: all(a.is_immutable() and a.echelon_form() == a for a in it)
+        True
+    """
+    cdef Matrix m0,m,mm
+    cdef Py_ssize_t i
+    n = int(n)
+    k = int(k)
+
+    if n < k:
+        raise NotImplementedError("echelon matrix with fewer rows than columns "
+                "i.e. not full rank) are not implemented")
+
+    from sage.matrix.matrix_space import MatrixSpace
+    from itertools import combinations,product
+
+    copy = copy or set_immutable
+
+    m0 = MatrixSpace(K,k,n,sparse=sparse)()
+    Klist = list(K)
+    K1 = K.one()
+
+    # First, we select which columns will be pivots:
+    for pivots in combinations(range(n),k):
+        m = m0.__copy__()
+        free_positions = []
+        for i in range(k):
+            m[i,pivots[i]] = K1
+            for j in range(pivots[i]+1,n):
+                if j not in pivots:
+                    free_positions.append((i,j))
+
+        # Next, we fill in those entries that are not
+        # determined by the echelon form alone:
+        num_free_pos = len(free_positions)
+        for v in product(Klist, repeat=num_free_pos):
+            for i in range(num_free_pos):
+                m[free_positions[i]] = v[i]
+
+            if copy:
+                mm = m.__copy__()
+                mm.cache('pivots',pivots)
+                mm.cache('rank',k)
+                mm.cache('in_echelon_form',True)
+                if set_immutable:
+                    mm.set_immutable()
+                yield mm
+            else:
+                yield m
+            del v   # hack: Python itertools reuses the tuple if nobody else uses it
+        del pivots  # hack: Python itertools reuses the tuple if nobody else uses it

sage/matrix/matrix.pxd

@@ -0,0 +1,2 @@
+# sage_setup: distribution = sagemath-modules
+from sage.matrix.matrix2 cimport Matrix

sage/matrix/matrix0.pxd

@@ -0,0 +1,68 @@
+# sage_setup: distribution = sagemath-modules
+"""
+Generic matrices
+"""
+
+# ***************************************************************************
+#       Copyright (C) 2006 William Stein <wstein@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ***************************************************************************
+
+cimport sage.structure.element
+cimport sage.structure.mutability
+
+cdef class Matrix(sage.structure.element.Matrix):
+    # Properties of any matrix  (plus _parent, inherited from base class)
+    cdef public object _subdivisions
+    cdef public object _base_ring
+    cdef bint _is_immutable
+
+    cpdef _add_(self, other)
+    cpdef _sub_(self, other)
+
+    cdef bint _will_use_strassen(self, Matrix right) except -2
+    cdef bint _will_use_strassen_echelon(self) except -2
+    cdef int _strassen_default_cutoff(self, Matrix right) except -2
+    cdef int _strassen_default_echelon_cutoff(self) except -2
+
+    # Implementation of hash function
+    cdef long _hash_(self) except -1
+    cdef void get_hash_constants(self, long C[5]) noexcept
+
+    # Cache
+    cdef public object _cache
+    cdef long hash  # cached hash value
+    cdef void clear_cache(self) noexcept
+    cdef fetch(self, key)
+    cdef cache(self, key, x)
+
+    # Mutability and bounds checking
+    cdef check_bounds(self, Py_ssize_t i, Py_ssize_t j)
+    cdef check_mutability(self)
+    cdef check_bounds_and_mutability(self, Py_ssize_t i, Py_ssize_t j)
+
+    # Unsafe entry access
+    cdef set_unsafe(self, Py_ssize_t i, Py_ssize_t j, object x)
+    cdef get_unsafe(self, Py_ssize_t i, Py_ssize_t j)
+    cdef _coerce_element(self, x)
+    cdef bint get_is_zero_unsafe(self, Py_ssize_t i, Py_ssize_t j) except -1
+
+    # Row and column operations
+    cdef check_row_bounds(self, Py_ssize_t r1, Py_ssize_t r2)
+    cdef check_column_bounds(self, Py_ssize_t c1, Py_ssize_t c2)
+    cdef check_row_bounds_and_mutability(self, Py_ssize_t r1, Py_ssize_t r2)
+    cdef check_column_bounds_and_mutability(self, Py_ssize_t c1, Py_ssize_t c2)
+    cdef swap_rows_c(self, Py_ssize_t r1, Py_ssize_t r2)
+    cdef swap_columns_c(self, Py_ssize_t c1, Py_ssize_t c2)
+    cdef add_multiple_of_row_c(self, Py_ssize_t i, Py_ssize_t j,    s, Py_ssize_t col_start)
+    cdef add_multiple_of_column_c(self, Py_ssize_t i, Py_ssize_t j, s, Py_ssize_t row_start)
+    cdef rescale_row_c(self, Py_ssize_t i, s, Py_ssize_t start_col)
+    cdef rescale_col_c(self, Py_ssize_t i, s, Py_ssize_t start_row)
+
+    # Helper function for inverse of sparse matrices
+    cdef build_inverse_from_augmented_sparse(self, A)