Linear Algebra (linalg)
=======================

.. currentmodule:: numpycore.linalg

The ``linalg`` module provides linear algebra functions for arrays.

Example
-------

.. code-block:: python

   import numpycore as np

   # Matrix operations
   A = np.array([[1, 2], [3, 4]])
   B = np.array([[5, 6], [7, 8]])

   # Matrix multiplication
   C = A @ B  # or np.matmul(A, B)

   # Matrix inverse
   A_inv = np.linalg.inv(A)

   # Eigenvalues and eigenvectors
   eigenvalues, eigenvectors = np.linalg.eig(A)

   # Solve linear system Ax = b
   b = np.array([1, 2])
   x = np.linalg.solve(A, b)

Matrix Decomposition
--------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - cholesky(a)
     - Cholesky decomposition
     - 
   * - qr(a)
     - QR decomposition
     - 
   * - svd(a)
     - Singular value decomposition
     - 
   * - eig(a)
     - Eigenvalues and eigenvectors
     - 
   * - eigh(a)
     - Eigenvalues for symmetric/Hermitian matrix
     - :ref:`View <example-linalg-decomposition-eigh-0>`
   * - eigvals(a)
     - Eigenvalues only
     - 
   * - eigvalsh(a)
     - Eigenvalues for symmetric/Hermitian
     - :ref:`View <example-linalg-decomposition-eigvalsh-1>`

Matrix Operations
-----------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - inv(a)
     - Matrix inverse
     - 
   * - pinv(a)
     - Pseudo-inverse (Moore-Penrose)
     - 
   * - det(a)
     - Matrix determinant
     - 
   * - matrix_rank(a)
     - Matrix rank
     - 
   * - trace(a)
     - Sum of diagonal elements
     - :ref:`View <example-linalg-operations-trace-2>`
   * - norm(x)
     - Matrix or vector norm
     - 
   * - cond(x)
     - Condition number
     - 
   * - matrix_power(a, n)
     - Matrix raised to power n
     - 

Solving Linear Systems
----------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - solve(a, b)
     - Solve linear system ax = b
     - 
   * - lstsq(a, b)
     - Least-squares solution
     - 
   * - tensorsolve(a, b)
     - Solve tensor equation
     - 

Products
--------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - dot(a, b)
     - Dot product
     - 
   * - vdot(a, b)
     - Vector dot product
     - 
   * - inner(a, b)
     - Inner product
     - 
   * - outer(a, b)
     - Outer product
     - 
   * - matmul(a, b)
     - Matrix multiplication
     - 
   * - tensordot(a, b)
     - Tensor dot product
     - 
   * - einsum(subscripts, ...)
     - Einstein summation
     - 
   * - cross(a, b)
     - Cross product
     - 
   * - kron(a, b)
     - Kronecker product
     - 

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

The following examples are extracted from the test suite.

.. _example-linalg-decomposition-eigh-0:

.. dropdown:: eigh (test_phase1_linalg.py:26)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 16
      :emphasize-lines: 11

              print(f"  NumpyCore result: {nc_result}")
              sys.exit(1)
          print(f"[OK] {test_name}: PASSED")
      
      def test_eigh_symmetric_2x2():
          """Test eigh on 2x2 symmetric matrix"""
          A_np = test_bind.np.array([[1.0, 2.0], [2.0, 1.0]])
          A_nc = test_bind.numpycore.array([[1.0, 2.0], [2.0, 1.0]])
      
          w_np, v_np = test_bind.np.linalg.eigh(A_np)
          w_nc, v_nc = test_bind.numpycore.linalg.eigh(A_nc)
      
          # Eigenvalues must match exactly
          assert_arrays_equal(w_np, w_nc, "eigh_eigenvalues_2x2")
      
          # Eigenvectors may differ by sign, compare absolute values
          assert_arrays_equal(test_bind.np.abs(v_np), test_bind.np.abs(v_nc),
                             "eigh_eigenvectors_2x2")
      
      def test_eigh_symmetric_3x3():
          """Test eigh on 3x3 symmetric matrix"""

.. _example-linalg-decomposition-eigvalsh-1:

.. dropdown:: eigvalsh (test_phase1_linalg.py:57)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 47
      :emphasize-lines: 11

          assert_arrays_equal(w_np, w_nc, "eigh_eigenvalues_3x3")
          assert_arrays_equal(test_bind.np.abs(v_np), test_bind.np.abs(v_nc),
                             "eigh_eigenvectors_3x3")
      
      def test_eigvalsh_symmetric_2x2():
          """Test eigvalsh on 2x2 symmetric matrix"""
          A_np = test_bind.np.array([[1.0, 2.0], [2.0, 1.0]])
          A_nc = test_bind.numpycore.array([[1.0, 2.0], [2.0, 1.0]])
      
          w_np = test_bind.np.linalg.eigvalsh(A_np)
          w_nc = test_bind.numpycore.linalg.eigvalsh(A_nc)
      
          assert_arrays_equal(w_np, w_nc, "eigvalsh_2x2")
      
      def test_eigvalsh_symmetric_100x100():
          """Test eigvalsh on larger 100x100 symmetric matrix"""
          # Create symmetric positive definite matrix
          test_bind.np.random.seed(42)  # For reproducibility
          A_np = test_bind.np.random.randn(100, 100)
          A_np = A_np + A_np.T  # Make symmetric
          A_nc = test_bind.numpycore.array(A_np.tolist())

.. _example-linalg-operations-trace-2:

.. dropdown:: trace (test_reduction_functions.py:292)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 282
      :emphasize-lines: 11

      
      
      def test_trace():
          """Test np.linalg.trace() for diagonal sum"""
          print("Testing np.linalg.trace()...")
      
          # Test 1: Basic 2D array
          nc_arr = test_bind.numpycore.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype='int32')
          np_arr = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype='int32')
      
          nc_trace = test_bind.numpycore.linalg.trace(nc_arr)
          np_trace = np.trace(np_arr)
          assert nc_trace == np_trace, f"trace() mismatch: {nc_trace} != {np_trace}"
      
          # Test 2: With offset
          nc_off1 = test_bind.numpycore.linalg.trace(nc_arr, offset=1)
          np_off1 = np.trace(np_arr, offset=1)
          assert nc_off1 == np_off1, f"trace() offset=1 mismatch: {nc_off1} != {np_off1}"
      
          nc_off_neg = test_bind.numpycore.linalg.trace(nc_arr, offset=-1)
          np_off_neg = np.trace(np_arr, offset=-1)