# amirgroup-codes/gfast architecture

> Architecture diagram of the GitHub repository amirgroup-codes/gfast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amirgroup-codes/gfast
- Repository: https://github.com/amirgroup-codes/gfast

## Overview

##### Project Type and Purpose
- This project implements an efficient algorithm (GFast) for computing sparse Fourier transforms of generalized q-ary functions. It is research-driven software that includes not only the core algorithm but also multiple experiment pipelines (for GFP experiments, synthetic data, and a tutorial) to evaluate the algorithm on different data sets.
- The project is structured as a Python module (gfast) with separate directories for experimental implementations and results. The README also mentions a paper and a tutorial notebook, which indicate that the repository is meant to be both a reusable algorithm library and an experimental/testbed platform.

##### Analyzing the File Structure & Identifying Main Components
- Core Algorithm (gfast folder):
– Contains modules like gfast.py (likely the main algorithm implementation), along with helper classes and methods such as input_signal.py, lasso.py, query.py, reconstruct.py, spright.py, and utility functions in utils.py.
– This is the “engine” folder that implements the core sparse Fourier transform algorithm.

- Experiment Pipelines:
– gfp_exp: Houses code (including shell scripts and experiments) for running NR-GFast on data related to the multilayer perceptron (MLP) and the avGFP protein experiment. It includes a model subdirectory with a protein sequence file, a pretrained model (mlp.pt), and model weights.
– synt_exp: Contains code and scripts for running tests on synthetic data. This will be important when isolating synthetic experiment configurations from the core algorithm.
– tutorial: The Jupyter notebook (tutorial.ipynb) and associated results folder demonstrate how to run the algorithm and serve as an example-driven overview of the system.

- Results and Supporting Files:
– gfp_results, synt_results, and tutorial_results folders: These store outputs from the various experimental runs.
– figures.ipynb not only generates figures for the paper but also serves as a visualization aid, so it can be thought of as a supplementary component.
– environment.yml and .gitignore provide configuration and version control utility.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Experiment Pipelines
    subgraph "GFP Experiment Pipeline"
        EG_main["Main Script"]:::exp
        EG_model["Supporting Scripts & Models"]:::exp
    end
    subgraph "Synthetic Experiment Pipeline"
        ES_main["Main Script"]:::exp
    end
    tut["Tutorial/Demo Notebook"]:::tutorial

    %% Core API Node
    API["GFast Module API"]:::core

    %% Core Internal Components
    subgraph "Core GFast Module"
        GA["Main Algorithm Implementation"]:::core
        GS["Input Signal Processing"]:::core
        GL["Lasso/Optimization Module"]:::core
        GQ["Query Functionality"]:::core
        GR["Reconstruction Functionality"]:::core
        GP["Special Processing (Spright)"]:::core
        GU["Utility Functions"]:::core
    end

    %% Results Storage
    subgraph "Results Storage"
        R_GFP["GFP Results Storage"]:::result
        R_SYN["Synthetic Results Storage"]:::result
        R_TUT["Tutorial Results Storage"]:::result
    end

    %% Configuration & Visualization
    subgraph "Configuration & Visualization"
        Conf["Environment Configuration"]:::config
        Vis["Visualization Scripts"]:::config
    end

    %% Connections from Experiment Pipelines to Core API
    EG_main -->|"calls"| API
    ES_main -->|"calls"| API
    tut    -->|"calls"| API

    %% Connections from Core API to Core Internal Components
    API -->|"invokes"| GA
    API -->|"invokes"| GS
    API -->|"invokes"| GL
    API -->|"invokes"| GQ
    API -->|"invokes"| GR
    API -->|"invokes"| GP
    API -->|"invokes"| GU

    %% Connections from Core API to Results Storage
    API -->|"outputs"| R_GFP
    API -->|"outputs"| R_SYN
    API -->|"outputs"| R_TUT

    %% Connections from Configuration & Visualization to Core API
    Conf -->|"configures"| API
    Vis  -->|"visualizes"| API

    %% Click Events
    click API "https://github.com/amirgroup-codes/gfast/tree/master/gfast/"
    click GA "https://github.com/amirgroup-codes/gfast/blob/master/gfast/gfast.py"
    click GS "https://github.com/amirgroup-codes/gfast/blob/master/gfast/input_signal.py"
    click GL "https://github.com/amirgroup-codes/gfast/blob/master/gfast/lasso.py"
    click GQ "https://github.com/amirgroup-codes/gfast/blob/master/gfast/query.py"
    click GR "https://github.com/amirgroup-codes/gfast/blob/master/gfast/reconstruct.py"
    click GP "https://github.com/amirgroup-codes/gfast/blob/master/gfast/spright.py"
    click GU "https://github.com/amirgroup-codes/gfast/blob/master/gfast/utils.py"
    click EG_main "https://github.com/amirgroup-codes/gfast/blob/master/gfp_exp/run_gfast.py"
    click EG_model "https://github.com/amirgroup-codes/gfast/tree/master/gfp_exp/model/"
    click ES_main "https://github.com/amirgroup-codes/gfast/blob/master/synt_exp/run_test_samples_vs_nmse.py"
    click tut "https://github.com/amirgroup-codes/gfast/blob/master/tutorial.ipynb"
    click R_GFP "https://github.com/amirgroup-codes/gfast/tree/master/gfp_results/"
    click R_SYN "https://github.com/amirgroup-codes/gfast/tree/master/synt_results/"
    click R_TUT "https://github.com/amirgroup-codes/gfast/tree/master/tutorial_results/"
    click Conf "https://github.com/amirgroup-codes/gfast/blob/master/environment.yml"
    click Vis "https://github.com/amirgroup-codes/gfast/blob/master/figures.ipynb"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef exp fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef tutorial fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef result fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
