# Variables

The following methods provide a compositional approach for defining common variables used in water network optimization models.

## Formulation-agnostic Variables

These methods are always defined over `AbstractWaterModel`

.

### Nodal Variables

`WaterModels.variable_head`

— Function```
variable_head(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Instantiates bounded (by default) or unbounded total hydraulic head (or head) variables for nodes in the network at subnetwork (or time) index `nw`

, i.e., `h[i]`

for `i`

in `node`

. Also instantiates JuMP expressions that are affine expressions of each head, i.e., pressure, which is computed as `p[i] = h[i] - elevation[i]`

, and tank volume (at each tank attached to a node), which is computed as `V[k] = 0.25 * pi * diameter[k]^2 * (h[i] - elevation[i])`

, where `k`

is the index of the tank; `diameter[k]`

is the cross-sectional diameter of the (cylindrical) tank; and `i`

is the index of the node to which the tank is attached.

`WaterModels.variable_demand_flow`

— Function```
variable_demand_flow(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates unbounded volumetric flow rate demand variables for all *dispatchable* demands in the network at subnetwork (or time) index `nw`

, i.e., `q_demand[i]`

for `i`

in `dispatchable_demand`

.

`WaterModels.variable_reservoir_flow`

— Function```
variable_reservoir_flow(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded outgoing volumetric flow rate variables for reservoirs in the network at subnetwork (or time) index `nw`

, i.e., `q_reservoir[i]`

for `i`

in `reservoir`

. Note that these variables are always nonnegative, since for each reservoir, there will never be incoming flow.

`WaterModels.variable_tank_flow`

— Function```
variable_tank_flow(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded volumetric flow rate variables for tanks in the network at subnetwork (or time) index `nw`

, i.e., `q_tank[i]`

for `i`

in `tank`

. Note that, unlike reservoirs, tanks can have inflow, represented as a negative quantity.

### Link Variables

`WaterModels.variable_des_pipe_indicator`

— Function```
variable_des_pipe_indicator(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for design pipes in the network at subnetwork (or time) index `nw`

, i.e., `z_des_pipe[a]`

for `a`

in `des_pipe`

, where one denotes that the pipe has been selected within the design at the current subnetwork (or time) index, and zero indicates that the design pipe has had not been selected.

`WaterModels.variable_pump_head_gain`

— Function```
variable_pump_head_gain(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded head gain variables for pumps in in the network at subnetwork (or time) index `nw`

, i.e., `g_pump[a]`

for `a`

in `pump`

. Note that these variables are always nonnegative, since for each pump, there will never be negative head gain (i.e., pumps only increase head). Head gain is always directed from "node*fr" (i.e., the tail node of the arc) to "node*to" (i.e., the head node of the arc).

`WaterModels.variable_pump_power`

— Function```
variable_pump_power(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded power consumption variables for pumps in the network at subnetwork (or time) index `nw`

, i.e., `P[a]`

for `a`

in `pump`

. Note that these variables are always nonnegative since each pump only *consumes* power. Additionally, two sets of JuMP expressions are also derived from these power variables: energy consumption, i.e., `E[a]`

for `a`

in `pump`

and cost of pump operation across a time step, i.e., `c[a]`

for `a`

in `pump`

.

`WaterModels.variable_pump_indicator`

— Function```
variable_pump_indicator(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for pumps in the network at subnetwork (or time) index `nw`

, i.e., `z_pump[a]`

for `a`

in `pump`

, where one denotes that the pump is currently operating (i.e., on), and zero indicates that the pump is not operating (i.e., off).

`WaterModels.variable_pump_switch_off`

— Function```
variable_pump_switch_off(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for pumps in the network at subnetwork (or time) index `nw`

, i.e., `z_switch_off_pump[a]`

for `a`

in `pump`

, where one denotes that the pump has been switched to the "off" status at the current subnetwork (or time) index, and zero indicates that the pump has had no status change.

`WaterModels.variable_pump_switch_on`

— Function```
variable_pump_switch_on(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for pumps in the network at subnetwork (or time) index `nw`

, i.e., `z_switch_on_pump[a]`

for `a`

in `pump`

, where one denotes that the pump has been switched to the "on" status at the current subnetwork (or time) index, and zero indicates that the pump has had no status change.

`WaterModels.variable_regulator_indicator`

— Function```
variable_regulator_indicator(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for regulators in the network at subnetwork (or time) index `nw`

, i.e., `z_regulator[a]`

for `a`

in `regulator`

, where one denotes that the pressure reducing regulator is currently active and zero otherwise.

`WaterModels.variable_valve_indicator`

— Function```
variable_valve_indicator(
wm::AbstractWaterModel;
nw::Int=nw_id_default,
relax::Bool=false,
report::Bool=true
)
```

Creates binary variables for valves in the network at subnetwork (or time) index `nw`

, i.e., `z_valve[a]`

for `a`

in `valve`

. Here, one denotes that the valve is open and zero denotes that the valve is closed.

## Flow-related Variables

In most of the implemented formulations, we model flow-related quantities in different ways. The formulation-specific functions used for instantiating the associated variables are described below.

`WaterModels.variable_flow`

— Function```
variable_flow(
wm::AbstractNCModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded flow variables for all node- connecting components (e.g., pipes, pumps) in the network at subnetwork (or time) index `nw`

, e.g., `q_pipe[a]`

for `a`

in `pipe`

, `q_pump[a]`

for `a`

in `pump`

. Used for non-flow-direction-based network model formulations only.

```
variable_flow(
wm::AbstractNCDModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates bounded (by default) or unbounded direction-based flow variables for all node-connecting components (e.g., pipes, pumps) in the network at subnetwork (or time) index `nw`

, e.g., `qp_pipe[a]`

and `qn_pipe[a]`

for `a`

in `pipe`

(i.e., positively-directed and negatively-directed flow through the pipe). Also creates JuMP expressions for direction-valued flow, e.g., `q_pipe[a] = qp_pipe[a] - qn_pipe[a]`

for `a`

in `pipe`

. Also creates binary flow direction variables, e.g., `y_pipe[a]`

for `a`

in `pipe`

, where one indicates flow traveling from `node_fr`

(tail of the arc) to `node_to`

(head of the arc). Also creates direction-based head difference variables for pipes and design pipes in the network, e.g., `dhp_pipe[a]`

and `dhn_pipe[a]`

for `a`

in `pipe`

. Used for flow direction-based network model formulations only.

```
variable_flow(
wm::AbstractLAModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates flow-related variables related to linear approximation- (LA-) based optimization models. First, creates flow variables for all node-connecting components (e.g., pipes) in the network at subnetwork (or time) index `nw`

, e.g., `q_pipe[a]`

for `a`

in `pipe`

. Then, creates continuous convex combination variables used to construct necessary linear approximations, e.g., `lambda_pipe[a]`

for `a`

in `pipe`

, where each is bounded between zero and one. Finally, creates binary convex combination variables used for piecewise-linear modeling of the approximating constraints, e.g., `x_pipe[a]`

for `a`

in `pipe`

.

```
variable_flow(
wm::AbstractPWLRDModel;
nw::Int=nw_id_default,
bounded::Bool=true,
report::Bool=true
)
```

Creates flow-related variables linked to piecewise-linear, relaxation- and direction- (PWLRD-) based optimization models. First, creates direction-based flow variables for all node-connecting components (e.g., pipes) in the network at subnetwork (or time) index `nw`

, e.g., `qp_pipe[a]`

and `qn_pipe[a]`

for `a`

in `pipe`

. Also creates JuMP expressions for direction-valued flow, e.g., `q_pipe[a] = qp_pipe[a] - qn_pipe[a]`

for `a`

in `pipe`

. Also creates binary flow direction variables, e.g., `y_pipe[a]`

for `a`

in `pipe`

, where one indicates flow traveling from `node_fr`

(tail of the arc) to `node_to`

(head of the arc). Also creates direction-based head difference variables for pipes and design pipes in the network, e.g., `dhp_pipe[a]`

and `dhn_pipe[a]`

for `a`

in `pipe`

. Then, creates continuous convex combination variables used to construct necessary piecewise-linear relaxations, e.g., `lambda_p_pipe[a]`

and `lambda_n_pipe[a]`

for `a`

in `pipe`

, where each is bounded between zero and one. Finally, creates binary convex combination variables used for piecewise-linear modeling of the relaxation constraints, e.g., `x_p_pipe[a]`

and `x_n_pipe[a]`

for `a`

in `pipe`

.