50-Parameter Registration Card Template v1.0 | Chapter 4 — Domains, Units & Defaults (Validation Conventions)

Home ／ Docs-Technical WhitePaper ／ 50-Parameter Registration Card Template v1.0

Chapter 4 — Domains, Units & Defaults (Validation Conventions)

I. Purpose & Scope

• Specify the value domain (domain), units & dimensions, defaults/ranges, and precision for parameters, and the validation conventions that ensure cross-pipeline consistency and traceability.
• For path quantities (arrival time/phase), explicitly show gamma(ell) and the measure d ell in text, and record delta_form ∈ {general, factored} in the card; publication requires p_dim = 1.0.

II. Prerequisites & Inputs

• Control equations & context: the control equations and target y = f(x) that use the parameter are cited with anchors (volume+version+anchor).
• Dimensional tool: use I70-dim_check(expr, units) to validate dimensional closure and export check_dim_report.json.
• Path consistency (if applicable): len(gamma_ell) = len(d_ell) = len(n_eff) ≥ 2, and Δell satisfies sampling constraints.

III. Domain Types & Declarations

• real: continuous real; specify unit / range[min,max] / default / precision.
• integer: discrete integer; specify step/bit-width (e.g., bits).
• enum: enumerated; list values[] & semantics; default must be a member.
• array: array; declare shape, element unit, precision, and bounds; for path functions add path{gamma, measure, delta_form}.
• tensor: tensor; declare rank/shape and metric (if any).
• boolean: only for safety/switch parameters; define default and scope.

Minimal domain fields:
domain{ type, unit, range[min,max] | values[], default, precision, shape? }

IV. Units & Dimensions

1. Units: SI/international symbols (m, s, rad, 1, Pa, N, J, Hz, …).
2. Dimensional closure: all derived/constraint expressions pass I70-dim_check and attach check_dim_report.json; publication requires p_dim = 1.0.
3. Canonical checks:
   • Arrival time: T_arr = ( ∫ ( n_eff / c_ref ) d ell ) ⇒ [1]/[m·s^-1]·[m] = [s].
   • Phase: Phi = ( 2π / λ_ref ) ( ∫ n_eff d ell ) ⇒ [1/m]·[m] = [rad].
4. Dimensionless: use 1 for dimensionless; avoid % as a unit (explain “percent” in notes if needed).

V. Defaults, Ranges & Precision

• Default: default must lie within range[min,max] or values[]; for array/tensor, provide construction rule or example.
• Ranges: provide engineering vs physical bounds (eng_range, phys_range); use engineering bounds in published tables.
• Precision: set precision as datatype (e.g., float64/int32) or significant digits; align with quantization/ADC step.
• Missingness: never encode missing as textual NaN/Inf; use null and document handling under constraints.

VI. Validation Rules

• Unit legality: domain.unit must be a standard symbol or resolvable alias to SI; custom units must include conversion.
• Dimensional closure: expressions in constraints.derived must be parenthesized and pass I70-dim_check.
• Dependency consistency: all depends_on[] upstream parameters must be registered and unit/domain-compatible; cross-card refs via see[] anchors.
• Path conventions: path-related parameters must include path{gamma, measure, delta_form}; absence of any item is a validation failure.
• Coverage info: if the parameter participates in uncertainty propagation, provide uncertainty{type, estimate, distribution, coverage} (k or confidence/quantiles).
• Enum mutual exclusion: when enumerations have mutual exclusivity, encode it explicitly in constraints.

VII. Normative Examples

# A) Real domain: reference propagation limit

domain:

type: "real"

unit: "m/s"

range: [2.9e8, 3.1e8]

default: 2.99792458e8

precision: "float64"

# B) Array domain (path function): effective refractive index profile

domain:

type: "array"

unit: "1"

shape: ["N"]

range: [0.8, 2.5]

precision: "float64"

path:

gamma: "gamma(ell)"

measure: "d ell"

delta_form: "general" # or "factored"

# C) Enum domain: clock state

domain:

type: "enum"

unit: "1"

values: ["locked","holdover","free"]

default: "locked"

VIII. Schema & Validation Snippet

{

"type": "object",

"required": ["domain"],

"properties": {

"domain": {

"type": "object",

"required": ["type","unit"],

"properties": {

"type": {"enum": ["real","integer","enum","array","tensor","boolean"]},

"unit": {"type": "string"},

"range": {"type": "array","items":{"type":"number"},"minItems":2,"maxItems":2},

"values": {"type":"array","items":{"type":["string","number","boolean"]}},

"default": {},

"precision": {"type":"string"},

"shape": {"type":"array","items":{"type":["integer","string"]}}

},

"oneOf": [

{"properties":{"type":{"const":"enum"}}, "required":["values","default"]},

{"properties":{"type":{"enum":["real","integer","array","tensor"]}}, "required":["range","precision"]}

]

}

}

}

IX. Cross-References

• Metrology & dimensions: See "EFT.WP.Core.Metrology v1.0" check_dim.
• Control equations & path: See "EFT.WP.Core.Equations v1.1" Ch.2 S20-1/S21-2.
• Data contract: See "EFT.WP.Core.DataSpec v1.0" TARR.
• Propagation & intervals: See "Error Budget Card Template v1.0" Ch. 6/Ch. 8.

X. Checklist

• domain{type, unit, range/default, precision} complete & valid; default ∈ range|values.
• For path quantities: explicit gamma(ell)/d ell in text; delta_form recorded; len(path) ≥ 2, Δell compliant.
• constraints.derived parenthesized and passed I70-dim_check; check_dim_report.json generated; p_dim = 1.0.
• Dependencies registered and unit/domain-compatible; see[]/references[] compliant with anchor coverage ≥ 90%.
• Enum/boolean/tensor types include values/shape and conflict/mutual-exclusion rules; missingness policy clear.
• Aligned with Error Budget Card cov_group, coverage conventions, and publication tables; units/dimensions explicit in registry/results.