# jbarberia/psse34to33 architecture

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

- Interactive diagram: https://gitdiagram.com/jbarberia/psse34to33
- Repository: https://github.com/jbarberia/psse34to33

## Overview

##### Project Type and Purpose
- This is a Python library/package whose sole purpose is to read PSSE version-34 `.raw` case files, convert them into the PSSE-33 data model provided by the `grg_pssedata` package, and optionally write them back out as PSSE-33 `.raw` files.
- There is no UI or microservice layer; it’s purely a parsing/conversion tool (an open-source utility library).

##### File Structure Analysis
- Top-level packaging and configuration:
- setup.py, requirements.txt → package installation
- README.md → usage and high-level description
- Core library (PSSE34to33/):
- readfiles.py → routines to read and tokenize the PSSE-34 `.raw` text
- dataformat.py → classes or functions that map raw tokens into in-memory structures
- psse33conversion.py → conversion logic that transforms these in-memory structures into a `grg_pssedata.struct.Case` instance
- __init__.py → public API (exports `conversion_to_33`)
- Tests (tests/):
- tests/data/*.raw → sample input files
- tests/test_00.py → unit tests that drive read → convert → write and verify outcomes

##### README Insights
- The public API is a single function: `conversion_to_33(filename) -> Case`
- The target of conversion is the `grg_pssedata.struct.Case` class.
- Writing back to `.raw` relies on the `.to_psse()` method on that Case instance.

##### Key Components
a. PSSE34to33 Package
- Module: readfiles
- Module: dataformat
- Module: psse33conversion
- Public API wrapper (in __init__.py)
b. External Library
- grg_pssedata (provides the Case data structure)
c. File I/O Layers
- Input: PSSE-34 `.raw` files
- Output: PSSE-33 `.raw` files via Case.to_psse()

##### Relationships & Data Flow
- Raw Input File → readfiles.parse_raw() → Intermediate Tokens
→ dataformat.build_structures() → Raw-version Data Models
→ psse33conversion.conversion_to_33() → grg_pssedata.struct.Case
→ Case.to_psse() → Raw Output File
- Packaging & Installation: setup.py installs the PSSE34to33 package and its dependency on grg_pssedata.

##### Architectural Patterns & Principles
- Single Responsibility per module:
- readfiles only reads and tokenizes
- dataformat only builds in-memory raw structures
- psse33conversion only transforms raw structures to target model
- Clear layering: I/O Layer → Parsing Layer → Conversion Layer → Output Layer
- Dependency inversion: high-level conversion logic depends on an abstract data model (grg_pssedata.struct.Case) rather than raw file details.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% File I/O
    InputRaw["PSSE-34 .raw File"]:::io
    OutputRaw["PSSE-33 .raw File"]:::io

    %% Sample files
    SampleFiles["Sample .raw Files\ntests/data/*.raw"]:::io

    %% Package & Modules
    subgraph "PSSE34to33 Package"
        API["Public API\nconversion_to_33()"]:::internal
        Readfiles["readfiles.parse_raw()"]:::internal
        Dataformat["dataformat.build_structures()"]:::internal
        Conversion["psse33conversion.conversion_to_33()"]:::internal
    end

    %% External Library
    Case["grg_pssedata.struct.Case"]:::ext

    %% Testing
    TestHarness["Test Harness\ntests/test_00.py"]:::test
    TestHelpers["Test Data Helpers\ntests/data.py"]:::test

    %% Packaging
    Packaging["Packaging & Metadata\nsetup.py, requirements.txt, README.md"]:::internal

    %% Data Flow
    SampleFiles -->|"input files"| InputRaw
    InputRaw -->|"parse_raw()"| Readfiles
    Readfiles -->|"build_structures()"| Dataformat
    Dataformat -->|"conversion_to_33()"| Conversion
    Conversion -->|"returns Case"| Case
    Case -->|"to_psse()"| OutputRaw

    %% Test Integration
    TestHarness -->|"calls conversion_to_33()"| API
    API -->|"drives pipeline"| Readfiles

    %% Packaging Relation
    Packaging -.-> API

    %% Click Events
    click Readfiles "https://github.com/jbarberia/psse34to33/blob/master/PSSE34to33/readfiles.py"
    click Dataformat "https://github.com/jbarberia/psse34to33/blob/master/PSSE34to33/dataformat.py"
    click Conversion "https://github.com/jbarberia/psse34to33/blob/master/PSSE34to33/psse33conversion.py"
    click API "https://github.com/jbarberia/psse34to33/blob/master/PSSE34to33/__init__.py"
    click Packaging "https://github.com/jbarberia/psse34to33/blob/master/setup.py"
    click TestHarness "https://github.com/jbarberia/psse34to33/blob/master/tests/test_00.py"
    click SampleFiles "https://github.com/jbarberia/psse34to33/tree/master/tests/data"
    click TestHelpers "https://github.com/jbarberia/psse34to33/blob/master/tests/data.py"

    %% Styling
    classDef internal fill:#e0f7fa,stroke:#00796b;
    classDef ext fill:#fff3e0,stroke:#ff9800,stroke-dasharray: 5 5;
    classDef io fill:#f1f8e9,stroke:#388e3c,stroke-width:2px;
    classDef test fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
```
