Metadata-Version: 2.4
Name: pyhelmholtz
Version: 0.1.1
Summary: PyHelmholtz is a framework for benchmarking absorbing boundary methods for 2D Helmholtz equation.
Author-email: Sirawit Inpuak <sirawit.inp@hotmail.com>, Chaiwoot Boonyasiriwat <chaiwoot@gmail.com>
Project-URL: Homepage, https://github.com/chaiwoot/PyHelmholtz
Project-URL: Issues, https://github.com/chaiwoot/PyHelmholtz/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib
Provides-Extra: suitesparse
Requires-Dist: scikit-sparse>=0.4.0; extra == "suitesparse"
Provides-Extra: mumps
Requires-Dist: pymumps; sys_platform != "win32" and extra == "mumps"

# 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 initialize a basic setup and let `PyHelmholtz` automatically fall back to SciPy if `scikit-sparse` isn't installed.

```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.
