Power#

use core::time::Duration;

use pamoja_power::{DutyCycle, PowerMode, PowerPlan};

// A solar node samples every minute while the charge is healthy, stretches to ten
// minutes to conserve, and to an hour once the battery is nearly flat.
let plan = PowerPlan::new(
    Duration::from_secs(60),
    Duration::from_secs(600),
    Duration::from_secs(3600),
);

// The default thresholds enter saver mode below 50% charge and critical below 20%.
for charge in [0.80, 0.35, 0.12] {
    let mode = plan.mode(charge);
    let every = plan.interval(charge).as_secs();
    let percent = charge * 100.0;
    println!("at {percent:.0}% charge: {mode:?}, sampling every {every}s");
}

// A panel that is delivering buys back one mode. The interval for a charge knows
// nothing of the panel, so the cadence comes from the mode the panel bought.
let charging = plan.mode_while_charging(0.12, true);
let every = plan.interval_for(charging).as_secs();
println!("at 12% charge while charging: {charging:?}, sampling every {every}s");

// A charge worked out from a fuel gauge that did not answer is not a number. The
// plan takes it as critical, so a node that cannot tell what it has left does the
// least until it can.
let unknown = f32::NAN;
let (mode, every) = (plan.mode(unknown), plan.interval(unknown).as_secs());
println!("with no reading from the gauge: {mode:?}, sampling every {every}s");

// The thresholds say how long the battery must carry the node without sun. Winter
// nights are long, so a winter plan starts saving sooner and goes critical sooner.
let winter = plan.thresholds(0.70, 0.30);
let saver = winter.saver_below() * 100.0;
let critical = winter.critical_below() * 100.0;
println!("the winter plan saves below {saver:.0}% and goes critical below {critical:.0}%");
let (cold, mild) = (winter.mode(0.60), plan.mode(0.60));
println!("at 60% charge: {cold:?} in winter, {mild:?} by default");

// A fuel gauge wanders a point or two between readings, so a charge sitting at a
// threshold would change the cadence on every cycle. `next_mode` takes the mode the
// node is in: it drops as soon as the charge falls below a threshold, and climbs
// back only once the charge is the plan's hysteresis margin clear of it.
let wandering = [0.49, 0.51, 0.50, 0.53, 0.48, 0.52];
let walk = |governor: PowerPlan| {
    let mut mode = PowerMode::Active;
    let mut modes = Vec::new();
    for charge in wandering {
        mode = governor.next_mode(mode, charge);
        modes.push(format!("{mode:?}"));
    }
    modes.join(", ")
};
let flapping = walk(plan.with_hysteresis(0.0));
println!("a charge wandering around 50% with no margin: {flapping}");
let margin = plan.hysteresis() * 100.0;
let settled = walk(plan);
println!("and with the {margin:.0} point margin: {settled}");
let back = plan.next_mode(PowerMode::Saver, 0.56);
println!("at 56% the charge has cleared the margin: {back:?}");

// The work is the same two seconds whichever mode the node is in; stretching the cycle
// is what saves the energy. The duty fraction is the proxy for average draw, so the
// hourly cadence costs a sixtieth of what the one-minute cadence does.
let awake = Duration::from_secs(2);
let healthy = DutyCycle::new(awake, plan.interval(0.80) - awake);
let flat = DutyCycle::new(awake, plan.interval(0.12) - awake);
let (healthy_duty, flat_duty) = (healthy.fraction() * 100.0, flat.fraction() * 100.0);
println!("awake {healthy_duty:.2}% of the time when healthy");
println!("awake {flat_duty:.3}% of the time when flat");

// A node that lives on its panel can stay awake for the share of the time the harvest
// pays for. Asleep it draws next to nothing, so that share is the harvest over what it
// draws awake, and the duty cycle turns it into time.
let minute = Duration::from_secs(60);
let awake_mw = 120.0;
let cloudy = DutyCycle::from_fraction(minute, 12.0 / awake_mw);
let paid = cloudy.active().as_millis();
println!("a 12 mW harvest pays for {paid}ms awake in each minute");

// The share is clamped, so a harvest above the draw keeps the node awake throughout,
// and a harvest the meter could not read keeps it asleep until one can be.
let sunny = DutyCycle::from_fraction(minute, 150.0 / awake_mw);
let unread = DutyCycle::from_fraction(minute, f32::NAN);
let awake_all = sunny.active().as_millis();
let asleep_all = unread.sleep().as_millis();
println!("a 150 mW harvest keeps it awake all {awake_all}ms");
println!("an unread harvest keeps it asleep all {asleep_all}ms");

import { DutyCycle, PowerMode, PowerPlan } from '@pamoja/power'

// A solar node samples every minute while the charge is healthy, stretches to ten minutes
// to conserve, and to an hour once the battery is nearly flat. Durations cross the binding
// as microseconds.
const plan = new PowerPlan(60_000_000, 600_000_000, 3_600_000_000)

// The default thresholds enter saver mode below 50% charge and critical below 20%.
for (const charge of [0.8, 0.35, 0.12]) {
  const every = plan.intervalUs(charge) / 1_000_000
  console.log(
    `at ${(charge * 100).toFixed(0)}% charge: ${plan.mode(charge)}, sampling every ${every}s`,
  )
}

// A panel that is delivering buys back one mode. The interval for a charge knows nothing of
// the panel, so the cadence comes from the mode the panel bought.
const charging = plan.modeWhileCharging(0.12, true)
const chargingEvery = plan.intervalForUs(charging) / 1_000_000
console.log(`at 12% charge while charging: ${charging}, sampling every ${chargingEvery}s`)

// A charge worked out from a fuel gauge that did not answer is not a number. The plan takes
// it as critical, so a node that cannot tell what it has left does the least until it can.
const unknown = Number.NaN
const unknownEvery = plan.intervalUs(unknown) / 1_000_000
console.log(
  `with no reading from the gauge: ${plan.mode(unknown)}, sampling every ${unknownEvery}s`,
)

// The thresholds say how long the battery must carry the node without sun. Winter nights
// are long, so a winter plan starts saving sooner and goes critical sooner.
const winter = plan.withThresholds(0.7, 0.3)
const saver = (winter.saverBelow * 100).toFixed(0)
const critical = (winter.criticalBelow * 100).toFixed(0)
console.log(`the winter plan saves below ${saver}% and goes critical below ${critical}%`)
const cold = winter.mode(0.6)
const mild = plan.mode(0.6)
console.log(`at 60% charge: ${cold} in winter, ${mild} by default`)

// A fuel gauge wanders a point or two between readings, so a charge sitting at a threshold
// would change the cadence on every cycle. `nextMode` takes the mode the node is in: it drops
// as soon as the charge falls below a threshold, and climbs back only once the charge is the
// plan's hysteresis margin clear of it.
const wandering = [0.49, 0.51, 0.5, 0.53, 0.48, 0.52]
const walk = (governor: PowerPlan): string => {
  let mode: PowerMode = PowerMode.Active
  const modes: string[] = []
  for (const charge of wandering) {
    mode = governor.nextMode(mode, charge)
    modes.push(mode)
  }
  return modes.join(', ')
}
const flapping = walk(plan.withHysteresis(0))
console.log(`a charge wandering around 50% with no margin: ${flapping}`)
const margin = (plan.hysteresis * 100).toFixed(0)
const settled = walk(plan)
console.log(`and with the ${margin} point margin: ${settled}`)
const back = plan.nextMode(PowerMode.Saver, 0.56)
console.log(`at 56% the charge has cleared the margin: ${back}`)

// The work is the same two seconds whichever mode the node is in; stretching the cycle is
// what saves the energy. The duty fraction is the proxy for average draw, so the hourly
// cadence costs a sixtieth of what the one-minute cadence does.
const awakeUs = 2_000_000
const healthy = new DutyCycle(awakeUs, plan.intervalUs(0.8) - awakeUs)
const flat = new DutyCycle(awakeUs, plan.intervalUs(0.12) - awakeUs)
console.log(`awake ${(healthy.fraction * 100).toFixed(2)}% of the time when healthy`)
console.log(`awake ${(flat.fraction * 100).toFixed(3)}% of the time when flat`)

// A node that lives on its panel can stay awake for the share of the time the harvest pays
// for. Asleep it draws next to nothing, so that share is the harvest over what it draws
// awake, and the duty cycle turns it into time.
const minuteUs = 60_000_000
const awakeMw = 120
const cloudy = DutyCycle.fromFraction(minuteUs, 12 / awakeMw)
console.log(`a 12 mW harvest pays for ${cloudy.activeUs / 1000}ms awake in each minute`)

// The share is clamped, so a harvest above the draw keeps the node awake throughout, and a
// harvest the meter could not read keeps it asleep until one can be.
const sunny = DutyCycle.fromFraction(minuteUs, 150 / awakeMw)
const unread = DutyCycle.fromFraction(minuteUs, Number.NaN)
console.log(`a 150 mW harvest keeps it awake all ${sunny.activeUs / 1000}ms`)
console.log(`an unread harvest keeps it asleep all ${unread.sleepUs / 1000}ms`)

from pamoja.power import DutyCycle, PowerMode, power_plan

# A solar node samples every minute while the charge is healthy, stretches to ten minutes
# to conserve, and to an hour once the battery is nearly flat. Durations cross the binding
# as microseconds.
plan = power_plan(60_000_000, 600_000_000, 3_600_000_000)

# The default thresholds enter saver mode below 50% charge and critical below 20%.
for charge in (0.80, 0.35, 0.12):
    every = plan.interval_us(charge) // 1_000_000
    print(f"at {charge * 100:.0f}% charge: {plan.mode(charge)}, sampling every {every}s")

# A panel that is delivering buys back one mode. The interval for a charge knows nothing of
# the panel, so the cadence comes from the mode the panel bought.
charging = plan.mode_while_charging(0.12, True)
every = plan.interval_for_us(charging) // 1_000_000
print(f"at 12% charge while charging: {charging}, sampling every {every}s")

# A charge worked out from a fuel gauge that did not answer is not a number. The plan takes
# it as critical, so a node that cannot tell what it has left does the least until it can.
unknown = float("nan")
every = plan.interval_us(unknown) // 1_000_000
print(f"with no reading from the gauge: {plan.mode(unknown)}, sampling every {every}s")

# The thresholds say how long the battery must carry the node without sun. Winter nights
# are long, so a winter plan starts saving sooner and goes critical sooner.
winter = plan.with_thresholds(0.70, 0.30)
saver, critical = winter.saver_below * 100, winter.critical_below * 100
print(f"the winter plan saves below {saver:.0f}% and goes critical below {critical:.0f}%")
cold, mild = winter.mode(0.60), plan.mode(0.60)
print(f"at 60% charge: {cold} in winter, {mild} by default")

# A fuel gauge wanders a point or two between readings, so a charge sitting at a threshold
# would change the cadence on every cycle. `next_mode` takes the mode the node is in: it
# drops as soon as the charge falls below a threshold, and climbs back only once the charge
# is the plan's hysteresis margin clear of it.
wandering = (0.49, 0.51, 0.50, 0.53, 0.48, 0.52)


def walk(governor):
    mode = PowerMode.ACTIVE
    modes = []
    for charge in wandering:
        mode = governor.next_mode(mode, charge)
        modes.append(mode)
    return ", ".join(modes)


flapping = walk(plan.with_hysteresis(0))
print(f"a charge wandering around 50% with no margin: {flapping}")
margin = plan.hysteresis * 100
settled = walk(plan)
print(f"and with the {margin:.0f} point margin: {settled}")
back = plan.next_mode(PowerMode.SAVER, 0.56)
print(f"at 56% the charge has cleared the margin: {back}")

# The work is the same two seconds whichever mode the node is in; stretching the cycle is
# what saves the energy. The duty fraction is the proxy for average draw, so the hourly
# cadence costs a sixtieth of what the one-minute cadence does.
awake_us = 2_000_000
healthy = DutyCycle(awake_us, plan.interval_us(0.80) - awake_us)
flat = DutyCycle(awake_us, plan.interval_us(0.12) - awake_us)
print(f"awake {healthy.fraction * 100:.2f}% of the time when healthy")
print(f"awake {flat.fraction * 100:.3f}% of the time when flat")

# A node that lives on its panel can stay awake for the share of the time the harvest pays
# for. Asleep it draws next to nothing, so that share is the harvest over what it draws
# awake, and the duty cycle turns it into time.
minute_us = 60_000_000
awake_mw = 120
cloudy = DutyCycle.from_fraction(minute_us, 12 / awake_mw)
print(f"a 12 mW harvest pays for {cloudy.active_us // 1000}ms awake in each minute")

# The share is clamped, so a harvest above the draw keeps the node awake throughout, and a
# harvest the meter could not read keeps it asleep until one can be.
sunny = DutyCycle.from_fraction(minute_us, 150 / awake_mw)
unread = DutyCycle.from_fraction(minute_us, float("nan"))
print(f"a 150 mW harvest keeps it awake all {sunny.active_us // 1000}ms")
print(f"an unread harvest keeps it asleep all {unread.sleep_us // 1000}ms")

// A solar node samples every minute while the charge is healthy, stretches to ten
// minutes to conserve, and to an hour once the battery is nearly flat. Durations
// cross the binding as microseconds.
PowerPlan plan = PowerPlan.Create(60_000_000, 600_000_000, 3_600_000_000);

// The default thresholds enter saver mode below 50% charge and critical below 20%.
foreach (float charge in new[] { 0.80f, 0.35f, 0.12f })
{
    ulong every = plan.IntervalUs(charge) / 1_000_000;
    Console.WriteLine(Invariant(
        $"at {charge * 100:F0}% charge: {plan.Mode(charge)}, sampling every {every}s"));
}

// A panel that is delivering buys back one mode. The interval for a charge knows
// nothing of the panel, so the cadence comes from the mode the panel bought.
PowerMode charging = plan.ModeWhileCharging(0.12f, true);
ulong chargingEvery = plan.IntervalForUs(charging) / 1_000_000;
Console.WriteLine(
    $"at 12% charge while charging: {charging}, sampling every {chargingEvery}s");

// A charge worked out from a fuel gauge that did not answer is not a number. The
// plan takes it as critical, so a node that cannot tell what it has left does the
// least until it can.
float unknown = float.NaN;
ulong unknownEvery = plan.IntervalUs(unknown) / 1_000_000;
Console.WriteLine(
    $"with no reading from the gauge: {plan.Mode(unknown)}, sampling every {unknownEvery}s");

// The thresholds say how long the battery must carry the node without sun. Winter
// nights are long, so a winter plan starts saving sooner and goes critical sooner.
PowerPlan winter = plan.WithThresholds(0.70f, 0.30f);
Console.WriteLine(Invariant(
    $"the winter plan saves below {winter.SaverBelow * 100:F0}% and goes critical below {winter.CriticalBelow * 100:F0}%"));
PowerMode cold = winter.Mode(0.60f);
PowerMode mild = plan.Mode(0.60f);
Console.WriteLine($"at 60% charge: {cold} in winter, {mild} by default");

// A fuel gauge wanders a point or two between readings, so a charge sitting at a
// threshold would change the cadence on every cycle. NextMode takes the mode the
// node is in: it drops as soon as the charge falls below a threshold, and climbs
// back only once the charge is the plan's hysteresis margin clear of it.
float[] wandering = { 0.49f, 0.51f, 0.50f, 0.53f, 0.48f, 0.52f };
string Walk(PowerPlan governor)
{
    PowerMode mode = PowerMode.Active;
    var modes = new List<string>();
    foreach (float charge in wandering)
    {
        mode = governor.NextMode(mode, charge);
        modes.Add(mode.ToString());
    }
    return string.Join(", ", modes);
}
string flapping = Walk(plan.WithHysteresis(0f));
Console.WriteLine($"a charge wandering around 50% with no margin: {flapping}");
float margin = plan.Hysteresis * 100;
string settled = Walk(plan);
Console.WriteLine(Invariant($"and with the {margin:F0} point margin: {settled}"));
PowerMode back = plan.NextMode(PowerMode.Saver, 0.56f);
Console.WriteLine($"at 56% the charge has cleared the margin: {back}");

// The work is the same two seconds whichever mode the node is in; stretching the
// cycle is what saves the energy. The duty fraction is the proxy for average draw,
// so the hourly cadence costs a sixtieth of what the one-minute cadence does.
const ulong AwakeUs = 2_000_000;
var healthy = new DutyCycle(AwakeUs, plan.IntervalUs(0.80f) - AwakeUs);
var flat = new DutyCycle(AwakeUs, plan.IntervalUs(0.12f) - AwakeUs);
Console.WriteLine(Invariant($"awake {healthy.Fraction * 100:F2}% of the time when healthy"));
Console.WriteLine(Invariant($"awake {flat.Fraction * 100:F3}% of the time when flat"));

// A node that lives on its panel can stay awake for the share of the time the
// harvest pays for. Asleep it draws next to nothing, so that share is the harvest
// over what it draws awake, and the duty cycle turns it into time.
const ulong MinuteUs = 60_000_000;
const float AwakeMw = 120f;
DutyCycle cloudy = DutyCycle.FromFraction(MinuteUs, 12f / AwakeMw);
Console.WriteLine($"a 12 mW harvest pays for {cloudy.ActiveUs / 1000}ms awake in each minute");

// The share is clamped, so a harvest above the draw keeps the node awake
// throughout, and a harvest the meter could not read keeps it asleep until one
// can be.
DutyCycle sunny = DutyCycle.FromFraction(MinuteUs, 150f / AwakeMw);
DutyCycle unread = DutyCycle.FromFraction(MinuteUs, float.NaN);
Console.WriteLine($"a 150 mW harvest keeps it awake all {sunny.ActiveUs / 1000}ms");
Console.WriteLine($"an unread harvest keeps it asleep all {unread.SleepUs / 1000}ms");