# flechtenberg/pulpo architecture

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

- Interactive diagram: https://gitdiagram.com/flechtenberg/pulpo
- Repository: https://github.com/flechtenberg/pulpo

## Overview

##### Project Type and Purpose
- PULPO is a Python package designed for Life Cycle Optimization (LCO) using life cycle inventories. It integrates with both the Brightway LCA framework and the Pyomo optimization modeling framework.
- The system is not a full-stack web application but rather a scientific/optimization package that also provides demonstration Jupyter notebooks, documentation (in docs), and tests.

##### Key Directories and Their Implications
- pulpo/ – This directory contains the core package code:
- pulpo.py: Likely contains the main orchestration of lifecycle optimization processes.
- utils/ – Hosts helper functions such as parsers, converters, optimizers, and savers that support the optimization logic.
- docs/ – Contains extensive documentation, examples, configuration templates, and even design resources like notebooks for various use cases (electricity, hydrogen, plastic).
- notebooks/ – Provides demonstration notebooks to show how to apply the package in real-case scenarios.
- tests/ – Contains unit tests that validate functionality across different optimization-related modules such as database examples and algorithm correctness.
- Other files (e.g., pyproject.toml, requirements.txt, MANIFEST.in, README files) indicate how the package is configured, built, and distributed, which is key for understanding external integrations.

##### Main Components
a. Core Optimization Engine:
- Main optimization engine found in pulpo/pulpo.py.
- Role in handling lifecycle inventory data and decision-making logic.
b. Utility Modules:
- Utilities (e.g., bw_parser, converter, optimizer, saver) under a “Utilities” component.
- How these support the optimization processes (e.g., parsing, converting, optimization routines, and saving output).
c. External Dependencies and Libraries:
- Integration with the Brightway LCA framework (used for managing life cycle inventories) and the Pyomo optimization framework (managing optimization constraints and solving).
- That these external libraries are fundamental to the project’s architecture.
d. User Interface and Interaction:
e. Documentation and Testing:
- Connection towards documentation (docs/) which guides users on setup, configuration, and examples.
- Testing framework (tests/) which ensures reliability of the underlying optimization algorithms.
f. Data Flow & Configuration:
- Components for how input data (such as life cycle inventories, technology choices, constraints, etc.) flows into the core optimization engine.
- Configuration files (pyproject.toml, environment.yaml, etc.) as part of the project’s build and runtime configuration.

##### Relationships and Interactions
- From the “Core Optimization Engine” outward to external libraries (Brightway and Pyomo) indicating utilization of these frameworks.
- Within the engine, illustrate interactions with the “Utilities” module to process data.
- “Documentation” and “Tests” to the main engine to show how they support and validate the system.

##### Architectural Patterns and Design Principles
- The design shows a modular structure typical for scientific computing packages: a core engine that delegates specialized tasks to utility modules.
- The loose coupling between the optimization processes and external dependency usage is visible (i.e., the package acts as a wrapper or adapter over Pyomo and Brightway).
- The inclusion of notebooks and clear separation of tests and documentation aligns with best practices in open-source scientific toolkits.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    subgraph "User Interaction"
        U["User / Jupyter Notebook"]:::user
    end

    %% Configuration & Build Setup
    subgraph "Configuration & Build Setup"
        PY["pyproject.toml"]:::configFile
        RT["requirements.txt"]:::configFile
    end

    %% Core Module
    subgraph "Core Module"
        CORE["Core Optimization Engine (pulpo.py)"]:::core
    end

    %% Utilities
    subgraph "Utilities"
        BP["bw_parser"]:::utility
        CV["converter"]:::utility
        OP["optimizer"]:::utility
        SV["saver"]:::utility
    end

    %% External Dependencies
    subgraph "External Dependencies"
        BW["Brightway LCA Framework"]:::external
        PYMO["Pyomo Optimization Framework"]:::external
    end

    %% Support Elements
    subgraph "Support"
        DOC["Documentation"]:::docs
        TS["Test Suite"]:::tests
    end

    %% Connections
    U -->|"triggers"| CORE
    PY -->|"configures"| CORE
    RT -->|"configures"| CORE

    CORE -->|"delegates"| BP
    CORE -->|"delegates"| CV
    CORE -->|"delegates"| OP
    CORE -->|"delegates"| SV

    CORE -->|"utilizes"| BW
    CORE -->|"utilizes"| PYMO

    BP -->|"integrates"| BW
    OP -->|"integrates"| PYMO

    CORE -->|"supported_by"| DOC
    CORE -->|"validated_by"| TS

    %% Click Events
    click U "https://github.com/flechtenberg/pulpo/tree/master/notebooks/"
    click CORE "https://github.com/flechtenberg/pulpo/blob/master/pulpo/pulpo.py"
    click BP "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/bw_parser.py"
    click CV "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/converter.py"
    click OP "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/optimizer.py"
    click SV "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/saver.py"
    click BW "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/bw_parser.py"
    click PYMO "https://github.com/flechtenberg/pulpo/blob/master/pulpo/utils/optimizer.py"
    click DOC "https://github.com/flechtenberg/pulpo/tree/master/docs/"
    click TS "https://github.com/flechtenberg/pulpo/tree/master/tests/"
    click PY "https://github.com/flechtenberg/pulpo/blob/master/pyproject.toml"
    click RT "https://github.com/flechtenberg/pulpo/blob/master/requirements.txt"

    %% Styles
    classDef user fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef utility fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#ff9900,stroke-width:2px;
    classDef docs fill:#e6e6fa,stroke:#663399,stroke-width:2px;
    classDef tests fill:#fff0f5,stroke:#ff66cc,stroke-width:2px;
    classDef configFile fill:#d9edf7,stroke:#31708f,stroke-width:2px;
```
