surge-network 0.1.9

Surge network — canonical power-system domain model
Documentation 
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

// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
//! Time-series profile types — hourly load and renewable capacity factor data.
//!
//! Used by `surge-io` profile readers and the Python bindings.
//!
//! ## Stable identifiers
//!
//! All profile types use **stable external identifiers** rather than internal
//! array indices.  Generator-targeted profiles use canonical generator IDs;
//! branch-targeted profiles use `(from_bus, to_bus, circuit)`.

use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// Load profiles
// ---------------------------------------------------------------------------

/// Hourly load profile for a single bus.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LoadProfile {
    /// External bus number (matches `Bus::number`).
    pub bus: u32,
    /// MW load for each hour.
    pub load_mw: Vec<f64>,
}

/// Collection of load profiles across buses.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct LoadProfiles {
    pub profiles: Vec<LoadProfile>,
    pub n_timesteps: usize,
}

// ---------------------------------------------------------------------------
// Renewable profiles
// ---------------------------------------------------------------------------

/// Hourly capacity factor profile for a renewable generator.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RenewableProfile {
    /// Canonical generator ID (matches `Generator::id`).
    pub generator_id: String,
    /// Capacity factor \[0, 1\] for each hour.
    pub capacity_factors: Vec<f64>,
}

/// Collection of renewable profiles.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RenewableProfiles {
    pub profiles: Vec<RenewableProfile>,
    pub n_timesteps: usize,
}

// ---------------------------------------------------------------------------
// Generator derate profiles
// ---------------------------------------------------------------------------

/// Per-interval derate factor for a single generator.
///
/// A derate factor of `1.0` means full nameplate capacity is available.
/// A derate factor of `0.5` means 50% of nameplate is available (partial outage).
/// A derate factor of `0.0` means the unit is fully offline (forced outage).
///
/// Applied *before* renewable capacity factors so that
/// `pmax_effective = pmax_nameplate × derate × cf`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GeneratorDerateProfile {
    /// Canonical generator ID (matches `Generator::id`).
    pub generator_id: String,
    /// Derate factor [0, 1] for each interval.
    pub derate_factors: Vec<f64>,
}

/// Collection of generator derate profiles.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GeneratorDerateProfiles {
    pub profiles: Vec<GeneratorDerateProfile>,
    pub n_timesteps: usize,
}

// ---------------------------------------------------------------------------
// Branch derate profiles
// ---------------------------------------------------------------------------

/// Per-interval derate factor for a single branch.
///
/// A derate factor of `1.0` leaves the thermal rating (`rate_a`) unchanged.
/// A derate factor in `(0, 1)` tightens the thermal limit proportionally
/// (e.g., seasonal ambient-adjusted ratings).
/// A derate factor of `0.0` marks the branch as out of service for that interval.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BranchDerateProfile {
    /// From-bus number (matches `Branch::from_bus`).
    pub from_bus: u32,
    /// To-bus number (matches `Branch::to_bus`).
    pub to_bus: u32,
    /// Circuit identifier (matches `Branch::circuit`).
    pub circuit: String,
    /// Derate factor [0, 1] for each interval.
    pub derate_factors: Vec<f64>,
}

/// Collection of branch derate profiles.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct BranchDerateProfiles {
    pub profiles: Vec<BranchDerateProfile>,
    pub n_timesteps: usize,
}

// ---------------------------------------------------------------------------
// HVDC derate profiles
// ---------------------------------------------------------------------------

/// Per-interval derate factor for a single HVDC link.
///
/// A derate factor of `1.0` leaves the scheduled setpoint unchanged.
/// A derate factor in `(0, 1)` reduces the transfer capacity proportionally.
/// A derate factor of `0.0` takes the link fully out of service for that interval.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HvdcDerateProfile {
    /// HVDC link name (matches `HvdcLink::name()`).
    pub name: String,
    /// Derate factor [0, 1] for each interval.
    pub derate_factors: Vec<f64>,
}

/// Collection of HVDC derate profiles.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HvdcDerateProfiles {
    pub profiles: Vec<HvdcDerateProfile>,
    pub n_timesteps: usize,
}