🥮 mooncakes.io

    voltweave

    Offline household energy scheduling and outage resilience simulation

    energy
    scheduler
    simulation
    wasm
    moonbit
    Download zip
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    last month
    Downloads
    7

    #VoltWeave（伏织）

    CI License MoonBit

    VoltWeave 是一个以 MoonBit 为主要实现语言、可离线运行的家庭用能调度与停电韧性仿真器。它把分时电价、碳排强度、屋顶光伏、家庭电池、固定或柔性电器以及停电事件放进同一套确定性模型，输出可执行计划、逐时能源流、风险区间和机器可读的决策解释。

    项目不控制真实电气设备，也不代替电工安全评估；它的边界是“规划、比较和仿真”。所有内置场景均在本地计算，无需云服务或外部 API。

    #为什么做 VoltWeave

    常见家庭能源项目偏向设备接入或实时看板；VoltWeave 专注于一个更明确的空白：在同一个离线内核中，同时处理电器时间窗、连续/可中断任务、配电功率上限、电池安全边界、停电保供优先级和不确定性复现，并给出稳定原因码。它不是 MoonBit 编译器、编辑器或包管理工具。

    #核心能力

    • 整数定点数据模型：功率 W、能量 Wh、金额微单位、效率千分比，跨后端结果可复现。
    • 约束调度：支持固定、可移峰、可中断、可放弃任务及四级保供优先级。
    • 储能调度：约束容量、充放电功率、效率、备用电量与停电期间的放电策略。
    • 多目标方案：费用、碳排、舒适度、韧性和电池损耗可配置，支持策略集与 Pareto 前沿。
    • 风险仿真：使用固定种子的确定性 PRNG 扰动光伏、基础负载及停电时段，输出分位数和风险等级。
    • 独立审计：重新检查数组形状、供需平衡、配电上限、停电约束、电池边界和任务时间窗。
    • 可解释输出：Markdown、CSV、ASCII 曲线、JSON 以及稳定的校验/审计原因码。
    • 双入口演示：MoonBit CLI 与浏览器 Wasm-GC 仪表盘，浏览器端不上传输入数据。

    #快速开始

    需要 MoonBit 工具链；本项目已用 moon 0.1.20260803 验证。

    git clone https://github.com/suqinxi/suqinxi.git
cd suqinxi
moon check --deny-warn
moon test -p sujy123456/voltweave --deny-warn
moon run cmd/voltweave -- demo

    常用命令：

    moon run cmd/voltweave -- compact       # 紧凑公寓场景
moon run cmd/voltweave -- outage        # 风暴停电场景
moon run cmd/voltweave -- compare       # 五种目标策略比较
moon run cmd/voltweave -- simulate      # 64 次确定性不确定性仿真
moon run cmd/voltweave -- validate      # 输入校验报告
moon run cmd/voltweave -- json          # JSON 计划结果
moon run cmd/voltweave -- input         # JSON 示例输入
moon run cmd/voltweave -- chart         # 终端功率曲线

    #浏览器 Wasm 演示

    moon build web/engine --target wasm-gc --release
cp _build/wasm-gc/release/build/web/engine/engine.wasm web/app/voltweave.wasm
python -m http.server 8765 --directory web/app

    访问 http://127.0.0.1:8765。Windows PowerShell 可用：

    Copy-Item _build/wasm-gc/release/build/web/engine/engine.wasm web/app/voltweave.wasm
python -m http.server 8765 --directory web/app

    仓库提交了一个可直接演示的 Wasm 构建产物；源代码仍是唯一可信来源，发布前应重新执行上述构建。

    #项目结构

    domain.mbt             领域类型、JSON 合约与单位约定
validation.mbt         输入校验、稳定错误码与建议
optimizer.mbt          候选搜索、任务调度、电池能源流和 Pareto 比较
simulation.mbt         可复现采样、分布统计与敏感性分析
analytics.mbt          独立结果审计、资源充足性与方案差异
report.mbt             Markdown、CSV、ASCII 报告
examples.mbt           三组可运行场景
cmd/voltweave/         MoonBit CLI
web/engine/            Wasm-GC 外部接口
web/app/               离线单页演示
docs/                  架构、使用、测试和发布文档

    #测试与构建

    moon fmt --check
moon check --deny-warn
moon test -p sujy123456/voltweave --deny-warn
moon build cmd/voltweave --target wasm --release
moon check web/engine --target wasm-gc --deny-warn
moon build web/engine --target wasm-gc --release
moon publish --dry-run

    目前包含 46 个可运行测试，覆盖模型序列化、校验、任务放置、电池流、停电约束、仿真可复现性、分位数、报告以及独立审计。为什么测试命令显式限定根包，见 docs/TESTING.md。

    #文档与发布

    #功能边界与限制

    • 当前求解器是确定性有界搜索与启发式调度，不声称得到全局最优解。
    • 输入时间序列必须使用同一时间粒度；内置示例为 60 分钟、24 个时段。
    • 仿真结果用于比较相对风险，不是天气预测、财务承诺或电气安全证明。
    • 浏览器演示公开的是预编译内置场景；完整自定义 JSON 流程通过 MoonBit 库和 CLI 完成。

    #许可证

    Copyright 2026 苏琴茜。项目按 Apache License 2.0 开源。当前运行时代码没有第三方包依赖；许可证与素材核验结果见 docs/OPEN_SOURCE_REVIEW.md。

    AdequacyProfile

    source
    pub(all) struct AdequacyProfile {
      total_demand_wh : Int
      total_solar_wh : Int
      usable_battery_wh : Int
      outage_demand_wh : Int
      outage_solar_wh : Int
      outage_storage_margin_wh : Int
      peak_requested_w : Int
      weakest_supply_margin_w : Int
      weakest_supply_slot : Int
      critical_task_energy_wh : Int
      flexible_task_energy_wh : Int
      risk_codes : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Capacity and outage adequacy indicators computed before optimization.

    AdequacyProfile::to_json_string

    source
    fn AdequacyProfile::to_json_string(self : AdequacyProfile) -> String

    AuditFinding

    source
    pub(all) struct AuditFinding {
      code : String
      severity : AuditSeverity
      subject : String
      message : String
      slot : Int?
      expected : Int?
      actual : Int?
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A stable, machine-readable audit result. Codes are intentionally kept separate from prose so downstream applications do not parse messages.

    AuditFinding::new

    source
    fn AuditFinding::new(code : String, severity : AuditSeverity, subject : String, message : String, slot? : Int, expected? : Int, actual? : Int) -> AuditFinding

    AuditSeverity

    source
    pub(all) enum AuditSeverity {
      AuditInfo
      AuditWarning
      AuditError
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Severity used by the independent result auditor.

    AuditSeverity::label

    source
    fn AuditSeverity::label(self : AuditSeverity) -> String

    AuditSummary

    source
    pub(all) struct AuditSummary {
      passed : Bool
      error_count : Int
      warning_count : Int
      info_count : Int
      maximum_balance_residual_w : Int
      maximum_grid_excess_w : Int
      minimum_battery_state_wh : Int
      maximum_battery_state_wh : Int
      findings : Array[AuditFinding]
      balances : Array[EnergyBalanceRow]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    AuditSummary::has_code

    source
    fn AuditSummary::has_code(self : AuditSummary, code : String) -> Bool

    AuditSummary::to_json_string

    source
    fn AuditSummary::to_json_string(self : AuditSummary) -> String

    BatterySpec

    source
    pub(all) struct BatterySpec {
      name : String
      capacity_wh : Int
      initial_wh : Int
      reserve_wh : Int
      minimum_wh : Int
      maximum_wh : Int
      maximum_charge_w : Int
      maximum_discharge_w : Int
      charge_efficiency_permille : Int
      discharge_efficiency_permille : Int
      cycle_cost_micro_per_kwh : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Battery characteristics use watt-hours, watts, and permille efficiencies.

    BatterySpec::clamp_state

    source
    fn BatterySpec::clamp_state(self : BatterySpec, state_wh : Int) -> Int

    BatterySpec::new

    source
    fn BatterySpec::new(name : String, capacity_wh : Int, initial_wh : Int, reserve_wh : Int, maximum_charge_w : Int, maximum_discharge_w : Int) -> BatterySpec

    BatterySpec::state_permille

    source
    fn BatterySpec::state_permille(self : BatterySpec, state_wh : Int) -> Int

    BatterySpec::usable_wh

    source
    fn BatterySpec::usable_wh(self : BatterySpec) -> Int

    BatteryStep

    source
    pub(all) struct BatteryStep {
      slot : Int
      state_before_wh : Int
      power_w : Int
      state_after_wh : Int
      source : String
      reason : String
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Positive battery power means charging; negative means discharging.

    BatteryStep::charged_wh

    source
    fn BatteryStep::charged_wh(self : BatteryStep) -> Int

    BatteryStep::discharged_wh

    source
    fn BatteryStep::discharged_wh(self : BatteryStep) -> Int

    CandidatePlacement

    source
    pub(all) struct CandidatePlacement {
      task_id : String
      start_slot : Int
      end_slot : Int
      energy_cost_component : Int
      carbon_component : Int
      comfort_component : Int
      resilience_component : Int
      capacity_excess_w : Int
      solar_overlap_wh : Int
      total_score : Int
      feasible : Bool
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Diagnostic score for a candidate task placement.

    CandidatePlacement::duration_slots

    source
    fn CandidatePlacement::duration_slots(self : CandidatePlacement) -> Int

    DispatchResult

    source
    type DispatchResult derive(
    Debug    )

    DistributionSummary

    source
    pub(all) struct DistributionSummary {
      minimum : Int
      p10 : Int
      median : Int
      p90 : Int
      p95 : Int
      maximum : Int
      mean : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    EnergyBalanceRow

    source
    pub(all) struct EnergyBalanceRow {
      slot : Int
      demand_w : Int
      served_demand_w : Int
      grid_w : Int
      solar_w : Int
      battery_charge_w : Int
      battery_discharge_w : Int
      unserved_w : Int
      supply_w : Int
      accounted_use_w : Int
      residual_w : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Per-slot reconstruction of supply, demand, storage, and residual energy.

    EnergyBalanceRow::is_balanced

    source
    fn EnergyBalanceRow::is_balanced(self : EnergyBalanceRow, tolerance_w? : Int) -> Bool

    Explanation

    source
    pub(all) struct Explanation {
      code : String
      severity : String
      subject : String
      message : String
      slot : Int?
      evidence : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A machine-readable explanation tied to a plan decision.

    Explanation::info

    source
    fn Explanation::info(code : String, subject : String, message : String, slot? : Int) -> Explanation

    Explanation::warning

    source
    fn Explanation::warning(code : String, subject : String, message : String, slot? : Int) -> Explanation

    IntSeries

    source
    pub(all) struct IntSeries {
      name : String
      unit : String
      slot_minutes : Int
      values : Array[Int]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A regular time grid represented using integer values.

    Values are deliberately unit-agnostic so the same type can carry prices, carbon intensity, solar power, or a capacity limit.

    IntSeries::at

    source
    fn IntSeries::at(self : IntSeries, slot : Int) -> Int

    IntSeries::average

    source
    fn IntSeries::average(self : IntSeries) -> Int

    IntSeries::copy_values

    source
    fn IntSeries::copy_values(self : IntSeries) -> Array[Int]

    IntSeries::length

    source
    fn IntSeries::length(self : IntSeries) -> Int

    IntSeries::maximum

    source
    fn IntSeries::maximum(self : IntSeries) -> Int

    IntSeries::minimum

    source
    fn IntSeries::minimum(self : IntSeries) -> Int

    IntSeries::new

    source
    fn IntSeries::new(name : String, unit : String, slot_minutes : Int, values : Array[Int]) -> IntSeries

    IntSeries::scale_permille

    source
    fn IntSeries::scale_permille(self : IntSeries, factor_permille : Int) -> IntSeries

    IntSeries::sum

    source
    fn IntSeries::sum(self : IntSeries) -> Int

    IntSeries::with_value

    source
    fn IntSeries::with_value(self : IntSeries, slot : Int, value : Int) -> IntSeries

    IssueLevel

    source
    pub(all) enum IssueLevel {
      Error
      Warning
      Advice
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    IssueLevel::label

    source
    fn IssueLevel::label(self : IssueLevel) -> String

    LoadTask

    source
    pub(all) struct LoadTask {
      id : String
      name : String
      mode : TaskMode
      priority : Priority
      power_w : Int
      duration_slots : Int
      earliest_start : Int
      latest_end : Int
      preferred_start : Int
      fixed_start : Int
      minimum_run_slots : Int
      maximum_interruptions : Int
      comfort_penalty_per_slot : Int
      skip_penalty : Int
      tags : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A schedulable household load.

    LoadTask::energy_wh

    source
    fn LoadTask::energy_wh(self : LoadTask, slot_minutes : Int) -> Int

    LoadTask::fixed

    source
    fn LoadTask::fixed(id : String, name : String, power_w : Int, duration_slots : Int, fixed_start : Int, priority? : Priority) -> LoadTask

    LoadTask::interruptible

    source
    fn LoadTask::interruptible(id : String, name : String, power_w : Int, duration_slots : Int, earliest_start : Int, latest_end : Int, preferred_start : Int, maximum_interruptions : Int, priority? : Priority) -> LoadTask

    LoadTask::is_required

    source
    fn LoadTask::is_required(self : LoadTask) -> Bool

    LoadTask::latest_start

    source
    fn LoadTask::latest_start(self : LoadTask) -> Int

    LoadTask::optional

    source
    fn LoadTask::optional(id : String, name : String, power_w : Int, duration_slots : Int, earliest_start : Int, latest_end : Int, preferred_start : Int, priority? : Priority) -> LoadTask

    LoadTask::shiftable

    source
    fn LoadTask::shiftable(id : String, name : String, power_w : Int, duration_slots : Int, earliest_start : Int, latest_end : Int, preferred_start : Int, priority? : Priority) -> LoadTask

    LoadTask::window_slots

    source
    fn LoadTask::window_slots(self : LoadTask) -> Int

    LoadTask::with_tag

    source
    fn LoadTask::with_tag(self : LoadTask, tag : String) -> LoadTask

    ObjectiveWeights

    source
    pub(all) struct ObjectiveWeights {
      cost : Int
      carbon : Int
      comfort : Int
      resilience : Int
      battery_wear : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Integer weights make scoring deterministic across all MoonBit backends.

    ObjectiveWeights::balanced

    source

    ObjectiveWeights::for_policy

    source

    ObjectiveWeights::normalized

    source

    ObjectiveWeights::total

    source
    fn ObjectiveWeights::total(self : ObjectiveWeights) -> Int

    OutageEvent

    source
    pub(all) struct OutageEvent {
      id : String
      start_slot : Int
      end_slot : Int
      grid_limit_w : Int
      reserve_override_wh : Int?
      description : String
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    An interval where the public grid is unavailable or capped.

    OutageEvent::blackout

    source
    fn OutageEvent::blackout(id : String, start_slot : Int, end_slot : Int, description? : String) -> OutageEvent

    OutageEvent::contains

    source
    fn OutageEvent::contains(self : OutageEvent, slot : Int) -> Bool

    OutageEvent::duration_slots

    source
    fn OutageEvent::duration_slots(self : OutageEvent) -> Int

    PlanComparison

    source
    pub(all) struct PlanComparison {
      baseline : PlanResult
      optimized : PlanResult
      cost_saving_micro : Int
      carbon_saving_g : Int
      peak_reduction_w : Int
      resilience_gain_permille : Int
      recommendation : String
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    PlanDelta

    source
    pub(all) struct PlanDelta {
      baseline_title : String
      candidate_title : String
      cost_delta_micro : Int
      carbon_delta_g : Int
      peak_delta_w : Int
      unserved_delta_wh : Int
      critical_unserved_delta_wh : Int
      resilience_delta_permille : Int
      comfort_delta : Int
      completed_task_delta : Int
      candidate_dominates : Bool
      baseline_dominates : Bool
      tradeoff_count : Int
      summary : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A compact comparison between two valid optimizer outputs.

    PlanDelta::to_json_string

    source
    fn PlanDelta::to_json_string(self : PlanDelta) -> String

    PlanMetrics

    source
    pub(all) struct PlanMetrics {
      imported_energy_wh : Int
      exported_energy_wh : Int
      solar_used_wh : Int
      solar_curtailed_wh : Int
      battery_charged_wh : Int
      battery_discharged_wh : Int
      cost_micro : Int
      export_credit_micro : Int
      carbon_g : Int
      comfort_penalty : Int
      unserved_energy_wh : Int
      critical_unserved_wh : Int
      completed_tasks : Int
      skipped_tasks : Int
      peak_grid_w : Int
      resilience_permille : Int
      score : Int64
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Aggregate objective values. Money is stored in micro currency units.

    PlanMetrics::empty

    source
    fn PlanMetrics::empty() -> PlanMetrics

    PlanMetrics::net_cost_micro

    source
    fn PlanMetrics::net_cost_micro(self : PlanMetrics) -> Int

    PlanMetrics::served_energy_wh

    source
    fn PlanMetrics::served_energy_wh(self : PlanMetrics) -> Int

    PlanResult

    source
    pub(all) struct PlanResult {
      title : String
      status : PlanStatus
      slot_minutes : Int
      horizon_slots : Int
      schedule : Array[ScheduleEntry]
      battery_steps : Array[BatteryStep]
      load_w : Array[Int]
      grid_w : Array[Int]
      solar_used_w : Array[Int]
      unserved_w : Array[Int]
      battery_state_wh : Array[Int]
      skipped_task_ids : Array[String]
      metrics : PlanMetrics
      explanations : Array[Explanation]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Full optimizer output used by the CLI, web demo, and JSON API.

    PlanResult::empty

    source
    fn PlanResult::empty(title : String, slots : Int, slot_minutes : Int) -> PlanResult

    PlanResult::entry_for

    source
    fn PlanResult::entry_for(self : PlanResult, task_id : String) -> ScheduleEntry?

    PlanResult::grid_peak_slot

    source
    fn PlanResult::grid_peak_slot(self : PlanResult) -> Int

    PlanResult::is_task_scheduled

    source
    fn PlanResult::is_task_scheduled(self : PlanResult, task_id : String) -> Bool

    PlanResult::to_json_string

    source
    fn PlanResult::to_json_string(self : PlanResult) -> String

    PlanResult::total_unserved_wh

    source
    fn PlanResult::total_unserved_wh(self : PlanResult) -> Int

    PlanStatus

    source
    pub(all) enum PlanStatus {
      Feasible
      FeasibleWithCurtailment
      Infeasible
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    PlanStatus::label

    source
    fn PlanStatus::label(self : PlanStatus) -> String

    PlanningInput

    source
    pub(all) struct PlanningInput {
      title : String
      slot_minutes : Int
      horizon_slots : Int
      tariff_micro_per_kwh : IntSeries
      carbon_g_per_kwh : IntSeries
      solar_w : IntSeries
      base_load_w : IntSeries
      grid_limit_w : IntSeries
      tasks : Array[LoadTask]
      battery : BatterySpec?
      outages : Array[OutageEvent]
      weights : ObjectiveWeights
      allow_grid_export : Bool
      export_credit_micro_per_kwh : Int
      random_seed : UInt
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Complete input contract for the optimizer.

    PlanningInput::empty

    source
    fn PlanningInput::empty(title : String, slots : Int) -> PlanningInput

    PlanningInput::grid_limit_at

    source
    fn PlanningInput::grid_limit_at(self : PlanningInput, slot : Int) -> Int

    PlanningInput::has_outage_at

    source
    fn PlanningInput::has_outage_at(self : PlanningInput, slot : Int) -> Bool

    PlanningInput::to_json_string

    source
    fn PlanningInput::to_json_string(self : PlanningInput) -> String

    PlanningInput::total_solar_energy_wh

    source
    fn PlanningInput::total_solar_energy_wh(self : PlanningInput) -> Int

    PlanningInput::total_task_energy_wh

    source
    fn PlanningInput::total_task_energy_wh(self : PlanningInput) -> Int

    PlanningInput::with_outage

    source
    fn PlanningInput::with_outage(self : PlanningInput, outage : OutageEvent) -> PlanningInput

    PlanningInput::with_task

    source
    fn PlanningInput::with_task(self : PlanningInput, task : LoadTask) -> PlanningInput

    PlanningPolicy

    source
    pub(all) enum PlanningPolicy {
      Balanced
      LowestCost
      LowestCarbon
      HighestComfort
      HighestResilience
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Policy used when several valid plans are available.

    PlanningPolicy::label

    source
    fn PlanningPolicy::label(self : PlanningPolicy) -> String

    Priority

    source
    pub(all) enum Priority {
      Critical
      High
      Normal
      Low
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Relative importance of a task during normal and outage operation.

    Priority::label

    source
    fn Priority::label(self : Priority) -> String

    Priority::rank

    source
    fn Priority::rank(self : Priority) -> Int

    RiskBand

    source
    pub(all) enum RiskBand {
      LowRisk
      ModerateRisk
      HighRisk
      CriticalRisk
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    RiskBand::label

    source
    fn RiskBand::label(self : RiskBand) -> String

    ScenarioSample

    source
    pub(all) struct ScenarioSample {
      index : Int
      seed : UInt
      solar_factor_permille : Int
      base_load_factor_permille : Int
      tariff_factor_permille : Int
      largest_spike_slot : Int
      largest_spike_w : Int
      outage_start_slots : Array[Int]
      outage_duration_slots : Array[Int]
      input : PlanningInput
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    ScheduleEntry

    source
    pub(all) struct ScheduleEntry {
      task_id : String
      task_name : String
      start_slot : Int
      end_slot : Int
      power_w : Int
      energy_wh : Int
      priority : Priority
      reason : String
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    A chosen execution interval. Interruptible tasks may have several entries.

    ScheduleEntry::contains

    source
    fn ScheduleEntry::contains(self : ScheduleEntry, slot : Int) -> Bool

    ScheduleEntry::duration_slots

    source
    fn ScheduleEntry::duration_slots(self : ScheduleEntry) -> Int

    SensitivityCase

    source
    pub(all) struct SensitivityCase {
      id : String
      label : String
      changed_parameter : String
      change_permille : Int
      status : PlanStatus
      metrics : PlanMetrics
      delta_cost_micro : Int
      delta_carbon_g : Int
      delta_unserved_wh : Int
      delta_resilience_permille : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    SimulationRun

    source
    pub(all) struct SimulationRun {
      index : Int
      seed : UInt
      solar_factor_permille : Int
      base_load_factor_permille : Int
      tariff_factor_permille : Int
      largest_spike_slot : Int
      largest_spike_w : Int
      outage_duration_slots : Array[Int]
      status : PlanStatus
      metrics : PlanMetrics
      scheduled_tasks : Int
      explanation_count : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    SimulationRun::from_sample

    source
    fn SimulationRun::from_sample(sample : ScenarioSample, result : PlanResult) -> SimulationRun

    SimulationSummary

    source
    pub(all) struct SimulationSummary {
      title : String
      requested_runs : Int
      completed_runs : Int
      feasible_runs : Int
      infeasible_runs : Int
      risk_band : RiskBand
      cost_micro : DistributionSummary
      carbon_g : DistributionSummary
      unserved_energy_wh : DistributionSummary
      critical_unserved_wh : DistributionSummary
      peak_grid_w : DistributionSummary
      resilience_permille : DistributionSummary
      worst_run_index : Int
      best_run_index : Int
      runs : Array[SimulationRun]
      recommendations : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    SimulationSummary::feasibility_permille

    source
    fn SimulationSummary::feasibility_permille(self : SimulationSummary) -> Int

    SimulationSummary::to_json_string

    source
    fn SimulationSummary::to_json_string(self : SimulationSummary) -> String

    SolverConfig

    source
    pub(all) struct SolverConfig {
      maximum_candidates_per_task : Int
      prefer_solar : Bool
      allow_grid_charging : Bool
      preserve_reserve_outside_outage : Bool
      capacity_violation_penalty : Int
      outage_violation_penalty : Int
      optional_skip_threshold : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Runtime limits and deterministic heuristics for the scheduler.

    SolverConfig::default

    source
    fn SolverConfig::default() -> SolverConfig

    TaskMode

    source
    pub(all) enum TaskMode {
      Fixed
      Shiftable
      Interruptible
      Optional
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Scheduling semantics for a household task.

    TaskMode::is_flexible

    source
    fn TaskMode::is_flexible(self : TaskMode) -> Bool

    TaskMode::label

    source
    fn TaskMode::label(self : TaskMode) -> String

    TaskMode::may_skip

    source
    fn TaskMode::may_skip(self : TaskMode) -> Bool

    UncertaintyConfig

    source
    pub(all) struct UncertaintyConfig {
      solar_min_permille : Int
      solar_max_permille : Int
      base_load_min_permille : Int
      base_load_max_permille : Int
      tariff_min_permille : Int
      tariff_max_permille : Int
      outage_start_jitter_slots : Int
      outage_duration_jitter_slots : Int
      temporary_spike_probability_permille : Int
      temporary_spike_min_w : Int
      temporary_spike_max_w : Int
      correlated_signal_permille : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Bounds for deterministic uncertainty sampling, expressed in permille.

    UncertaintyConfig::conservative

    source
    fn UncertaintyConfig::conservative() -> UncertaintyConfig

    UncertaintyConfig::none

    source

    UncertaintyConfig::typical

    source

    ValidationCode

    source
    pub(all) enum ValidationCode {
      InvalidHorizon
      InvalidSlotMinutes
      SeriesLengthMismatch
      SeriesSlotMismatch
      NegativeSeriesValue
      InvalidTaskId
      DuplicateTaskId
      InvalidTaskPower
      InvalidTaskDuration
      InvalidTaskWindow
      FixedTaskOutsideWindow
      InvalidInterruptionRule
      InvalidBatteryCapacity
      InvalidBatteryState
      InvalidBatteryPower
      InvalidBatteryEfficiency
      InvalidBatteryReserve
      InvalidOutageWindow
      InvalidGridLimit
      InvalidObjectiveWeights
      ImpossibleRequiredTask
      PeakCapacityRisk
      MissingTariffVariation
      MissingCarbonVariation
      ExportWithoutCredit
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Stable validation codes suitable for CLI and web clients.

    ValidationCode::label

    source
    fn ValidationCode::label(self : ValidationCode) -> String

    ValidationIssue

    source
    pub(all) struct ValidationIssue {
      code : ValidationCode
      level : IssueLevel
      path : String
      message : String
      hint : String
      slot : Int?
      task_id : String?
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    ValidationIssue::advice

    source
    fn ValidationIssue::advice(code : ValidationCode, path : String, message : String, hint : String) -> ValidationIssue

    ValidationIssue::at_slot

    source
    fn ValidationIssue::at_slot(self : ValidationIssue, slot : Int) -> ValidationIssue

    ValidationIssue::error

    source
    fn ValidationIssue::error(code : ValidationCode, path : String, message : String, hint? : String) -> ValidationIssue

    ValidationIssue::for_task

    source
    fn ValidationIssue::for_task(self : ValidationIssue, task_id : String) -> ValidationIssue

    ValidationIssue::warning

    source
    fn ValidationIssue::warning(code : ValidationCode, path : String, message : String, hint? : String) -> ValidationIssue

    ValidationReport

    source
    pub(all) struct ValidationReport {
      issues : Array[ValidationIssue]
      checked_tasks : Int
      checked_slots : Int
      estimated_required_peak_w : Int
      estimated_required_energy_wh : Int
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    ValidationReport::advice_count

    source
    fn ValidationReport::advice_count(self : ValidationReport) -> Int

    ValidationReport::empty

    source

    ValidationReport::error_count

    source
    fn ValidationReport::error_count(self : ValidationReport) -> Int

    ValidationReport::has_code

    source
    fn ValidationReport::has_code(self : ValidationReport, code : ValidationCode) -> Bool

    ValidationReport::is_valid

    source
    fn ValidationReport::is_valid(self : ValidationReport) -> Bool

    ValidationReport::messages

    source
    fn ValidationReport::messages(self : ValidationReport) -> Array[String]

    ValidationReport::warning_count

    source
    fn ValidationReport::warning_count(self : ValidationReport) -> Int

    apply_safe_defaults

    source
    fn apply_safe_defaults(input : PlanningInput) -> PlanningInput

    Return a repaired copy for safe, explicitly documented defaults. Structural errors such as impossible windows are intentionally not hidden.

    assess_adequacy

    source
    fn assess_adequacy(input : PlanningInput) -> AdequacyProfile

    Estimate resource adequacy before scheduling. This deliberately reports a conservative envelope rather than claiming that aggregate energy guarantees a feasible schedule.

    audit_markdown

    source
    fn audit_markdown(summary : AuditSummary) -> String

    audit_plan

    source
    fn audit_plan(input : PlanningInput, result : PlanResult, balance_tolerance_w? : Int) -> AuditSummary

    Independently audit a plan against its original input. The auditor does not call the optimizer and therefore also catches regression defects in solve().

    built_in_examples

    source
    fn built_in_examples() -> Array[(String, PlanningInput)]

    All built-in examples with stable identifiers.

    candidate_placements

    source
    fn candidate_placements(input : PlanningInput, task : LoadTask, current_load_w : Array[Int], config? : SolverConfig) -> Array[CandidatePlacement]

    capability_summary

    source
    fn capability_summary() -> String

    Short capability summary used by smoke tests and package documentation.

    compact_apartment_example

    source
    fn compact_apartment_example() -> PlanningInput

    Small apartment without solar or storage.

    compare_plans

    source
    fn compare_plans(baseline : PlanResult, candidate : PlanResult) -> PlanDelta

    Compare plans using decision-facing deltas rather than their weighted score, because scores from different objective policies are not directly comparable.

    compare_with_baseline

    source
    fn compare_with_baseline(input : PlanningInput, config? : SolverConfig) -> PlanComparison

    comparison_markdown

    source
    fn comparison_markdown(comparison : PlanComparison) -> String

    evaluate_candidate

    source
    fn evaluate_candidate(input : PlanningInput, task : LoadTask, start_slot : Int, current_load_w : Array[Int], config? : SolverConfig) -> CandidatePlacement

    Evaluate a contiguous placement against the current provisional load.

    example_by_id

    source
    fn example_by_id(id : String) -> PlanningInput?

    format_energy_wh

    source
    fn format_energy_wh(value : Int) -> String

    format_money_micro

    source
    fn format_money_micro(value : Int) -> String

    format_slot

    source
    fn format_slot(slot : Int, slot_minutes : Int) -> String

    home_day_example

    source
    fn home_day_example() -> PlanningInput

    Full household example used by the CLI, README, and web engine.

    most_influential_case

    source
    fn most_influential_case(cases : Array[SensitivityCase]) -> SensitivityCase?

    pareto_frontier

    source
    fn pareto_frontier(results : Array[(PlanningPolicy, PlanResult)]) -> Array[(PlanningPolicy, PlanResult)]

    Remove policy results that are worse on every reported objective.

    plan_ascii_chart

    source
    fn plan_ascii_chart(result : PlanResult, width? : Int) -> String

    plan_csv

    source
    fn plan_csv(result : PlanResult) -> String

    plan_markdown

    source
    fn plan_markdown(result : PlanResult) -> String

    Render a complete review-friendly Markdown plan report.

    plan_result_from_json

    source
    fn plan_result_from_json(source : String) -> PlanResult raise

    plan_timeline

    source
    fn plan_timeline(result : PlanResult) -> String

    planning_input_from_json

    source
    fn planning_input_from_json(source : String) -> PlanningInput raise

    project_name

    source
    let project_name : String

    Human-readable project name.

    reconstruct_energy_balance

    source
    fn reconstruct_energy_balance(result : PlanResult) -> Array[EnergyBalanceRow]

    sample_scenario

    source
    fn sample_scenario(input : PlanningInput, config : UncertaintyConfig, index : Int) -> ScenarioSample

    Generate a single reproducible uncertainty sample.

    sensitivity_analysis

    source
    fn sensitivity_analysis(input : PlanningInput) -> Array[SensitivityCase]

    Evaluate transparent one-at-a-time changes for key planning assumptions.

    simulate

    source
    fn simulate(input : PlanningInput, runs? : Int, uncertainty? : UncertaintyConfig, solver_config? : SolverConfig) -> SimulationSummary

    Run reproducible scenario analysis. Each sample is derived from the input seed.

    simulation_markdown

    source
    fn simulation_markdown(summary : SimulationSummary) -> String

    solve

    source
    fn solve(original_input : PlanningInput, config? : SolverConfig) -> PlanResult

    Produce a deterministic energy plan for a validated input.

    solve_policy_set

    source
    fn solve_policy_set(input : PlanningInput, config? : SolverConfig) -> Array[(PlanningPolicy, PlanResult)]

    Solve the same scenario for all supported policies.

    solve_preferred_baseline

    source
    fn solve_preferred_baseline(input : PlanningInput) -> PlanResult

    Create a simple preferred-time baseline without changing the input contract.

    storm_outage_example

    source
    fn storm_outage_example() -> PlanningInput

    Household storm scenario with a six-hour evening blackout.

    summarize_distribution

    source
    fn summarize_distribution(values : Array[Int]) -> DistributionSummary

    validate

    source
    fn validate(input : PlanningInput) -> ValidationReport

    Validate a complete planning request without modifying it.

    validation_markdown

    source
    fn validation_markdown(report : ValidationReport) -> String

    version

    source
    let version : String

    Semantic version exposed by the library and CLI.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io