PyCMatrix 1.0.0__py3-none-any.whl

pycmatrix-1.0.0.dist-info/METADATA

@@ -0,0 +1,862 @@
+Metadata-Version: 2.4
+Name: PyCMatrix
+Version: 1.0.0
+Summary: A Python matrix manipulation library
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyMat
+
+A modular Python library for creating, manipulating, and performing mathematical operations on matrices.
+
+**Version:** `1.0.0`
+**Status:** Stable
+
+---
+
+## Features
+
+PyMat provides a collection of tools for working with matrices:
+
+* Matrix creation and constructors
+* Matrix indexing and iteration
+* Matrix addition and subtraction
+* Matrix multiplication
+* Scalar multiplication and division
+* Element-wise multiplication
+* Matrix powers
+* Mathematical functions
+* Aggregation and reduction operations
+* Matrix norms
+* Row and column manipulation
+* Matrix reshaping and flattening
+* Transpose
+* Minors and cofactors
+* Determinant
+* Adjoint and inverse
+* Matrix rank
+* Linear-system solving
+* Matrix property checks
+* Approximate equality
+* Random matrix generation
+* Deep copying
+* Input validation
+
+---
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/Github-Shashank/PyMat.git
+cd PyMat
+```
+
+Create and activate a virtual environment if desired:
+
+```bash
+python -m venv .venv
+```
+
+On Windows:
+
+```bash
+.venv\Scripts\activate
+```
+
+On Linux/macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+Install PyMat:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from matrix import Matrix
+
+A = Matrix([
+    [1, 2],
+    [3, 4]
+])
+
+B = Matrix([
+    [5, 6],
+    [7, 8]
+])
+
+print(A)
+print(B)
+```
+
+### Matrix arithmetic
+
+```python
+print(A + B)
+print(A - B)
+print(A * B)
+```
+
+`*` performs matrix multiplication when both operands are matrices.
+
+Scalar multiplication is also supported:
+
+```python
+print(A * 2)
+print(2 * A)
+```
+
+Scalar division:
+
+```python
+print(A / 2)
+```
+
+Negation:
+
+```python
+print(-A)
+```
+
+---
+
+## Indexing
+
+Matrix elements are accessed using:
+
+```python
+A[row, column]
+```
+
+For example:
+
+```python
+print(A[0, 1])
+```
+
+Assigning an element:
+
+```python
+A[0, 1] = 10
+```
+
+---
+
+## Matrix Properties
+
+```python
+print(A.order)
+print(A.shape)
+```
+
+Both return:
+
+```text
+(rows, columns)
+```
+
+Matrix classification properties include:
+
+```python
+A.isSqrMatrix
+A.isDiagMatrix
+A.isRowMatrix
+A.isColMatrix
+A.isSclrMatrix
+A.isIdntMatrix
+A.isZeroMatrix
+A.isSymtMatrix
+A.isSkewSymtMatrix
+```
+
+Invertibility-related properties:
+
+```python
+A.isInvertible
+A.isSingularMatrix
+A.isNonSingularMatrix
+```
+
+---
+
+## Constructors
+
+PyMat provides several class methods for creating matrices.
+
+### Ones
+
+```python
+Matrix.one(3, 3)
+```
+
+Creates a matrix filled with `1`.
+
+### Zeros
+
+```python
+Matrix.zero(3, 3)
+```
+
+Creates a matrix filled with `0`.
+
+### Identity
+
+```python
+Matrix.identity(3)
+```
+
+Creates a `3 × 3` identity matrix.
+
+### Constant
+
+```python
+Matrix.constant(2, 3, 5)
+```
+
+Creates a `2 × 3` matrix filled with `5`.
+
+### Diagonal
+
+```python
+Matrix.diagonal([1, 2, 3])
+```
+
+Creates a diagonal matrix.
+
+### Random
+
+```python
+Matrix.random(3, 3)
+```
+
+Creates a random matrix using PyMat's existing random constructor.
+
+### Uniform random
+
+```python
+Matrix.random_uniform(3, 3, low=-1, high=1)
+```
+
+Creates a matrix whose elements are uniformly distributed between `low` and `high`.
+
+### Seed
+
+```python
+Matrix.seed(42)
+```
+
+Sets the random generator seed used by PyMat's uniform random constructor.
+
+---
+
+## Matrix Transformation
+
+### Transpose
+
+```python
+A.transpose
+```
+
+Returns the transpose of `A`.
+
+### Flatten
+
+```python
+A.flatten()
+```
+
+Converts the matrix into a single-row matrix.
+
+For example:
+
+```text
+[1 2]
+[3 4]
+```
+
+becomes:
+
+```text
+[1 2 3 4]
+```
+
+### Reshape
+
+```python
+A.reshape(4, 1)
+```
+
+Changes the matrix dimensions while preserving the element count.
+
+The number of elements must remain unchanged.
+
+---
+
+## Row and Column Manipulation
+
+Rows and columns can be inserted, deleted, retrieved, or swapped.
+
+```python
+A.insertRow(...)
+A.insertCol(...)
+A.delRow(...)
+A.delCol(...)
+A.getRow(...)
+A.getCol(...)
+```
+
+Rows:
+
+```python
+A.swapRows(0, 1)
+```
+
+Columns:
+
+```python
+A.swapCols(0, 1)
+```
+
+By default, swapping returns a new matrix.
+
+In-place swapping is also supported:
+
+```python
+A.swapRows(0, 1, inplace=True)
+A.swapCols(0, 1, inplace=True)
+```
+
+---
+
+## Element-wise Operations
+
+Matrix multiplication and element-wise multiplication are different operations.
+
+Element-wise multiplication:
+
+```python
+A.elementwise_multiply(B)
+```
+
+Each corresponding pair of elements is multiplied:
+
+```text
+[a b]    [x y]       [a*x b*y]
+[c d] ×  [z w]   =   [c*z d*w]
+```
+
+The matrices must have the same dimensions.
+
+---
+
+## Applying Functions
+
+PyMat provides a general `apply()` operation:
+
+```python
+A.apply(function)
+```
+
+Example:
+
+```python
+A.apply(lambda x: x * x)
+```
+
+This applies the function independently to every matrix element.
+
+---
+
+## Mathematical Functions
+
+PyMat provides element-wise mathematical functions:
+
+```python
+A.exp()
+A.log()
+A.sqrt()
+
+A.abs()
+
+A.sin()
+A.cos()
+A.tan()
+
+A.sinh()
+A.cosh()
+A.tanh()
+```
+
+For example:
+
+```python
+A.sqrt()
+```
+
+returns a matrix containing the square root of every element.
+
+---
+
+## Reductions
+
+PyMat provides operations that reduce the entire matrix to a single value.
+
+### Sum
+
+```python
+A.sum()
+```
+
+### Mean
+
+```python
+A.mean()
+```
+
+### Minimum
+
+```python
+A.min()
+```
+
+### Maximum
+
+```python
+A.max()
+```
+
+### Product
+
+```python
+A.prod()
+```
+
+---
+
+## Norm
+
+The Frobenius norm of a matrix can be calculated using:
+
+```python
+A.norm()
+```
+
+The squared norm is available through:
+
+```python
+A.norm_squared()
+```
+
+For a matrix
+
+```text
+[a b]
+[c d]
+```
+
+the squared Frobenius norm is:
+
+```text
+a² + b² + c² + d²
+```
+
+and the norm is:
+
+```text
+√(a² + b² + c² + d²)
+```
+
+---
+
+## Matrix Operations
+
+### Minor
+
+```python
+A.minor(row, column)
+```
+
+Returns the minor associated with an element.
+
+### Cofactor
+
+```python
+A.cofactor(row, column)
+```
+
+Returns the corresponding cofactor.
+
+### Matrix of Minors
+
+```python
+A.matrixOfMinors
+```
+
+### Matrix of Cofactors
+
+```python
+A.matrixOfCofactors
+```
+
+### Determinant
+
+```python
+A.determinant
+```
+
+### Trace
+
+```python
+A.trace
+```
+
+### Adjoint
+
+```python
+A.adjoint
+```
+
+### Inverse
+
+```python
+A.inverse
+```
+
+The inverse exists only for an invertible square matrix.
+
+---
+
+## Rank
+
+The rank of a matrix can be calculated using:
+
+```python
+A.rank()
+```
+
+Example:
+
+```python
+A = Matrix([
+    [1, 2],
+    [2, 4]
+])
+
+print(A.rank())
+```
+
+The rank is:
+
+```text
+1
+```
+
+---
+
+## Solving Linear Systems
+
+PyMat can solve a system of linear equations represented as:
+
+```text
+AX = B
+```
+
+using:
+
+```python
+A.solve(B)
+```
+
+Example:
+
+```python
+A = Matrix([
+    [2, 1],
+    [1, 3]
+])
+
+B = Matrix([
+    [5],
+    [6]
+])
+
+X = A.solve(B)
+
+print(X)
+```
+
+The coefficient matrix must be square and the right-hand side must have compatible dimensions.
+
+---
+
+## Approximate Equality
+
+Exact equality:
+
+```python
+A == B
+```
+
+checks whether corresponding elements are exactly equal.
+
+For floating-point calculations, approximate equality is available:
+
+```python
+A.isApproxEqual(B)
+```
+
+A custom tolerance can be supplied:
+
+```python
+A.isApproxEqual(B, tolerance=1e-6)
+```
+
+This is useful when numerical calculations produce small floating-point differences.
+
+---
+
+## Copying
+
+To create an independent copy of a matrix:
+
+```python
+B = A.copy()
+```
+
+The copy is independent of the original matrix.
+
+Changing `B` does not modify `A`.
+
+---
+
+## Iteration
+
+A matrix can be iterated over:
+
+```python
+for row in A:
+    print(row)
+```
+
+The matrix's traversal functionality is also available through:
+
+```python
+A.traverse
+```
+
+---
+
+## Matrix Power
+
+Positive integer powers are supported:
+
+```python
+A ** 2
+```
+
+which performs:
+
+```text
+A × A
+```
+
+For example:
+
+```python
+A ** 3
+```
+
+calculates:
+
+```text
+A × A × A
+```
+
+---
+
+## API Overview
+
+### Operators
+
+| Operator     | Operation             |
+| ------------ | --------------------- |
+| `A + B`      | Matrix addition       |
+| `A - B`      | Matrix subtraction    |
+| `A * B`      | Matrix multiplication |
+| `A * scalar` | Scalar multiplication |
+| `scalar * A` | Scalar multiplication |
+| `A / scalar` | Scalar division       |
+| `-A`         | Matrix negation       |
+| `A ** n`     | Matrix power          |
+| `A == B`     | Exact equality        |
+
+### Core Properties
+
+| Property      | Purpose            |
+| ------------- | ------------------ |
+| `order`       | Matrix dimensions  |
+| `shape`       | Alias for `order`  |
+| `transpose`   | Transposed matrix  |
+| `traverse`    | Matrix traversal   |
+| `determinant` | Matrix determinant |
+| `trace`       | Matrix trace       |
+| `adjoint`     | Matrix adjoint     |
+| `inverse`     | Matrix inverse     |
+
+### Numerical Methods
+
+| Method                   | Purpose                           |
+| ------------------------ | --------------------------------- |
+| `elementwise_multiply()` | Element-wise multiplication       |
+| `apply()`                | Apply a function to every element |
+| `exp()`                  | Element-wise exponential          |
+| `log()`                  | Element-wise logarithm            |
+| `sqrt()`                 | Element-wise square root          |
+| `abs()`                  | Element-wise absolute value       |
+| `sin()`                  | Element-wise sine                 |
+| `cos()`                  | Element-wise cosine               |
+| `tan()`                  | Element-wise tangent              |
+| `sinh()`                 | Element-wise hyperbolic sine      |
+| `cosh()`                 | Element-wise hyperbolic cosine    |
+| `tanh()`                 | Element-wise hyperbolic tangent   |
+| `sum()`                  | Sum of all elements               |
+| `mean()`                 | Mean of all elements              |
+| `min()`                  | Minimum element                   |
+| `max()`                  | Maximum element                   |
+| `prod()`                 | Product of all elements           |
+| `norm_squared()`         | Squared Frobenius norm            |
+| `norm()`                 | Frobenius norm                    |
+| `rank()`                 | Matrix rank                       |
+| `solve()`                | Solve a linear system             |
+
+---
+
+## Validation
+
+PyMat provides validation helpers:
+
+```python
+A.isValidIndex(...)
+A.isEqualOrder(B)
+A.isMultiplicable(B)
+A.isApproxEqual(B)
+```
+
+These can be used to validate matrix dimensions, indices, and numerical equality.
+
+---
+
+## Testing
+
+PyMat includes a test suite covering the library's functionality.
+
+Run the tests with:
+
+```bash
+python -m unittest discover
+```
+
+The current v1 implementation has:
+
+```text
+100 tests
+100 passed
+0 failed
+```
+
+---
+
+## Project Structure
+
+```text
+PyMat/
+├── matrix/
+│   ├── __init__.py
+│   ├── arithmetic.py
+│   ├── bool.py
+│   ├── constructors.py
+│   ├── exceptions.py
+│   ├── manipulation.py
+│   ├── matrix.py
+│   ├── operations.py
+│   └── validators.py
+│
+├── tests/
+│   └── test_matrix.py
+│
+├── docs/
+│   ├── api_reference.md
+│   ├── arithmetic.md
+│   ├── constructors.md
+│   ├── manipulation.md
+│   ├── operations.md
+│   └── properties.md
+│
+├── README.md
+├── LICENSE
+├── .gitignore
+└── pyproject.toml
+```
+
+---
+
+## Design
+
+PyMat is organized into separate modules so that different areas of matrix functionality remain independent.
+
+```text
+matrix.py
+   │
+   ├── arithmetic.py
+   ├── constructors.py
+   ├── manipulation.py
+   ├── operations.py
+   ├── validators.py
+   └── bool.py
+```
+
+The `Matrix` class provides the public interface while the individual modules contain the underlying functionality.
+
+This structure makes PyMat easier to maintain, test, and extend.
+
+---
+
+## Documentation
+
+Detailed documentation is available in the `docs/` directory:
+
+* [API Reference](docs/api_reference.md)
+* [Arithmetic](docs/arithmetic.md)
+* [Constructors](docs/constructors.md)
+* [Manipulation](docs/manipulation.md)
+* [Operations](docs/operations.md)
+* [Properties](docs/properties.md)
+
+---
+
+## Version
+
+Current release:
+
+```text
+PyMat 1.0.0
+```
+
+PyMat 1.0 represents the first stable version of the library's public API.
+
+---
+
+## License
+
+PyMat is distributed under the license included in the `LICENSE` file.