Stage BG5: DOE skylights spread as the source does (design note)

Status: Done (D-252) · Date: 2026-11-01 · Decided by: Cheng Xuan Li (the owner's principle for skylights, "follow the source evidence", and the stage's brief: place the skylights as the source geometry each family cites does, scaled to BEMGen's roof, keeping BG4's area); the BG5 builder (the realisation below) · Decisions: D-249, D-250, ADR-039, ADR-012 (skylights), DOE geometry note S5; new: D-252, ADR-039 amended · Branch: feat/bg5-skylight-layout in D:/bg-bg5, from main at 7d9cc08

BG4 (D-249) gave each DOE key the skylight area of its family's source geometry but kept S5's distribution, one skylight centred on each roof. D-250 found the controlled floor fractions equal to PNNL's and the controlled lighting fractions a quarter to a half of them, because one centred skylight's toplit area is far smaller than that of the source's many spread ones. This stage places the skylights as the source places them.

1. The source layouts

scripts/doe-geometry/family_skylights.py now also reads every skylight of every source file it already reads (D-249: the PNNL 90.1 and IECC IDFs, the DOE Ref v1.4 IDFs, the openstudio-standards supermarket geometry) and the layout record's own reference file (DOE Ref v1.4 New2004 Chicago), as a rectangle along the plan axes in its zone's coordinates. Per key, the layout is the frame (the bounding box of the key's source roof; for the supermarket's Sales, whose skylights lie over Main Sales only, the roofs of its four sales spaces) and each skylight from the frame's lower-left corner, to 0.1 mm. The script refuses a skylight that is not such a rectangle, a multiplier other than 1, a zone turned from north, a key of more than one zone, a frame that is not the record zone's size within 0.01 m, and two layouts of one key at one skylight ratio.

Type, key	Skylight ratio	Source layout (count × size; grid; where on the roof)	Found in
Stand-alone retail Core_Retail (frame 54.27 × 32.27 m)	0.004179	8 × 0.914 m square (3 ft), 2 rows × 4, pitch 4.57 m; the north-west corner, x 1.83–16.46, y 24.96–30.44 of the frame	90.1-2007, IECC 2006, 2009 everywhere; 6A, 6B, 7A, 8A of 90.1-2013, 2019, IECC 2015–2021
	0.01486	16 × 1.219 m square (4 ft), 4 × 4, pitch 6.40 × 7.11 m; the west half, x 3.35–23.78, y 6.35–28.92	90.1-2013, 2019, IECC 2015–2021 outside 6A–8A; IECC 2012 everywhere
Warehouse Bulk (45.72 × 70.10 m)	0.004638	10 × 1.219 m, 5 rows × 2, pitch 6.10 m; the south-west corner, x 2.44–9.75, y 2.44–28.04	as the retail's 0.004179
	0.014842	32 × 1.219 m, 4 rows × 8, pitch 5.58 × 8.64 m; the southern 31 m of the 70 m, y 3.96–31.09	as the retail's 0.01486 without IECC 2012
	0.022263	48 × 1.219 m, 6 rows × 8, the same pitch; y 3.96–48.36	IECC 2012
Warehouse Fine (45.72 × 30.48 m)	0.014935	14 × 1.219 m, 2 rows × 7, pitch 5.72 × 7.62 m; the north half, y 18.44–27.28	as the bulk's 0.014842
	0.018135	17 × 1.219 m, the 14 and three more in a row below at the east	IECC 2012
Supermarket Sales (53.06 × 43.82 m)	0.015344	24 × 1.219 m, 6 rows × 4, pitch 6.25 m; over the west half of the main sales, x 3.35–23.32, y 7.93–40.39	90.1-2013, 2019 (openstudio-standards ASHRAE9012013SuperMarket.osm)
Primary school Gym (21 × 17 m)	0.037473	9 × 1.219 m, 3 × 3, pitch 7.0 × 5.67 m, over the whole roof	every 90.1 and IECC family; the record (New2004)
Secondary school Gym (38 × 52 m)	0.040626	54 × 1.219 m, 9 rows × 6, over the whole roof	every 90.1 and IECC family; the record
Secondary school Gym - audience (24 × 52 m)	0.042906	36 × 1.22 × 1.219 m, 9 rows × 4, over the whole roof	every 90.1 and IECC family; the record

The layouts follow BG4's climate groups exactly: one layout per key and ratio, and the New2004 gyms equal the PNNL ones to 0.1 mm. No other type has a skylight in any source (D-249). The retail's, warehouse's, and supermarket's skylights do not cover their roofs: PNNL puts them in a part of the roof, and so does BEMGen now.

2. The placement rule

• Data. family-skylights.json format version 2 adds, per type, layouts: per key and skylight ratio the frame, the skylights, and foundIn (the families and climate zones, the record). The families' groups and ratios are unchanged.
• Core. SkylightLayout (Lod.Core.Geometry) holds one layout. Place(roof, area) maps the frame onto the roof's bounding box along the plan axes: each skylight's centre goes to the same place relative to the box (its x and y scaled by the roof's width and depth over the frame's), and every skylight is scaled about its centre by one factor k = √(area / Σ source skylight area), so the skylights keep their shape and together have the roof's glazed area. A skylight that leaves the roof or meets another is SkylightDoesNotFit, never moved or capped; the plan generators then give that ceiling one centred skylight of the same area (S5) with the warning SkylightLayoutNotFitted, so no parameters valid before are refused (the review found the warehouse's fine storage, an L around the office, losing four of its 14 source skylights to the office at a 12 m band or a 20 m deep office). Each ceiling of a zone takes the whole layout with its own area; no DOE zone has two. PlannedZone.SkylightLayouts carries a zone's layouts; PlanBuilder gives a zone whose preset's skylight ratio is one of theirs (within ToleranceSettings.AbsoluteFraction) that layout's skylights of ratio × ceiling area, any other ratio one centred skylight (S5), and records SkylightLayouts in the plan's provenance only for zones whose ceilings took it.
• The skylight area is BG4's. The area stays the preset's ratio × the zone's ceiling area, so the totals, the validation, and the window areas are unchanged. At the generators' defaults the frame is the roof's box and k is 1 where BEMGen's roof is the source's (the retail core, the warehouse bulk, the supermarket sales, the gyms): the skylights stand where the source's do. The warehouse's fine storage is smaller than its source roof by the office (G4, the office drawn to the storey height has its own roof), so its 14 skylights are 1.111 m instead of 1.219 m wide, at the source's places.
• Generators. DoeFamilySkylights.WithSourceLayouts gives the zones of the stand-alone retail, warehouse, supermarket, and school generators the layouts of their program keys. Any preset, illustrative, atlas, or suite, whose skylight ratio is a source's gets that source's layout: the schools' illustrative presets (the record's New2004 ratio) so get their gyms' grids too.
• Later steps. CentredSkylights.Place keeps the skylights of a target ceiling that is a detailed ceiling unchanged (their overlap is the area of both within the area tolerance), so No Simplification and the stacker keep the layout on every unchanged roof. A merged or split ceiling still takes one centred skylight of the area under it (ADR-012): the simplified zonings do not keep the source's spread.

3. The prototype check again (D-252, after D-250)

The same check as D-250: this branch's suite generator wrote the 90.1-2019 stand-alone retail and warehouse, 5A Buffalo TMY3, No Simplification, Stack, settings.daylighting: true, record glazing, the atlas release 2.3.0 filled programs and the Example envelope (BG4's spec, its suite id renamed); the same scratch script read the controls of these IDFs and of the PNNL 90.1-2019 Buffalo IDFs.

Prototype	Controlled floor fraction, BEMGen / PNNL (D-250)	Controlled lighting fraction, BEMGen / PNNL (D-250)
Stand-alone retail	0.698 / 0.698 (0.698)	0.402 / 0.387 (0.090)
Warehouse	1.000 / 1.000 (1.000)	0.618 / 0.492 (0.208)

Per zone, the share of its lights the points control, BEMGen / PNNL: retail core 0.515 / 0.500; warehouse bulk 0.528 / 0.500, fine 0.710 / 0.500, office 0.768 / 0.390. Both IDFs ran a year in EnergyPlus 26.2.0 4bd7a1f26f (eplus-check): 0 severe; the retail passed with its one expected PartialDaylightingControl; the warehouse reported the same one unexpected warning as in D-250, Site:GroundTemperature:BuildingSurface: Some values fall outside the range of 15-25C., from the Example envelope's ground.

Where the gap left comes from. The toplit areas are now the source's, and BEMGen's shares are the code rule's geometric fractions on them (openstudio-standards' space_daylighting_fractions_and_windows, ADR-037): the toplit area over the zone's floor, split between two points. PNNL's IDFs do not use the geometry here: every toplit retail and warehouse zone of the 90.1-2019 models has two points of 0.25 each in every climate checked (Miami, Buffalo, Seattle), whatever its toplit area. Where the geometric fraction is near 0.5 the two agree (the retail core 0.515, the bulk storage 0.528); the fine storage's 14 skylights, grown by 0.7 × the 8.5 m height, light 71 % of its floor, which BEMGen controls and PNNL caps at 0.5. Of the warehouse's 0.126 excess, the fine storage gives about two thirds, the office about a quarter (unchanged from D-250: drawn to the storey height, G4, it has taller windows, and PNNL gives it 0.29 + 0.10), the bulk storage the rest. Closing it would mean taking PNNL's fixed fractions instead of the code rule's geometry, a change of the daylighting rule (ADR-037), for the owner.

4. What else it touches

• Other layouts. Only the five types whose sources have skylights get layouts; every other type has none in any source (D-249) and is unchanged. Of the five, a zone whose preset has a source's ratio gets its spread skylights: the retail, warehouse, and supermarket through atlas maps and record-glazing suites of a family with skylights (BG4), the schools' gyms also with the illustrative presets.
• Snapshots. None changed.
• The LOD study. Its suites stay on their pinned inputs (D-244) and are not rerun here. If rerun with this BEMGen, its 90.1 retail, warehouse, supermarket, and primary school reference sites (No Simplification, Stack, record glazing) would carry the source's spread skylights, and its zonings that merge or split the skylit zones one centred skylight per target, with the same area; the study's specs do not turn daylighting on, so the difference is in the solar gains' distribution only.