MSD2GNN

Graph diffusion model that places the rooms of an apartment on the Modified Swiss Dwellings (MSD) dataset. It is conditioned on the unit's allocated region and a per-facade window-to-wall ratio (WWR) target. Room sizes are given by the brief; the model generates position and orientation.

Part of the PhD dissertation A Data-Driven Framework for Early-Stage Design towards Affordable and Sustainable Housing, Faculdade de Arquitetura, Universidade de Lisboa.

Built on MSD. This repository uses the Modified Swiss Dwellings dataset and benchmark by van Engelenburg et al. [1], derived from the Swiss Dwellings database by Archilyse AG [4]. All code here is original; no code from the official MSD repository [2] is included. If you use this repository, please also cite MSD and Swiss Dwellings (see Citation).

Status

Component	Status
Training notebook, run placement_v2 (no local mask probe)	Included: notebooks/02_train_placement_model.ipynb
Evaluation notebook: data validation, sampler, post-refinement, metrics, WWR tests	Included: notebooks/03_results_placement_model.ipynb
Training code for run placement_v5 (with local mask probe)	Not yet included
Enrichment code (MSD → graph_out_enriched)	Not yet included
Enriched graphs (graph_out_enriched)	To do: will be published separately; link to be added
Trained weights (best_placement_v2.pt, best_placement_v5.pt)	Not yet released
Python package and scripts (src/msd2gnn/, scripts/)	Structure only, not implemented yet

Both notebooks run locally (CPU or GPU) once the enriched graphs are in data/; evaluation also needs the weights. Their format is documented in notebooks/README.md.

Method

• Unit of generation: one apartment, as a graph of its rooms plus the adjacent shared circulation. Edges are door, passage or entrance connections.
• Rooms are oriented bounding boxes (cx, cy, w, h, sin 2θ, cos 2θ) in the floor-normalised frame. w and h come from the brief and are held fixed throughout diffusion; only centre and orientation are generated.
• Conditioning: room type and zoning, floor footprint statistics, the floor envelope and the unit's allocated region (two 16 × 16 rasters), and a WWR target for N, E, S and W.
• Denoiser: 4 GATv2 layers [6], hidden size 128, predicting x₀. It is trained and sampled as a DDPM with 1,000 steps [5].
• Symmetry breaking: a random identity vector per room, held fixed along each sampling trajectory, as in HouseDiffusion [10].
• Local mask probe: each room reads both rasters at nine points on its current box at every denoising step.
• Losses: placement error on the free columns with matching within room types; relative offsets along edges; spread; rotation-aware overlap; corner-sampled containment; a soft-render loss comparing occupancy maps.
• Post-refinement (optional): a short optimisation of room centres for overlap, containment and coverage. It uses inputs only, never ground truth.

Settings of both runs are listed in configs/model/: placement_v5 (the evaluation default) and placement_v2 (trained by the training notebook). They differ in the local mask probe and the loss weights.

Repository structure

MSD2GNN/
├── notebooks/          # training and evaluation notebooks            (working)
├── data/               # not tracked; see data/README.md
├── tools/              # code-overlap check against MSD               (working)
├── configs/            # run settings                                  (documentation)
├── src/msd2gnn/        # Python package                               (structure only)
├── scripts/            # pipeline entry points 01 → 05                (structure only)
├── slurm/              # cluster job template                         (structure only)
└── docs/figures/       # figures for this README

Installation

git clone https://github.com/aydanaghabayli/MSD2GNN.git
cd MSD2GNN

# Install PyTorch and PyTorch Geometric first (CPU build, or the one for your CUDA version):
#   https://pytorch.org/get-started/locally/
#   https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html
pip install -e ".[model,notebooks]"

Data

MSD is not redistributed here. The notebook uses the release published by the MSD authors on Kaggle, in the folder modified-swiss-dwellings-v2. MSD is derived from Swiss Dwellings v3.0.0 [4] (CC BY 4.0).

The enriched graphs will be published separately (to do; link to be added). Training needs the train and test splits; evaluation needs only the test split and the weights. Both read data/ inside the repository (layout in data/README.md). To keep them elsewhere, set DATA_DIR in the notebook's first cell or the MSD2GNN_DATA environment variable.

Usage

cd MSD2GNN
jupyter lab notebooks/02_train_placement_model.ipynb        # train   -> data/best_placement_v2.pt
jupyter lab notebooks/03_results_placement_model.ipynb      # evaluate (set RUN_NAME to the run)

In each notebook the first code cell holds all settings, including a QUICK mode for a short run on a CPU. Inputs and settings are described in notebooks/README.md.

Metrics

The notebook reports the following on the MSD test split:

Metric	What it shows
Size match	Must be exactly 0, because sizes are copied from the input
Within-apartment R², cx and cy (raw and type-matched)	Whether placement is learned. Read against the null (room-type mean), not against 0. Pooled R² is not used because most variance lies between apartments
Spread ratio	Bunching of generated rooms relative to ground truth (1.00 = same)
Overlap, generated vs real	Share of area covered twice (rotation-aware)
Diversity	Mean centre distance between two samples for the same brief
WWR target sweep, lift per facade	Whether pushing the WWR target toward a facade moves habitable rooms there (positive on all four = causal effect)
WWR compliance	Target vs achieved WWR under a fixed window-transfer rule, with a shuffled-target control

Citation

This repository: use the "Cite this repository" button on GitHub (generated from CITATION.cff).

Please also cite the dataset this work builds on. BibTeX for all references is in references.bib.

@inproceedings{vanengelenburg2024msd,
  author    = {van Engelenburg, Casper and Mostafavi, Fatemeh and Kuhn, Emanuel and Jeon, Yuntae and
               Franzen, Michael and Standfest, Matthias and van Gemert, Jan and Khademi, Seyran},
  title     = {{MSD}: A Benchmark Dataset for Floor Plan Generation of Building Complexes},
  booktitle = {Computer Vision -- {ECCV} 2024},
  editor    = {Leonardis, Ale{\v{s}} and Ricci, Elisa and Roth, Stefan and Russakovsky, Olga and
               Sattler, Torsten and Varol, G{\"u}l},
  series    = {Lecture Notes in Computer Science},
  volume    = {15116},
  pages     = {60--75},
  publisher = {Springer},
  address   = {Cham},
  year      = {2024},
  doi       = {10.1007/978-3-031-73636-0_4}
}

@misc{standfest2023swissdwellings,
  author    = {Standfest, Matthias and Franzen, Michael and Schr{\"o}der, Yvonne and Gonzalez Medina, Luis and
               Villanueva Hernandez, Yarilo and Buck, Jan Hendrik and Tan, Yen-Ling and
               Niedzwiecka, Milena and Colmegna, Rachele},
  title     = {Swiss Dwellings: A large dataset of apartment models including aggregated geolocation-based
               simulation results covering viewshed, natural light, traffic noise, centrality and geometric analysis},
  version   = {3.0.0},
  publisher = {Zenodo},
  year      = {2023},
  doi       = {10.5281/zenodo.7788422}
}

References

Dataset

1. van Engelenburg, C., Mostafavi, F., Kuhn, E., Jeon, Y., Franzen, M., Standfest, M., van Gemert, J., & Khademi, S. (2024). MSD: A Benchmark Dataset for Floor Plan Generation of Building Complexes. In A. Leonardis et al. (Eds.), Computer Vision – ECCV 2024 (LNCS 15116, pp. 60–75). Springer. https://doi.org/10.1007/978-3-031-73636-0_4
2. van Engelenburg, C., et al. (2024). MSD: code repository [Software]. GitHub. https://github.com/caspervanengelenburg/msd (official MSD code; not included here)
3. van Engelenburg, C., Khademi, S., Mostafavi, F., Standfest, M., & Franzen, M. (2023). Modified Swiss Dwellings: a Machine Learning-ready Dataset for Floor Plan Auto-Completion at Scale (Version 2) [Dataset]. 4TU.ResearchData. https://doi.org/10.4121/e1d89cb5-6872-48fc-be63-aadd687ee6f9.v2 (earlier release, ICCV 2023 challenge)
4. Standfest, M., Franzen, M., Schröder, Y., Gonzalez Medina, L., Villanueva Hernandez, Y., Buck, J. H., Tan, Y.-L., Niedzwiecka, M., & Colmegna, R. (2023). Swiss Dwellings: A large dataset of apartment models including aggregated geolocation-based simulation results covering viewshed, natural light, traffic noise, centrality and geometric analysis (Version 3.0.0) [Dataset]. Zenodo. https://doi.org/10.5281/zenodo.7788422

Methods

5. Ho, J., Jain, A., & Abbeel, P. (2020). Denoising Diffusion Probabilistic Models. Advances in Neural Information Processing Systems 33 (pp. 6840–6851).
6. Brody, S., Alon, U., & Yahav, E. (2022). How Attentive are Graph Attention Networks? International Conference on Learning Representations (ICLR). https://arxiv.org/abs/2105.14491

Software

7. Paszke, A., et al. (2019). PyTorch: An Imperative Style, High-Performance Deep Learning Library. Advances in Neural Information Processing Systems 32 (pp. 8024–8035).
8. Fey, M., & Lenssen, J. E. (2019). Fast Graph Representation Learning with PyTorch Geometric. ICLR Workshop on Representation Learning on Graphs and Manifolds. https://arxiv.org/abs/1903.02428
9. Hagberg, A. A., Schult, D. A., & Swart, P. J. (2008). Exploring Network Structure, Dynamics, and Function using NetworkX. Proceedings of the 7th Python in Science Conference (SciPy 2008) (pp. 11–15).

Related work

10. Shabani, M. A., Hosseini, S., & Furukawa, Y. (2023). HouseDiffusion: Vector Floorplan Generation via a Diffusion Model with Discrete and Continuous Denoising. Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR) (pp. 5466–5475).
11. Kuhn, E. (2023). Adapting HouseDiffusion for conditional Floor Plan generation on Modified Swiss Dwellings dataset. arXiv:2312.03938. https://arxiv.org/abs/2312.03938

Acknowledgements

This work was supported by the Fundação para a Ciência e a Tecnologia (FCT) under the scope of the MIT Portugal MPP2030-FCT PhD Grant, reference RT/BD/154270/2022, and by the MIT Portugal Program.

This work was supported by FCT I.P./AI2 under Project 2026.03121.CPCA.A1 at Deucalion supercomputer, jointly funded by EuroHPC JU and Portugal.

Supervision: José Nuno Beirão, Faculdade de Arquitetura, Universidade de Lisboa.

Thanks to the MSD authors (TU Delft) for the dataset and benchmark, and to Archilyse AG for the Swiss Dwellings database.

Licence

Code: MIT. Third-party data and software terms are listed in THIRD_PARTY_NOTICES.md; the MSD and Swiss Dwellings data keep their own licences.