Metadata-Version: 2.4
Name: asynch-hlm
Version: 1.7.0
Summary: Python interface to ASYNCH, an asynchronous solver of hydrological models on river networks
License: GPL-2.0
Project-URL: Documentation, https://gurbuzf.github.io/asynch/
Project-URL: Source, https://github.com/gurbuzf/asynch
Project-URL: Changelog, https://github.com/gurbuzf/asynch/blob/modernization/CHANGELOG.md
Project-URL: Release notes, https://gurbuzf.github.io/asynch/release_notes.html
Keywords: hydrology,river network,ODE,Runge-Kutta,MPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: mpich
Provides-Extra: h5
Requires-Dist: h5py; extra == "h5"
Provides-Extra: fast
Requires-Dist: numba; extra == "fast"
Provides-Extra: mpi
Requires-Dist: mpi4py; extra == "mpi"
Provides-Extra: all
Requires-Dist: h5py; extra == "all"
Requires-Dist: numba; extra == "all"
Requires-Dist: mpi4py; extra == "all"
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist

# asynch-hlm: the Python package of ASYNCH (`import asynch`)

Python interface to [ASYNCH](https://github.com/gurbuzf/asynch), the asynchronous solver of hydrological models on river networks.
The numerical work is done by the C library `libasynch.so`; Python drives it.

```python
from asynch import Simulation
with Simulation("test_2015.gbl") as sim:     # run in examples/
    sim.run()                                # same output files as `asynch test_2015.gbl`
    q = sim.states[:, 0]                     # discharge of every link
```

* `Simulation`: run a global file, advance in steps, get/set states and parameters, custom outputs, MPI.
* `Model`: define a new model with C code (compiled, as fast as the built-in models) or Python functions.
* `GlobalConfig`: read, change and write global files (`.gbl`).
* `asynch.io`: read output files, write input files.

Installation, tutorial and reference: <https://gurbuzf.github.io/asynch/guide/10_python.html>.

**Ready-made (Linux x86-64, glibc 2.31 or newer)**, from [PyPI](https://pypi.org/project/asynch-hlm/). The package
carries the library and the `asynch` program, compiled; pip installs MPI with it (the `mpich` package, with
`mpiexec`). Nothing to build:

```sh
pip install --upgrade pip && pip install asynch-hlm      # the latest version
asynch test.gbl               # the program; mpiexec -n 4 asynch test.gbl
```

`pip install --upgrade asynch-hlm` updates it; `pip install asynch-hlm==<version>` installs a given version. The same
wheels are attached to each release of <https://github.com/gurbuzf/asynch/releases>.

**From the sources**, after building and installing ASYNCH (`make install` puts `libasynch.so` in `/usr/local/lib`):

```sh
pip install ./python          # or: export PYTHONPATH=$PWD/python
python3 -m asynch library     # shows which libasynch.so is used (override with ASYNCH_LIBRARY)
```

Needs Python >= 3.8 and NumPy; h5py to read `.h5` files; a C compiler for models written in C; mpi4py only
to pass another communicator.

## Changelog

The details of every change, with its effect on numerical results, are in [CHANGELOG.md](https://github.com/gurbuzf/asynch/blob/modernization/CHANGELOG.md).

### 1.7.0 (2026-09-28)

A speed release. A new, optional numerical solver for stiff equations makes long simulations several times faster at
the same accuracy, and peaks are located more precisely with it. The default solver is unchanged, so existing
configurations give the same results as 1.6.0. Runs also start about one second sooner.

### 1.6.0 (2026-09-27)

A quality release. The units and equations of every built-in model were checked systematically and the
inconsistencies found were corrected; new tests check the physical consistency of every model. Numerical results
change for some models (listed in the changelog); model 254 gives the same results as 1.5.0. The ready-made
package is now installed with `pip install asynch-hlm`.

### 1.5.0 (2026-09-26)

The first release of this branch: a Python library (`asynch`: run and change simulations, new models in C, Numba or
Python, MPI), installable on Linux with pip without building anything, many reliability fixes, support for networks
above 65 535 links, automated tests against the reference results, GitHub Actions, and a documentation website.
