# bumsu-kim/cars architecture

> Architecture diagram of the GitHub repository bumsu-kim/cars, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bumsu-kim/cars
- Repository: https://github.com/bumsu-kim/cars

## Overview

##### Project type and purpose
- This is a research codebase implementing “Curvature-Aware Derivative-Free Optimization” (CARS) and running three experiments:
– A minimal MATLAB demo (CARS_minimal)
– A benchmark suite on More-Garbow-Hillstrom test functions (CARS_MoreGarbowHillstrom)

##### File structure
- Top-level folders:
– CARS_minimal (MATLAB)
– CARS_MoreGarbowHillstrom (MATLAB)
– CARS_MNIST (Python + notebooks)
- Shared root files: LICENSE, top-level README.md
- Each experiment folder contains its own README and driver scripts that call:
– Core algorithm modules (Directional_Newton.m, GH_Deriv.m, etc.)
– Utilities (Param_Settings, PickRandDir, performance_profile, plot_res)
– Data (for MNIST: raw & processed files)
– Notebooks for interactive exploration

##### README for additional insights
- The root README states the three experiments and points to a refactored Python package.
- No monolithic server or UI—this is a library + batch‐style experiment suite.

##### Main components and their interactions
a. Core Library of Optimizers
– CARS algorithm implementations (e.g., CARS.m, AdaDGS.m, RealSPSA.m)
– Supporting derivatives and quadrature modules (GH_Deriv.m, GH_quad.m)
– Common utility functions (PickRandDir.m, Param_Settings.m)
b. Experiment Drivers
– CARS_minimal/SimpleDemo.m (calls core library)
– CARS_MoreGarbowHillstrom/more_run.m & more_test.m (benchmark scripts)
– CARS_MNIST/MNIST_Train.py, MNIST_Attack.py, AttackTools.py, DataLoaders.py
c. Data Layers
– MATLAB: no external data (built-in test functions)
– Python: MNIST/raw → processed (.pt files) → DataLoaders
d. Outputs
– MATLAB: performance_profile plots, .m result files
– Python: trained models (models/MNIST_weights.pth), attack results
e. External Dependencies
– MATLAB (no extra toolboxes beyond base)
– Python: PyTorch (assuming from file extensions .pth), numpy, torch.utils.data

##### Architectural patterns / design principles
- Modular core library with experiment‐specific driver scripts
- Separation of concerns:
– Algorithm implementations separate from data I/O and experiment orchestration
- Reusability: same algorithm modules used by both minimal demo and full benchmark
- Batch-style pipelines (no persistent services)

##### Essential elements
– Clear labels: e.g., “PickRandDir.m” vs. “Network.py”
– Note any loops or iterative calls (optimizer loops inside MNIST_Train)

| Core Algorithms | CARS_minimal Pipeline | CARS_MoreGH Pipeline | CARS_MNIST Pipeline |

| [CARS.m, GH_Deriv.m, …]         →  | SimpleDemo.m  →  CARS.m  → performance_profile  → plots
|                                 →  | more_run.m → core modules → performance_profile → plots
|                                 →  | MNIST_Train.py
|                                 →  |   ↳ DataLoaders.py → MNIST/raw → MNIST/processed
|                                 →  |   ↳ Network.py
|                                 →  |   ↳ AttackTools.py → outputs/models/*.pth

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef driver fill:#bbf,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px
    classDef output fill:#fbf,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5

    subgraph "Core Algorithms" 
        CARS["CARS.m"]:::core
        DirNewton["Directional_Newton.m"]:::core
        GHDeriv["GH_Deriv.m"]:::core
        GHQuad["GH_quad.m"]:::core
        PickDir["PickRandDir.m"]:::core
        ParamSet["Param_Settings.m"]:::core
        AdaDGS["AdaDGS.m"]:::core
        RealSPSA["RealSPSA.m"]:::core
        Real2SPSA["Real2SPSA.m"]:::core
        NesterovRS["NesterovRS.m"]:::core
        SMTP["SMTP.m"]:::core
        TauRho["create_tau_rho.m"]:::core
        getR["getR.m"]:::core
    end

    subgraph "CARS_minimal Pipeline"
        SimpleDemo["SimpleDemo.m"]:::driver
    end

    subgraph "CARS_MoreGH Pipeline"
        moreRun["more_run.m"]:::driver
        moreTest["more_test.m"]:::driver
        moreScript["moretest_script.m"]:::driver
        perfProfScript["MORE_TEST_PERF_PROF.m"]:::driver
    end

    subgraph "CARS_MNIST Pipeline"
        MNISTTrain["MNIST_Train.py"]:::driver
        MNISTAttack["MNIST_Attack.py"]:::driver
        AttackTools["AttackTools.py"]:::driver
        TestTools["TestTools.py"]:::driver
        OptTools["OptTools.py"]:::driver
        OptimizersPy["optimizers.py"]:::driver
        OptBase["optbase.py"]:::driver
        UtilsPy["utils.py"]:::driver
        DataLoaders["DataLoaders.py"]:::data
        MNISTLoaders["MNISTLoaders.py"]:::data
    end

    subgraph "Data Storage / I/O"
        RawData["MNIST/raw"]:::data
        ProcData["MNIST/processed"]:::data
    end

    subgraph "Outputs / Visualization"
        PerfProfile["performance_profile.m"]:::output
        PlotRes["plot_res.m"]:::output
        ModelWeights["MNIST_weights.pth"]:::output
    end

    subgraph "External Dependencies"
        MATLAB["MATLAB"]:::external
        PyTorch["PyTorch"]:::external
    end

    %% Relationships - CARS_minimal
    SimpleDemo -->|calls| CARS
    SimpleDemo -->|calls| DirNewton
    SimpleDemo -->|calls| GHDeriv
    SimpleDemo -->|calls| GHQuad
    SimpleDemo -->|calls| PickDir
    SimpleDemo -->|calls| ParamSet
    SimpleDemo -->|generates| PerfProfile
    SimpleDemo -->|generates| PlotRes

    %% Relationships - CARS_MoreGH
    moreRun -->|calls| CARS
    moreRun -->|calls| DirNewton
    moreRun -->|calls| GHDeriv
    moreRun -->|calls| GHQuad
    moreRun -->|calls| PickDir
    moreRun -->|calls| ParamSet
    moreRun -->|calls| AdaDGS
    moreRun -->|calls| RealSPSA
    moreRun -->|calls| Real2SPSA
    moreRun -->|calls| NesterovRS
    moreRun -->|calls| SMTP
    moreRun -->|calls| TauRho
    moreRun -->|calls| getR
    moreTest -->|calls| PerfProfile
    moreTest -->|calls| PlotRes
    moreScript -->|orchestrates| moreRun
    perfProfScript -->|visualizes| PerfProfile

    %% Relationships - CARS_MNIST
    MNISTTrain -->|uses| DataLoaders
    MNISTTrain -->|uses| MNISTLoaders
    DataLoaders -->|loads| RawData
    DataLoaders -->|loads| ProcData
    MNISTTrain -->|calls| OptTools
    MNISTTrain -->|calls| OptimizersPy
    MNISTTrain -->|calls| OptBase
    MNISTTrain -->|calls| UtilsPy
    MNISTTrain -->|saves| ModelWeights
    MNISTAttack -->|uses| AttackTools
    MNISTAttack -->|uses| TestTools
    MNISTAttack -->|reads| ModelWeights

    %% Dependencies
    SimpleDemo -->|runs on| MATLAB
    moreRun -->|runs on| MATLAB
    MNISTTrain -->|runs on| PyTorch

    %% Click Events - Core Algorithms
    click CARS "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/CARS.m"
    click CARS "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/CARS.m"
    click DirNewton "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/Directional_Newton.m"
    click DirNewton "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/Directional_Newton.m"
    click GHDeriv "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/GH_Deriv.m"
    click GHDeriv "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/GH_Deriv.m"
    click GHQuad "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/GH_quad.m"
    click GHQuad "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/GH_quad.m"
    click PickDir "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/PickRandDir.m"
    click PickDir "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/PickRandDir.m"
    click ParamSet "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/Param_Settings.m"
    click AdaDGS "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/AdaDGS.m"
    click RealSPSA "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/RealSPSA.m"
    click Real2SPSA "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/Real2SPSA.m"
    click NesterovRS "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/NesterovRS.m"
    click SMTP "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/SMTP.m"
    click TauRho "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/create_tau_rho.m"
    click getR "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/getR.m"

    %% Click Events - Drivers
    click SimpleDemo "https://github.com/bumsu-kim/cars/blob/main/CARS_minimal/SimpleDemo.m"
    click moreRun "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/more_run.m"
    click moreTest "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/more_test.m"
    click moreScript "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/moretest_script.m"
    click perfProfScript "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/MORE_TEST_PERF_PROF.m"
    click MNISTTrain "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/MNIST_Train.py"
    click MNISTAttack "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/MNIST_Attack.py"
    click AttackTools "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/AttackTools.py"
    click TestTools "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/TestTools.py"
    click OptTools "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/OptTools.py"
    click OptimizersPy "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/optimizers.py"
    click OptBase "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/optbase.py"
    click UtilsPy "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/utils.py"

    %% Click Events - Data
    click DataLoaders "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/DataLoaders.py"
    click MNISTLoaders "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/MNISTLoaders.py"
    click RawData "https://github.com/bumsu-kim/cars/tree/main/CARS_MNIST/MNIST/raw"
    click ProcData "https://github.com/bumsu-kim/cars/tree/main/CARS_MNIST/MNIST/processed"
    
    %% Click Events - Outputs
    click ModelWeights "https://github.com/bumsu-kim/cars/blob/main/CARS_MNIST/models/MNIST_weights.pth"
    click PerfProfile "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/performance_profile.m"
    click PlotRes "https://github.com/bumsu-kim/cars/blob/main/CARS_MoreGarbowHillstrom/plot_res.m"
```
