# vsgabel/psd_tools architecture

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

- Interactive diagram: https://gitdiagram.com/vsgabel/psd_tools
- Repository: https://github.com/vsgabel/psd_tools

## Overview

psd-tools is a small NumPy library that turns regularly sampled signals and fields into variance-normalized power spectra. Users call the top-level exports for 1D, 2D or 3D analysis; the 2D and 3D paths also provide radial averaging, while plotting helpers shift and scale a 2D spectrum. Window correction and Parseval diagnostics are built into the spectral routines. The graph focuses on runtime capabilities; the README also documents the 3D frequency–radial-wavenumber transform, whose implementation is in the sampled 3D module. There are no external services or persistent stores.

Main entry points: [`src/psd_tools/__init__.py`](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/__init__.py) (Top-level exports), [`src/psd_tools/psd_2d.py`](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_2d.py) (2D spectrum), [`src/psd_tools/psd_3d.py`](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_3d.py) (3D spectrum), [`src/psd_tools/plotting.py`](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/plotting.py) (Centered plot view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_exports["Top-level exports<br/>[__init__.py]"]
end

subgraph group_spectra["Spectral analysis"]
  node_one_d["1D spectrum<br/>[psd_1d.py]"]
  node_two_d["2D spectrum<br/>[psd_2d.py]"]
  node_three_d["3D spectrum<br/>[psd_3d.py]"]
  node_radial_2d["2D radial average<br/>[psd_2d.py]"]
  node_radial_3d["3D radial average<br/>[psd_3d.py]"]
end

subgraph group_views["Spectrum views"]
  node_plot_shift["Centered plot view<br/>[plotting.py]"]
  node_plot_positive["Positive plot view<br/>[plotting.py]"]
end

node_user(("Library user"))

node_user -->|"imports API"| node_exports
node_exports -->|"exports"| node_one_d
node_exports -->|"exports"| node_two_d
node_exports -->|"exports"| node_three_d
node_exports -->|"exports"| node_plot_shift
node_exports -->|"exports"| node_plot_positive
node_exports -->|"exports"| node_radial_2d
node_user -->|"computes 1D PSD"| node_one_d
node_user -->|"computes 2D PSD"| node_two_d
node_user -->|"computes 3D PSD"| node_three_d
node_user -->|"requests radial bins"| node_radial_2d
node_user -->|"requests plot scaling"| node_plot_shift
node_two_d -->|"bins 2D PSD"| node_radial_2d
node_three_d -->|"bins 3D PSD"| node_radial_3d
node_two_d -.->|"provides PSD inputs"| node_plot_shift

click node_exports "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/__init__.py"
click node_one_d "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_1d.py"
click node_two_d "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_2d.py"
click node_three_d "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_3d.py"
click node_radial_2d "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_2d.py"
click node_radial_3d "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_3d.py"
click node_plot_shift "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/plotting.py"
click node_plot_positive "https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/plotting.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_exports,node_user toneBlue
class node_one_d,node_two_d,node_three_d,node_radial_2d,node_radial_3d toneAmber
class node_plot_shift,node_plot_positive toneMint
```

## Components

### Public API

- [Top-level exports](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/__init__.py): `src/psd_tools/__init__.py`

### Spectral analysis

- [1D spectrum](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_1d.py): `src/psd_tools/psd_1d.py`
- [2D spectrum](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_2d.py): `src/psd_tools/psd_2d.py`
- [3D spectrum](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_3d.py): `src/psd_tools/psd_3d.py`
- [2D radial average](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_2d.py): `src/psd_tools/psd_2d.py`
- [3D radial average](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/psd_3d.py): `src/psd_tools/psd_3d.py`

### Spectrum views

- [Centered plot view](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/plotting.py): `src/psd_tools/plotting.py`
- [Positive plot view](https://github.com/vsgabel/psd_tools/blob/main/src/psd_tools/plotting.py): `src/psd_tools/plotting.py`

### Other components

- **Library user**

## Connections

- Library user → Top-level exports: imports API (evidence: `README.md`)
- Top-level exports → 1D spectrum: exports (evidence: `src/psd_tools/__init__.py`)
- Top-level exports → 2D spectrum: exports (evidence: `src/psd_tools/__init__.py`)
- Top-level exports → 3D spectrum: exports (evidence: `src/psd_tools/__init__.py`)
- Top-level exports → Centered plot view: exports (evidence: `src/psd_tools/__init__.py`)
- Top-level exports → Positive plot view: exports (evidence: `src/psd_tools/__init__.py`)
- Top-level exports → 2D radial average: exports (evidence: `src/psd_tools/__init__.py`)
- Library user → 1D spectrum: computes 1D PSD (evidence: `README.md`)
- Library user → 2D spectrum: computes 2D PSD (evidence: `README.md`)
- Library user → 3D spectrum: computes 3D PSD (evidence: `README.md`)
- Library user → 2D radial average: requests radial bins (evidence: `README.md`)
- Library user → Centered plot view: requests plot scaling (evidence: `README.md`)
- 2D spectrum → 2D radial average: bins 2D PSD (evidence: `src/psd_tools/psd_2d.py`)
- 3D spectrum → 3D radial average: bins 3D PSD (evidence: `src/psd_tools/psd_3d.py`)
- 2D spectrum → Centered plot view: provides PSD inputs (evidence: `README.md`)