ANNESI: Artificial neural network for estuarine salt intrusion

This repository is part of a PhD research on developing nature-based solutions to mitigate salt intrusion (for more information, see the central repository).

Part of this research is a sensitivity analysis of estuarine salt intrusion to estuarine characteristics. As a by-product of the sensitivity analysis, a neural network has been trained to the elaborate data set created, consisting of 1,252 simulations with Delft3D Flexible Mesh (specifically the D-Flow module).

The neural network is contained in this repository but is accessible via a web-API on the website of SALTISolutions of which the GitHub-repository is called ANNESI-web. The neural network can also be used without the web-API (see src).

Requirements

This repository has the following requirements (see also requirements.txt):

• numpy==1.19.4
• pandas==1.1.4
• torch==1.9.0
• scikit_learn==0.24.2
• joblib==1.0.1

For the installation of torch, please look at their installation guide; the installation of torch is slightly different from other Python-packages for which a pip install suffices. Also note that torch is (currently) only supported for python 3.7-3.9, and not for python 2.x (or 3.10); see the official documentation of torch for the latest updates.

Usage

The (basic) usage of the neural network requires importing and initialising the NeuralNetwork in a straightforward manner:

from src.neural_network import NeuralNetwork

nn = NeuralNetwork()

The most basic usage of the neural network encompasses a single prediction, using the single_predict()-method:

from src.neural_network import NeuralNetwork

# initialise neural network
nn = NeuralNetwork()
nn.output = 'L'

# single prediction
prediction = nn.single_predict(
    tidal_range=2.25,
    surge_level=0,
    river_discharge=10000,
    channel_depth=20,
    channel_width=1000,
    channel_friction=.023,
    convergence=1e-4,
    flat_depth_ratio=0,
    flat_width=500,
    flat_friction=.05,
    bottom_curvature=1e-5,
    meander_amplitude=1000,
    meander_length=20000
)

# print prediction
print(prediction)

This will return the salt intrusion length (in metres):

13576.671481132507

In addition to the above basic usage of the neural network, some more elaborate use-cases are supported by the neural network. These are demonstrated in the src-folder.

Structure

The neural network is stored in the src-folder:

+-- src/
|   +-- _data/
|   |   +-- __init__.py
|   |   +-- annesi.gz
|   |   +-- annesi.onnx
|   |   +-- annesi.pkl
|   |   +-- annesi-onnx.txt
|   |   +-- annesi-pkl.txt
|   +-- __init__.py
|   +-- _backend.py
|   +-- neural_network.py
|   +-- README.md
+-- tests/
|   +-- __init__.py
|   +-- test_nn.py
|   +-- test_utils.py
+-- utils/
|   +-- __init__.py
|   +-- check.py
|   +-- data_conv.py
|   +-- files_dirs.py
+-- .gitignore
+-- __init__.py
+-- LICENSE
+-- README.md
+-- requirements.txt
+-- setup.py

Author

Gijs G. Hendrickx 0000-0001-9523-7657 (Delft University of Technology).

Contact: [email protected].

References

When using this repository, please cite accordingly:

Hendrickx, G.G. (2022). ANNESI: An open-source artificial neural network for estuarine salt intrusion. 4TU.ResearchData. Software. doi:10.4121/19307693.

Version-control

The neural network, and so ANNESI-web, are subject to updates. These updates are reflected by different versions of the repository.

Related references

The neural network (and its web-API) has been part of presentations at the following conferences (presenter in bold-face):

• Hendrickx, G.G., Antolínez, J.A.A., Aarninkhof, S.G.J., Huismans, Y., Kranenburg, W.M., and Herman, P.M.J. (March 4, 2022). Combining machine learning and process-based models to enhance the understanding of estuarine salt intrusion and development of estuary-scale nature-based solutions. Ocean Sciences Meeting 2022. Online.

License

This repository is licensed under Apache License 2.0.