ASYNCH¶

ASYNCH

River networks, solved asynchronously.

ASYNCH computes how much water flows in every stream of a river basin, from the rain that falls on it. It cuts the river network into thousands of links, lets every link advance with its own time step, and shares the work between processors with MPI. More than 50 hydrological models are built in, including the Top Layer model (254) of the Iowa Flood Center, and you can add your own, in C or in Python.

Start here Install Python library

Command line

$ mpirun -n 4 asynch my_basin.gbl

A global file (.gbl) names the model, the dates, the network, the rain and the outputs. Running the model explains each part.

Python

from asynch import Simulation

with Simulation("my_basin.gbl") as sim:
    sim.run()
    peak_time, peak_q = sim.peaks          # every link, as NumPy arrays

Change parameters, read states while the model runs, write new models: Using ASYNCH from Python.

A new model

from asynch import Model

model = Model(states=["q"], global_params=["k"], params=["A_h"], forcings=["rain"],
              param_factors={"A_h": 1e6})
model.equations = """
    d_q = (upstream_q + rain * A_h * (0.001 / 3600.0) - q) / k;
"""

Your equations run in the C solver, as fast as a built-in model: A new model.

50+

built-in hydrological models

400 000

links: the whole state of Iowa

2.9×

faster on 4 processes (6 359 links)

119

automatic tests, run on every change

Find your way¶

Start here

What the model computes, how to install it (Ubuntu, WSL or Docker) and run a first simulation.

0. What ASYNCH is, in plain words

Python library

Run and control simulations from Python, and write new models in Python at C speed (Numba).

10. Using ASYNCH from Python

Understand

The asynchronous solver, model 254 equation by equation, a map of the code, just enough C.

4. How the solver works (the mathematics behind advance.c)

Reference

Every file format, every option of the global file, every built-in model, the C and Python APIs.

Input/Output Formats

Quality

What was found and fixed, how serious it was, and how every result is checked against the references.

7. What was fixed, and why it matters

Changes

Every change to the code, and whether it changes numerical results.

Changelog

How a run works¶

A model run: the input files, the three stages inside ASYNCH, the output files

What’s new in 1.7¶

A faster solver for stiff equations (numerical solver index 4). Long simulations run several times faster at the same accuracy, and flood peaks are located more precisely. It is optional: the default solver is unchanged. To use it, change one number in your global file and the tolerances: how to switch.
Runs start sooner: a pause of about one second at start-up is gone.

What’s new in 1.6¶

Every built-in model checked. The units and equations of all models were reviewed systematically and the inconsistencies found were corrected. Results change for some models; model 254 is unchanged. See the changelog.
New tests of the physics: every model is checked for consistency, including from a completely dry state.
pip install asynch-hlm installs the ready-made package from PyPI.

What’s new in 1.5¶

A Python library that works. pip install it, run and change simulations, write models in C, Numba or plain Python, use MPI: chapter 10.
Two critical and ten high-severity bugs fixed, among them wrong coefficients in solver methods 0 and 1, and memory overwritten by the main example: what was fixed.
Networks larger than 65 535 links are counted correctly through the library.
Every result is checked against the reference results of the original ASYNCH: make check runs 96 tests (119 since 1.7), and GitHub Actions run them on every change: reproducibility.
This website, with search, diagrams and a light and dark theme.

The complete list, with the effect of each change on numerical results, is the changelog.