Welcome to the Giswater Project - QGIS Plugin

Water management has traditionally been complex and costly, making it difficult to efficiently plan or control water supply networks without further investments. However, with the inception of Giswater in 2014, the first open-source software specifically designed for water supply and water management, this complexity is now manageable.

Giswater integrates various IT solutions and pre-existing databases, enabling high-performance management systems combined with hydraulic software such as EPANET and SWMM.

Giswater is the first open-source tool for integral water cycle management, created for city councils, municipal administrations, water and sewerage service providers, and hydraulic professionals. As a driver, it connects hydraulic analysis tools and spatial databases, allowing user access from any GIS. Compatible with EPANET, EPA SWMM, GIS, WMS, SCADA, and more, Giswater integrates seamlessly into water management entities’ ecosystems, amplifying their operational capabilities.

Additionally, Giswater can be connected with business management tools like ERP, CRM, Business Intelligence software, and corporate mobile devices.

Developed in Python (QGIS plugin) and PL/SQL (PostgreSQL database), the project is organized across three main repositories: QGIS-PLUGIN, DB-MODEL, and DOCS.

Table of Contents

1. Requirements
2. Install
3. Optional: Go2Epa with hydraulic_engine
4. Test
5. Deployment
6. Wiki
7. FAQ
8. Code Repositories
9. Versioning
10. Third-Party Libraries
11. License
12. Acknowledgments

Requirements

To work with Giswater, you will need:

• PostgreSQL: Ensure to select the pgAdmin component (Database Manager) and PostGIS (Spatial Extension) during installation.
• QGIS: Required geoprocessing software.

Install

Since Giswater functions as server-client software, installation is done across two environments.

Backend Environment

Compatible with Windows, Mac, and Linux OS.

• Install PostgreSQL (versions 9.5 to 18).

• Install PostGIS, pgRouting, and other required PostgreSQL extensions (database-level, once per database):

  CREATE EXTENSION IF NOT EXISTS postgis;
  CREATE EXTENSION IF NOT EXISTS pgrouting;
  CREATE EXTENSION IF NOT EXISTS tablefunc;
  CREATE EXTENSION IF NOT EXISTS unaccent;
  CREATE EXTENSION IF NOT EXISTS postgis_raster;
  CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;
  

  postgis, pgrouting, tablefunc, and unaccent are also created automatically when you build a WS/UD schema (dbmodel/schemas/main/common/base/init.sql). Install the packages on the server first; the extension objects must exist at the OS level.

• PostgreSQL roles — Giswater uses a fixed role hierarchy. You do not need to run separate corporate DDL scripts: roles are created idempotently during schema creation and permissions are applied by gw_fct_admin_role_permissions() at the end of lastprocess.

  Role	Purpose	Inherits
  role_basic	Read-only base (SELECT on catalogued tables/views)	—
  role_om	Operations & maintenance	role_basic
  role_edit	Network editing	role_om
  role_epa	EPA / SWMM modelling	role_edit
  role_plan	Planning (psectors, etc.)	role_epa
  role_admin	Schema administration (no superuser)	role_plan
  role_system	Owns schema objects; used for DDL during build	role_admin
  role_crm	CRM integration (standalone, no inheritance chain)	—

  Inheritance chain (each role is granted to the one below; higher roles inherit all lower permissions):

  role_system
    └── role_admin
          └── role_plan
                └── role_epa
                      └── role_edit
                            └── role_om
                                  └── role_basic
  
  role_crm   (standalone)
  

  Installer requirements: gw db init must run as a PostgreSQL superuser (extensions, roles, GRANT CREATE ON DATABASE … TO role_system). After that, schema create/update/drop can run as that superuser or as a login granted role_system. init.sql creates the schema AUTHORIZATION role_system and SET ROLE role_system for base DDL; later phases (updates, sample) run as the installer login. Drop/rename still SET ROLE role_system because the schema is owned by that role. Restrictive object grants are applied by gw_fct_admin_role_permissions.

  Manual bootstrap (only if you must prepare roles before the first schema build, e.g. restricted DBA workflow):

  DO $$
  DECLARE
    v_role_exists boolean;
  BEGIN
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_basic') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_basic NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_om') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_om NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_edit') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_edit NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_epa') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_epa NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_plan') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_plan NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_admin') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_admin NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_system') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_system NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'role_crm') INTO v_role_exists;
    IF NOT v_role_exists THEN
      CREATE ROLE role_crm NOSUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;
    END IF;
  
    GRANT role_basic TO role_om;
    GRANT role_om TO role_edit;
    GRANT role_edit TO role_epa;
    GRANT role_epa TO role_plan;
    GRANT role_plan TO role_admin;
    GRANT role_admin TO role_system;
  
    IF NOT pg_has_role(current_user, 'role_system', 'member')
       AND (SELECT rolsuper FROM pg_roles WHERE rolname = current_user) IS TRUE THEN
      GRANT role_system TO current_user;
    END IF;
  END$$;
  

  Map QGIS/PostgreSQL logins to the appropriate role (e.g. GRANT role_edit TO gis_user). Object-level grants on each project schema are (re)applied by gw_fct_admin_role_permissions() during create and upgrade (lastprocess).

Frontend environment:

Compatible with Windows, Mac, and Linux.

• Install the latest Long-Term Release (LTR) of QGIS (or QGIS 4.x).
• Install the QPIP plugin dependency manager so Giswater can install Python packages from requirements.txt (WNTR, pyswmm, etc.).
• Classic EPA desktop apps (SWMM 5.1 / EPANET 2.2) are mainly relevant on Windows. On macOS/Linux, Go2Epa Execute EPA needs the optional hydraulic_engine package (see below).
• On Linux systems, you may need to install the PostgreSQL Qt driver for database connectivity.
  • On Ubuntu:

  sudo apt install libqt5sql5-psql
  

  • On Fedora:

  sudo dnf install qt5-qtbase-postgresql
  

Optional: Go2Epa with hydraulic_engine

Go2Epa works without hydraulic_engine: on Windows it uses the classic EPA desktop apps. Install the package only if you want the enhanced path (clearer run/import errors; Execute EPA on Linux/macOS for WS and UD). When the package is missing, Giswater keeps the classic EPA path automatically.

Why it is not in requirements.txt / QPIP

QPIP installs into the profile python/dependencies tree with an isolated prefix that does not see QGIS’s bundled site-packages. Pip then tends to pull its own latest stack (including SciPy). At runtime QGIS often still loads NumPy from its own Python, which can be incompatible with the SciPy sitting under dependencies. We hit that mismatch with hydraulic_engine, so the package stays optional and manual — users who want it install a pinned version themselves.

Tested pin with Giswater 4.x: hydraulic_engine==0.9.0.

Manual install

Use QGIS’s Python (not system Python) and install into the same dependencies prefix QPIP uses for your profile. Adjust the QGIS path, profile name, and Python minor version (3.9, 3.12, …) to match your install.

Windows (PowerShell example; point python-qgis.bat at your QGIS install):

$py = "C:\Program Files\QGIS 3.40.0\bin\python-qgis.bat"
$prefix = "$env:APPDATA\QGIS\QGIS3\profiles\default\python\dependencies"
& $py -m pip install "hydraulic_engine==0.9.0" --prefix $prefix

macOS / Linux (example; use the Python that ships with QGIS):

# Set QGIS_PYTHON to your QGIS python binary, then:
PREFIX="$HOME/Library/Application Support/QGIS/QGIS3/profiles/default/python/dependencies"  # macOS QGIS 3
# Linux often: "$HOME/.local/share/QGIS/QGIS3/profiles/default/python/dependencies"
"$QGIS_PYTHON" -m pip install "hydraulic_engine==0.9.0" --prefix "$PREFIX"

Fully quit and reopen QGIS afterwards. In the log you should see that hydraulic engine was imported; otherwise Go2Epa falls back to classic EPA.

Align SciPy with QGIS (recommended after install)

hydraulic_engine (and its deps) often pull a newer SciPy than QGIS’s bundled NumPy can load. After installing hydraulic_engine, reinstall the same SciPy version QGIS already has into the dependencies prefix:

1. In the QGIS Python console:

   import scipy
   print(scipy.__version__)
   

2. Reinstall that version with the same QGIS Python and --prefix as above, e.g.:

   "$QGIS_PYTHON" -m pip install "scipy==<version-from-step-1>" --prefix "$PREFIX"
   

Example that fixed the NumPy/SciPy mismatch after hydraulic_engine==0.9.0 on QGIS 3.40.12 / Python 3.12.11 / Windows 11 / NumPy 1.26.4: install scipy==1.17.1. Do not copy that SciPy pin blindly — use the version printed in step 1 for your QGIS.

If imports still fail, check that QGIS NumPy is the one being used (import numpy; print(numpy.__version__, numpy.__file__)) and avoid leaving a different numpy under python/dependencies.

macOS: re-sign native libraries

On macOS, QGIS runs with Hardened Runtime. Native libraries from QPIP/pip wheels (wntr / EPANET, pyswmm / SWMM, hydraulic_engine, etc.) often ship ad-hoc or unsigned. Loading them into QGIS can kill the app with:

EXC_BAD_ACCESS (SIGKILL) — CODESIGNING / Invalid Page

This is a packaging limitation of those PyPI wheels, not a Giswater bug. After installing or updating dependencies, re-sign them locally:

# QGIS 4 + Python 3.12 (default profile).
# QGIS 3: replace QGIS4 with QGIS3. Adjust 3.12 if your QGIS Python minor differs.
DEP="$HOME/Library/Application Support/QGIS/QGIS4/profiles/default/python/dependencies/3.12"

xattr -dr com.apple.quarantine "$DEP" 2>/dev/null
find "$DEP" \( -name "*.so" -o -name "*.dylib" \) \
  -exec codesign --force --sign - {} \;

Fully quit and reopen QGIS afterwards. Re-run this command after any QPIP / pip update that refreshes native wheels.

Test

Database model (pgTAP, Docker): dbmodel/README.md — Testing — ./dbmodel/test/run_tests.sh ws (PostgreSQL 16–18 via PG_MAJOR).

Schema CLI (no QGIS): giswater_admin/README.md — pipx install giswater-cli then gw create --kind ws …

Python unit tests: python3 -m pytest test/engine -v (from plugin repo root).

Use the provided example projects, pre-loaded with datasets for testing. Find setup videos below:

• Install the plugin
• Setup connection
• Create DB schema example
• Create QGIS project

Deployment

Requirements

Ensure you have the permissions to connect to PostgreSQL. Database bootstrap (gw db init, extensions, roles) needs superuser rights. After that, schema administration can be done by a login that is a member of role_system.

Project Setup

• Define catalogs with at least the mandatory categories ([materials, node, arc]) and create map zones ([macroexploitation, exploitation, municipality, sector, dma]).
• To get started, refer to Start from Scratch for guidance.
• Tip: Once map zones and catalogs are defined, you can begin adding network nodes and arcs.

For more configuration options, see the Giswater configuration guide.

Wiki

Explore additional documentation on the Giswater Wiki.

FAQs

Find answers to common questions in the Giswater FAQs.

QGIS on macOS crashes when running Go2Epa / EPANET? See macOS: re-sign native libraries.

Want Go2Epa with hydraulic_engine / Execute EPA on Linux or macOS? See Optional: Go2Epa with hydraulic_engine (manual install; not via QPIP).

Code Repositories

• Docs: Documentation repository
• QGIS Plugin: QGIS Plugin repository
• Database Model: Database Model repository — in this repo: dbmodel/ (schema layout, local tests)
• Headless schema CLI: giswater_admin/ (full reference)
• Translations: Language packs and coverage

Other repositories may exist but are either deprecated or inactive.

Versioning

Giswater follows a three-level release system:

• Major: New architecture with significant updates (no forward compatibility).
• Minor: Bug fixes and new features (forward compatible).
• Build: Minor fixes and updates (forward compatible).

Release frequency:

• Build: Monthly (12 builds/year)
• Minor: Annually
• Major: No fixed schedule

Third-Party Libraries

Giswater uses the following third-party libraries:

• WNTR: WNTR GitHub
  WNTR is an open-source Python package for analyzing water distribution systems using hydraulic and water quality models.
  The WNTR license can be found in the LICENSE file or in their repository.

• swmm-api: swmm-api GitLab
  swmm-api provides a Pythonic interface to the EPA SWMM5 software, enabling advanced scripting, simulation control, and access to simulation results.
  The license and further details can be found in the LICENSE or in their repository.

• tqdm: tqdm GitHub
  tqdm is a fast, extensible progress bar library for Python, supporting console, GUI, and notebook environments.
  The tqdm license can be viewed in the LICENSE or in their repository.

• PyPDF2: PyPDF2 GitHub
  PyPDF2 is a Python library for working with PDF files, offering functionalities such as splitting, merging, and text extraction.
  The PyPDF2 license is available in the LICENSE or in their repository.

• osmnx: OSMnx GitHub
  OSMnx is a Python package to easily download, model, analyze, and visualize street networks and other geospatial features from OpenStreetMap. You can download and model walking, driving, or biking networks with a single line of code then analyze and visualize them. You can just as easily work with urban amenities/points of interest, building footprints, transit stops, elevation data, street orientations, speed/travel time, and routing.
  The OSMnx license can be viewed in the LICENSE or in their repository

License

This program is free software, licensed under the GNU General Public License (GPL) version 3 or later. Refer to the LICENSE file for details.

Acknowledgments

Special thanks to our founding contributors:

• GITS-BarcelonaTech University
• Aigües de Mataró
• Cicle de l'Aigua del Ter S.A
• Aigües de Blanes
• Aigües del Prat
• Aigües de Vic
• Aigües de Castellbisbal
• Aigües de Banyoles
• Figueres de Serveis, S.A
• Prodaisa
• Sabemsa
• Consorci Aigües de Tarragona
• BGEO OPEN GIS S.L.