use std::collections::VecDeque;
use std::time::Duration;
use crate::types::{DateTime, Decimal};
const WH: i128 = 3_600_000_000;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PhaseSwitching {
Follows {
pause: Duration,
},
StopsCharging,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Limit {
Amps(Decimal),
Watts(Decimal),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Power {
Charge(Decimal),
Discharge(Decimal),
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Command {
ceiling: Option<Limit>,
phases: Option<u8>,
target: Option<Power>,
discharge_ceiling: Option<Decimal>,
}
fn magnitude(value: impl Into<Decimal>, what: &str) -> Decimal {
let value = value.into();
assert!(value.signum() >= 0, "{what} is a magnitude, got {value}");
value
}
impl Command {
#[must_use]
pub fn unlimited() -> Self {
Self::default()
}
#[must_use]
pub fn amps(amps: impl Into<Decimal>) -> Self {
Self {
ceiling: Some(Limit::Amps(magnitude(amps, "a current"))),
..Self::default()
}
}
#[must_use]
pub fn watts(watts: impl Into<Decimal>) -> Self {
Self {
ceiling: Some(Limit::Watts(magnitude(watts, "a power"))),
..Self::default()
}
}
#[must_use]
pub fn phases(mut self, phases: u8) -> Self {
assert!((1..=3).contains(&phases), "phases must be 1, 2 or 3");
self.phases = Some(phases);
self
}
#[must_use]
pub fn target(mut self, target: Power) -> Self {
let (Power::Charge(w) | Power::Discharge(w)) = target;
magnitude(w, "a power target");
self.target = Some(target);
self
}
#[must_use]
pub fn discharge_at_most(mut self, watts: impl Into<Decimal>) -> Self {
self.discharge_ceiling = Some(magnitude(watts, "a discharge limit"));
self
}
#[must_use]
pub fn ceiling(&self) -> Option<Limit> {
self.ceiling
}
#[must_use]
pub fn phase_count(&self) -> Option<u8> {
self.phases
}
#[must_use]
pub fn power_target(&self) -> Option<Power> {
self.target
}
#[must_use]
pub fn discharge_ceiling(&self) -> Option<Decimal> {
self.discharge_ceiling
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum EvState {
Unplugged,
Connected,
Charging,
Discharging,
SuspendedEv,
SuspendedEvse,
SwitchingPhases,
Faulted,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct Reading {
pub power: Decimal,
pub current: Decimal,
pub phases: u8,
pub soc: Decimal,
pub imported: Decimal,
pub exported: Decimal,
pub state: EvState,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum EvError {
AlreadyPlugged,
NotPlugged,
}
impl core::fmt::Display for EvError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str(match self {
Self::AlreadyPlugged => "the vehicle is plugged in already",
Self::NotPlugged => "the vehicle is not plugged in",
})
}
}
impl std::error::Error for EvError {}
#[derive(Clone, Debug)]
pub struct Ev {
capacity: i128,
target: i128,
floor: i128,
phases: u8,
min_current: Decimal,
max_current: Decimal,
voltage: Decimal,
reaction: Duration,
switching: PhaseSwitching,
taper_above: Option<Decimal>,
max_discharge: Option<Decimal>,
departure: Option<DateTime>,
plugged: bool,
stored: i128,
imported: i128,
exported: i128,
elapsed: u64,
applied: Option<Command>,
pending: VecDeque<(u64, Command)>,
phases_in_use: u8,
switching_until: Option<u64>,
faulted: bool,
}
#[derive(Clone, Debug)]
pub struct EvBuilder {
battery_wh: Decimal,
soc: Decimal,
target_soc: Decimal,
floor_soc: Decimal,
phases: u8,
min_current: Decimal,
max_current: Decimal,
voltage: Decimal,
reaction: Duration,
switching: PhaseSwitching,
taper_above: Option<Decimal>,
max_discharge: Option<Decimal>,
departure: Option<DateTime>,
}
impl Default for EvBuilder {
fn default() -> Self {
Self {
battery_wh: Decimal::from(60_000),
soc: Decimal::from(20),
target_soc: Decimal::from(100),
floor_soc: Decimal::from(20),
phases: 3,
min_current: Decimal::from(6),
max_current: Decimal::from(16),
voltage: Decimal::from(230),
reaction: Duration::from_secs(2),
switching: PhaseSwitching::Follows {
pause: Duration::from_secs(5),
},
taper_above: None,
max_discharge: None,
departure: None,
}
}
}
impl EvBuilder {
#[must_use]
pub fn battery_wh(mut self, wh: impl Into<Decimal>) -> Self {
self.battery_wh = wh.into();
self
}
#[must_use]
pub fn soc(mut self, percent: impl Into<Decimal>) -> Self {
self.soc = percent.into();
self
}
#[must_use]
pub fn target_soc(mut self, percent: impl Into<Decimal>) -> Self {
self.target_soc = percent.into();
self
}
#[must_use]
pub fn phases(mut self, phases: u8) -> Self {
self.phases = phases;
self
}
#[must_use]
pub fn current(mut self, min: impl Into<Decimal>, max: impl Into<Decimal>) -> Self {
self.min_current = min.into();
self.max_current = max.into();
self
}
#[must_use]
pub fn voltage(mut self, volts: impl Into<Decimal>) -> Self {
self.voltage = volts.into();
self
}
#[must_use]
pub fn reaction(mut self, delay: Duration) -> Self {
self.reaction = delay;
self
}
#[must_use]
pub fn phase_switching(mut self, behaviour: PhaseSwitching) -> Self {
self.switching = behaviour;
self
}
#[must_use]
pub fn taper_above(mut self, percent: impl Into<Decimal>) -> Self {
self.taper_above = Some(percent.into());
self
}
#[must_use]
pub fn bidirectional(mut self, watts: impl Into<Decimal>) -> Self {
self.max_discharge = Some(watts.into());
self
}
#[must_use]
pub fn floor_soc(mut self, percent: impl Into<Decimal>) -> Self {
self.floor_soc = percent.into();
self
}
#[must_use]
pub fn departure(mut self, at: DateTime) -> Self {
self.departure = Some(at);
self
}
#[must_use]
pub fn build(self) -> Ev {
let percent = |value: Decimal, what: &str| {
assert!(
(Decimal::ZERO..=Decimal::from(100)).contains(&value),
"{what} must be 0–100 %, got {value}"
);
value
};
assert!((1..=3).contains(&self.phases), "phases must be 1, 2 or 3");
assert!(
self.min_current.signum() >= 0 && self.min_current <= self.max_current,
"the minimum current must be between 0 and the maximum"
);
assert!(self.voltage.signum() > 0, "the voltage must be positive");
assert!(
self.battery_wh.signum() > 0,
"the capacity must be positive"
);
if let Some(watts) = self.max_discharge {
magnitude(watts, "a discharge power");
}
if let Some(taper) = self.taper_above {
percent(taper, "the taper start");
}
let capacity = units(self.battery_wh, WH);
let share = |pct: Decimal| capacity * units(pct, 1_000_000) / 100_000_000;
Ev {
capacity,
target: share(percent(self.target_soc, "the target")),
floor: share(percent(self.floor_soc, "the floor")),
stored: share(percent(self.soc, "the state of charge")),
phases: self.phases,
min_current: self.min_current,
max_current: self.max_current,
voltage: self.voltage,
reaction: self.reaction,
switching: self.switching,
taper_above: self.taper_above,
max_discharge: self.max_discharge,
departure: self.departure,
plugged: false,
imported: 0,
exported: 0,
elapsed: 0,
applied: None,
pending: VecDeque::new(),
phases_in_use: self.phases,
switching_until: None,
faulted: false,
}
}
}
fn units(value: Decimal, per: i128) -> i128 {
let scale = u32::from(value.scale());
let mantissa = i128::from(value.mantissa()) * per;
let divisor = 10_i128.pow(scale);
(mantissa + divisor / 2 * mantissa.signum()) / divisor
}
fn thousandths(amount: i128, per: i128) -> Decimal {
let scaled = (amount * 1000 + per / 2 * amount.signum()) / per;
Decimal::new(i64::try_from(scaled).unwrap_or(i64::MAX), 3)
}
fn product(values: &[Decimal]) -> Option<Decimal> {
values
.iter()
.try_fold(Decimal::from(1), |acc, value| acc.checked_mul(*value))
}
impl Default for Ev {
fn default() -> Self {
EvBuilder::default().build()
}
}
impl Ev {
#[must_use]
pub fn builder() -> EvBuilder {
EvBuilder::default()
}
pub fn plug_in(&mut self) -> Result<(), EvError> {
if self.plugged {
return Err(EvError::AlreadyPlugged);
}
self.plugged = true;
self.applied = None;
self.pending.clear();
self.phases_in_use = self.phases;
self.switching_until = None;
self.faulted = false;
Ok(())
}
pub fn unplug(&mut self) -> Result<(), EvError> {
if !self.plugged {
return Err(EvError::NotPlugged);
}
self.plugged = false;
self.applied = None;
self.pending.clear();
self.switching_until = None;
self.faulted = false;
Ok(())
}
#[must_use]
pub fn is_plugged(&self) -> bool {
self.plugged
}
pub fn command(&mut self, command: Command) {
if !self.plugged {
return;
}
let due = self.elapsed + millis(self.reaction);
self.pending.retain(|(at, _)| *at < due);
self.pending.push_back((due, command));
self.apply_due();
}
#[must_use]
pub fn applied(&self) -> Option<Command> {
self.applied
}
pub fn advance(&mut self, by: Duration) {
let end = self.elapsed + millis(by);
while self.elapsed < end {
self.apply_due();
let mut until = end;
if let Some((at, _)) = self.pending.front() {
until = until.min(*at);
}
if let Some(at) = self.switching_until.filter(|at| *at > self.elapsed) {
until = until.min(at);
}
let (power, _, _) = self.operating_point();
if power > 0 && self.taper_above.is_some() {
until = until.min(self.elapsed + 1000);
}
let mut step = i128::from(until - self.elapsed);
let room = match power.signum() {
1 => self.target - self.stored,
-1 => self.stored - self.floor,
_ => 0,
};
if power != 0 {
step = step.min((room + power.abs() - 1) / power.abs()).max(1);
}
let energy = (power * step).clamp(-room.max(0), room.max(0));
self.stored += energy;
if energy > 0 {
self.imported += energy;
} else {
self.exported -= energy;
}
self.elapsed += u64::try_from(step).unwrap_or(u64::MAX);
if self.switching_until.is_some_and(|at| at <= self.elapsed) {
self.switching_until = None;
}
}
self.apply_due();
}
#[must_use]
pub fn reading(&self) -> Reading {
let (power, current, state) = self.operating_point();
let soc = Decimal::new(
i64::try_from(self.stored * 1000 / self.capacity).unwrap_or(0),
1,
)
.round_to(1)
.unwrap_or(Decimal::ZERO);
Reading {
power: thousandths(power, 1000).normalized(),
current,
phases: self.phases_in_use,
soc,
imported: thousandths(self.imported, WH),
exported: thousandths(self.exported, WH),
state,
}
}
#[must_use]
pub fn state(&self) -> EvState {
self.operating_point().2
}
#[must_use]
pub fn soc(&self) -> Decimal {
self.reading().soc
}
#[must_use]
pub fn energy_request(&self) -> Decimal {
thousandths((self.target - self.stored).max(0), WH).normalized()
}
#[must_use]
pub fn phases(&self) -> u8 {
self.phases
}
#[must_use]
pub fn current_range(&self) -> (Decimal, Decimal) {
(self.min_current, self.max_current)
}
#[must_use]
pub fn voltage(&self) -> Decimal {
self.voltage
}
#[must_use]
pub fn max_charge_power(&self) -> Decimal {
product(&[self.max_current, self.voltage, Decimal::from(self.phases)])
.unwrap_or(Decimal::ZERO)
}
#[must_use]
pub fn max_discharge_power(&self) -> Option<Decimal> {
self.max_discharge
}
#[must_use]
pub fn target_soc(&self) -> Decimal {
Decimal::new(
i64::try_from(self.target * 1000 / self.capacity).unwrap_or(0),
1,
)
}
#[must_use]
pub fn departure(&self) -> Option<DateTime> {
self.departure
}
fn apply_due(&mut self) {
while let Some((at, command)) = self.pending.front().copied() {
if at > self.elapsed {
break;
}
self.pending.pop_front();
let wanted = command.phases.unwrap_or(3).min(self.phases);
if self.applied.is_none() {
self.phases_in_use = wanted;
} else if wanted != self.phases_in_use {
match self.switching {
PhaseSwitching::Follows { pause } => {
self.phases_in_use = wanted;
self.switching_until = Some(at + millis(pause)).filter(|until| *until > at);
}
PhaseSwitching::StopsCharging => self.faulted = true,
}
}
self.applied = Some(command);
}
}
fn operating_point(&self) -> (i128, Decimal, EvState) {
let idle = |state| (0, Decimal::ZERO, state);
if !self.plugged {
return idle(EvState::Unplugged);
}
if self.faulted {
return idle(EvState::Faulted);
}
let Some(command) = self.applied else {
return idle(EvState::Connected);
};
if self.switching_until.is_some_and(|at| self.elapsed < at) {
return idle(EvState::SwitchingPhases);
}
let phases = Decimal::from(self.phases_in_use);
let per_phase = self.voltage.checked_mul(phases).unwrap_or(Decimal::ZERO);
let ceiling_watts = match command.ceiling {
None => None,
Some(Limit::Watts(w)) => Some(w),
Some(Limit::Amps(a)) => a.checked_mul(per_phase),
};
let max_current = self.tapered_max_current();
let max_charge = max_current.checked_mul(per_phase).unwrap_or(Decimal::ZERO);
let watts_to_amps = |watts: Decimal| {
watts
.checked_div(per_phase, 3)
.unwrap_or(Decimal::ZERO)
.normalized()
};
let draw = |watts: Decimal, state| {
let mw = units(watts, 1000);
(
mw,
watts_to_amps(watts.checked_abs().unwrap_or(watts)),
state,
)
};
match command.target {
Some(Power::Discharge(target)) => {
let Some(max) = self.max_discharge else {
return idle(EvState::SuspendedEv);
};
if self.stored <= self.floor {
return idle(EvState::SuspendedEv);
}
let mut watts = target.min(max);
if let Some(cap) = command.discharge_ceiling {
watts = watts.min(cap);
}
if watts.is_zero() {
return idle(EvState::SuspendedEvse);
}
draw(-watts, EvState::Discharging)
}
Some(Power::Charge(target)) => {
if self.stored >= self.target {
return idle(EvState::SuspendedEv);
}
let mut watts = target.min(max_charge);
if let Some(cap) = ceiling_watts {
watts = watts.min(cap);
}
if watts.is_zero() {
return idle(EvState::SuspendedEvse);
}
draw(watts, EvState::Charging)
}
None => {
if self.stored >= self.target {
return idle(EvState::SuspendedEv);
}
let offered = match command.ceiling {
None => max_current,
Some(Limit::Amps(a)) => a,
Some(Limit::Watts(w)) => watts_to_amps(w),
};
let current = offered.min(max_current);
if current < self.min_current || current.is_zero() {
return idle(EvState::SuspendedEvse);
}
let watts = current.checked_mul(per_phase).unwrap_or(Decimal::ZERO);
(units(watts, 1000), current.normalized(), EvState::Charging)
}
}
}
fn tapered_max_current(&self) -> Decimal {
let Some(start) = self.taper_above else {
return self.max_current;
};
let start = units(start, 1_000_000) * self.capacity / 100_000_000;
if self.stored <= start || self.capacity <= start {
return self.max_current;
}
let span = units(self.max_current - self.min_current, 1000);
let cut = span * (self.stored - start) / (self.capacity - start);
thousandths(units(self.max_current, 1000) - cut, 1000).normalized()
}
}
fn millis(duration: Duration) -> u64 {
u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
}
#[cfg(test)]
mod tests {
use super::*;
fn d(value: i64) -> Decimal {
Decimal::from(value)
}
fn secs(s: u64) -> Duration {
Duration::from_secs(s)
}
fn plugged(builder: EvBuilder) -> Ev {
let mut ev = builder.build();
ev.plug_in().unwrap();
ev
}
#[test]
fn it_follows_a_ceiling_after_its_reaction_delay() {
let mut ev = plugged(Ev::builder());
assert_eq!(ev.state(), EvState::Connected);
ev.command(Command::amps(16));
ev.advance(Duration::from_millis(1999));
assert_eq!(ev.reading().power, Decimal::ZERO, "not yet");
ev.advance(Duration::from_millis(1));
let reading = ev.reading();
assert_eq!(reading.power, d(11_040));
assert_eq!((reading.current, reading.phases), (d(16), 3));
assert_eq!(reading.state, EvState::Charging);
}
#[test]
fn an_hour_is_exact_however_many_steps_it_took() {
let mut ev = plugged(Ev::builder().reaction(Duration::ZERO));
ev.command(Command::amps(16));
for _ in 0..3600 {
ev.advance(secs(1));
}
assert_eq!(ev.reading().imported, Decimal::new(11_040_000, 3));
let mut once = plugged(Ev::builder().reaction(Duration::ZERO));
once.command(Command::amps(16));
once.advance(secs(3600));
assert_eq!(once.reading().imported, ev.reading().imported);
assert_eq!(ev.soc(), Decimal::new(384, 1));
}
#[test]
fn below_its_minimum_current_it_draws_nothing() {
let mut ev = plugged(Ev::builder().reaction(secs(2)));
ev.command(Command::amps(16));
ev.advance(secs(2));
ev.command(Command::amps(4));
ev.advance(secs(1));
assert_eq!(ev.reading().power, d(11_040), "still the old ceiling");
ev.advance(secs(1));
assert_eq!(ev.reading().power, Decimal::ZERO);
assert_eq!(ev.state(), EvState::SuspendedEvse);
ev.command(Command::watts(4140));
ev.advance(secs(2));
assert_eq!(ev.reading().current, d(6));
}
#[test]
fn a_phase_switch_costs_a_pause_or_stops_it() {
let mut ev = plugged(Ev::builder().reaction(Duration::ZERO));
ev.command(Command::amps(16));
ev.advance(secs(1));
ev.command(Command::amps(16).phases(1));
ev.advance(secs(4));
assert_eq!(ev.state(), EvState::SwitchingPhases);
assert_eq!(ev.reading().power, Decimal::ZERO);
ev.advance(secs(1));
assert_eq!((ev.reading().phases, ev.reading().power), (1, d(3680)));
let mut stuck = plugged(
Ev::builder()
.reaction(Duration::ZERO)
.phase_switching(PhaseSwitching::StopsCharging),
);
stuck.command(Command::amps(16));
stuck.advance(secs(1));
stuck.command(Command::amps(16).phases(1));
stuck.advance(secs(600));
assert_eq!(stuck.state(), EvState::Faulted);
stuck.command(Command::amps(16));
stuck.advance(secs(10));
assert_eq!(stuck.state(), EvState::Faulted, "until unplugged");
stuck.unplug().unwrap();
stuck.plug_in().unwrap();
stuck.command(Command::amps(16).phases(1));
stuck.advance(secs(1));
assert_eq!(
stuck.state(),
EvState::Charging,
"it starts on what it is offered"
);
let mut single = plugged(Ev::builder().phases(1).reaction(Duration::ZERO));
single.command(Command::amps(32));
single.advance(secs(1));
assert_eq!(
(single.reading().phases, single.reading().current),
(1, d(16))
);
}
#[test]
fn it_stops_at_its_target_exactly() {
let mut ev = plugged(
Ev::builder()
.battery_wh(10_000)
.soc(79)
.target_soc(80)
.reaction(Duration::ZERO),
);
ev.command(Command::unlimited());
ev.advance(secs(3600));
assert_eq!(ev.state(), EvState::SuspendedEv);
assert_eq!(ev.soc(), d(80));
assert_eq!(ev.reading().imported, d(100), "exactly 1 % of 10 kWh");
assert_eq!(ev.energy_request(), Decimal::ZERO);
}
#[test]
fn it_tapers_above_the_taper_start() {
let mut ev = plugged(
Ev::builder()
.battery_wh(10_000)
.soc(90)
.taper_above(80)
.reaction(Duration::ZERO),
);
ev.command(Command::unlimited());
ev.advance(Duration::from_millis(1));
assert_eq!(ev.reading().current, d(11));
}
#[test]
fn a_bidirectional_vehicle_discharges_to_its_floor() {
let mut ev = plugged(
Ev::builder()
.battery_wh(10_000)
.soc(25)
.floor_soc(20)
.bidirectional(5000)
.reaction(Duration::ZERO),
);
ev.command(Command::unlimited().target(Power::Discharge(d(3000))));
ev.advance(secs(1));
let reading = ev.reading();
assert_eq!(
(reading.power, reading.state),
(d(-3000), EvState::Discharging)
);
ev.advance(secs(3600));
assert_eq!(ev.state(), EvState::SuspendedEv);
assert_eq!(ev.soc(), d(20));
assert_eq!(ev.reading().exported, d(500));
ev.command(Command::unlimited().target(Power::Charge(d(2000))));
ev.advance(secs(1));
assert_eq!(ev.reading().power, d(2000));
ev.command(
Command::unlimited()
.target(Power::Discharge(d(3000)))
.discharge_at_most(1000),
);
ev.advance(secs(1));
assert_eq!(ev.reading().power, d(-1000));
let mut charge_only = plugged(Ev::builder().reaction(Duration::ZERO));
charge_only.command(Command::unlimited().target(Power::Discharge(d(3000))));
charge_only.advance(secs(1));
assert_eq!(charge_only.state(), EvState::SuspendedEv);
}
#[test]
fn plugging_is_checked_and_time_zero_changes_nothing() {
let mut ev = Ev::default();
assert_eq!(ev.unplug(), Err(EvError::NotPlugged));
ev.command(Command::amps(16));
assert!(
ev.applied().is_none(),
"a command to an unplugged vehicle is ignored"
);
ev.plug_in().unwrap();
assert_eq!(ev.plug_in(), Err(EvError::AlreadyPlugged));
let before = ev.reading();
ev.advance(Duration::ZERO);
assert_eq!(ev.reading(), before);
}
#[test]
#[should_panic(expected = "magnitude")]
fn a_negative_ceiling_is_a_programming_error() {
let _ = Command::amps(-1);
}
}