Ticket #10425: trac_10425-matrix-augment-subdivide.patch

File trac_10425-matrix-augment-subdivide.patch, 5.5 KB (added by rbeezer, 10 years ago)
  • sage/matrix/matrix1.pyx

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1291410713 28800
    # Node ID b5a0bc9c6c6bda9d5ab3ee2fdc9f1c863eb525e8
    # Parent  bb8bfd4d2eff6242af4a5de13e9133212f16ae30
    10425: manage matrix subdivisions when augment'ing
    
    diff -r bb8bfd4d2eff -r b5a0bc9c6c6b sage/matrix/matrix1.pyx
    a b  
    14291429        return self.matrix_space(nrows, ncols, sparse=sparse)(entries=entries,
    14301430                                             coerce=coerce, copy=copy)
    14311431
    1432     def augment(self, other):
     1432    def augment(self, other, subdivide=False):
    14331433        r"""
    14341434        Returns a new matrix formed by appending the matrix
    14351435        (or vector) ``other`` on the right side of ``self``.
     
    14391439        - ``other`` - a matrix, vector or free module element, whose
    14401440          dimensions are compatible with ``self``.
    14411441
     1442        - ``subdivide`` - default: ``False`` - request the resulting
     1443          matrix to have a new subdivision, separating ``self`` from ``other``.
     1444
    14421445        OUTPUT:
    14431446
    14441447        A new matrix formed by appending ``other`` onto the right side of ``self``.
    14451448        If ``other`` is a vector (or free module element) then in this context
    1446         it is apprpriate to consider it as a column vector.  (The code first
     1449        it is appropriate to consider it as a column vector.  (The code first
    14471450        converts a vector to a 1-column matrix.)
    14481451
     1452        If ``subdivide`` is ``True`` then any column subdivisions for
     1453        the two matrices are preserved, and a new subdivision is added
     1454        between ``self`` and ``other``.  If the row divisions are
     1455        identical, then they are preserved, otherwise they are discarded.
     1456        When ``subdivide`` is ``False`` there is no subdivision information
     1457        in the result.
     1458
     1459        .. warning::
     1460            If ``subdivide`` is ``True`` then unequal row subdivisions
     1461            will be discarded, since it would be ambiguous how to interpret
     1462            them.  If the subdivision behavior is not what you need,
     1463            you can manage subdivisions yourself with methods like
     1464            :meth:`~sage.matrix.matrix2.Matrix.get_subdivisions`
     1465            and
     1466            :meth:`~sage.matrix.matrix2.Matrix.subdivide`.
     1467            You might also find :func:`~sage.matrix.constructor.block_matrix`
     1468            or
     1469            :func:`~sage.matrix.constructor.block_diagonal_matrix`
     1470            useful and simpler in some instances.
     1471
     1472
    14491473        EXAMPLES:
    14501474
    14511475        Augmenting with a matrix. ::
     
    14801504            ...
    14811505            TypeError: number of rows must be the same
    14821506
     1507        Setting ``subdivide`` to ``True`` will, in its simplest form,
     1508        add a subdivision between ``self`` and ``other``. ::
     1509
     1510            sage: A = matrix(3, range(12))
     1511            sage: B = matrix(3, range(15))
     1512            sage: A.augment(B, subdivide=True)
     1513            [ 0  1  2  3| 0  1  2  3  4]
     1514            [ 4  5  6  7| 5  6  7  8  9]
     1515            [ 8  9 10 11|10 11 12 13 14]
     1516
     1517        Column subdivisions are preserved by augmentation, and enriched,
     1518        if subdivisions are requested.  (So multiple augmentations can
     1519        be recorded.) ::
     1520
     1521            sage: A = matrix(3, range(6))
     1522            sage: A.subdivide(None,[1])
     1523            sage: B = matrix(3, range(9))
     1524            sage: B.subdivide(None,[2])
     1525            sage: A.augment(B, subdivide=True)
     1526            [0|1|0 1|2]
     1527            [2|3|3 4|5]
     1528            [4|5|6 7|8]
     1529
     1530        Row subdivisions can be preserved, but only if they are identical.
     1531        Otherwise, this information is discarded and must be managed
     1532        separately. ::
     1533
     1534            sage: A = matrix(3, range(6))
     1535            sage: A.subdivide([1,3],None)
     1536            sage: B = matrix(3, range(9))
     1537            sage: B.subdivide([1,3],None)
     1538            sage: A.augment(B, subdivide=True)
     1539            [0 1|0 1 2]
     1540            [---+-----]
     1541            [2 3|3 4 5]
     1542            [4 5|6 7 8]
     1543            [---+-----]
     1544
     1545            sage: A.subdivide([1,2],None)
     1546            sage: A.augment(B, subdivide=True)
     1547            [0 1|0 1 2]
     1548            [2 3|3 4 5]
     1549            [4 5|6 7 8]
     1550
    14831551        The result retains the base ring of ``self`` by coercing
    14841552        the elements of ``other`` into the base ring of ``self``. ::
    14851553
     
    15281596            other = matrix(other.degree(), other.list())
    15291597        if not isinstance(other, sage.matrix.matrix1.Matrix):
    15301598            raise TypeError("a matrix must be augmented with another matrix, or a vector")
    1531         return self._augment(other)
     1599        return self._augment(other, subdivide)
    15321600
    1533     def _augment(self, Matrix other):
     1601    def _augment(self, Matrix other, subdivide):
    15341602        """
    15351603        Return the augmented matrix of the form::
    15361604
     
    15971665            for c from 0 <= c < other._ncols:           
    15981666                Z.set_unsafe(r, c+nc, other.get_unsafe(r,c))
    15991667
     1668        if subdivide:
     1669            self_subs_rows, self_subs_cols = self.get_subdivisions()
     1670            other_subs_rows, other_subs_cols = other.get_subdivisions()
     1671            if self_subs_rows == other_subs_rows:
     1672                z_subs_rows = self_subs_rows
     1673            else:
     1674                z_subs_rows = None
     1675            z_subs_cols = self_subs_cols + [nc]
     1676            for col in other_subs_cols:
     1677                z_subs_cols.append(col+nc)
     1678            Z.subdivide(z_subs_rows, z_subs_cols)
     1679
    16001680        return Z
    16011681
    16021682    def block_sum(self, Matrix other):