Skip to content

ADR-036: Atlas program maps on the DOE program map presets, and Generator JSON from the atlas site

  • Status: Accepted · amended by D-226 (the stored map's format 1.1.0 keeps each key's canonical checksum as downloaded, against which its Json.Store is recorded; 1.0.0 still reads), D-227 (the site index schema 1.0.0; decision 2's fault is joined by separate faults for the compositions and the construction sets), D-240 (a map stored from site release 2.2.0 or earlier is refused as a whole, naming its programs' release 2.3.0 IDs, ADR-038), and D-241 (decision 4: the six IECC families are offered for the eleven prototypes they hold; decision 3's recorded index has 141 folders since), D-246 (the stand-alone retail's core and front keyed apart; a crosswalk may name a source program; the alternatives' crosswalk), D-249 (decision 7: the skylights are the family's source geometry's, ADR-039), and D-247 (decision 4: the IECC offices offered, every key crosswalked to the whole-building program; 159 folders)
  • Date: 2026-10-30
  • Decision log: D-209
  • Design note: atlas program picker, §3, §4.3, and §6 (every recommendation accepted by the owner on 2026-10-30)
  • Amends: ADR-018 (the atlas window, D-208) and ADR-035 (where Generator JSON may come from)
  • Atlas side: the atlas's ADR 0052, live since 2026-10-30: the site's index gives each program its folder, mode, space_type, and building_type, and a top-level folders with each folder's programs and, where the release has one, its generation.json in the store

Context

The fifteen DOE Programs components give each DOE generator a map of illustrative presets (D-023, stage P7). The atlas publishes every DOE prototype's programs in five commercial families, and since its ADR 0052 the site's index says which folder, mode, and space type each program has. Program JSON already takes one program from the site (D-208). The owner asked that the DOE components take a whole map that way, and that Schedule Draw's Generator JSON come from the site too.

Decision

  1. One fixed folder per prototype. DoeAtlasFolders (Lod.Generators) gives each DOE prototype its folder name: the nine whose prototype name is the folder's, the three detailed offices (small-office-detailed, medium-office-detailed, large-office-detailed), and retail-standalone, retail-stripmall, super-market. The folder of a family is commercial/<template>/<folder>/. Folders are never searched: space types repeat across folders.
  2. The index's folders are read apart from its programs. A fault in the atlas ADR 0052 fields (a folder that is not its family, template, and building type, a folder and a program that do not list each other, a malformed generation, a program field that is not a text) drops all of them (AtlasSiteIndex.FoldersFault) but not the programs, so Program JSON's window (D-208) keeps working; the DOE windows and Schedule Draw's refuse with the fault.
  3. A key matches by space type, among source programs only. AtlasSiteIndex.MatchKeys matches a key to the one program of the folder whose mode is source and whose space_type is the key, compared exactly. Programs of mode department and general are not candidates: the atlas derives them by merging source programs (their space types are *_Mixed, such as Sales_Mixed and General_Mixed), so they are not a standards space type of the prototype. A key with no such program is a gap; a key with more than one is ambiguous and unmatched too. A test pins, against a recorded index of the 75 folders, every family's resolved keys and gaps, that no key is ambiguous, and that no department or general program has a key's space type, so a change on the atlas side fails it.
  4. Five families. The window offers DOE Ref pre-1980, DOE Ref 1980–2004, 90.1-2007, 90.1-2013, and 90.1-2019, the families the note reconciled, each with its coverage. The IECC templates, which hold most of the prototypes' folders too (none of the offices' or the supermarket's), are not offered: their programs were not reconciled with the DOE layouts' keys and are source only. Offering them is a separate decision. Amended by D-241 (2026-11-01, the review's F1): the six IECC families (IECC 2006 to 2021) are offered after the five for the eleven prototypes they hold, matched by the same rule; their offices hold only whole-building programs and they have no supermarket, so the three offices and the supermarket are not offered them. Each resolves 110 keys with the crosswalk of 90.1-2013 and 2019 (GuestRoom, Office), leaves Retail and Gym - audience as gaps, and is stored in its source version, the only one the atlas exports. Amended by D-246 and D-247 (2026-11-01, the owner's G1 and G9): the stand-alone retail's Core_Retail and Front_Retail take their own programs in 90.1-2013, 2019, and IECC, so Gym - audience is the one gap left; the IECC offices are offered at their IECC folders (small-office, medium-office, large-office), every key crosswalked to the folder's whole-building program as PNNL's IECC model gives every zone (the large office's data centre keeps OfficeLarge Data Center), and the coverage says the rooms are not distinguished. Every family but DOE Ref then resolves all keys but Gym - audience with its crosswalk.
  5. Keys without a program are refused (the note's question 5, answer a). OK in the window stores a family with gaps, the keys left empty in the map; the solve then outputs no Program Map, an error that names the keys, the family, and the folder, and Presets and JSON with those positions empty, so DOE Program Map can complete the map by hand. Neither the illustrative preset (b) nor a crosswalk (c) fills them.
  6. One stored text. OK downloads every matched key's program in parallel, each checked as Program JSON's download is (the SHA-256 of the gzip bytes against the store path, id, version, source.release) and then given the program check on the component's calendar, climate zone, and context; one failure stores nothing. The map is stored as one text (bemgen-atlas-program-map 1.0.0: the prototype, the site, its release and manifest checksum, the family, the folder, the version, and per key the program, its store path, and its text) in the component, written by Write and read by Read, with one undo event. Clear in the window removes it. The solve reads no file or network.
  7. The solve shares Program JSON's import. Each key's text is imported by ProgramJsonImporter with the key's name, its space type (DoeSpaceTypes.Of), the component's Climate Zone, Year, Holidays, and Context (optional inputs appended after none, unset as on Program JSON), and the DOE reference building's window-to-wall ratio per orientation and skylight ratio of the key (DoeProgramPresets.KeyRatios), so the presets fit the generator's geometry and their window area is the illustrative map's. The new output JSON, after the existing three, gives each key's text in the order of Keys.
  8. Old definitions reopen unchanged. No GUID changes. A definition saved before (no inputs, three outputs, no stored map) reads without the IO dialog and solves with the illustrative presets as before; the smoke check reopens one saved by the 1.7.0 plugin.
  9. Generator JSON from the site. The same strip on Schedule Draw finds the folder of the program in its Program JSON by the program's id in the index, downloads that folder's generation.json from the store, checks it (the SHA-256 of its gzip bytes against its path, the decoded size the index gives, a JSON object whose programs names every program of the folder), and stores it as the Generator JSON input's value with one undo event. Where the release has no generation file for the folder it is refused with a message saying so (AtlasSiteGenerationNotPublished). In release 2.2.0 only 90 of the 255 folders have one, and none of the *-detailed office folders, so the DOE small, medium, and large office cannot take Generator JSON from the site: an atlas limitation, not worked around (the release's own non-detailed office folders hold programs of other IDs, which the draw would not find).

Alternatives

  • Match across folders by name: refused; Retail and several restaurant keys are names of other prototypes' programs too.
  • Match department or general programs where no source program matches: refused; they merge source programs, which would mix programs in one key silently. Amended by D-218 (2026-11-01): a per-family crosswalk (DoeAtlasFolders.Crosswalk, AtlasMapFamily.Crosswalk) matches a key the 90.1 families split into several space types to the folder's one department mix whose members, read from the atlas release, are exactly those split spaces: the small hotel's GuestRoom to GuestRooms_Mixed (90.1-2007 to 2019) and the hospital's Office to Office_Mixed (90.1-2013, 2019). The mix is named in the window's coverage. The stand-alone retail's Retail stays a gap (its Sales_Mixed also holds Point_of_Sale, a key of its own), as does Gym - audience. Amended by D-246 (2026-11-01, the owner's G1, "no atlas mix"): the retail's core and front are keyed apart instead (Core_Retail, Front_Retail); a crosswalk may name a source program of the folder, matched before any department mix, so DOE Ref and 90.1-2007 give both keys their one Retail program.
  • Fill gaps with the illustrative preset (b) or an owner-approved crosswalk (c): (b) mixes sourced and illustrative values in one map; (c) is a source decision that needs its own evidence.
  • A hidden input holding the map's text: refused; a visible text input would invite wiring and editing a 1 MB document by hand. The text is the component's own state, like a value list's.
  • One program per key downloaded in the solve: refused, as in D-126 and D-208; the network is used only after a click.

Consequences

  • A DOE map can now be sourced from the atlas for 153 of 153 keys (DOE Ref families), 151 (90.1-2007), or 149 (90.1-2013 and 2019); the others need a preset by hand. Since D-246 and D-247, with each family's crosswalk: 154 of 154 (DOE Ref), and every key but the secondary school's Gym - audience in 90.1-2007 to 2019 (153 of 154) and in IECC (the 14 prototypes but the supermarket, 147 of 148).
  • A stored map is about the size of its programs' texts, some 30 kB per key (about 1 MB for the outpatient's 32 keys), in the definition.
  • The programs of the DOE offices' keys cannot be drawn until the atlas publishes a generation.json for the detailed folders.
  • A draw's recipe_sha256 is that of the bytes given (ADR-033 decision 10 as amended by D-207), so a generation.json taken from the site, compact JSON, records another checksum than the release zip's pretty-printed file of the same content; the drawn schedules are the same.
  • The recorded site tests/Lod.ProgramJson.Tests/Fixtures/site-doe/ (the 75 folders whole, and the store files of three maps and one generation file) is recorded again by scripts/atlas-fixtures/record_site_fixtures.py when the atlas changes them.