# `kh2d-solver`: Python-based incompressible Kelvin-Helmholtz 2D Instability Solver
[](https://www.python.org/downloads/)
[](http://www.wtfpl.net/about/)
[](https://github.com/psf/black)
[](https://numba.pydata.org/)
[](https://badge.fury.io/py/kh2d-solver)
[](https://doi.org/10.5281/zenodo.17096830)
A high-performance solver for 2D Kelvin-Helmholtz instability for incompressible flows using finite difference methods with Numba acceleration.
## Features
- Numba JIT compilation for 10-50x speedup
- Multi-core parallelization support
- High-order finite difference schemes
- FFT-based Poisson solver
- Multiple predefined scenarios (shear layers, rotating flows, forced turbulence)
- NetCDF output format
- Animated GIF generation
- Conservation monitoring (mass, momentum, energy)
## Installation
### Install from PyPI (Recommended)
```bash
pip install kh2d-solver
```
### Install from Source
```bash
git clone https://github.com/sandyherho/kelvin-helmholtz-2d-solver.git
cd kelvin-helmholtz-2d-solver
pip install .
```
### Development Installation
For development with editable installation:
```bash
git clone https://github.com/sandyherho/kelvin-helmholtz-2d-solver.git
cd kelvin-helmholtz-2d-solver
pip install -e .
```
## Quick Start
Run simulations directly after installation:
```bash
# Run a basic shear layer simulation
kh2d-simulate basic_shear
# Run with multiple cores (e.g., 8 cores)
kh2d-simulate basic_shear --cores 8
# Run all predefined scenarios
kh2d-simulate --all
# Use a custom configuration
kh2d-simulate --config my_config.txt
```
### Python API Usage
```python
import numpy as np
from kh2d_solver import KH2DSolver, ShearLayer
# Create solver
solver = KH2DSolver(nx=256, nz=128, lx=2.0, lz=1.0)
# Set initial conditions
ic = ShearLayer(shear_thickness=0.05, u_top=1.0, u_bot=-1.0)
u0, w0, rho0 = ic(solver.x, solver.z)
# Run simulation
result = solver.solve(
u0=u0, w0=w0, rho0=rho0,
t_final=10.0,
reynolds=1000,
richardson=0.25
)
# Access results
vorticity = result['vorticity']
density = result['rho']
```
## Performance Options
The solver automatically uses Numba JIT compilation for critical loops. You can control parallelization:
```bash
# Use all available cores (default)
kh2d-simulate basic_shear
# Specify number of cores
kh2d-simulate basic_shear --cores 4
# Disable parallelization (single core)
kh2d-simulate basic_shear --cores 1
```
## Configuration
Configuration files are simple text files with key-value pairs:
```text
# Example configuration
scenario_name = My Simulation
nx = 256
nz = 128
t_final = 10.0
reynolds = 1000
richardson = 0.25
n_cores = 8 # Optional: specify cores (default: all available)
```
## Predefined Scenarios
1. **basic_shear** - Classical Kelvin-Helmholtz instability
2. **double_shear** - Double shear layer configuration
3. **rotating** - KH instability with system rotation
4. **forced** - Forced turbulence with energy injection
All scenarios use a unified 2.0 × 1.0 domain for direct comparison.
## Output
The solver generates:
- NetCDF files with complete flow field data
- Animated GIFs showing vorticity (ω_z) and density evolution
- Log files with simulation parameters and performance metrics
## Physics
The solver solves the 2D incompressible Navier-Stokes equations with density stratification:
- Continuity: ∇·**u** = 0
- Momentum: ∂**u**/∂t + (**u**·∇)**u** = -(1/ρ₀)∇p + ν∇²**u** - (ρ/ρ₀)g**k**
- Density: ∂ρ/∂t + **u**·∇ρ = κ∇²ρ
The vorticity shown is the z-component: ω_z = ∂w/∂x - ∂u/∂z
## Publishing to PyPI (For Maintainers)
### First-time Setup
1. **Create PyPI Account**: Register at [pypi.org](https://pypi.org)
2. **Get API Token**: Account Settings → API tokens → Create token
3. **Configure Poetry**:
```bash
poetry config pypi-token.pypi pypi-XXXXXXXX
```
### Publishing Process
```bash
# Update version in pyproject.toml
poetry version patch # or minor/major
# Build the package
poetry build
# Publish to PyPI
poetry publish
```
### Version Management
Follow semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR: Breaking changes
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes
## Requirements
- Python 3.8+
- NumPy
- SciPy
- Matplotlib
- netCDF4
- tqdm
- Numba
## Authors
- Sandy H. S. Herho (sandy.herho@email.ucr.edu)
- Faiz R. Fajary
- Iwan P. Anwar
- Faruq Khadami
- Gandhi Napitupulu
- Nurjanna J. Trilaksono
## License
This project is licensed under the WTFPL - Do What The F*ck You Want To Public License.
See the [LICENSE](LICENSE) file for details.
## Citation
If you use this software in your research, please cite:
```bibtex
@software{kh2d_solver_2025,
title = {Kelvin-Helmholtz 2D Instability Solver},
author = {Herho, Sandy H. S. and Fajary, Faiz R. and Anwar, Iwan P. and
Khadami, Faruq and Napitupulu, Gandhi and Trilaksono, Nurjanna J.},
year = {2025},
version = {0.1.0},
url = {https://github.com/sandyherho/kelvin-helmholtz-2d-solver}
}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For issues, questions, or suggestions, please open an issue on [GitHub](https://github.com/sandyherho/kelvin-helmholtz-2d-solver/issues).
Raw data
{
"_id": null,
"home_page": "https://github.com/sandyherho/kelvin-helmholtz-2d-solver",
"name": "kh2d-solver",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "fluid-dynamics, kelvin-helmholtz, instability, CFD, numerical-simulation, numba",
"author": "Sandy H. S. Herho",
"author_email": "sandy.herho@email.ucr.edu",
"download_url": "https://files.pythonhosted.org/packages/cc/87/2f60778a2197a9ecea7bbf878c609c931fe829e32be48e61a56a5c0c2c2e/kh2d_solver-0.1.1.tar.gz",
"platform": null,
"description": "# `kh2d-solver`: Python-based incompressible Kelvin-Helmholtz 2D Instability Solver\n\n[](https://www.python.org/downloads/)\n[](http://www.wtfpl.net/about/)\n[](https://github.com/psf/black)\n[](https://numba.pydata.org/)\n[](https://badge.fury.io/py/kh2d-solver)\n[](https://doi.org/10.5281/zenodo.17096830)\n\nA high-performance solver for 2D Kelvin-Helmholtz instability for incompressible flows using finite difference methods with Numba acceleration.\n\n## Features\n\n- Numba JIT compilation for 10-50x speedup\n- Multi-core parallelization support\n- High-order finite difference schemes\n- FFT-based Poisson solver\n- Multiple predefined scenarios (shear layers, rotating flows, forced turbulence)\n- NetCDF output format\n- Animated GIF generation\n- Conservation monitoring (mass, momentum, energy)\n\n## Installation\n\n### Install from PyPI (Recommended)\n\n```bash\npip install kh2d-solver\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/sandyherho/kelvin-helmholtz-2d-solver.git\ncd kelvin-helmholtz-2d-solver\npip install .\n```\n\n### Development Installation\n\nFor development with editable installation:\n```bash\ngit clone https://github.com/sandyherho/kelvin-helmholtz-2d-solver.git\ncd kelvin-helmholtz-2d-solver\npip install -e .\n```\n\n## Quick Start\n\nRun simulations directly after installation:\n\n```bash\n# Run a basic shear layer simulation\nkh2d-simulate basic_shear\n\n# Run with multiple cores (e.g., 8 cores)\nkh2d-simulate basic_shear --cores 8\n\n# Run all predefined scenarios\nkh2d-simulate --all\n\n# Use a custom configuration\nkh2d-simulate --config my_config.txt\n```\n\n### Python API Usage\n\n```python\nimport numpy as np\nfrom kh2d_solver import KH2DSolver, ShearLayer\n\n# Create solver\nsolver = KH2DSolver(nx=256, nz=128, lx=2.0, lz=1.0)\n\n# Set initial conditions\nic = ShearLayer(shear_thickness=0.05, u_top=1.0, u_bot=-1.0)\nu0, w0, rho0 = ic(solver.x, solver.z)\n\n# Run simulation\nresult = solver.solve(\n u0=u0, w0=w0, rho0=rho0,\n t_final=10.0,\n reynolds=1000,\n richardson=0.25\n)\n\n# Access results\nvorticity = result['vorticity']\ndensity = result['rho']\n```\n\n## Performance Options\n\nThe solver automatically uses Numba JIT compilation for critical loops. You can control parallelization:\n\n```bash\n# Use all available cores (default)\nkh2d-simulate basic_shear\n\n# Specify number of cores\nkh2d-simulate basic_shear --cores 4\n\n# Disable parallelization (single core)\nkh2d-simulate basic_shear --cores 1\n```\n\n## Configuration\n\nConfiguration files are simple text files with key-value pairs:\n\n```text\n# Example configuration\nscenario_name = My Simulation\nnx = 256\nnz = 128\nt_final = 10.0\nreynolds = 1000\nrichardson = 0.25\nn_cores = 8 # Optional: specify cores (default: all available)\n```\n\n## Predefined Scenarios\n\n1. **basic_shear** - Classical Kelvin-Helmholtz instability\n2. **double_shear** - Double shear layer configuration\n3. **rotating** - KH instability with system rotation\n4. **forced** - Forced turbulence with energy injection\n\nAll scenarios use a unified 2.0 \u00d7 1.0 domain for direct comparison.\n\n## Output\n\nThe solver generates:\n- NetCDF files with complete flow field data\n- Animated GIFs showing vorticity (\u03c9_z) and density evolution\n- Log files with simulation parameters and performance metrics\n\n## Physics\n\nThe solver solves the 2D incompressible Navier-Stokes equations with density stratification:\n\n- Continuity: \u2207\u00b7**u** = 0\n- Momentum: \u2202**u**/\u2202t + (**u**\u00b7\u2207)**u** = -(1/\u03c1\u2080)\u2207p + \u03bd\u2207\u00b2**u** - (\u03c1/\u03c1\u2080)g**k**\n- Density: \u2202\u03c1/\u2202t + **u**\u00b7\u2207\u03c1 = \u03ba\u2207\u00b2\u03c1\n\nThe vorticity shown is the z-component: \u03c9_z = \u2202w/\u2202x - \u2202u/\u2202z\n\n## Publishing to PyPI (For Maintainers)\n\n### First-time Setup\n\n1. **Create PyPI Account**: Register at [pypi.org](https://pypi.org)\n2. **Get API Token**: Account Settings \u2192 API tokens \u2192 Create token\n3. **Configure Poetry**:\n```bash\npoetry config pypi-token.pypi pypi-XXXXXXXX\n```\n\n### Publishing Process\n\n```bash\n# Update version in pyproject.toml\npoetry version patch # or minor/major\n\n# Build the package\npoetry build\n\n# Publish to PyPI\npoetry publish\n```\n\n### Version Management\n\nFollow semantic versioning (MAJOR.MINOR.PATCH):\n- MAJOR: Breaking changes\n- MINOR: New features (backwards compatible)\n- PATCH: Bug fixes\n\n## Requirements\n\n- Python 3.8+\n- NumPy\n- SciPy\n- Matplotlib\n- netCDF4\n- tqdm\n- Numba\n\n## Authors\n\n- Sandy H. S. Herho (sandy.herho@email.ucr.edu)\n- Faiz R. Fajary\n- Iwan P. Anwar\n- Faruq Khadami\n- Gandhi Napitupulu\n- Nurjanna J. Trilaksono\n\n## License\n\nThis project is licensed under the WTFPL - Do What The F*ck You Want To Public License.\nSee the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use this software in your research, please cite:\n\n```bibtex\n@software{kh2d_solver_2025,\n title = {Kelvin-Helmholtz 2D Instability Solver},\n author = {Herho, Sandy H. S. and Fajary, Faiz R. and Anwar, Iwan P. and \n Khadami, Faruq and Napitupulu, Gandhi and Trilaksono, Nurjanna J.},\n year = {2025},\n version = {0.1.0},\n url = {https://github.com/sandyherho/kelvin-helmholtz-2d-solver}\n}\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues, questions, or suggestions, please open an issue on [GitHub](https://github.com/sandyherho/kelvin-helmholtz-2d-solver/issues).\n",
"bugtrack_url": null,
"license": "WTFPL",
"summary": "A high-performance solver for 2D Kelvin-Helmholtz instability with Numba acceleration",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/sandyherho/kelvin-helmholtz-2d-solver/blob/main/README.md",
"Homepage": "https://github.com/sandyherho/kelvin-helmholtz-2d-solver",
"Repository": "https://github.com/sandyherho/kelvin-helmholtz-2d-solver"
},
"split_keywords": [
"fluid-dynamics",
" kelvin-helmholtz",
" instability",
" cfd",
" numerical-simulation",
" numba"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd038f40989f59ec0f6577d9a6938117961405e982fb9b273c2d7414f6fbdc83",
"md5": "f8e8f989368bf2c42d671045e886d8b8",
"sha256": "591c35912ff55558a04632b9ead851fecce77cb727882a93b3152ff0a5099960"
},
"downloads": -1,
"filename": "kh2d_solver-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f8e8f989368bf2c42d671045e886d8b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 18622,
"upload_time": "2025-09-11T05:20:33",
"upload_time_iso_8601": "2025-09-11T05:20:33.806682Z",
"url": "https://files.pythonhosted.org/packages/fd/03/8f40989f59ec0f6577d9a6938117961405e982fb9b273c2d7414f6fbdc83/kh2d_solver-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc872f60778a2197a9ecea7bbf878c609c931fe829e32be48e61a56a5c0c2c2e",
"md5": "d53589c07ca811d352ccc449e05ba078",
"sha256": "7864736776481c730495c40b05efa4fbfc9fe68a6211cff3bfd39fefb8b1887f"
},
"downloads": -1,
"filename": "kh2d_solver-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d53589c07ca811d352ccc449e05ba078",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 16946,
"upload_time": "2025-09-11T05:20:35",
"upload_time_iso_8601": "2025-09-11T05:20:35.588645Z",
"url": "https://files.pythonhosted.org/packages/cc/87/2f60778a2197a9ecea7bbf878c609c931fe829e32be48e61a56a5c0c2c2e/kh2d_solver-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 05:20:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sandyherho",
"github_project": "kelvin-helmholtz-2d-solver",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kh2d-solver"
}
JSON
