# miriamalina/duffing-hb architecture

> Architecture diagram of the GitHub repository miriamalina/duffing-hb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miriamalina/duffing-hb
- Repository: https://github.com/miriamalina/duffing-hb

## Overview

##### Project Type and Purpose
- This is an open-source scientific computation toolbox written in MATLAB.
- Its goal is to reproduce and extend analyses of nonlinear vibration problems (specifically the Duffing oscillator) using the Harmonic Balance Method (HB), leveraging the external NLvib library.

##### High-Level File Structure
- Top-Level
- MATLAB driver scripts (Duffing.m, HB_analysis.m, HB_residual_Duffing.m, Going_around_turning_points.m, P_Comparison.m)
- README.md, LICENSE
- figures/ (output data visualizations)
- NLvib-Basic (embedded external library)
- DOC/ (manuals and PDFs)
- SRC/ (core MATLAB functions for HB, shooting, continuation, mechanical system definitions)
- EXAMPLES/ (numerical examples illustrating usage)
- README.md, LICENSE

##### Key Architectural Insights from README
- Scripts at the root orchestrate experiments by calling into NLvib-Basic/SRC.
- The NLvib-Basic library provides:
a. Mechanical system constructors (single-mass, chain, beam, etc.)
b. Residual and solver routines (HB_residual, shooting_residual, solve_and_continue)
c. A plugin-style pattern for adding new system definitions.
- Output flows into figures/.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "duffing-hb Repository"
        subgraph "User Scripts"
            DS["Duffing.m"]:::scripts
            HA["HB_analysis.m"]:::scripts
            HRD["HB_residual_Duffing.m"]:::scripts
            GATP["Going_around_turning_points.m"]:::scripts
            PC["P_Comparison.m"]:::scripts
        end

        subgraph "NLvib-Basic (embedded third-party)" 
            direction TB
            DOC["DOC/"]:::docs
            DOCPDF["NLvibManual.pdf"]:::docs
            EX["EXAMPLES/"]:::examples
            EX01["01_Duffing/"]:::examples
            EXF1["Duffing.m"]:::examples
            EXF2["HB_residual_Duffing.m"]:::examples
            SRC["SRC/"]:::library
            subgraph "MechanicalSystems"
                CMS["CMS_ROM.m"]:::library
                Chain["ChainOfOscillators.m"]:::library
                FE1["FE_ElasticRod.m"]:::library
                FE2["FE_EulerBernoulliBeam.m"]:::library
                MSys["MechanicalSystem.m"]:::library
                SM["SingleMassOscillator.m"]:::library
                SP["System_with_PolynomialStiffnessNonlinearity.m"]:::library
            end
            HB["HB_residual.m"]:::library
            SR["shooting_residual.m"]:::library
            SC["solve_and_continue.m"]:::library
        end

        subgraph "Outputs"
            FIG["figures/"]:::output
        end

        subgraph "Configuration / Metadata"
            LIC["LICENSE"]:::meta
            RM["README.md"]:::meta
            NBLIC["NLvib-NLvib-Basic/LICENSE"]:::meta
            NBRM["NLvib-NLvib-Basic/README.md"]:::meta
        end
    end

    %% Relationships
    DS -->|"calls"| HB
    DS -->|"calls"| SR
    DS -->|"calls"| SC
    HA -->|"calls"| HB
    HA -->|"calls"| SR
    HRD -->|"calls"| HB
    GATP -->|"calls"| SC
    PC -->|"calls"| SR

    DS -->|"outputs to"| FIG
    HA -->|"outputs to"| FIG
    HRD -->|"outputs to"| FIG
    GATP -->|"outputs to"| FIG
    PC -->|"outputs to"| FIG

    MSys -->|"defines model for"| HB
    MSys -->|"defines model for"| SR
    MSys -->|"defines model for"| SC

    EXF1 -->|"template for"| DS
    EXF2 -->|"template for"| HRD

    %% Click Events
    click DS "https://github.com/miriamalina/duffing-hb/blob/main/Duffing.m"
    click HA "https://github.com/miriamalina/duffing-hb/blob/main/HB_analysis.m"
    click HRD "https://github.com/miriamalina/duffing-hb/blob/main/HB_residual_Duffing.m"
    click GATP "https://github.com/miriamalina/duffing-hb/blob/main/Going_around_turning_points.m"
    click PC "https://github.com/miriamalina/duffing-hb/blob/main/P_Comparison.m"
    click DOC "https://github.com/miriamalina/duffing-hb/tree/main/NLvib-NLvib-Basic/DOC/"
    click DOCPDF "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/DOC/NLvibManual.pdf"
    click EX "https://github.com/miriamalina/duffing-hb/tree/main/NLvib-NLvib-Basic/EXAMPLES/"
    click EX01 "https://github.com/miriamalina/duffing-hb/tree/main/NLvib-NLvib-Basic/EXAMPLES/01_Duffing/"
    click EXF1 "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/EXAMPLES/01_Duffing/Duffing.m"
    click EXF2 "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/EXAMPLES/01_Duffing/HB_residual_Duffing.m"
    click SRC "https://github.com/miriamalina/duffing-hb/tree/main/NLvib-NLvib-Basic/SRC/"
    click CMS "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/CMS_ROM.m"
    click Chain "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/ChainOfOscillators.m"
    click FE1 "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/FE_ElasticRod.m"
    click FE2 "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/FE_EulerBernoulliBeam.m"
    click MSys "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/MechanicalSystem.m"
    click SM "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/SingleMassOscillator.m"
    click SP "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/MechanicalSystems/System_with_PolynomialStiffnessNonlinearity.m"
    click HB "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/HB_residual.m"
    click SR "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/shooting_residual.m"
    click SC "https://github.com/miriamalina/duffing-hb/blob/main/NLvib-NLvib-Basic/SRC/solve_and_continue.m"
    click FIG "https://github.com/miriamalina/duffing-hb/tree/main/figures/"

    %% Styles
    classDef scripts fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef library fill:#90EE90,stroke:#000,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef examples fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef output fill:#FFA500,stroke:#000,stroke-width:1px
    classDef meta fill:#EEEEEE,stroke:#000,stroke-width:1px
    classDef dashed stroke-dasharray: 5 5;color:#000
    class DOC,EX,SRC dashed
```
