Metadata-Version: 2.4
Name: otex
Version: 0.3.1
Summary: OTEX - Ocean Thermal Energy eXchange: OTEC plant design, simulation, and analysis
Author: OTEX Development Team
License: MIT
Project-URL: Homepage, https://github.com/otex-dev/otex
Project-URL: Documentation, https://otex.readthedocs.io
Project-URL: Repository, https://github.com/otex-dev/otex
Project-URL: Issues, https://github.com/otex-dev/otex/issues
Keywords: OTEC,ocean thermal energy,renewable energy,thermodynamic cycles,power plant,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Requires-Dist: scipy>=1.7
Requires-Dist: matplotlib>=3.4
Requires-Dist: tables>=3.6
Requires-Dist: xarray>=0.19
Requires-Dist: netCDF4>=1.5
Requires-Dist: tqdm>=4.60
Requires-Dist: geopandas>=0.12
Requires-Dist: shapely>=2.0
Requires-Dist: pyproj>=3.4
Requires-Dist: requests>=2.28
Requires-Dist: pyarrow>=10.0
Provides-Extra: coolprop
Requires-Dist: CoolProp>=6.4; extra == "coolprop"
Provides-Extra: uncertainty
Requires-Dist: SALib>=1.4.0; extra == "uncertainty"
Provides-Extra: siting
Requires-Dist: geopandas>=0.12; extra == "siting"
Requires-Dist: rasterio>=1.3; extra == "siting"
Requires-Dist: shapely>=2.0; extra == "siting"
Requires-Dist: pyproj>=3.4; extra == "siting"
Requires-Dist: requests>=2.28; extra == "siting"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: myst-parser>=0.18; extra == "docs"
Provides-Extra: all
Requires-Dist: CoolProp>=6.4; extra == "all"
Requires-Dist: SALib>=1.4.0; extra == "all"
Requires-Dist: geopandas>=0.12; extra == "all"
Requires-Dist: rasterio>=1.3; extra == "all"
Requires-Dist: shapely>=2.0; extra == "all"
Requires-Dist: pyproj>=3.4; extra == "all"
Requires-Dist: requests>=2.28; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: pytest-cov>=4.0; extra == "all"

<p align="center">
  <img src="https://github.com/Net-Zero-Horizon/OTEX/blob/b553a7753a20db5f05e0a08e46eeedafdbf2e549/img/logo.png" alt="OTEX Logo" width="400"/>
</p>

<h1 align="center">OTEX - Ocean Thermal Energy eXchange</h1>

<p align="center">
  <strong>A Python library for OTEC plant design, simulation, and techno-economic analysis</strong>
</p>

<p align="center">
  <a href="https://github.com/msotocalvo/OTEX/actions/workflows/workflow.yml">
    <img src="https://github.com/msotocalvo/OTEX/actions/workflows/workflow.yml/badge.svg" alt="CI">
  </a>
  <a href="https://codecov.io/gh/msotocalvo/OTEX">
    <img src="https://codecov.io/gh/msotocalvo/OTEX/branch/main/graph/badge.svg" alt="codecov">
  </a>
  <a href="https://otex.readthedocs.io">
    <img src="https://readthedocs.org/projects/otex/badge/?version=latest" alt="Documentation">
  </a>
  <a href="https://doi.org/10.5281/zenodo.18428742">
    <img src="https://zenodo.org/badge/1145581288.svg" alt="DOI">
  </a>
</p>

<p align="center">
  <a href="https://pypi.org/project/otex/">
    <img src="https://img.shields.io/pypi/v/otex.svg" alt="PyPI">
  </a>
  <a href="https://pypi.org/project/otex/">
    <img src="https://img.shields.io/pypi/pyversions/otex.svg" alt="Python">
  </a>
  <a href="https://pepy.tech/project/otex">
    <img src="https://static.pepy.tech/badge/otex" alt="Downloads">
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
  </a>
  <a href="https://github.com/astral-sh/ruff">
    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
  </a>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#citation">Citation</a>
</p>

---

## Overview

**OTEX** (Ocean Thermal Energy eXchange) is a Python library for designing, simulating, and analyzing Ocean Thermal Energy Conversion (OTEC) power plants. It integrates with global oceanographic databases to enable site-specific techno-economic assessments anywhere in the tropical oceans.

OTEX enables researchers and engineers to:

- **Design OTEC plants** with multiple thermodynamic cycles and working fluids
- **Analyze regional and global potential** using CMEMS or HYCOM oceanographic data
- **Perform uncertainty analysis** with Monte Carlo simulations and sensitivity studies
- **Compare scenarios** across different locations, plant sizes, and configurations

## Features

### Thermodynamic Cycles
| Cycle | Description | Status |
|-------|-------------|--------|
| Rankine Closed | Ammonia/organic fluid closed loop | ✅ Stable |
| Rankine Open | Flash evaporation of seawater | ✅ Stable |
| Rankine Hybrid | Combined closed/open cycle | ✅ Stable |
| Kalina | Ammonia-water mixture | ✅ Stable |
| Uehara | Advanced ammonia-water cycle | ✅ Stable |

### Working Fluids
- **Ammonia** (NH₃) - Default, polynomial or CoolProp
- **R134a** - Requires CoolProp
- **R245fa** - Requires CoolProp
- **Propane** - Requires CoolProp
- **Isobutane** - Requires CoolProp

### Data Sources

| Source | Resolution | Depth Levels | Period | Authentication |
|--------|-----------|-------------|--------|----------------|
| [CMEMS](https://data.marine.copernicus.eu/) | 0.083° | 50 | 1993–present | Required (free account) |
| [HYCOM](https://www.hycom.org/) | 0.08° | 40 | 1994–2015, 2019–2024 | Not required |

### Analysis Capabilities
- **Regional Analysis**: Site-specific LCOE maps and power profiles
- **Multi-year Simulations** *(0.2.0)*: Run a continuous N-year simulation
  with NPV-based LCOE, configurable degradation (constant / logistic /
  step), and OPEX escalation (flat / fixed-rate / indexed). Inter-annual
  variability of AEP is reported per site.
- **Site Screening**: Optional exclusion of protected areas (WDPA) and busy shipping lanes (World Bank vessel density), plus seismic and cyclone risk-based cost multipliers (GEM PGA, NOAA IBTrACS)
- **Uncertainty Analysis**: Monte Carlo with Latin Hypercube Sampling
- **Sensitivity Analysis**: Sobol indices and Tornado diagrams
- **Off-design Performance**: Time-resolved power output profiles

## Installation

### Basic Installation

```bash
pip install otex
```

### With Optional Dependencies

```bash
# High-accuracy fluid properties
pip install otex[coolprop]

# Uncertainty analysis (Sobol indices)
pip install otex[uncertainty]

# Siting layers (protected areas, shipping lanes, seismic and cyclone hazards)
pip install otex[siting]

# All optional dependencies
pip install otex[all]
```

### Development Installation

```bash
git clone https://github.com/msotocalvo/OTEX.git
cd OTEX
pip install -e ".[dev]"
```

### Oceanographic Data Access

**HYCOM (no credentials needed):**

```python
from otex.regional import run_regional_analysis

otec_plants, sites = run_regional_analysis(
    studied_region='Jamaica',
    data_source='HYCOM',
    year_start=2020,
    year_end=2020,
)
```

**CMEMS (requires free account):**

1. Create account at [Copernicus Marine](https://data.marine.copernicus.eu/)
2. Configure credentials:
   ```bash
   copernicusmarine login
   ```

See [Installation Guide](docs/installation.md) for detailed instructions.

## Quick Start

### Basic Plant Configuration

```python
from otex.config import parameters_and_constants

# Configure a 100 MW OTEC plant
inputs = parameters_and_constants(
    p_gross=-100000,           # 100 MW (negative = power output)
    cost_level='low_cost',
    cycle_type='rankine_closed',
    fluid_type='ammonia',
    year_start=2020,
    year_end=2020,
)

print(f"Cycle: {inputs['cycle_type']}")
print(f"Discount rate: {inputs['discount_rate']:.1%}")
print(f"Plant lifetime: {inputs['lifetime']} years")
```

### Regional Analysis

```bash
# Analyze Cuba for 2020 with a 50 MW plant (CMEMS, default)
otex-regional Cuba --year 2020 --power -50000

# Using HYCOM data (no credentials needed)
otex-regional Philippines --year 2020 --data-source HYCOM

# Analyze with Kalina cycle
otex-regional Philippines --cycle kalina --year 2021
```

### Multi-Year Analysis

Since 0.2.0, a single run can span multiple calendar years. The
oceanographic data is concatenated along the time axis, LCOE is computed
via discounted cashflow NPV (with configurable degradation and OPEX
escalation), and the output CSV includes inter-annual AEP statistics:

```bash
# Continuous 4-year simulation, NPV LCOE, inter-annual AEP variability
otex-regional Jamaica --year-start 2020 --year-end 2023
```

```python
from otex.regional import run_regional_analysis

otec_plants, sites = run_regional_analysis(
    studied_region='Jamaica',
    year_start=2020,
    year_end=2023,
)
# sites includes columns: LCOE (NPV), LCOE_legacy (CRF), AEP_min/p50/max/std
# A second CSV `OTEC_sites_yearly_*.csv` reports per-(site, year) energy.
```

### Uncertainty Analysis

```python
from otex.analysis import (
    MonteCarloAnalysis,
    UncertaintyConfig,
    TornadoAnalysis,
    plot_histogram,
    plot_tornado
)

# Monte Carlo analysis
config = UncertaintyConfig(n_samples=1000, seed=42)
mc = MonteCarloAnalysis(T_WW=28.0, T_CW=5.0, config=config)
results = mc.run()

# Get statistics
stats = results.compute_statistics()
print(f"LCOE: {stats['lcoe']['lcoe_mean']:.2f} ± {stats['lcoe']['lcoe_std']:.2f} ct/kWh")
print(f"90% CI: [{stats['lcoe']['lcoe_p5']:.2f}, {stats['lcoe']['lcoe_p95']:.2f}]")

# Tornado diagram
tornado = TornadoAnalysis(T_WW=28.0, T_CW=5.0)
tornado_results = tornado.run()
plot_tornado(tornado_results)
```

### Command Line Interface

```bash
# Tornado analysis
python scripts/uncertainty_analysis.py --T_WW 28 --T_CW 5 --method tornado

# Monte Carlo with 500 samples
python scripts/uncertainty_analysis.py --T_WW 28 --T_CW 5 --method monte-carlo --samples 500

# Full analysis with plots
python scripts/uncertainty_analysis.py --T_WW 28 --T_CW 5 --method all --samples 200 --save-plots
```

## Documentation

| Document | Description |
|----------|-------------|
| [Installation Guide](docs/installation.md) | Detailed setup instructions |
| [Quick Start Tutorial](docs/tutorials/quickstart.md) | Get started in 10 minutes |
| [Regional Analysis](docs/tutorials/regional_analysis.md) | Analyze specific regions |
| [Uncertainty Analysis](docs/tutorials/uncertainty_analysis.md) | Monte Carlo and sensitivity |
| [API Reference](docs/api/README.md) | Complete API documentation |
| [01 - Quick Start](docs/examples/01_quickstart.ipynb) | Basic plant sizing and cost analysis |
| [02 - Regional Analysis](docs/examples/02_regional_analysis.ipynb) | Analyze OTEC potential for a region |
| [03 - Uncertainty Analysis](docs/examples/03_uncertainty_analysis.ipynb) | Monte Carlo, Tornado, Sobol |

## Project Structure

```
OTEX/
├── otex/                    # Main package
│   ├── core/               # Thermodynamic cycles and fluids
│   ├── plant/              # Plant sizing and operation
│   ├── economics/          # Cost models and LCOE
│   ├── analysis/           # Uncertainty and sensitivity
│   ├── data/               # Data loading (CMEMS, HYCOM, NetCDF)
│   └── config.py           # Configuration management
├── scripts/                 # CLI scripts
│   ├── regional_analysis.py
│   ├── global_analysis.py
│   └── uncertainty_analysis.py
├── tests/                   # Test suite
├── docs/                    # Documentation
└── data/                    # Reference data files
```

## Configuration Options

| Parameter | Options | Default |
|-----------|---------|---------|
| `cycle_type` | `rankine_closed`, `rankine_open`, `rankine_hybrid`, `kalina`, `uehara` | `rankine_closed` |
| `fluid_type` | `ammonia`, `r134a`, `r245fa`, `propane`, `isobutane` | `ammonia` |
| `cost_level` | `'low_cost'`, `'high_cost'`, or a `CostScheme` object | `'low_cost'` |
| `p_gross` | Any negative value (kW) | `-136000` |
| `data_source` | `'CMEMS'`, `'HYCOM'` | `'CMEMS'` |
| `year` | 1993–present (CMEMS), 1994–2015 / 2019–2024 (HYCOM) | `2020` |

### Custom Cost Schemes

Beyond the two built-in scenarios you can define your own cost parameters with `CostScheme` and Python's standard `dataclasses.replace()`:

```python
from otex.economics import CostScheme, LOW_COST
from dataclasses import replace

# Modify specific parameters of an existing scheme
my_scheme = replace(LOW_COST, turbine_coeff=400, opex_fraction=0.04)

# Use it everywhere cost_level is accepted
inputs = parameters_and_constants(p_gross=-100000, cost_level=my_scheme)
costs, capex, opex, lcoe = capex_opex_lcoe(plant, inputs, my_scheme)
```

All existing code that uses `cost_level='low_cost'` or `cost_level='high_cost'` continues to work unchanged.

## Requirements

- Python >= 3.9
- NumPy, Pandas, SciPy, Matplotlib
- xarray, netCDF4 (oceanographic data)
- tqdm (progress bars)

**Optional:**
- CoolProp (additional working fluids)
- SALib (Sobol sensitivity analysis)

## Acknowledgments

OTEX builds upon [pyOTEC](https://github.com/JKALanger/pyOTEC) by Langer et al. For the original methodology, see:

> Langer, J., Blok, K. *The global techno-economic potential of floating, closed-cycle ocean thermal energy conversion.* J. Ocean Eng. Mar. Energy (2023). https://doi.org/10.1007/s40722-023-00301-1

## Citation

If you use OTEX in your research, please cite:


- Soto Calvo M, and Lee HS., 2025. Ocean Thermal Energy Conversion (OTEC) Potential in Central American and Caribbean Regions: A Multicriteria Analysis for Optimal Sites. Applied Energy. 394: 126182. https://doi.org/10.1016/j.apenergy.2025.126182

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

