|
| 1 | +--- |
| 2 | +-api-id: T:Windows.Devices.Power.PowerGridForecast |
| 3 | +-api-type: winrt class |
| 4 | +--- |
| 5 | + |
| 6 | +# Windows.Devices.Power.PowerGridForecast |
| 7 | + |
| 8 | +<!-- |
| 9 | +public sealed class PowerGridForecast |
| 10 | +--> |
| 11 | + |
| 12 | + |
| 13 | +## -description |
| 14 | + |
| 15 | +Contains information about the power grid that the device is connected to. The data is meant to be used in a forecast for time-shifting the time at which workloads happen, or reducing energy consumption during intense times. |
| 16 | + |
| 17 | +## -remarks |
| 18 | + |
| 19 | +Windows exposes forecasts of power grid carbon emissions based on the power grid that the device is connected to. This data is already used by Windows Update, for example, to time-shift when updates happen in order to lessen carbon emissions. This API exposes these same forecasts to you so that you can reduce the carbon emissions of some of your workloads. For example, you could time-shift when updates of your apps/games happen; or throttle the bit-rate of audio playback, or some other rendering fidelity level; or enable an *efficiency mode*, if you have one. |
| 20 | + |
| 21 | +The power grid forecast API provides two signals to you (to prompt time-shifting). One signal contains a normalized [Severity](./powergriddata_severity.md) value (between 0.0 and 1.0) of grid conditions to optimize for (carbon intensity). The other signal, [IsLowUserExperienceImpact](./powergriddata_islowuserexperienceimpact.md), is a Boolean value that represents when Windows thinks the user will be away from the device. You might choose to use only one signal instead of both; the signals have value individually as well as together. |
| 22 | + |
| 23 | +*Time-shifting* means using the same energy to accomplish work, but doing so at a different time based on a signal. |
| 24 | + |
| 25 | +*Severity* is a normalized value between 0.0 and 1.0, where 0 is considered best, and 1 is worst. That corresponds to power grid carbon severity based on where the device is located. |
| 26 | + |
| 27 | +*Low user-experience impact*. A Boolean value that represents when Windows thinks the user will be away, or not using many resources. This can be thought of as inverse Active Hours. When the value is `true`, it's considered a good time to time-shift workloads to. When it's `false`, it's considered a bad time to time-shift workloads to, in terms of user experience. |
| 28 | + |
| 29 | +## -see-also |
| 30 | + |
| 31 | +## -examples |
| 32 | + |
| 33 | +```csharp |
| 34 | +using Windows.Devices.Power; |
| 35 | + |
| 36 | +void PrintBestTimes(PowerGridForecast forecast) |
| 37 | +{ |
| 38 | + double bestSeverity = double.MaxValue; |
| 39 | + double bestLowImpactSeverity = double.MaxValue; |
| 40 | + DateTime bestTime = DateTime.MaxValue; |
| 41 | + DateTime bestLowImpactTime = DateTime.MaxValue; |
| 42 | + TimeSpan blockDuration = forecast.BlockDuration; |
| 43 | + DateTime startTime = forecast.StartTime; |
| 44 | + IList<PowerGridData> forecastSignals = forecast.Forecast; |
| 45 | + |
| 46 | + if (forecastSignals.Count == 0) |
| 47 | + { |
| 48 | + Console.WriteLine("Error encountered with getting forecast; try again later."); |
| 49 | + return; |
| 50 | + } |
| 51 | + |
| 52 | + foreach (PowerGridData data in forecastSignals) |
| 53 | + { |
| 54 | + if (data.Severity < bestSeverity) |
| 55 | + { |
| 56 | + bestSeverity = data.Severity; |
| 57 | + bestTime = startTime; |
| 58 | + } |
| 59 | + |
| 60 | + if (data.IsLowUserExperienceImpact && data.Severity < bestLowImpactSeverity) |
| 61 | + { |
| 62 | + bestLowImpactSeverity = data.Severity; |
| 63 | + bestLowImpactTime = startTime; |
| 64 | + } |
| 65 | + |
| 66 | + startTime = startTime + blockDuration; |
| 67 | + } |
| 68 | + |
| 69 | + if (bestLowImpactTime != DateTime.MaxValue) |
| 70 | + { |
| 71 | + DateTime endBestLowImpactTime = bestLowImpactTime + blockDuration; |
| 72 | + Console.WriteLine($"Lowest severity during low impact is {bestLowImpactSeverity}, which starts at {bestLowImpactTime.ToString()}, and ends at {endBestLowImpactTime}."); |
| 73 | + } |
| 74 | + else |
| 75 | + { |
| 76 | + Console.WriteLine("There's no low-user-impact time in which to do work."); |
| 77 | + } |
| 78 | + |
| 79 | + if (bestTime != DateTime.MaxValue) |
| 80 | + { |
| 81 | + DateTime endBestSeverity = bestTime + blockDuration; |
| 82 | + Console.WriteLine($"Lowest severity is {bestSeverity}, which starts at {bestTime.ToString()}, and ends at {endBestSeverity.ToString()}."); |
| 83 | + } |
| 84 | +} |
| 85 | + |
| 86 | +PowerGridForecast forecast = PowerGridForecast.GetForecast(); |
| 87 | +PrintBestTimes(forecast); |
| 88 | +``` |
| 89 | + |
| 90 | +```cppwinrt |
| 91 | +#include "pch.h" |
| 92 | +#include <iostream> |
| 93 | +#include <winrt/Windows.Foundation.Collections.h> |
| 94 | +#include <winrt/Windows.Devices.Power.h> |
| 95 | +
|
| 96 | +using namespace winrt::Windows::Devices::Power; |
| 97 | +using namespace winrt::Windows::Foundation::Collections; |
| 98 | +using namespace winrt::Windows::Foundation; |
| 99 | +
|
| 100 | +void PrintFullForecast(PowerGridForecast const& forecast) |
| 101 | +{ |
| 102 | + IVectorView<PowerGridData> forecastSignals = forecast.Forecast(); |
| 103 | + DateTime forecastStartTime = forecast.StartTime(); |
| 104 | + TimeSpan forecastBlockDuration = forecast.BlockDuration(); |
| 105 | + DateTime blockStartTime = forecastStartTime; |
| 106 | +
|
| 107 | + // On failure the forecast will be empty. |
| 108 | + if (forecastSignals.Size() == 0) |
| 109 | + { |
| 110 | + std::wcout << L"Error encountered while reading the forecast; try again later." << std::endl; |
| 111 | + return; |
| 112 | + } |
| 113 | +
|
| 114 | + // Iterate through the forecast printing all the data. |
| 115 | + for (auto const& block : forecastSignals) |
| 116 | + { |
| 117 | + auto severity = block.Severity(); |
| 118 | + auto isLowImpact = block.IsLowUserExperienceImpact(); |
| 119 | +
|
| 120 | + std::wcout << L"Start time - "; |
| 121 | + PrintDateTime(blockStartTime, true); |
| 122 | + std::wcout << L" | End time - "; |
| 123 | + PrintDateTime(blockStartTime + forecastBlockDuration, true); |
| 124 | + std::wcout << L" | Intensity - " << severity << L" | IsLowImpactTime - " << (isLowImpact ? L"TRUE" : L"FALSE") << std::endl; |
| 125 | +
|
| 126 | + blockStartTime = blockStartTime + forecastBlockDuration; |
| 127 | + } |
| 128 | +} |
| 129 | +
|
| 130 | +void PrintBestTimes(PowerGridForecast const& forecast) |
| 131 | +{ |
| 132 | + IVectorView<PowerGridData> forecastSignals = forecast.Forecast(); |
| 133 | + DateTime forecastStartTime = forecast.StartTime(); |
| 134 | + TimeSpan forecastBlockDuration = forecast.BlockDuration(); |
| 135 | + DateTime blockStartTime = forecastStartTime; |
| 136 | +
|
| 137 | + // On failure the forecast will be empty |
| 138 | + if (forecastSignals.Size() == 0) |
| 139 | + { |
| 140 | + std::wcout << L"Error encountered while reading the forecast; try again later." << std::endl; |
| 141 | + return; |
| 142 | + } |
| 143 | +
|
| 144 | + DateTime bestSeverityTimeUTC = DateTime::max(); |
| 145 | + DateTime bestSeverityTimeInLowUserImpactTimeUTC = DateTime::max(); |
| 146 | +
|
| 147 | + // 1.0 is maximum severity the API can return. |
| 148 | + double bestSeverity = 1.0; |
| 149 | + double bestSeverityInLowUserImpactTime = 1.0; |
| 150 | +
|
| 151 | + // Iterate through the forecast looking for the best times. |
| 152 | + for (auto const& block : forecastSignals) |
| 153 | + { |
| 154 | + auto severity = block.Severity(); |
| 155 | + auto isLowImpact = block.IsLowUserExperienceImpact(); |
| 156 | +
|
| 157 | + // Check if there is lower severity |
| 158 | + if (severity < bestSeverity) |
| 159 | + { |
| 160 | + bestSeverity = severity; |
| 161 | + bestSeverityTimeUTC = blockStartTime; |
| 162 | + } |
| 163 | +
|
| 164 | + // Check whether there's a lower severity that's also at a time with low user impact. |
| 165 | + if (isLowImpact && severity < bestSeverityInLowUserImpactTime) |
| 166 | + { |
| 167 | + bestSeverityInLowUserImpactTime = severity; |
| 168 | + bestSeverityTimeInLowUserImpactTimeUTC = blockStartTime; |
| 169 | + } |
| 170 | +
|
| 171 | + blockStartTime = blockStartTime + forecastBlockDuration; |
| 172 | + } |
| 173 | +
|
| 174 | + // Print out the best times only if they've been set. |
| 175 | + if (bestSeverityTimeUTC != DateTime::max()) |
| 176 | + { |
| 177 | + std::wcout << L"Best time to do work is "; |
| 178 | + PrintDateTime(bestSeverityTimeUTC, true); |
| 179 | + std::wcout << L" with a severity of " << bestSeverity; |
| 180 | + std::wcout << L" and ends at "; |
| 181 | + PrintDateTime(bestSeverityTimeUTC + forecastBlockDuration, true); |
| 182 | + std::wcout << std::endl; |
| 183 | + } |
| 184 | +
|
| 185 | + if (bestSeverityTimeInLowUserImpactTimeUTC != DateTime::max()) |
| 186 | + { |
| 187 | + std::wcout << L"Best time with low user impact is "; |
| 188 | + PrintDateTime(bestSeverityTimeInLowUserImpactTimeUTC, true); |
| 189 | + std::wcout << L" with a severity of " << bestSeverityInLowUserImpactTime; |
| 190 | + std::wcout << L" and ends at "; |
| 191 | + PrintDateTime(bestSeverityTimeInLowUserImpactTimeUTC + forecastBlockDuration, true); |
| 192 | + std::wcout << std::endl; |
| 193 | + } |
| 194 | + else |
| 195 | + { |
| 196 | + std::wcout << "There's no low-user-impact time in which to do work." << std::endl; |
| 197 | + } |
| 198 | +} |
| 199 | +
|
| 200 | +int main() |
| 201 | +{ |
| 202 | + std::wcout << L"Power Grid Forecast WinRT API sample app." << std::endl; |
| 203 | +
|
| 204 | + // Register for the forecast notification. |
| 205 | + auto revoker = PowerGridForecast::ForecastUpdated(winrt::auto_revoke, [&](auto, winrt::Windows::Foundation::IInspectable const&) { |
| 206 | + std::wcout << L"Forecast updated..." << std::endl; |
| 207 | +
|
| 208 | + // Forecast has been updated; find the next best times. |
| 209 | + PowerGridForecast forecast = PowerGridForecast::GetForecast(); |
| 210 | + PrintBestTimes(forecast); |
| 211 | + }); |
| 212 | +
|
| 213 | + // Print out the full forecast. |
| 214 | + PowerGridForecast forecast = PowerGridForecast::GetForecast(); |
| 215 | + PrintFullForecast(forecast); |
| 216 | +
|
| 217 | + // Wait until the user presses a key to exit. |
| 218 | + std::cout << "Listening to the signal: a new forecast has been created." |
| 219 | + "Leave this program open to see when a new forecast is created, otherwise press any key to exit this program..." << std::endl; |
| 220 | + std::cin.get(); |
| 221 | +
|
| 222 | + return 0; |
| 223 | +} |
| 224 | +``` |
0 commit comments