# Lisflood OS
This repository hosts source code of LISFLOOD model.
Go to [Lisflood OS page](https://ec-jrc.github.io/lisflood/) for more information.
Other useful resources
| **Project** | **Documentation** | **Source code** |
| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| Lisflood | [Model docs](https://ec-jrc.github.io/lisflood-model/) | https://github.com/ec-jrc/lisflood-code (this repository) |
| | [User guide](https://ec-jrc.github.io/lisflood-code/) | |
| Lisvap | [Docs](https://ec-jrc.github.io/lisflood-lisvap/) | https://github.com/ec-jrc/lisflood-lisvap |
| Calibration tool | [Docs](https://ec-jrc.github.io/lisflood-calibration/) | https://github.com/ec-jrc/lisflood-calibration |
| Lisflood Utilities | | https://github.com/ec-jrc/lisflood-utilities |
| Lisflood Usecases | | https://github.com/ec-jrc/lisflood-usecases |
## Quick start
You can use conda environment to easily install dependencies.
* Install [miniconda](https://docs.conda.io/en/latest/miniconda.html)
* Create a conda env named "lisflood" and install dependencies:
```bash
conda create --name lisflood python=3.7 -c conda-forge
conda activate lisflood
conda install -c conda-forge pcraster gdal
```
* Install lisflood-model pypi package
```bash
pip install lisflood-model
```
Command above will also install the executable `lisflood` in the conda env, so that you can run LISFLOOD with the following:
```bash
lisflood /absolute_path/to/my/local/folder/LF_ETRS89_UseCase/settings/cold.xml
```
You can also clone the repository which contains datasets to test the model.
Follow this instruction for a basic test (included in this repository under [tests/data](https://github.com/ec-jrc/lisflood-code/tree/master/tests/data))
* Clone the master branch of this repository (you need to have git installed on your machine).
```bash
git clone --single-branch --branch master https://github.com/ec-jrc/lisflood-code.git
```
* **Install requirements into a python 3 conda env**
```bash
conda create --name lisflood python=3.7 -c conda-forge
conda activate lisflood
conda install -c conda-forge pcraster gdal
cd lisflood-code
pip install -r requirements.txt
```
If you don't use conda but a plain virtualenv, you need to install PCRaster and GDAL by your own and include its python interface in PYTHONPATH environment variable.
For details, please follow instruction on [official docs](http://pcraster.geo.uu.nl).
3. Run a cold run for the test catchment
Now your environment should be set up to run lisflood. Try with a prepared settings file for one of the two test catchments:
```bash
mkdir tests/data/LF_ETRS89_UseCase/out
python src/lisf1.py tests/data/LF_ETRS89_UseCase/settings/cold.xml
```
If the command above successed without errors, producing dis.nc into tests/data/LF_ETRS89_UseCase/out folder, your lisflood installation was correct.
### Docker image
You can use the updated docker image to run lisflood, so without taking care to install dependencies on your system.
#### Pull image from repository:
```bash
docker pull jrce1/lisflood:latest
```
#### Run test catchments in image:
```bash
docker run -v /absolute_path/to/my/local/folder:/usecases jrce1/lisflood:latest usecases
```
After this command, you can find all files to run tests against catchments under the directory you mapped: `/absolute_path/to/my/local/folder/`
```
/absolute_path/to/my/local/folder/LF_ETRS89_UseCase
/absolute_path/to/my/local/folder/LF_lat_lon_UseCase
```
Now, you can run LISFLOOD as a docker container to test included catchments. Only thing you need to do is to map the test catchment folder to the container folder `input`, by using -v option.
In the XML settings file, all paths are adjusted to be relative to the very same settings file, so you don't need to edit paths, as long as you keep same folders structure.
#### Execute lisflood with a Docker image:
```bash
docker run -v /absolute_path/to/my/local/folder/LF_ETRS89_UseCase:/input jrce1/lisflood /input/settings/cold.xml
```
Once LISFLOOD finished, you find reported maps in `/absolute_path/to/my/local/folder/LF_ETRS89_UseCase/out/` folder.
### Pypi packaged LISFLOOD
LISFLOOD is also distributed as a standard python package. You can install the pip package in your Python 3 virtualenv:
```bash
pip install lisflood-model
```
Command above will also install the executable `lisflood` in the virtualenv, so that you can run LISFLOOD with the following:
```bash
lisflood /absolute_path/to/my/local/folder/LF_ETRS89_UseCase/settings/cold.xml
```
### IMPORTANT NOTE 1
Please note that there are known issues when installing the LISFLOOD code on Windows (source code and pypi package). We cannot provide Windows support and strongly recommend using LINUX to install the LISFLOOD code.
Windows users are recommended to execute LISFLOOD with a Docker image.
### IMPORTANT NOTE 2
The users are recommended to download the [reference settings xml](https://github.com/ec-jrc/lisflood-code/tree/master/src/lisfloodSettings_reference.xml) file and adapt it by inserting their own paths and modelling choices.
## Collaborate
If you find an issue in our code, please follow the [GitHub flow](https://guides.github.com/introduction/flow/) to propose your changes (Fork, commit your changes and ask for a Pull Request).
You are required to run unit tests during your development and before to propose a pull request.
To execute unit tests:
```bash
pytest tests/
```
Furthermore, before to propose a pull request, there are additional tests we ask you to execute:
```bash
pytest tests/ -m "slow"
```
These tests could take 30 minutes or several hours, depending on your machine.
You can find full description and implementation details at [Test documentation](https://ec-jrc.github.io/lisflood-code/4_annex_tests/) page.
**Note**: If yuor pull request is about a new feature you may want to integrate in LISFLOOD,
ensure to include tests with good coverage for it.
For more info about pytest, see [official website](https://docs.pytest.org/en/latest/).
Raw data
{
"_id": null,
"home_page": "https://github.com/ec-jrc/lisflood-code",
"name": "lisflood-model",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "lisflood,lisvap,efas,glofas,copernicus,ecmwf",
"author": "Ad de Roo, Emiliano Gelati, Peter Burek, Johan van der Knijff, Niko Wanders",
"author_email": "carlo.russo@ext.ec.europa.eu",
"download_url": "https://files.pythonhosted.org/packages/20/3c/720a20df8857e88edacc6ca2d463a43e41e447f61a2fa09fcec8d219c5a8/lisflood-model-4.3.1.tar.gz",
"platform": null,
"description": "# Lisflood OS\n\nThis repository hosts source code of LISFLOOD model.\nGo to [Lisflood OS page](https://ec-jrc.github.io/lisflood/) for more information.\n\nOther useful resources\n\n| **Project** | **Documentation** | **Source code** |\n| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |\n| Lisflood | [Model docs](https://ec-jrc.github.io/lisflood-model/) | https://github.com/ec-jrc/lisflood-code (this repository) |\n| | [User guide](https://ec-jrc.github.io/lisflood-code/) | |\n| Lisvap | [Docs](https://ec-jrc.github.io/lisflood-lisvap/) | https://github.com/ec-jrc/lisflood-lisvap |\n| Calibration tool | [Docs](https://ec-jrc.github.io/lisflood-calibration/) | https://github.com/ec-jrc/lisflood-calibration |\n| Lisflood Utilities | | https://github.com/ec-jrc/lisflood-utilities |\n| Lisflood Usecases | | https://github.com/ec-jrc/lisflood-usecases |\n\n\n\n## Quick start\n\nYou can use conda environment to easily install dependencies.\n\n* Install [miniconda](https://docs.conda.io/en/latest/miniconda.html)\n* Create a conda env named \"lisflood\" and install dependencies:\n\n```bash\nconda create --name lisflood python=3.7 -c conda-forge\nconda activate lisflood\nconda install -c conda-forge pcraster gdal\n```\n\n* Install lisflood-model pypi package\n```bash\npip install lisflood-model\n```\n\nCommand above will also install the executable `lisflood` in the conda env, so that you can run LISFLOOD with the following:\n```bash\nlisflood /absolute_path/to/my/local/folder/LF_ETRS89_UseCase/settings/cold.xml\n```\n\nYou can also clone the repository which contains datasets to test the model.\nFollow this instruction for a basic test (included in this repository under [tests/data](https://github.com/ec-jrc/lisflood-code/tree/master/tests/data))\n\n* Clone the master branch of this repository (you need to have git installed on your machine).\n\n```bash\ngit clone --single-branch --branch master https://github.com/ec-jrc/lisflood-code.git\n```\n\n* **Install requirements into a python 3 conda env**\n\n```bash\nconda create --name lisflood python=3.7 -c conda-forge\nconda activate lisflood\nconda install -c conda-forge pcraster gdal\ncd lisflood-code\npip install -r requirements.txt\n```\n\nIf you don't use conda but a plain virtualenv, you need to install PCRaster and GDAL by your own and include its python interface in PYTHONPATH environment variable.\nFor details, please follow instruction on [official docs](http://pcraster.geo.uu.nl).\n\n3. Run a cold run for the test catchment\n\nNow your environment should be set up to run lisflood. Try with a prepared settings file for one of the two test catchments:\n\n```bash\nmkdir tests/data/LF_ETRS89_UseCase/out\npython src/lisf1.py tests/data/LF_ETRS89_UseCase/settings/cold.xml\n```\n\nIf the command above successed without errors, producing dis.nc into tests/data/LF_ETRS89_UseCase/out folder, your lisflood installation was correct.\n\n### Docker image\n\nYou can use the updated docker image to run lisflood, so without taking care to install dependencies on your system.\n\n#### Pull image from repository:\n\n```bash\ndocker pull jrce1/lisflood:latest\n```\n\n#### Run test catchments in image:\n\n```bash\ndocker run -v /absolute_path/to/my/local/folder:/usecases jrce1/lisflood:latest usecases\n```\n\nAfter this command, you can find all files to run tests against catchments under the directory you mapped: `/absolute_path/to/my/local/folder/`\n\n```\n/absolute_path/to/my/local/folder/LF_ETRS89_UseCase\n/absolute_path/to/my/local/folder/LF_lat_lon_UseCase\n```\n\nNow, you can run LISFLOOD as a docker container to test included catchments. Only thing you need to do is to map the test catchment folder to the container folder `input`, by using -v option. \n\nIn the XML settings file, all paths are adjusted to be relative to the very same settings file, so you don't need to edit paths, as long as you keep same folders structure.\n\n\n#### Execute lisflood with a Docker image:\n\n```bash\ndocker run -v /absolute_path/to/my/local/folder/LF_ETRS89_UseCase:/input jrce1/lisflood /input/settings/cold.xml\n```\n\nOnce LISFLOOD finished, you find reported maps in `/absolute_path/to/my/local/folder/LF_ETRS89_UseCase/out/` folder.\n\n### Pypi packaged LISFLOOD\n\nLISFLOOD is also distributed as a standard python package. You can install the pip package in your Python 3 virtualenv:\n\n```bash\npip install lisflood-model\n```\n\nCommand above will also install the executable `lisflood` in the virtualenv, so that you can run LISFLOOD with the following:\n\n```bash\nlisflood /absolute_path/to/my/local/folder/LF_ETRS89_UseCase/settings/cold.xml\n```\n\n### IMPORTANT NOTE 1\n\nPlease note that there are known issues when installing the LISFLOOD code on Windows (source code and pypi package). We cannot provide Windows support and strongly recommend using LINUX to install the LISFLOOD code.\nWindows users are recommended to execute LISFLOOD with a Docker image.\n\n### IMPORTANT NOTE 2\n\nThe users are recommended to download the [reference settings xml](https://github.com/ec-jrc/lisflood-code/tree/master/src/lisfloodSettings_reference.xml) file and adapt it by inserting their own paths and modelling choices.\n\n\n\n## Collaborate\n\nIf you find an issue in our code, please follow the [GitHub flow](https://guides.github.com/introduction/flow/) to propose your changes (Fork, commit your changes and ask for a Pull Request).\nYou are required to run unit tests during your development and before to propose a pull request.\n\nTo execute unit tests:\n\n```bash\npytest tests/\n```\n\nFurthermore, before to propose a pull request, there are additional tests we ask you to execute: \n\n```bash\npytest tests/ -m \"slow\"\n```\n\nThese tests could take 30 minutes or several hours, depending on your machine.\n\nYou can find full description and implementation details at [Test documentation](https://ec-jrc.github.io/lisflood-code/4_annex_tests/) page.\n\n**Note**: If yuor pull request is about a new feature you may want to integrate in LISFLOOD,\nensure to include tests with good coverage for it.\n\nFor more info about pytest, see [official website](https://docs.pytest.org/en/latest/).\n",
"bugtrack_url": null,
"license": "EUPL 1.2",
"summary": "LISFLOOD model python module",
"version": "4.3.1",
"project_urls": {
"Download": "https://github.com/ec-jrc/lisflood-code/archive/4.3.1.tar.gz",
"Homepage": "https://github.com/ec-jrc/lisflood-code"
},
"split_keywords": [
"lisflood",
"lisvap",
"efas",
"glofas",
"copernicus",
"ecmwf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "203c720a20df8857e88edacc6ca2d463a43e41e447f61a2fa09fcec8d219c5a8",
"md5": "78aacdf6f17acde26c72f0eaa2612ef3",
"sha256": "20faeebda7856d5466de0b6edcacac40622daf0ce14d2ab7b12d82753950cec6"
},
"downloads": -1,
"filename": "lisflood-model-4.3.1.tar.gz",
"has_sig": false,
"md5_digest": "78aacdf6f17acde26c72f0eaa2612ef3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 168711,
"upload_time": "2024-01-23T10:34:56",
"upload_time_iso_8601": "2024-01-23T10:34:56.783775Z",
"url": "https://files.pythonhosted.org/packages/20/3c/720a20df8857e88edacc6ca2d463a43e41e447f61a2fa09fcec8d219c5a8/lisflood-model-4.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-23 10:34:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ec-jrc",
"github_project": "lisflood-code",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "lisflood-model"
}
JSON
