2026-06-14 08:18:06 +01:00
|
|
|
# homemaker-layout
|
2026-06-10 20:50:13 +01:00
|
|
|
|
|
|
|
|
Programme-driven building-layout search over slicing trees. A clean-room Python
|
|
|
|
|
successor to the Perl [Urb](../urb) project, intended to eventually be 100% Python.
|
|
|
|
|
|
|
|
|
|
## Why a rewrite
|
|
|
|
|
|
|
|
|
|
Urb represents a building as a binary slicing tree where room sizes are derived
|
|
|
|
|
**top-down** from division ratios. That makes room area an emergent property of
|
|
|
|
|
every cut above it, which:
|
|
|
|
|
|
|
|
|
|
- gives the genome low locality (a cut near the root rescales every descendant),
|
|
|
|
|
- makes target room sizes nearly impossible to hit, so the gaussian size penalty
|
|
|
|
|
dominates fitness, and
|
|
|
|
|
- defeats crossover (transplanted subtrees lose their proportions).
|
|
|
|
|
|
|
|
|
|
homemaker inverts this: leaves carry **target dimensions** from the programme and
|
|
|
|
|
division ratios are **solved bottom-up** for a fixed topology. The evolutionary
|
|
|
|
|
search then only explores topology + types + adjacency.
|
|
|
|
|
|
|
|
|
|
## Phase plan
|
|
|
|
|
|
2026-06-17 18:40:56 +01:00
|
|
|
1. ~~Solver experiment: port Urb's geometry, re-solve ratios from programme
|
|
|
|
|
targets, score the result against the original via the Perl oracle.~~ ✓
|
|
|
|
|
2. ~~Native Python fitness (retire the Perl oracle).~~ ✓
|
2026-07-31 09:57:45 +01:00
|
|
|
3. ~~Memetic search: canonical slicing genome + high-locality operators +
|
|
|
|
|
Nelder-Mead inner loop.~~ ✓
|
|
|
|
|
4. ~~Penalty reshaping: lexicographic `(-n_fails, fitness)` outer-search
|
|
|
|
|
comparison.~~ ✓
|
|
|
|
|
5. ~~Representation upgrade: canonical slicing encoding + bottom-up shape
|
|
|
|
|
feasibility, scaled to larger programmes.~~ ✓
|
|
|
|
|
6. **Search-quality experiments** (current): a long running series of
|
|
|
|
|
opt-in levers tried against the `harbor-house`, `health-centre`, and
|
|
|
|
|
`programme-house` example corpora — leaf-sharing, finish-time cell→room
|
|
|
|
|
collapse, ruin-and-recreate LNS, 2-opt polish, multi-use/co-located
|
|
|
|
|
leaves, adjacency-graph and bubble-diagram fitness signals, and more.
|
|
|
|
|
Most of these are negative/null results kept as opt-in flags or reference
|
|
|
|
|
code rather than defaults. See `DESIGN.md` §11 onward for the full,
|
|
|
|
|
numbered experiment log with methodology and results for each.
|
2026-06-10 20:50:13 +01:00
|
|
|
|
|
|
|
|
## Layout
|
|
|
|
|
|
2026-06-14 08:18:06 +01:00
|
|
|
- `src/homemaker_layout/dom.py` — read/write Urb `.dom` YAML into a `Node` tree.
|
|
|
|
|
- `src/homemaker_layout/geometry.py` — faithful port of Urb's top-down geometry.
|
|
|
|
|
- `src/homemaker_layout/programme.py` — parse `patterns.config` space requirements.
|
|
|
|
|
- `src/homemaker_layout/solver.py` — bottom-up ratio solve (scipy).
|
2026-06-17 18:40:56 +01:00
|
|
|
- `src/homemaker_layout/fitness.py` — native Python fitness evaluator.
|
|
|
|
|
- `src/homemaker_layout/fitness_cmd.py` — `homemaker-fitness` CLI (drop-in for `urb-fitness.pl`).
|
2026-07-18 12:39:23 +01:00
|
|
|
- `src/homemaker_layout/collapse_cmd.py` — `homemaker-collapse` CLI: finish-time global cell→room relabel of a `.dom`.
|
2026-06-17 18:40:56 +01:00
|
|
|
- `src/homemaker_layout/graph.py` — leaf-adjacency graph for programme-driven checks.
|
|
|
|
|
- `src/homemaker_layout/genome.py` — topology genome: base-floor tree + per-storey deltas.
|
|
|
|
|
- `src/homemaker_layout/operators.py` — high-locality mutation and subtree crossover.
|
|
|
|
|
- `src/homemaker_layout/innerloop.py` — ratio optimisation inner loop (Nelder-Mead / CMA-ES).
|
|
|
|
|
- `src/homemaker_layout/driver.py` — memetic search outer loop.
|
|
|
|
|
- `src/homemaker_layout/evolve.py` — `homemaker-evolve` CLI entry point.
|
|
|
|
|
- `src/homemaker_layout/oracle.py` — legacy Perl shim, kept for cross-validation only.
|
2026-07-31 09:57:45 +01:00
|
|
|
- `src/homemaker_layout/bubble.py` — 3D bubble-diagram adjacency fitness-signal
|
|
|
|
|
prototype (DESIGN.md §27); validated null, not wired into `fitness.py` —
|
|
|
|
|
reference only.
|
§39.4 completion + §39.5 retraction + §39.6: the usage namespace is NOT clean
Answering "are we clean". Generic namespace: yes. Usage namespace: no.
FINISH §39.4. The first sweep missed sites, found by a full re-grep:
graph.py's free-area budget, operators.py host-preference / keep-type /
repair-candidate, fitness.py's ("l","c","k") public-access test, bubble.py's
generic adjacency reference, and -- the important one -- cpsat.py, which was
still matching adjacency by raw startswith. graph.code_matches_requirement is
now the single public answer to "does this leaf count as the thing the
programme asked to be next to", shared by has_adjacency, has_vertical_connection
and cpsat.
RETRACT §39.5. It concluded 2g7.5's CP-SAT seeder win did not survive the
correction. That was wrong. The cause was the missed cpsat matcher above: the
exact solver was optimising a different relation than the scorer checked, so a
failing test reporting an incomplete sweep was misread as a baseline shift.
Re-measured over 6 seeds, cpsat now wins on both programmes (harbor 102/92,
maple 156/154). xfail removed.
REAL BUG UNDERNEATH: CP-SAT was never deterministic despite
num_search_workers=1 and a comment claiming it. neighbors[slot] is a set of
dom.Node, which hashes by id() -- a memory address -- so raw iteration made the
model-build order vary and CP-SAT returned a different equally-optimal
assignment each run (measured 194/180/171/182 over four identical aggregates).
sorted() on the slot indices fixes it. Also paired the wall-clock cap with
max_deterministic_time (solves run ~124ms against a 2s cap, so nothing was
timing out -- latent hazard, not the cause). solve_room_labels is now
reproducible on every captured instance; constructive_topology on the cpsat
path still is not, filed as homemaker-py-fdp (plausible contributor to b8g).
§39.6 THE SECOND NAMESPACE. Usage prefixes b/t/l/k (bedroom/toilet/living/
kitchen) classify programme codes by first letter and stay prefix-based by
design, but they are not inert: has_circulation deletes graph edges from them.
Four corpus rooms are misclassified by spelling -- la1 "Laundry Room" and li1
"Library Corner" as living, br1 "Staff Room" as bedroom, tr1 "Treatment Room"
as toilet. Measured on a health-centre seed: tr1 loses its edge to the adjacent
O, br1 loses its edge to t10 "Staff WC" -- both feed the connectivity fails §38
found persisting. Filed homemaker-py-sel; an explicit usage: key is the fix,
but it changes fitness for correctly-spelled programmes too so it needs its own
A/B.
DOCS. README gains a "Room codes and reserved names" section; CLAUDE.md and
AGENTS.md gain the same summary for agents. audit_programme_config.py now
reports the usage class each code picks up alongside the namespace and
satisfiability checks. DESIGN §37.2's note calling the c/o/s quirk "existing
product behaviour, not a bug" is annotated as superseded.
Corpus audit: zero generic-namespace violations across all ten example
programmes. 346 passed, same 7 pre-existing fixture failures, lint unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB
2026-08-26 10:09:14 +00:00
|
|
|
|
|
|
|
|
## Room codes and reserved names
|
|
|
|
|
|
|
|
|
|
Leaf types live in **three namespaces that share a first character**. Only the
|
|
|
|
|
first is enforced; the other two are conventions the fitness function reads, so
|
|
|
|
|
a room's *spelling* can change how it is scored.
|
|
|
|
|
|
|
|
|
|
**1. Generic structural types — `C`, `O`, `S` (reserved).** The leaves the
|
|
|
|
|
search itself creates: `C` circulation, `O` outside, `S` sahn (an outside court
|
|
|
|
|
that also serves as circulation). Always uppercase. A programme code spelled
|
|
|
|
|
exactly `C`, `O` or `S` is rejected at load.
|
|
|
|
|
|
|
|
|
|
**2. Programme room codes — anything else, lowercase.** `k1`, `b1`, `cr1`,
|
|
|
|
|
`of`, and single-character codes like `r` or `t`. These may start with **any**
|
|
|
|
|
letter: since DESIGN.md §39.4 the generic tests match `C`/`O`/`S` exactly, so
|
|
|
|
|
naming a room `cr1` no longer makes it circulation. (Before that fix it did —
|
|
|
|
|
and silently dropped it from the required-space check entirely.)
|
|
|
|
|
|
§39.7: access requirements become a declared `usage:` attribute (homemaker-py-sel)
Closes the second namespace sharing a first character with programme codes: the
usage prefixes b/t/l/k, under which a room silently inherited another room's
connectivity rules from its spelling.
usage is a plain, MANDATORY attribute of the space definition -- not a lookup
table. An interim design proposed a top-level usage_classes: table binding
author-coined names to behaviour; withdrawn, because an indirect name->behaviour
mapping living apart from the thing it describes is exactly the shape of the
prefix rule §39 exists to remove, it would be the only such table in a schema
where every other space property is a plain attribute, and the need it served
was already met -- "building specific" is about what a room is CALLED, and
name: is already free text.
Rule that settles it: a usage value exists iff the engine treats it differently
somewhere. Config selects among behaviours; it cannot invent them.
- programme.USAGES (living/kitchen/bedroom/toilet/utility/none) plus the
behaviour groupings PRIVATE_USAGES / PRIVATE_STRIPS / TOILET_STRIPS /
SOCIABLE_USAGES. Missing or unknown usage is a load error naming the code,
from BOTH parse paths.
- Code-level, never leaf-level: usage_of(leaf.type) is looked up fresh, so a
retype changes the class automatically. 51 sites assign leaf.type, and
share/share_type plus the r5a resurrection are the precedent for why
leaf-level attributes rot.
- graph.has_circulation takes the usage map and trims on declared class;
fitness.access and the public-access check likewise. fitness._t0 is DELETED --
no first-character type test remains anywhere in the codebase.
- utility is distinct from bedroom (same access requirements today) because it
is a different use and gives derive_interchange_classes an axis to relax on.
- A toilet now keeps its edge to a terminal room -- the Brand adjacency, which
the old b-before-t loop ordering severed.
- All 107 corpus entries migrated by experiments/migrate_usage_key.py, comments
and layout preserved.
MEASURED -- the connectivity model was ~4x too permissive. `none` is not
neutral: nothing is trimmed, so the graph may route THROUGH the room, and 34 of
52 codes had no class (Dental Surgery, Records Room, Utilities Closet all served
as corridors). Edges trimmed, prefix-inferred vs declared, 3 seeds each:
harbor-house 18 (9%) -> 79 (39%) inaccessible fails 0 -> 4
health-centre 12 (8%) -> 59 (40%) inaccessible fails 2 -> 3
maple-court 53 (17%) -> 123 (39%) inaccessible fails 1 -> 5
Re-baseline (seed 1, 20k, harbor): 58 fails (15h/43s) -> 61 (16h/45s), now
reporting 1-inaccessible-usable-space x2 plus level 0 and level 1 not connected.
The count rose because the objective got honest -- those failures were always
true of the layout and the old model could not see them. Every harbor number
before this was measured against a graph crediting routes through store
cupboards.
Sharpens §38.2: the objective pays x60-85 to delete circulation, and until now
the deleted corridors were not missed because storage stood in for them. With
that substitution gone, homemaker-py-2v1 is the remaining half -- and now
measurable, because the fails it should prevent actually fire.
350 passed (+5 new), same 7 pre-existing fixture failures, lint unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB
2026-08-26 13:39:41 +00:00
|
|
|
**3. Access requirements — the `usage:` attribute.** Every space declares one
|
|
|
|
|
of `living`, `kitchen`, `bedroom`, `toilet`, `utility`, `none`. Mandatory, no
|
|
|
|
|
fallback, and a missing or unknown value is a load error. It replaced a
|
|
|
|
|
first-character convention (`b`/`t`/`l`/`k`) under which a room silently
|
|
|
|
|
inherited another room's connectivity rules from its spelling — `la1` "Laundry
|
|
|
|
|
Room" was trimmed as a living room (DESIGN.md §39.7).
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
spaces:
|
|
|
|
|
la1:
|
|
|
|
|
usage: utility # controlled, drives engine behaviour
|
|
|
|
|
name: Laundry Room # free text, building-specific
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
A usage value exists only where the engine treats it differently, so the
|
|
|
|
|
vocabulary is closed: a new access class means new code, not new config. Check a
|
|
|
|
|
programme with:
|
§39.4 completion + §39.5 retraction + §39.6: the usage namespace is NOT clean
Answering "are we clean". Generic namespace: yes. Usage namespace: no.
FINISH §39.4. The first sweep missed sites, found by a full re-grep:
graph.py's free-area budget, operators.py host-preference / keep-type /
repair-candidate, fitness.py's ("l","c","k") public-access test, bubble.py's
generic adjacency reference, and -- the important one -- cpsat.py, which was
still matching adjacency by raw startswith. graph.code_matches_requirement is
now the single public answer to "does this leaf count as the thing the
programme asked to be next to", shared by has_adjacency, has_vertical_connection
and cpsat.
RETRACT §39.5. It concluded 2g7.5's CP-SAT seeder win did not survive the
correction. That was wrong. The cause was the missed cpsat matcher above: the
exact solver was optimising a different relation than the scorer checked, so a
failing test reporting an incomplete sweep was misread as a baseline shift.
Re-measured over 6 seeds, cpsat now wins on both programmes (harbor 102/92,
maple 156/154). xfail removed.
REAL BUG UNDERNEATH: CP-SAT was never deterministic despite
num_search_workers=1 and a comment claiming it. neighbors[slot] is a set of
dom.Node, which hashes by id() -- a memory address -- so raw iteration made the
model-build order vary and CP-SAT returned a different equally-optimal
assignment each run (measured 194/180/171/182 over four identical aggregates).
sorted() on the slot indices fixes it. Also paired the wall-clock cap with
max_deterministic_time (solves run ~124ms against a 2s cap, so nothing was
timing out -- latent hazard, not the cause). solve_room_labels is now
reproducible on every captured instance; constructive_topology on the cpsat
path still is not, filed as homemaker-py-fdp (plausible contributor to b8g).
§39.6 THE SECOND NAMESPACE. Usage prefixes b/t/l/k (bedroom/toilet/living/
kitchen) classify programme codes by first letter and stay prefix-based by
design, but they are not inert: has_circulation deletes graph edges from them.
Four corpus rooms are misclassified by spelling -- la1 "Laundry Room" and li1
"Library Corner" as living, br1 "Staff Room" as bedroom, tr1 "Treatment Room"
as toilet. Measured on a health-centre seed: tr1 loses its edge to the adjacent
O, br1 loses its edge to t10 "Staff WC" -- both feed the connectivity fails §38
found persisting. Filed homemaker-py-sel; an explicit usage: key is the fix,
but it changes fitness for correctly-spelled programmes too so it needs its own
A/B.
DOCS. README gains a "Room codes and reserved names" section; CLAUDE.md and
AGENTS.md gain the same summary for agents. audit_programme_config.py now
reports the usage class each code picks up alongside the namespace and
satisfiability checks. DESIGN §37.2's note calling the c/o/s quirk "existing
product behaviour, not a bug" is annotated as superseded.
Corpus audit: zero generic-namespace violations across all ten example
programmes. 346 passed, same 7 pre-existing fixture failures, lint unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB
2026-08-26 10:09:14 +00:00
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python experiments/audit_programme_config.py
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
which reports reserved-name collisions, the usage class each code picks up, and
|
|
|
|
|
whether each room's size/width/proportion/crinkliness targets are mutually
|
|
|
|
|
satisfiable at all.
|
