# biswajitsadhu/pydoseia architecture

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

- Interactive diagram: https://gitdiagram.com/biswajitsadhu/pydoseia
- Repository: https://github.com/biswajitsadhu/pydoseia

## Overview

##### Project type and purpose
- pyDOSEIA is an open-source scientific Python package for radiation dose assessment from atmospheric releases.
- It provides an interactive CLI input generator, reads YAML configuration files, pulls in tabular data (Excel/CSV) for dose conversion factors and meteorology, runs computational models (inhalation, ingestion, external, plume-shine), and writes results (CSV, pickled objects).

##### File structure
- Top-level scripts:
- main.py – entry point
- auto_input_generator.py / auto_input_v18.py – interactive input generation modules
- test_module.py – basic module‐level tests
- Modules implementing functionality:
- auto_input_generator_funcs_class.py
- dosefunc.py, metfunc.py, raddcffunc.py, outputfunc.py, static_utils.py
- Configuration and input:
- configs/*.yaml – example scenario definitions
- data_sources.md – documentation of data sources
- Data libraries:
- library/half_life, ingestion_public, inhalation_HC2 – Excel/CSV dose conversion factor tables
- met_data/Met_data_5Yr.xlsx – historical meteorological data
- Environment and dependencies:
- environment.yml – conda environment spec
- Tests:
- test/ – YAML test cases + test/test_module.py

##### Extract insights from README
- Provides two high-level flowcharts (simple and INGEN)
- Describes the two major workflows:
a) Interactive Input Generator CLI (auto_input_generator.py)
b) Batch computation engine (main.py reading existing config)
- Highlights parallel processing via joblib, pickle outputs, CSV summaries.

##### Elements
- Clear labels:
[CLI Input Generator], [Config Loader], [Dose Conversion Loader], [Met Processing], [Dose Engine], [Output Writer], [Data Library], [Met Data], [YAML Configs], [Tests]
- CLI → Config Loader → Core Engine
- Core Engine ↔ Data Library / Met Data
- Core Engine → Output Writer
- Tests → each component
- Rectangles for code modules
- Parallelogram for CLI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CLI_Func["Input Generator Funcs"]:::cli
        click CLI_Func "https://github.com/biswajitsadhu/pydoseia/blob/main/auto_input_generator_funcs_class.py"
        CLI1["CLI Input Generator"]:::cli
        click CLI1 "https://github.com/biswajitsadhu/pydoseia/blob/main/auto_input_generator.py"
        CLI2["CLI Input v18"]:::cli
        click CLI2 "https://github.com/biswajitsadhu/pydoseia/blob/main/auto_input_v18.py"
        ConfigLoader["Configuration Loader"]:::process
        click ConfigLoader "https://github.com/biswajitsadhu/pydoseia/blob/main/static_utils.py"
    end

    %% Data Layer
    subgraph "Data Layer"
        YAML["YAML Configs"]:::data
        click YAML "https://github.com/biswajitsadhu/pydoseia/tree/main/configs/"
        DataLib["Dose Conversion Library"]:::data
        click DataLib "https://github.com/biswajitsadhu/pydoseia/tree/main/library/"
        MetData["Meteorological Data"]:::data
        click MetData "https://github.com/biswajitsadhu/pydoseia/blob/main/met_data/Met_data_5Yr.xlsx"
    end

    %% Processing Layer
    subgraph "Processing Layer"
        DoseConv["Dose Conversion Loader"]:::process
        click DoseConv "https://github.com/biswajitsadhu/pydoseia/blob/main/raddcffunc.py"
        MetProc["Met Processing"]:::process
        click MetProc "https://github.com/biswajitsadhu/pydoseia/blob/main/metfunc.py"
        Utils["Utility & Static Utils"]:::process
        click Utils "https://github.com/biswajitsadhu/pydoseia/blob/main/static_utils.py"
        DoseEngine["Dose Calculation Engine"]:::process
        click DoseEngine "https://github.com/biswajitsadhu/pydoseia/blob/main/dosefunc.py"
    end

    %% Output Layer
    subgraph "Output Layer"
        Output["Output Writer"]:::output
        click Output "https://github.com/biswajitsadhu/pydoseia/blob/main/outputfunc.py"
    end

    %% Test Harness
    subgraph "Test Harness"
        TestScript["test_module.py"]:::test
        click TestScript "https://github.com/biswajitsadhu/pydoseia/blob/main/test_module.py"
        TestTests["test/test_module.py"]:::test
        click TestTests "https://github.com/biswajitsadhu/pydoseia/blob/main/test/test_module.py"
        TestYAML["YAML Test Cases"]:::test
        click TestYAML "https://github.com/biswajitsadhu/pydoseia/tree/main/test/"
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ENV["environment.yml"]:::external
        click ENV "https://github.com/biswajitsadhu/pydoseia/blob/main/environment.yml"
    end

    %% Data Flows
    CLI_Func --> CLI1
    CLI_Func --> CLI2
    CLI1 -->|"generates/validates"| YAML
    CLI2 -->|"generates/validates"| YAML
    CLI1 --> ConfigLoader
    CLI2 --> ConfigLoader

    YAML -->|"loads config"| ConfigLoader
    ConfigLoader -->|"parameters"| DoseConv
    ConfigLoader -->|"parameters"| MetProc
    ConfigLoader -->|"parameters"| DoseEngine

    DataLib -->|"dose tables"| DoseConv
    MetData -->|"met data"| MetProc
    Utils --> DoseConv
    Utils --> MetProc
    Utils --> DoseEngine

    DoseConv -->|"conversion factors"| DoseEngine
    MetProc -->|"processed met inputs"| DoseEngine

    DoseEngine -->|"results"| Output

    %% Test connections
    TestScript --> CLI1
    TestScript --> ConfigLoader
    TestScript --> DoseConv
    TestScript --> MetProc
    TestScript --> DoseEngine
    TestScript --> Output
    TestYAML --> CLI1
    TestYAML --> DoseEngine

    %% Dependencies
    ENV -.-> CLI1
    ENV -.-> ConfigLoader
    ENV -.-> DoseConv
    ENV -.-> MetProc
    ENV -.-> DoseEngine
    ENV -.-> Output

    %% Styles
    classDef cli fill:#E8F4FD,stroke:#0366D6,color:#0366D6,stroke-width:2px;
    classDef data fill:#FFF4E5,stroke:#D69E2E,color:#944D04,stroke-width:2px;
    classDef process fill:#E6FFFA,stroke:#02735E,color:#024737,stroke-width:2px;
    classDef output fill:#FFF5F5,stroke:#D32F2F,color:#9A1C1C,stroke-width:2px;
    classDef test fill:#F5F5F5,stroke:#999999,color:#333333,stroke-dasharray: 5 5;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333,stroke-dasharray: 2 2;
```
