casadi 3.5.6.pre2__cp39-none-win_amd64.whl → 3.6.0__cp39-none-win_amd64.whl

casadi/include/casadi/core/sparsity.hpp

@@ -2,8 +2,8 @@
  *    This file is part of CasADi.
  *
  *    CasADi -- A symbolic framework for dynamic optimization.
- *    Copyright (C) 2010-2014 Joel Andersson, Joris Gillis, Moritz Diehl,
- *                            K.U. Leuven. All rights reserved.
+ *    Copyright (C) 2010-2023 Joel Andersson, Joris Gillis, Moritz Diehl,
+ *                            KU Leuven. All rights reserved.
  *    Copyright (C) 2011-2014 Greg Horn
  *    Copyright (C) 2005-2013 Timothy A. Davis
  *
@@ -44,7 +44,9 @@ namespace casadi {
   class DeserializingStream;
 
   #ifndef SWIG
-    /** \brief Compact representation of a sparsity pattern */
+    /** \brief Compact representation of a sparsity pattern
+
+        \identifier{b8} */
     struct CASADI_EXPORT SparsityStruct {
       casadi_int nrow;
       casadi_int ncol;
@@ -64,8 +66,8 @@ namespace casadi {
    columns respectively), there are also two vectors of integers:
 
    1. "colind" [length size2()+1], which contains the index to the first non-zero element on or
-   after the corresponding column. All the non-zero elements of a particular i are thus the elements
-   with index el that fulfills: colind[i] <= el < colind[i+1].
+   after the corresponding column. All the non-zero elements of a particular column i are thus
+   the elements with index el that fulfills: colind[i] <= el < colind[i+1].
 
    2. "row" [same length as the number of non-zero elements, nnz()] The rows for each of the
    structural non-zeros.
@@ -89,7 +91,8 @@ namespace casadi {
    *
    * \author Joel Andersson
    * \date 2010-2015
-   */
+
+      \identifier{b9} */
   class CASADI_EXPORT Sparsity
     : public SharedObject,
       public SWIG_IF_ELSE(SparsityInterfaceCommon, SparsityInterface<Sparsity>),
@@ -99,7 +102,9 @@ namespace casadi {
     /// Default constructor
     explicit Sparsity(casadi_int dummy=0);
 
-    /** \brief Pattern with all structural zeros */
+    /** \brief Pattern with all structural zeros
+
+        \identifier{ba} */
     Sparsity(casadi_int nrow, casadi_int ncol);
 
     /// Construct from sparsity pattern vectors given in compressed column storage format
@@ -107,7 +112,9 @@ namespace casadi {
              const std::vector<casadi_int>& colind, const std::vector<casadi_int>& row,
              bool order_rows=false);
 
-    /** \brief Create a sparse matrix with all structural zeros */
+    /** \brief Create a sparse matrix with all structural zeros
+
+        \identifier{bb} */
     explicit Sparsity(const std::pair<casadi_int, casadi_int>& rc);
 
 #ifndef SWIG
@@ -115,7 +122,9 @@ namespace casadi {
     Sparsity(casadi_int nrow, casadi_int ncol, const casadi_int* colind, const casadi_int* row,
             bool order_rows=false);
 
-    /** \brief  Create from node */
+    /** \brief  Create from node
+
+        \identifier{bc} */
     static Sparsity create(SparsityInternal *node);
 
     /// Base class
@@ -130,13 +139,17 @@ namespace casadi {
     SparsityInternal* get() const;
 #endif
 
-    /** \brief Create a scalar sparsity pattern **/
+    /** \brief Create a scalar sparsity pattern *
+
+        \identifier{bd} */
     ///@{
     static Sparsity scalar(bool dense_scalar=true)
     { return dense_scalar ? dense(1, 1) : Sparsity(1, 1); }
     ///@}
 
-    /** \brief Create a dense rectangular sparsity pattern **/
+    /** \brief Create a dense rectangular sparsity pattern *
+
+        \identifier{be} */
     ///@{
     static Sparsity dense(casadi_int nrow, casadi_int ncol=1);
     static Sparsity dense(const std::pair<casadi_int, casadi_int> &rc) {
@@ -145,18 +158,27 @@ namespace casadi {
     ///@}
 
     /** \brief Create the sparsity pattern for a unit vector of length n and a nonzero on
-     * position el **/
+
+     * position el *
+
+        \identifier{bf} */
     ///@{
     static Sparsity unit(casadi_int n, casadi_int el);
     ///@}
 
-    /** \brief Create a upper triangular square sparsity pattern **/
+    /** \brief Create a upper triangular square sparsity pattern *
+
+        \identifier{bg} */
     static Sparsity upper(casadi_int n);
 
-    /** \brief Create a lower triangular square sparsity pattern **/
+    /** \brief Create a lower triangular square sparsity pattern *
+
+        \identifier{bh} */
     static Sparsity lower(casadi_int n);
 
-    /** \brief Create diagonal sparsity pattern **/
+    /** \brief Create diagonal sparsity pattern *
+
+        \identifier{bi} */
     ///@{
     static Sparsity diag(casadi_int nrow) { return diag(nrow, nrow);}
     static Sparsity diag(casadi_int nrow, casadi_int ncol);
@@ -170,39 +192,41 @@ namespace casadi {
      * band(n, 0) is equivalent to diag(n) \n
      * band(n, -1) has a band below the diagonal \n
      * \param p indicate
-     **/
+     *
+        \identifier{bj} */
     static Sparsity band(casadi_int n, casadi_int p);
 
     /** \brief Create banded square sparsity pattern
      *
      * banded(n, 0) is equivalent to diag(n) \n
      * banded(n, 1) is tri-diagonal matrix \n
-     **/
+     *
+        \identifier{bk} */
     static Sparsity banded(casadi_int n, casadi_int p);
 
-    /** \brief Construct a block sparsity pattern from (row, col) vectors */
+    /** \brief Construct a block sparsity pattern from (row, col) vectors
+
+        \identifier{bl} */
     static Sparsity rowcol(const std::vector<casadi_int>& row,
                            const std::vector<casadi_int>& col,
                            casadi_int nrow, casadi_int ncol);
 
-    /** \brief Create a sparsity pattern given the nonzeros in sparse triplet form
-    **/
+    ///@{
+    /** \brief Create a sparsity pattern given the nonzeros in sparse triplet form *
+
+        \identifier{bm} */
     static Sparsity triplet(casadi_int nrow, casadi_int ncol,
                             const std::vector<casadi_int>& row, const std::vector<casadi_int>& col,
                             std::vector<casadi_int>& SWIG_OUTPUT(mapping), bool invert_mapping);
-
-    /** \brief Create a sparsity pattern given the nonzeros in sparse triplet form
-        (no nonzero mapping)
-        rows_are_sorted==true means that the row entries already in increasing order
-        for each col and without any duplicates
-    **/
     static Sparsity triplet(casadi_int nrow, casadi_int ncol, const std::vector<casadi_int>& row,
                             const std::vector<casadi_int>& col);
+    ///@}
 
-    /** \brrief Create a sparsity from nonzeros
+    /** \brief Create a sparsity from nonzeros
     *
     * Inverse of `find()`
-    */
+
+        \identifier{23g} */
     static Sparsity nonzeros(casadi_int nrow, casadi_int ncol, const std::vector<casadi_int>& nz,
                               bool ind1=SWIG_IND1);
 
@@ -220,11 +244,22 @@ namespace casadi {
 #endif // SWIG
     ///@}
 
-#ifdef WITH_DEPRECATED_FEATURES
-    /** \brief [DEPRECATED] Correctness of sparsity patterns are checked during
-              construction */
-    void sanity_check(bool complete=false) const {}
-#endif // WITH_DEPRECATED_FEATURES
+    /** \brief Construct a permutation matrix P from a permutation vector p
+     * 
+     * Right multiplication of P with a vector leads to the same results as indexing that vector with p
+     * 
+     * P @ v = v[p]
+     * 
+     * The inverse of a permutation matrix is equal to its transpose (property of orthonormality)
+     *
+
+        \identifier{244} */
+    static Sparsity permutation(const std::vector<casadi_int>& p, bool invert=false);
+
+    /** \brief Construct permutation vector from permutation matrix
+
+        \identifier{245} */
+    const std::vector<casadi_int> permutation_vector(bool invert=false) const;
 
     /** Get the diagonal of the matrix/create a diagonal matrix
         (mapping will contain the nonzero mapping)
@@ -264,15 +299,21 @@ namespace casadi {
 
 #ifndef SWIG
     /** \brief Implicit or explicit type conversion to C representation
+
         In the C runtime, sparsity patterns are represented as a "const casadi_int*".
         This enables using the C runtime functions using a natural syntax.
-    */
+
+        \identifier{bn} */
     operator const casadi_int*() const;
 
-    /** \brief Implicit or explicit type conversion to compact representation */
+    /** \brief Implicit or explicit type conversion to compact representation
+
+        \identifier{bo} */
     operator const std::vector<casadi_int>&() const;
 
-    /** \brief Implicit or explicit type conversion to C representation */
+    /** \brief Implicit or explicit type conversion to C representation
+
+        \identifier{bp} */
     operator SparsityStruct() const;
 #endif // SWIG
 
@@ -292,49 +333,72 @@ namespace casadi {
     casadi_int columns() const {return size2();}
 
     /** \brief The total number of elements, including structural zeros, i.e. size2()*size1()
+
       * Beware of overflow
       * \see nnz()
-      */
+
+        \identifier{bq} */
     casadi_int numel() const;
 
     /** \brief The percentage of nonzero
+
      * Equivalent to (100.0 * nnz())/numel(), but avoids overflow
-     */
+
+        \identifier{br} */
     double density() const;
 
     /** \brief Check if the sparsity is empty
      *
      * A sparsity is considered empty if one of the dimensions is zero
      * (or optionally both dimensions)
-     */
+
+        \identifier{bs} */
     bool is_empty(bool both=false) const;
 
     /** \brief Get the number of (structural) non-zeros
+
       * \see numel()
-      */
+
+        \identifier{bt} */
     casadi_int nnz() const;
 
     /** \brief Number of non-zeros in the upper triangular half,
-     * i.e. the number of elements (i, j) with j>=i */
+
+     * i.e. the number of elements (i, j) with j>=i
+
+        \identifier{bu} */
     casadi_int nnz_upper(bool strictly=false) const;
 
     /** \brief Number of non-zeros in the lower triangular half,
-     * i.e. the number of elements (i, j) with j<=i */
+
+     * i.e. the number of elements (i, j) with j<=i
+
+        \identifier{bv} */
     casadi_int nnz_lower(bool strictly=false) const;
 
-    /** \brief Number of non-zeros on the diagonal, i.e. the number of elements (i, j) with j==i */
+    /** \brief Number of non-zeros on the diagonal, i.e. the number of elements (i, j) with j==i
+
+        \identifier{bw} */
     casadi_int nnz_diag() const;
 
-    /** \brief Upper half-bandwidth */
+    /** \brief Upper half-bandwidth
+
+        \identifier{bx} */
     casadi_int bw_upper() const;
 
-    /** \brief Lower half-bandwidth */
+    /** \brief Lower half-bandwidth
+
+        \identifier{by} */
     casadi_int bw_lower() const;
 
-    /** \brief  Get the shape */
+    /** \brief  Get the shape
+
+        \identifier{bz} */
     std::pair<casadi_int, casadi_int> size() const;
 
-    /** \brief  Get the size along a particular dimensions */
+    /** \brief  Get the size along a particular dimensions
+
+        \identifier{c0} */
     casadi_int size(casadi_int axis) const;
     /// @}
 
@@ -351,80 +415,121 @@ namespace casadi {
     static Sparsity from_file(const std::string& filename, const std::string& format_hint="");
 
 #ifndef SWIG
-    /** \brief Serialize */
+    /** \brief Serialize
+
+        \identifier{c1} */
     void serialize(std::ostream &stream) const;
 #endif
 
-    /** \brief Serialize */
+    /** \brief Serialize
+
+        \identifier{c2} */
     std::string serialize() const;
 
-    /** \brief Build Sparsity from serialization */
+    /** \brief Build Sparsity from serialization
+
+        \identifier{c3} */
     static Sparsity deserialize(std::istream& stream);
 
-    /** \brief Build Sparsity from serialization */
+    /** \brief Build Sparsity from serialization
+
+        \identifier{c4} */
     static Sparsity deserialize(const std::string& s);
 
-    /** \brief Serialize an object */
+    /** \brief Serialize an object
+
+        \identifier{c5} */
     void serialize(SerializingStream& s) const;
 
-    /** \brief Deserialize */
+    /** \brief Deserialize
+
+        \identifier{c6} */
     static Sparsity deserialize(DeserializingStream& s);
 
 #ifndef SWIG
     /** \brief Get a reference to row-vector,
-     * containing rows for all non-zero elements (see class description) */
+
+     * containing rows for all non-zero elements (see class description)
+
+        \identifier{c7} */
     const casadi_int* row() const;
 
-    /** \brief Get a reference to the colindex of all column element (see class description) */
+    /** \brief Get a reference to the colindex of all column element (see class description)
+
+        \identifier{c8} */
     const casadi_int* colind() const;
 #endif
 
     /** \brief Get the row for each non-zero entry
+
         Together with the column-vector, this vector gives the sparsity of the matrix in
         sparse triplet format, and together with the colind vector, one obtains the sparsity
-        in column compressed format. */
+        in column compressed format.
+
+        \identifier{c9} */
     std::vector<casadi_int> get_row() const;
 
     /** \brief Get the column index for each column
+
         Together with the row-vector, one obtains the sparsity pattern in the
-        column compressed format. */
+        column compressed format.
+
+        \identifier{ca} */
     std::vector<casadi_int> get_colind() const;
 
-    /** \brief  Get a reference to the colindex of column cc (see class description) */
+    /** \brief  Get a reference to the colindex of column cc (see class description)
+
+        \identifier{cb} */
     casadi_int colind(casadi_int cc) const;
 
-    /** \brief Get the row of a non-zero element */
+    /** \brief Get the row of a non-zero element
+
+        \identifier{cc} */
     casadi_int row(casadi_int el) const;
 
     /** \brief Get the column for each non-zero entry
+
         Together with the row-vector, this vector gives the sparsity of the matrix in
-        sparse triplet format, i.e. the column and row for each non-zero elements  */
+        sparse triplet format, i.e. the column and row for each non-zero elements
+
+        \identifier{cd} */
     std::vector<casadi_int> get_col() const;
 
     /// Resize
     void resize(casadi_int nrow, casadi_int ncol);
 
     /** \brief Get the index of a non-zero element
-        Add the element if it does not exist and copy object if it's not unique */
+
+        Add the element if it does not exist and copy object if it's not unique
+
+        \identifier{ce} */
     casadi_int add_nz(casadi_int rr, casadi_int cc);
 
     /** \brief Get the index of an existing non-zero element
-        return -1 if the element does not exist */
+
+        return -1 if the element does not exist
+
+        \identifier{cf} */
     casadi_int get_nz(casadi_int rr, casadi_int cc) const;
 
     /// Returns true if the pattern has a non-zero at location rr, cc
     bool has_nz(casadi_int rr, casadi_int cc) const;
 
     /** \brief Get a set of non-zero element
-        return -1 if the element does not exist */
+
+        return -1 if the element does not exist
+
+        \identifier{cg} */
     std::vector<casadi_int> get_nz(const std::vector<casadi_int>& rr,
                                     const std::vector<casadi_int>& cc) const;
 
     /** \brief Get the nonzero index for a set of elements
+
         The index vector is used both for input and outputs and must be sorted by increasing
         nonzero index, i.e. column-wise.
         Elements not found in the sparsity pattern are set to -1.
-    */
+
+        \identifier{ch} */
     void get_nz(std::vector<casadi_int>& SWIG_INOUT(indices)) const;
 
     /// Get nonzeros in lower triangular part
@@ -449,7 +554,8 @@ namespace casadi {
      *
      * Returns the sparsity of the submatrix, with a mapping such that
      *   submatrix[k] = originalmatrix[mapping[k]]
-     */
+
+        \identifier{ci} */
     Sparsity sub(const std::vector<casadi_int>& rr,
                  const std::vector<casadi_int>& cc,
                  std::vector<casadi_int>& SWIG_OUTPUT(mapping), bool ind1=false) const;
@@ -458,7 +564,8 @@ namespace casadi {
      *
      * Returns the sparsity of the corresponding elements, with a mapping such that
      *   submatrix[k] = originalmatrix[mapping[k]]
-     */
+
+        \identifier{cj} */
     Sparsity sub(const std::vector<casadi_int>& rr, const Sparsity& sp,
                  std::vector<casadi_int>& SWIG_OUTPUT(mapping), bool ind1=false) const;
 
@@ -469,7 +576,8 @@ namespace casadi {
     *
     *  \param[out] mapping the non-zeros of the original matrix
     *              for each non-zero of the new matrix
-    */
+
+        \identifier{ck} */
     Sparsity transpose(std::vector<casadi_int>& SWIG_OUTPUT(mapping),
                         bool invert_mapping=false) const;
 
@@ -481,12 +589,15 @@ namespace casadi {
 
     /// @{
     /** \brief Combine two sparsity patterns
+
         Returns the new sparsity pattern as well as a mapping with the same length as
         the number of non-zero elements
         The mapping matrix contains the arguments for each nonzero, the first bit indicates
         if the first argument is nonzero,
         the second bit indicates if the second argument is nonzero (note that none of,
-        one of or both of the arguments can be nonzero) */
+        one of or both of the arguments can be nonzero)
+
+        \identifier{cl} */
 #ifndef SWIG
     Sparsity combine(const Sparsity& y, bool f0x_is_zero, bool function0_is_zero,
                             std::vector<unsigned char>& mapping) const;
@@ -495,7 +606,9 @@ namespace casadi {
     /// @}
 
     /// @{
-    /** \brief Union of two sparsity patterns */
+    /** \brief Union of two sparsity patterns
+
+        \identifier{cm} */
 #ifndef SWIG
     Sparsity unite(const Sparsity& y, std::vector<unsigned char>& mapping) const;
 #endif // SWIG
@@ -505,10 +618,13 @@ namespace casadi {
 
     /// @{
     /** \brief Intersection of two sparsity patterns
+
         Returns the new sparsity pattern as well as a mapping with the same length as the
         number of non-zero elements
         The value is 1 if the non-zero comes from the first (i.e. this) object, 2 if it is from
-        the second and 3 (i.e. 1 | 2) if from both */
+        the second and 3 (i.e. 1 | 2) if from both
+
+        \identifier{cn} */
 #ifndef SWIG
     Sparsity intersect(const Sparsity& y,
                        std::vector<unsigned char>& mapping) const;
@@ -520,23 +636,42 @@ namespace casadi {
     /// Is subset?
     bool is_subset(const Sparsity& rhs) const;
 
+    /** \brief Propagates subset according to sparsity cast
+     * 
+     * Assumption: 'this' is a subset of X.
+     * 
+     * Example:
+     * 
+     * X = [ * . . .; . * . .; . . * .; . . . *]
+     * Y = [* *; . . ; * *]
+     * x = [ * . . .; . . . .; . . * .; . . . *]
+     * returns [* *; . . ; . *]
+     *
+
+        \identifier{246} */
+    Sparsity sparsity_cast_mod(const Sparsity& X, const Sparsity& Y) const;
+
     /// Take the inverse of a sparsity pattern; flip zeros and non-zeros
     Sparsity pattern_inverse() const;
 
 #ifndef SWIG
     /** \brief Propagate sparsity using 0-1 logic through a matrix product,
+
      * no memory allocation: <tt>z = mul(x, y)</tt> with work vector
      * Forward mode.
-     */
+
+        \identifier{co} */
     static void mul_sparsityF(const bvec_t* x, const Sparsity& x_sp,
                               const bvec_t* y, const Sparsity& y_sp,
                               bvec_t* z, const Sparsity& z_sp,
                               bvec_t* w);
 
     /** \brief Propagate sparsity using 0-1 logic through a matrix product,
+
      * no memory allocation: <tt>z = mul(x, y)</tt> with work vector
      * Reverse mode.
-     */
+
+        \identifier{cp} */
     static void mul_sparsityR(bvec_t* x, const Sparsity& x_sp,
                               bvec_t* y, const Sparsity& y_sp,
                               bvec_t* z, const Sparsity& z_sp,
@@ -544,7 +679,9 @@ namespace casadi {
 
     /// \cond INTERNAL
     /// @{
-    /** \brief Accessed by SparsityInterface */
+    /** \brief Accessed by SparsityInterface
+
+        \identifier{cq} */
     static Sparsity horzcat(const std::vector<Sparsity> & sp);
     static Sparsity vertcat(const std::vector<Sparsity> & sp);
     static Sparsity blockcat(const std::vector< std::vector< Sparsity > > &v);
@@ -561,6 +698,7 @@ namespace casadi {
     static Sparsity mac(const Sparsity& x, const Sparsity& y, const Sparsity& z) { return z;}
     static Sparsity reshape(const Sparsity& x, casadi_int nrow, casadi_int ncol);
     static Sparsity reshape(const Sparsity& x, const Sparsity& sp);
+    static Sparsity sparsity_cast(const Sparsity& x, const Sparsity& sp);
     static casadi_int sprank(const Sparsity& x);
     static casadi_int norm_0_mul(const Sparsity& x, const Sparsity& A);
     static Sparsity kron(const Sparsity& a, const Sparsity& b);
@@ -572,6 +710,7 @@ namespace casadi {
 #endif //SWIG
 
     /** \brief Enlarge matrix
+
         Make the matrix larger by inserting empty rows and columns, keeping the existing non-zeros
 
         For the matrices A to B
@@ -582,25 +721,36 @@ namespace casadi {
         A=enlarge(m, n, ii, jj) makes sure that
 
         B[jj, ii] == A
-    */
+
+        \identifier{cr} */
     void enlarge(casadi_int nrow, casadi_int ncol,
                   const std::vector<casadi_int>& rr,
                   const std::vector<casadi_int>& cc, bool ind1=false);
 
-    /** \brief Enlarge the matrix along the first dimension (i.e. insert rows) */
+    /** \brief Enlarge the matrix along the first dimension (i.e. insert rows)
+
+        \identifier{cs} */
     void enlargeRows(casadi_int nrow, const std::vector<casadi_int>& rr, bool ind1=false);
 
-    /** \brief Enlarge the matrix along the second dimension (i.e. insert columns) */
+    /** \brief Enlarge the matrix along the second dimension (i.e. insert columns)
+
+        \identifier{ct} */
     void enlargeColumns(casadi_int ncol, const std::vector<casadi_int>& cc, bool ind1=false);
 
-    /** \brief Make a patten dense */
+    /** \brief Make a patten dense
+
+        \identifier{cu} */
     Sparsity makeDense(std::vector<casadi_int>& SWIG_OUTPUT(mapping)) const;
 
-    /** \brief Erase rows and/or columns of a matrix */
+    /** \brief Erase rows and/or columns of a matrix
+
+        \identifier{cv} */
     std::vector<casadi_int> erase(const std::vector<casadi_int>& rr,
                                   const std::vector<casadi_int>& cc, bool ind1=false);
 
-    /** \brief Erase elements of a matrix */
+    /** \brief Erase elements of a matrix
+
+        \identifier{cw} */
     std::vector<casadi_int> erase(const std::vector<casadi_int>& rr, bool ind1=false);
 
     /// Append another sparsity patten vertically (NOTE: only efficient if vector)
@@ -615,44 +765,109 @@ namespace casadi {
     /// Is dense?
     bool is_dense() const;
 
-    /** \brief  Check if the pattern is a row vector (i.e. size1()==1) */
+    /** \brief  Check if the pattern is a row vector (i.e. size1()==1)
+
+        \identifier{cx} */
     bool is_row() const;
 
-    /** \brief  Check if the pattern is a column vector (i.e. size2()==1) */
+    /** \brief  Check if the pattern is a column vector (i.e. size2()==1)
+
+        \identifier{cy} */
     bool is_column() const;
 
-    /** \brief  Check if the pattern is a row or column vector */
+    /** \brief  Check if the pattern is a row or column vector
+
+        \identifier{cz} */
     bool is_vector() const;
 
-    /// Is diagonal?
+    /** \brief Is diagonal?
+
+        \identifier{247} */
     bool is_diag() const;
 
-    /// Is square?
+    /** \brief Is square?
+
+        \identifier{248} */
     bool is_square() const;
 
-    /// Is symmetric?
+    /** \brief Is symmetric?
+
+        \identifier{249} */
     bool is_symmetric() const;
 
-    /// Is upper triangular?
-    bool is_triu() const;
+    /** \brief Is upper triangular?
+
+        \identifier{24a} */
+    bool is_triu(bool strictly = false) const;
+
+    /** \brief Is lower triangular?
 
-    /// Is lower triangular?
-    bool is_tril() const;
+        \identifier{24b} */
+    bool is_tril(bool strictly = false) const;
 
-    /// Check whether the sparsity-pattern indicates structural singularity
+    /** \brief Check whether the sparsity-pattern indicates structural singularity
+
+        \identifier{24c} */
     bool is_singular() const;
 
+    /** \brief Is this a permutation matrix?
+     * 
+     * A Matrix P is permutation matrix if right multiplication with a dense vector v leads to 
+     * a vector with the same elements, but permuted.
+     * 
+     * Implies square
+     * 
+     * Equivalent to is_orthonormal(false)
+
+        \identifier{24d} */
+    bool is_permutation() const;
+
+    /** \brief Is this a selection matrix?
+     * 
+     * A Matrix S is selection matrix if right multiplication with a dense vector leads to 
+     * a vector with a subset of the elements of the original vector
+     * 
+     * \param[in] allow_empty Allow the resultant vector to have structural zeros
+     * 
+     * Equivalent to is_orthonormal_rows(allow_empty)
+
+        \identifier{24e} */
+    bool is_selection(bool allow_empty=false) const;
+
+    /** \brief Are both rows and columns orthonormal ?
+     * 
+     * \param[in] allow_empty Disregard empty rows and columns in the analysis
+
+        \identifier{24f} */
+    bool is_orthonormal(bool allow_empty=false) const;
+
+    /** \brief Are the rows of the pattern orthonormal ?
+     * 
+     * \param[in] allow_empty Disregard empty rows in the analysis
+
+        \identifier{24g} */
+    bool is_orthonormal_rows(bool allow_empty=false) const;
+
+    /** \brief Are the columns of the pattern orthonormal ?
+     * 
+     * \param[in] allow_empty Disregard empty columns in the analysis
+
+        \identifier{24h} */
+    bool is_orthonormal_columns(bool allow_empty=false) const;
+
     /** \brief Do the rows appear sequentially on each column
     *
     * \param[in] strictly if true, then do not allow multiple entries
-    */
+
+        \identifier{d0} */
     bool rowsSequential(bool strictly=true) const;
 
     /** \brief Remove duplicate entries
     *
     * The same indices will be removed from the \a mapping vector,
     * which must have the same length as the number of nonzeros
-    */
+
+        \identifier{d1} */
     void removeDuplicates(std::vector<casadi_int>& SWIG_INOUT(mapping));
 
 #ifndef SWIG
@@ -673,6 +888,7 @@ namespace casadi {
 #endif //SWIG
 
     /** \brief Calculate the elimination tree
+
         See Direct Methods for Sparse Linear Systems by Davis (2006).
         If the parameter ata is false, the algorithm is equivalent to MATLAB's etree(A), except that
         the indices are zero-based. If ata is true, the algorithm is equivalent to MATLAB's
@@ -681,37 +897,45 @@ namespace casadi {
         The implementation is a modified version of cs_etree in CSparse
         Copyright(c) Timothy A. Davis, 2006-2009
         Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d2} */
     std::vector<casadi_int> etree(bool ata=false) const;
 
     /** \brief Symbolic LDL factorization
+
         Returns the sparsity pattern of L^T
 
         The implementation is a modified version of LDL
         Copyright(c) Timothy A. Davis, 2005-2013
         Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d3} */
     Sparsity ldl(std::vector<casadi_int>& SWIG_OUTPUT(p), bool amd=true) const;
 
     /** \brief Symbolic QR factorization
+
         Returns the sparsity pattern of V (compact representation of Q) and R
         as well as vectors needed for the numerical factorization and solution.
         The implementation is a modified version of CSparse
         Copyright(c) Timothy A. Davis, 2006-2009
         Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d4} */
     void qr_sparse(Sparsity& SWIG_OUTPUT(V), Sparsity& SWIG_OUTPUT(R),
                    std::vector<casadi_int>& SWIG_OUTPUT(prinv),
                    std::vector<casadi_int>& SWIG_OUTPUT(pc), bool amd=true) const;
 
     /** \brief Depth-first search on the adjacency graph of the sparsity
+
         See Direct Methods for Sparse Linear Systems by Davis (2006).
-    */
+
+        \identifier{d5} */
     casadi_int dfs(casadi_int j, casadi_int top, std::vector<casadi_int>& SWIG_INOUT(xi),
             std::vector<casadi_int>& SWIG_INOUT(pstack),
             const std::vector<casadi_int>& pinv, std::vector<bool>& SWIG_INOUT(marked)) const;
 
     /** \brief Find the strongly connected components of the bigraph defined by the sparsity pattern
+
         of a square matrix
 
         See Direct Methods for Sparse Linear Systems by Davis (2006).
@@ -731,11 +955,13 @@ namespace casadi {
         The implementation is a modified version of cs_scc in CSparse
         Copyright(c) Timothy A. Davis, 2006-2009
         Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d6} */
     casadi_int scc(std::vector<casadi_int>& SWIG_OUTPUT(index),
             std::vector<casadi_int>& SWIG_OUTPUT(offset)) const;
 
     /** \brief Calculate the block triangular form (BTF)
+
         See Direct Methods for Sparse Linear Systems by Davis (2006).
 
         The function computes the Dulmage-Mendelsohn decomposition, which allows you to reorder
@@ -753,7 +979,8 @@ namespace casadi {
         The implementation is a modified version of cs_dmperm in CSparse
         Copyright(c) Timothy A. Davis, 2006-2009
         Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d7} */
     casadi_int btf(std::vector<casadi_int>& SWIG_OUTPUT(rowperm),
             std::vector<casadi_int>& SWIG_OUTPUT(colperm),
             std::vector<casadi_int>& SWIG_OUTPUT(rowblock),
@@ -762,6 +989,7 @@ namespace casadi {
             std::vector<casadi_int>& SWIG_OUTPUT(coarse_colblock)) const;
 
     /** \brief Approximate minimal degree preordering
+
       Fill-reducing ordering applied to the sparsity pattern of a linear system
       prior to factorization.
       The system must be symmetric, for an unsymmetric matrix A, first form the square
@@ -770,16 +998,19 @@ namespace casadi {
       The implementation is a modified version of cs_amd in CSparse
       Copyright(c) Timothy A. Davis, 2006-2009
       Licensed as a derivative work under the GNU LGPL
-    */
+
+        \identifier{d8} */
     std::vector<casadi_int> amd() const;
 
 #ifndef SWIG
     /** \brief Propagate sparsity through a linear solve
-     */
+
+        \identifier{d9} */
     void spsolve(bvec_t* X, const bvec_t* B, bool tr) const;
 #endif // SWIG
 
     /** \brief Get the location of all non-zero elements as they would appear in a Dense matrix
+
         A : DenseMatrix  4 x 3
         B : SparseMatrix 4 x 3 , 5 structural non-zeros
 
@@ -787,7 +1018,8 @@ namespace casadi {
         A[k] will contain the elements of A that are non-zero in B
 
         Inverse of `nonzeros`.
-    */
+
+        \identifier{da} */
     std::vector<casadi_int> find(bool ind1=SWIG_IND1) const;
 
 #ifndef SWIG
@@ -796,11 +1028,15 @@ namespace casadi {
 #endif // SWIG
 
     /** \brief Perform a unidirectional coloring: A greedy distance-2 coloring algorithm
-        (Algorithm 3.1 in A. H. GEBREMEDHIN, F. MANNE, A. POTHEN) */
+
+        (Algorithm 3.1 in A. H. GEBREMEDHIN, F. MANNE, A. POTHEN)
+
+        \identifier{db} */
     Sparsity uni_coloring(const Sparsity& AT=Sparsity(),
                           casadi_int cutoff = std::numeric_limits<casadi_int>::max()) const;
 
     /** \brief Perform a star coloring of a symmetric matrix:
+
         A greedy distance-2 coloring algorithm
         Algorithm 4.1 in
           What Color Is Your Jacobian? Graph Coloring for Computing Derivatives
@@ -808,11 +1044,13 @@ namespace casadi {
           SIAM Rev., 47(4), 629–705 (2006)
 
         Ordering options: None (0), largest first (1)
-    */
+
+        \identifier{dc} */
     Sparsity star_coloring(casadi_int ordering = 1,
                             casadi_int cutoff = std::numeric_limits<casadi_int>::max()) const;
 
     /** \brief Perform a star coloring of a symmetric matrix:
+
         A new greedy distance-2 coloring algorithm
         Algorithm 4.1 in
           NEW ACYCLIC AND STAR COLORING ALGORITHMS WITH APPLICATION TO COMPUTING HESSIANS
@@ -820,18 +1058,23 @@ namespace casadi {
           SIAM J. SCI. COMPUT. Vol. 29, No. 3, pp. 1042–1072 (2007)
 
         Ordering options: None (0), largest first (1)
-    */
+
+        \identifier{dd} */
     Sparsity star_coloring2(casadi_int ordering = 1,
                             casadi_int cutoff = std::numeric_limits<casadi_int>::max()) const;
 
-    /** \brief Order the columns by decreasing degree */
+    /** \brief Order the columns by decreasing degree
+
+        \identifier{de} */
     std::vector<casadi_int> largest_first() const;
 
     /** \brief Permute rows and/or columns
+
         Multiply the sparsity with a permutation matrix from the left and/or from the right
         P * A * trans(P), A * trans(P) or A * trans(P) with P defined by an index vector
         containing the row for each col. As an alternative, P can be transposed (inverted).
-    */
+
+        \identifier{df} */
     Sparsity pmult(const std::vector<casadi_int>& p,
                     bool permute_rows=true, bool permute_columns=true,
                     bool invert_permutation=false) const;
@@ -840,24 +1083,30 @@ namespace casadi {
     std::string dim(bool with_nz=false) const;
 
     /** \brief Dimension string as a postfix to a name
+
       Rules:
       1. Dense and scalar: ""
       2. 0-by-0: "[]"
       3. Dense column vector: "[5]"
       4. Dense matrix: "[5x10]"
       5. Otherwise: "[5x10,3nz]"
-    */
+
+        \identifier{dg} */
     std::string postfix_dim() const;
 
     /// Describe the nonzero location k as a string
     std::string repr_el(casadi_int k) const;
 
     /** \brief Print a textual representation of sparsity
-     */
+
+        \identifier{dh} */
     void spy(std::ostream &stream=casadi::uout()) const;
 
     /** \brief Generate a script for Matlab or Octave which visualizes
-     * the sparsity using the spy command  */
+
+     * the sparsity using the spy command
+
+        \identifier{di} */
     void spy_matlab(const std::string& mfile) const;
 
     /** \brief Export matrix in specific language
@@ -870,7 +1119,8 @@ namespace casadi {
      *   as_matrix: Matlab does not have a sparsity object. (default: false)
     *               With this option true, a numeric matrix will be constructed
      * \endverbatim
-     */
+
+        \identifier{dj} */
     void export_code(const std::string& lang, std::ostream &stream=casadi::uout(),
        const Dict& options=Dict()) const;
 
@@ -884,24 +1134,35 @@ namespace casadi {
     static bool test_cast(const SharedObjectInternal* ptr);
 
     /** \brief Get KKT system sparsity
+
      * [H + I1, J'; J, I2] where I1 and I2 are optional
-     */
+
+        \identifier{dk} */
     static Sparsity kkt(const Sparsity& H, const Sparsity& J,
                         bool with_x_diag=true, bool with_lam_g_diag=true);
 
 #ifndef SWIG
     /** \brief Assign the nonzero entries of one sparsity pattern to the nonzero
-     * entries of another sparsity pattern */
+
+     * entries of another sparsity pattern
+
+        \identifier{dl} */
     template<typename T>
     void set(T* data, const T* val_data, const Sparsity& val_sp) const;
 
     /** \brief Add the nonzero entries of one sparsity pattern to the nonzero entries
-     * of another sparsity pattern */
+
+     * of another sparsity pattern
+
+        \identifier{dm} */
     template<typename T>
     void add(T* data, const T* val_data, const Sparsity& val_sp) const;
 
     /** \brief Bitwise or of the nonzero entries of one sparsity pattern and the nonzero
-     * entries of another sparsity pattern */
+
+     * entries of another sparsity pattern
+
+        \identifier{dn} */
     template<typename T>
     void bor(T* data, const T* val_data, const Sparsity& val_sp) const;
 
@@ -921,27 +1182,37 @@ namespace casadi {
 #endif //SWIG
   };
 
-  /** \brief Hash value of an integer */
+  /** \brief Hash value of an integer
+
+      \identifier{do} */
   template<typename T>
   inline size_t hash_value(T v) { return size_t(v);}
 
-  /** \brief Generate a hash value incrementally (function taken from boost) */
+  /** \brief Generate a hash value incrementally (function taken from boost)
+
+      \identifier{dp} */
   template<typename T>
   inline void hash_combine(std::size_t& seed, T v) {
     seed ^= hash_value(v) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
   }
 
-  /** \brief Generate a hash value incrementally, array */
+  /** \brief Generate a hash value incrementally, array
+
+      \identifier{dq} */
   inline void hash_combine(std::size_t& seed, const casadi_int* v, std::size_t sz) {
     for (casadi_int i=0; i<sz; ++i) hash_combine(seed, v[i]);
   }
 
-  /** \brief Generate a hash value incrementally (function taken from boost) */
+  /** \brief Generate a hash value incrementally (function taken from boost)
+
+      \identifier{dr} */
   inline void hash_combine(std::size_t& seed, const std::vector<casadi_int>& v) {
     hash_combine(seed, get_ptr(v), v.size());
   }
 
-  /** \brief Hash a sparsity pattern */
+  /** \brief Hash a sparsity pattern
+
+      \identifier{ds} */
   CASADI_EXPORT std::size_t hash_sparsity(casadi_int nrow, casadi_int ncol,
                                           const std::vector<casadi_int>& colind,
                                           const std::vector<casadi_int>& row);