loadcast 0.1.1__tar.gz

loadcast-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattéo Hauglustaine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loadcast-0.1.1/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: loadcast
+Version: 0.1.1
+Summary: Synthetic multi-carrier industrial energy demand profiles with controllable cross-carrier structure
+Author-email: Matteo Hauglustaine <matteo@abeo.be>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Matt-haug/loadcast
+Project-URL: Documentation, https://loadcast.readthedocs.io
+Project-URL: Repository, https://github.com/Matt-haug/loadcast
+Project-URL: Issues, https://github.com/Matt-haug/loadcast/issues
+Keywords: energy,demand,load profile,industrial,synthetic data,time series,heat,cooling,multi-carrier
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == "plot"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: loadcast[docs,plot,test]; extra == "dev"
+Dynamic: license-file
+
+[![PyPI version](https://img.shields.io/pypi/v/loadcast)](https://pypi.org/project/loadcast/)
+[![Documentation Status](https://readthedocs.org/projects/loadcast/badge/?version=latest)](https://loadcast.readthedocs.io/en/latest/)
+[![Build Status](https://github.com/Matt-haug/loadcast/actions/workflows/tests.yml/badge.svg)](https://github.com/Matt-haug/loadcast/actions/workflows/tests.yml)
+[![License](https://img.shields.io/github/license/Matt-haug/loadcast)](https://github.com/Matt-haug/loadcast/blob/main/LICENSE)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22961300-blue)](https://doi.org/10.5281/zenodo.22961300)
+
+# loadcast
+
+**A synthetic multi-carrier industrial energy demand generator**
+
+```python
+import loadcast
+
+profiles = loadcast.generate(
+    annual_mwh=10_000,
+    heat_to_cold=7.4,        # this site wants 7.4x more heat than cold
+    elec_share=0.20,         # a fifth of its energy is electricity
+    process_class="semi_continuous",   # weekday shifts, weekend trough
+    carrier_correlation=0.75,          # how tightly the carriers move together
+    carrier_lag_h={"cold": 6},         # cold demand trails heat by six hours
+)
+```
+
+Returns an 8760-row hourly or quarter-hourly frame of `heat_kw`, `cold_kw` and `elec_kw`.
+
+![Heat-cold cross-correlogram: the published disaggregated construction peaks at exactly 1.000; loadcast peaks at the 0.60 asked for](https://raw.githubusercontent.com/Matt-haug/loadcast/main/examples/figures/07_coincidence.png)
+
+*Left: every carrier as a fixed multiple of one shared profile, the construction behind published
+disaggregated data, which is correlated at 1 by algebra. Right: `loadcast` with `carrier_correlation=0.60`.
+More in the [tutorial notebook](https://github.com/Matt-haug/loadcast/blob/main/examples/01_tutorial.ipynb).*
+
+## Why
+
+Designing anything with storage against an industrial site needs to know not
+just *how much* of each carrier the site wants, but **whether it wants them at
+the same hours**. A store exists to bridge the gap when it does not.
+
+Existing sources cannot answer that question:
+
+| source | approach | industrial | coincidence controllable? |
+|---|---|---|---|
+| demandlib / BDEW SLP | deterministic step profiles | yes | no — deterministic |
+| RAMP | bottom-up from appliances | no | no — emerges from user schedules |
+| LoadProfileGenerator | behavioural simulation | no | no |
+| EnTiSe | framework, pluggable methods | partly | no — pipeline dependency |
+| JERICHO-E-usage | disaggregated national totals | yes | no — fixed at 1.000 |
+
+The disaggregated datasets build every carrier as a fixed scalar times one
+shared profile, $P_m(t) = \kappa_m p(t)$, under which the correlation between
+any two carriers is identically 1 — an artefact of the construction, not a
+measurement. Feeding that into a storage study builds the answer into the
+question.
+
+`loadcast` makes the relationship an input you set and sweep.
+
+## What you specify
+
+Things you can answer from a site visit or an energy bill, not things the
+mathematics wants:
+
+| input | meaning |
+|---|---|
+| `annual_mwh` | total annual energy across all carriers |
+| `heat_to_cold` | ratio of annual heat to annual cold |
+| `elec_share` | electricity as a fraction of the total |
+| `process_class` | continuous, semi-continuous, campaign or batch |
+| `carrier_correlation` | how tightly carriers move together, at peak alignment |
+| `carrier_lag_h` | hours by which a carrier trails the others |
+
+The four process classes are calibrated on metered industrial sites. If none
+fits yours, build one from your own statistics:
+
+```python
+from loadcast import class_from_observations, register_class
+
+mine = class_from_observations(
+    "my_plant", load_factor=0.45, cv=0.60, lag1=0.90,
+    calendar_from="semi_continuous",
+)
+register_class(mine)
+profiles = loadcast.generate(process_class="my_plant", annual_mwh=5_000)
+```
+
+The inversion from observables to generator parameters is closed form. See [mathematics](https://loadcast.readthedocs.io/en/latest/mathematics/) for details.
+
+## What it guarantees exactly
+
+Not approximately, but to floating-point:
+
+- annual energy equals `annual_mwh`
+- the heat:cold ratio equals `heat_to_cold`
+- the electricity share equals `elec_share`
+- the load factor equals the process class's, via the capacity cap fixed point
+- every value is strictly positive
+
+## Diagnostics
+
+```python
+loadcast.summary_table(profiles)                       # the four scalars
+loadcast.duration_curve(profiles["heat_kw"])           # load duration curve
+loadcast.cross_correlogram(profiles["heat_kw"], profiles["cold_kw"])
+loadcast.integrated_drift(profiles["heat_kw"], profiles["cold_kw"], window_h=24)
+```
+
+Read the correlogram's **peak position**, not only its height. A lag and a weak
+coupling are indistinguishable from the contemporaneous correlation alone: as
+carriers are offset, the lag-0 correlation decays towards the floor the shared
+calendar imposes, exactly where a small correlation would also put it.
+
+`integrated_drift` is the quantity a store actually responds to. A buffer does
+not sample a mismatch, it integrates one, so what sizes it is the area under the
+mismatch autocovariance over the storage window — correlation is a single point
+of that picture.
+
+## What it deliberately does not do
+
+- **No temperature.** It carries energy by carrier. Whether a machine can
+  *reach* a given process is a separate question, answered from the machine's
+  own limits.
+- **No claim about your site.** Parameters are yours to choose; defaults are
+  indicative values with a stated provenance, not predictions. Results are meant
+  to be reported as they hold across a swept space, not at one assumed point.
+- **No cold validation.** No site in the calibration archive meters
+  refrigeration. The cold carrier's annual quantity is whatever you specify;
+  its *shape* rests on the same calendar and correlation assumptions as the
+  others, and nothing independent confirms it. Every cold result carries this.
+
+## Install
+
+```bash
+pip install loadcast
+```
+
+Requires Python 3.9+, numpy and pandas. Nothing else.
+
+## Documentation
+
+A detailed documentation of the library is available at: https://loadcast.readthedocs.io/en/latest/
+
+Refer to that documentation for usage instructions and examples and details of the method.
+
+## Calibration data
+
+The process classes are calibrated on metered industrial sites that cannot be
+redistributed. What ships is the *derived* statistics and calendar factors —
+group means carrying no identifying information. The raw series are not part of
+this repository.
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](https://github.com/Matt-haug/loadcast/blob/main/CONTRIBUTING.md)
+for scope, what a test looks like here, and support expectations. Reports that
+the generated profiles disagree with a real site you have measured are
+especially welcome: the calibration archive is small, and that is the package's
+main limitation.
+
+This project follows the [Contributor Covenant](https://github.com/Matt-haug/loadcast/blob/main/CODE_OF_CONDUCT.md).
+Generative AI was used in building it; see [AI_USAGE.md](https://github.com/Matt-haug/loadcast/blob/main/AI_USAGE.md).
+
+## Citing
+
+Use the "Cite this repository" button, or `CITATION.cff`. Each release is
+archived on Zenodo with a DOI.
+
+## Licence
+
+MIT — see [LICENSE](https://github.com/Matt-haug/loadcast/blob/main/LICENSE). Changes are recorded in
+[CHANGELOG.md](https://github.com/Matt-haug/loadcast/blob/main/CHANGELOG.md).

loadcast-0.1.1/README.md

@@ -0,0 +1,168 @@
+[![PyPI version](https://img.shields.io/pypi/v/loadcast)](https://pypi.org/project/loadcast/)
+[![Documentation Status](https://readthedocs.org/projects/loadcast/badge/?version=latest)](https://loadcast.readthedocs.io/en/latest/)
+[![Build Status](https://github.com/Matt-haug/loadcast/actions/workflows/tests.yml/badge.svg)](https://github.com/Matt-haug/loadcast/actions/workflows/tests.yml)
+[![License](https://img.shields.io/github/license/Matt-haug/loadcast)](https://github.com/Matt-haug/loadcast/blob/main/LICENSE)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22961300-blue)](https://doi.org/10.5281/zenodo.22961300)
+
+# loadcast
+
+**A synthetic multi-carrier industrial energy demand generator**
+
+```python
+import loadcast
+
+profiles = loadcast.generate(
+    annual_mwh=10_000,
+    heat_to_cold=7.4,        # this site wants 7.4x more heat than cold
+    elec_share=0.20,         # a fifth of its energy is electricity
+    process_class="semi_continuous",   # weekday shifts, weekend trough
+    carrier_correlation=0.75,          # how tightly the carriers move together
+    carrier_lag_h={"cold": 6},         # cold demand trails heat by six hours
+)
+```
+
+Returns an 8760-row hourly or quarter-hourly frame of `heat_kw`, `cold_kw` and `elec_kw`.
+
+![Heat-cold cross-correlogram: the published disaggregated construction peaks at exactly 1.000; loadcast peaks at the 0.60 asked for](https://raw.githubusercontent.com/Matt-haug/loadcast/main/examples/figures/07_coincidence.png)
+
+*Left: every carrier as a fixed multiple of one shared profile, the construction behind published
+disaggregated data, which is correlated at 1 by algebra. Right: `loadcast` with `carrier_correlation=0.60`.
+More in the [tutorial notebook](https://github.com/Matt-haug/loadcast/blob/main/examples/01_tutorial.ipynb).*
+
+## Why
+
+Designing anything with storage against an industrial site needs to know not
+just *how much* of each carrier the site wants, but **whether it wants them at
+the same hours**. A store exists to bridge the gap when it does not.
+
+Existing sources cannot answer that question:
+
+| source | approach | industrial | coincidence controllable? |
+|---|---|---|---|
+| demandlib / BDEW SLP | deterministic step profiles | yes | no — deterministic |
+| RAMP | bottom-up from appliances | no | no — emerges from user schedules |
+| LoadProfileGenerator | behavioural simulation | no | no |
+| EnTiSe | framework, pluggable methods | partly | no — pipeline dependency |
+| JERICHO-E-usage | disaggregated national totals | yes | no — fixed at 1.000 |
+
+The disaggregated datasets build every carrier as a fixed scalar times one
+shared profile, $P_m(t) = \kappa_m p(t)$, under which the correlation between
+any two carriers is identically 1 — an artefact of the construction, not a
+measurement. Feeding that into a storage study builds the answer into the
+question.
+
+`loadcast` makes the relationship an input you set and sweep.
+
+## What you specify
+
+Things you can answer from a site visit or an energy bill, not things the
+mathematics wants:
+
+| input | meaning |
+|---|---|
+| `annual_mwh` | total annual energy across all carriers |
+| `heat_to_cold` | ratio of annual heat to annual cold |
+| `elec_share` | electricity as a fraction of the total |
+| `process_class` | continuous, semi-continuous, campaign or batch |
+| `carrier_correlation` | how tightly carriers move together, at peak alignment |
+| `carrier_lag_h` | hours by which a carrier trails the others |
+
+The four process classes are calibrated on metered industrial sites. If none
+fits yours, build one from your own statistics:
+
+```python
+from loadcast import class_from_observations, register_class
+
+mine = class_from_observations(
+    "my_plant", load_factor=0.45, cv=0.60, lag1=0.90,
+    calendar_from="semi_continuous",
+)
+register_class(mine)
+profiles = loadcast.generate(process_class="my_plant", annual_mwh=5_000)
+```
+
+The inversion from observables to generator parameters is closed form. See [mathematics](https://loadcast.readthedocs.io/en/latest/mathematics/) for details.
+
+## What it guarantees exactly
+
+Not approximately, but to floating-point:
+
+- annual energy equals `annual_mwh`
+- the heat:cold ratio equals `heat_to_cold`
+- the electricity share equals `elec_share`
+- the load factor equals the process class's, via the capacity cap fixed point
+- every value is strictly positive
+
+## Diagnostics
+
+```python
+loadcast.summary_table(profiles)                       # the four scalars
+loadcast.duration_curve(profiles["heat_kw"])           # load duration curve
+loadcast.cross_correlogram(profiles["heat_kw"], profiles["cold_kw"])
+loadcast.integrated_drift(profiles["heat_kw"], profiles["cold_kw"], window_h=24)
+```
+
+Read the correlogram's **peak position**, not only its height. A lag and a weak
+coupling are indistinguishable from the contemporaneous correlation alone: as
+carriers are offset, the lag-0 correlation decays towards the floor the shared
+calendar imposes, exactly where a small correlation would also put it.
+
+`integrated_drift` is the quantity a store actually responds to. A buffer does
+not sample a mismatch, it integrates one, so what sizes it is the area under the
+mismatch autocovariance over the storage window — correlation is a single point
+of that picture.
+
+## What it deliberately does not do
+
+- **No temperature.** It carries energy by carrier. Whether a machine can
+  *reach* a given process is a separate question, answered from the machine's
+  own limits.
+- **No claim about your site.** Parameters are yours to choose; defaults are
+  indicative values with a stated provenance, not predictions. Results are meant
+  to be reported as they hold across a swept space, not at one assumed point.
+- **No cold validation.** No site in the calibration archive meters
+  refrigeration. The cold carrier's annual quantity is whatever you specify;
+  its *shape* rests on the same calendar and correlation assumptions as the
+  others, and nothing independent confirms it. Every cold result carries this.
+
+## Install
+
+```bash
+pip install loadcast
+```
+
+Requires Python 3.9+, numpy and pandas. Nothing else.
+
+## Documentation
+
+A detailed documentation of the library is available at: https://loadcast.readthedocs.io/en/latest/
+
+Refer to that documentation for usage instructions and examples and details of the method.
+
+## Calibration data
+
+The process classes are calibrated on metered industrial sites that cannot be
+redistributed. What ships is the *derived* statistics and calendar factors —
+group means carrying no identifying information. The raw series are not part of
+this repository.
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](https://github.com/Matt-haug/loadcast/blob/main/CONTRIBUTING.md)
+for scope, what a test looks like here, and support expectations. Reports that
+the generated profiles disagree with a real site you have measured are
+especially welcome: the calibration archive is small, and that is the package's
+main limitation.
+
+This project follows the [Contributor Covenant](https://github.com/Matt-haug/loadcast/blob/main/CODE_OF_CONDUCT.md).
+Generative AI was used in building it; see [AI_USAGE.md](https://github.com/Matt-haug/loadcast/blob/main/AI_USAGE.md).
+
+## Citing
+
+Use the "Cite this repository" button, or `CITATION.cff`. Each release is
+archived on Zenodo with a DOI.
+
+## Licence
+
+MIT — see [LICENSE](https://github.com/Matt-haug/loadcast/blob/main/LICENSE). Changes are recorded in
+[CHANGELOG.md](https://github.com/Matt-haug/loadcast/blob/main/CHANGELOG.md).

loadcast-0.1.1/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loadcast"
+version = "0.1.1"
+description = "Synthetic multi-carrier industrial energy demand profiles with controllable cross-carrier structure"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Matteo Hauglustaine", email = "matteo@abeo.be" },
+]
+keywords = [
+    "energy",
+    "demand",
+    "load profile",
+    "industrial",
+    "synthetic data",
+    "time series",
+    "heat",
+    "cooling",
+    "multi-carrier",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.21",
+    "pandas>=1.3",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.5"]
+test = ["pytest>=7.0"]
+docs = ["mkdocs>=1.5", "mkdocs-material>=9.0", "mkdocstrings[python]>=0.24"]
+dev = ["loadcast[plot,test,docs]"]
+
+[project.urls]
+Homepage = "https://github.com/Matt-haug/loadcast"
+Documentation = "https://loadcast.readthedocs.io"
+Repository = "https://github.com/Matt-haug/loadcast"
+Issues = "https://github.com/Matt-haug/loadcast/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+loadcast = ["data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

loadcast-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loadcast-0.1.1/src/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",
+]