Metadata-Version: 2.4
Name: ma1522-linear-algebra
Version: 1.2.0
Summary: Python scripts for NUS MA1522 Linear Algebra for Computing
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0.2
Requires-Dist: sympy>=1.13.3
Requires-Dist: sympy-latex-parser>=1.9.0

# linear-algebra

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ma1522-linear-algebra)](https://pypi.org/project/ma1522-linear-algebra/)
[![PyPI - Version](https://img.shields.io/pypi/v/ma1522-linear-algebra)](https://pypi.org/project/ma1522-linear-algebra/)
[![GitHub License](https://img.shields.io/github/license/yeeshin504/linear-algebra)](https://github.com/YeeShin504/linear-algebra/blob/master/LICENSE.txt)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/ma1522-linear-algebra)](https://pypistats.org/packages/ma1522-linear-algebra)
[![codecov](https://codecov.io/github/YeeShin504/linear-algebra/graph/badge.svg?token=2TJ7RSIDOI)](https://codecov.io/github/YeeShin504/linear-algebra)

## About

This project builds on SymPy's Matrix class and is designed for students taking NUS MA1522 Linear Algebra for Computing. It has implementations of most of the algorithms taught during the course (as of Sem 1 AY24/25).


### Key Features

1. Import matrices directly from $\rm\LaTeX$ or string/list representations.
2. Step-by-step workings for most algorithms (including LU Factorisation, SVD, QR, diagonalization, and more).
3. Enhanced symbolic matrix class with:
    - Matrix creation from lists, $\rm\LaTeX$, or random values.
    - Matrix decompositions: REF, RREF, LU, QR, SVD, diagonalization.
    - Vector space operations: orthogonalization, projections, basis manipulation, subspace intersection, and more.
    - Eigenvalue/eigenvector computations and characteristic polynomials.
    - Custom pretty-printing and $\rm\LaTeX$ formatting, including augmented matrices.
    - Support for both exact symbolic and numerical computations.
    - Utilities for displaying results in Jupyter/IPython or standard Python.
4. Follows MA1522 syllabus conventions for linear algebra and provides detailed, educational output.
5. Rich set of custom types for representing decompositions, solutions, and factorizations.

## Installation and Usage

### Installation

#### Prerequisites

This project is best supported in a Jupyter Notebook environment with Python 3.10+. You can download Python from [here](https://www.python.org/downloads/).

Alternatively, you can use a minimal GUI developed by [@MarcusMa06-code](https://github.com/MarcusMa06-code) [here](https://github.com/MarcusMa06-code/linear-algebra/tree/gui-development).

#### Install Dependencies

It is recommended to use a virtual environment for managing dependencies.

1. Create a virtual environment:
    ```bash
    python -m venv venv
    ```

2. Activate the virtual environment:
    - On Windows:
      ```bash
      venv\Scripts\activate
      ```
    - On macOS/Linux:
      ```bash
      source venv/bin/activate
      ```

3. Install the library:
    ```bash
    pip install ma1522-linear-algebra
    ```
   It is recommended to use a Jupyter Notebook environment to run the code.
   ```bash
   pip install notebook
   ```

### Usage

Create a Jupyter Notebook `test.ipynb`. Within the notebook, run the following code.
```python
from ma1522 import *

# Create Matrix objects
A = Matrix([[1, 2, 3],
            [4, 5, 5],
            [7, 8, 9]])

b = Matrix([[1], 
            [2], 
            [3]])

# Join matrices along the columns via `row_join`. 
augmented_matrix = A.aug_line().row_join(b)

# `aug_line` adds a visual line that can be seen using `display`
display(augmented_matrix)

# Solution to the matrix equation Ax = b can be found using `solve`.
A.solve(rhs=b)

# Alternatively, the full steps with LU Factorisation can be found using `ref` with the appropriate options.
augmented_matrix.ref(verbosity=2)
```

Documentation of more functions can be found [here](https://yeeshin504.github.io/linear-algebra/api/symbolic).

More usage examples can be found under [tutorials](https://yeeshin504.github.io/linear-algebra/tutorials/tutorial).

Live demonstration of the library can be found [here](https://yeeshin504.github.io/linear-algebra/live/demo).

### Offline Documentation

An offline version of the documentation is available for download from the [Releases](https://github.com/YeeShin504/linear-algebra/releases) page. This is useful for exam when you may not have internet access.

To use the offline documentation:

1. Download `linear-algebra-docs-offline.zip` from the latest release
2. Extract the ZIP to a folder
3. Open `index.html` in your browser

A quick reference guide is also available as a function in the library:
```python
from ma1522 import sympy_commands
sympy_commands()
```

#### Building from Source

If the offline ZIP is not available in the releases, you can build it yourself:

1. Clone the repository:
   ```bash
   git clone https://github.com/YeeShin504/linear-algebra.git
   cd linear-algebra
   ```

2. Install documentation dependencies:
   ```bash
   pip install mkdocs-material mkdocs-jupyter
   ```

3. Build the documentation:
   ```bash
   mkdocs build
   ```

4. The documentation will be in the `site/` folder. Open `site/index.html` in your browser.


### Credits

I would like to thank [@DenseLance](https://github.com/DenseLance) for his contributions.
