# guglimenny/jkatelab architecture

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

- Interactive diagram: https://gitdiagram.com/guglimenny/jkatelab
- Repository: https://github.com/guglimenny/jkatelab

## Overview

This repository is a small scientific Python ecosystem: shared utilities, QMEP simulation-data analysis tools, and a molecular-dynamics package. The visible QMEP workflow discovers and parses scan files into cases, validates simulation outputs, then loads data for analysis. Core utilities separately provide filesystem, text I/O, plotting, statistics, and error handling; the MD package exposes simulation-related modules, though their internal wiring is not shown. The README is empty, and several excerpts are partial or use names that differ from the tree, so uncertain connections are omitted.

Main entry points: [`jklab-qmep/src/jklab/qmep/loader.py`](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/loader.py) (Data Loader), [`jklab-qmep/src/jklab/qmep/validation.py`](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/validation.py) (Data Validation), [`jklab-qmep/src/jklab/qmep/scan.py`](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/scan.py) (Scan Loader), [`jklab-core/src/jklab/core/exceptions.py`](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/exceptions.py) (Error Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Utilities"]
  node_paths["Filesystem Paths<br/>[paths.py]"]
  node_io["Text I/O<br/>[io.py]"]
  node_statistics["Array Statistics<br/>[statistics.py]"]
  node_plotting["Plotting<br/>[plotting.py]"]
  node_exceptions["Error Handling<br/>[exceptions.py]"]
end

subgraph group_qmep["QMEP Analysis"]
  node_scan["Scan Files"]
  node_scan_module["Scan Loader<br/>[scan.py]"]
  node_case["Simulation Case<br/>[case.py]"]
  node_qmep_paths["QMEP Paths<br/>[paths.py]"]
  node_constants["QMEP Constants<br/>[constants.py]"]
  node_validation["Data Validation<br/>[validation.py]"]
  node_loader["Data Loader<br/>[loader.py]"]
  node_sim_data["Simulation Files"]
  node_qmep_stats["QMEP Statistics<br/>[statistics.py]"]
  node_results["Analysis Results"]
end

subgraph group_md["Molecular Dynamics"]
  node_md_system["MD System<br/>[system.py]"]
  node_md_state["MD State<br/>[state.py]"]
  node_md_simulation["MD Simulation<br/>[simulation.py]"]
  node_md_box["Simulation Box<br/>[box.py]"]
end

node_user(("Analyst"))

node_user -->|"selects scan"| node_scan_module
node_scan -->|"read by"| node_scan_module
node_scan_module -->|"creates cases"| node_case
node_user -->|"requests checks"| node_validation
node_validation -->|"builds paths"| node_qmep_paths
node_validation -->|"gets file paths"| node_loader
node_user -->|"requests data"| node_loader
node_loader -->|"builds paths"| node_qmep_paths
node_loader -->|"uses file types"| node_constants
node_sim_data -->|"loaded from"| node_loader
node_loader -->|"provides arrays"| node_qmep_stats
node_qmep_stats -->|"computes"| node_results
node_io -->|"raises errors"| node_exceptions
node_paths -->|"raises errors"| node_exceptions
node_plotting -->|"raises errors"| node_exceptions

click node_scan_module "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/scan.py"
click node_case "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/case.py"
click node_qmep_paths "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/paths.py"
click node_constants "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/constants.py"
click node_validation "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/validation.py"
click node_loader "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/loader.py"
click node_qmep_stats "https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/statistics.py"
click node_paths "https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/paths.py"
click node_io "https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/io.py"
click node_statistics "https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/statistics.py"
click node_plotting "https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/plotting.py"
click node_exceptions "https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/exceptions.py"
click node_md_system "https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/system.py"
click node_md_state "https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/state.py"
click node_md_simulation "https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/simulation.py"
click node_md_box "https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/box.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_paths,node_io,node_statistics,node_plotting,node_exceptions toneBlue
class node_scan,node_scan_module,node_case,node_qmep_paths,node_constants,node_validation,node_loader,node_sim_data,node_qmep_stats,node_results toneAmber
class node_md_system,node_md_state,node_md_simulation,node_md_box toneMint
class node_user toneIndigo
```

## Components

### Core Utilities

- [Filesystem Paths](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/paths.py): `jklab-core/src/jklab/core/paths.py`
- [Text I/O](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/io.py): `jklab-core/src/jklab/core/io.py`
- [Array Statistics](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/statistics.py): `jklab-core/src/jklab/core/statistics.py`
- [Plotting](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/plotting.py): `jklab-core/src/jklab/core/plotting.py`
- [Error Handling](https://github.com/guglimenny/jkatelab/blob/main/jklab-core/src/jklab/core/exceptions.py): `jklab-core/src/jklab/core/exceptions.py`

### QMEP Analysis

- **Scan Files**
- [Scan Loader](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/scan.py): `jklab-qmep/src/jklab/qmep/scan.py`
- [Simulation Case](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/case.py): `jklab-qmep/src/jklab/qmep/case.py`
- [QMEP Paths](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/paths.py): `jklab-qmep/src/jklab/qmep/paths.py`
- [QMEP Constants](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/constants.py): `jklab-qmep/src/jklab/qmep/constants.py`
- [Data Validation](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/validation.py): `jklab-qmep/src/jklab/qmep/validation.py`
- [Data Loader](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/loader.py): `jklab-qmep/src/jklab/qmep/loader.py`
- **Simulation Files**
- [QMEP Statistics](https://github.com/guglimenny/jkatelab/blob/main/jklab-qmep/src/jklab/qmep/statistics.py): `jklab-qmep/src/jklab/qmep/statistics.py`
- **Analysis Results**

### Molecular Dynamics

- [MD System](https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/system.py): `jklab-md/src/jklab/md/system.py`
- [MD State](https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/state.py): `jklab-md/src/jklab/md/state.py`
- [MD Simulation](https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/simulation.py): `jklab-md/src/jklab/md/simulation.py`
- [Simulation Box](https://github.com/guglimenny/jkatelab/blob/main/jklab-md/src/jklab/md/box.py): `jklab-md/src/jklab/md/box.py`

### Other components

- **Analyst**

## Connections

- Analyst → Scan Loader: selects scan
- Scan Files → Scan Loader: read by
- Scan Loader → Simulation Case: creates cases
- Analyst → Data Validation: requests checks
- Data Validation → QMEP Paths: builds paths
- Data Validation → Data Loader: gets file paths
- Analyst → Data Loader: requests data
- Data Loader → QMEP Paths: builds paths
- Data Loader → QMEP Constants: uses file types
- Simulation Files → Data Loader: loaded from
- Data Loader → QMEP Statistics: provides arrays
- QMEP Statistics → Analysis Results: computes
- Text I/O → Error Handling: raises errors
- Filesystem Paths → Error Handling: raises errors
- Plotting → Error Handling: raises errors