74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# Material calibrations
|
||
|
||
Process calibration values live in the version-controlled
|
||
`config/material-calibrations.yaml`. Calculations refer to opaque IDs; IDs have
|
||
no special meaning to the parser. The current entry is:
|
||
|
||
```yaml
|
||
calibrations:
|
||
bento1-spreader-1-2:
|
||
type: rotational_discharge
|
||
value: 2.75
|
||
unit: kg_per_rev_m
|
||
calibrated_at: 2026-09-08
|
||
method: gravimetric_tray
|
||
description: Bento 1 fresh-bentonite spreaders 1 and 2
|
||
reference:
|
||
measured_application_g_m2: 4068
|
||
line_speed_m_min: 2.3
|
||
signal_values:
|
||
left: 1.65
|
||
right: 1.75
|
||
```
|
||
|
||
All entry fields are required. Type, unit, method and description are non-empty
|
||
strings; value must be a finite number (booleans are rejected); calibrated_at is
|
||
a calendar date in YYYY-MM-DD format, quoted or unquoted. Reference is a non-empty
|
||
mapping whose contents preserve source-specific measurement provenance. Unknown
|
||
entry fields and duplicate YAML keys are rejected. The generic registry permits
|
||
other types and units; each consuming calculation checks its own compatibility.
|
||
|
||
`config/bento1-material-consumption.yaml` contains
|
||
`calibration_ref: bento1-spreader-1-2`. During configuration loading, references
|
||
resolve from `material-calibrations.yaml` in the calculation file's directory,
|
||
independently of the working directory. The entire registry is validated when a
|
||
reference is used. Rotational discharge requires type `rotational_discharge`,
|
||
unit `kg_per_rev_m` and a positive value. Resolution supplies the existing
|
||
`specific_discharge_kg_per_rev_m` runtime field for both application and
|
||
consumption; the calculation algorithms are unchanged. There is no unit conversion.
|
||
|
||
Missing/unreadable files, missing IDs, invalid metadata and incompatible type or
|
||
unit raise `CalculationConfigError` before a runner starts. Existing direct numeric
|
||
configurations remain supported; specifying both a reference and a direct factor
|
||
is rejected. References are currently supported by rotational discharge consumers.
|
||
K7 uses direct mass rate and does not load or require a calibration file.
|
||
|
||
## Updating a calibration
|
||
|
||
After a physical measurement, edit only the central entry's value, date, method
|
||
and reference details, and keep its ID stable. Review and version-control the
|
||
change. Additional machines can add new IDs using the same structure. A new
|
||
calculation type needs an explicit consumer compatibility contract.
|
||
|
||
Ship the central YAML alongside the calculation YAML and restart the consuming
|
||
process to load changes. No new CLI flag, environment variable, database migration
|
||
or UI is required. There is no hot reload or historical date-based selection.
|
||
Changes affect future calculations and explicitly rebuilt calculations. Historical
|
||
persisted snapshots are **not automatically recalculated**. Existing checkpoints
|
||
retain accumulated totals, so subsequent increments use the newly loaded factor;
|
||
a complete historical rebuild requires a separately planned replay. Persisted
|
||
snapshots do not gain calibration-version provenance through this change.
|
||
|
||
## Current Bento provenance
|
||
|
||
On 2026-09-08, an independent gravimetric tray measurement found 4068 g/m² at
|
||
2.3 m/min with actual rotational signals left 1.65 and right 1.75.
|
||
`(4068 / 1000) × 2.3 / (1.65 + 1.75) ≈ 2.75188 kg/(rev*m)` gives the configured
|
||
rounded factor **2.75 kg/(rev*m)**. The original measurement remains recorded,
|
||
without fitting or adjusting the runtime value to reproduce it exactly.
|
||
|
||
Only fresh-bentonite spreaders 1 and 2 are included. Before adding spreader 3,
|
||
confirm its material scope, actual signal units, independent calibration and
|
||
whether its output belongs in the fresh-material KPIs. No spreader 3 support is
|
||
included here.
|