Domain packs
A domain has its own words. A process plant has tanks, pumps and valves; a railway has tracks and signals. A pack brings the words of one domain to a project in one step: its kinds, their relations, its units and the checks its engineers make.
A pack is a library. It is versioned, it is taken offline, and its files are included like any other. Nothing in it is compiled: a pack is model.
A first pack#
archec ships process-plant, the words of a piping and instrumentation
diagram (P&ID).
archec shelf packs # the packs there are
archec shelf packs process-plant # its card
archec shelf add main.arche process-plant # take it
The last command writes two lines:
project Plant {
uses process-plant "^0.2"
}
include "process-plant/pack.arche"
Now the pack's kinds are words of the model:
tank T-101 "Raw water" { volume 5m³; rating 6bar; feeds P-101 }
pump P-101 "Feed pump" { flow 12m³/h; head 30m; pressure 4bar; feeds LV-101 }
control-valve LV-101 { rating 10bar; feeds T-102 }
tank T-102 "Treated water" { volume 12m³ }
transmitter LT-101 { measures T-102 }
controller LIC-101 { reads LT-101; controls LV-101 }
archec check applies the pack's rules, and archec status counts each of
them on each element:
PP-LOOPS Control loops are whole
✓ check control-valve LV-101: count(incoming(controls)) == 1 model just now
✓ check controller LIC-101: count(controls) >= 1 model just now
✓ check transmitter LT-101: count(measures) >= 1 model just now
To start a new project from a pack's template instead:
archec new my-plant --template plant-loop
What a pack holds#
| In a pack | What it is |
|---|---|
| kinds | The kinds of element, each with its properties, its checks and its shape (kinds.md). |
| relations | The links between them: feeds, measures, controls. |
| units | The units the domain uses and archec does not know: unit barg "bar gauge" { quantity pressure }. |
| rules | The check lines of its kinds, and the requirements they are evidence for (verifies). |
| parts and types | Anything else a library holds: enums, types, components. |
| a template | A small project to start from (archec new --template). |
| generators | Code generators of its own (generators.md). They run only after archec generator approve. |
The files of a pack#
process-plant/
library.arche the manifest: its name, its version, `kind pack`, `shelf packs`
pack.arche the one file a project includes; it includes the others
kinds.arche the kinds, relations and checks
units.arche the units
README.md what it holds and what it checks
template/ a project to start from (its own library.arche says `kind template`)
The manifest is the one every library has:
library process-plant "Process plant (P&ID)" {
description "Kinds for a piping and instrumentation diagram: …"
kind pack
owner arche
version "0.2.0"
archec ">=0.13"
shelf packs
license "Apache-2.0"
export-control none
edition "1.0"
}
kind packsays what it is. The store then asks for apack.arche.shelf packsputs it on the packs shelf.pack.archeincludes the pack's other files, so a project includes one file.- Each of those files starts with
package process-plant: a kind is then namedvalve, orprocess-plant.valvewhen another pack has avalvetoo.
archec store check <folder> says what a pack lacks before it is published.
Where packs come from#
- Shipped with archec, in
lib/packs. They need no network and no store. The VS Code extension carries them too. - A folder of your own. Name it in the project (
libraries "../shared"), andarchec shelf addtakes the pack from there. - The Arche Store.
archec add main.arche acme/railchecks the package and installs it. Then writeinclude "rail/pack.arche".
A project locks the version it uses, as for any library: archec lib main.arche lock.
Write a pack#
This section is the whole recipe. A pack is written only with what kinds can say: no change to archec is needed, and none is allowed. What a pack cannot say with kinds is a gap to report, not to work around.
1. The folder#
my-pack/
library.arche the manifest
pack.arche the one file a project includes: it includes the others
kinds.arche the kinds, the relations, the checks, the requirements
units.arche the units the domain adds (only when it adds some)
README.md the kinds, the relations and each check, in tables
template/
library.arche `kind template`, a name of its own (`plant-loop`)
main.arche a small project that uses the pack and checks clean
A pack archec ships goes in lib/packs/<name>/. The folder's name is the
pack's name: lowercase letters, digits and hyphens.
2. The package#
Every file of the pack that declares something starts with the pack's package.
pack.arche has no package line: it only includes.
// kinds.arche
package my-pack
kind valve "Valve" {
prop size: float64 unit mm
}
The package is what lets two packs each have a valve, a line or a
controller. A project writes valve V1 while yours is the only one, and
my-pack.valve V1 when another pack has one too
(kinds.md). Inside the pack, write the short
names: they are read from the pack's own package.
Requirements, enums, types and units are not qualified: their names are one of
the whole model. Give them the pack's prefix (PP-SOUND, PlantFailPosition).
3. The kinds#
/// Anything the fluid passes through.
kind plant-item "Plant item" {
/// The pressure it withstands.
prop rating: optional float64 unit bar
relation feeds -> plant-item
verifies PP-SOUND
}
/// A machine that moves liquid.
kind pump "Pump" extends plant-item {
prop flow: float64 unit m³/h
color teal
draw circle
}
- Write a
///comment above each kind and each property: it is its description, on the shelf's card and in the editor. - A property every element must give has no default and no
optional. Keep those few: an equipment list rarely has every column. - Give each quantity its
unit. An element writes its values in that unit. - Build kinds on a base kind (
extends) when they share properties, relations or checks. A relation to the base takes them all, andarchec query … plant-itemlists them all. - A kind's name may not be a word of the language (
kind-shadows-keyword):gate,port,state,part,event.archec checksays so. drawis one of box, rounded, circle, ellipse, diamond, hexagon, cylinder.
4. The relations#
relation measures: transmitter | indicator -> plant-item
relation controls: controller [1] -> control-valve {
verifies PP-LOOPS
}
relation controls: controller -> pump
- A relation used by one kind and those built on it is written inside that
kind (
relation feeds -> plant-item). One between several kinds is written at the top of the file. [1]after the source: every target has exactly one source.[1..*]after the target: every source links to at least one. A count not met is a warning and evidence inarchec status.- To count differently by kind, declare the relation again for the other
kinds, as
controlsabove. - A link has no properties. What a link carries is an element between the two.
5. The rules#
A rule is a check on a kind, with the message a breach gives and the
requirement it proves.
requirement PP-SOUND "The plant's items are sound" {
description "Every pump shall move something, from a suction source, into something."
}
requirement PP-TAGS "Tags are as ISA-5.1 says"
kind pump "Pump" extends plant-item {
prop flow: float64 unit m³/h
check flow > 0 "a pump moves something"
check count(feeds) >= 1 "a pump discharges into something"
check count(incoming(feeds)) >= 1 "a pump has a suction source"
check matches(name, "^P-[0-9]+$") "a pump's tag is P- and a number" verifies PP-TAGS
}
- Write one requirement for each family of rules, and
verifieson the base kind. A rule of another family says its own:… "message" verifies PP-TAGS. - Write the message in the domain's words, as a sentence that is true when the model is right: "a pump has a suction source".
- A check says nothing where a value it reads is not given. So a rule on an optional property never fails an element that leaves it out.
What a check reads (kinds.md has the whole table):
| You write | It reads |
|---|---|
flow, rating |
a property of the element |
feeds, count(feeds) |
the elements it links to, and how many |
incoming(feeds) |
the elements that link to it |
feeds.rating, min(feeds.rating) |
a property of each element linked |
parent, children, valve |
what it is written in, what is written in it, those of one kind |
name, label, kind |
its name, its label, its kind |
matches(name, "^[A-Z]+-[0-9]+$") |
the form of a text |
exists v in feeds: v.rating > 6bar, forall … |
one of a list fits; every one fits |
6. The units#
archec knows the usual units (archec shelf units). Declare only the ones the
domain adds, with a plain name and the spelling as an alias:
package my-pack
unit kgh "kilogram per hour" { quantity mass-flow; alias "kg/h" }
A kind then writes unit kg/h. Nothing is converted between units.
7. The manifest, the README, the template#
library.arche:
library my-pack "My domain" {
description "Kinds for … : … . Relations … . Checks: … ."
kind pack
owner arche
version "0.1.0"
archec ">=0.13"
shelf packs
license "Apache-2.0"
keywords domain, words, to, search
export-control none
edition "1.0"
}
pack.arche:
// The pack, whole: include this file, and its kinds are words of the model.
include "units.arche"
include "kinds.arche"
README.md lists the kinds with their properties, the relations with their
ends, and every check under its requirement, then the limits.
template/main.arche is a small project that uses the pack
(uses my-pack "^0.1", include "my-pack/pack.arche") and checks clean.
8. Check it#
archec fmt --write *.arche template/*.arche
archec store check . # what the store would refuse or remark
archec check template/main.arche # no error, no warning
archec status template/main.arche # every check under its requirement
archec shelf packs my-pack # its card
Then a test, as test/packs.test.js does for process-plant: each rule with a
small model that breaks it, and the message it gives. The first test of that
file holds every shipped pack to this recipe.
To publish a pack of your own: archec store publish ..
What a pack cannot do yet#
- Behave. A kind has no ports, functions or states: its elements are not simulated (kinds.md).
- An interval, or a unit each element chooses. A property has one type and
one unit. A range is a text, or two properties (
range-min,range-max). - A property on a link. Make it an element between the two.
- New syntax. A pack's elements are written
kind Name { property value }, and a link is a relation's name then its targets.T1 -> P1 -> V1andconnector J1 { pin 1 VBAT }are not kinds' syntax. - A symbol of its own. An element is drawn in one of the seven shapes.
Fill a pack's kinds from a table#
An equipment list or an asset register becomes elements with
archec import table:
archec import table equipment.csv --as plant-item --id Tag --map "Type=kind" -o equipment.arche
The example examples/process-plant is
made this way, from two tables.
The process-plant pack#
Its README lists its kinds, its
relations and each of its checks. In short:
tank,pump,exchanger,line,valve(andgate-valve,globe-valve,check-valve,control-valve) are plant items. Each may give itspressureand itsrating, in bar.transmitter,indicatorandcontrollerare instruments. Their names are ISA-5.1 tags:LT-101,FIC-201.feedsgoes from a plant item to the next.measures,readsandcontrolsmake the control loops.- The checks: a tag's form, a transmitter that measures nothing, a controller with no transmitter or no valve, a control valve without a controller, a pump that moves nothing or has no suction source, a line fed at a pressure its next item does not withstand.
The services, networks and ml packs#
Three packs add to domains the language already has words for. Each says in its README what the language says and what the pack says.
services: anapiand itsendpoints, alatency-sloand anavailability-slo, ascalingrule, abrokerand itstopics. They name the components, functions, messages and chains of the model. The checks: a public endpoint has an SLO, a latency target holds its endpoints' and its chains' budgets, an endpoint's budget covers what it calls, a topic's publishers and consumers have ports on it. The example isexamples/services.networks: aswitch, arouter, ahost, thenet-linkbetween two of them, avlan, asubnet, astream, atsn-scheduleand itsslots. A host and a link stand for a processor and a bus of the platform. The checks: the streams of a link add up to its bandwidth at most, VLAN membership is the same along a stream's path, a TSN slot fits its cycle and holds its stream's frame. The example isexamples/networks.ml: anml-dataset, anml-model, atraining-run, anevaluation, adrift-monitor. A threshold on a metric is a requirement whosecheckreads an evaluation. The checks: a deployed model has a training run, an evaluation on a test set and a drift monitor, and a model is judged on data its run did not train on. The example isexamples/ml.
The organisation, manufacturing and cost packs#
Each has a README with its kinds, its relations, each of its checks and its limits.
organisation: stakeholders, teams, roles, the people who hold them, human tasks with a deadline, timers and service levels, around theworkflowof the language. It checks that every role is held and every task has someone who does it. A service level is proved by aqueueingmodel (examples/organisation).manufacturing: production lines, their steps and test stations, maintenance tasks with their intervals, spares, service lives and obsolescence notices, linked to the components of the bill of materials (examples/manufacturing).cost: one-off costs, unit costs at each volume, yearly costs, and cost cases held to a target. It stands besidebudget cost, astudyover the volume and aprofileover the years (examples/cost).
The harness pack#
A wiring harness. Its README lists its
kinds, its relations and each of its checks. In short:
connectorwith itscavityelements,conductor(a wire),splice,terminal,cable,branchandfuse. The copper table is elements too:gauge AWG-18.joinsgoes from a wire to its two ends.mateslinks two connectors,fitted-onandcarriestie a connector and its cavities to a component of the model and its ports.- The checks: every cavity takes one wire, mating connectors have the same ways and signals, a wire carries its current, its voltage drop (length × current × resistance per metre) is under its limit, a fuse protects its wires.
The example is examples/harness.
The sites pack#
Places, and what is installed where. Its
README has the whole of it. In short:
site(latitude, longitude),building,floor,room,yard,zone, andfixturefor an installed thing with no model of its own.installed-ingoes from a fixture, a component or a part to its room. Declared again in a project, it goes from another pack's kinds too.coversgoes to a zone, and a zonespansrooms.- The checks: coordinates in range, one level for each floor, a fixture in exactly one room, a zone covered by as many items as it needs, from inside it and within reach.
The example is examples/sites: a plant written
with process-plant, placed in the rooms of a site.
The compliance pack#
The clauses of standards, and the evidence that meets each. Its
README has the whole of it. In short:
- A clause set writes a
standard, itslevelelements and itsclauseelements. The pack ships sets for ISO 26262-6, DO-178C (tables A-5 to A-7), IEC 62304, UN R155 and the EU Cyber Resilience Act: clause numbers and the pack's own short wording, never a standard's text. A project includes the ones it follows:include "compliance/iso26262-6.arche". - A project writes an
assurance(the standard, and the level it is followed at), aclaimfor the clauses met (meets … byrequirements, documents, decisions) and anexclusionfor the ones left out, with the reason. - The checks: every clause that applies at the project's level is met by
evidence that is ready, or excluded.
archec statuslists each clause.
The example is examples/compliance.
Limits#
- A pack is built only from what kinds can say. What kinds cannot say, a pack cannot check (above).
archec shelf addtakes a pack that archec ships or that alibrariesfolder holds. A pack installed from the store is included by hand.- The Arche app has no page for a pack's elements.
elements.yamlholds them.