Metadata-Version: 2.1
Name: supy
Version: 2026.1.28
Summary: The SUEWS model that speaks Python
Author-Email: Dr Ting Sun <ting.sun@ucl.ac.uk>
License: GPL-V3.0
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Requires-Dist: pandas
Requires-Dist: numpy>=2.0
Requires-Dist: scipy<1.15; python_version >= "3.11" and python_version < "3.13" and platform_system == "Linux"
Requires-Dist: scipy; python_version < "3.11" or python_version >= "3.13" or platform_system != "Linux"
Requires-Dist: pydantic
Requires-Dist: pyyaml
Requires-Dist: f90nml
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: chardet
Requires-Dist: click
Requires-Dist: pyarrow<21,>=20; python_version < "3.14" and platform_system == "Linux"
Requires-Dist: pyarrow>=20; python_version < "3.14" and platform_system != "Linux"
Requires-Dist: pyarrow>=22; python_version >= "3.14"
Requires-Dist: atmosp
Requires-Dist: scikit-learn
Requires-Dist: lmfit
Requires-Dist: cdsapi
Requires-Dist: tzfpy>=1.0.0
Requires-Dist: pytz
Requires-Dist: jsonschema
Requires-Dist: rich
Requires-Dist: packaging
Provides-Extra: tmy
Requires-Dist: pvlib; extra == "tmy"
Requires-Dist: metpy; extra == "tmy"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: fprettify; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: sphinx<8.2,>=4.0; extra == "dev"
Requires-Dist: sphinx-autobuild; extra == "dev"
Requires-Dist: sphinx-book-theme; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: recommonmark; extra == "dev"
Requires-Dist: pybtex; extra == "dev"
Requires-Dist: sphinxcontrib.bibtex~=2.4; extra == "dev"
Requires-Dist: sphinx-panels; extra == "dev"
Requires-Dist: sphinx-design; extra == "dev"
Requires-Dist: sphinx-last-updated-by-git; extra == "dev"
Requires-Dist: sphinx-click; extra == "dev"
Requires-Dist: sphinx_comments; extra == "dev"
Requires-Dist: sphinx-gallery>=0.16.0; extra == "dev"
Requires-Dist: docutils<0.17,>=0.16; extra == "dev"
Requires-Dist: jinja2>=3.0; extra == "dev"
Description-Content-Type: text/markdown

# SUEWS - Surface Urban Energy and Water Balance Scheme

This is the SUEWS urban climate model repository.

## Installation

```bash
pip install supy
```

## Documentation

See the full documentation at: https://suews.readthedocs.io

## Quick Start

For users who want to run SUEWS simulations:

1. **Install from PyPI** (simplest):
   ```bash
   pip install supy
   ```

2. **Run a simulation**:
   ```bash
   suews-run /path/to/config.yml
   ```

For developers, see the [Developer Note](#developer-note) section below.

## Developer Note

### Development Environment

#### Claude Code Integration

SUEWS includes Claude Code configuration in the `.claude/` directory with development skills for environment setup, code linting, build verification, PR review, and release management.

**Install Skills via Marketplace** (recommended for new contributors):
```
# In Claude Code, add the SUEWS skills marketplace
/plugin marketplace add UMEP-dev/SUEWS

# Then install the skills
/plugin install suews-dev@UMEP-dev/SUEWS
```

This provides access to:
* `/setup-dev` - Set up development environment (macOS, Linux, Windows)
* `/lint-code` - Check code style against SUEWS conventions
* `/verify-build` - Verify build configuration consistency
* `/audit-pr` - Review pull requests comprehensively
* `/examine-issue` - Analyse GitHub issues
* `/log-changes` - Update CHANGELOG with recent commits
* `/prep-release` - Prepare releases with pre-flight checks
* `/sync-docs` - Check doc-code consistency

**Local Configuration** (for contributors with cloned repo):
* **Setup Guide**: See [`.claude/README.md`](.claude/README.md) for workspace structure
* **Skills Reference**: See [`.claude/skills/`](.claude/skills/) for detailed workflows

#### CLAUDE.md Protection System

This repository includes automatic protection for the CLAUDE.md configuration file to prevent accidental content loss:

* **Automatic Features** (no setup required):
  - GitHub Actions validation on all PRs/pushes affecting CLAUDE.md
  - Content reduction detection (alerts if >20% content removed)
  - Automatic snapshots on validation failures

* **Local Protection** (one-time setup):
  ```bash
  # Run once after cloning or pulling this feature
  bash .claude/scripts/setup-claude-protection.sh
  ```
  This enables:
  - Git pre-commit validation
  - Local backup system
  - Manual validation: `python3 .claude/scripts/validate-claude-md.py`

#### Local Development

Follow these steps to set up local development:

##### Prerequisites

**Essential Tools**:
* **Fortran Compiler**: [gfortran](https://gcc.gnu.org/wiki/GFortran) (≥ 9.3.0) or Intel ifort
  - macOS: `brew install gcc`
  - Ubuntu/Debian: `sudo apt-get install gfortran`
  - Windows: Use WSL or MinGW-w64
* **Version Control**: [git](https://git-scm.com/)
* **Package Manager**: [mamba](https://mamba.readthedocs.io/en/latest/) (faster than conda)
  ```bash
  # Install mambaforge (if not already installed)
  curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
  bash Miniforge3-$(uname)-$(uname -m).sh
  ```

**Recommended Tools**:
* [VS Code](https://code.visualstudio.com/) with extensions:
  - Modern Fortran
  - Python
  - GitHub Copilot (free for academic use)
* [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) (Windows users)

##### Setup Steps

1. **Clone the repository**:
   ```bash
   git clone https://github.com/UMEP-dev/SUEWS.git
   cd SUEWS
   ```

2. **Initialise submodules** (required for SPARTACUS dependency):
   ```bash
   git submodule init
   git submodule update
   ```
   *Note: If permission denied, [configure SSH for GitHub](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh)*

3. **Create development environment**:
   ```bash
   mamba env create -f env.yml
   ```
   This creates `suews-dev` environment with all required packages.

4. **Activate environment**:
   ```bash
   mamba activate suews-dev
   ```

5. **Build SUEWS**:
   ```bash
   make dev       # Install in editable mode
   make test      # Run tests (optional)
   ```
   *Run `make` to see all available commands and quick start workflows.*

6. **Verify installation**:
   ```bash
   pip show supy
   suews-run --help
   ```

##### Development Workflow

* **Build commands**:
  ```bash
  make dev          # Install in editable mode (self-healing, works after clean)
  make test         # Run test suite only
  make clean        # Clean build artifacts (smart - keeps .venv if active)
  make docs         # Build documentation
  make livehtml     # Live documentation preview
  make              # Show help summary (default target)
  ```

* **Common workflows**:
  ```bash
  make clean && make dev    # Fresh start (most common for troubleshooting)
  git pull && make dev      # Update code and rebuild
  make dev && make test     # Build and test changes
  ```

* **Environment management**:
  ```bash
  make help         # Show all available commands
  make deactivate   # Show deactivation command
  ```

* **Common issues**:
  - **Build conflicts**: Run `make clean && make dev` (most reliable)
  - **Import errors**: Ensure you're in the `suews-dev` environment
  - **Permission errors on Windows**: Right-click project folder → Properties → Security → Edit → Everyone → Allow

##### Project Structure

```
SUEWS/
├── src/
│   ├── suews/          # Fortran physics engine
│   ├── supy/           # Python interface
│   └── supy_driver/    # F2Py wrapper
├── test/               # Test suite
├── docs/               # Documentation source
├── env.yml             # Development environment
└── Makefile            # Build commands
```


## Contributing

### Code Style and Formatting

SUEWS maintains consistent code style through automated formatting:

* **Coding Standards**: See [`CODING_GUIDELINES.md`](dev-ref/CODING_GUIDELINES.md) for detailed standards
* **Automated Formatting**: The master branch is automatically formatted after merge
* **Zero Friction**: Contributors can focus on functionality; formatting is handled by machines
* **Tools Used**:
  - Python: [`ruff`](https://docs.astral.sh/ruff/) (configuration in `.ruff.toml`)
  - Fortran: [`fprettify`](https://github.com/pseewald/fprettify) (configuration in `.fprettify.rc`)

**For Contributors**: Just write working code! Formatting will be applied automatically after merge.

### Testing Development Versions

For developers who need to test pre-release versions from test.pypi.org:

**1. Install uv (one-time setup):**
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**2. Create isolated environment with uv:**
```bash
uv venv .venv-dev
source .venv-dev/bin/activate  # Linux/macOS
# or: .venv-dev\Scripts\activate  # Windows
# You'll see (.venv-dev) in your terminal prompt when activated
```
Note: `uv venv` is 80x faster than `python -m venv` and manages Python versions automatically.

**3. Check latest version:**
Visit https://test.pypi.org/project/supy/ to find the latest development version (format: `YYYY.M.D.dev0`)

**4. Install development version:**
```bash
# Replace 2025.9.16.dev0 with the latest version from step 3
uv pip install --extra-index-url https://test.pypi.org/simple/ \
              --index-strategy unsafe-best-match \
              supy==2025.9.16.dev0
```

**5. Verify installation:**
```bash
python -c "import supy; print(f'SUEWS version: {supy.__version__}')"
# Should show: 2025.9.16.dev0 (or your installed version)
```

**6. Test functionality:**
```bash
python -c "import supy as sp; sp.load_sample_data(); print('✓ Installation successful')"
```

**For future use:** Always activate the environment before working:
```bash
source .venv-dev/bin/activate  # Linux/macOS
# or: .venv-dev\Scripts\activate  # Windows
# Use 'deactivate' to exit the environment
```

**Why uv?** 
- Creates virtual environments 80x faster than `python -m venv`
- Handles test.pypi.org dependencies correctly with `--index-strategy unsafe-best-match`
- Single tool for both environment and package management
- No Python installation required (uv can download Python as needed)
