SYMFLUENCE

SYnergistic Modelling Framework for Linking and Unifying Earth-system Nexii for Computational Exploration

Overview

SYMFLUENCE is a computational environmental modeling platform that streamlines the hydrological modeling workflow—from domain setup to evaluation. It provides an integrated framework for multi-model comparison, parameter optimization, and automated workflow management across spatial scales.

Quick Links

• Install: pip install symfluence
• Documentation: symfluence.readthedocs.io
• Website: symfluence.org
• Discussions: GitHub Discussions
• Issues: GitHub Issues

Installation

pip install symfluence

After installation, install external model binaries:

symfluence binary install

For development setup (editable install / bootstrap) and all other install methods — Docker, conda, npm, uv, HPC modules — see the installation guide.

Quick Start

Basic CLI Usage

# Show options
symfluence --help

# Run full workflow
symfluence workflow run --config my_config.yaml

# Run specific steps
symfluence workflow steps setup_project calibrate_model

# Define domain from pour point
symfluence project pour-point 51.1722/-115.5717 --domain-name MyDomain --definition delineate

# Check workflow status
symfluence workflow status

# Validate configuration
symfluence config validate --config my_config.yaml

First Project

# Initialize project from template
symfluence project init

# Or copy template manually
cp src/symfluence/resources/config_templates/config_template.yaml my_project.yaml

# Run setup
symfluence workflow step setup_project --config my_project.yaml

# Run full workflow
symfluence workflow run --config my_project.yaml

Python API

For programmatic control or integration:

from pathlib import Path
from symfluence import SYMFLUENCE

cfg = Path('my_config.yaml')
symfluence = SYMFLUENCE(cfg)
symfluence.run_individual_steps(['setup_project', 'calibrate_model'])

Configuration

YAML configuration files define:

• Domain boundaries and discretization
• Model selection and parameters
• Optimization targets
• Output and visualization options

See src/symfluence/resources/config_templates/config_template.yaml for a full example.

Project Structure

SYMFLUENCE/
├── src/symfluence/           # Main Python package
│   ├── core/                 # Core system, configuration, mixins
│   ├── cli/                  # Command-line interface
│   ├── tui/                  # Terminal user interface
│   ├── gui/                  # Graphical user interface
│   ├── agent/                # Agentic / assistant integration
│   ├── project/              # Project and workflow management
│   ├── data/                 # Data acquisition and preprocessing
│   ├── geospatial/           # Domain discretization and geofabric
│   ├── models/               # Model integrations (SUMMA, FUSE, GR, etc.)
│   ├── coupling/             # Model coupling
│   ├── optimization/         # Calibration algorithms (DDS, DE, PSO, NSGA-II)
│   ├── evaluation/           # Performance metrics and evaluation
│   ├── fews/                 # Delft-FEWS integration
│   ├── reporting/            # Visualization and plotting
│   └── resources/            # Configuration templates and base settings
├── examples/                 # Progressive tutorial examples
├── docs/                     # Sphinx documentation source
├── scripts/                  # Build and release scripts
├── tools/                    # NPM packaging and utilities
└── tests/                    # Unit, integration, and E2E tests

Branching Strategy

• main: Stable releases only — every commit is a published version.
• develop: Ongoing integration — merges from feature branches and then tested before release.
• Feature branches: feat/<description>, PR to develop.

Contributing

See CONTRIBUTING.md for:

• Code standards and testing
• Branching and pull request process
• Issue reporting

License

SYMFLUENCE is free and open-source software under GPL-3.0-or-later. See LICENSE for the full text.

Commercial and dual-licensing options are available for organizations that need alternative terms (proprietary integration, redistribution without copyleft obligations, or operational deployment support). See the licensing guide for details, or the full Licensing Policy. Inquiries: licensing@symfluence.org.

Happy modelling! The SYMFLUENCE Team