enpax 0.1.0__tar.gz

enpax-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Alliance for Energy Innovation, LLC
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

enpax-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: enpax
+Version: 0.1.0
+Summary: ENergy Platform — Automated eXpenditures
+Author-email: Daniel Mulas Hernando <daniel.mulashernando@nlr.gov>, Kaitlin Brunik <kaitlin.brunik@nlr.gov>, Elenya Grant <elenya.grant@nlr.gov>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/NatLabRockies/ENPAX
+Project-URL: Repository, https://github.com/NatLabRockies/ENPAX
+Project-URL: Issues, https://github.com/NatLabRockies/ENPAX/issues
+Keywords: energy,cost modeling,techno-economic analysis,solar,BESS,hybrid energy systems
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyyaml
+Provides-Extra: develop
+Requires-Dist: pytest; extra == "develop"
+Requires-Dist: pytest-cov; extra == "develop"
+Provides-Extra: examples
+Requires-Dist: jupyterlab; extra == "examples"
+Requires-Dist: ipykernel; extra == "examples"
+Provides-Extra: all
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: pytest-cov; extra == "all"
+Requires-Dist: jupyterlab; extra == "all"
+Requires-Dist: ipykernel; extra == "all"
+Dynamic: license-file
+
+# ENPAX
+ 
+[![PyPI version](https://badge.fury.io/py/enpax.svg)](https://badge.fury.io/py/enpax)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/enpax)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+ 
+ENPAX (**EN**ergy **P**latform — **A**utomated e**X**penditures) is an open-source Python library that provides modular, bottom-up capital and operating expenditure (CAPEX/OPEX) models for energy technologies. Cost estimates are derived using system design, characteristics, site specific details, power system considerations and infrastructure assumptions.
+ 
+## Software Requirements
+ 
+- Python 3.10+
+## Installing ENPAX
+ 
+### PyPI
+ 
+```bash
+pip install enpax
+```
+ 
+### Source Installation
+ 
+1. Using Git, navigate to a local target directory and clone the repository:
+    ```bash
+    git clone https://github.com/NatLabRockies/ENPAX.git
+    ```
+ 
+2. Navigate to `ENPAX`:
+    ```bash
+    cd ENPAX
+    ```
+ 
+3. Create a new virtual environment and activate it. Using Conda and naming it `enpax`:
+    ```bash
+    conda create --name enpax python=3.11 -y
+    conda activate enpax
+    ```
+ 
+4. Install ENPAX and its dependencies:
+    - To use ENPAX only:
+        ```bash
+        pip install .
+        ```
+    - To install in editable mode with development dependencies:
+        ```bash
+        pip install -e ".[develop]"
+        ```
+    - To install with example/notebook dependencies:
+        ```bash
+        pip install -e ".[examples]"
+        ```
+    - To install all optional dependencies at once:
+        ```bash
+        pip install -e ".[all]"
+        ```
+ 
+## Usage
+ 
+ENPAX models can be configured and run either via YAML config files or Python dictionaries. Example notebooks are provided in the `examples/` directory:
+ 
+- `examples_using_yaml_config_files.ipynb` — configure and run models using `.yaml` files from the `configs/` directory
+- `examples_using_dictionaries.ipynb` — configure and run models programmatically in Python
+### Quick Start
+ 
+```python
+from enpax.runner import CentralRunner
+ 
+runner = CentralRunner(config="configs/solar_bess.yaml")
+results = runner.run()
+print(results)
+```
+ 
+## Available Models
+
+The library is structured around a shared abstract base class (BaseCostModel) that enforces a consistent interface — run_capex(), run_opex(), and run_design() — across all technology models, and a central runner (CentralRunner) that assembles multi-technology systems from YAML configuration files and returns structured output objects (TechResult, SystemResult). The current release includes two fully detailed technology models as well as the ability for a user to define their own technology cost model, both applicable for CAPEX and O&M cost estimations. 
+
+| Model | Description |
+|-------|-------------|
+| `solar_bess_2024Q1` | Solar PV + BESS hybrid CAPEX/OPEX model |
+| `bess_2025` | Standalone battery energy storage CAPEX/OPEX model |
+| `generic_passthrough` | Generic passthrough model for custom CAPEX/OPEX inputs |
+ 
+## Release Notes
+ 
+1. Ensure all tests pass.
+2. Ensure this README is up to date.
+3. Ensure dependency and Python versions are current.
+4. Ensure `CHANGELOG.md` is up to date.
+5. Bump the version in `pyproject.toml` using semantic versioning (<https://semver.org/>).
+6. Make a pull request into `main` from `develop` or a patch release branch.
+   1. Merge `main` back into `develop` if `develop` was not the base branch.
+7. Tag the new release and push it:
+    ```bash
+    git tag -a v0.1.0 -m "message for v0.1.0"
+    git push origin v0.1.0
+    ```
+    1. This will trigger the **Deploy to Test PyPI** GitHub Action. If it passes, proceed to step 8. If it fails, continue below.
+    2. Delete the tag locally and on remote:
+        ```bash
+        git tag -d v0.1.0
+        git push --delete origin v0.1.0
+        ```
+    3. Create a new branch off `main`, fix the build issue, and return to step 5.
+8. Create a new release at <https://github.com/NatLabRockies/ENPAX/releases>, ensuring that:
+   1. The newly created tag is selected, and
+   2. **Generate release notes** is selected.
+   This will trigger the **Deploy to PyPI** GitHub Action.
+## Contributing
+ 
+Contributions are welcome. Please open an issue or submit a pull request against the `develop` branch.
+ 
+## Authors
+ 
+- [Daniel Mulas Hernando](daniel.mulashernando@nlr.gov) — National Laboratory of the Rockies
+- [Kaitlin Brunik](kaitlin.brunik@nlr.gov) — National Laboratory of the Rockies
+- [Elenya Grant](elenya.grant@nlr.gov) — National Laboratory of the Rockies
+## License
+ 
+This project is licensed under the BSD 3-Clause License. See [LICENSE](LICENSE) for details.

enpax-0.1.0/README.md

@@ -0,0 +1,118 @@
+# ENPAX
+ 
+[![PyPI version](https://badge.fury.io/py/enpax.svg)](https://badge.fury.io/py/enpax)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/enpax)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+ 
+ENPAX (**EN**ergy **P**latform — **A**utomated e**X**penditures) is an open-source Python library that provides modular, bottom-up capital and operating expenditure (CAPEX/OPEX) models for energy technologies. Cost estimates are derived using system design, characteristics, site specific details, power system considerations and infrastructure assumptions.
+ 
+## Software Requirements
+ 
+- Python 3.10+
+## Installing ENPAX
+ 
+### PyPI
+ 
+```bash
+pip install enpax
+```
+ 
+### Source Installation
+ 
+1. Using Git, navigate to a local target directory and clone the repository:
+    ```bash
+    git clone https://github.com/NatLabRockies/ENPAX.git
+    ```
+ 
+2. Navigate to `ENPAX`:
+    ```bash
+    cd ENPAX
+    ```
+ 
+3. Create a new virtual environment and activate it. Using Conda and naming it `enpax`:
+    ```bash
+    conda create --name enpax python=3.11 -y
+    conda activate enpax
+    ```
+ 
+4. Install ENPAX and its dependencies:
+    - To use ENPAX only:
+        ```bash
+        pip install .
+        ```
+    - To install in editable mode with development dependencies:
+        ```bash
+        pip install -e ".[develop]"
+        ```
+    - To install with example/notebook dependencies:
+        ```bash
+        pip install -e ".[examples]"
+        ```
+    - To install all optional dependencies at once:
+        ```bash
+        pip install -e ".[all]"
+        ```
+ 
+## Usage
+ 
+ENPAX models can be configured and run either via YAML config files or Python dictionaries. Example notebooks are provided in the `examples/` directory:
+ 
+- `examples_using_yaml_config_files.ipynb` — configure and run models using `.yaml` files from the `configs/` directory
+- `examples_using_dictionaries.ipynb` — configure and run models programmatically in Python
+### Quick Start
+ 
+```python
+from enpax.runner import CentralRunner
+ 
+runner = CentralRunner(config="configs/solar_bess.yaml")
+results = runner.run()
+print(results)
+```
+ 
+## Available Models
+
+The library is structured around a shared abstract base class (BaseCostModel) that enforces a consistent interface — run_capex(), run_opex(), and run_design() — across all technology models, and a central runner (CentralRunner) that assembles multi-technology systems from YAML configuration files and returns structured output objects (TechResult, SystemResult). The current release includes two fully detailed technology models as well as the ability for a user to define their own technology cost model, both applicable for CAPEX and O&M cost estimations. 
+
+| Model | Description |
+|-------|-------------|
+| `solar_bess_2024Q1` | Solar PV + BESS hybrid CAPEX/OPEX model |
+| `bess_2025` | Standalone battery energy storage CAPEX/OPEX model |
+| `generic_passthrough` | Generic passthrough model for custom CAPEX/OPEX inputs |
+ 
+## Release Notes
+ 
+1. Ensure all tests pass.
+2. Ensure this README is up to date.
+3. Ensure dependency and Python versions are current.
+4. Ensure `CHANGELOG.md` is up to date.
+5. Bump the version in `pyproject.toml` using semantic versioning (<https://semver.org/>).
+6. Make a pull request into `main` from `develop` or a patch release branch.
+   1. Merge `main` back into `develop` if `develop` was not the base branch.
+7. Tag the new release and push it:
+    ```bash
+    git tag -a v0.1.0 -m "message for v0.1.0"
+    git push origin v0.1.0
+    ```
+    1. This will trigger the **Deploy to Test PyPI** GitHub Action. If it passes, proceed to step 8. If it fails, continue below.
+    2. Delete the tag locally and on remote:
+        ```bash
+        git tag -d v0.1.0
+        git push --delete origin v0.1.0
+        ```
+    3. Create a new branch off `main`, fix the build issue, and return to step 5.
+8. Create a new release at <https://github.com/NatLabRockies/ENPAX/releases>, ensuring that:
+   1. The newly created tag is selected, and
+   2. **Generate release notes** is selected.
+   This will trigger the **Deploy to PyPI** GitHub Action.
+## Contributing
+ 
+Contributions are welcome. Please open an issue or submit a pull request against the `develop` branch.
+ 
+## Authors
+ 
+- [Daniel Mulas Hernando](daniel.mulashernando@nlr.gov) — National Laboratory of the Rockies
+- [Kaitlin Brunik](kaitlin.brunik@nlr.gov) — National Laboratory of the Rockies
+- [Elenya Grant](elenya.grant@nlr.gov) — National Laboratory of the Rockies
+## License
+ 
+This project is licensed under the BSD 3-Clause License. See [LICENSE](LICENSE) for details.

enpax-0.1.0/enpax/base_model.py

@@ -0,0 +1,93 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+import json
+import yaml
+
+from enpax.outputs import DesignSummary, CapexBreakdown, OpexBreakdown, TechResult
+
+
+class BaseCostModel(ABC):
+
+    # Subclasses declare their defaults dict at class level
+    DEFAULTS: dict = {}
+
+    def __init__(self, name: str, tech_type: str, params: dict):
+        self.name = name
+        self.tech_type = tech_type
+        if params and not isinstance(params, dict):
+            raise ValueError("params must be a dictionary.")
+        self.config = {**self.DEFAULTS, **(params or {})}
+
+    # ------------------------------------------------------------------
+    # Config loading — shared by all subclasses, no duplication needed
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_config_file(cls, file_name: str, name: str = None, tech_type: str = None):
+        base_dir = Path(__file__).parent.absolute()
+        search_paths = [
+            base_dir / file_name,
+            base_dir / "configs" / file_name,
+            base_dir.parent / "configs" / file_name,
+            base_dir.parent / "configs" / "single_tech" / file_name,
+        ]
+        full_path = next((p for p in search_paths if p.exists()), Path(file_name))
+
+        if not full_path.exists():
+            tried = "\n".join(str(p) for p in search_paths)
+            raise FileNotFoundError(f"Could not find '{file_name}'. Checked:\n{tried}")
+
+        with open(full_path) as f:
+            if full_path.suffix == ".json":
+                data = json.load(f)
+            elif full_path.suffix in (".yaml", ".yml"):
+                data = yaml.safe_load(f)
+            else:
+                raise ValueError(f"Unsupported format: {full_path.suffix}. Use .json or .yaml")
+
+        resolved_name = name or data.pop("name", cls.__name__)
+        resolved_type = tech_type or data.pop("tech_type", cls.__name__.lower())
+        return cls(name=resolved_name, tech_type=resolved_type, params=data)
+
+    # ------------------------------------------------------------------
+    # Abstract interface every tech model must implement
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def run_capex(self) -> CapexBreakdown:
+        """Return a CapexBreakdown with total, unit, and line_items."""
+        pass
+
+    def run_opex(self) -> Optional[OpexBreakdown]:
+        """
+        Override in subclass if this tech has OPEX.
+        Returns None by default — runner skips gracefully.
+        """
+        return None
+
+    # ------------------------------------------------------------------
+    # Dynamic attribute resolution — preserves existing __getattr__ pattern
+    # ------------------------------------------------------------------
+    def __getattr__(self, name: str):
+        if name.startswith("calculate_") and "_per_" in name:
+            # e.g. calculate_li_ion_cost_per_kwh → get_li_ion_cost_breakdown
+            suffix_start = name.rfind("_per_")
+            getter_name = "get_" + name[10:suffix_start] + "_breakdown"
+            if hasattr(self.__class__, getter_name) or getter_name in self.__dict__:
+                def _caller():
+                    breakdown = getattr(self, getter_name)()
+                    return breakdown[next(k for k in breakdown if k.startswith("total_"))]
+                return _caller
+        raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")
+
+    # ------------------------------------------------------------------
+    # Top-level runner — produces a TechResult
+    # ------------------------------------------------------------------
+    def run(self) -> TechResult:
+        return TechResult(
+            tech_name=self.name,
+            tech_type=self.tech_type,
+            capex=self.run_capex(),
+            opex=self.run_opex(),
+            design=self.run_design(),
+            
+        )