# tcl03-hcmut/251-ca-assignment architecture

> Architecture diagram of the GitHub repository tcl03-hcmut/251-ca-assignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tcl03-hcmut/251-ca-assignment
- Repository: https://github.com/tcl03-hcmut/251-ca-assignment

## Overview

##### Project type and purpose
- This is an educational lab assignment for “Filtering and Prediction Signal With Wiener Filter,” implemented primarily in MIPS Assembly.
- Its goal is to read a noisy signal from input.txt, apply a Wiener filter (and supporting routines) in MIPS, and produce an output that closely matches desired.txt.
- A complementary Python folder contains reference implementations and test harnesses for comparison and validation.

##### File structure
Top-level:
- Mars4_5.jar        – MARS MIPS simulator used to run .asm files
- README.md          – project description
- _HK251_*.pdf       – assignment specifications
- *.asm              – various MIPS modules (filter, correlation, IO, float routines)
- solve_linear.c     – helper C code (optional)
- Python/            – reference implementations and test scripts in Python
- Test_case-20251029/– additional test vectors

Python directory:
- main.py, main_nonumpy.py, main_non_causal.py – reference filter implementations
- compare.py         – compares MIPS output to desired outputs
- gaussian_noise.py  – adds synthetic noise
- input*.txt, desired.txt – test signals

##### README for additional insights
- Confirms the use of a MIPS Wiener filter to reduce noise.
- Indicates that input.txt and desired.txt drive the comparison.

a. Main components:
- Test Data Generator (Python scripts + Test_case folder)
- MIPS Simulator Layer (Mars4_5.jar)
- MIPS Assembly Modules:
– readinput.asm, write_output.asm (I/O)
– apply_filter.asm, cross_auto_correlation.asm
– solve_linear.asm, gaussian_elim_test.asm
– ftoa.asm, directFloat.asm (float routines)
- Reference Model (Python implementations)
- Comparator (compare.py)
- Data Stores (input.txt, desired.txt, output.txt, wiener_coeffs.txt, etc.)

b. Relationships and data flow:
1. Test Data Generator → produces input.txt and desired.txt
2. MIPS Simulator loads main.asm (which links submodules)
3. Simulator reads input.txt → invokes filter routines → writes output.txt
4. Reference Model processes the same input files in Python → produces Python_output.txt
5. Comparator (compare.py) reads output.txt, Python_output.txt, desired.txt → produces error metrics

c. Architectural patterns / design principles:
- Modular assembly: each algorithmic step (I/O, filtering, correlation, linear solve) lives in its own .asm file
- Separation of concerns: MIPS code focuses on signal processing, Python code on test harness and validation
- Data-driven flow: all inputs/outputs are plain text files to simplify integration

d. Key technologies / frameworks:
- MIPS Assembly (SPIM/MARS simulator)
- Python 3 scripts (no external deps beyond standard library)
- Makefile (in Python/) for automating Python tests

##### Key points to capture
- All major .asm modules and their roles
- The MARS simulator as the execution environment
- The Python reference path for validation
- File-based data flow between components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Data Generation
    subgraph "Test Data Generator" 
        direction TB
        GaussianNoise["gaussian_noise.py"]:::python
        TestCases["Test_case-20251029/"]:::data
    end
    GaussianNoise -->|"generate input.txt"| InputFile["input.txt"]:::data
    TestCases -->|"provide input.txt and desired.txt"| InputFile
    TestCases --> InputDesired["desired.txt"]:::data

    %% MIPS Simulation Environment
    Simulator["Mars4_5.jar"]:::tool
    Simulator -->|"loads"| MainAsm["main.asm"]:::asm
    click GaussianNoise "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Python/gaussian_noise.py"
    click TestCases "https://github.com/tcl03-hcmut/251-ca-assignment/tree/main/Test_case-20251029/"
    click Simulator "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Mars4_5.jar"
    click MainAsm "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/main.asm"

    %% Assembly Modules
    subgraph "MIPS Assembly Modules"
        direction TB
        ReadInput["readinput.asm"]:::asm
        AltInput["input.asm"]:::asm
        WriteOutput["write_output.asm"]:::asm
        Filter["apply_filter.asm"]:::asm
        Correlation["cross_auto_correlation.asm"]:::asm
        GaussElim["gaussian_elim_test.asm"]:::asm
        CorrSolver["solve_linear – correlation.asm"]:::asm
        GenericSolver["solve_linear.asm"]:::asm
        Ftoa["ftoa.asm"]:::asm
        DirectFloat["directFloat.asm"]:::asm
    end
    MainAsm --> ReadInput
    MainAsm --> AltInput
    MainAsm --> WriteOutput
    MainAsm --> Filter
    MainAsm --> Correlation
    MainAsm --> GaussElim
    MainAsm --> CorrSolver
    MainAsm --> GenericSolver
    MainAsm --> Ftoa
    MainAsm --> DirectFloat

    click ReadInput "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/readinput.asm"
    click AltInput "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/input.asm"
    click WriteOutput "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/write_output.asm"
    click Filter "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/apply_filter.asm"
    click Correlation "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/cross_auto_correlation.asm"
    click GaussElim "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/gaussian_elim_test.asm"
    click CorrSolver "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/solve_linear – correlation.asm"
    click GenericSolver "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/solve_linear.asm"
    click Ftoa "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/ftoa.asm"
    click DirectFloat "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/directFloat.asm"

    %% Data flow for MIPS output
    InputFile -->|"read by filter"| Simulator
    DesiredRef["desired.txt"]:::data
    InputDesired --> DesiredRef
    Simulator -->|"writes output.txt"| OutputFile["output.txt"]:::data

    %% Reference Model and Comparator
    subgraph "Reference Model & Validation"
        direction TB
        RM1["main.py"]:::python
        RM2["main_nonumpy.py"]:::python
        RM3["main_non_causal.py"]:::python
        Comparator["compare.py"]:::python
    end
    click RM1 "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Python/main.py"
    click RM2 "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Python/main_nonumpy.py"
    click RM3 "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Python/main_non_causal.py"
    click Comparator "https://github.com/tcl03-hcmut/251-ca-assignment/blob/main/Python/compare.py"

    %% Python reference data stores
    PythonInput["Python/input.txt"]:::data
    PythonDesired["Python/desired.txt"]:::data
    PythonOutput["Python/wiener_output.txt"]:::data
    PythonCoeffs["Python/wiener_coeffs.txt"]:::data

    %% Reference flow
    RM1 -->|"processes"| PythonInput
    RM2 --> PythonInput
    RM3 --> PythonInput
    RM1 --> PythonOutput
    RM2 --> PythonOutput
    RM3 --> PythonOutput
    RM1 --> PythonCoeffs
    RM2 --> PythonCoeffs
    RM3 --> PythonCoeffs

    %% Comparison
    InputFile --> Comparator
    OutputFile --> Comparator
    PythonOutput --> Comparator
    DesiredRef --> Comparator
    Comparator --> Metrics["Error Metrics"]:::data

    %% Styles
    classDef python fill:#B3DDF2,stroke:#1E70BF,color:#000
    classDef asm fill:#C6E5C6,stroke:#2E8B57,color:#000
    classDef data fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef tool fill:#FEEFB3,stroke:#9F6000,color:#000
```
