# harmonic-measure

Harmonic measure computation and boundary crowding diagnostics for 2D domains.

[![PyPI version](https://img.shields.io/pypi/v/harmonic-measure.svg)](https://pypi.org/project/harmonic-measure/)
[![Python versions](https://img.shields.io/pypi/pyversions/harmonic-measure.svg)](https://pypi.org/project/harmonic-measure/)
[![License](https://img.shields.io/github/license/egoughnour/harmonic-measure.svg)](https://github.com/egoughnour/harmonic-measure/blob/main/LICENSE)
[![CI](https://github.com/egoughnour/harmonic-measure/actions/workflows/ci.yml/badge.svg)](https://github.com/egoughnour/harmonic-measure/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://egoughnour.github.io/harmonic-measure/)
[![codecov](https://codecov.io/gh/egoughnour/harmonic-measure/branch/main/graph/badge.svg)](https://codecov.io/gh/egoughnour/harmonic-measure)

## Overview

Harmonic measure quantifies the "visibility" of boundary subsets from interior points in potential-theoretic terms. This package provides:

- **Direct computation** of harmonic measure via boundary integral methods
- **Corner detection** for domains approaching polygonal limits
- **Scaling diagnostics** to quantify boundary crowding
- **Visualization** of harmonic measure density on boundaries

## Installation

```bash
pip install harmonic-measure

# With plotting
pip install harmonic-measure[plot]
```

## Quick Start

```python
from harmonic_measure import HarmonicMeasure
from superellipse import Superellipse

# Create a Lamé domain approaching a rectangle
curve = Superellipse(a=1, b=1, p=32)  # p=2n, so n=16

# Compute harmonic measure of a boundary subset
hm = HarmonicMeasure(curve)
omega = hm.measure_subset(
    basepoint=[0, 0],
    subset_fn=lambda pt: abs(pt[0] - 1) < 0.1  # near corner
)
print(f"Harmonic measure of corner neighborhood: {omega:.6f}")
```

## Theory

### Harmonic Measure

For a domain Ω with boundary ∂Ω, the harmonic measure ω_Ω(z, A) of a boundary subset A ⊂ ∂Ω as seen from z ∈ Ω is:

$$\omega_\Omega(z, A) = u_A(z)$$

where u_A solves: Δu = 0 in Ω, u = 1 on A, u = 0 on ∂Ω \ A.

### Conformal Invariance

Under a conformal map f: 𝔻 → Ω with f(0) = z:

$$\omega_\Omega(z, A) = \frac{|f^{-1}(A)|}{2\pi}$$

where |·| denotes arc length on ∂𝔻.

### Corner Crowding

For polygonal limits with interior angle α, boundary layers of thickness ρ have:

$$\omega \sim \rho^{\pi/\alpha}$$

For right angles (α = π/2): ω ~ ρ² (quadratic crowding)

## API Reference

### `HarmonicMeasure(geometry)`

Main class for harmonic measure computations.

| Method | Description |
|--------|-------------|
| `measure_subset(basepoint, subset_fn)` | Harmonic measure of subset defined by boolean function |
| `measure_corners(basepoint, radius)` | Harmonic measure of corner neighborhoods |
| `density(basepoint)` | Harmonic measure density at each boundary node |
| `plot_density(basepoint)` | Visualize density on boundary |

### `corner_scaling_diagnostic(curve, ns, c=2.0)`

Compute corner harmonic mass across a range of Lamé exponents.

Returns (ns, arc_lengths, fitted_slope).

### `adaptive_convergence(n, a, c, tol=1e-10)`

Adaptively refine discretization until harmonic measure converges.

## CLI

```bash
# Compute harmonic measure of corner regions
harmonic-measure corners --p 32 --radius 0.1

# Scaling diagnostic across exponents
harmonic-measure scaling --ns 8 16 32 64 --output scaling.csv

# Plot harmonic measure density
harmonic-measure density --p 16 --output density.png
```

## Applications

- **Conformal mapping**: Diagnose boundary correspondence crowding
- **Schwarz-Christoffel limits**: Quantify prevertex clustering
- **Brownian motion**: Exit distribution from domains
- **Potential theory**: Capacity and extremal length computations

## Related Packages

- [`superellipse`](https://github.com/egoughnour/superellipse): Geometry primitives
- [`panel-bie`](https://github.com/egoughnour/panel-bie): Boundary integral solvers

## References

- Garnett, J.B. & Marshall, D.E. (2005). *Harmonic Measure*. Cambridge University Press.
- Pommerenke, C. (1992). *Boundary Behaviour of Conformal Maps*. Springer.

## License

MIT License. See [LICENSE](LICENSE) for details.
