# predsci/psipy architecture

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

- Interactive diagram: https://gitdiagram.com/predsci/psipy
- Repository: https://github.com/predsci/psipy

## Overview

##### Project Type and Purpose
- This is a scientific Python package focused on handling data from MHD (magneto-hydrodynamic) simulations. Its main goals are reading input files (via custom I/O methods), processing simulation data (through the “model” modules), and visualizing or tracing results (using dedicated visualization and tracing functions).
- The project also includes examples and comprehensive documentation, serving both as a core library and an educational tool.

##### File Structure
- The top-level directories include:
- .github – indicating CI/CD pipelines for testing, linting, and releases.
- docs – for documentation, including developer guides and API references.
- examples – showcasing practical usage in areas like sampling, tracing, and visualization.
- psipy – the core package, with clearly segregated submodules:
▸ data – for handling or creating sample data.
▸ io – dedicated to reading MHD simulation files (formats like MAS and PLUTO).
▸ model – handling data representations, computations, and model-specific logic.
▸ tracing – implementing algorithms (e.g., field line tracing) for data analysis.
▸ visualization – providing plotting capabilities via libraries such as Matplotlib and PyVista.
▸ util – containing helper functions and decorators.
- Configuration files (setup.py, pyproject.toml, etc.) support packaging and building the project.

##### README for Additional Insights
- Although brief, the README confirms the package’s core functionality centered on data handling and visualization of simulation models.
- The integration of continuous integration (GitHub workflows) and documentation (readthedocs) reinforces the importance of quality and user guidance in the architecture.

a. Main Components to Include:
- Input/Output (I/O) Module: Representing psipy/io, with specific support for file formats (mas.py, pluto.py) and utility functions.
- Data Module: The psipy/data package, responsible for sample data generation and handling.
- Model Module: The psipy/model package, which abstracts simulation data into structured models (including variable processing).
- Tracing Module: The psipy/tracing package, implementing algorithms to trace features within the simulation data.
- Visualization Module: The psipy/visualization package, showing results through plotting libraries (Matplotlib, PyVista).
- Utility Module: psipy/util for decorators and helper functions that support the other modules.
- Examples & Documentation: While not part of the runtime architecture, include these as side components that illustrate and validate usage patterns.

b. Relationships and Interactions:
- The I/O Module serves as the entry point, reading raw simulation data and passing it to the Data and Model modules.
- The Model Module processes this data and defines the structure of simulations, which is then used by both the Tracing and Visualization modules.
- The Tracing Module might analyze processed data to generate specific feasible “routes” or “lines” in the simulation (for example, field lines).
- The Visualization Module accepts either raw data, model results, or tracing outputs and converts these into graphical representations.
- Utility functions support cross-cutting concerns across all modules.
- Examples provide a practical demonstration of these interactions.

c. Important Architectural Patterns and Design Principles:
- Modular Design & Separation of Concerns: Each submodule (io, model, visualization, etc.) has a distinct responsibility.
- Layered Architecture: Data flows from low-level I/O reading to mid-level processing (model and tracing) and finally to high-level visualization.
- Extensive Testing and Documentation: Indicated by the presence of a tests directory within most modules and comprehensive docs from Sphinx and GitHub Actions.

d. Technologies and Frameworks to Highlight:
- Python as the core language.
- Scientific libraries (implied through modules names like matplotlib.py and pyvista.py).
- Tools for continuous integration (GitHub Actions workflows) and documentation (Sphinx/readthedocs) are part of the overall system context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Processing"
        IO["I/O Module"]:::io
        DATA["Data Module"]:::data
        MODEL["Model Module"]:::model
        UTIL["Utility Module"]:::utility
    end

    subgraph "Analysis Layer"
        TRACING["Tracing Module"]:::tracing
    end

    subgraph "Presentation Layer"
        VIZ["Visualization Module"]:::visualization
        EXAM["Examples & Demos"]:::examples
        DOCS["Documentation"]:::docs
    end

    %% Data Flow Arrows
    IO -->|"reads"| DATA
    IO -->|"reads"| MODEL
    DATA -->|"supplies raw data"| MODEL
    MODEL -->|"processes data"| TRACING
    MODEL -->|"processes data"| VIZ

    %% Support from Utility Module
    UTIL ---|"supports"| IO
    UTIL ---|"supports"| DATA
    UTIL ---|"supports"| MODEL
    UTIL ---|"supports"| TRACING
    UTIL ---|"supports"| VIZ

    %% Ancillary Components
    EXAM ---|"demonstrates usage"| MODEL
    DOCS ---|"provides guidance"| MODEL

    %% Click Events
    click IO "https://github.com/predsci/psipy/tree/main/psipy/io"
    click DATA "https://github.com/predsci/psipy/tree/main/psipy/data"
    click MODEL "https://github.com/predsci/psipy/tree/main/psipy/model"
    click TRACING "https://github.com/predsci/psipy/tree/main/psipy/tracing"
    click VIZ "https://github.com/predsci/psipy/tree/main/psipy/visualization"
    click UTIL "https://github.com/predsci/psipy/tree/main/psipy/util"
    click EXAM "https://github.com/predsci/psipy/tree/main/examples"
    click DOCS "https://github.com/predsci/psipy/tree/main/docs"

    %% Styles
    classDef io fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef data fill:#2a9d8f,stroke:#264653,stroke-width:2px;
    classDef model fill:#e9c46a,stroke:#f4a261,stroke-width:2px;
    classDef tracing fill:#e76f51,stroke:#2a9d8f,stroke-width:2px;
    classDef visualization fill:#264653,stroke:#2a9d8f,stroke-width:2px;
    classDef utility fill:#457b9d,stroke:#1d3557,stroke-width:2px;
    classDef examples fill:#a8dadc,stroke:#457b9d,stroke-width:2px;
    classDef docs fill:#8ecae6,stroke:#219ebc,stroke-width:2px;
```
