hoffmation-base 3.8.0 → 4.0.0

package/lib/settingsObjects/deviceSettings/victronDeviceSettings.js

@@ -1,8 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VictronDeviceSettings = void 0;
+exports.acceptedShare = acceptedShare;
+exports.reportImpossibleWindow = reportImpossibleWindow;
 const deviceSettings_1 = require("./deviceSettings");
 const utils_1 = require("../../utils");
+const logging_1 = require("../../logging");
+const enums_1 = require("../../enums");
+/**
+ * Takes over a setting that has to lie between 0 and 1, or keeps the value in force and reports the refusal.
+ *
+ * Kept rather than clamped, and that is the whole decision: 90 written for "90 percent" clamps to 1 and turns
+ * a dial nobody touched to its extreme - a coverage demanding every single reading of a day, a quantile at
+ * the maximum of the sample, a conversion factor that loses nothing at all. Each of those is a plausible
+ * looking number, and a plausible looking number is exactly the one an operator never goes looking for. The
+ * value in force is the documented default, the refused input is named in the log, and no unusable input
+ * quietly becomes a different plant.
+ *
+ * Deliberately loud rather than thrown: a settings file is read at startup, and one mistyped share must not
+ * cost the whole installation its automation.
+ *
+ * Lives here rather than on the settings base class only because of how this change was cut; it is shared by
+ * every settings class that carries a share and belongs next to them.
+ * @param name - The setting, so the log line names what was refused
+ * @param value - What was handed in, or undefined when the caller set nothing
+ * @param current - The value in force, kept whenever the input is unusable
+ * @returns - The value to use from now on
+ */
+function acceptedShare(name, value, current) {
+    if (value === undefined) {
+        return current;
+    }
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `Settings: ${name} of ${value} lies outside 0..1 --> refused, ${current} stays in force`);
+        return current;
+    }
+    return value;
+}
+/**
+ * Reports a history window shorter than the number of days the fit demands before it produces anything.
+ *
+ * Reported rather than corrected: which of the two numbers the operator meant cannot be told from here, and
+ * the combination is not dangerous - the fit simply never yields a band and the decision falls back to the
+ * rung that needs no history. Only nobody would ever see why it never got past that rung.
+ * @param windowDays - The length of the sliding window in days
+ * @param minimumDays - How many usable days the fit demands
+ */
+function reportImpossibleWindow(windowDays, minimumDays) {
+    if (windowDays >= minimumDays) {
+        return;
+    }
+    logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `Settings: historyWindowDays of ${windowDays} is shorter than historyMinimumDays of ${minimumDays} ` +
+        '--> the fit can never gather enough days and no band will be produced');
+}
 class VictronDeviceSettings extends deviceSettings_1.DeviceSettings {
     constructor() {
         super(...arguments);
@@ -53,6 +103,91 @@ class VictronDeviceSettings extends deviceSettings_1.DeviceSettings {
          * @default 10000
          */
         this.batteryCapacityWattage = 10000;
+        /**
+         * The share of the expected consumption readings a recorded day has to carry before its window sum is
+         * counted at all, between 0 and 1.
+         *
+         * A dial of the plant rather than of whoever reads its history: an incompletely covered night adds up to
+         * too little, therefore looks like a frugal night, pulls the quantile down and makes the resulting bound
+         * too optimistic - and two readers who disagree about what counts as a covered day of the same plant would
+         * be answering about two different plants. Deliberately strict, because a bound that is too optimistic
+         * suppresses, and a wrong suppression has no way back: the morning is simply below the reserve by then.
+         * @default 0.9
+         */
+        this.historyMinimumDayCoverage = 0.9;
+        /**
+         * The quantile of the recorded consumption windows a model free bound is calculated with, between 0 and 1.
+         * An upper quantile rather than the median, because the bound has to hold on a heavy night and not on half
+         * of them.
+         * @default 0.9
+         */
+        this.historyConsumptionQuantile = 0.9;
+        /**
+         * How many usable consumption window sums are needed before that quantile means anything at all.
+         *
+         * An upper quantile of one night is that night, and of two nights it sits all but on their maximum - so a
+         * single quiet night would yield a high bound and a suppression with nothing behind it. Deliberately its
+         * own number rather than a shared minimum with the day count a model fit needs: that one protects the
+         * stability of a fit, this one protects the meaning of a quantile.
+         * @default 10
+         */
+        this.historyMinimumConsumptionDays = 10;
+        /**
+         * The state of charge in percent the coming morning's low is expected to stay above.
+         *
+         * A property of the battery and therefore stated once, here: "how low may the morning get" is the same
+         * question whichever device asks it, and two numbers for one battery would let a plant judge one and the
+         * same morning twice. Where consumers legitimately differ is how sure they want to be before they act, and
+         * that is the split between the verdicts that need no model and the ones that do - see
+         * {@link iMorningReserveVerdict.measured}, not a second reserve.
+         *
+         * It is also the threshold the model shadow measures against, and a shadow whose sample is split across two
+         * thresholds measures nothing - see {@link ModelShadow}.
+         * @default 20
+         */
+        this.minimumMorningSocReserve = 20;
+        /**
+         * Below this many remaining sun hours no further photovoltaic yield is expected to change the coming
+         * morning.
+         *
+         * Plant wide next to the reserve, because it describes this installation's photovoltaic rather than whoever
+         * asks: the last half hour before sunset yields the same nothing for every consumer.
+         * @default 0.5
+         */
+        this.noSunThresholdHours = 0.5;
+        /**
+         * The length of the sliding window in days the history is read and fitted from. Older days describe a
+         * differently grown installation and are deliberately left out.
+         *
+         * Stated once for the whole plant, here, because it says how much of the recorded data is telling enough to
+         * answer with - a property of that data and not of whoever asks. Every consumer of the history asks the
+         * same question, and a second window meant a second read and a second paid backfill of the same days.
+         *
+         * The default is a starting point, not a finding: it has not been established against recorded data. In the
+         * back test the estimate gets monotonically worse the longer the window is, and a window of sixty days
+         * already scores worse than the trivial threshold rule. Treat this value as unproven until a run against
+         * the recorded history has produced a number.
+         * @default 90
+         */
+        this.historyWindowDays = 90;
+        /**
+         * How many usable historical days are needed before the weights are fitted at all. Below this number no
+         * band is produced at all and every consumer falls back to what needs no history.
+         *
+         * Plant wide for the same reason {@link historyWindowDays} is: how much evidence makes a fit meaningful is a
+         * property of the recorded data.
+         * @default 15
+         */
+        this.historyMinimumDays = 15;
+        /**
+         * How many standard deviations of the residuals each band edge lies away from the point estimate.
+         *
+         * Plant wide, because the band is part of the answer rather than of the judgement made on it. A consumer
+         * that one day wants edges of its own width reads {@link iEnergyHistoryOutlook.residualSigma} and forms
+         * them; it does not fit a second model.
+         * @default 1.0
+         */
+        this.historyBandSigma = 1.0;
         /**
          * The normal base consumption of the house in wattage
          * @default 600
@@ -73,7 +208,7 @@ class VictronDeviceSettings extends deviceSettings_1.DeviceSettings {
         this.excessEnergyTurnOffThreshold = 50;
     }
     fromPartialObject(data) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
         this.maxBatteryLoadWattage = (_a = data.maxBatteryLoadWattage) !== null && _a !== void 0 ? _a : this.maxBatteryLoadWattage;
         this.batteryReportingInterval = (_b = data.batteryReportingInterval) !== null && _b !== void 0 ? _b : this.batteryReportingInterval;
         this.hasBattery = (_c = data.hasBattery) !== null && _c !== void 0 ? _c : this.hasBattery;
@@ -86,10 +221,20 @@ class VictronDeviceSettings extends deviceSettings_1.DeviceSettings {
             (_h = data.minimumTransientTimeAcBatteryLevel) !== null && _h !== void 0 ? _h : this.minimumTransientTimeAcBatteryLevel;
         this.minimumDayTimeAcBatteryLevel = (_j = data.minimumDayTimeAcBatteryLevel) !== null && _j !== void 0 ? _j : this.minimumDayTimeAcBatteryLevel;
         this.batteryCapacityWattage = (_k = data.batteryCapacityWattage) !== null && _k !== void 0 ? _k : this.batteryCapacityWattage;
-        this.normalBaseConsumptionWattage = (_l = data.normalBaseConsumptionWattage) !== null && _l !== void 0 ? _l : this.normalBaseConsumptionWattage;
-        this.maximumBatteryDischargeWattage = (_m = data.maximumBatteryDischargeWattage) !== null && _m !== void 0 ? _m : this.maximumBatteryDischargeWattage;
-        this.excessEnergyTurnOnThreshold = (_o = data.excessEnergyTurnOnThreshold) !== null && _o !== void 0 ? _o : this.excessEnergyTurnOnThreshold;
-        this.excessEnergyTurnOffThreshold = (_p = data.excessEnergyTurnOffThreshold) !== null && _p !== void 0 ? _p : this.excessEnergyTurnOffThreshold;
+        this.historyMinimumDayCoverage = acceptedShare('historyMinimumDayCoverage', data.historyMinimumDayCoverage, this.historyMinimumDayCoverage);
+        this.historyConsumptionQuantile = acceptedShare('historyConsumptionQuantile', data.historyConsumptionQuantile, this.historyConsumptionQuantile);
+        this.historyMinimumConsumptionDays = (_l = data.historyMinimumConsumptionDays) !== null && _l !== void 0 ? _l : this.historyMinimumConsumptionDays;
+        this.minimumMorningSocReserve = (_m = data.minimumMorningSocReserve) !== null && _m !== void 0 ? _m : this.minimumMorningSocReserve;
+        this.noSunThresholdHours = (_o = data.noSunThresholdHours) !== null && _o !== void 0 ? _o : this.noSunThresholdHours;
+        this.historyWindowDays = (_p = data.historyWindowDays) !== null && _p !== void 0 ? _p : this.historyWindowDays;
+        this.historyMinimumDays = (_q = data.historyMinimumDays) !== null && _q !== void 0 ? _q : this.historyMinimumDays;
+        this.historyBandSigma = (_r = data.historyBandSigma) !== null && _r !== void 0 ? _r : this.historyBandSigma;
+        this.normalBaseConsumptionWattage = (_s = data.normalBaseConsumptionWattage) !== null && _s !== void 0 ? _s : this.normalBaseConsumptionWattage;
+        this.maximumBatteryDischargeWattage = (_t = data.maximumBatteryDischargeWattage) !== null && _t !== void 0 ? _t : this.maximumBatteryDischargeWattage;
+        this.excessEnergyTurnOnThreshold = (_u = data.excessEnergyTurnOnThreshold) !== null && _u !== void 0 ? _u : this.excessEnergyTurnOnThreshold;
+        this.excessEnergyTurnOffThreshold = (_v = data.excessEnergyTurnOffThreshold) !== null && _v !== void 0 ? _v : this.excessEnergyTurnOffThreshold;
+        // After both are taken over, because the two only contradict each other as a pair.
+        reportImpossibleWindow(this.historyWindowDays, this.historyMinimumDays);
         super.fromPartialObject(data);
     }
     toJSON() {