Macro Objects

Edge{T} <: AbstractEdge{T}

A mutable struct representing an edge in a network model, parameterized by commodity type T.

# Fields
- id::Symbol: Unique identifier for the edge
- timedata::TimeData: Time-related data for the edge
- start_vertex::AbstractVertex: Starting vertex of the edge
- end_vertex::AbstractVertex: Ending vertex of the edge
- availability::Vector{Float64}: Time series of availability factors
- can_expand::Bool: Whether edge capacity can be expanded
- can_retire::Bool: Whether edge capacity can be retired
- capacity::Union{AffExpr,Float64}: Total available capacity
- capacity_size::Float64: Size factor for resource cluster
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the edge
- distance::Float64: Physical distance of the edge
- existing_capacity::Float64: Initial installed capacity
- fixed_om_cost::Float64: Fixed operation and maintenance costs
- flow::Union{JuMPVariable,Vector{Float64}}: Flow of commodity `T` through the edge at each timestep
- has_capacity::Bool: Whether the edge has capacity variables
- integer_decisions::Bool: Whether capacity decisions must be integer
- investment_cost::Float64: CAPEX per unit of new capacity
- loss_fraction::Vector{Float64}: Fraction of flow lost during transmission, it can be time-dependent.
- max_capacity::Float64: Maximum allowed capacity
- min_capacity::Float64: Minimum required capacity
- min_flow_fraction::Float64: Minimum flow as fraction of capacity
- new_capacity::Union{JuMPVariable,Float64}: JuMP variable representing new capacity built
- ramp_down_fraction::Float64: Maximum ramp-down rate as fraction of capacity
- ramp_up_fraction::Float64: Maximum ramp-up rate as fraction of capacity
- ret_capacity::Union{JuMPVariable,Float64}: JuMP variable representing capacity to be retired
- unidirectional::Bool: Whether flow is restricted to one direction
- variable_om_cost::Float64: Variable operation and maintenance costs per unit flow

Edges represent connections between vertices that allow commodities to flow between them. 
They can model physical infrastructure like pipelines, transmission lines, or logical 
connections with associated costs, capacities, and operational constraints.

EdgeWithUC{T} <: AbstractEdge{T}

A mutable struct representing an edge with unit commitment constraints in a network model, parameterized by commodity type T.

# Inherited Attributes from Edge
- id::Symbol: Unique identifier for the edge
- timedata::TimeData: Time-related data for the edge
- start_vertex::AbstractVertex: Starting vertex of the edge
- end_vertex::AbstractVertex: Ending vertex of the edge
- availability::Vector{Float64}: Time series of availability factors
- can_expand::Bool: Whether edge capacity can be expanded
- can_retire::Bool: Whether edge capacity can be retired
- capacity::Union{AffExpr,Float64}: Total available capacity
- capacity_size::Float64: Size factor for resource cluster
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the edge
- distance::Float64: Physical distance of the edge
- existing_capacity::Float64: Initial installed capacity
- fixed_om_cost::Float64: Fixed operation and maintenance costs
- flow::Union{JuMPVariable,Vector{Float64}}: Flow of commodity through the edge at each timestep
- has_capacity::Bool: Whether the edge has capacity variables
- integer_decisions::Bool: Whether capacity decisions must be integer
- investment_cost::Float64: CAPEX per unit of new capacity
- loss_fraction::Float64: Fraction of flow lost during transmission
- max_capacity::Float64: Maximum allowed capacity
- min_capacity::Float64: Minimum required capacity
- min_flow_fraction::Float64: Minimum flow as fraction of capacity
- new_capacity::Union{JuMPVariable,Float64}: JuMP variable representing new capacity built
- ramp_down_fraction::Float64: Maximum ramp-down rate as fraction of capacity
- ramp_up_fraction::Float64: Maximum ramp-up rate as fraction of capacity
- ret_capacity::Union{JuMPVariable,Float64}: JuMP variable representing capacity to be retired
- unidirectional::Bool: Whether flow is restricted to one direction
- variable_om_cost::Float64: Variable operation and maintenance costs per unit flow

# Fields specific to EdgeWithUC
- min_down_time::Int64: Minimum time units that must elapse between shutting down and starting up
- min_up_time::Int64: Minimum time units that must elapse between starting up and shutting down
- startup_cost::Float64: Cost incurred when starting up the unit
- startup_fuel::Float64: Amount of fuel consumed during startup
- startup_fuel_balance_id::Symbol: Identifier for the balance constraint tracking startup fuel
- ucommit::Union{JuMPVariable,Vector{Float64}}: Binary commitment state variables
- ushut::Union{JuMPVariable,Vector{Float64}}: Binary shutdown decision variables
- ustart::Union{JuMPVariable,Vector{Float64}}: Binary startup decision variables

EdgeWithUC extends Edge to model units that have operational constraints related to their on/off status. It includes variables and parameters
for tracking unit commitment decisions and associated costs/constraints.

Node{T} <: AbstractVertex

A mutable struct representing a node in a network, parameterized by commodity type T.

# Inherited Attributes
- id::Symbol: Unique identifier for the node
- timedata::TimeData: Time-related data for the node
- balance_data::Dict{Symbol,Dict{Symbol,Float64}}: Balance equations data
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the node
- operation_expr::Dict: Operational JuMP expressions for the node

# Fields
- demand::Union{Vector{Float64},Dict{Int64,Float64}}: Time series of demand values
- max_nsd::Vector{Float64}: Maximum allowed non-served demand for each segment
- max_supply::Vector{Float64}: Maximum supply for each segment
- non_served_demand::Union{JuMPVariable,Matrix{Float64}}: JuMP variables or matrix representing unmet demand
- policy_budgeting_vars::Dict: Policy budgeting variables for constraints
- policy_slack_vars::Dict: Policy slack variables for constraints
- price::Union{Vector{Float64},Dict{Int64,Float64}}: Time series of prices
- price_nsd::Vector{Float64}: Penalties for non-served demand by segment
- price_supply::Vector{Float64}: Supply costs by segment
- price_unmet_policy::Dict{DataType,Float64}: Mapping of policy types to penalty costs
- rhs_policy::Dict{DataType,Float64}: Mapping of policy types to right-hand side values
- supply_flow::Union{JuMPVariable,Matrix{Float64}}: JuMP variables or matrix representing supply flows

Note: Base attributes are inherited from AbstractVertex via @AbstractVertexBaseAttributes macro.

Storage{T} <: AbstractVertex

A mutable struct representing a storage vertex in a network model, parameterized by commodity type T.

# Inherited Attributes
- id::Symbol: Unique identifier for the storage
- timedata::TimeData: Time-related data for the storage
- balance_data::Dict{Symbol,Dict{Symbol,Float64}}: Dictionary mapping balance equation IDs to coefficients
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the storage
- operation_expr::Dict: Dictionary storing operational JuMP expressions for the storage

# Fields
- can_expand::Bool: Whether storage capacity can be expanded
- can_retire::Bool: Whether storage capacity can be retired
- capacity::AffExpr: Total available storage capacity
- capacity_size::Float64: Size of each storage unit
- charge_edge::Union{Nothing,AbstractEdge}: `Edge` representing charging flow
- charge_discharge_ratio::Float64: Ratio between charging and discharging rates
- discharge_edge::Union{Nothing,AbstractEdge}: `Edge` representing discharging flow
- existing_capacity::Float64: Initial installed storage capacity
- fixed_om_cost::Float64: Fixed operation and maintenance costs
- investment_cost::Float64: CAPEX per unit of new storage capacity
- loss_fraction::Float64: Fraction of stored commodity lost at each timestep
- loss_fraction::Vector{Float64}: Fraction of stored commodity lost at each timestep
- max_capacity::Float64: Maximum allowed storage capacity
- max_duration::Float64: Maximum storage duration in hours
- max_storage_level::Float64: Maximum storage level as fraction of capacity
- min_capacity::Float64: Minimum required storage capacity
- min_duration::Float64: Minimum storage duration in hours
- min_outflow_fraction::Float64: Minimum discharge rate as fraction of capacity
- min_storage_level::Float64: Minimum storage level as fraction of capacity
- new_capacity::AffExpr: New storage capacity to be built
- new_units::Union{Missing, JuMPVariable}: New storage units to be built
- retired_capacity::AffExpr: Storage capacity to be retired
- retired_units::Union{Missing, JuMPVariable}: Storage units to be retired
- spillage_edge::Union{Nothing,AbstractEdge}: Edge representing spillage/losses (e.g. hydro reservoirs)
- storage_level::Vector{VariableRef}: Storage level at each timestep

Storage vertices represent facilities that can store commodities over time, such as batteries, 
pumped hydro, or gas storage. They can charge (store) and discharge (release) commodities, 
subject to capacity and operational constraints.

Transformation <: AbstractVertex

A mutable struct representing a transformation vertex in a network model, which models a conversion process between different commodities or energy forms.

# Inherited Attributes
- id::Symbol: Unique identifier for the transformation
- timedata::TimeData: Time-related data for the transformation
- balance_data::Dict{Symbol,Dict{Symbol,Float64}}: Dictionary mapping stoichiometric equation IDs to coefficients
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the transformation
- operation_expr::Dict: Dictionary storing operational JuMP expressions for the transformation

Transformations are used to model conversion processes between different commodities, such as power plants 
converting fuel to electricity or electrolyzers converting electricity to hydrogen. The `balance_data` field 
typically contains conversion efficiencies and other relationships between input and output flows.

@AbstractVertexBaseAttributes()

A macro that defines the base attributes for all vertex types in the network model.

# Generated Fields
- id::Symbol: Unique identifier for the vertex
- timedata::TimeData: Time-related data for the vertex
- balance_data::Dict{Symbol,Dict{Symbol,Float64}}: Dictionary mapping balance equation IDs to coefficients
- constraints::Vector{AbstractTypeConstraint}: List of constraints applied to the vertex
- operation_expr::Dict: Dictionary storing operational JuMP expressions for the vertex

This macro is used to ensure consistent base attributes across all vertex types in the network.