1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
//! Inflow non-negativity treatment method for SDDP subproblems.
//!
//! [`InflowNonNegativityMethod`] is a flat enum representing the strategies
//! for handling negative PAR(p) inflow realisations in the LP subproblems.
//! It is dispatched via `match` when constructing LP templates and extracting
//! simulation results. Enum dispatch is used because the variant set is closed
//! (enum dispatch for closed variant sets).
/// Inflow non-negativity treatment method.
///
/// Determines whether slack columns are added to the LP and what objective
/// coefficient they carry. The variant must be the same across all stages
/// (set once at solver initialisation from the loaded case config).
///
/// # Examples
///
/// ```rust
/// use cobre_sddp::InflowNonNegativityMethod;
///
/// let penalty = InflowNonNegativityMethod::Penalty;
/// assert!(penalty.has_slack_columns());
///
/// let none = InflowNonNegativityMethod::None;
/// assert!(!none.has_slack_columns());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
pub enum InflowNonNegativityMethod {
/// No inflow non-negativity enforcement.
///
/// The LP does not include slack columns. Negative inflow noise may cause
/// LP infeasibility if the PAR(p) noise realisation is sufficiently negative.
None,
/// Truncation-based enforcement: clamps negative PAR(p) inflows to zero
/// by modifying the noise vector before LP patching.
///
/// Does not add slack columns to the LP. Instead, the PAR(p) model is
/// evaluated outside the LP to obtain the full inflow value; if the result
/// is negative, the noise component is adjusted so that the inflow is zero.
/// This prevents LP infeasibility without perturbing the objective function.
Truncation,
/// Penalty-based enforcement.
///
/// Appends `N` slack columns (`sigma_inf_h >= 0`) to the LP. Each slack
/// enters the water balance row for hydro `h` with coefficient
/// `tau_total * M3S_TO_HM3`, where `tau_total` is the total stage duration
/// in hours. The objective coefficient is sourced from
/// `penalties.json → hydro.inflow_nonnegativity_cost` (default 1000.0).
Penalty,
/// Combined truncation and penalty enforcement.
///
/// The PAR(p) noise is clamped (identical to `Truncation`) so that the
/// mean + noise inflow is never negative. In addition, penalty slack
/// columns are added (identical to `Penalty`) so the solver can "undo"
/// part of the clamping if cost-effective. This matches `SPTcpp`'s
/// `truncamento_penalizacao` mode.
TruncationWithPenalty,
}
impl InflowNonNegativityMethod {
/// Returns `true` when slack columns are appended to the LP.
///
/// # Examples
///
/// ```rust
/// use cobre_sddp::InflowNonNegativityMethod;
///
/// assert!(!InflowNonNegativityMethod::None.has_slack_columns());
/// assert!(InflowNonNegativityMethod::Penalty.has_slack_columns());
/// ```
#[must_use]
pub fn has_slack_columns(&self) -> bool {
matches!(
self,
InflowNonNegativityMethod::Penalty | InflowNonNegativityMethod::TruncationWithPenalty
)
}
}
impl From<&cobre_io::config::InflowNonNegativityConfig> for InflowNonNegativityMethod {
/// Convert from the cobre-io config type.
///
/// Recognised method values are `None`, `Truncation`, `Penalty`,
/// and `TruncationWithPenalty` (the typed enum — typos are rejected at parse
/// time before this conversion runs).
fn from(cfg: &cobre_io::config::InflowNonNegativityConfig) -> Self {
match cfg.method {
cobre_io::config::InflowNonNegativityMethod::None => InflowNonNegativityMethod::None,
cobre_io::config::InflowNonNegativityMethod::Truncation => {
InflowNonNegativityMethod::Truncation
}
cobre_io::config::InflowNonNegativityMethod::Penalty => {
InflowNonNegativityMethod::Penalty
}
cobre_io::config::InflowNonNegativityMethod::TruncationWithPenalty => {
InflowNonNegativityMethod::TruncationWithPenalty
}
}
}
}
#[cfg(test)]
mod tests {
use super::InflowNonNegativityMethod;
use cobre_io::config::{InflowNonNegativityConfig, InflowNonNegativityMethod as CfgMethod};
// ── has_slack_columns ────────────────────────────────────────────────────
#[test]
fn none_has_no_slack_columns() {
assert!(!InflowNonNegativityMethod::None.has_slack_columns());
}
#[test]
fn truncation_has_no_slack_columns() {
assert!(!InflowNonNegativityMethod::Truncation.has_slack_columns());
}
#[test]
fn penalty_has_slack_columns() {
assert!(InflowNonNegativityMethod::Penalty.has_slack_columns());
}
// ── conversion from config ───────────────────────────────────────────────
#[test]
fn test_inflow_method_conversion_none() {
let cfg = InflowNonNegativityConfig {
method: CfgMethod::None,
};
assert_eq!(
InflowNonNegativityMethod::from(&cfg),
InflowNonNegativityMethod::None
);
}
#[test]
fn test_inflow_method_conversion_penalty() {
let cfg = InflowNonNegativityConfig {
method: CfgMethod::Penalty,
};
assert_eq!(
InflowNonNegativityMethod::from(&cfg),
InflowNonNegativityMethod::Penalty
);
}
#[test]
fn test_inflow_method_conversion_truncation() {
let cfg = InflowNonNegativityConfig {
method: CfgMethod::Truncation,
};
assert_eq!(
InflowNonNegativityMethod::from(&cfg),
InflowNonNegativityMethod::Truncation
);
}
// ── TruncationWithPenalty ───────────────────────────────────────────────
#[test]
fn truncation_with_penalty_has_slack_columns() {
assert!(InflowNonNegativityMethod::TruncationWithPenalty.has_slack_columns());
}
#[test]
fn test_inflow_method_conversion_truncation_with_penalty() {
let cfg = InflowNonNegativityConfig {
method: CfgMethod::TruncationWithPenalty,
};
assert_eq!(
InflowNonNegativityMethod::from(&cfg),
InflowNonNegativityMethod::TruncationWithPenalty
);
}
}