loadcast 0.1.1__py3-none-any.whl

loadcast/__init__.py

@@ -0,0 +1,94 @@
+"""loadcast -- synthetic multi-carrier industrial energy demand.
+
+Hourly heat, cold and electricity demand for an industrial site, from the
+handful of numbers someone actually knows about a plant: how much energy it uses
+in a year, roughly how much more heat than cold it wants, how much of the
+total is electricity, and whether the process runs continuously, in shifts or in
+batches.
+
+    import loadcast
+
+    profiles = loadcast.generate(
+        annual_mwh=10_000,
+        heat_to_cold=7.4,
+        elec_share=0.20,
+        process_class="semi_continuous",
+    )
+
+What makes it different
+-----------------------
+Existing tools either produce deterministic profiles or leave the relationship
+between carriers to fall out of whatever drives them. Both give carriers that
+move in lockstep, which is an artefact of the construction rather than a
+property of industry -- and for anything with storage, *whether the carriers
+peak together* is precisely what decides how much buffering is needed.
+
+loadcast makes that relationship an explicit input. `carrier_correlation` sets
+how tightly the carriers move together and `carrier_lag_h` sets how far apart
+they are offset, so a study can sweep coincidence rather than inherit it.
+
+What it does not do
+-------------------
+It carries energy by carrier, not temperature: whether a machine can *reach* a
+given process is a separate question, answered from the machine's own limits.
+And the parameters are yours to choose. Defaults are indicative values with a
+stated provenance, not predictions about any real site -- results are meant to
+be reported as they hold across a swept space, not at a single assumed point.
+"""
+
+from __future__ import annotations
+
+from .classes import (
+    ProcessClass,
+    available_classes,
+    get_class,
+    load_classes,
+    register_class,
+)
+from .fitting import (
+    bias_report,
+    class_from_observations,
+    correlation_floor,
+    correlation_transfer,
+    phi_from_lag1,
+    sigma_from_cv,
+)
+from . import reference
+from .generator import (
+    build_profiles,
+    generate,
+    rescale_persistence,
+    solve_correlation_knob,
+    step_hours,
+)
+from .spec import CARRIERS, DemandSpec
+from .stats import (
+    cross_correlogram,
+    duration_curve,
+    integrated_drift,
+    profile_statistics,
+    summary_table,
+)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "__version__",
+    # what to generate
+    "DemandSpec", "CARRIERS",
+    # generating
+    "generate", "build_profiles", "solve_correlation_knob",
+    "step_hours", "rescale_persistence",
+    # process classes
+    "ProcessClass", "available_classes", "get_class", "load_classes",
+    "register_class",
+    # fitting to your own measurements
+    "class_from_observations", "bias_report",
+    "sigma_from_cv", "phi_from_lag1",
+    "correlation_floor", "correlation_transfer",
+    # diagnostics
+    # indicative published values
+    "reference",
+    "profile_statistics", "summary_table", "duration_curve",
+    "cross_correlogram", "integrated_drift",
+]

loadcast/classes.py

@@ -0,0 +1,187 @@
+"""Process classes: how peaky an industrial process is, and on what rhythm.
+
+A process class bundles everything the generator needs that is *not* specific to
+one site: the calendar rhythm (month, day-of-week, hour-of-day factors) and the
+three statistics that describe how the load fluctuates around it (load factor,
+coefficient of variation, lag-1 persistence), plus an on/off description for
+processes that are genuinely intermittent rather than merely variable.
+
+Each class is calibrated on one metered industrial site. The sites themselves
+are not distributed -- what ships is the derived statistics and the calendar
+factors, which are group means and carry no identifying information.
+
+The four classes span the range the archive covers:
+
+    continuous       runs around the clock, small excursions
+    semi_continuous  weekday shift pattern with a weekend trough
+    campaign         long runs separated by genuine shutdowns
+    batch            strongly bimodal, most hours near zero
+
+Choose one from the *process description* of the site you are modelling, not by
+fitting to an answer you already have. If none fits, `loadcast.fitting` builds a
+class from your own observed statistics.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+
+import numpy as np
+
+__all__ = ["ProcessClass", "available_classes", "get_class", "load_classes",
+           "register_class"]
+
+
+@dataclass(frozen=True)
+class ProcessClass:
+    """One calibrated process rhythm.
+
+    Attributes
+    ----------
+    name
+        Identifier used in `DemandSpec.process_class`.
+    month, dayofweek, hour
+        Calendar factors, each normalised to mean one over a balanced calendar.
+        `month` is indexed January..December, `dayofweek` Monday..Sunday, `hour`
+        00..23. They carry *shape only*: the level comes from the spec.
+    target_load_factor
+        Mean over peak of the finished profile. Imposed exactly by the capacity
+        cap, not fitted.
+    target_cv
+        Coefficient of variation of the finished profile, calendar included.
+    target_lag1
+        Lag-1 autocorrelation of the finished profile.
+    mode
+        ``"lognormal"`` for a process that varies continuously, ``"onoff"`` for
+        one that genuinely stops. The choice is forced by the data: a lognormal
+        with the right spread still puts a batch process's load factor at 0.02
+        against 0.22 measured, because a lognormal tail is far longer than an
+        on/off process at equal spread.
+    off_fraction
+        Share of hours in the off state. Zero for ``"lognormal"`` classes.
+    off_level
+        Load in the off state, as a fraction of the running level. Non-zero
+        because real plants idle rather than stop.
+    description
+        The kind of process this rhythm was measured on.
+    anchor_site
+        Anonymised label of the metered site it was calibrated against.
+    n_hours
+        Length of the series it was calibrated on.
+    """
+
+    name: str
+    month: tuple[float, ...]
+    dayofweek: tuple[float, ...]
+    hour: tuple[float, ...]
+    target_load_factor: float
+    target_cv: float
+    target_lag1: float
+    mode: str
+    off_fraction: float
+    off_level: float
+    description: str
+    anchor_site: str
+    n_hours: int
+
+    def __post_init__(self) -> None:
+        if self.mode not in ("lognormal", "onoff"):
+            raise ValueError(f"unknown mode {self.mode!r}")
+        for field, expected in (("month", 12), ("dayofweek", 7), ("hour", 24)):
+            got = len(getattr(self, field))
+            if got != expected:
+                raise ValueError(
+                    f"{self.name}: {field} needs {expected} factors, got {got}"
+                )
+
+    def calendar(self, index) -> np.ndarray:
+        """Calendar factor `S(t)` for every timestamp in `index`.
+
+        The three periodic factors multiply. Each has mean one over a balanced
+        calendar, so their product carries shape and no level -- which is what
+        lets the same rhythm be reused at any plant size.
+        """
+        month = np.asarray(self.month, dtype=float)
+        dayofweek = np.asarray(self.dayofweek, dtype=float)
+        hour = np.asarray(self.hour, dtype=float)
+        return (month[index.month - 1]
+                * dayofweek[index.dayofweek]
+                * hour[index.hour])
+
+
+@lru_cache(maxsize=1)
+def load_classes() -> dict[str, ProcessClass]:
+    """Every calibrated process class shipped with the package."""
+    source = resources.files("loadcast.data").joinpath("process_classes.json")
+    raw = json.loads(source.read_text(encoding="utf-8"))
+
+    classes: dict[str, ProcessClass] = {}
+    for name, entry in raw.items():
+        classes[name] = ProcessClass(
+            name=name,
+            month=tuple(entry["month"]),
+            dayofweek=tuple(entry["dayofweek"]),
+            hour=tuple(entry["hour"]),
+            target_load_factor=float(entry["target_load_factor"]),
+            target_cv=float(entry["target_cv"]),
+            target_lag1=float(entry["target_lag1"]),
+            mode=str(entry["mode"]),
+            off_fraction=float(entry["off_fraction"]),
+            off_level=float(entry["off_level"]),
+            description=str(entry["description"]),
+            anchor_site=str(entry["anchor_site"]),
+            n_hours=int(entry["n_hours"]),
+        )
+    return classes
+
+
+# Classes built at runtime from a user's own measurements. Kept apart from the
+# shipped ones so `available_classes` can say which is which, and so nothing
+# a user registers can silently shadow a calibrated class.
+_REGISTERED: dict[str, ProcessClass] = {}
+
+
+def register_class(process_class: ProcessClass, overwrite: bool = False) -> None:
+    """Make a process class usable by name in a `DemandSpec`.
+
+    Pair this with `loadcast.fitting.class_from_observations` to generate from
+    statistics you measured yourself:
+
+        own = class_from_observations("my_plant", 0.45, 0.6, 0.9)
+        register_class(own)
+        generate(process_class="my_plant", annual_mwh=5_000)
+    """
+    name = process_class.name
+    if name in load_classes():
+        raise ValueError(
+            f"{name!r} is a calibrated class shipped with loadcast; "
+            f"choose another name rather than shadowing it"
+        )
+    if name in _REGISTERED and not overwrite:
+        raise ValueError(f"{name!r} is already registered; pass overwrite=True")
+    _REGISTERED[name] = process_class
+
+
+def available_classes(include_registered: bool = True) -> list[str]:
+    """Names of the process classes that can be generated from."""
+    names = set(load_classes())
+    if include_registered:
+        names |= set(_REGISTERED)
+    return sorted(names)
+
+
+def get_class(name: str) -> ProcessClass:
+    """One process class by name, with a helpful error if it does not exist."""
+    classes = load_classes()
+    if name in classes:
+        return classes[name]
+    if name in _REGISTERED:
+        return _REGISTERED[name]
+    raise KeyError(
+        f"unknown process class {name!r}; available: {available_classes()}. "
+        f"To build one from your own measurements, see "
+        f"loadcast.fitting.class_from_observations and register_class."
+    )

loadcast/data/__init__.py

@@ -0,0 +1,5 @@
+"""Bundled calibration data.
+
+A regular package rather than a bare directory: ``importlib.resources.files``
+cannot read from a namespace package on Python 3.9.
+"""

loadcast/data/process_classes.json

@@ -0,0 +1,242 @@
+{
+ "batch": {
+  "anchor_site": "site_c",
+  "dayofweek": [
+   1.55929,
+   1.50644,
+   1.234482,
+   1.053401,
+   1.217668,
+   0.25477,
+   0.169895
+  ],
+  "description": "long on/off runs; coffee roasting",
+  "hour": [
+   0.154848,
+   0.154795,
+   0.158523,
+   0.157162,
+   0.281185,
+   1.229629,
+   1.857477,
+   1.894545,
+   1.853708,
+   1.773206,
+   1.719132,
+   1.632496,
+   1.446623,
+   1.373535,
+   1.369311,
+   1.322143,
+   1.253803,
+   1.170113,
+   1.100534,
+   1.024897,
+   0.553287,
+   0.210613,
+   0.154494,
+   0.15394
+  ],
+  "mode": "onoff",
+  "month": [
+   1.135009,
+   1.011868,
+   0.962326,
+   0.930036,
+   0.965991,
+   1.067641,
+   0.445614,
+   0.913278,
+   0.995257,
+   1.142671,
+   1.422581,
+   1.022282
+  ],
+  "n_hours": 8760,
+  "off_fraction": 0.4,
+  "off_level": 0.02,
+  "target_cv": 1.177,
+  "target_lag1": 0.848,
+  "target_load_factor": 0.221
+ },
+ "campaign": {
+  "anchor_site": "site_d",
+  "dayofweek": [
+   0.954028,
+   0.960068,
+   0.975323,
+   1.033885,
+   1.014871,
+   1.045056,
+   1.017728
+  ],
+  "description": "long campaigns on and off; phosphate burner",
+  "hour": [
+   1.032559,
+   1.035685,
+   1.036415,
+   1.037355,
+   1.039047,
+   1.029501,
+   1.026594,
+   1.001638,
+   0.886791,
+   0.898781,
+   0.966302,
+   0.990871,
+   0.988767,
+   0.98998,
+   0.992691,
+   0.998371,
+   0.996536,
+   0.997509,
+   0.99553,
+   0.998669,
+   1.004324,
+   1.011664,
+   1.016607,
+   1.027876
+  ],
+  "mode": "onoff",
+  "month": [
+   1.101382,
+   1.153565,
+   1.260548,
+   1.025009,
+   1.080069,
+   0.909929,
+   0.907351,
+   0.907123,
+   1.051813,
+   0.838124,
+   0.765126,
+   0.928618
+  ],
+  "n_hours": 16535,
+  "off_fraction": 0.196,
+  "off_level": 0.02,
+  "target_cv": 0.527,
+  "target_lag1": 0.957,
+  "target_load_factor": 0.503
+ },
+ "continuous": {
+  "anchor_site": "site_a",
+  "dayofweek": [
+   0.883038,
+   1.201896,
+   1.195369,
+   1.191803,
+   1.105632,
+   0.722996,
+   0.697166
+  ],
+  "description": "runs around the clock; pasta drying, mineral drying",
+  "hour": [
+   0.990317,
+   0.993397,
+   0.993791,
+   0.962328,
+   0.95992,
+   0.962603,
+   0.969056,
+   0.956698,
+   0.932786,
+   0.949027,
+   0.992933,
+   1.005735,
+   1.008749,
+   1.024708,
+   1.023066,
+   1.016832,
+   0.992313,
+   1.014779,
+   1.047381,
+   1.04819,
+   1.037668,
+   1.052113,
+   1.046296,
+   1.019314
+  ],
+  "mode": "lognormal",
+  "month": [
+   1.165743,
+   1.129872,
+   1.088858,
+   1.09592,
+   0.950285,
+   1.109809,
+   0.733752,
+   0.930212,
+   0.989356,
+   1.045419,
+   0.880077,
+   0.895691
+  ],
+  "n_hours": 8760,
+  "off_fraction": 0.0,
+  "off_level": 0.0,
+  "target_cv": 0.409,
+  "target_lag1": 0.973,
+  "target_load_factor": 0.576
+ },
+ "semi_continuous": {
+  "anchor_site": "site_b",
+  "dayofweek": [
+   1.236234,
+   1.256554,
+   1.231145,
+   1.190143,
+   0.962295,
+   0.442463,
+   0.681708
+  ],
+  "description": "shifts with weekend shutdown; brewing, phosphate burners",
+  "hour": [
+   1.004733,
+   0.954934,
+   0.943026,
+   0.953191,
+   1.027009,
+   1.047198,
+   1.039582,
+   1.032001,
+   1.000225,
+   1.042484,
+   1.040865,
+   1.050062,
+   1.035649,
+   1.015254,
+   1.021087,
+   1.038695,
+   1.022148,
+   0.977781,
+   0.973244,
+   0.96839,
+   0.93851,
+   0.917547,
+   0.950893,
+   1.005491
+  ],
+  "mode": "lognormal",
+  "month": [
+   0.983435,
+   1.034075,
+   1.068202,
+   1.160898,
+   0.98848,
+   0.973074,
+   0.929518,
+   1.093648,
+   0.843058,
+   0.864036,
+   0.983501,
+   1.080097
+  ],
+  "n_hours": 8760,
+  "off_fraction": 0.0,
+  "off_level": 0.0,
+  "target_cv": 0.478,
+  "target_lag1": 0.793,
+  "target_load_factor": 0.401
+ }
+}

loadcast/data/reference.json

@@ -0,0 +1,158 @@
+{
+ "compositions": {
+  "_source": "jericho",
+  "industry_aggregate": {
+   "cold": 0.049,
+   "elec": 0.213,
+   "heat": 0.738,
+   "heat_to_cold": 15.0
+  }
+ },
+ "sector_temperatures": {
+  "Chemical": {
+   "process_median_c": 109.6,
+   "process_p25_c": 71.0,
+   "process_p75_c": 129.0,
+   "process_pj_15_200": 354.6,
+   "waste_median_c": 52.1,
+   "waste_pj_15_200": 337.1,
+   "waste_to_process": 0.95
+  },
+  "Food and Beverage": {
+   "process_median_c": 120.9,
+   "process_p25_c": 105.5,
+   "process_p75_c": 180.0,
+   "process_pj_15_200": 193.1,
+   "waste_median_c": 57.0,
+   "waste_pj_15_200": 97.2,
+   "waste_to_process": 0.5
+  },
+  "Paper": {
+   "process_median_c": 140.0,
+   "process_p25_c": 125.0,
+   "process_p75_c": 157.2,
+   "process_pj_15_200": 356.5,
+   "waste_median_c": 45.0,
+   "waste_pj_15_200": 230.9,
+   "waste_to_process": 0.65
+  },
+  "Refinery": {
+   "process_median_c": 275.3,
+   "process_p25_c": 173.4,
+   "process_p75_c": 309.0,
+   "process_pj_15_200": 219.1,
+   "waste_median_c": 89.5,
+   "waste_pj_15_200": 464.9,
+   "waste_to_process": 2.12
+  }
+ },
+ "sources": {
+  "jericho": {
+   "caveat": "Annual shares only. Its hourly series cannot be used: carriers are a fixed scalar times one shared profile, so their correlation is 1.000000 and the composition is identical across all 38 regions to 4e-8 while regional scale varies 17.9x.",
+   "citation": "Priesmann J, Nolting L, Kockel C, Praktiknjo A. Time series of useful energy consumption patterns for energy system modeling (JERICHO-E-usage). Scientific Data 8:148, 2021. doi:10.1038/s41597-021-00907-w",
+   "kind": "useful energy by carrier, annual totals",
+   "peer_reviewed": true,
+   "scope": "German industry, 2019, 38 NUTS2 regions"
+  },
+  "rehfeldt": {
+   "caveat": "Digitised from Fig. 16 to about +-5 percentage points. Its own two datasets disagree by more than the subsectors differ from one another, so this is reported as a range and never as a point.",
+   "citation": "Rehfeldt M, Fleiter T, Toro F. A bottom-up estimation of the heating and cooling demand in European industry. Energy Efficiency 11:1057-1082, 2018. doi:10.1007/s12053-017-9571-y",
+   "kind": "heat by temperature band and cooling, shares of subsector demand",
+   "peer_reviewed": true,
+   "scope": "UK industry, 7 subsectors, two datasets (ECUK and FORECAST)"
+  },
+  "tno": {
+   "caveat": "No electricity and essentially no refrigeration. Its waste heat is rejected above ambient and is a heat pump source, not a cooling demand.",
+   "citation": "Marina A, Spoelstra S, Zondag HA, Wemmers AK. An estimation of the European industrial heat pump market potential. Renewable and Sustainable Energy Reviews 139:110545, 2021. doi:10.1016/j.rser.2020.110545",
+   "kind": "process and waste heat quantities with stream temperatures",
+   "peer_reviewed": true,
+   "scope": "EU-28, 2016 production, 4 sectors, ~66 products"
+  }
+ },
+ "subsector_heat_to_cold": {
+  "Chemicals": {
+   "ECUK": {
+    "cold_pct": 13.0,
+    "heat_pct": 87.0,
+    "heat_to_cold": 6.7
+   },
+   "FORECAST": {
+    "cold_pct": 2.0,
+    "heat_pct": 98.0,
+    "heat_to_cold": 49.0
+   }
+  },
+  "Food, beverages and tobacco": {
+   "ECUK": {
+    "cold_pct": 8.0,
+    "heat_pct": 92.0,
+    "heat_to_cold": 11.5
+   },
+   "FORECAST": {
+    "cold_pct": 3.0,
+    "heat_pct": 97.0,
+    "heat_to_cold": 32.3
+   }
+  },
+  "Iron and steel, non-ferrous metals": {
+   "ECUK": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   },
+   "FORECAST": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   }
+  },
+  "Machinery and Transport": {
+   "ECUK": {
+    "cold_pct": 2.0,
+    "heat_pct": 98.0,
+    "heat_to_cold": 49.0
+   },
+   "FORECAST": {
+    "cold_pct": 2.0,
+    "heat_pct": 98.0,
+    "heat_to_cold": 49.0
+   }
+  },
+  "Non-metallic minerals": {
+   "ECUK": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   },
+   "FORECAST": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   }
+  },
+  "Other industry": {
+   "ECUK": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   },
+   "FORECAST": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   }
+  },
+  "Paper": {
+   "ECUK": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   },
+   "FORECAST": {
+    "cold_pct": 0.0,
+    "heat_pct": 100.0,
+    "heat_to_cold": null
+   }
+  }
+ }
+}