Pattern.h

Go to the documentation of this file.

// ========================================================================= //
// This file is part of MyraMath, copyright (c) 2014-2019 by Ryan A Chilton  //
// and distributed by MyraCore, LLC. See LICENSE.txt for license terms.      //
// ========================================================================= //

#ifndef MYRAMATH_SPARSE_PATTERN_H
#define MYRAMATH_SPARSE_PATTERN_H

#include <myramath/MYRAMATH_EXPORT.h>

#include <myramath/sparse/PatternRange.h>

#include <vector>
#include <iosfwd>
#include <utility>

namespace myra {

// Forward declarations.
class InputStream;
class OutputStream;
class intCRange;
class Pattern;
class PatternRange;
class PatternIterator;
class PatternBuilder;
template<class Number> class SparseMatrix;
template<class T> class Array1;
template<class T> class Array2;

namespace detail {

// Some of these functions can be implemented more efficiently with access to internal 
// data structures, they're forward declared here so they can be granted friendship later.
class permute_wrapper;
class horzcat_wrapper;
class vertcat_wrapper;
class bothcat_wrapper;
class diagcat_wrapper;
class transpose_wrapper;
class multiply_wrapper;
class flip_wrapper;
Pattern stencil1(int I);
Pattern stencil2(int I, int J);
Pattern stencil3(int I, int J, int K);

} // namespace detail

class MYRAMATH_EXPORT Pattern
  {
  public:

    typedef std::pair<PatternRange, PatternRange> Pair;

    // ------------------------------------ Construction, serialization, value semantics.

    Pattern();

    Pattern(const Pattern& that);

    void swap(Pattern& that);

#ifdef MYRAMATH_ENABLE_CPP11
    Pattern(Pattern&& that);
#endif

    Pattern& operator = (Pattern that);

    explicit Pattern(const PatternRange& that);

    explicit Pattern(InputStream& in);

    void write(OutputStream& out) const;

    const Pattern& add_const() const;

   ~Pattern();

    // ------------------------------------ Size queries.

    std::pair<int,int> size() const;

    int n_nonzeros() const;

    int n_nonzeros(int j) const;

    bool test(int i, int j) const;

    std::vector<int> pattern(int j) const;

    // ------------------------------------ Iterating.
    
    PatternIterator begin() const;
    PatternIterator end  () const;
    
    PatternIterator begin(int j) const;
    PatternIterator end  (int j) const;

    // ------------------------------------ General slicing.

    PatternRange range() const;
    
    operator PatternRange() const;
    
    PatternRange window(int i0, int i1, int j0, int j1) const;

    Array2<PatternRange> windows(const intCRange& i, const intCRange& j) const;

    Pattern& operator = (const PatternRange& that);

    // ------------------------------------ Row slicing.

    PatternRange row(int i) const;

    PatternRange rows(int i0, int i1) const;

    Array1<PatternRange> rows(const intCRange& i) const;
  
    PatternRange top(int i) const;

    PatternRange cut_top(int i) const;
    
    Pair split_top(int i) const;
    
    PatternRange bottom(int i) const;
    
    PatternRange cut_bottom(int i) const;
    
    Pair split_bottom(int i) const;

    // ------------------------------------ Column slicing.
    
    PatternRange column(int j) const;
    
    PatternRange columns(int j0, int j1) const;

    Array1<PatternRange> columns(const intCRange& j) const;
    
    PatternRange left(int j) const;
    
    PatternRange cut_left(int j) const;
    
    Pair split_left(int j) const;
    
    PatternRange right(int j) const;
    
    PatternRange cut_right(int j) const;
    
    Pair split_right(int j) const;

    // ------------------------------------ Static generators.

    static Pattern identity(int IJ);

    static Pattern random(int I, int J, int N);

    static Pattern fill(const intCRange& i, const intCRange& j);

    static Pattern swap(int I, int J, std::vector<int>& Ao, std::vector<int>& Ai);

    void debug(std::ostream& out) const;

  private:
  
    // Returns offset to *this A(i,j). Returns -1 if (i,j) is a structural zero. Throws if (i,j) are out of (I,J) bounds.
    int offset(int i, int j) const;

    // Stores size.
    int I;
    int J;

    // Stores offsets for each column of A.
    std::vector<int> Ao;

    // Holds row indices (i). The sorted i-pattern of column A(:,j) is given by Ai[Ao[j]:Ao[j+1]]
    std::vector<int> Ai;

    // Nonmember friend functions that are granted access to internal data structures.
    friend class PatternBuilder;
    friend class detail::permute_wrapper;
    friend class detail::horzcat_wrapper;
    friend class detail::vertcat_wrapper;
    friend class detail::bothcat_wrapper;
    friend class detail::diagcat_wrapper;
    friend class detail::transpose_wrapper;
    friend class detail::multiply_wrapper;
    friend class detail::flip_wrapper;
    friend Pattern detail::stencil1(int I);
    friend Pattern detail::stencil2(int I, int J);
    friend Pattern detail::stencil3(int I, int J, int K);
    template<class Number> friend class SparseMatrix;
  };

} // namespace

#endif