Setting up models ===== Introduction ----- SFINCS models can be set up using simple ascii text and/or binary input files, which can be generated on whatever platform suiting you as a user best. While SFINCS itself is coded in Fortran, it does not matter whether you create the input using a text editor, Matlab or Python. To make the setting up of basic models easier, making a SFINCS model is supported by different open source available options: * Python script framework called **'HydroMT'**, with its dedicated plugin **'hydromt_sfincs'** --> highly recommended to use since 2023 * Graphical User Interface (GUI) to make SFINCS models interactively: **'Delft Dashboard'** --> the Matlab DDB GUI is currently depricated * Graphical User Interface (GUI) to make SFINCS models interactively: **'Delft Dashboard Python'** --> the Python DDB GUI is currently being developed * Matlab scripts toolbox in the **'Open Earth Toolbox'** --> the Matlab OET scripts are currently depricated If you need a more tailor-made solution for setting up your SFINCS models get in touch with us! HydroMT-SFINCS ----- HydroMT (Eilander et al. 2022 https://doi.org/10.5194/egusphere-2022-149) is a more recent addition to the tools available for setting up SFINCS models, and is a Python based command-line alternative. Besides globally available DEMs it can also retrieve spatially varying infiltration and manning roughness data based on landuse maps. Also, it is possible to burn in rivers or setup a offline coupled model together with the hydrological Wflow model that will provide boundary conditions as river discharge. **NOTE - As of HydroMT-SFINCS v2.0.0, the API uses a component-based architecture. The old ``setup_*`` methods (e.g. ``setup_grid``, ``setup_dep``) have been replaced by component methods (e.g. ``sf.grid.create()``, ``sf.elevation.create()``). See the migration guide for details.** * For more information regarding the SFINCS plugin of HydroMT see: https://deltares.github.io/hydromt_sfincs/ * For more information regarding HydroMT in general see: https://deltares.github.io/hydromt/ * For the HydroMT-SFINCS v2 migration guide see: https://deltares.github.io/hydromt_sfincs/ * For an example of building a model from scratch in Python see: https://deltares.github.io/hydromt_sfincs/ Delft Dashboard ----- Delft Dashboard (Van Ormondt et al. 2020 https://doi.org/10.2166/hydro.2020.092) is a quick set-up tool GUI for hydrodynamic models that includes setting up SFINCS models. The tool can be run on Matlab or as standalone executable and has all the basic functionality to setup your basic model using globally available DEMs in an interactive way. In ongoing work, DDB is converted into a Python based GUI! Executable ===== We provide pre-compiled versions of SFINCS for you to use directly: * Windows: https://download.deltares.nl/en/sfincs * Platform independent through Docker (Windows/linux/singularity/HPC): https://hub.docker.com/r/deltares/sfincs-cpu Compiling yourself ===== If you want to compile SFINCS yourself for windows to test certain improvements, you need Visual Studio and an Intel Fortran compiler. Find here at tested and free available combination: * Visual Studio Community 2022 - freely available from: https://visualstudio.microsoft.com/vs/community/ * Intel Fortran Compiler Classic and Intel Fortran Compiler for Windows* 2022.1.0 - freely available from: https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html After installation and configuring (see respective websites for help), you can compile your own SFINCS model locally and add features. Make a checkout of the SFINCS github page, and open the VS solution file to do this: https://github.com/Deltares/SFINCS/blob/main/source/sfincs.sln To collaborate together and under the GNU GPL-v3.0 license SFINCS comes with, share any improvements with us as pull request on Github: https://github.com/Deltares/SFINCS/pulls Running SFINCS ===== SFINCS can be run on multiple different platforms, both local, HPC and cloud based. The simplest way is to run SFINCS on Windows using a batch-file. On windows (standard) ----- The standard method to run SFINCS locally is on a windows machine using a batch-file. This batch file you copy to the folder where your input files to be used by SFINCS are located. The batch file simply calls the executable (add the right path to the folder where sfincs.exe is located) and the general output text file is written to a new text file called 'sfincs_log.txt', see below for an example. Using batch-file ^^^^^ **run.bat** .. code-block:: text make a text file called 'run.bat' and add here: call "c:\..\folder_where_exe_is_located\sfincs.exe">sfincs_log.txt On linux ----- Dedicated linux compiled version ^^^^^ Generally for Linux (HPC) systems, running using Docker or Singularity is the most generic and succesfull way. In case you need a dedicated Linux build, get in touch and we can create a version specifically for you. We have experience doing this for our own Deltares cluster. Using Docker ----- For always using the last build version of SFINCS on Windows, Mac, Linux or a cloud based cluster a convenient solution is running a Docker container version of SFINCS. This can be done on a local desktop or in a cloud based cluster supporting docker (or using singularity, see below). **Note that this Docker version of SFINCS is available under the same GNU GPL-v3 License as the windows executable.** Local desktop version ^^^^^ After downloading Docker desktop for your operating system (https://www.docker.com/products/docker-desktop), you can run a model using: **Example** .. code-block:: text docker pull deltares/sfincs-cpu docker run -vC:/Users/../SFINCS:/data deltares/sfincs-cpu (here 'C:/Users/../SFINCS' is the folder where the SFINCS input files to be used are located) NOTE - you have to supply the full path, not a relative path! NOTE - For Linux/Mac you do the same, but write the path as /Users/../SFINCS/ Instead of using the latest automatically cmpiled version, you can also pull a verified tagged release from: https://hub.docker.com/r/deltares/sfincs-cpu/tags This can be for instance the open source release version 'docker pull deltares/sfincs-cpu:sfincs-v2.0.3-Cauberg'. Cloud based cluster ^^^^^ The same principle is also possible on a cloud based cluster that supports running docker containers Using Singularity ----- On cloud based clusters like Surfsara/Azure/Amazon that **supports singularity**, it is possible to run the Docker container version of SFINCS directly. Depending on the application it could be wise to pull the docker container once and save as new image, after which this image can be run multiple times. This prevents unnesissarily loading the Docker container every time a simulation is performed. **Note that this Docker version of SFINCS is available under the same GNU GPL-v3 License as the windows executable.** **Example** .. code-block:: text Pulling and running the docker container immediately: singularity run -B$(pwd):/data --nv docker://deltares/sfincs-cpu First pulling the docker container and creating a singularity image, then running this image: singularity pull docker://deltares/sfincs-cpu sfincs-cpu.img singularity run -B$(pwd):/data sfincs-cpu.img Also here, instead of using the latest automatically cmpiled version, you can also pull a verified tagged release from: https://hub.docker.com/r/deltares/sfincs-cpu/tags This can be for instance the open source release version 'sfincs-v2.0.3-Cauberg'. Courses learning SFINCS ===== Besides the elaborate information available in this manual, we do offer courses to learn from the experts how to set up a SFINCS model, and the theory and philosophy behind the model: * SFINCS trainings during the DSD are planned to be yearly, for an up to date agenda see: https://softwaredays.deltares.nl/welcome * For US/Canada users, online SFINCS training through Deltares USA, see: https://www.deltares-usa.us/book-online If these dates don't suit you or your organisation, or you want a more advanced training; get in touch and we can set up a tailor-made course for you. Questions and support ===== As Deltares is a NGO project-based organisation, and while we do try to answer all your questions, we simply cannot do this to the ultimate end-degree-level as the model is provided to you free of charge. If you do have more structurally returning questions about how to set up SFINCS models for your application, considering getting a Software Service Package. For more information, send an email to: software@deltares.nl Additionally, if you want the experts to set up a first working framework of SFINCS models for you, get in touch at sfincs@deltares.nl to discuss options for collaborations to set this up. Contributing ===== Documentation ----- The code of this documentation is available from https://github.com/Deltares/SFINCS/docs. Get in touch if you have suggestions how to improve this manual, or put in a pull request with improvements yourself: https://github.com/Deltares/SFINCS/pulls Code ----- The SFINCS code is open source as of 16-11-2022, see: https://github.com/Deltares/SFINCS/source Get in touch if you would like to join us in developing the SFINCS code, or put in a pull request on Github with improvements yourself: https://github.com/Deltares/SFINCS/pulls