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/. 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.
| Folder | Holds | Placed by |
|---|---|---|
project/ | the project record (its frame, millimetres, Z up), the levels, the grids, the materials | shared by everyone |
architecture/ | walls, slabs and roofs that bear nothing, ceilings, doors, windows, rooms, stairs that carry nothing, railings, furniture, fire equipment | the architect |
structure/ | beams, columns, foundations, slab edges, rebar, mesh, structural plates and connectors, and the walls, slabs, roofs and stairs that bear | the structural engineer |
ventilation/ | ducts and air devices | the ventilation engineer |
plumbing/ | pipes and every other terminal | the heating and plumbing engineer |
electrical/ | electrical devices, cable carriers and cables | the electrical engineer |
sprinkler/ | records whose owner is set to sprinkler by hand | the sprinkler engineer |
site/ | terrain, grading, property lines, planting, roads, parking | the landscape or civil engineer |
types/<discipline>/ | the types, in the same discipline folders | as their elements |
drawings/<discipline>/ | views and sheets | as 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.
- Two lines of work that keep the same datums, with the same ids, merge. Two that do not, do not.
- Levels merge as one list by id, so a change to a level's id or elevation, or to the project's origin, is a decision for everyone, not one discipline's edit.
- A discipline that starts its own model starts from the building's datums: the project record, the levels and the grids, copied with their ids.
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.
- Records match by id. A record changed on one side only is taken from that side.
- Both sides changed one record? It is merged field by field. A wall renamed by one side and raised by the other gets both changes.
- A conflict only where it is real: both sides change the same field to different values, one side changes a record the other deleted, or both add different records with one id.
- The result is checked whole. A merge that would leave a host, a type or a level missing is refused, and the refusal names the records.
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 done | What the tools said |
|---|---|
| An HVAC line merged with the architect's line, both changing the ground slab | 11 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 building | 170 changes, 0 conflicts, 0 errors |
| Two lines raised the same wall, to 2700 and to 2600 mm | 1 conflict, named, with both values |
| An HVAC model that replaced the shared levels with its own | merge 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:
| Removed | Result |
|---|---|
| All pipes, ducts and terminals, with their types | 0 errors, 0 warnings |
| Architecture and structure, leaving the HVAC model alone | 0 errors, 0 warnings |
| Architecture alone | 18 errors: each slab edge lost its slab |
| Structure alone | 0 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/*"]}
]
}
- The last matching rule wins. Here the architect owns everything no later rule gives to another, the owners file itself included.
- A party owns its discipline's folders by one plain rule:
<discipline>/**, its types and its drawings. Rules name folders, not categories, because the folder already follows the owner. - The datums need everyone. A rule with
"all": trueneeds every owner's approval, which is how a change to the levels becomes a shared decision. - An application's folder, such as a structural analysis kept beside the building, gets one rule of its own, owned by the discipline its work serves.
- The model states it, a host enforces it, a tool reports it. EikHub lets a proposal join the main line once each owner it needs has approved it, and shows which parties a change needs and which have approved. A diff or a merge reports the same.
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
- 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.
- Work on a line each, and merge often. A fork, a clone or an alternative. Small merges keep conflicts small and early.
- 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.
- Place services by coordinates on the shared levels, and find clashes with a check, not with links.
- Delete with commands, so that what depends on a record goes with it and nothing dangles.
- 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.