Metadata-Version: 2.5
Name: gridops
Version: 1.0.0
Summary: An open-source production cost model (PCM) for the U.S. interconnections and grid regions.
Project-URL: Repository, https://github.com/IMMM-SFA/gridops
Project-URL: Documentation, https://immm-sfa.github.io/gridops
Author-email: Kerem Ziya Akdemir <keremziya.akdemir@pnnl.gov>, Jordan Kern <jkern@ncsu.edu>, Chris Vernon <chris.vernon@pnnl.gov>, Konstantinos Oikonomou <konstantinos.oikonomou@pnnl.gov>, Nathalie Voisin <nathalie.voisin@pnnl.gov>, Henry Ssembatya <hssemba@ncsu.edu>, Jingwei Qian <jqian4@ncsu.edu>
Maintainer-email: Kerem Ziya Akdemir <keremziya.akdemir@pnnl.gov>, Chris Vernon <chris.vernon@pnnl.gov>
License-Expression: BSD-2-Clause
License-File: LICENSE
Keywords: economic dispatch,grid operations,optimal power flow,production cost model,unit commitment
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.10
Requires-Dist: cloudpickle>=3.0.0
Requires-Dist: highspy>=1.10.0
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2.2
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: pyomo>=6.0.1
Requires-Dist: pyyaml>=5.4.1
Requires-Dist: requests>=2.25.1
Provides-Extra: deploy
Requires-Dist: twine>=3.4.1; extra == 'deploy'
Provides-Extra: docs
Requires-Dist: build>=0.5.1; extra == 'docs'
Requires-Dist: nbsphinx>=0.8.6; extra == 'docs'
Requires-Dist: setuptools>=57.0.0; extra == 'docs'
Requires-Dist: sphinx-panels>=0.6.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=0.5.2; extra == 'docs'
Requires-Dist: sphinx>=4.0.2; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-cov>=2.12.1; extra == 'test'
Requires-Dist: pytest>=6.2.4; extra == 'test'
Description-Content-Type: text/markdown

# gridops

[![tests](https://github.com/IMMM-SFA/gridops/actions/workflows/tests.yml/badge.svg)](https://github.com/IMMM-SFA/gridops/actions/workflows/tests.yml)

`gridops` is an open-source and customizable grid operations model for three major U.S. interconnections (Western, Eastern, ERCOT). Production cost modeling in `gridops` utilizes linear DC Optimal Power Flow (DC-OPF) approximation to optimize hourly unit commitment (UC) and economic dispatch (ED) processes over a user-configurable rolling horizon.

## Purpose

`gridops` was created to:
  - Address weather and water dynamics and associated vulnerabilities in U.S. bulk power systems,
  - Link with a wide range of hydrometeorological datasets and energy system/machine learning models to explore future uncertainty in grid operations,
  - Analyze current and future grid stress and reliability trends under a wide range of weather conditions, generation mixes, and demand growth scenarios.
  - Create simple and user-tailored representations of the U.S. interconnections to find a balance between model accuracy and run time to answer research questions of interest.

## Installation

```bash
pip install gridops
```

## Quickstart

```python
import gridops as go

# Instantiate the model
model = go.Model(
    region="west",              # U.S. Western Interconnection
    problem="linear",           # Linear programming (economic dispatch only)
    solver_name="appsi_highs",  # Using open-source HiGHS solver
    solver_params=None,         # Optional – using default solver parameters
)

# Run for 7 days with a 24-hour rolling horizon
model.run(
    config_file="example_config_file.yml",  # Path to the model configuration file
    n_days=7,                               # Running for 7 days
    horizon_hours=24,                       # Optional – using default 24-hour horizon
)
```

## Configuration file

`gridops` needs a YAML file that maps each input CSV and NPY files to their file path and each
output Parquet to its destination. Check out below for a minimal example (see
`gridops/data/example_config_file.yml` for a full template):

```yaml
generator_parameters_file: Input/data_genparams.csv
line_parameters_file: Input/line_param.csv
# … all other input entries …
flow_file: Output/flow.parquet
mwh_file: Output/mwh.parquet
# … all other output entries …
restart_file_directory: Restart/
```

## Supported solvers

| Solver | Interface | Notes |
|--------|-----------|-------|
| HiGHS  | `appsi_highs`  | Open-source; install separately with `pip install highspy` |
| Gurobi | `appsi_gurobi` or `gurobi` | Commercial; requires a valid Gurobi license |

Users can pass any desired solver parameters via the `solver_params`:

```python
model = go.Model(
    solver_name="appsi_highs",
    solver_params={"presolve": "on", "solver": "ipm", "time_limit": 3600},
    ...
)
```

## License

BSD-2-Clause – See [LICENSE](LICENSE).

## Disclaimer

See [DISCLAIMER](DISCLAIMER).

## Reference

If you use gridops in an academic context, please cite the following article.

Akdemir, K. Z., Oikonomou, K., Kern, J. D., Voisin, N., Ssembatya, H., & Qian, J. (2024). An open-source framework for balancing computational speed and fidelity in production cost models. Environmental Research: Energy, 1(1), 015003. https://doi.org/10.1088/2753-3751/ad1751
