Skip to content

ADR-035: Schedule Draw on generator 4.0.0 — release program IDs, the export's view, and the release's generation blocks

  • Status: Accepted (D-205, version 1.7.0, under the owner's blanket authority for the release, D-204)
  • Date: 2026-10-30
  • Context: ADR-033 (Schedule Draw, generator 3.0.0, D-194 to D-196, D-198), design note, the atlas's ADR 0051 (generation parameters in the release; data release 2.2.0 and generator 4.0.0, atlas 2b3a6870), program JSON 5.4.0 (ADR-027)
  • Amends: ADR-033 decisions 2 (pins), 4 (the wrong-recipe hint), 8 (supported recipes, by method), 9 (the setting format), and 10 (provenance). Decisions 1, 3, 5, 6, and 7 stand unchanged.
  • Amended by: ADR-036 (D-209): the program setting may also come from the atlas site, the store file of the program's folder's generation.json (compact JSON, equal in content to the release's file), through Schedule Draw's strip Get from Atlas…; what the draw reads and checks is unchanged. D-242 (version 1.9.0, 2026-11-01): the pins are generator atlas_schedules 4.1.0 and data release 2.3.0 (manifest afe7e2ef…fb86c); since D-255 (version 1.10.0) generator 4.1.1 and data release 2.4.0 (manifest 51ce9c9e…bd7f), the same code; the program setting the generation.json of release 2.3.0 and the setting's generator version 4.1.0; the request and bundle schema stay 4.0.0, and every other decision stands. Release 2.3.0 generates the IECC commercial and detailed office folders, so the DOE offices and IECC programs are drawn.

Context

Atlas release 2.2.0 removes every folder's generator.json, the program settings Schedule Draw read under ADR-033, and adds each generated folder's generation.json: per release program its generation method and, per view (source, and filled where the filled program generates differently), the parameters the program record does not state (for a commercial program its ComStock configuration_id); per release service the configurations it runs under; and the folder's building configurations. Generator 4.0.0 assembles each recipe itself from the release it bundles (the generator view of 2.2.0). Its request schema 4.0.0 takes release program and service IDs and an optional values (source or filled, the two consumer exports' names; default filled where the block has that view, else source); a 3.0.0 request, with its definition IDs, is refused with a message naming atlas-schedules translate. Its bundle schema 4.0.0 is 3.0.0's content plus a top-level release (version, manifest_sha256, generation_schema_version) and each owner's values. Program JSON 5.4.0 exports of 2.2.0 differ from 2.1.0's only in source.release, which the 5.4.0 schema now admits by a pattern.

Decision

  1. Pins. The setting must name atlas_schedules 4.0.0 and request and bundle schema 4.0.0 (ScheduleDrawGeneratorNotSupported otherwise). A bundle must have schema 4.0.0, generator_version 4.0.0 or a PEP 440 pre-release or development version of it (accepted with ScheduleDrawPreRelease, the logic of ADR-033 decision 2 kept), and the release block of the pinned data release: version 2.2.0 and manifest_sha256 67e73e55861a9b9c88d4a745ee883ec73ad859c5a8d14ac86be3b3409ce7ece4 (ScheduleDrawVersionMismatch otherwise, naming --release-dir and ATLAS_RELEASES, which point the generator at another release). The generation_schema_version is recorded, not pinned: the manifest's hash fixes it.
  2. Program settings: the release's generation.json. The program setting of a draw is the generation.json of the program's release 2.2.0 folder (generation schema 1.0.0), one or more files; a program, service, or configuration in two files must be the same in both. A generator.json of release 2.0.0 or 2.1.0 is refused (ScheduleDrawRecipesInvalid), with a message that names the file to give instead. Why not ask the generator: the request must name each shared service's configuration_id, which only the block states, and BEMGen refuses unsupported methods before the generator runs. Why not derive the configuration from the program's template and building type: the configuration IDs are the release's names; deriving them would be a second, unvalidated copy of a rule.
  3. The request names the export's own release ID and view. program_id is the export's id (the release program ID, equal to source.program_id); program IDs do not change between releases 2.0.0, 2.1.0, and 2.2.0 (atlas ADR 0051 section 4), so an export of any of the three is drawn by the same request. values is the export's version: a filled export is drawn with filled and a source export with source, so the generator's recipe takes the same values the program holds. Where the block has no view of that name (the DOE Ref programs, whose blocks carry only source, and whose filled exports the release does not generate differently), the request says source, the generator's own default for such a block, and an information diagnostic ScheduleDrawValuesSource says so. The magnitude check of ADR-033 decision 4 stays the guard: a drawn load's program value must equal the bundle's amplitude. values is always written, never left to the default, so the request states what was asked.
  4. Shared services from the export. A program's shared services are the export's hot-water demands that name a service of the given generation.json (each water_heating[].demand_id and each hot_water load's demand_id with a positive value, in the export's order, once each; the generator's assembler takes a release program's hot water of a shared service as a required service the same way). Each becomes a service instance with the configuration of the program's view, which the service's block must list (ScheduleDrawRecipesInvalid otherwise). A missing or extra link is also refused by the generator.
  5. Supported methods. comstock_hours (recipe kind commercial) and fixed (fixed); composition, resstock_unit, and resstock_dwelling are ScheduleDrawKindNotSupported for ADR-033 decision 8's reasons, and a program without a block is ScheduleDrawRecipeNotFound. A fixed recipe has no shared services.
  6. Where a drawn load goes. With one load of the slot's type, that load. With several, the one whose value equals the bundle's amplitude for the slot; otherwise the draw is ScheduleDrawAmbiguous. (Generator 3.0.0's packaged recipes also named the source schedule, which a release block does not.)
  7. The bundle's view and release. Every program owner's values must equal the request's (ScheduleDrawBundleInvalid otherwise).
  8. The setting is schedule_draw_setting 2.0.0 (schedule-draw-setting-v2.schema.json): 1.0.0 without view, since the view now comes from the export (decision 3); generator names atlas_schedules 4.0.0 and bundle schema 4.0.0. A 1.0.0 setting is refused (ScheduleDrawSettingInvalid) with a message that says what to change.
  9. Provenance. metadata.schedule_draw gains release (version, manifest_sha256, generation_schema_version, as the bundle reports them) and values (the view the request named), in place of view; recipe_sha256 holds the SHA-256 of each generation.json given. Describe() adds a Release: line and names the program settings as generation.json.

Alternatives

  • Keep reading generator.json from release 2.1.0. Rejected: generator 4.0.0 refuses its 90.1 definition IDs, and its recipes would be a second copy of values the generator now assembles from 2.2.0.
  • Leave values out and take the generator's default. Rejected: a filled 90.1 export would be drawn with the filled recipe only by coincidence of the default, and a source export would be drawn with the filled recipe, whose magnitudes differ; the request would not record which view was meant.
  • Refuse a filled export whose block has no filled view. Rejected: the DOE Ref filled exports (the recorded draw's program among them) were drawn with the source recipe under ADR-033 too, and the magnitude check refuses any load that would differ.
  • Keep view in a 1.0.0 setting as an override. Rejected: two sources of the view, which could disagree with the export; a setting must change for 4.0.0 in any case (its pinned version).
  • Pin the data release by version only. Rejected: a release folder on disk (ATLAS_RELEASES) could carry the label with other content; the manifest hash names exactly what the recipes were assembled from.

Consequences

  • Users give Schedule Draw (and a suite's schedules.recipes) the generation.json of the program's folder in atlas-release-2.2.0.zip (v2.2.0/<family>/<template>/<type>/generation.json) and a 2.0.0 setting; the component's inputs, outputs, and GUID are unchanged, and only the descriptions name the new files and versions.
  • A draw stored by 1.6.0 (a drawn program JSON with generator 3.0.0 provenance) still reads; drawing it again with 1.7.0 gives the same schedules where atlas ADR 0051's equivalence holds (263 of its 266 sampled generator 3.0.0 bundles agree within 1e-9 after translation; the 3 others are retired hotel corridor compositions, which Schedule Draw refuses as compositions anyway). The 36 90.1 apartment-building fixed recipes now carry the release's values (heat fractions kept, zero-density occupancy left out), so their bundles can differ from 3.0.0's. BEMGen's recorded draw (the DOE Ref 1980–2004 medium office, two instances, seed 42) gave the same schedules and owners as under 3.0.0 (D-205).
  • Open, as before: apartment units, composition parents, mixed slots, a calendar other than 2007.