Detailed Description

Statistics for clamping negative input concentrations to zero before speciation. PHREEQC rejects negative concentrations, so every negative value is clamped to zero unconditionally; the warning threshold (a negative value, see ChemistryLib parameter concentration_warning_threshold) only decides whether a clamp is reported. Values in \([\text{warning\_threshold}, 0)\) are treated as floating-point noise and clamped silently; values \(<\text{warning\_threshold}\) are clamped and counted as "severe" so an aggregated warning can be emitted.

The same type is used both as a per-cell leaf (built by clamp()) and as a run-level accumulator (folded by operator+=). It is an aggregate (no user-declared constructor, no private data) so brace-init and = {} reset work.

Definition at line 26 of file ClampingStats.h.

#include <ClampingStats.h>

Public Member Functions
double	clamp (double c, double warning_threshold, std::string_view name)
ClampingStats &	operator+= (ClampingStats const &other)
	Folds another stats object into this accumulator (identity = {}).
void	report (double warning_threshold) const
	WARN for severe clamps, DBUG for silent noise clamps. No-op when empty.

Public Attributes
std::string_view	worst_component_name
	aliases Component::name
std::size_t	n_cells = 0
	cells with any clamping
std::size_t	n_values = 0
	total values clamped
std::size_t	n_severe_cells = 0
	cells with a severe clamp
std::size_t	n_severe_values = 0
	total severe values clamped
double	total_clamped_amount = 0.0
double	worst_negative_value = 0.0

Member Function Documentation

◆ clamp()

double ChemistryLib::PhreeqcIOData::ClampingStats::clamp	(	double	c,
		double	warning_threshold,
		std::string_view	name )

Clamps one concentration: negative values are returned as 0 and the value-level counters are updated; non-negative input is returned unchanged. A value below warning_threshold (which is negative) is recorded as severe and may update the worst value/name. The cell-level counters (n_cells / n_severe_cells) are set by the caller after the per-component loop.

Definition at line 12 of file ClampingStats.cpp.

{
    if (c >= 0.0)
    {
        return c;
    }
    if (c < warning_threshold)
    {
        ++n_severe_values;
        if (c < worst_negative_value)
        {
            worst_negative_value = c;
            worst_component_name = name;
        }
    }
    ++n_values;
    total_clamped_amount += -c;
    return 0.0;
}

References n_severe_values, n_values, total_clamped_amount, worst_component_name, and worst_negative_value.

Referenced by ChemistryLib::PhreeqcIOData::setAqueousSolution().

◆ operator+=()

ClampingStats & ChemistryLib::PhreeqcIOData::ClampingStats::operator+= ( ClampingStats const & other )

Folds another stats object into this accumulator (identity = {}).

Definition at line 33 of file ClampingStats.cpp.

{
    n_cells += other.n_cells;
    n_values += other.n_values;
    n_severe_cells += other.n_severe_cells;
    n_severe_values += other.n_severe_values;
    total_clamped_amount += other.total_clamped_amount;
    if (other.worst_negative_value < worst_negative_value)
    {
        worst_negative_value = other.worst_negative_value;
        worst_component_name = other.worst_component_name;
    }
    return *this;
}

References n_cells, n_severe_cells, n_severe_values, n_values, total_clamped_amount, worst_component_name, and worst_negative_value.

◆ report()

void ChemistryLib::PhreeqcIOData::ClampingStats::report ( double warning_threshold ) const

WARN for severe clamps, DBUG for silent noise clamps. No-op when empty.

Definition at line 48 of file ClampingStats.cpp.

{
    if (n_severe_values > 0)
    {
        WARN(
            "Clamped {:d} concentration value(s) more negative than the "
            "warning threshold ({:g} mol/kgw) to zero across {:d} chemical "
            "system(s) before speciation; worst: '{:s}' = {:g} mol/kgw.",
            n_severe_values, warning_threshold, n_severe_cells,
            worst_component_name, worst_negative_value);
    }
    if (n_values > 0)
    {
        DBUG(
            "PhreeqcIO: clamped {:d} negative concentration value(s) to zero "
            "across {:d} chemical system(s) before speciation (total clamped: "
            "{:g} mol/kgw).",
            n_values, n_cells, total_clamped_amount);
    }
}