[REFACTOR] Replace Matrix and Vector Data Structures with Dataclass

[CupapiOT]

Summary

The current Vectors, Matrix, and MatrixDict data structures are clunky to use, difficult to attach metadata to, and don't support OOP paradigms very well. This limits scalability, especially when more matrix transformations options exist in the future.

The Number type (float | int) is also unnecessary and will be replaced with a simple float.

---

Context

This structure was set up a long time ago and wasn't designed with future features (like projections, eigenvectors, or serialization) in mind. As a result:

• The animation logic is messier than it should be.
• Repeated code for unpacking coordinates and colors is fragile.
• It will be difficult to scale or maintain as features expand.

Also, not having a clear structure makes it harder to debug or extend, especially as the UI and animation logic grow more complex.

---

Implementation Plan

Refactor the existing Vectors, Matrix, and MatrixDict types into proper @dataclasses or similar objects with clearly named fields.

The new structure should be easier to work with and help clean up the logic for creating figures, applying matrices, and possibly future use-cases such as showcasing eigenvectors and projections.

Steps:

1. Create a new Vector class or dataclass that holds .coords and .color, same with Matrix and MatrixDict. Matrix and MatrixDict in particular should have methods that clean up code. For example, it's currently common to do np.array(list(stored_matrices.values())[-1]), which could be abstracted to stored_matrices.get_np_matrix(index=-1).
2. Update all functions that use the old structure to use the new class (e.g., in create_figure, apply_matrix_to_vectors, add_matrix, etc).
3. Verify everything still runs; calculations and logic, animations, etc. No unit tests currently exist, so rely on manual testing.
4. Make sure future use-cases like projections, labels, or animation states are actually easier to support with this structure.

---

Impact

Benefits

• Improves readability and developer experience
• Easier to scale with future vector and matrix properties
• Removes confusing and clunky data-access (like vectors[name][0][1] and list(stored_matrices.keys())), and replaces them with more readable code.

Challenges

• May introduce temporary bugs due to the tight coupling between logic and data format
• All downstream functions must be updated to use the new structure

Mitigation

• Tightly scope changes
• Refactor incrementally

[CupapiOT]

After evaluating the refactor to use a dataclass for vectors, it became clear that the change introduced more complexity than necessary for the project. Here's why the refactor wasn't worth pursuing:

• No Real Benefit: The original tuple structure ([(x, y), color]) was already simple, works well with NumPy, and was easy to understand.
• Unnecessary Object-Oriented Design: The project doesn't need vector-specific methods, and utility functions are more appropriate for the operations we need.
• Serialization Overhead: Using a dataclass would have added unnecessary serialization/deserialization logic and potential bugs.
• Preserving Simplicity: The existing structure works fine, and the refactor would only complicate things without significant gain.

In the end, I decided to keep the original design, with clearer documentation for the tuple structure.

This issue may be reopened again at some point, but probably not with a dataclass structure.

[CupapiOT]

Coming back to this after resolving #34, it's clearer that there needs to be a way to add meta-data and other functions to clean up the logic of the code. I've edited the issue to reflect these new requirements.