COOMatrix
=========

.. cpp:class:: numpy::COOMatrix

   numpy C++ class.

Example
-------

.. code-block:: cpp

   #include <numpy/np_ndarray.h>
   using namespace numpy;

   // Use COOMatrix
   COOMatrix obj;
   // ... operations ...

Constructors
------------

.. list-table::
   :widths: 55 25 20
   :header-rows: 1

   * - Signature
     - Location
     - Example
   * - ``COOMatrix(size_trows, size_tcols)``
     - NP_SPARSE_COO.H:67
     - 
   * - ``COOMatrix(size_trows, size_tcols, std::vector<T>&&values, std::vector<sparse_index_t>&&row_indices, std::vector<sparse_index_t>&&col_indices)``
     - NP_SPARSE_COO.H:73
     - 

Operators
---------

.. list-table::
   :widths: 40 25 15 20
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``T operator()(size_ti, size_tj)``
     - T
     - NP_SPARSE_COO.H:232
     - 

Construction
------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``COOMatrix from_dense(const NDArray<T>&dense, Ttol = T{1e-10})``
     - COOMatrix
     - NP_SPARSE_COO.H:96
     - :ref:`View <example-coomatrix-from_dense-0>`

Array Creation
--------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``COOMatrix diagonal(const std::vector<T>&diag)``
     - COOMatrix
     - NP_SPARSE_COO.H:148
     - :ref:`View <example-coomatrix-diagonal-1>`
   * - ``COOMatrix identity(size_tn)``
     - COOMatrix
     - NP_SPARSE_COO.H:129
     - :ref:`View <example-coomatrix-identity-2>`

Shape Manipulation
------------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``COOMatrix<T> transpose()``
     - COOMatrix<T>
     - NP_SPARSE_COO.H:376
     - :ref:`View <example-coomatrix-transpose-3>`

Statistics
----------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void sum_duplicates()``
     - void
     - NP_SPARSE_COO.H:319
     - 

Sorting
-------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void sort_indices()``
     - void
     - NP_SPARSE_COO.H:284
     - 

Math Operations
---------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void add_entries(const std::vector<sparse_index_t>&rows, const std::vector<sparse_index_t>&cols, const std::vector<T>&values)``
     - void
     - NP_SPARSE_COO.H:187
     - 
   * - ``void add_entry(sparse_index_trow, sparse_index_tcol, Tvalue)``
     - void
     - NP_SPARSE_COO.H:173
     - :ref:`View <example-coomatrix-add_entry-4>`

I/O
---

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``CSRMatrix<T> to_csr()``
     - CSRMatrix<T>
     - NP_SPARSE_COO.H:222
     - :ref:`View <example-coomatrix-to_csr-5>`

Type Checking
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool is_square()``
     - bool
     - NP_SPARSE_COO.H:262
     - 

Other Methods
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool check_format()``
     - bool
     - NP_SPARSE_COO.H:401
     - :ref:`View <example-coomatrix-check_format-6>`
   * - ``COOMatrix<T> clone()``
     - COOMatrix<T>
     - NP_SPARSE_COO.H:387
     - :ref:`View <example-coomatrix-clone-7>`
   * - ``const std::vector<sparse_index_t>& col_indices()``
     - const std::vector<sparse_index_t>&
     - NP_SPARSE_COO.H:270
     - 
   * - ``std::vector<sparse_index_t>& col_indices()``
     - std::vector<sparse_index_t>&
     - NP_SPARSE_COO.H:274
     - 
   * - ``size_t cols()``
     - size_t
     - NP_SPARSE_COO.H:254
     - :ref:`View <example-coomatrix-cols-8>`
   * - ``double density()``
     - double
     - NP_SPARSE_COO.H:257
     - 
   * - ``size_t nnz()``
     - size_t
     - NP_SPARSE_COO.H:255
     - :ref:`View <example-coomatrix-nnz-9>`
   * - ``void print_entries(std::ostream &os = std::cout, size_tmax_entries = 20)``
     - void
     - NP_SPARSE_COO.H:432
     - 
   * - ``void print_structure(std::ostream &os = std::cout)``
     - void
     - NP_SPARSE_COO.H:422
     - 
   * - ``void remove_zeros(Ttol = T{0})``
     - void
     - NP_SPARSE_COO.H:355
     - 
   * - ``const std::vector<sparse_index_t>& row_indices()``
     - const std::vector<sparse_index_t>&
     - NP_SPARSE_COO.H:269
     - 
   * - ``std::vector<sparse_index_t>& row_indices()``
     - std::vector<sparse_index_t>&
     - NP_SPARSE_COO.H:273
     - 
   * - ``size_t rows()``
     - size_t
     - NP_SPARSE_COO.H:253
     - :ref:`View <example-coomatrix-rows-10>`
   * - ``const std::vector<T>& values()``
     - const std::vector<T>&
     - NP_SPARSE_COO.H:268
     - :ref:`View <example-coomatrix-values-11>`
   * - ``std::vector<T>& values()``
     - std::vector<T>&
     - NP_SPARSE_COO.H:272
     - :ref:`View <example-coomatrix-values-12>`


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-coomatrix-from_dense-0:

.. dropdown:: from_dense (np_test_3_all.cpp:19939)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 19929
      :emphasize-lines: 11

            std::cout << "========= CSR Matrix - basic functionality =======================";
      
            numpy::NDArray<double> dense({ 4, 4 });
            dense.setElementAt({ 0, 0 }, 1.0);
            dense.setElementAt({ 0, 3 }, 2.0);
            dense.setElementAt({ 1, 1 }, 3.0);
            dense.setElementAt({ 2, 2 }, 4.0);
            dense.setElementAt({ 3, 0 }, 5.0);
            dense.setElementAt({ 3, 3 }, 6.0);
      
            auto csr = numpy::sparse::CSRMatrix<double>::from_dense(dense);
      
            if (csr.rows() != 4 || csr.cols() != 4 || csr.nnz() != 6) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : Incorrect matrix dimensions";
              throw std::runtime_error("np_test_sparse_csr_basic failed: dimension mismatch");
            }
      
            if (!csr.check_format()) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : CSR format validation failed";
              throw std::runtime_error("np_test_sparse_csr_basic failed: invalid format");
            }

.. _example-coomatrix-diagonal-1:

.. dropdown:: diagonal (np_test_2_all.cpp:11408)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 11398
      :emphasize-lines: 11

          void np_test_linalg_missing_diagonal() {
            std::cout << "========= diagonal: extract diagonal from matrix =======================";
      
            numpy::NDArray<double> mat({ 3, 4 });
            for (size_t i = 0; i < 3; ++i) {
              for (size_t j = 0; j < 4; ++j) {
                mat.setElementAt({ i, j }, static_cast<double>(i * 4 + j));
              }
            }
      
            auto diag = numpy::diagonal(mat);
            if (diag.getShape()[0] != 3) {
              std::cout << "  [FAIL] : diagonal shape incorrect";
              throw std::runtime_error("diagonal test failed: wrong shape");
            }
      
            // Check diagonal values (0, 5, 10)
            if (std::abs(diag.getElementAt({ 0 }) - 0.0) > 1e-10 ||
              std::abs(diag.getElementAt({ 1 }) - 5.0) > 1e-10 ||
              std::abs(diag.getElementAt({ 2 }) - 10.0) > 1e-10) {
              std::cout << "  [FAIL] : diagonal values incorrect";

.. _example-coomatrix-identity-2:

.. dropdown:: identity (np_test_1_all.cpp:24002)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 23992
      :emphasize-lines: 11

                throw std::runtime_error(description);
            }
            if (!((eye_offset.getShape() == std::vector<size_t>{3, 4}))) {
                std::string description = std::string("testArrayCreationSignatures():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !((eye_offset.getShape() == std::vector<size_t>{3, 4}))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            // std::cout << "[OK] eye function with optional parameters works correctly\n";
      
            // Test identity
            auto identity_result = identity<int>(4);
            if (!((identity_result.getShape() == std::vector<size_t>{4, 4}))) {
                std::string description = std::string("testArrayCreationSignatures():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !((identity_result.getShape() == std::vector<size_t>{4, 4}))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            // std::cout << "[OK] identity function has correct signature\n";
      
            // Test diag with different use cases
            auto vector1d = createInt32Array({ 3 }, 5);
            auto matrix2d = createInt32Array({ 3, 3 }, 0);

.. _example-coomatrix-transpose-3:

.. dropdown:: transpose (np_test_2_all.cpp:4973)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 4963
      :emphasize-lines: 11

          }
      
          /**
           * Test matrix properties and methods
           */
          void testMatrixProperties() {
            std::cout << "========= testMatrixProperties =======================";
      
            // Test transpose
            numpy::Matrix<double> m("1 2 3; 4 5 6");
            auto mt = m.transpose();
            assert_test(mt.rows() == 3, "Transpose rows");
            assert_test(mt.cols() == 2, "Transpose cols");
            assert_test(std::abs(mt(0, 1) - 4.0) < 1e-10, "Transpose element");
            assert_test(std::abs(mt(2, 0) - 3.0) < 1e-10, "Transpose element");
      
            // Test trace for square matrix
            numpy::Matrix<double> square("1 2; 3 4");
            double tr = square.trace();
            assert_test(std::abs(tr - 5.0) < 1e-10, "Matrix trace");
      

.. _example-coomatrix-add_entry-4:

.. dropdown:: add_entry (np_test_3_all.cpp:19991)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 19981
      :emphasize-lines: 11

          }
      
          // ============================================================================
          // COO MATRIX TESTS
          // ============================================================================
      
          void np_test_sparse_coo_basic() {
            std::cout << "========= COO Matrix - basic functionality =======================";
      
            numpy::sparse::COOMatrix<double> coo(4, 4);
            coo.add_entry(0, 0, 1.0);
            coo.add_entry(0, 3, 2.0);
            coo.add_entry(1, 1, 3.0);
            coo.add_entry(2, 2, 4.0);
            coo.add_entry(3, 0, 5.0);
            coo.add_entry(3, 3, 6.0);
      
            if (coo.rows() != 4 || coo.cols() != 4 || coo.nnz() != 6) {
              std::cout << "  [FAIL] : in np_test_sparse_coo_basic() : Incorrect matrix dimensions";
              throw std::runtime_error("np_test_sparse_coo_basic failed");
            }

.. _example-coomatrix-to_csr-5:

.. dropdown:: to_csr (np_test_3_all.cpp:20025)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 20015
      :emphasize-lines: 11

          void np_test_sparse_conversion() {
            std::cout << "========= format conversion - COO to CSR =======================";
      
            numpy::sparse::COOMatrix<double> coo(5, 5);
            coo.add_entry(0, 0, 1.0);
            coo.add_entry(1, 1, 2.0);
            coo.add_entry(2, 2, 3.0);
            coo.add_entry(3, 3, 4.0);
            coo.add_entry(4, 4, 5.0);
      
            auto csr = coo.to_csr();
      
            if (csr.rows() != 5 || csr.cols() != 5 || csr.nnz() != 5) {
              std::cout << "  [FAIL] : in np_test_sparse_conversion() : Conversion produced wrong dimensions";
              throw std::runtime_error("np_test_sparse_conversion failed");
            }
      
            if (!csr.check_format()) {
              std::cout << "  [FAIL] : in np_test_sparse_conversion() : Converted CSR format invalid";
              throw std::runtime_error("np_test_sparse_conversion failed");
            }

.. _example-coomatrix-check_format-6:

.. dropdown:: check_format (np_test_3_all.cpp:19946)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 19936
      :emphasize-lines: 11

            dense.setElementAt({ 3, 0 }, 5.0);
            dense.setElementAt({ 3, 3 }, 6.0);
      
            auto csr = numpy::sparse::CSRMatrix<double>::from_dense(dense);
      
            if (csr.rows() != 4 || csr.cols() != 4 || csr.nnz() != 6) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : Incorrect matrix dimensions";
              throw std::runtime_error("np_test_sparse_csr_basic failed: dimension mismatch");
            }
      
            if (!csr.check_format()) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : CSR format validation failed";
              throw std::runtime_error("np_test_sparse_csr_basic failed: invalid format");
            }
      
            auto reconstructed = csr.to_dense();
            for (size_t i = 0; i < 4; ++i) {
              for (size_t j = 0; j < 4; ++j) {
                if (std::abs(dense.getElementAt({ i, j }) - reconstructed.getElementAt({ i, j })) > 1e-12) {
                  std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : Roundtrip conversion mismatch";
                  throw std::runtime_error("np_test_sparse_csr_basic failed");

.. _example-coomatrix-clone-7:

.. dropdown:: clone (np_test_1_all.cpp:24942)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 24932
      :emphasize-lines: 11

            }
      
            // Test reproducibility
            numpy::random::PCG64DXSM rng2(11111);
            if (rng2.next_uint64() != val) {
              std::cout << "  [FAIL] : in np_test_bitgen_pcg64dxsm() : not reproducible";
              throw std::runtime_error("np_test_bitgen_pcg64dxsm failed");
            }
      
            // Test clone
            auto cloned = rng.clone();
            if (cloned->name() != "PCG64DXSM") {
              std::cout << "  [FAIL] : in np_test_bitgen_pcg64dxsm() : clone name incorrect";
              throw std::runtime_error("np_test_bitgen_pcg64dxsm failed");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // PHILOX TESTS

.. _example-coomatrix-cols-8:

.. dropdown:: cols (np_test_2_all.cpp:4911)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 4901
      :emphasize-lines: 11

      
          /**
           * Test basic matrix construction and properties
           */
          void testMatrixBasics() {
            std::cout << "========= testMatrixBasics =======================";
      
            // Test construction from dimensions
            numpy::Matrix<double> m1(3, 3);
            assert_test(m1.rows() == 3, "Matrix rows");
            assert_test(m1.cols() == 3, "Matrix cols");
            assert_test(m1.isSquare(), "Matrix is square");
      
            // Test construction from 2D vector
            std::vector<std::vector<int>> data = { {1, 2, 3}, {4, 5, 6} };
            numpy::Matrix<int> m2(data);
            assert_test(m2.rows() == 2, "Matrix from vector rows");
            assert_test(m2.cols() == 3, "Matrix from vector cols");
            assert_test(m2(0, 0) == 1, "Matrix element access");
            assert_test(m2(1, 2) == 6, "Matrix element access");
      

.. _example-coomatrix-nnz-9:

.. dropdown:: nnz (np_test_3_all.cpp:19941)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 19931
      :emphasize-lines: 11

            numpy::NDArray<double> dense({ 4, 4 });
            dense.setElementAt({ 0, 0 }, 1.0);
            dense.setElementAt({ 0, 3 }, 2.0);
            dense.setElementAt({ 1, 1 }, 3.0);
            dense.setElementAt({ 2, 2 }, 4.0);
            dense.setElementAt({ 3, 0 }, 5.0);
            dense.setElementAt({ 3, 3 }, 6.0);
      
            auto csr = numpy::sparse::CSRMatrix<double>::from_dense(dense);
      
            if (csr.rows() != 4 || csr.cols() != 4 || csr.nnz() != 6) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : Incorrect matrix dimensions";
              throw std::runtime_error("np_test_sparse_csr_basic failed: dimension mismatch");
            }
      
            if (!csr.check_format()) {
              std::cout << "  [FAIL] : in np_test_sparse_csr_basic() : CSR format validation failed";
              throw std::runtime_error("np_test_sparse_csr_basic failed: invalid format");
            }
      
            auto reconstructed = csr.to_dense();

.. _example-coomatrix-rows-10:

.. dropdown:: rows (np_test_2_all.cpp:4910)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 4900
      :emphasize-lines: 11

        namespace test_matrix {
      
          /**
           * Test basic matrix construction and properties
           */
          void testMatrixBasics() {
            std::cout << "========= testMatrixBasics =======================";
      
            // Test construction from dimensions
            numpy::Matrix<double> m1(3, 3);
            assert_test(m1.rows() == 3, "Matrix rows");
            assert_test(m1.cols() == 3, "Matrix cols");
            assert_test(m1.isSquare(), "Matrix is square");
      
            // Test construction from 2D vector
            std::vector<std::vector<int>> data = { {1, 2, 3}, {4, 5, 6} };
            numpy::Matrix<int> m2(data);
            assert_test(m2.rows() == 2, "Matrix from vector rows");
            assert_test(m2.cols() == 3, "Matrix from vector cols");
            assert_test(m2(0, 0) == 1, "Matrix element access");
            assert_test(m2(1, 2) == 6, "Matrix element access");

.. _example-coomatrix-values-11:

.. dropdown:: values (np_test_1_all.cpp:15133)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 15123
      :emphasize-lines: 11

              std::cout << " -> tests passed" << std::endl;
            }
            else {
              std::cout << "[FAIL] Where function failed" << std::endl;
              errors++;
            }
      
            // Test 8: Clip function
            std::cout << "========= test_clip_function =======================" ;
      
            numpy::NDArray<double> values({ 5 });
            values.setElementAt({ 0 }, -2.0);
            values.setElementAt({ 1 }, -1.0);
            values.setElementAt({ 2 }, 0.5);
            values.setElementAt({ 3 }, 2.0);
            values.setElementAt({ 4 }, 5.0);
            double min_val = -1.0;
            double max_val = 3.0;
      
            auto clip_result = numpy::clip(values, min_val, max_val);
      

.. _example-coomatrix-values-12:

.. dropdown:: values (np_test_1_all.cpp:15133)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 15123
      :emphasize-lines: 11

              std::cout << " -> tests passed" << std::endl;
            }
            else {
              std::cout << "[FAIL] Where function failed" << std::endl;
              errors++;
            }
      
            // Test 8: Clip function
            std::cout << "========= test_clip_function =======================" ;
      
            numpy::NDArray<double> values({ 5 });
            values.setElementAt({ 0 }, -2.0);
            values.setElementAt({ 1 }, -1.0);
            values.setElementAt({ 2 }, 0.5);
            values.setElementAt({ 3 }, 2.0);
            values.setElementAt({ 4 }, 5.0);
            double min_val = -1.0;
            double max_val = 3.0;
      
            auto clip_result = numpy::clip(values, min_val, max_val);