Stomra Guides

OpenEik · Guide

Disciplines in one model

How architecture, structure, building services and electrical share one OpenEik model, merge their lines of work and approve each other's changes.

project/ · the datums the project record · levels · grids · materials each namesits level and type architecture/ structure/ ventilation/ plumbing/ electrical/ site/ Interwoven by hosts slab edges on slabs, wall tops on roofs Loose: placed by coordinates they name no wall, slab or beam
Every discipline shares the datums in project/. Architecture and structure name each other a great deal; pipes, ducts and electrical devices name only their level, their type and their own records.

One model, a folder per discipline

An OpenEik building is one model: one folder, one file for each record. Each discipline has a top folder of its own, and every discipline shares the project's folder. The folder a record sits in is the discipline that owns it.

FolderHoldsPlaced by
project/the project record (its frame, millimetres, Z up), the levels, the grids, the materialsshared by everyone
architecture/walls, slabs and roofs that bear nothing, ceilings, doors, windows, rooms, stairs that carry nothing, railings, furniture, fire equipmentthe architect
structure/beams, columns, foundations, slab edges, rebar, mesh, structural plates and connectors, and the walls, slabs, roofs and stairs that bearthe structural engineer
ventilation/ducts and air devicesthe ventilation engineer
plumbing/pipes and every other terminalthe heating and plumbing engineer
electrical/electrical devices, cable carriers and cablesthe electrical engineer
sprinkler/records whose owner is set to sprinkler by handthe sprinkler engineer
site/terrain, grading, property lines, planting, roads, parkingthe landscape or civil engineer
types/<discipline>/the types, in the same discipline foldersas their elements
drawings/<discipline>/views and sheetsas their records

An element's path is worked out from the record: <discipline>/<level>/<category>/<id>.json. A supply duct on the ground floor is, for example, ventilation/level-0/duct/duct-hall-supply.json.

The folder follows the owner

One set of rules gives every record its owner. A wall made structural moves to structure/, its type with it. An owner set by hand on a record wins over every rule.

Meaning never comes from the folder

A reader takes a record for what it says. The folder only says who owns it.

Nothing is lost

A tool that does not handle a discipline keeps that discipline's records as they are when it writes the model back. A tool that knows nothing of ducts does not drop them.

Models written in OpenEik 0.1 file records by category instead, with pipes, ducts and terminals together in systems/. A reader of later versions reads both layouts, and a building moves to the owners' layout once, in the version that migrates it.

The datums

The datums are what every discipline works to: the project record, whose frame, units and zero every coordinate is measured in; the levels, each a named horizontal datum; and the grids. They are the contract between the disciplines.

What each discipline names

Every element names its level and a type of its own category. Beyond that, the disciplines differ a great deal in what they name of each other.

Architecture and structure name each other

A slab edge is hosted by a slab or a foundation; rebar by a slab, a foundation, a beam or a column; mesh by a slab, a foundation or a wall. A wall's top attaches to a roof, a floor, a ceiling or a foundation, and a column's base to its host. Framing members and trusses are made from walls and roofs, and member ends join other members and plates. Most of these references must resolve, and a check refuses a model where they do not.

Building services and electrical name very little

A pipe or a duct is a run: points in plan, a height for each above its level, a size and a system. Besides its level and its type it names only the terminal each of its ends joins. A valve, a pump or a damper in a run is hosted on that run and names nothing else. An electrical device sits against a wall face by its coordinates and names no wall; its circuit, its feed and its switches are electrical records too.

What follows

A moved wall moves no duct

The model holds no statement that a duct passes through a wall. When the architect moves a wall, the duct stays where it is.

Holes belong to the host

A slab's voids, a wall's recesses and a shaft are the architect's or the structural engineer's records. Take the duct away and the hole stays, for its owner to close.

A hole is asked for, not cut

A run that crosses another discipline's element asks for a void with a provision: a record of its own, which the element's owner answers by cutting the void or declining with a reason.

One exception in Stomra: a downpipe made from a gutter is hosted on that gutter, so it follows the gutter when it moves and goes with it when it is deleted.

Merging lines of work

Each discipline works on a line of its own: a clone in its own store, a fork on a host such as EikHub, or an alternative in the same project. Lines merge by record and by field, never by text.

Two disciplines that write in their own folders therefore do not conflict, and merging often keeps it so. In a test on a copy of the example L-house, an example building of 130 elements in architecture and structure, a small HVAC and drainage set was added in this way:

What was doneWhat the tools said
An HVAC line merged with the architect's line, both changing the ground slab11 changes, 0 conflicts, 0 errors; the slab merged field by field
An HVAC model built on its own from the datums, merged into the whole building170 changes, 0 conflicts, 0 errors
Two lines raised the same wall, to 2700 and to 2600 mm1 conflict, named, with both values
An HVAC model that replaced the shared levels with its ownmerge refused: 130 errors, every architectural element without its level; nothing written

A merge and a diff also say which top folders each side changed, and name a change to the datums. A line that strays into another discipline's folder shows up at once, for example as architecture 1 changed beside its own additions.

Taking a discipline out

Because the services records stand on the datums alone, they come apart cleanly. In the same tests:

RemovedResult
All pipes, ducts and terminals, with their types0 errors, 0 warnings
Architecture and structure, leaving the HVAC model alone0 errors, 0 warnings
Architecture alone18 errors: each slab edge lost its slab
Structure alone0 errors in this house; a house whose walls attach to foundations would give some

Two things stay behind when the services go: the void cut in the slab for the pipe, which is the slab's to close, and the ids of the removed types in the model's list order, which readers ignore and the next save tidies away.

Delete with commands rather than by removing files. A delete takes with it what is hosted by the element and the view items that name it, and a type cannot be deleted while anything still uses it, so nothing is left dangling.

Ownership: who approves what

On most projects several firms write one building. OpenEik says in the model who owns which paths, the way a code base's owners file does: project/owners.json names the project's parties and the paths each owns. A change to an owned path needs an owner's approval before it joins the building's main line.

{
  "format": "openeik-owners/0.1",
  "parties": [
    {"id": "arch", "name": "Example Architects", "discipline": "architecture"},
    {"id": "struct", "name": "Example Structures", "discipline": "structure"},
    {"id": "hvac", "name": "Example Building Services"}
  ],
  "rules": [
    {"owners": ["arch"], "paths": ["**"]},
    {"owners": ["struct"], "paths": ["structure/**", "types/structure/**", "drawings/structure/**", "fabrication/**"]},
    {"owners": ["hvac"], "paths": ["ventilation/**", "types/ventilation/**", "plumbing/**", "types/plumbing/**"]},
    {"all": true, "owners": ["arch", "struct", "hvac"], "paths": ["project/project", "project/levels", "project/grids/*"]}
  ]
}

A party may say its discipline and the organisation it is, by an Internet domain of its own. Which people and accounts act for a party is the host's to say; the model names no accounts.

Coordination is a check

Since the model keeps no links between a run and the walls it passes, coordination is a check that a tool runs on the derived bodies (or on a supplier's declared geometry), not a reference kept in the model. OpenEik's clash check takes the pipes and ducts against the bodies of the architecture and the structure:

clash  pipe-wc-sewage  passes through slab study-slab (architecture, ground-eps)
1 clash: 1 run against 1 element of the architecture and the structure (tolerance 1 mm)

Here the sewage pipe, laid at a fall from the WC, runs in the insulation of the ground slab, which no record of either discipline says. A run passes through an element where its axis enters it, and grazes it where only its side does; a run that only touches a face within the tolerance is no clash, and a run through a void or an opening does not clash. The answer is for the two disciplines to agree: a void, a sleeve, or the pipe laid under the slab.

Working across disciplines, step by step

  1. Share the datums. Start each discipline from the building's project record, levels and grids, with their ids. Treat a change to them as everyone's decision.
  2. Work on a line each, and merge often. A fork, a clone or an alternative. Small merges keep conflicts small and early.
  3. Write in your own folders. Need a hole in a slab or a shaft? Ask for it with a provision, or offer the change as a proposal to the slab's owner, rather than editing their record.
  4. Place services by coordinates on the shared levels, and find clashes with a check, not with links.
  5. Delete with commands, so that what depends on a record goes with it and nothing dangles.
  6. Bring in services from another program as OpenEik records written by a bridge or an agent, on a line of their own, or link its IFC for reference, which is how Stomra reads IFC: shown beside the model, not taken into its records.