AFAR-WQS: A Quick and Simple Toolbox for Water Quality Simulation

Abstract

Water quality management in large basins demands tools that balance scientific rigor with computational efficiency to avoid paralysis by analysis. While traditional models offer detailed insights, their complexity and resource intensity hinder timely decision-making. To address this gap, we present AFAR-WQS, an open-source MATLAB™ toolbox that introduces a novel integration of assimilation factors with graph theory and a Depth-First Search (DFS) algorithm to rapidly simulate 13 water quality determinants across complex topological networks. AFAR-WQS resolves cumulative processes in networks of up to 30,000 segments in just 163 s on standard hardware, enabling real-time scenario evaluations. Its object-oriented architecture ensures scalability, allowing customization for urban drainage systems or macro-basin studies while maintaining computational efficiency. Case studies demonstrate its utility in prioritizing sanitation investments, assessing water quality at the national scale and fostering stakeholder collaboration through participatory workshops. By bridging the gap between simplified and complex models, AFAR-WQS supports adaptive management in contexts of hydrological uncertainty, regulatory compliance, and climate change. The toolbox is freely available at GitHub, offering a transformative approach for integrated water resource management.

1. Introduction

The analysis and understanding of water systems in large basins present significant challenges in the development of tools that enable a multidimensional understanding of the current state of natural resources and the impacts that may arise from specific actions within a basin. A comprehensive view of water systems requires not only an understanding of water quantity but also water quality [1,2,3,4], which is a crucial parameter for assessing the health of freshwater ecosystems and their potential for sustainable use [5].

According to [6], approximately 80% of global industrial and municipal wastewater is discharged into the environment without prior treatment. This percentage is even higher in less developed countries, where the lack of infrastructure for sanitation and wastewater treatment is more severe. This situation has significant negative repercussions, not only for human health but also for the functioning of aquatic ecosystems and socio-economic development [6,7]. Moreover, the continuous growth of the global population, along with increased freshwater consumption for human use, agriculture, and industry, amplifies these challenges [8].

One of the most useful tools for understanding water quality is mathematical modeling [9]. Currently, the range of available models that allow us to understand water quality dynamics in watersheds is quite diverse. Some of the models cited in the literature include Agricultural Non-Point Source, AGWA, ANSWERS-2000, APEX, AQUATOX, BASINS, EFDC, EPD-RIV1, GLEAMS/CREAMS, HSPF, InVEST, KINEROS2, LSPC, MIKE SHE, NLEAP, PRMS, QUAL2E, QUAL2K, SIGA-CAL, SWAT, SWMM, WAM, WARMF, WASP7, WCS, AquaChem, TOMCAT, SisBaHIA, SIMCAT, QUAL2KW, MOHID, MIKE HYDRO, ECETOC, and CE-QUAL-W2 [4,10,11]. Some of these models rely on physical equations to provide a detailed description of water quality determinant fate and transport processes, whereas others employ simpler conceptual approaches. Although each approach has its advantages and limitations, numerous studies have focused on comparing these models to guide selection according to specific objectives [5,12].

However, many of the aforementioned models exhibit significant computational complexity and extensive data requirements, which pose challenges for their implementation and calibration in large basins [13]. In most cases, prolonged execution times represent a major constraint, particularly in contexts requiring rapid decision-making and exploration of multiple scenarios [14,15]. For instance, [14] reported that simulating a single hydrological year at an hourly time step for a 139 km river with cross sections spaced every 50 m required approximately four days of computation. This computational burden complicates the execution of uncertainty and risk analyses, as well as the evaluation of multiple scenarios within limited timeframes—both of which are fundamental for water resources planning [15]. Consequently, simplified modeling approaches have gained traction as viable alternatives for integrated water quality assessments in large basins as they facilitate large-scale modeling with lower computational and data demands. Furthermore, these models can be incorporated into decision-support systems that integrate optimization techniques and risk-and-uncertainty analyses [14]. In such contexts, methodologies capable of producing preliminary results with reduced computational effort are critical for informing resource allocation strategies and assessing the feasibility of management interventions [16].

In this context, simplified models offer a compelling alternative, enabling water quality simulations with lower computational demand and more accessible input data. Their efficiency makes them particularly valuable for preliminary assessments and large-scale applications. Due to their speed and reduced calibration complexity, these models can be seamlessly integrated into decision-support platforms. One example of such tools is the InVEST models [17], which are designed to support natural resource management, particularly in implementing nature-based solutions. There are cases, such as SWAT, which have been integrated into the Hydrologic and Water Quality System (HAWQS), a national-scale decision support system (DSS) that allows for the simple and intuitive modeling of large watersheds [18]. Similarly, InVEST has been incorporated into WaterProof, a web-based decision support tool that provides quick calculations of return on investment (ROI) and early indications of an optimal portfolio of nature-based solutions (NBS) for any watershed globally [19]. However, while the use of such platforms should be encouraged, they still present limitations for global-scale basin analysis. These limitations include longer calculation times, complex preliminary configurations before the model becomes operational on the platform, and default configurations based on global databases that do not adequately capture the local characteristics of the territory.

Given this situation, there is a significant gap in water quality modeling innovation, particularly in designing efficient algorithms and computational procedures that enhance efficiency while preserving scientific rigor. One of the key challenges in chemical risk assessments in the 21st century, as identified by [20], is the need to develop parsimonious tools that are both scientifically rigorous and practical for regulatory applications. These tools must strike a balance between capturing the complexity of environmental processes and providing rapid, actionable insights for decision-makers. This balance is crucial to avoid paralysis by analysis, where overly complex models hinder timely decision-making. AFAR-WQS directly addresses this challenge by offering a simplified yet robust modeling approach that enables efficient simulations of water quality determinants, making it a valuable tool for regulatory risk assessment and integrated water resources management.

Recently, ref. [21] presented a simplified water quality model based on the concept of assimilation factors [22,23] for 13 water quality determinants: temperature (T), organic nitrogen (NO), ammoniacal nitrogen (NH₄), nitrates (NO₃), organic phosphorus (Po), inorganic phosphorus (Pi), organic matter (OM), dissolved oxygen (DO), suspended solids (SS), pathogenic organisms (X), elemental mercury (Hg0), divalent mercury (Hg2), and methylmercury (MeHg). This parsimonious approach builds on the foundations of conceptual models such as ADZ-QUASAR [24], which focus on the transport and fate of water quality determinants in water bodies. However, unlike these models, which are primarily designed to assess the behavior of specific substances, AFAR-WQS is tailored for the integrated water quality management at the basin scale, enabling rapid simulations of multiple determinants and facilitating decision-making processes.

This approach has been successfully applied in various contexts to identify priorities in sanitation [25,26,27,28], support national-scale water resource management [27], and approximate the health and integrity of freshwater ecosystems [21,29]. For instance, it has been used to prioritize investments in sanitation infrastructure, evaluate the impacts of point and non-point source pollution, and assess the effectiveness of nature-based solutions in improving water quality. These applications demonstrate the versatility and practical relevance of the assimilation factor concept, which now serves as the foundation for AFAR-WQS.

In this research, we present a computational implementation of the model proposed by [21] incorporating a novel approach in the calculation scheme for the rapid simulation of water quality determinants. The implementation is carried out as an open-source MATLAB™ toolbox (1.0 tested on Matlab R2023b, https://github.com/N4W-Facility/AFAR-WQS_Toolbox) (accessed on 25 February 2025) called AFAR-WQS (Assimilation Factor Analysis of Rivers for Water Quality Simulation). This toolbox employs a Depth-First Search (DFS) algorithm to efficiently resolve cumulative processes in complex topological networks, maximizing computational performance. AFAR-WQS simulates the concentration, loads, and assimilation factors of 13 water quality determinants. Additionally, it allows for the integration of diffuse sources of pollution by basin, point discharges, and boundary conditions. The toolbox was developed using an object-oriented programming approach, which facilitates scalability and maintenance. Furthermore, it incorporates an interactive user interface that enables visual analysis of the model results, allowing users to explore variations in water quality conditions from the reach to the network scale, thus facilitating interpretation and decision-making in water resource management.

2. Materials and Methods

AFAR-WQS was developed using the concept of assimilation factors to model the 13 water quality parameters it evaluates. Conceptually, this factor is defined as the stream’s capacity to absorb and mitigate the impact of a contamination event [22,23]. According to [22,23], this concept is intrinsically linked to the physical, chemical, and biological processes that influence the contaminant within the receiving water body. Mathematically, the assimilation factor is expressed as follows:

$$a={\displaystyle \frac{W_u}{C}}$$

where $a$ represents the assimilation factor, which depends on the characteristics of the receiving water body and the nature of the contaminant; $W_u$ corresponds to the water quality determinant load originating from upstream segments (with the subscript $u$ indicating the concentration of the parameter at that point); and $C$ denotes the downstream concentration in the segment.

Operationally, AFAR-WQS represents the drainage network of a watershed as a directed graph, allowing each river segment to be modeled as a connection between two nodes, as illustrated in Figure 1a. Using this framework, AFAR-WQS resolves the topological connectivity of the network through a Depth-First Search (DFS) algorithm [30], which begins at the segment corresponding to the watershed outlet. From this point, the algorithm progresses upstream through the drainage network until it identifies a headwater segment, defined as one with no incoming connections. (Figure 1b). Upon identifying a headwater segment, the model begins aggregating loads for various water quality determinants, estimating both assimilation factors and concentrations for that specific reach (Figure 1c). The algorithm then proceeds downstream to the immediately adjacent reach. If this downstream reach has incoming connections, the model recursively moves upstream, repeating the process described until it returns to the original confluence point. Figure 1c illustrates the manner in which concentrations are estimated for intermediate and headwater reaches.

This modeling scheme assumes that the physicochemical conditions are uniform throughout the entire reach, as it represents the smallest modeling unit in AFAR-WQS. Therefore, the assimilation factors are calculated based on the average values of the physicochemical characteristics of the reach. Moreover, the recursive approach used by the tool to solve the topological network allows for the analysis of networks with a large number of nodes while using minimal storage resources, a capability that would not be possible with adjacency matrix-based schemes, which require significantly higher computational resources [31].

Reach segmentation can be performed automatically, either based on an area accumulation threshold or a maximum length defined by the user, employing tools such as Topotoolbox [32], ArcHydro [33], and ArcSWAT [34], which facilitate the generation of river networks from a digital elevation model (DEM). AFAR-WQS offers the advantage of resolving connections involving more than two reaches connected to a node, as well as one-to-one reach connections. However, it is important to note that the tool cannot represent cyclic connections or bifurcations within the network. Additionally, it assumes that the graph is unidirectional, with connections directed toward the reach representing the basin’s outlet. This flexibility allows the topological network to be segmented at points of interest defined by the user. AFAR-WQS also supports the representation of topological networks with multiple outlets, which is particularly relevant in decision-making processes where boundaries are guided not strictly by watershed divides but by political or administrative limits.

Toolbox Configuration

The configuration of AFAR-WQS requires assigning each reach in the network a set of physical attributes related to the geomorphological characteristics of the river reaches to be modeled, which govern the transport conditions of the water quality determinants (see

Table 1. Attributes that are assigned to each topological network reach.

Attributes	Unit	Description
ReachID	-	Unique positive integer numeric identifier of each reach in the topological network.
FromNode	-	Positive integer numeric identifier of the initial node of a reach of the topological network.
ToNode	-	Positive integer numerical identifier of the end node of a reach of the topological network.
ReachType	-	Identifies whether the reach represents a plain or mountain river. If false is specified, the tool will assume that the reach represents a plain river. To define whether a river is a plain or a mountain river, the first criterion may be to assume that the former is limited by capacity (slope ≤ 0.025 m/m) and the latter by supply (slope > 0.025 m/m), following the slope thresholds defined by [35]. A second criterion may be to use the slope threshold defined by [36] to define whether a river is mountain (slope > 0.002 m/m) or plain (slope < 0.002 m/m).
RiverMouth	-	Identifies the river reach that corresponds to the basin closure point. If the value is false, it is considered not to be a closure point reach.
$DF$**	dimensionless	The tool estimates the dispersive fraction following the criteria of [37]. For the sections of the topological network representing mountain rivers, an overall value of 0.27 is considered, while for plain rivers it is 0.40.
$\overline{t}$	day	The tool estimates the average travel time as follows: $\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}{U}_s={\displaystyle \frac{U}{1+\beta }}$ $\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\overline{t}=\left({\displaystyle \frac{L}{U_s}}\right)$ × $\left({\displaystyle \frac{1}{3600 \ast 24}}\right)$ where $U_s$ is solute velocity (m/s), and β is the effective delay coefficient. According to [37], the effective delay coefficient for mountain rivers has an overall magnitude of 1.10, while for plain rivers it is 2.0.
$\tau$**	day	The tool estimates the advection time as follows: $\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\tau =\overline{t}\times \left(1-DF\right)$
$TR$**	day	The tool estimates the residence time as follows: $\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}\hspace{1em}TR=\overline{t}\times DF$
L	m	River length representing the reach in the topological network.
Z	m.a.s.l	Average elevation of the river representing the reach in the topological network.
A	m2	Drainage area of the river representing the reach in the topological network, accumulated up to the ToNode of the reach.
Q	m3/s	Average discharge of the river representing the reach in the topological network, for a selected discharge scenario.
W	m	Average width of the river’s cross section representing the reach in the topological network, for the selected discharge scenario. The width can be estimated from the DEM, satellite imagery [31,38], physically based relationships [39,40], field studies, or global datasets.
H	m	Average depth of the water column in the river representing the reach in the topological network, for the selected discharge scenario. The depth can be estimated from physically based relationships [39,40], field studies, or global datasets.
U	m/s	Average velocity of the water column in the river representing the reach in the topological network, for the selected discharge scenario. The velocity can be derived by continuity or through physically based relationships [39,40] as well as from field studies or global datasets.
S	m/m	Slope of the river representing the reach in the topological network. The slope can be estimated from the DEM, field studies, or global datasets.
T	°C	Average river water temperature representing the reach of the topological network.
Load_T	°C	Average temperature of the wastewater discharges entering the river representing the reach of the topological network.
Load_SS *	mg/d	The load of solids entering the river reach.
Load_X *	MPN/day	Total coliform load entering the river reach.
Load_NO *	mg/day	Organic nitrogen load entering the river reach.
Load_NH4 *	mg/day	Ammonia nitrogen load entering the river reach.
Load_NO3 *	mg/day	Nitrates load entering the river reach.
Load_PO *	mg/day	Organic phosphorus load entering the river reach.
Load_PI *	mg/day	Inorganic phosphorus load entering the river reach.
Load_OM *	mg/day	Organic matter load entering the river reach.
Load_DO *	mg/day	The load of dissolved oxygen entering the river reach.
Load_Hg0 *	mg/day	Elemental mercury load entering the river reach.
Load_Hg2 *	mg/day	Divalent mercury load entering the river reach.
	mg/day	Methylmercury load entering the river reach.

Notes: * The loads of various water quality determinants entering the river, represented by a reach in the topological network, are estimated as the sum of diffuse loads (contributions from land covers, livestock, fertilization, etc.) within the sub-basin draining into the river reach, along with the loads contributed by point-source wastewater discharges within the same reach. ** The user can assign a unique value for reach section of the topological network.

). All the necessary attributes for the tool can be derived from mathematical models (e.g., hydrological, hydrodynamic, etc.), prior studies, field data, or a combination of these sources. However, AFAR-WQS estimates certain key parameters by default, such as average travel time, dispersive fraction, advection time, and residence time. Given that the tool is developed using an object-oriented programming approach, users can customize it by incorporating additional methods tailored to their specific study area, allowing for the estimation of other attributes required by the tool.

Depending on the water quality determinant to be modeled, it is necessary to assign the corresponding reaction rates and decay parameters (see

Table 2. Key physicochemical input parameters for each of the water quality determinants.

Water Quality Determinants	Parameter	Unit	Description
Temperature	No parameters	-	-
Suspended Solids	$v_{SS}$	m/day	Sedimentation velocity
Pathogenic Organisms	$k_{dX}$	dimensionless	Constant decay of pathogenic organisms (mortality)
	$F_{px}$	dimensionless	Fraction of pathogenic organisms adsorbed on solid particles
	$v_X$	m/day	Sedimentation velocity of the adsorbed fraction of pathogens on solid particles
Organic Nitrogen	$k_{NO}$	1/day	Decay rate by hydrolysis of organic nitrogen
	$v_{NO}$	m/day	Sedimentation velocity of organic nitrogen
Ammoniacal Nitrogen	$k_{NH4}$	1/day	Nitrification decay rate
Nitrates	$k_{dNO3}$	1/day	Denitrification rate
	$F_{oxdNO3}$	dimensionless	Factor considering the effect of low oxygen on denitrification
Organic Phosphorus	$k_{Po}$	1/day	Organic phosphorus hydrolysis decay rate
	$v_{Po}$	m/day	Organic phosphorus sedimentation velocity
Inorganic Phosphorus	$v_{Pi}$	m/day	Inorganic phosphorus sedimentation velocity
Organic Matter	$k_{dOM}$	1/day	Organic matter oxidation decay rate
	$F_{oxdOM}$	dimensionless	Factor considering the effect of low oxygen on organic matter
Oxygen Deficit	$k_a$	1/day	Reaeration rate
Elemental Mercury	$v_v$	m/day	Elemental mercury volatilization velocity
	$k_{ox}$	1/day	Elemental mercury oxidation reaction rate
	$k_{rx}$	1/day	Oxidation decay rate of mercury
Divalent Mercury	$k_{me,a}$	1/day	Adsorbed divalent mercury methylation rate
	$k_{me,d}$	1/day	Dissolved divalent mercury methylation rate
	$F_{pHg2}$	dimensionless	Fraction of divalent mercury adsorbed on solid particles
	$v_{Hg2}$	m/day	Sedimentation velocity of divalent mercury
Methyl mercury	$F_{pMeHg}$	dimensionless	Fraction of methyl mercury adsorbed on solid particles
	$v_{MeHg}$	m/day	Sedimentation velocity of methyl mercury

). By default, the tool incorporates the values used by [21] for all determinants. However, these parameters are fully editable by the user, allowing for greater flexibility to adapt the model to the specific conditions of the study area.

3. Results and Discussion

3.1. Toolbox Structure

The file and folder structure used by the toolbox is illustrated in Figure 2. The @ClassNetwork object represents the topological network and includes the recursive accumulation operations across this network. In turn, @AFAR_WQS groups the necessary methods for estimating the concentrations and assimilation factors of the various water quality determinants, inheriting the properties and methods of @ClassNetwork. Each determinant is modeled as a specific method within the @AFAR_WQS object, and these methods are executed independently. This allows the user to configure only the required inputs for the specific water quality determinant they intend to model.

AFAR-WQS takes the drainage network as input, organized in a data structure called ReachData. Each row in ReachData corresponds to an individual reach in the network, while the columns contain the geomorphological and physicochemical characteristics of the reach (detailed in Table 1). The ReachData structure can be exported as a shapefile, allowing for visualization and further analysis in any Geographic Information System (GIS) software.

As for the outputs, the toolbox calculates the concentration for each water quality determinant (expressed in mg/L for most determinants, except for coliforms, which is expressed in MPN/L), the assimilation factors in liters, and the loads in mg/day (except for coliforms, which is expressed in MPN/day). These results correspond to the flow scenario previously configured by the user. If different flow conditions need to be evaluated, the user can run multiple model executions to represent various discharge scenarios.

3.2. Computational Performance

The DFS algorithm [30] employed by AFAR-WQS to resolve the topological connectivity of the network exhibits strong computational performance, delivering results within minutes. On a computer equipped with an Intel(R) Core(TM) i7-10750H CPU @ 2.60GHz and 64.0 GB of RAM, AFAR-WQS completes the modeling of a single water quality parameter for a network comprising 30,000 river segments in just 163 s (see Figure 3). A key advantage of AFAR-WQS is its low memory usage, as it does not generate vector data structures larger than the total number of segments in the network. Notably, due to the recursive nature of the DFS algorithm, the computational time scales following a power-law relationship as the number of segments increases. However, for networks containing up to 100,000 segments, the computation times remain manageable and aligned with the requirements of macro-basin scale modeling. The implementation of AFAR-WQS was validated using the results from [21], where we verified that the approach accurately reproduces the original outcomes.

3.3. Outputs and Visualization Options

When modeling a water quality determinant with AFAR-WQS, three key outputs are generated: (1) the concentration of the water quality determinant at the outlet of each reach (represented by object variables starting with “C_”), (2) the assimilation factor for the water quality determinant within the reach (represented by variables beginning with “AF_”), and (3) the load of the water quality determinant at the reach outlet (represented by variables beginning with “W_”). These outputs are generated for each reach in the analysis network and are stored as column vectors within the object representing the network, thereby facilitating efficient data management and analysis.

The toolbox also provides a Matlab application developed in App Designer, enabling users to visualize the results of each water quality determinant and support model interpretation. In the application interface, users can select both the variable and the water quality determinant they wish to visualize (see Figure 4a). The tool offers two visualization options: a network-level representation and a longitudinal profile. For the longitudinal profile, users must specify the Reach ID of the initial reach for the determinant profile. In this visualization, the graph displays the cumulative reach distance on the horizontal axis, spanning from the selected starting reach to the network outlet (river mouth), while the vertical axis illustrates changes in the analyzed determinant variable along the profile (see Figure 4b).

Additionally, the Matlab application allows users to customize the color palette used to visualize the water quality determinant variable, thereby improving visual comprehension and facilitating the analysis of model results.

3.4. Application in the Decision-Making Process

The concept of assimilation factors [22,23], applied to topological networks via graph theory and solved using a Depth-First Search algorithm, provides AFAR-WQS with the ability to run multiple simulations of the same water quality determinant in macro-basins within a matter of minutes. This speed not only optimizes computational times but also creates new opportunities for participatory management and real-time decision-making. For instance, the tool facilitates interactive workshops with key stakeholders, allowing for dynamic evaluation and comparison of scenarios, thereby fostering a deeper understanding and stronger community engagement in water resource management.

Furthermore, the rapid execution of simulations facilitates risk and uncertainty analyses, thereby enhancing support for decision-making in large-scale systems [14]. This capability is especially relevant in contexts where hydrological variability and anthropogenic pressures demand swift, well-founded responses. AFAR-WQS does not aim to replace more detailed studies that can be performed using robust models; rather, its goal is to serve as a preliminary analysis tool offering an integrated view of water quality at the macro-basin scale. This approach helps identify critical areas requiring more detailed study, thus optimizing the allocation of technical and financial resources.

AFAR-WQS’s straightforward and quick configuration enables the evaluation of multiple scenarios in short timeframes, allowing decision-makers to analyze the potential effects of interventions such as constructing wastewater treatment plants or regulating discharges over several downstream kilometers. This capability is particularly useful in infrastructure planning and public policy evaluation, where multiple variables and scenarios must be considered within tight deadlines.

Likewise, the tool accommodates a broad spectrum of variants, enabling comprehensive risk and uncertainty analyses. This feature provides more robust support for selecting which interventions to implement, reducing the likelihood of suboptimal decisions. For instance, in climate change scenarios, where hydrological uncertainty is high, AFAR-WQS can be used to assess the resilience of different management strategies in the face of extreme events such as droughts or floods.

Another potential application of AFAR-WQS is in the context of freshwater ecosystem restoration. With the adoption of the Convention on Biological Diversity [41] by several countries, efforts to restore degraded ecosystems have intensified. According to [42], the success of these initiatives depends largely on the support of local communities, as their active participation contributes to the long-term effectiveness of restoration projects. However, in large areas or at the country scale, this process represents a significant challenge, particularly in communicating to communities the synergies between rivers and how the impacts of restoration projects propagate from upstream to downstream.

Modeling frameworks such as SIGA-CAL [4] allow for robust assessments of the impacts of nature-based solutions (NBS) on water quality. However, their use in workshops with local communities is limited due to the long computation times required; for example, a single simulation for a watershed of more than 10,000 km² can take more than 10 h. In contrast, AFAR-WQS is specifically designed for such contexts, where an exhaustive level of detail is not required, but rather an approximate and rapid response to the impacts that could be generated by interventions across the territory. AFAR-WQS can be configured for very large areas, including entire countries, enabling the evaluation of effects at the basin or national scale in a matter of minutes.

This capability is particularly useful in participatory workshops, where stakeholders often want to explore the potential effects of changes or measures and how they affect water quality. With AFAR-WQS, this is possible in just a few minutes, making it feasible to conduct these interactions in a dynamic and efficient manner. By allowing communities to quickly visualize how interventions propagate from upstream to downstream, AFAR-WQS fosters a deeper understanding of the impacts and benefits of restoration projects, enhancing community engagement and ensuring the sustainability of interventions in the long term.

The output generated by AFAR-WQS aids in identifying priority areas not only for infrastructure investment but also for research and the development of more detailed models focused on specific regions. Various applications reported in the literature corroborate the usefulness of this approach. For example, ref. [25] employed the estimation of assimilation factors to prioritize investments in water sanitation at the national level in Colombia, focusing on pathogens, nitrogen, and phosphorus by calculating the maximum permissible loads in rivers. Similarly, ref. [26] applied the same concept to create a tool aimed at generating and selecting optimal sanitation scenarios based on water quality standards and cost-efficiency using the Bogotá and Teusacá river basins as a case study. Ref. [27] also implemented assimilation factors at the national scale, including uncertainty analyses and designing an investment plan for the water sanitation sector across Peru. Ref. [21] used assimilation factors to evaluate the health and integrity of freshwater ecosystems in the Caquetá River basin, thus demonstrating the applicability of this strategy in freshwater ecosystem conservation. And, more recently, refs. [28,43] employed the same approach to model the transport and fate of mercury in surface waters at the national scale in Colombia.

The recursive algorithm implemented in AFAR-WQS confers scalability when configuring and applying the tool to different network topologies. The only requirement is that the network be a unidirectional graph (i.e., with no cycles), which does not preclude detailed subdivisions of specific reaches for more precise modeling when needed. This flexibility allows its use in urban environments with complex structures and extensive interconnections, as well as the option to combine simplified and detailed segments within a single study. For example, in urban areas with intricate drainage networks, AFAR-WQS can be employed to evaluate the impact of water quality determinant discharges at different points in the network, identifying critical areas that require immediate intervention.

The concept of assimilation factors has also been integrated into regulatory instruments within the Colombian context, such as the official methodology for determining the length of influence of discharges in surface watercourses [44], underscoring the relevance and currency of this approach in public management. This institutional adoption facilitates the uptake of AFAR-WQS by governmental agencies and non-governmental organizations, promoting its use in water resource planning and management at multiple scales.

Finally, by incorporating object-oriented programming, AFAR-WQS aligns with the component-based modeling paradigm [45]. This modular architecture simplifies the addition of new water quality determinants and the extension of conceptual representations to hydrological, sedimentological, and biological processes. Consequently, decision-making becomes more informed by enabling a comparative evaluation of alternative interventions within an integrated water resources management framework.

4. Conclusions

The AFAR-WQS toolbox represents a significant breakthrough in water quality modeling by transforming the theoretical concept of assimilation factors into a practical, scalable, and parsimonious decision-support tool. Developed as an open-source MATLAB™ toolbox, AFAR-WQS leverages graph theory and a Depth-First Search (DFS) algorithm to efficiently resolve cumulative processes in extensive, unidirectional river networks. This approach enables rapid simulations of 13 water quality determinants—including suspended solids, pathogens, nutrients, dissolved oxygen, biochemical oxygen demand, and mercury—across macro-basins, achieving computation times of 163 s for networks with 30,000 segments on standard hardware. Such efficiency addresses the critical challenge of analysis paralysis, empowering stakeholders to evaluate scenarios, conduct risk analyses, and prioritize interventions within feasible timeframes.

The novelty of this study lies in AFAR-WQS’s capability to efficiently resolve cumulative processes in complex topological networks. This not only maximizes computational performance but also enables the rapid simulation of water quality determinants, making it a valuable tool for preliminary assessments and large-scale applications. Furthermore, AFAR-WQS is designed for high adaptability, allowing its application in diverse watershed contexts—from urban environments with intricate drainage networks to large basins. The toolbox’s object-oriented programming approach ensures scalability, permitting users to tailor the model to the specific characteristics of each basin without compromising computational efficiency. Its interactive user interface facilitates result visualization and interpretation, making it accessible for communicating technical information to non-technical stakeholders. This feature is particularly relevant for fostering collaboration among scientists, decision-makers, and local communities, as it promotes participatory decision-making processes. For instance, AFAR-WQS can be employed in stakeholder workshops to simulate and compare various intervention scenarios very quickly, cultivating a shared understanding of potential impacts and trade-offs. This collaborative approach not only enhances transparency in decision-making but also increases the likelihood of successfully implementing water management strategies.

The flexibility of AFAR-WQS is also one of its most notable features. The toolbox accommodates various data sources, ranging from field measurements to outputs from hydrological models, and adapts to diverse geographic contexts. Its object-oriented architecture ensures scalability, allowing users to customize river segmentation, integrate region-specific reaction rates, or refine network topology without undermining performance. Moreover, seamless GIS compatibility facilitates data preparation, visualization, and sharing, bridging the gap between technical modeling and spatial decision-making.

The assimilation factor framework underpinning AFAR-WQS is already institutionally recognized, particularly in Colombia’s regulatory methodology for determining the length of influence for discharges in surface water bodies. While this regulatory framework adopts the conceptual basis of assimilation factors, AFAR-WQS transforms the theory into a dynamic tool for real-world applications. Case studies demonstrate its versatility: from prioritizing sanitation investments in the Bogotá region’s watersheds to modeling mercury transport at the national scale in Colombia and designing climate-resilient water management plans in Peru. These applications highlight AFAR-WQS’s dual role as both a preliminary evaluation tool and a potential platform for stakeholder engagement through participatory workshops that enable real-time scenario comparisons, thus promoting transparency and community acceptance.

By democratizing access to rapid, large-scale water quality assessments, AFAR-WQS supports adaptive governance in the face of climate change, population growth, and regulatory complexity. Its open-source nature fosters collaboration, encouraging the research community to expand its library of determinants or integrate modules for sediment dynamics and ecosystem services. The toolbox, along with its documentation and user-friendly interface, is freely available on GitHub (https://github.com/N4W-Facility/AFAR-WQS_Toolbox) (accessed on 25 February 2025), ensuring that policymakers, scientists, and communities worldwide can harness its potential.