feat: add experimental data entities as mirrors of the computational ones

docs/02-schema-layering.md

@@ -72,10 +72,13 @@ platform behind.
 
 ### `entity` and `entity-component` — the nouns
 
-The eleven root schemas (`material`, `model`, `method`, `workflow`, `job`, `project`, `element`,
-`context-provider`, and the material variants) plus the components they are assembled from —
-`material/material_properties`, `workflow/unit/*`, `model/mixins/*`, `method/unit_method`, and so
-on. [Entity anatomy](entity-anatomy.html) covers these in detail.
+The fifteen root schemas — `material`, `model`, `method`, `workflow`, `job`, `project`, `element`,
+`context-provider` and the material variants on the computational side, `sample`, `instrument`,
+`measurement` and `process` on the experimental one — plus the components they are assembled from:
+`material/material_properties`, `workflow/unit/*`, `model/mixins/*`, `method/unit_method`,
+`sample/layer`, `process/step` and so on. [Entity anatomy](entity-anatomy.html) covers these in
+detail, and [Experimental data](experimental-data.html) covers how the two families mirror each
+other.
 
 ### `category`, `directory` and `application-parsing` — the catalogues
 

docs/03-entity-anatomy.md

@@ -6,10 +6,15 @@ summary: The root entities, how they compose, and why there are four kinds of ma
 
 # Entity anatomy
 
-Eleven schemas sit at the top level of `schema/`. They are the nouns of the domain — the things a
+Fifteen schemas sit at the top level of `schema/`. They are the nouns of the domain — the things a
 user creates, names, owns and looks at — and everything else in the repository exists to define,
 categorize or support them.
 
+Eleven of them describe computational work. The other four — `sample`, `instrument`, `measurement`
+and `process` — describe experimental work, and each is built as the mirror of a computational one
+rather than as a separate vocabulary. [Experimental data](experimental-data.html) sets out the
+correspondence; the sections below cover the computational originals.
+
 ## Material
 
 A material is a structure plus what is known about it. It is assembled entirely by composition:
@@ -96,7 +101,8 @@ shape: `scalar` (total energy, pressure, band gap), `non-scalar` (band structure
 states, charge density), `structural`, `elemental` and `workflow` (convergence monitors).
 
 They are tied together by `property/holder`, which is the widest schema in the corpus: its `data`
-field is a union over every property type, on top of one mixin and one provenance reference. That
+field is a union over every property type, on top of one mixin and a `source` whose `info` is
+itself a small union over where the value came from: a job, a measurement or a process. That
 one file is why "what property types exist?" has a single answer, and it is the clearest
 illustration of the union idiom in ESSE. On the [ontology map](../map/index.html) it is the node
 with by far the largest fan-out.

docs/10-experimental-data.md

@@ -0,0 +1,90 @@
+---
+title: Experimental data
+order: 10
+summary: The four experimental entities, and why each one mirrors a computational one.
+---
+
+# Experimental data
+
+ESSE began as a description of simulation: a [material](entity-anatomy.html) is characterized by
+properties produced by a model, realized by a method, run as a workflow inside a job. Experimental
+work has the same shape and different nouns. A specimen is measured on an instrument; a film is
+grown by a process on another instrument; the numbers that come out are properties like any other.
+
+Rather than invent a parallel vocabulary, each experimental entity is built as the **mirror** of the
+computational one it corresponds to, composing the same mixins and keeping the fields that transfer.
+
+## The mirror
+
+| Computational | Experimental | What the mirror keeps |
+| --- | --- | --- |
+| `material` | `sample` | the same `named_defaultable` mixin, `formula`, `external`, `src`; `basis` and `lattice` become an optional `_material` reference, because a specimen may have no known structure |
+| `software/application` | `instrument` | `shortName` and `summary`; `version` becomes `firmware` and `build` becomes `serialNumber`, which is what identifies a physical unit |
+| `job` | `measurement` | `status`, timing, `_project`; `compute` becomes `instrument`, `_material` becomes `_sample` |
+| `workflow` | `process` | the five composition branches; `subworkflows` become `stages`, `units` become `steps`, and the `application` a workflow names becomes the instrument each stage runs on |
+| `property` | `property` | unchanged — see below |
+
+Read it as one sentence. A **sample** is characterized by **properties**; those properties are
+produced by applying a **technique** on an **instrument** in a **measurement**; the sample itself is
+produced by a **process** of **stages** and **steps**; measurements and processes belong to a
+**project**, exactly as jobs do.
+
+## Properties do not fork
+
+This is the load-bearing decision. A measured film thickness is an ordinary `property/holder`: the
+same `data` union, the same `exabyteId`, the same `repetition`. Only the source differs.
+
+```json
+{
+    "data": { "name": "film_thickness", "value": 140, "units": "nm" },
+    "source": {
+        "type": "measurement",
+        "info": { "measurementId": "mXrf0042", "channel": "thickness" }
+    },
+    "exabyteId": ["mXrf0042"],
+    "repetition": 0
+}
+```
+
+`source.info` is a union over where a value came from: `core/reference/exabyte` for a computed
+result, `core/reference/measurement` for a measured one, `core/reference/process` for something read
+off a fabrication record. The measurement reference is deliberately shaped like the job reference —
+`measurementId` where a job has `jobId`, `channel` where a job has `unitId` — so a consumer that
+already reads job provenance needs no new code path.
+
+The consequence is that a query for "band gap of this material" and one for "band gap of this
+sample" return the same shape, and a plot can mix them.
+
+## Techniques are categorized, not enumerated
+
+`techniques_category` narrows the same `core/reusable/categories` tiers that `models_category` and
+`methods_category` use. An atomic force microscopy scan is `experimental / characterization /
+microscopy / scanning_probe_microscopy / atomic_force_microscopy`, in the same five-tier ladder a
+density functional theory model sits in. Techniques that are not yet modelled in detail — sputtering,
+molecular beam epitaxy, X-ray diffraction — exist as vocabulary values before they have schemas.
+
+## Where the split is visible
+
+The computational and experimental entities sit side by side under `schema/`, as peers, because that
+is what they are: `$id` is a public contract and neither family is a sub-domain of the other. What
+separates them is:
+
+- **the ontology map**, which colours the experimental entities as one family;
+- **`categories.tier1`**, which is `experimental` on every measurement and process;
+- **`source.type`** on a property, which says whether a number was computed or measured.
+
+None of these is a hand-maintained tag that can disagree with the schemas. Each is derived from the
+record or from the path.
+
+## What a record looks like
+
+A combinatorial library is a `sample` with `form: library` and a grid of positions; each position is
+a child `sample` with a `_parent` and a `position`. That child's identity is the join key: a
+measurement points at it with `_sample`, and every property holder produced from that measurement
+carries it. This is how a per-position thickness from an X-ray fluorescence map and a per-position
+piezoresponse loop end up on the same specimen without a shared spreadsheet.
+
+Deposition records follow the process shape: one `process` per run, one `stage` per chamber, one
+`step` per operation, with material `sources` (targets, precursors, gases) named once per stage and
+referenced from the steps that use them. A cycle count lives on the step's `repeat`, which is the
+only place it appears.

docs/10-glossary.md → docs/11-glossary.md

@@ -1,6 +1,6 @@
 ---
 title: Glossary
-order: 10
+order: 11
 summary: The vocabulary of the repository, with pointers to where each idea is explained.
 ---
 

docs/index.md

@@ -48,7 +48,9 @@ Then, as you need them:
    and what the two runtimes do and do not guarantee.
 8. **[Consuming ESSE](consuming-esse.html)** — using the schemas from Python and JavaScript.
 9. **[Contributing a schema](contributing-a-schema.html)** — a worked example, end to end.
-10. **[Glossary](glossary.html)** — the vocabulary, in one place.
+10. **[Experimental data](experimental-data.html)** — the four experimental entities, and
+    why each mirrors a computational one.
+11. **[Glossary](glossary.html)** — the vocabulary, in one place.
 
 ## Conventions in these pages
 

example/core/abstract/multidimensional_array.json

@@ -0,0 +1,26 @@
+{
+    "shape": [
+        2,
+        3
+    ],
+    "values": [
+        0.1,
+        0.2,
+        0.3,
+        0.4,
+        0.5,
+        0.6
+    ],
+    "axes": [
+        {
+            "name": "y",
+            "start": 0,
+            "step": 0.5
+        },
+        {
+            "name": "x",
+            "start": 0,
+            "step": 0.5
+        }
+    ]
+}

example/core/reference/measurement.json

@@ -0,0 +1,7 @@
+{
+    "type": "measurement",
+    "measurementId": "mPfmSpectroscopy0005",
+    "channel": "piezoresponsePhase",
+    "sampleId": "sAlScN6705p17",
+    "instrumentId": "iJupiter01"
+}

example/core/reference/process.json

@@ -0,0 +1,6 @@
+{
+    "type": "process",
+    "processId": "pLmc1699",
+    "stepFlowchartId": "s2",
+    "sampleId": "sAlScN6705"
+}

example/core/reusable/array_data.json

@@ -0,0 +1,26 @@
+{
+    "shape": [
+        256,
+        256
+    ],
+    "axes": [
+        {
+            "name": "y",
+            "start": 0,
+            "step": 0.0078125
+        },
+        {
+            "name": "x",
+            "start": 0,
+            "step": 0.0078125
+        }
+    ],
+    "units": "nm",
+    "dataType": "float32",
+    "file": {
+        "basename": "PFM_DART_raw.ibw",
+        "format": "asylum_ibw",
+        "role": "raw"
+    },
+    "datasetPath": "HeightRetrace"
+}

example/core/reusable/environment.json

@@ -0,0 +1,11 @@
+{
+    "temperature": {
+        "value": 295,
+        "units": "K"
+    },
+    "atmosphere": "ambient",
+    "humidity": {
+        "value": 38,
+        "units": "percent"
+    }
+}

example/core/reusable/file_reference.json

@@ -0,0 +1,12 @@
+{
+    "basename": "PFM_DART_raw.ibw",
+    "pathname": "/data/utk/2026-03-13/",
+    "filetype": "binary",
+    "format": "asylum_ibw",
+    "size": 1688293,
+    "checksum": {
+        "algorithm": "sha256",
+        "value": "1a3f9c2b5d7e8f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607182"
+    },
+    "role": "raw"
+}

example/core/reusable/identifier.json

@@ -0,0 +1,4 @@
+{
+    "scheme": "htem",
+    "value": "6705"
+}

example/core/reusable/quantity/current.json

@@ -0,0 +1,4 @@
+{
+    "value": 1.5,
+    "units": "nA"
+}

example/core/reusable/quantity/frequency.json

@@ -0,0 +1,4 @@
+{
+    "value": 372.177,
+    "units": "kHz"
+}

example/core/reusable/quantity/length.json

@@ -0,0 +1,4 @@
+{
+    "value": 140,
+    "units": "nm"
+}

example/core/reusable/quantity/pressure.json

@@ -0,0 +1,4 @@
+{
+    "value": 0.004,
+    "units": "Torr"
+}

example/core/reusable/quantity/temperature.json

@@ -0,0 +1,4 @@
+{
+    "value": 300,
+    "units": "degC"
+}

example/core/reusable/quantity/time.json

@@ -0,0 +1,4 @@
+{
+    "value": 30,
+    "units": "min"
+}

example/core/reusable/quantity/voltage.json

@@ -0,0 +1,4 @@
+{
+    "value": 0.5,
+    "units": "V"
+}

example/instrument.json

@@ -0,0 +1,39 @@
+{
+    "_id": "iJupiter01",
+    "name": "Jupiter scanning probe microscope",
+    "isDefault": true,
+    "shortName": "jupiter",
+    "summary": "Asylum Research Jupiter atomic force microscope with dual-frequency resonance tracking",
+    "vendor": "Asylum Research",
+    "model": "Jupiter",
+    "firmware": "19.34.88",
+    "techniques": [
+        {
+            "tier1": "experimental",
+            "tier2": "characterization",
+            "tier3": "microscopy",
+            "type": "scanning_probe_microscopy",
+            "subtype": "piezoresponse_force_microscopy"
+        }
+    ],
+    "components": [
+        {
+            "kind": "cantilever",
+            "name": "Multi75-EG",
+            "parameters": {
+                "springConstant": {
+                    "value": 2.1868,
+                    "units": "N/m"
+                },
+                "inverseOpticalLeverSensitivity": {
+                    "value": 82.055,
+                    "units": "nm/V"
+                }
+            }
+        }
+    ],
+    "location": {
+        "facility": "University of Tennessee, Knoxville",
+        "laboratory": "Kalinin group"
+    }
+}

example/instrument/component.json

@@ -0,0 +1,15 @@
+{
+    "kind": "cantilever",
+    "name": "Multi75-EG",
+    "vendor": "BudgetSensors",
+    "parameters": {
+        "springConstant": {
+            "value": 2.1868,
+            "units": "N/m"
+        },
+        "resonanceFrequency": {
+            "value": 372.177,
+            "units": "kHz"
+        }
+    }
+}

example/instrument/instrument_properties.json

@@ -0,0 +1,15 @@
+{
+    "shortName": "pdac_com5",
+    "summary": "Combinatorial magnetron sputtering chamber",
+    "vendor": "National Laboratory of the Rockies",
+    "model": "PDAC COM5",
+    "techniques": [
+        {
+            "tier1": "experimental",
+            "tier2": "synthesis",
+            "tier3": "vapor_deposition",
+            "type": "physical_vapor_deposition",
+            "subtype": "sputtering"
+        }
+    ]
+}

example/instrument/instrument_property.json

@@ -0,0 +1,9 @@
+{
+    "instrument": {
+        "_id": "iJupiter01",
+        "name": "Jupiter scanning probe microscope",
+        "vendor": "Asylum Research",
+        "model": "Jupiter",
+        "firmware": "19.34.88"
+    }
+}