AEC Algorithms
Purple8 Hyper Graph ships a dedicated AEC (Architecture, Engineering & Construction) algorithm layer as part of Phase 8. It exposes 12 domain-specific sub-modules via the /aec/* REST API, all operating on the same node/edge graph primitives used everywhere else in Purple8.
Every endpoint accepts lightweight NodeIn / EdgeIn JSON — no IFC parser, no BIM authoring tool required. The algorithms run server-side; the optional AEC Algorithms UI page in the dashboard wraps every endpoint with sample fixtures and live result views.
Module overview
| Phase | Module | Endpoints | Description |
|---|---|---|---|
| 8.1 | Space Syntax / VGA | /aec/vga/* | Visibility graph analysis, integration scores, space hierarchy |
| 8.2 | Structural Topology | /aec/structural/* | Rigidity, load paths, critical members |
| 8.3 | BIM Graph | /aec/bim/* | IFC ingest, change-impact BFS, clash detection |
| 8.4 | Generative Design | /aec/design/* | Spatial allocation CSP, egress optimisation |
| 8.5 | MEP Flow Analysis | /aec/mep/* | Max-flow, fault isolation, thermal simulation |
| 8.6 | Graph Grammars | /aec/grammar/* | Code-compliance generation & validation |
| 8.7 | Spectral Analysis | /aec/spectral/* | Fiedler value, spectral bisection, robustness score |
| 8.8 | Topology Optimisation | /aec/topo/* | SIMP-on-graph, async job queue |
| 8.9 | MORL + GCN | /aec/morl/* | Multi-objective RL agent, Pareto front |
| 8.10 | MPNN Physics Kernel | /aec/mpnn/* | Message-passing nodal displacement prediction |
| 8.11 | Hypergraph | /aec/hypergraph/* | Clique/star expansion, isomorphism, transversal |
| 8.12 | IFC Graph Rewriting | /aec/ifc/* | Grammar-rule transform → VGA / structural / MEP graphs |
Shared request schema
Every endpoint that takes a graph accepts the same two arrays.
Node (NodeIn):
{
"node_id": "R1",
"node_type": "space",
"x": 0.0,
"y": 0.0,
"z": 0.0,
"properties": { "area": 20 }
}Valid node_type values: space, room, corridor, zone, joint, support, wall, beam, column, floor, roof, door, window, stair, pump, valve, ahu, panel, junction, outlet, generic.
Edge (EdgeIn):
{
"edge_id": "e01",
"edge_type": "CORRIDOR",
"source_id": "R1",
"target_id": "C1",
"weight": 1.0,
"capacity": 1.0,
"properties": {}
}8.1 — Space Syntax & Visibility Graph Analysis (VGA)
Analyses movement potential and spatial integration in architectural floor plans.
Build a visibility graph
Constructs a VGA from a vector floor plan (boundary polygon + optional obstacles).
POST /aec/vga/build{
"floor_plan": {
"plan_id": "ground-floor",
"boundary": [[0,0],[20,0],[20,15],[0,15]],
"obstacles": [[[4,4],[8,4],[8,8],[4,8]]],
"rooms": {
"R1": { "label": "Office A" },
"R2": { "label": "Office B" }
},
"entries": [[0, 7]],
"grid_resolution": 0.5
}
}Compute integration scores
Returns mean visual depth (integration) per node — higher = more spatially integrated.
POST /aec/vga/integration{
"node_ids": ["R1", "R2", "C1", "R3"],
"adjacency": {
"R1": ["C1"],
"R2": ["C1"],
"R3": ["C1"],
"C1": ["R1", "R2", "R3"]
},
"graph_id": "ground-floor"
}Response includes: integration_scores, mean_depth, global_integration.
Find articulation points (space hierarchy)
Identifies rooms/corridors whose removal would disconnect the floor plan.
POST /aec/vga/hierarchy{
"node_ids": ["R1", "R2", "C1", "R3"],
"adjacency": { "C1": ["R1","R2","R3"], "R1": ["C1"], "R2": ["C1"], "R3": ["C1"] }
}8.2 — Structural Topology & Load Paths
Analyses structural systems as graphs — joints are nodes, members are edges.
Check rigidity
Tests whether a structure satisfies Maxwell's rule: m ≥ 2j − 3 (2D) or m ≥ 3j − 6 (3D).
POST /aec/structural/rigidity{
"nodes": [
{ "node_id": "S0", "node_type": "support", "x": 0, "y": 0 },
{ "node_id": "J0", "node_type": "joint", "x": 0, "y": 4 },
{ "node_id": "J1", "node_type": "joint", "x": 4, "y": 6 }
],
"edges": [
{ "edge_id": "m0", "edge_type": "MEMBER", "source_id": "S0", "target_id": "J0", "weight": 2 },
{ "edge_id": "m1", "edge_type": "MEMBER", "source_id": "J0", "target_id": "J1", "weight": 5 }
],
"dimension": 2
}Response includes: is_rigid, member_count, joint_count, maxwell_lhs, maxwell_rhs, redundancies.
Trace load paths
Finds shortest weighted paths from every loaded joint to all support nodes.
POST /aec/structural/load-paths{
"nodes": [ ... ],
"edges": [ ... ],
"loads": { "J1": 50.0, "J2": 30.0 },
"weight_property": "stiffness"
}Identify critical members
Finds bridge edges (Tarjan) whose removal would disconnect the structural graph.
POST /aec/structural/critical-members8.3 — BIM Graph & Change Propagation
Works with IFC-style building graphs. Nodes represent BIM entities (walls, beams, doors…); edges represent containment, adjacency, or system connections.
Ingest an IFC file
Parses an IFC file (requires ifcopenshell) and builds an in-memory BIM graph.
POST /aec/bim/ingest{
"file_path": "/data/project.ifc",
"graph_id": "project-001"
}Propagate change impact
BFS from a modified element — surfaces all downstream elements that may be affected by the change.
POST /aec/bim/change-impact{
"nodes": [ ... ],
"edges": [ ... ],
"changed_guid": "C1",
"max_depth": 5,
"relation_filter": ["CONTAINS", "ADJACENT_TO"]
}Response includes: changed_guid, impacted_nodes, impact_depth_map, relation_breakdown.
Detect clashes
Identifies topological clashes between element types (e.g. beams crossing pipes).
POST /aec/bim/clashes{
"nodes": [ ... ],
"edges": [ ... ],
"type_a": "beam",
"type_b_prefix": "pipe"
}8.4 — Generative Design & Spatial Allocation
Allocate rooms
Constraint-propagation (AC-3 + backtracking CSP) solver that assigns rooms to zones subject to adjacency constraints and an area budget.
POST /aec/design/allocate{
"rooms": ["office", "meeting-room", "reception", "kitchen", "wc"],
"constraints": [
{ "room_a": "reception", "room_b": "office", "desirability": 1.0, "required": true },
{ "room_a": "kitchen", "room_b": "meeting-room", "desirability": 0.8, "required": false }
],
"area_budget": 500.0,
"max_attempts": 100,
"seed": 42
}Response includes: assignments, total_area, constraint_satisfaction_rate, attempts_used.
Optimise egress
Dijkstra / min-cut from all occupiable nodes to designated exit nodes — surfaces bottleneck edges and worst-case evacuation distances.
POST /aec/design/egress{
"nodes": [ ... ],
"edges": [ ... ],
"exit_node_ids": ["E1", "E2"]
}8.5 — MEP Flow Analysis & Fault Isolation
Max-flow / min-cut
Edmonds-Karp algorithm on a pipe/duct/cable network — returns maximum flow and the minimum cut edge set.
POST /aec/mep/max-flow{
"nodes": [
{ "node_id": "SRC", "node_type": "pump", "x": 0, "y": 0 },
{ "node_id": "J1", "node_type": "junction", "x": 3, "y": 0 },
{ "node_id": "OUT1", "node_type": "outlet", "x": 6, "y": 0 }
],
"edges": [
{ "edge_id": "p0", "edge_type": "PIPE", "source_id": "SRC", "target_id": "J1", "capacity": 10 },
{ "edge_id": "p1", "edge_type": "PIPE", "source_id": "J1", "target_id": "OUT1", "capacity": 7 }
],
"source_id": "SRC",
"sink_id": "OUT1",
"system_type": "water_supply"
}Response includes: max_flow, min_cut_edges, residual_graph_summary.
Fault isolation
BFS from a faulted component — returns all downstream affected nodes weighted by criticality score.
POST /aec/mep/fault-impact{
"nodes": [ ... ],
"edges": [ ... ],
"fault_node_id": "J1",
"criticality_map": { "OUT1": 2.0, "OUT2": 1.5 },
"system_type": "water_supply"
}Thermal zone simulation
Iterative steady-state heat-flow simulation across zones until temperatures converge.
POST /aec/mep/thermal/simulate{
"nodes": [ ... ],
"edges": [ ... ],
"outdoor_temp": -5.0,
"setpoints": { "SRC": 22.0, "OUT2": 18.0 },
"max_iterations": 100
}8.6 — Constrained Graph Grammars
Generate code-compliant floor plans
Generates N floor-plan graphs that satisfy the built-in compliance rule set (minimum room sizes, egress widths, required adjacencies).
POST /aec/grammar/generate{
"rooms": ["corridor", "office", "wc", "meeting-room"],
"n": 5,
"seed": 42,
"max_attempts": 20
}Response: array of n plan objects each with rooms, edges, and rule_results.
Validate a floor plan
Runs the compliance rule set against an existing plan graph.
POST /aec/grammar/validate{
"rooms": [
{ "node_id": "R1", "node_type": "space", "properties": { "area": 20, "label": "office" } },
{ "node_id": "R2", "node_type": "space", "properties": { "area": 5, "label": "wc" } }
],
"constraints": []
}Response: { "passed": [...], "failed": { "R2": ["min_area_wc"] }, "all_pass": false }
8.7 — Spectral Graph Theory
Spectral methods applied to structural networks — uses the Laplacian eigendecomposition.
Fiedler value (algebraic connectivity)
Computes λ₂ of the graph Laplacian. Low values → the structure is close to disconnecting; high values → well-connected and robust.
POST /aec/spectral/fiedler{
"nodes": [ ... ],
"edges": [ ... ],
"normalised": false,
"safety_threshold": 0.01,
"graph_id": "truss-A"
}Response includes: fiedler_value, fiedler_vector, is_connected, below_safety_threshold, natural_frequency_hz.
Spectral bisection / k-partition
Recursively bisects the structure using the Fiedler vector into k partitions — useful for load-zone planning or seismic analysis.
POST /aec/spectral/partition{
"nodes": [ ... ],
"edges": [ ... ],
"k": 4,
"graph_id": "truss-A"
}Response: partitions array, each with partition_id, node_ids, internal_edges, cut_edges.
Structural robustness score
Composite score combining Fiedler value and effective graph resistance. Returns a [0, 1] score: 1.0 = maximally robust.
POST /aec/spectral/robustness8.8 — Topology Optimisation
SIMP-on-graph: iteratively removes low-utilisation structural members until the target volume fraction is reached. Submitted as a background job because it can take several seconds.
Step 1 — queue the job
POST /aec/topo/optimise{
"bounding_box": [0, 0, 0, 10, 0, 6],
"resolution": 1.0,
"load_node_ids": ["J1"],
"support_node_ids": ["S0", "S1"],
"volume_fraction": 0.3,
"max_iter": 50
}Response: { "job_id": "uuid", "status": "pending" }
Step 2 — poll for the result
GET /aec/topo/{job_id}/resultResponse (when done):
{
"status": "done",
"result": {
"iterations": 34,
"converged": true,
"volume_fraction_achieved": 0.301,
"compliance_initial": 1842.3,
"compliance_final": 1104.1,
"compliance_reduction_pct": 40.1,
"retained_node_ids": [ ... ],
"removed_edge_ids": [ ... ]
}
}You can also build just the volume mesh without running the optimiser:
POST /aec/topo/build-mesh{ "bounding_box": [0,0,0,10,0,6], "resolution": 1.0 }8.9 — Multi-Objective RL + GCN Agent (MORL)
Trains a GCN policy with REINFORCE to simultaneously optimise three objectives: circulation efficiency, egress safety, and structural stability. Returns a Pareto front of non-dominated layout solutions.
POST /aec/morl/train{
"nodes": [ ... ],
"edges": [ ... ],
"zone_labels": ["A", "B", "C", "D"],
"reward_weights": {
"circulation": 0.4,
"egress": 0.4,
"structural": 0.2
},
"episodes": 50,
"seed": 42
}Response includes: pareto_front (array of non-dominated solutions), best_episode, reward_history, final_weights.
CPU-bound
Training is CPU-bound. Keep episodes ≤ 20 for interactive demos; use a worker process for production training runs.
8.10 — MPNN Physics Kernel
Message Passing Neural Network that propagates physics states (loads, displacements, stresses) across the structural graph — approximating FEM without a full matrix solve.
Full propagation
POST /aec/mpnn/propagate{
"nodes": [ ... ],
"edges": [ ... ],
"load_vector": {
"J1": [0, 0, -10],
"J2": [0, 0, -5]
},
"hidden_dim": 16,
"message_steps": 3,
"graph_id": "truss-A"
}Response: node_states map of predicted nodal displacements [dx, dy, dz] per node.
Incremental propagation
Re-propagates only within the k-hop neighbourhood of changed nodes — much faster for small edits.
POST /aec/mpnn/incremental{
"changed_node_ids": ["J1"],
"nodes": [ ... ],
"edges": [ ... ],
"prev_states": { "J0": [0,0,0], "J1": [0,0,0], "J2": [0,0,0] },
"k_hop": 2,
"graph_id": "truss-A"
}8.11 — Hypergraph Algorithms
AEC systems naturally form hyperedges — e.g. a single HVAC circuit that serves rooms R1, R2, and R3 simultaneously. The hypergraph module expands these into standard graphs for downstream analysis.
Build (expand) a hypergraph
Two expansion strategies:
- clique — adds a standard edge between every pair of nodes in a hyperedge
- star — adds a dummy centre node + spoke edges to each member
POST /aec/hypergraph/build{
"nodes": [ ... ],
"hyperedges": [
{ "hyperedge_id": "h1", "node_ids": ["R1","R2","C1"], "edge_type": "HVAC_ZONE" },
{ "hyperedge_id": "h2", "node_ids": ["R2","R3","C1"], "edge_type": "HVAC_ZONE" }
],
"method": "clique"
}Sub-hypergraph isomorphism
Finds all sub-hypergraph matches of a pattern hyperedge set within a larger target.
POST /aec/hypergraph/isomorphism{
"pattern": [
{ "hyperedge_id": "p1", "node_ids": ["A","B","C"], "edge_type": "ZONE" }
],
"target": [ ... ],
"max_matches": 10
}Minimum transversal
Finds the smallest set of nodes that intersects every hyperedge — useful for placing sensors or shut-off valves.
POST /aec/hypergraph/transversal{
"hyperedges": [
{ "hyperedge_id": "h1", "node_ids": ["R1","R2","C1"] },
{ "hyperedge_id": "h2", "node_ids": ["R2","R3","C1"] },
{ "hyperedge_id": "h3", "node_ids": ["R4","C1","E1"] }
]
}8.12 — IFC Graph Rewriting
Transforms an IFC-style node/edge graph into a clean analytical representation for a specific downstream pipeline using grammar rewriting rules.
POST /aec/ifc/rewrite{
"nodes": [ ... ],
"edges": [ ... ],
"target": "vga"
}target must be one of:
| Value | Output |
|---|---|
vga | Floor-plan graph ready for VGA integration scoring |
structural | Joint-and-member graph ready for rigidity / load-path analysis |
mep | Source-junction-sink graph ready for max-flow / fault analysis |
The rewriter handles cross-version IFC property normalisation (IFC2x3 ↔ IFC4 ↔ IFC4.3) and incremental diff-patch for live model updates.
Frontend UI
All 12 modules are accessible in the AEC Algorithms dashboard page at /dashboard/aec. Each tab includes:
- Pre-loaded sample fixtures (floor plans, structural trusses, MEP networks)
- All operation variants selectable via radio buttons
- Configurable parameters (dimension, load node, volume fraction, episode count…)
- Collapsible JSON result panel with error state highlighting
- Async job polling for Topology Optimisation (queue → poll pattern)
- Sample graph preview (expandable JSON of the fixture nodes/edges)
Exit criteria (Phase 8 benchmarks)
| Module | Target |
|---|---|
| VGA | Integration score correlation ≥ 0.99 vs depthmapX reference |
| Structural | Rigidity classifier correct on 50-member benchmark set |
| BIM | Round-trip IFC < 120 s for 50 MB file; clash precision ≥ 0.95 |
| MEP | Max-Flow matches NetworkX on 500-node pipe network |
| Grammar | ≥ 100 code-compliant plans/second |
| Spectral | Fiedler value matches NumPy to 6 decimal places |
| Topo Opt | Convergence ≤ 50 iterations; compliance reduction ≥ 40% |
| MORL | Pareto improvement within 500 training episodes |
| MPNN | MAPE ≤ 5% on FEM test set |
| Hypergraph | Correct isomorphism matches on 50-hyperedge test case |
| IFC Rewriting | Matches expert annotation on 5 reference IFC files |