Metadata-Version: 2.4
Name: pyhelmholtz
Version: 0.1.3
Summary: PyHelmholtz is a framework for benchmarking absorbing boundary methods for 2D Helmholtz equation.
Project-URL: Homepage, https://github.com/chaiwoot/PyHelmholtz
Project-URL: Issues, https://github.com/chaiwoot/PyHelmholtz/issues
Author: S. Inpuak & C. Boonyasiriwat
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Requires-Dist: matplotlib
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: mumps
Requires-Dist: pymumps; (sys_platform != 'win32') and extra == 'mumps'
Provides-Extra: suitesparse
Requires-Dist: scikit-sparse>=0.4.0; extra == 'suitesparse'
Description-Content-Type: text/markdown

# PyHelmholtz

A Python package for solving the 2D Helmholtz equation and benchmarking absorbing boundary methods.

## Features

- Fast frequency-domain wave propagation modeling.
- Support for standard sparse direct solvers via SciPy.
- Optional high-performance nested dissection algorithms via SuiteSparse.
- Optional parallel direct solver acceleration via MUMPS.

---

## Installation

`PyHelmholtz` provides three installation tiers depending on your performance needs and platform.

### 1. Standard Installation (Recommended)
If you only need standard solvers using SciPy's `spsolve()`, you can install `PyHelmholtz` instantly with no external C-library or compiler requirements:

```bash
pip install pyhelmholtz
```

### 2. With Nested Dissection Support (Optional)
To enable advanced nested dissection algorithms, the package requires `scikit-sparse`. Because this depends on underlying SuiteSparse C-libraries, it is highly recommended to install the dependencies via **Conda** first to avoid compilation issues (especially on Windows):

```bash
# Install the C-libraries and pre-compiled wrapper via Conda
conda install -c conda-forge scikit-sparse

# Install PyHelmholtz with the optional suitesparse feature flag
pip install pyhelmholtz[suitesparse]
```

### 3. With MUMPS Acceleration (Optional, Linux only)
For large-scale problems requiring parallel direct solvers, `PyHelmholtz` interfaces with MUMPS via `PyMUMPS`. 

Because this relies on compiled Fortran, MPI, and BLAS/LAPACK binaries, you **must install the system MUMPS libraries first** before installing the Python package:

```bash
# Install system MUMPS and MPI development libraries (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install libmumps-dev

# Install PyHelmholtz with the optional mumps feature flag
pip install pyhelmholtz[mumps]
```

---

## Quick Start

Here is a quick example of how to use `PyHelmholtz` to solve the Helmholtz equation using the default parameters:
- homogeneous domain of size [-1,1]x[-1,1] m^2 with wave speed of <img src="https://latex.codecogs.com/svg.image?3^8" /> m/s and grid spacing of 1 cm
- point source of frequency <img src="https://latex.codecogs.com/svg.image?2^9" /> Hz located at the center of the domain

```python
import pyhelmholtz as ph
ho = ph. Helmholtz () # create an Helmholtz object with default parameters
ho. solve ()          # SciPy ’s spsolve () is used by default as the sparse linear solver
ho. viz ()            # visualize the real part of the wave field u
```

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.