# fatematabassum/numerical_instability_and_chaos architecture

> Architecture diagram of the GitHub repository fatematabassum/numerical_instability_and_chaos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fatematabassum/numerical_instability_and_chaos
- Repository: https://github.com/fatematabassum/numerical_instability_and_chaos

## Overview

This repository is a research toolkit for measuring numerical instability and decision-boundary behavior in language-model representations under small perturbations. The principal workflow is to select and load a model, run perturbation analyses, and generate figures and aggregate tables. The analysis modules provide the internal measurement layer; the figure suite preserves the paper’s distinct experiment branches. The README is empty, and several modules were not sampled, so some connections are shown only where the tree or sampled callers support them.

Main entry points: [`experiments/run_all.py`](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/experiments/run_all.py) (Experiment runner), [`llm/hf_client.py`](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/hf_client.py) (HuggingFace client), [`analysis/svd.py`](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/svd.py) (Singular directions), [`figures/tables.py`](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/tables.py) (Metric tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Experiment execution"]
  node_runner["Experiment runner<br/>[run_all.py]"]
  node_aliases["Model aliases"]
end

subgraph group_models["Model access"]
  node_factory["Client factory<br/>[factory.py]"]
  node_interface["Client interface<br/>[interface.py]"]
  node_hfclient["HuggingFace client<br/>[hf_client.py]"]
  node_openai["OpenAI client<br/>[openai_client.py]"]
end

subgraph group_analysis["Perturbation analysis"]
  node_svd["Singular directions<br/>[svd.py]"]
  node_condition["Condition analysis<br/>[condition.py]"]
  node_continuity["Continuity analysis<br/>[continuity.py]"]
  node_decision["Decision analysis<br/>[decision.py]"]
  node_stability["Stability analysis<br/>[stability.py]"]
  node_averaging["Noise averaging<br/>[averaging.py]"]
end

subgraph group_results["Figures and tables"]
  node_fig1["Directional number"]
  node_figlayers["Layerwise propagation"]
  node_figmicro["Micro-continuity"]
  node_figdecision["Decision maps"]
  node_figangular["Angular stability"]
  node_figuniversal["Universal stability"]
  node_figprecision["Precision study<br/>[fig8_precision.py]"]
  node_figaverage["Averaging convergence<br/>[fig9_averaging.py]"]
  node_tables["Metric tables<br/>[tables.py]"]
end

node_researcher(("Researcher"))
node_model_backend["Model backend"]

node_researcher -->|"selects experiments"| node_runner
node_runner -->|"selects model"| node_aliases
node_runner -->|"creates client"| node_factory
node_factory -->|"creates client"| node_hfclient
node_factory -.->|"creates client"| node_openai
node_hfclient -->|"runs inference"| node_model_backend
node_openai -.->|"requests completions"| node_model_backend
node_runner -->|"runs and plots"| node_fig1
node_runner -->|"runs and plots"| node_figlayers
node_runner -->|"runs and plots"| node_figmicro
node_runner -->|"runs and plots"| node_figdecision
node_runner -->|"runs and plots"| node_figangular
node_runner -->|"runs and plots"| node_figuniversal
node_runner -->|"runs and plots"| node_figprecision
node_runner -->|"runs and plots"| node_figaverage
node_runner -->|"computes tables"| node_tables
node_fig1 -->|"computes metrics"| node_condition
node_fig1 -->|"gets directions"| node_svd
node_figlayers -->|"reads layer states"| node_hfclient
node_figmicro -->|"computes metrics"| node_continuity
node_figdecision -->|"maps decisions"| node_decision
node_figangular -->|"computes boundary"| node_stability
node_figangular -->|"gets directions"| node_svd
node_figuniversal -->|"computes thresholds"| node_stability
node_figuniversal -->|"gets directions"| node_svd
node_figprecision -->|"compares precision"| node_hfclient
node_figaverage -->|"computes convergence"| node_averaging
node_figaverage -->|"gets directions"| node_svd
node_tables -->|"computes stability metrics"| node_continuity
node_tables -->|"computes boundary metrics"| node_decision
node_tables -->|"gets directions"| node_svd
node_condition -->|"evaluates perturbations"| node_hfclient
node_continuity -->|"evaluates perturbations"| node_hfclient
node_decision -->|"evaluates perturbations"| node_hfclient
node_stability -->|"evaluates perturbations"| node_hfclient
node_averaging -->|"evaluates perturbations"| node_hfclient

click node_runner "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/experiments/run_all.py"
click node_aliases "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/experiment_enums.py"
click node_factory "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/factory.py"
click node_interface "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/interface.py"
click node_hfclient "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/hf_client.py"
click node_openai "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/openai_client.py"
click node_svd "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/svd.py"
click node_condition "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/condition.py"
click node_continuity "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/continuity.py"
click node_decision "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/decision.py"
click node_stability "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/stability.py"
click node_averaging "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/averaging.py"
click node_fig1 "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig1_directional_number.py"
click node_figlayers "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig2_layerwise_large.py"
click node_figmicro "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig4_microcontinuity.py"
click node_figdecision "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig5_decision_maps.py"
click node_figangular "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig6_angular_stability.py"
click node_figuniversal "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig7_universal_smax.py"
click node_figprecision "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig8_precision.py"
click node_figaverage "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig9_averaging.py"
click node_tables "https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/tables.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_aliases toneBlue
class node_factory,node_interface,node_hfclient,node_openai toneAmber
class node_svd,node_condition,node_continuity,node_decision,node_stability,node_averaging toneMint
class node_fig1,node_figlayers,node_figmicro,node_figdecision,node_figangular,node_figuniversal,node_figprecision,node_figaverage,node_tables toneRose
class node_researcher,node_model_backend toneIndigo
```

## Components

### Experiment execution

- [Experiment runner](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/experiments/run_all.py): `experiments/run_all.py`
- [Model aliases](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/experiment_enums.py): `experiment_enums.py`

### Model access

- [Client factory](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/factory.py): `llm/factory.py`
- [Client interface](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/interface.py): `llm/interface.py`
- [HuggingFace client](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/hf_client.py): `llm/hf_client.py`
- [OpenAI client](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/llm/openai_client.py): `llm/openai_client.py`

### Perturbation analysis

- [Singular directions](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/svd.py): `analysis/svd.py`
- [Condition analysis](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/condition.py): `analysis/condition.py`
- [Continuity analysis](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/continuity.py): `analysis/continuity.py`
- [Decision analysis](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/decision.py): `analysis/decision.py`
- [Stability analysis](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/stability.py): `analysis/stability.py`
- [Noise averaging](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/analysis/averaging.py): `analysis/averaging.py`

### Figures and tables

- [Directional number](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig1_directional_number.py): `figures/fig1_directional_number.py`
- [Layerwise propagation](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig2_layerwise_large.py): `figures/fig2_layerwise_large.py`
- [Micro-continuity](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig4_microcontinuity.py): `figures/fig4_microcontinuity.py`
- [Decision maps](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig5_decision_maps.py): `figures/fig5_decision_maps.py`
- [Angular stability](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig6_angular_stability.py): `figures/fig6_angular_stability.py`
- [Universal stability](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig7_universal_smax.py): `figures/fig7_universal_smax.py`
- [Precision study](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig8_precision.py): `figures/fig8_precision.py`
- [Averaging convergence](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/fig9_averaging.py): `figures/fig9_averaging.py`
- [Metric tables](https://github.com/fatematabassum/numerical_instability_and_chaos/blob/master/figures/tables.py): `figures/tables.py`

### Other components

- **Researcher**
- **Model backend**

## Connections

- Researcher → Experiment runner: selects experiments
- Experiment runner → Model aliases: selects model
- Experiment runner → Client factory: creates client
- Client factory → HuggingFace client: creates client
- Client factory → OpenAI client: creates client
- HuggingFace client → Model backend: runs inference
- OpenAI client → Model backend: requests completions
- Experiment runner → Directional number: runs and plots
- Experiment runner → Layerwise propagation: runs and plots
- Experiment runner → Micro-continuity: runs and plots
- Experiment runner → Decision maps: runs and plots
- Experiment runner → Angular stability: runs and plots
- Experiment runner → Universal stability: runs and plots
- Experiment runner → Precision study: runs and plots
- Experiment runner → Averaging convergence: runs and plots
- Experiment runner → Metric tables: computes tables
- Directional number → Condition analysis: computes metrics
- Directional number → Singular directions: gets directions
- Layerwise propagation → HuggingFace client: reads layer states
- Micro-continuity → Continuity analysis: computes metrics
- Decision maps → Decision analysis: maps decisions
- Angular stability → Stability analysis: computes boundary
- Angular stability → Singular directions: gets directions
- Universal stability → Stability analysis: computes thresholds
- Universal stability → Singular directions: gets directions
- Precision study → HuggingFace client: compares precision
- Averaging convergence → Noise averaging: computes convergence
- Averaging convergence → Singular directions: gets directions
- Metric tables → Continuity analysis: computes stability metrics
- Metric tables → Decision analysis: computes boundary metrics
- Metric tables → Singular directions: gets directions
- Condition analysis → HuggingFace client: evaluates perturbations
- Continuity analysis → HuggingFace client: evaluates perturbations
- Decision analysis → HuggingFace client: evaluates perturbations
- Stability analysis → HuggingFace client: evaluates perturbations
- Noise averaging → HuggingFace client: evaluates perturbations