Metadata-Version: 2.4
Name: electrolyzer
Version: 0.2.1
Summary: A controls-oriented engineering electrolyzer model.
Author-email: NLR <christopher.bay@nlr.gov>
License: Apache Software License 2.0
        
        Copyright (c) 2022, Christopher Bay
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
        http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
        
Keywords: electrolyzer,hydrogen
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: rainflow
Requires-Dist: attrs
Requires-Dist: jsonschema
Requires-Dist: ruamel.yaml
Provides-Extra: develop
Requires-Dist: pre-commit; extra == "develop"
Requires-Dist: pytest; extra == "develop"
Requires-Dist: pytest_mock; extra == "develop"
Requires-Dist: pytest-subtests; extra == "develop"
Requires-Dist: pytest-dependency; extra == "develop"
Requires-Dist: responses; extra == "develop"
Requires-Dist: Sphinx; extra == "develop"
Requires-Dist: jupyter-book; extra == "develop"
Requires-Dist: sphinxcontrib-napoleon; extra == "develop"
Requires-Dist: readthedocs-sphinx-ext; extra == "develop"
Requires-Dist: bump2version; extra == "develop"
Provides-Extra: examples
Requires-Dist: jupyterlab; extra == "examples"
Provides-Extra: all
Requires-Dist: electrolyzer[develop,examples]; extra == "all"
Dynamic: license-file

# Electrolyzer

[![CI Status](https://github.com/NREL/electrolyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/NREL/electrolyzer/actions/workflows/ci.yml)
[![Lint](https://github.com/NREL/electrolyzer/actions/workflows/black.yml/badge.svg)](https://github.com/NREL/electrolyzer/actions/workflows/black.yml)

Electrolyzer is a controls-oriented engineering model for hydrogen production systems. It simulates
multi-stack electrolyzer operation, supports PEM and alkaline cell models, tracks degradation, and
includes levelized cost of hydrogen (LCOH) analysis utilities.

## What this repo provides

- Time-series simulation of one or more stacks with supervisory control logic.
- PEM and alkaline electrochemical cell models with polarization curve fitting.
- Degradation tracking (steady, fatigue, and on/off cycling) with optional penalty modes.
- Cost and LCOH analysis tools tied to simulation outputs.
- YAML-based modeling configuration with a JSON schema for validation and defaults.

## Project structure

- Core simulation: [electrolyzer/simulation](electrolyzer/simulation)
- Cell models: [electrolyzer/simulation/cell_models](electrolyzer/simulation/cell_models)
- Validation/schema: [electrolyzer/tools/validation.py](electrolyzer/tools/validation.py), [electrolyzer/tools/modeling_schema.yaml](electrolyzer/tools/modeling_schema.yaml)
- LCOH analysis: [electrolyzer/tools/analysis](electrolyzer/tools/analysis)
- Examples: [examples](examples)
- Documentation: [docs](docs)

## Installation

Python 3.11+ is required.

```bash
pip install .
```

Optional extras:

```bash
pip install ".[examples]"   # notebooks + example dependencies
pip install -e ".[develop]"  # dev + docs tooling
pip install -e ".[all]"      # everything
```

More detail is in [docs/installing.md](docs/installing.md).

## Quick start

Run a simulation from a YAML configuration and a power signal:

```python
import numpy as np

from electrolyzer.simulation.bert import run_electrolyzer

power_signal = np.ones(3600) * 1e6  # 1 MW for 1 hour, in Watts
elec_sys, results = run_electrolyzer("examples/example_02_electrolyzer/modeling_options.yaml", power_signal)

print(results.head())
```

Compute LCOH using the same signal:

```python
import numpy as np

from electrolyzer.tools.analysis.run_lcoh import run_lcoh

power_signal = np.ones(3600) * 1e6
lcoe = 0.04418  # $/kWh

lcoh_breakdown, lcoh_value = run_lcoh(
    "examples/example_04_lcoh/cost_modeling_options.yaml",
    power_signal,
    lcoe,
)

print(lcoh_value)
```

## Modeling configuration

Models are configured with YAML files validated against a JSON schema. The schema defines defaults
and accepted ranges for parameters like stack rating, cell geometry, degradation rates, and control
policy settings.

- Schema: [electrolyzer/tools/modeling_schema.yaml](electrolyzer/tools/modeling_schema.yaml)
- Example PEM configuration: [examples/example_02_electrolyzer/modeling_options.yaml](examples/example_02_electrolyzer/modeling_options.yaml)
- Example alkaline configuration: [examples/example_06_alkaline/default_alkaline.yaml](examples/example_06_alkaline/default_alkaline.yaml)

Key configuration blocks:

- `electrolyzer.supervisor`: system rating and number of stacks.
- `electrolyzer.controller`: control strategy and decision policy flags.
- `electrolyzer.stack`: stack sizing, cell type, and operational settings.
- `electrolyzer.degradation`: degradation rates and end-of-life parameters.
- `electrolyzer.cell_params`: PEM or alkaline cell model parameters.
- `electrolyzer.costs`: LCOH input data for capex, opex, feedstock, and finance.

## Control strategies

The supervisor supports multiple control modes for stack scheduling and power distribution:

- `PowerSharingRotation`, `SequentialRotation`
- `EvenSplitEagerDeg`, `EvenSplitHesitantDeg`
- `SequentialEvenWearDeg`, `SequentialSingleWearDeg`
- `BaselineDeg`
- `DecisionControl` (composed from policy flags in the YAML)

See [electrolyzer/simulation/supervisor.py](electrolyzer/simulation/supervisor.py) for logic.

## Degradation modeling

Each stack tracks voltage degradation from steady operation, fatigue, and on/off cycling. You can
choose whether degradation penalizes hydrogen production or increases power draw. The end-of-life
voltage delta drives replacement calculations in the LCOH workflow.

## Outputs

`run_electrolyzer` returns a supervisor object and a `pandas.DataFrame` of time-series results.
The frame includes overall power and curtailment plus per-stack columns for degradation, cycles,
uptime, hydrogen production rate, and current density.

## Examples

- Basic simulation: [examples/example_02_electrolyzer/example_run.py](examples/example_02_electrolyzer/example_run.py)
- Polarization curve fitting: [examples/example_01_polarization/example_run.py](examples/example_01_polarization/example_run.py)
- Controller behavior: [examples/example_05_controller/example_05_controller_options.py](examples/example_05_controller/example_05_controller_options.py)
- Alkaline configuration: [examples/example_06_alkaline/alkaline_example_run.py](examples/example_06_alkaline/alkaline_example_run.py)
- LCOH calculation: [examples/example_04_lcoh/cost_example_run.py](examples/example_04_lcoh/cost_example_run.py)

## Documentation

Docs are in [docs](docs). The landing page is [docs/intro.md](docs/intro.md). If you build the
Jupyter Book locally, the generated site lands in [docs/_build/html](docs/_build/html).

## Testing

```bash
pytest
```
