OpenPyTEA 2.0.0__tar.gz → 2.1.0__tar.gz

{openpytea-2.0.0/src/OpenPyTEA.egg-info → openpytea-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenPyTEA
-Version: 2.0.0
+Version: 2.1.0
 Summary: OpenPyTEA: An open-source Python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation
 Maintainer-email: "Panji B. Tamarona" <P.B.Tamarona@tudelft.nl>
 License-Expression: MIT
@@ -97,11 +97,30 @@ src/openpytea/
 ├── helpers.py              # Helper functions for data handling and common operations
 └── data/                   # Cost correlations database and CEPCI data
 examples/                   # Example notebooks and case studies
-walkthrough.ipynb           # walkthrough of the package
+walkthrough.ipynb           # Walkthrough of the package
+
+backend/                    # FastAPI backend for the web GUI
+├── app/
+│   ├── main.py             # FastAPI app with CORS and router mounting
+│   ├── state.py            # In-memory session state
+│   ├── schemas.py          # Pydantic request/response models
+│   ├── util.py             # JSON serialization utilities
+│   ├── routers/            # API endpoints (equipment, plant, analysis, I/O)
+│   └── presets/            # Example preset JSON files
+└── requirements.txt
+
+frontend/                   # React + TypeScript web GUI
+├── src/
+│   ├── api/client.ts       # Typed API client
+│   ├── types/index.ts      # TypeScript interfaces
+│   ├── pages/              # Equipment, Plant Config, Results, Analysis, Monte Carlo, Compare
+│   ├── App.tsx             # Tab navigation + examples dropdown
+│   └── App.css             # Styling
+└── package.json
+
 pyproject.toml
 README.md
 ```
-
 ---
 
 ## 🏗️ Software Architecture
@@ -112,6 +131,42 @@ Software architecture and data flow of **OpenPyTEA**, illustrating the progressi
 
 ---
 
+## 🖥️ Web GUI (**work in progress**)
+
+OpenPyTEA includes an optional web-based graphical interface for users who prefer a visual workflow over Python scripting. The GUI provides the full TEA workflow through a tabbed browser interface:
+
+- **Equipment** — add, edit, and remove equipment with cost database lookup
+- **Plant Config** — configure location, financial parameters, labor, products, and variable OPEX
+- **Results** — run calculations and view metric cards, cost breakdown charts, and cash flow tables
+- **Analysis** — sensitivity plots and tornado diagrams. Sensitivity supports a **multi-panel grid** (different parameter and metric per panel, e.g. NPV vs. interest rate, ROI vs. electricity price, all in one figure) and **multi-plant overlay** (curves for every plant added on the Compare tab share the same axes for direct comparison)
+- **Monte Carlo** — uncertainty analysis with histogram distributions, fitted normal curves, and summary statistics. **Multi-plant overlay** shows distributions for several plants on the same axes, mirroring `plot_multiple_monte_carlo` from the library
+- **Compare** — side-by-side comparison of saved plants (CAPEX/OPEX breakdown bars, key metric bars). Plants imported here are also reused as the overlay set on the Analysis and Monte Carlo tabs
+- **Downloadable charts** — all plots include a download button to export as standalone PNG images with full axis labels
+- **Examples** — built-in presets from the case study notebooks for quick demonstration
+
+### Running the GUI
+
+**Backend** (requires Python 3.10+):
+```bash
+pip install -e .          # install OpenPyTEA from repo root
+cd backend
+pip install -r requirements.txt
+PYTHONPATH=../src python3 -m uvicorn app.main:app --reload --port 8000
+```
+
+**Frontend** (requires Node.js):
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:5173. Click **Examples** in the header to load a case study preset and explore.
+
+For detailed architecture documentation, see `GUI_ARCHITECTURE.md`.
+
+---
+
 ## 🧠 Core Concepts
 
 ### 1. **Equipment-level costing**
@@ -299,7 +354,7 @@ Or if you prefer to cite manually, you may use:
   title        = {OpenPyTEA: An open-source python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation},
   year         = {2025},
   url          = {\url{https://github.com/pbtamarona/OpenPyTEA}},
-  version      = {1.2.0},
+  version      = {2.0.0},
   note         = {Accessed: YYYY-MM-DD}
 }
 ```

{openpytea-2.0.0 → openpytea-2.1.0}/README.md

@@ -73,11 +73,30 @@ src/openpytea/
 ├── helpers.py              # Helper functions for data handling and common operations
 └── data/                   # Cost correlations database and CEPCI data
 examples/                   # Example notebooks and case studies
-walkthrough.ipynb           # walkthrough of the package
+walkthrough.ipynb           # Walkthrough of the package
+
+backend/                    # FastAPI backend for the web GUI
+├── app/
+│   ├── main.py             # FastAPI app with CORS and router mounting
+│   ├── state.py            # In-memory session state
+│   ├── schemas.py          # Pydantic request/response models
+│   ├── util.py             # JSON serialization utilities
+│   ├── routers/            # API endpoints (equipment, plant, analysis, I/O)
+│   └── presets/            # Example preset JSON files
+└── requirements.txt
+
+frontend/                   # React + TypeScript web GUI
+├── src/
+│   ├── api/client.ts       # Typed API client
+│   ├── types/index.ts      # TypeScript interfaces
+│   ├── pages/              # Equipment, Plant Config, Results, Analysis, Monte Carlo, Compare
+│   ├── App.tsx             # Tab navigation + examples dropdown
+│   └── App.css             # Styling
+└── package.json
+
 pyproject.toml
 README.md
 ```
-
 ---
 
 ## 🏗️ Software Architecture
@@ -88,6 +107,42 @@ Software architecture and data flow of **OpenPyTEA**, illustrating the progressi
 
 ---
 
+## 🖥️ Web GUI (**work in progress**)
+
+OpenPyTEA includes an optional web-based graphical interface for users who prefer a visual workflow over Python scripting. The GUI provides the full TEA workflow through a tabbed browser interface:
+
+- **Equipment** — add, edit, and remove equipment with cost database lookup
+- **Plant Config** — configure location, financial parameters, labor, products, and variable OPEX
+- **Results** — run calculations and view metric cards, cost breakdown charts, and cash flow tables
+- **Analysis** — sensitivity plots and tornado diagrams. Sensitivity supports a **multi-panel grid** (different parameter and metric per panel, e.g. NPV vs. interest rate, ROI vs. electricity price, all in one figure) and **multi-plant overlay** (curves for every plant added on the Compare tab share the same axes for direct comparison)
+- **Monte Carlo** — uncertainty analysis with histogram distributions, fitted normal curves, and summary statistics. **Multi-plant overlay** shows distributions for several plants on the same axes, mirroring `plot_multiple_monte_carlo` from the library
+- **Compare** — side-by-side comparison of saved plants (CAPEX/OPEX breakdown bars, key metric bars). Plants imported here are also reused as the overlay set on the Analysis and Monte Carlo tabs
+- **Downloadable charts** — all plots include a download button to export as standalone PNG images with full axis labels
+- **Examples** — built-in presets from the case study notebooks for quick demonstration
+
+### Running the GUI
+
+**Backend** (requires Python 3.10+):
+```bash
+pip install -e .          # install OpenPyTEA from repo root
+cd backend
+pip install -r requirements.txt
+PYTHONPATH=../src python3 -m uvicorn app.main:app --reload --port 8000
+```
+
+**Frontend** (requires Node.js):
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:5173. Click **Examples** in the header to load a case study preset and explore.
+
+For detailed architecture documentation, see `GUI_ARCHITECTURE.md`.
+
+---
+
 ## 🧠 Core Concepts
 
 ### 1. **Equipment-level costing**
@@ -275,7 +330,7 @@ Or if you prefer to cite manually, you may use:
   title        = {OpenPyTEA: An open-source python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation},
   year         = {2025},
   url          = {\url{https://github.com/pbtamarona/OpenPyTEA}},
-  version      = {1.2.0},
+  version      = {2.0.0},
   note         = {Accessed: YYYY-MM-DD}
 }
 ```

{openpytea-2.0.0 → openpytea-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "OpenPyTEA"
-version = "2.0.0"
+version = "2.1.0"
 description = "OpenPyTEA: An open-source Python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation"
 readme = "README.md"
 license = "MIT"

{openpytea-2.0.0 → openpytea-2.1.0/src/OpenPyTEA.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenPyTEA
-Version: 2.0.0
+Version: 2.1.0
 Summary: OpenPyTEA: An open-source Python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation
 Maintainer-email: "Panji B. Tamarona" <P.B.Tamarona@tudelft.nl>
 License-Expression: MIT
@@ -97,11 +97,30 @@ src/openpytea/
 ├── helpers.py              # Helper functions for data handling and common operations
 └── data/                   # Cost correlations database and CEPCI data
 examples/                   # Example notebooks and case studies
-walkthrough.ipynb           # walkthrough of the package
+walkthrough.ipynb           # Walkthrough of the package
+
+backend/                    # FastAPI backend for the web GUI
+├── app/
+│   ├── main.py             # FastAPI app with CORS and router mounting
+│   ├── state.py            # In-memory session state
+│   ├── schemas.py          # Pydantic request/response models
+│   ├── util.py             # JSON serialization utilities
+│   ├── routers/            # API endpoints (equipment, plant, analysis, I/O)
+│   └── presets/            # Example preset JSON files
+└── requirements.txt
+
+frontend/                   # React + TypeScript web GUI
+├── src/
+│   ├── api/client.ts       # Typed API client
+│   ├── types/index.ts      # TypeScript interfaces
+│   ├── pages/              # Equipment, Plant Config, Results, Analysis, Monte Carlo, Compare
+│   ├── App.tsx             # Tab navigation + examples dropdown
+│   └── App.css             # Styling
+└── package.json
+
 pyproject.toml
 README.md
 ```
-
 ---
 
 ## 🏗️ Software Architecture
@@ -112,6 +131,42 @@ Software architecture and data flow of **OpenPyTEA**, illustrating the progressi
 
 ---
 
+## 🖥️ Web GUI (**work in progress**)
+
+OpenPyTEA includes an optional web-based graphical interface for users who prefer a visual workflow over Python scripting. The GUI provides the full TEA workflow through a tabbed browser interface:
+
+- **Equipment** — add, edit, and remove equipment with cost database lookup
+- **Plant Config** — configure location, financial parameters, labor, products, and variable OPEX
+- **Results** — run calculations and view metric cards, cost breakdown charts, and cash flow tables
+- **Analysis** — sensitivity plots and tornado diagrams. Sensitivity supports a **multi-panel grid** (different parameter and metric per panel, e.g. NPV vs. interest rate, ROI vs. electricity price, all in one figure) and **multi-plant overlay** (curves for every plant added on the Compare tab share the same axes for direct comparison)
+- **Monte Carlo** — uncertainty analysis with histogram distributions, fitted normal curves, and summary statistics. **Multi-plant overlay** shows distributions for several plants on the same axes, mirroring `plot_multiple_monte_carlo` from the library
+- **Compare** — side-by-side comparison of saved plants (CAPEX/OPEX breakdown bars, key metric bars). Plants imported here are also reused as the overlay set on the Analysis and Monte Carlo tabs
+- **Downloadable charts** — all plots include a download button to export as standalone PNG images with full axis labels
+- **Examples** — built-in presets from the case study notebooks for quick demonstration
+
+### Running the GUI
+
+**Backend** (requires Python 3.10+):
+```bash
+pip install -e .          # install OpenPyTEA from repo root
+cd backend
+pip install -r requirements.txt
+PYTHONPATH=../src python3 -m uvicorn app.main:app --reload --port 8000
+```
+
+**Frontend** (requires Node.js):
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:5173. Click **Examples** in the header to load a case study preset and explore.
+
+For detailed architecture documentation, see `GUI_ARCHITECTURE.md`.
+
+---
+
 ## 🧠 Core Concepts
 
 ### 1. **Equipment-level costing**
@@ -299,7 +354,7 @@ Or if you prefer to cite manually, you may use:
   title        = {OpenPyTEA: An open-source python toolkit for techno-economic assessment of process plants with economic sensitivity and uncertainty evaluation},
   year         = {2025},
   url          = {\url{https://github.com/pbtamarona/OpenPyTEA}},
-  version      = {1.2.0},
+  version      = {2.0.0},
   note         = {Accessed: YYYY-MM-DD}
 }
 ```

{openpytea-2.0.0 → openpytea-2.1.0}/src/openpytea/analysis.py

@@ -630,54 +630,76 @@ def monte_carlo(plant,
                 batch_size: int = 1000,
                 additional_capex: bool = False):
     """
-    This function conducts a probabilistic analysis of a plant's economic
-    performance by sampling from distributions of various input parameters
-    and computing multiple economic metrics across the samples. The simulation
-    processes samples in batches to optimize memory usage while maintaining
-    computational efficiency.
-        configuration attributes initialized. The plant will be deep copied
-        internally to preserve the original state.
-        Must be divisible by batch_size for optimal performance.
-        Reduces memory usage by processing samples in chunks rather than
-        all at once. Smaller batches use less memory but may be slower.
-        calculations. Default is False. Only applies when product prices
-        are available.
+    Probabilistic analysis of a plant's economic performance by sampling
+    input parameters from truncated normal distributions and computing
+    economic metrics across all samples. Samples are processed in batches
+    to manage memory.
+
+    Parameters
+    ----------
+    plant : Plant
+        A fully configured Plant instance. Baseline economic calculations
+        are run internally before sampling begins. The original plant is not
+        modified; results are stored on it after the simulation completes.
+    num_samples : int, optional
+        Total number of Monte Carlo samples. Default is 1_000_000.
+    batch_size : int, optional
+        Number of samples processed per batch. Smaller values reduce peak
+        memory at the cost of slightly more overhead. Default is 1000.
+    additional_capex : bool, optional
+        Include additional CAPEX in ROI and payback time calculations.
+        Only applies when product prices are available. Default is False.
+
+    Returns
+    -------
     dict
-        A dictionary containing the Monte Carlo simulation results with keys:
-        - "name" : str
-            Name of the analyzed plant.
-        - "metrics" : dict
-                (only populated if product prices available).
-                (only populated if product prices available).
-                (only populated if product prices available).
-        - "inputs" : dict
-            - Variable opex price samples for each item formatted as
-              "{Item} price"
-            - Product price samples for each product formatted as
-              "{Product} product price"
-        - "num_samples" : int
-            Number of samples generated in the simulation.
-        - "additional_capex" : bool
-            Whether additional CAPEX was included in calculations.
-        - "currency" : str
-            Currency symbol used in the plant's economic calculations.
-    - The plant object is deep copied to avoid modifying the original during
-      sampling. Results are stored back to the original plant as
-    - All input parameters are sampled from truncated normal distributions
-      with parameter-specific mean, standard deviation, and bounds.
-      are defined in the plant configuration.
-    - Progress is displayed via a progress bar showing batch processing status.
-    - Fixed capital and fixed opex factors use a standard distribution with
-      mean=1, std=0.3, bounds=[0.25, 1.75].
-    - Operator hourly rate is sampled from configurable
-    distribution parameters.
-    - Project lifetime and interest rate use 2-sigma bounds around baseline
-      values.
+        A dictionary with the following keys:
+
+        - ``"name"`` : str — plant name.
+        - ``"metrics"`` : dict — arrays of length *num_samples*:
+            - ``"LCOP"`` — levelized cost of production (always populated).
+            - ``"NPV"`` — net present value (requires product prices).
+            - ``"ROI"`` — return on investment (requires product prices).
+            - ``"PBT"`` — payback time (requires product prices).
+        - ``"inputs"`` : dict — sampled input arrays, always containing:
+            - ``"Fixed capital factor"``
+            - ``"Fixed opex factor"``
+            - ``"Operator hourly rate"``
+            - ``"Project lifetime"``
+            - ``"Interest rate"``
+            - ``"{Item} price"`` for each variable OPEX item.
+            - ``"{Product} product price"`` for each product.
+            And conditionally (when ``std > 0`` in ``project_uncertainties``):
+            - ``"Plant utilization"``
+            - ``"Tax rate"``
+        - ``"num_samples"`` : int — number of samples generated.
+        - ``"additional_capex"`` : bool — whether additional CAPEX was
+          included.
+        - ``"currency"`` : str — currency symbol.
+
+    Notes
+    -----
+    - Sampling distributions for fixed capital factor, fixed opex factor,
+      project lifetime, interest rate, plant utilization, and tax rate are
+      controlled by the plant's ``project_uncertainties`` configuration dict
+      (see Plant class docstring). Default std, min, and max values are used
+      when a parameter is absent from that dict.
+    - ``plant_utilization`` and ``tax_rate`` have a default ``std`` of 0 and
+      are only sampled when explicitly set to a positive value in
+      ``project_uncertainties``.
+    - Variable OPEX items and products are sampled using the ``std``,
+      ``min``, and ``max`` fields defined within each item's own config dict.
+    - The plant is deep-copied each batch to avoid mutating the original.
+      After the run, ``monte_carlo_metrics`` and ``monte_carlo_inputs`` are
+      written back to the original plant.
+    - Progress is shown via a tqdm progress bar over batches.
+
     Raises
     ------
     AttributeError
         If the plant object lacks required economic calculation methods or
         configuration attributes.
+
     Examples
     --------
     >>> results = monte_carlo(plant, num_samples=10000, batch_size=500)
@@ -702,7 +724,58 @@ def monte_carlo(plant,
         "PBT": np.zeros(num_samples),
     }
 
-    # ---- Allocate all input distributions (same as before) ----
+    # ---- Resolve project uncertainty parameters ----
+    pu = plant.project_uncertainties
+
+    fc_cfg  = pu.get("fixed_capital_factor", {})
+    fc_std  = fc_cfg.get("std", 0.3)
+    fc_min  = fc_cfg.get("min", 0.25)
+    fc_max  = fc_cfg.get("max", 1.75)
+
+    fo_cfg  = pu.get("fixed_opex_factor", {})
+    fo_std  = fo_cfg.get("std", 0.3)
+    fo_min  = fo_cfg.get("min", 0.25)
+    fo_max  = fo_cfg.get("max", 1.75)
+
+    lt_cfg  = pu.get("project_lifetime", {})
+    lt_std  = lt_cfg.get("std", 5)
+    lt_min  = lt_cfg.get("min", max(5, plant.project_lifetime - 2 * lt_std))
+    lt_max  = lt_cfg.get("max", plant.project_lifetime + 2 * lt_std)
+
+    ir_cfg  = pu.get("interest_rate", {})
+    ir_std  = ir_cfg.get("std", 0.03)
+    ir_min  = ir_cfg.get("min", max(0.02, plant.interest_rate - 2 * ir_std))
+    ir_max  = ir_cfg.get("max", plant.interest_rate + 2 * ir_std)
+
+    pu_util_cfg = pu.get("plant_utilization", {})
+    pu_util_std = pu_util_cfg.get("std", 0)
+    if pu_util_std > 0:
+        pu_util_mean = plant.plant_utilization
+        pu_util_min = pu_util_cfg.get(
+            "min", max(0.0, pu_util_mean - 2 * pu_util_std)
+        )
+        pu_util_max = pu_util_cfg.get(
+            "max", min(1.0, pu_util_mean + 2 * pu_util_std)
+        )
+        plant_utilizations = _truncated_normal_samples(
+            pu_util_mean, pu_util_std, pu_util_min, pu_util_max, num_samples
+        )
+    else:
+        plant_utilizations = None
+
+    tr_cfg = pu.get("tax_rate", {})
+    tr_std = tr_cfg.get("std", 0)
+    if tr_std > 0:
+        tr_mean = plant.tax_rate
+        tr_min = tr_cfg.get("min", max(0.0, tr_mean - 2 * tr_std))
+        tr_max = tr_cfg.get("max", min(1.0, tr_mean + 2 * tr_std))
+        tax_rates = _truncated_normal_samples(
+            tr_mean, tr_std, tr_min, tr_max, num_samples
+        )
+    else:
+        tax_rates = None
+
+    # ---- Allocate all input distributions ----
     op_cfg = plant.operator_hourly_rate
     op_mean = op_cfg.get("rate", 38.11)
     op_std = op_cfg.get("std", 20 / 2)
@@ -711,11 +784,11 @@ def monte_carlo(plant,
 
     # ---- Sample ALL inputs once ----
     fixed_capitals = _truncated_normal_samples(
-        1, 0.3, 0.25, 1.75, num_samples
+        1, fc_std, fc_min, fc_max, num_samples
     )
 
     fixed_opexs = _truncated_normal_samples(
-        1, 0.3, 0.25, 1.75, num_samples
+        1, fo_std, fo_min, fo_max, num_samples
     )
 
     operator_hourlys = _truncated_normal_samples(
@@ -723,19 +796,11 @@ def monte_carlo(plant,
     )
 
     project_lifetimes = _truncated_normal_samples(
-        plant.project_lifetime,
-        5,
-        max(5, plant.project_lifetime - 2 * 5),
-        plant.project_lifetime + 2 * 5,
-        num_samples,
+        plant.project_lifetime, lt_std, lt_min, lt_max, num_samples,
     )
 
     interests = _truncated_normal_samples(
-        plant.interest_rate,
-        0.03,
-        max(0.02, plant.interest_rate - 2 * 0.03),
-        plant.interest_rate + 2 * 0.03,
-        num_samples,
+        plant.interest_rate, ir_std, ir_min, ir_max, num_samples,
     )
 
     variable_opex_price_samples = {}
@@ -768,12 +833,15 @@ def monte_carlo(plant,
         # ---- Apply sampled inputs ----
         plant_copy.operator_hourly_rate["rate"] = operator_hourlys[start:end]
 
-        plant_copy.update_configuration(
-            {
-                "project_lifetime": project_lifetimes[start:end],
-                "interest_rate": interests[start:end],
-            }
-        )
+        scalar_updates = {
+            "project_lifetime": project_lifetimes[start:end],
+            "interest_rate": interests[start:end],
+        }
+        if plant_utilizations is not None:
+            scalar_updates["plant_utilization"] = plant_utilizations[start:end]
+        if tax_rates is not None:
+            scalar_updates["tax_rate"] = tax_rates[start:end]
+        plant_copy.update_configuration(scalar_updates)
 
         for item in plant.variable_opex_inputs:
             plant_copy.variable_opex_inputs[item]["price"] = (
@@ -814,6 +882,10 @@ def monte_carlo(plant,
         "Operator hourly rate": operator_hourlys,
         "Project lifetime": project_lifetimes,
         "Interest rate": interests,
+        **({} if plant_utilizations is None
+           else {"Plant utilization": plant_utilizations}),
+        **({} if tax_rates is None
+           else {"Tax rate": tax_rates}),
         **{
             f"{k.replace('_', ' ').title()} price": v
             for k, v in variable_opex_price_samples.items()

{openpytea-2.0.0 → openpytea-2.1.0}/src/openpytea/equipment.py

@@ -288,6 +288,22 @@ class Equipment:
         Default is None (auto-resolved).
     target_year : int, optional
         Target year for inflation adjustment. Default is 2024.
+    erection_factor : float | None, optional
+        Erection factor override. Default is None (use process_type table).
+    piping_factor : float | None, optional
+        Piping factor override. Default is None (use process_type table).
+    instrumentation_factor : float | None, optional
+        Instrumentation & controls factor override. Default is None.
+    electrical_factor : float | None, optional
+        Electrical factor override. Default is None (use process_type table).
+    civil_factor : float | None, optional
+        Civil factor override. Default is None (use process_type table).
+    structural_factor : float | None, optional
+        Structural steel factor override. Default is None (use process_type table).
+    lagging_factor : float | None, optional
+        Lagging & painting factor override. Default is None (use process_type table).
+    material_factor : float | None, optional
+        Material factor override. Default is None (use material table).
 
     Methods
     -------
@@ -387,10 +403,16 @@ class Equipment:
         num_units: int | None = None,
         purchased_cost: float | None = None,
         cost_year: int | None = None,
-        cost_func: (
-            str | None
-        ) = None,  # explicit correlation key
+        cost_func: str | None = None,
         target_year: int = 2024,
+        erection_factor: float | None = None,
+        piping_factor: float | None = None,
+        instrumentation_factor: float | None = None,
+        electrical_factor: float | None = None,
+        civil_factor: float | None = None,
+        structural_factor: float | None = None,
+        lagging_factor: float | None = None,
+        material_factor: float | None = None,
     ):
 
         self.name = name
@@ -407,9 +429,48 @@ class Equipment:
         )
         self.target_year = target_year
         self._cost_func = cost_func
-        self._db = (
-            CostCorrelationDB()
-        )  # always loads from the fixed CSV file
+        self._db = CostCorrelationDB()
+
+        valid_process_types = list(self.process_factors.keys())
+        if process_type not in self.process_factors:
+            raise ValueError(
+                f"Invalid process_type '{process_type}'. "
+                f"Valid options are: {valid_process_types}"
+            )
+        valid_materials = list(self.material_factors.keys())
+        if material not in self.material_factors:
+            raise ValueError(
+                f"Invalid material '{material}'. "
+                f"Valid options are: {valid_materials}"
+            )
+
+        _pf = self.process_factors[process_type]
+        self.erection_factor = (
+            erection_factor if erection_factor is not None else _pf["fer"]
+        )
+        self.piping_factor          = (
+            piping_factor          if piping_factor          is not None else _pf["fp"]
+        )
+        self.instrumentation_factor = (
+            instrumentation_factor if instrumentation_factor is not None else _pf["fi"]
+        )
+        self.electrical_factor      = (
+            electrical_factor      if electrical_factor      is not None else _pf["fel"]
+        )
+        self.civil_factor           = (
+            civil_factor           if civil_factor           is not None else _pf["fc"]
+        )
+        self.structural_factor      = (
+            structural_factor      if structural_factor      is not None else _pf["fs"]
+        )
+        self.lagging_factor         = (
+            lagging_factor         if lagging_factor         is not None else _pf["fl"]
+        )
+        self.material_factor = (
+            material_factor
+            if material_factor is not None
+            else self.material_factors[material]
+        )
 
         if purchased_cost is not None:
             self.purchased_cost = purchased_cost
@@ -456,29 +517,15 @@ class Equipment:
         )
 
     def calculate_direct_cost(self) -> float:
-
-        if self.process_type not in self.process_factors:
-            raise ValueError(
-                f"Process type not found: {self.process_type}"
-            )
-
-        if self.material not in self.material_factors:
-            raise ValueError(
-                f"Material not found: {self.material}"
-            )
-
-        factors = self.process_factors[self.process_type]
-        fm = self.material_factors[self.material]
-
         self.direct_cost = self.purchased_cost * (
-            (1 + factors["fp"]) * fm
+            (1 + self.piping_factor) * self.material_factor
             + (
-                factors["fer"]
-                + factors["fel"]
-                + factors["fi"]
-                + factors["fc"]
-                + factors["fs"]
-                + factors["fl"]
+                self.erection_factor
+                + self.electrical_factor
+                + self.instrumentation_factor
+                + self.civil_factor
+                + self.structural_factor
+                + self.lagging_factor
             )
         )
         return self.direct_cost