OPI - Orographic Precipitation and Isotopes

A comprehensive model for analyzing precipitation and water isotope fractionation associated with steady atmospheric flow over arbitrary three-dimensional topography.

📦 Two Versions Available

This repository contains two implementations of the OPI model:

Version	Language	Status	Documentation
MATLAB	MATLAB R2020b+	✅ Original	MATLAB Docs
Python	Python 3.8+	✅ Ported	Python Docs

🎯 Quick Start

Choose Your Version

# For MATLAB users
cd matlab/
# See matlab/README.md for instructions

# For Python users
cd python/
pip install -e ".[all]"
# See python/README.md for instructions

📚 Learning Path

For New Users

1. Read Getting Started
2. Try the Gaussian Mountain Example
3. Explore your preferred version

For MATLAB Users Learning Python

1. Start with MATLAB to Python Guide
2. Compare side-by-side examples
3. See function mapping

For Python Users

1. See Python Quick Start
2. Try Jupyter Notebooks
3. Explore examples

📂 Repository Structure

OPI/
├── README.md                 # This file - main entry point
├── LICENSE                   # MIT License
├── docs/                     # Shared documentation
│   ├── getting-started.md   # Getting started guide
│   ├── comparison/          # MATLAB vs Python comparison
│   └── theory/              # Theoretical background
│
├── matlab/                   # MATLAB implementation
│   ├── README.md            # MATLAB-specific docs
│   ├── OPI_programs/        # Main programs
│   ├── private/             # Core functions
│   ├── data/                # Sample data
│   └── runs/                # Run files & output
│
├── python/                   # Python implementation
│   ├── README.md            # Python-specific docs
│   ├── opi/                 # Main package
│   ├── tests/               # Test suite
│   ├── examples/            # Examples
│   └── notebooks/           # Jupyter notebooks
│
└── examples/                 # Shared/comparative examples
    ├── gaussian-mountain/   # Same case in both languages
    ├── himalaya/            # Real-world case study
    └── README.md            # Example guide

🔬 Side-by-Side Comparison

Feature	MATLAB	Python
Installation	MATLAB R2020b+	pip install -e ".[all]"
Quick Start	Run opiCalc_OneWind.m	from opi import OneWindModel
Documentation	MATLAB Docs	Python Docs
Examples	MATLAB Examples	Python Examples
Visualization	MATLAB plots	Matplotlib + advanced viz
Parallel	Parallel Computing Toolbox	joblib, multiprocessing
I/O	.mat files	NumPy, NetCDF, GeoTIFF, etc.

📖 Documentation

Main Documentation

• Getting Started - Start here!
• Installation Guide - Detailed installation
• Theory & Background - Physical basis

Comparison Documentation

• MATLAB vs Python - Feature comparison
• MATLAB to Python Guide - Migration guide
• Function Mapping - Function correspondence
• Syntax Differences - Syntax comparison

Version-Specific Docs

• MATLAB Documentation
• Python Documentation

🎓 Examples

Comparative Examples (Same case in both languages)

• Gaussian Mountain - Idealized case
• Simple Ridge - 2D ridge case
• Himalaya - Real-world application

MATLAB Examples

See matlab/examples/

Python Examples

See python/examples/

🔄 Function Mapping

MATLAB Function	Python Function	Location
opiCalc_OneWind	OneWindModel.run()	opi/models/
baseState	base_state()	opi/core/
fourierSolution	fourier_solution()	opi/core/
precipitationGrid	precipitation_grid()	opi/core/
isotopeGrid	isotope_grid()	opi/core/
fminCRS3	CRS3Optimizer	opi/solvers/

See full mapping for complete list.

🛠️ Development

Contributing

We welcome contributions to both versions! See:

• Contributing Guide
• MATLAB Contributing
• Python Contributing

Testing

# MATLAB
run(matlab/tests/run_tests.m)

# Python
cd python/
pytest tests/ -v

📚 Citation

If you use OPI in your research, please cite:

@software{opi_model,
  title = {OPI: Orographic Precipitation and Isotopes},
  author = {Brandon, Mark},
  year = {2024},
  note = {MATLAB original; Python port available}
}

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: ...

🙏 Acknowledgments

• MATLAB Original: Mark Brandon, Yale University
• Python Port: AI Assistant & Contributors
• Theory: Based on Smith & Barstad (2004), Durran & Klemp (1982)

---

Choose your path: MATLAB | Python | Compare