processforge 0.2.14__tar.gz → 0.2.15__tar.gz

{processforge-0.2.14/src/processforge.egg-info → processforge-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.14
+Version: 0.2.15
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Process Forge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause
@@ -223,12 +223,27 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 ```json
 {
   "metadata": { "name": "My Flowsheet", "version": "2.0" },
+  "materials": {
+    "Water":   { "friendly_material_id": 1 },
+    "Toluene": { "friendly_material_id": 2 },
+    "Steel":   { "friendly_material_id": 3 }
+  },
+  "material_mixes": {
+    "Water_Toluene_Mix": {
+      "friendly_material_mix_id": 1,
+      "percent_type": "ao",
+      "components": [
+        { "name": "Water",   "fraction": 0.8 },
+        { "name": "Toluene", "fraction": 0.2 }
+      ]
+    }
+  },
   "streams": {
-    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
   },
   "units": {
-    "pump_1": { "type": "Pump", "in": "feed", "out": "after_pump", "deltaP": 200000, "efficiency": 0.75 },
-    "valve_1": { "type": "Valve", "in": "after_pump", "out": "product", "pressure_ratio": 0.5 }
+    "pump_1":  { "type": "Pump",  "in": "feed",       "out": "after_pump", "deltaP": 200000, "efficiency": 0.75, "material": 3 },
+    "valve_1": { "type": "Valve", "in": "after_pump",  "out": "product",   "pressure_ratio": 0.5,                "material": 3 }
   },
   "simulation": {
     "mode": "steady",
@@ -239,6 +254,40 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 
 The optional `backend` key selects the EO solver backend (`"scipy"`, `"pyomo"`, or `"casadi"`). Defaults to `"scipy"`.
 
+### Materials and composition
+
+Stream composition can be defined in two ways:
+
+**Explicit `z` dict** — list component mole fractions directly on the stream:
+```json
+"feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+```
+
+**`material_mix` reference** — define a reusable mix in the top-level `material_mixes` section and reference it by `friendly_material_mix_id`. The validator automatically expands the reference into a `z` dict before simulation:
+```json
+"material_mixes": {
+  "Water_Toluene_Mix": {
+    "friendly_material_mix_id": 1,
+    "percent_type": "ao",
+    "components": [
+      { "name": "Water",   "fraction": 0.8 },
+      { "name": "Toluene", "fraction": 0.2 }
+    ]
+  }
+},
+"streams": {
+  "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
+}
+```
+
+Rules:
+- `z` and `material_mix` are mutually exclusive on a single stream.
+- `friendly_material_mix_id` values must be unique across all mixes.
+- Each component `name` in a mix must match a key in the top-level `materials` section.
+- When all component fractions are provided they must sum to 1.0.
+
+Every unit also requires a `material` integer field pointing to a `friendly_material_id` in the `materials` section (this identifies the structural material the unit is made of, separate from the fluid composition).
+
 ### Recycle streams
 
 Recycle streams require no special configuration. Any stream produced as the `out` of one unit can be used as the `in` of any other unit — including upstream units. The EO solver resolves the full coupled system simultaneously.

{processforge-0.2.14 → processforge-0.2.15}/README.md

@@ -172,12 +172,27 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 ```json
 {
   "metadata": { "name": "My Flowsheet", "version": "2.0" },
+  "materials": {
+    "Water":   { "friendly_material_id": 1 },
+    "Toluene": { "friendly_material_id": 2 },
+    "Steel":   { "friendly_material_id": 3 }
+  },
+  "material_mixes": {
+    "Water_Toluene_Mix": {
+      "friendly_material_mix_id": 1,
+      "percent_type": "ao",
+      "components": [
+        { "name": "Water",   "fraction": 0.8 },
+        { "name": "Toluene", "fraction": 0.2 }
+      ]
+    }
+  },
   "streams": {
-    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
   },
   "units": {
-    "pump_1": { "type": "Pump", "in": "feed", "out": "after_pump", "deltaP": 200000, "efficiency": 0.75 },
-    "valve_1": { "type": "Valve", "in": "after_pump", "out": "product", "pressure_ratio": 0.5 }
+    "pump_1":  { "type": "Pump",  "in": "feed",       "out": "after_pump", "deltaP": 200000, "efficiency": 0.75, "material": 3 },
+    "valve_1": { "type": "Valve", "in": "after_pump",  "out": "product",   "pressure_ratio": 0.5,                "material": 3 }
   },
   "simulation": {
     "mode": "steady",
@@ -188,6 +203,40 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 
 The optional `backend` key selects the EO solver backend (`"scipy"`, `"pyomo"`, or `"casadi"`). Defaults to `"scipy"`.
 
+### Materials and composition
+
+Stream composition can be defined in two ways:
+
+**Explicit `z` dict** — list component mole fractions directly on the stream:
+```json
+"feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+```
+
+**`material_mix` reference** — define a reusable mix in the top-level `material_mixes` section and reference it by `friendly_material_mix_id`. The validator automatically expands the reference into a `z` dict before simulation:
+```json
+"material_mixes": {
+  "Water_Toluene_Mix": {
+    "friendly_material_mix_id": 1,
+    "percent_type": "ao",
+    "components": [
+      { "name": "Water",   "fraction": 0.8 },
+      { "name": "Toluene", "fraction": 0.2 }
+    ]
+  }
+},
+"streams": {
+  "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
+}
+```
+
+Rules:
+- `z` and `material_mix` are mutually exclusive on a single stream.
+- `friendly_material_mix_id` values must be unique across all mixes.
+- Each component `name` in a mix must match a key in the top-level `materials` section.
+- When all component fractions are provided they must sum to 1.0.
+
+Every unit also requires a `material` integer field pointing to a `friendly_material_id` in the `materials` section (this identifies the structural material the unit is made of, separate from the fluid composition).
+
 ### Recycle streams
 
 Recycle streams require no special configuration. Any stream produced as the `out` of one unit can be used as the `in` of any other unit — including upstream units. The EO solver resolves the full coupled system simultaneously.

{processforge-0.2.14 → processforge-0.2.15}/flowsheets/closed-loop-chain.json

@@ -52,10 +52,6 @@
     "feed": {
       "T": 298.15,
       "P": 101325,
-      "z": {
-        "Benzene": 0.5,
-        "Toluene": 0.5
-      },
       "flowrate": 0.1,
       "material_mix": 1
     }

{processforge-0.2.14 → processforge-0.2.15}/flowsheets/hydraulic-chain.json

@@ -4,15 +4,33 @@
     "description": "A two-pump, one-valve, one-strainer steady-state hydraulic system.",
     "version": "2.0"
   },
+  "materials": {
+    "Water": {
+      "friendly_material_id": 1
+    },
+    "Toluene": {
+      "friendly_material_id": 2
+    },
+    "Steel": {
+      "friendly_material_id": 3
+    }
+  },
+  "material_mixes": {
+    "Water_Toluene_Mix": {
+      "friendly_material_mix_id": 1,
+      "percent_type": "ao",
+      "components": [
+        {"name": "Water", "fraction": 0.8},
+        {"name": "Toluene", "fraction": 0.2}
+      ]
+    }
+  },
   "streams": {
     "feed": {
       "T": 298.15,
       "P": 101325,
-      "z": {
-        "Water": 0.8,
-        "Toluene": 0.2
-      },
-      "flowrate": 1.0
+      "flowrate": 1.0,
+      "material_mix": 1
     }
   },
   "units": {
@@ -21,54 +39,62 @@
       "in": "feed",
       "out": "after_pump_1",
       "deltaP": 200000.0,
-      "efficiency": 0.75
+      "efficiency": 0.75,
+      "material": 3
     },
     "pipe_1": {
       "type": "Pipes",
       "in": "after_pump_1",
       "out": "after_pipe_1",
       "delta_p": 1000.0,
-      "diameter": 0.05
+      "diameter": 0.05,
+      "material": 3
     },
     "valve_1": {
       "type": "Valve",
       "in": "after_pipe_1",
       "out": "after_valve_1",
-      "pressure_ratio": 0.5
+      "pressure_ratio": 0.5,
+      "material": 3
     },
     "pipe_2": {
       "type": "Pipes",
       "in": "after_valve_1",
       "out": "after_pipe_2",
       "delta_p": 1000.0,
-      "diameter": 0.08
+      "diameter": 0.08,
+      "material": 3
     },
     "strainer_1": {
       "type": "Strainer",
       "in": "after_pipe_2",
       "out": "after_strainer_1",
-      "deltaP": 5000.0
+      "deltaP": 5000.0,
+      "material": 3
     },
     "pipe_3": {
       "type": "Pipes",
       "in": "after_strainer_1",
       "out": "after_pipe_3",
       "delta_p": 1000.0,
-      "diameter": 0.1
+      "diameter": 0.1,
+      "material": 3
     },
     "pump_2": {
       "type": "Pump",
       "in": "after_pipe_3",
       "out": "after_pump_2",
       "deltaP": 300000.0,
-      "efficiency": 0.8
+      "efficiency": 0.8,
+      "material": 3
     },
     "pipe_4": {
       "type": "Pipes",
       "in": "after_pump_2",
       "out": "product",
       "delta_p": 1000.0,
-      "diameter": 0.12
+      "diameter": 0.12,
+      "material": 3
     }
   },
   "simulation": {

{processforge-0.2.14 → processforge-0.2.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.2.14"
+version = "0.2.15"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"

{processforge-0.2.14 → processforge-0.2.15}/src/processforge/utils/validate_flowsheet.py

@@ -33,6 +33,7 @@ def validate_flowsheet(config_path):
         logger.info(f"✅ Flowsheet '{config_path}' is valid.")
         check_stream_connectivity(config)
         _check_material_semantics(config)
+        _resolve_material_mix_streams(config)
         return config
     except ValidationError as e:
         logger.error(f"❌ Validation failed for '{config_path}':")
@@ -237,6 +238,15 @@ def _check_material_semantics(config):
                         f"❌ Stream '{stream_name}' z-key '{comp_name}' is not defined in materials."
                     )
 
+        # 5b. z and material_mix are mutually exclusive on a stream
+        for stream_name, stream_def in config.get("streams", {}).items():
+            if "z" in stream_def and "material_mix" in stream_def:
+                raise ValueError(
+                    f"❌ Stream '{stream_name}' defines both 'z' and 'material_mix'. "
+                    f"Use 'material_mix' to reference a predefined mix, or 'z' for an "
+                    f"explicit composition — not both."
+                )
+
         # 6. Stream material_mix references must resolve to a valid friendly_material_mix_id
         valid_mix_ids = {
             mix_def["friendly_material_mix_id"]
@@ -261,3 +271,46 @@ def _check_material_semantics(config):
             )
 
     return True
+
+
+def _resolve_material_mix_streams(config: dict) -> dict:
+    """Expand material_mix references on streams into z composition dicts.
+
+    For every stream that carries a ``material_mix`` integer
+    (a ``friendly_material_mix_id``), this function looks up the corresponding
+    mix definition and writes its component fractions into ``stream["z"]``.
+    This expansion happens after validation so that the solver receives a fully
+    populated ``z`` dict regardless of whether the author wrote ``z`` explicitly
+    or used a ``material_mix`` reference.
+
+    The mutual-exclusivity rule (``z`` and ``material_mix`` cannot coexist) is
+    enforced earlier in ``_check_material_semantics``, so by the time this
+    function runs every stream has at most one of the two.
+
+    Args:
+        config: Validated flowsheet configuration dict (mutated in place).
+
+    Returns:
+        The same config dict with ``z`` populated on any stream that had
+        ``material_mix``.
+    """
+    material_mixes = config.get("material_mixes", {})
+    if not material_mixes:
+        return config
+
+    id_to_mix = {
+        mix_def["friendly_material_mix_id"]: mix_def
+        for mix_def in material_mixes.values()
+    }
+
+    for stream_def in config.get("streams", {}).values():
+        mix_ref = stream_def.get("material_mix")
+        if mix_ref is not None:
+            mix = id_to_mix[mix_ref]  # existence already validated
+            stream_def["z"] = {
+                comp["name"]: comp["fraction"]
+                for comp in mix["components"]
+                if "fraction" in comp
+            }
+
+    return config

{processforge-0.2.14 → processforge-0.2.15/src/processforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.14
+Version: 0.2.15
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Process Forge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause
@@ -223,12 +223,27 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 ```json
 {
   "metadata": { "name": "My Flowsheet", "version": "2.0" },
+  "materials": {
+    "Water":   { "friendly_material_id": 1 },
+    "Toluene": { "friendly_material_id": 2 },
+    "Steel":   { "friendly_material_id": 3 }
+  },
+  "material_mixes": {
+    "Water_Toluene_Mix": {
+      "friendly_material_mix_id": 1,
+      "percent_type": "ao",
+      "components": [
+        { "name": "Water",   "fraction": 0.8 },
+        { "name": "Toluene", "fraction": 0.2 }
+      ]
+    }
+  },
   "streams": {
-    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+    "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
   },
   "units": {
-    "pump_1": { "type": "Pump", "in": "feed", "out": "after_pump", "deltaP": 200000, "efficiency": 0.75 },
-    "valve_1": { "type": "Valve", "in": "after_pump", "out": "product", "pressure_ratio": 0.5 }
+    "pump_1":  { "type": "Pump",  "in": "feed",       "out": "after_pump", "deltaP": 200000, "efficiency": 0.75, "material": 3 },
+    "valve_1": { "type": "Valve", "in": "after_pump",  "out": "product",   "pressure_ratio": 0.5,                "material": 3 }
   },
   "simulation": {
     "mode": "steady",
@@ -239,6 +254,40 @@ Flowsheets are defined as JSON files. The `simulation.mode` field controls which
 
 The optional `backend` key selects the EO solver backend (`"scipy"`, `"pyomo"`, or `"casadi"`). Defaults to `"scipy"`.
 
+### Materials and composition
+
+Stream composition can be defined in two ways:
+
+**Explicit `z` dict** — list component mole fractions directly on the stream:
+```json
+"feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "z": { "Water": 0.8, "Toluene": 0.2 } }
+```
+
+**`material_mix` reference** — define a reusable mix in the top-level `material_mixes` section and reference it by `friendly_material_mix_id`. The validator automatically expands the reference into a `z` dict before simulation:
+```json
+"material_mixes": {
+  "Water_Toluene_Mix": {
+    "friendly_material_mix_id": 1,
+    "percent_type": "ao",
+    "components": [
+      { "name": "Water",   "fraction": 0.8 },
+      { "name": "Toluene", "fraction": 0.2 }
+    ]
+  }
+},
+"streams": {
+  "feed": { "T": 298.15, "P": 101325, "flowrate": 1.0, "material_mix": 1 }
+}
+```
+
+Rules:
+- `z` and `material_mix` are mutually exclusive on a single stream.
+- `friendly_material_mix_id` values must be unique across all mixes.
+- Each component `name` in a mix must match a key in the top-level `materials` section.
+- When all component fractions are provided they must sum to 1.0.
+
+Every unit also requires a `material` integer field pointing to a `friendly_material_id` in the `materials` section (this identifies the structural material the unit is made of, separate from the fluid composition).
+
 ### Recycle streams
 
 Recycle streams require no special configuration. Any stream produced as the `out` of one unit can be used as the `in` of any other unit — including upstream units. The EO solver resolves the full coupled system simultaneously.