symfluence 0.9.0

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

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 semidistributed

# 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
│   ├── project/              # Project and workflow management
│   ├── data/                 # Data acquisition and preprocessing
│   ├── geospatial/           # Domain discretization and geofabric
│   ├── models/               # Model integrations (SUMMA, FUSE, GR4J, etc.)
│   ├── optimization/         # Calibration algorithms (DDS, DE, PSO, NSGA-II)
│   ├── evaluation/           # Performance metrics and evaluation
│   ├── 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: feature/<description>, PR to develop.

---

Contributing

See CONTRIBUTING.md for:

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

---

License

Licensed under the GPL-3.0 License. See LICENSE for details.

Commercial Licensing

SYMFLUENCE is free and open-source software under GPL-3.0-or-later. For organizations that require alternative licensing terms — including proprietary integration, redistribution without copyleft obligations, or operational deployment support — commercial licenses are available.

For commercial licensing, derivative-platform inquiries, and the Foundation's dual-licensing policy, see LICENSING.md.

Contact: [e-mail] (licensing) · [e-mail] (general)

---

Happy modelling! The SYMFLUENCE Team