exergyflow 0.1.0__tar.gz

exergyflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Andrés Gómez González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exergyflow-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include docs/STEP_BY_STEP.md
+include docs/CHEATSHEET.md
+include docs/diagram.svg
+include LICENSE
+include pyproject.toml
+include requirements.txt
+recursive-exclude __pycache__ *
+recursive-exclude tests __pycache__ *

exergyflow-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: exergyflow
+Version: 0.1.0
+Summary: Sankey and Grassmann diagrams for energy and exergy analysis
+Author-email: Juan Andrés Gómez González <ja.gomez@uniandes.edu.co>
+License: MIT License
+        
+        Copyright (c) 2026 Juan Andrés Gómez González
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/GOMGON777/exergyflow
+Project-URL: Issues, https://github.com/GOMGON777/exergyflow/issues
+Keywords: exergy,energy,grassmann,grassmann diagram,grassmann diagrams,sankey,sankey diagram,sankey diagrams,thermodynamics,thermodynamic analysis,visualization,flow visualization,data visualization,engineering,process engineering,thermal systems,exergy analysis,energy analysis,flow diagram,scientific visualization,python sankey,python exergy,python thermodynamics,brayton cycle,rankine cycle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.23
+Dynamic: license-file
+
+# ExergyFlow
+
+Grassmann/Sankey diagrams for energy and exergy analysis
+
+![ExergyFlow diagram](docs/diagram.svg)
+
+## Install
+```bash
+python -m pip install exergyflow
+```
+
+## Quickstart
+```python
+from exergyflow import Diagram, DiagramConfig, RouteSegment
+d = Diagram(DiagramConfig(auto_scale=True, auto_scale_target=1.0))
+d.add_process("P1")
+d.add_flow("F1", 10, source=None, target="P1")
+d.add_flow("F2", 5, source="P1", target=None)
+route1 = [RouteSegment(kind='rect', length=0.25, direction='right'),
+          RouteSegment(kind='elbow', length=0.25, turn='rightup'),
+          RouteSegment(kind='rect', length=0.5, direction='up')]
+d.add_flow("F3", 2, source="P1", target=None, route=route1)
+fig, ax = d.draw()
+fig.savefig("diagram.png", dpi=300, bbox_inches="tight")
+```
+
+## Real engineering example
+A simplified Brayton flow sketch (values illustrative):
+```python
+from exergyflow import Diagram, DiagramConfig, RouteSegment
+
+cfg = DiagramConfig(flow_value_unit="kW", flow_value_format=".0f",
+                    auto_scale=True, auto_scale_target=2.0)
+d = Diagram(cfg)
+
+# Processes
+d.add_process("Compressor", direction="up", length=2.5,
+              label_rotation=90, color="#59a2d3")
+d.add_process("Combustor", direction="right", length=2.5, color="#59a2d3")
+d.add_process("Turbine", direction="down", label_rotation=-90, color="#59a2d3")
+
+# Routes
+route_work_out = [
+    RouteSegment(kind='rect', length=0.25, direction='down'),
+    RouteSegment(kind='elbow', length=0.5, turn='downright'),
+    RouteSegment(kind='rect', length=2.5, direction='right')
+]
+route_exhaust = [
+    RouteSegment(kind='rect', length=1.5, direction='down'),
+    RouteSegment(kind='elbow', length=0.5, turn='downright'),
+    RouteSegment(kind='rect', length=2.6, direction='right')
+]
+route_air = [
+    RouteSegment(kind='rect', length=3.5, direction='right'),
+    RouteSegment(kind='elbow', length=0.5, turn='rightup'),
+    RouteSegment(kind='rect', length=0.5, direction='up')
+]
+
+# Flows
+d.add_flow("Work_out", 220, source="Turbine",
+           target=None, label="W_t", route=route_work_out)
+d.add_flow("Exhaust", 180, source="Turbine", target=None,
+           label="E_exh", route=route_exhaust)
+d.add_flow("Work_in", 80, source="Turbine",
+           target="Compressor", label="W_c", cycle_breaker=True, label_dy=-0.3)
+d.add_flow("Air", 280, source=None,
+           target="Compressor", label="E_air", route=route_air)
+d.add_flow("Compressed", 300, source="Compressor",
+           target="Combustor", label="E_2", label_dy=0.2)
+d.add_flow("Fuel", 700, source=None,
+           target="Combustor", length=7.75, label="E_f")
+d.add_flow("Hot_gas", 560, source="Combustor",
+           target="Turbine", label="E_3", label_dy=0.2)
+fig, ax = d.draw()
+fig.savefig("brayton.svg", dpi=300, bbox_inches="tight")
+```
+
+## Advantages
+- Built for thermodynamic energy and exergy conventions, including imbalance triangles and process-aware flow direction rules.
+- Auto-layout for fast drafts, manual routing for publication-grade control.
+- Matplotlib-native output for crisp vector export (SVG/PDF) without extra tooling.
+- Deterministic layout and explicit routing rules help reproduce figures consistently.
+- Built-in unit formatting for labels keeps diagrams engineering-ready.
+
+## Details
+- Supported Python versions: 3.9–3.14 (see `pyproject.toml`).
+- `flow_label_mode` options: `name_value_units` (default), `value_units`, `value_only`.
+- Units formatting: `flow_value_unit`, `flow_value_format`, `flow_value_unit_sep`.
+- Auto-layout expects a DAG; use `cycle_breaker=True` on a process→process flow to break cycles.
+- Manual routing must alternate `rect` and `elbow` segments and start/end with `rect`.
+- Matplotlib-native output: export PNG, SVG, or PDF via `fig.savefig(...)`.
+
+## Docs
+- [Step-by-step guide](docs/STEP_BY_STEP.md)
+- [Cheatsheet](docs/CHEATSHEET.md)
+
+## Adavanced example
+For an advanced example see: [Example script](examples/grassmann_example.py)

exergyflow-0.1.0/README.md

@@ -0,0 +1,98 @@
+# ExergyFlow
+
+Grassmann/Sankey diagrams for energy and exergy analysis
+
+![ExergyFlow diagram](docs/diagram.svg)
+
+## Install
+```bash
+python -m pip install exergyflow
+```
+
+## Quickstart
+```python
+from exergyflow import Diagram, DiagramConfig, RouteSegment
+d = Diagram(DiagramConfig(auto_scale=True, auto_scale_target=1.0))
+d.add_process("P1")
+d.add_flow("F1", 10, source=None, target="P1")
+d.add_flow("F2", 5, source="P1", target=None)
+route1 = [RouteSegment(kind='rect', length=0.25, direction='right'),
+          RouteSegment(kind='elbow', length=0.25, turn='rightup'),
+          RouteSegment(kind='rect', length=0.5, direction='up')]
+d.add_flow("F3", 2, source="P1", target=None, route=route1)
+fig, ax = d.draw()
+fig.savefig("diagram.png", dpi=300, bbox_inches="tight")
+```
+
+## Real engineering example
+A simplified Brayton flow sketch (values illustrative):
+```python
+from exergyflow import Diagram, DiagramConfig, RouteSegment
+
+cfg = DiagramConfig(flow_value_unit="kW", flow_value_format=".0f",
+                    auto_scale=True, auto_scale_target=2.0)
+d = Diagram(cfg)
+
+# Processes
+d.add_process("Compressor", direction="up", length=2.5,
+              label_rotation=90, color="#59a2d3")
+d.add_process("Combustor", direction="right", length=2.5, color="#59a2d3")
+d.add_process("Turbine", direction="down", label_rotation=-90, color="#59a2d3")
+
+# Routes
+route_work_out = [
+    RouteSegment(kind='rect', length=0.25, direction='down'),
+    RouteSegment(kind='elbow', length=0.5, turn='downright'),
+    RouteSegment(kind='rect', length=2.5, direction='right')
+]
+route_exhaust = [
+    RouteSegment(kind='rect', length=1.5, direction='down'),
+    RouteSegment(kind='elbow', length=0.5, turn='downright'),
+    RouteSegment(kind='rect', length=2.6, direction='right')
+]
+route_air = [
+    RouteSegment(kind='rect', length=3.5, direction='right'),
+    RouteSegment(kind='elbow', length=0.5, turn='rightup'),
+    RouteSegment(kind='rect', length=0.5, direction='up')
+]
+
+# Flows
+d.add_flow("Work_out", 220, source="Turbine",
+           target=None, label="W_t", route=route_work_out)
+d.add_flow("Exhaust", 180, source="Turbine", target=None,
+           label="E_exh", route=route_exhaust)
+d.add_flow("Work_in", 80, source="Turbine",
+           target="Compressor", label="W_c", cycle_breaker=True, label_dy=-0.3)
+d.add_flow("Air", 280, source=None,
+           target="Compressor", label="E_air", route=route_air)
+d.add_flow("Compressed", 300, source="Compressor",
+           target="Combustor", label="E_2", label_dy=0.2)
+d.add_flow("Fuel", 700, source=None,
+           target="Combustor", length=7.75, label="E_f")
+d.add_flow("Hot_gas", 560, source="Combustor",
+           target="Turbine", label="E_3", label_dy=0.2)
+fig, ax = d.draw()
+fig.savefig("brayton.svg", dpi=300, bbox_inches="tight")
+```
+
+## Advantages
+- Built for thermodynamic energy and exergy conventions, including imbalance triangles and process-aware flow direction rules.
+- Auto-layout for fast drafts, manual routing for publication-grade control.
+- Matplotlib-native output for crisp vector export (SVG/PDF) without extra tooling.
+- Deterministic layout and explicit routing rules help reproduce figures consistently.
+- Built-in unit formatting for labels keeps diagrams engineering-ready.
+
+## Details
+- Supported Python versions: 3.9–3.14 (see `pyproject.toml`).
+- `flow_label_mode` options: `name_value_units` (default), `value_units`, `value_only`.
+- Units formatting: `flow_value_unit`, `flow_value_format`, `flow_value_unit_sep`.
+- Auto-layout expects a DAG; use `cycle_breaker=True` on a process→process flow to break cycles.
+- Manual routing must alternate `rect` and `elbow` segments and start/end with `rect`.
+- Matplotlib-native output: export PNG, SVG, or PDF via `fig.savefig(...)`.
+
+## Docs
+- [Step-by-step guide](docs/STEP_BY_STEP.md)
+- [Cheatsheet](docs/CHEATSHEET.md)
+
+## Adavanced example
+For an advanced example see: [Example script](examples/grassmann_example.py)

exergyflow-0.1.0/docs/CHEATSHEET.md

@@ -0,0 +1,103 @@
+# ExergyFlow Cheatsheet
+
+Quick reference for `DiagramConfig`, `Diagram.add_process(...)`, and `Diagram.add_flow(...)`.
+
+## Core Concepts
+- **Diagram**: container for processes and flows; supports auto-layout and auto-routing.
+- **Process**: a rectangular block that can show imbalance via a right triangle.
+- **Flow**: a magnitude drawn as a band (rectangles + elbows); width scales with value.
+
+## Key Rules
+- Flow routes must start/end with a `rect` and alternate `rect`/`elbow`.
+- Elbows are quarter-annulus turns; thickness equals the flow width.
+- Elbow turns use labels like `rightup`, `rightdown`, `leftup`, `leftdown`, `upright`, `downright`, `upleft`, `downleft` which correspond to the change in direction (e.g. rightup is an elbow that changes the flow direction from right to up).
+- `label_rotation` is in degrees; for flows, vertical segments auto-rotate to 90 if `None`.
+- Process directions: `right`, `left`, `up`, `down`.
+- Inlet flows must end with a direction that matches the process direction.
+- Outlet flows must start with a direction that matches the process direction.
+
+### RouteSegment (for manual `route`)
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `kind` | `str` | `rect` or `elbow`. |
+| `length` | `float` | Rect: section length. Elbow: inner radius. |
+| `direction` | `str \| None` | Required for `rect`: `right`, `left`, `up`, `down`. |
+| `turn` | `str \| None` | Required for `elbow`: `rightup`, `rightdown`, `leftup`, `leftdown`, `upright`, `downright`, `upleft`, `downleft` |
+
+Manual routes must alternate `rect`/`elbow` segments and start/end with `rect`.
+
+## DiagramConfig
+Create with `DiagramConfig(...)` and pass into `Diagram(config=...)`.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `scale` | `float` | `1.0` | Multiplies all flow magnitudes for drawing. |
+| `auto_scale` | `bool` | `False` | Auto-scales flows so the largest value maps to `auto_scale_target`. |
+| `auto_scale_target` | `float` | `1.0` | Target width for the largest flow when `auto_scale=True`. |
+| `flow_label_mode` | `str` | `"name_value_units"` | Options: `name_value_units`, `value_units`, `value_only`. |
+| `flow_value_format` | `str \| None` | `None` | Python format spec, e.g. `".2f"` or `".3g"`. |
+| `flow_value_unit` | `str \| None` | `None` | Unit label appended when enabled by `flow_label_mode`. |
+| `flow_value_unit_sep` | `str` | `" "` | Separator between value and unit. |
+| `render_min_flow_width` | `float` | `0.0` | Minimum visible thickness for drawing only. |
+| `flow_label_style` | `dict` | `{"fontsize": 8, "color": "black"}` | Matplotlib text kwargs for flow labels. |
+| `process_label_style` | `dict` | `{"fontsize": 9, "color": "black"}` | Matplotlib text kwargs for process labels. |
+| `triangle_label_style` | `dict` | `{"fontsize": 8, "color": "black"}` | Matplotlib text kwargs for imbalance labels. |
+| `flow_gap` | `float` | `0.0` | Gap between stacked flows on a process edge. |
+| `layer_gap` | `float` | `2.0` | Gap between layout layers (auto-layout). |
+| `process_gap` | `float` | `1.0` | Gap between processes within a layer (auto-layout). |
+| `elbow_inner_radius` | `float` | `0.5` | Inner radius for elbow turns (auto-routing). |
+| `layout_direction` | `str` | `"right"` | Global layout direction: `right`, `left`, `up`, `down`. |
+| `min_straight` | `float` | `0.2` | Minimum straight length between elbows (auto-routing). |
+
+## Diagram.add_process(...)
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | `str` | required | Unique process name. |
+| `direction` | `str \| None` | `DiagramConfig.layout_direction` | `right`, `left`, `up`, `down`. |
+| `length` | `float \| None` | `1.8` | Process length along its direction. |
+| `color` | `str \| None` | `"#cfd8dc"` | Fill color. |
+| `triangle_side` | `str \| None` | `None` | If direction is `right/left`: `top` or `bottom`. If `up/down`: `left` or `right`. |
+| `overlay` | `bool \| None` | `False` | Draws an outline-only overlay rectangle. |
+| `overlay_height` | `float \| None` | `None` | Overlay size perpendicular to process direction. |
+| `overlay_edgecolor` | `str \| None` | `None` | Overlay border color. |
+| `overlay_linewidth` | `float \| None` | `None` | Overlay border width. |
+| `overlay_linestyle` | `str \| None` | `None` | Overlay border style. |
+| `overlay_alpha` | `float \| None` | `None` | Overlay border opacity. |
+| `label_dx` | `float` | `0.0` | X offset for the process label. |
+| `label_dy` | `float` | `0.0` | Y offset for the process label. |
+| `label_rotation` | `float \| None` | `None` | Rotation in degrees for the process label. |
+| `triangle_label` | `str \| None` | `None` | Optional label prefix for imbalance triangle. |
+| `triangle_label_dx` | `float` | `0.0` | X offset for triangle label. |
+| `triangle_label_dy` | `float` | `0.0` | Y offset for triangle label. |
+| `x` | `float \| None` | `None` | Fixed X position (skips auto-layout if set). |
+| `y` | `float \| None` | `None` | Fixed Y position (skips auto-layout if set). |
+
+## Diagram.add_flow(...)
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | `str` | required | Unique flow name. |
+| `value` | `float` | required | Flow magnitude (must be non‑negative). |
+| `source` | `str \| None` | `None` | Source process name or `None`/`"source"`. |
+| `target` | `str \| None` | `None` | Target process name or `None`/`"sink"`. |
+| `color` | `str \| None` | `"#7fb3d5"` | Flow fill color. |
+| `length` | `float \| None` | `2.2` | Default straight length (used when no manual route). |
+| `inlet_tri_height` | `float \| None` | `0.3` | Multiplier of flow width for inlet triangle depth. |
+| `outlet_tri_height` | `float \| None` | `0.6` | Multiplier of flow width for outlet triangle depth. |
+| `label_dx` | `float` | `0.0` | X offset for flow label. |
+| `label_dy` | `float` | `0.0` | Y offset for flow label. |
+| `label_rotation` | `float \| None` | `None` | Rotation in degrees for flow label. |
+| `cycle_breaker` | `bool` | `False` | Marks a process→process flow to break layout cycles. |
+| `route` | `list[RouteSegment] \| None` | `None` | Manual route; skips auto-routing. |
+| `label` | `str \| None` | `None` | Custom label name used in `name = value` mode. |
+
+## Where Things Live
+- `exergyflow/grassmann_types.py`: dataclasses and config
+- `exergyflow/grassmann_geometry.py`: geometry helpers
+- `exergyflow/grassmann_layout.py`: auto layout + routing
+- `exergyflow/grassmann_render.py`: drawing engine
+- `exergyflow/grassmann_diagram.py`: public API
+- `examples/grassmann_example.py`: example usage
+- `docs/diagram.svg`: example output (generated by the example script)

exergyflow-0.1.0/docs/STEP_BY_STEP.md

@@ -0,0 +1,61 @@
+# Step-by-Step: Build a Grassmann/Sankey Diagram
+
+This guide walks you through creating a diagram from scratch using the public API.
+
+**Step 1: Install dependencies**
+```bash
+python -m pip install exergyflow
+```
+
+**Step 2: Import the API**
+```python
+from exergyflow import Diagram, DiagramConfig, RouteSegment
+```
+
+**Step 3: Define a configuration (optional but recommended)**
+```python
+cfg = DiagramConfig(
+    auto_scale=True,
+    auto_scale_target=1.0,
+    flow_value_unit="kW",
+    flow_value_format=".2f",
+    flow_label_style={"fontsize": 8, "color": "#1d3557"},
+    process_label_style={"fontsize": 9, "fontweight": "bold"},
+    triangle_label_style={"fontsize": 8, "color": "#444444"},
+)
+```
+
+**Step 4: Create the diagram and add processes**
+```python
+d = Diagram(config=cfg)
+
+d.add_process("P1", direction="right", length=1.6)
+d.add_process("P2", direction="right", length=1.2)
+```
+
+**Step 5: Add flows**
+Use `source=None` for a source and `target=None` for a sink.
+```python
+d.add_flow("F1", 10, source=None, target="P1")
+d.add_flow("F2", 8, source="P1", target="P2", label="Q_in")
+d.add_flow("F3", 2, source="P1", target=None)
+d.add_flow("F4", 6, source="P2", target=None)
+```
+
+**Step 6: (Optional) Add a manual route**
+Manual routes must alternate `rect` and `elbow`, and start/end with `rect`.
+```python
+route = [
+    RouteSegment(kind="rect", length=1.5, direction="right"),
+    RouteSegment(kind="elbow", length=0.4, turn="rightup"),
+    RouteSegment(kind="rect", length=1.0, direction="up"),
+]
+
+d.add_flow("F5", 3, source="P1", target="P2", route=route)
+```
+
+**Step 7: Draw and save**
+```python
+fig, ax = d.draw()
+fig.savefig("diagram.png", dpi=300, bbox_inches="tight")
+```