03-EFT.WP.Core.Parameters v1.0 | Appendix A — Parameter Registry Schema

Home ／ Docs-Technical WhitePaper ／ 03-EFT.WP.Core.Parameters v1.0

Appendix A — Parameter Registry Schema

I. Schema Overview and Applicability

• Objective: define a unified schema for the parameter registry to support register_param, import/export, and scenario governance, ensuring theta is traceable, validatable, and reusable.
• Applies to: six roles — physical, constitutive, statistical, numerical, environment, derived; supports scalar, vector, matrix, and field (shape-declared) types.
• Strict conventions: parameter names, set names, units, and expressions are all English and plain text (narrative notes may use other languages). Never mix T_fil with T_trans; strictly distinguish n and n_eff.

II. Field Specifications and Required Items

1. Identity & grouping
   • code [required]: globally unique identifier (lowercase snake/camel, starting with a letter).
   • name [required]: English display name (reader-facing).
   • aliases [optional]: list of synonymous identifiers (normalized to code after registration).
   • group [optional]: parameter group tag (corresponds to theta_g).
   • role [required]: one of physical|constitutive|statistical|numerical|environment|derived.
   • see [optional]: cross-volume anchors (e.g., "S20-*", "S40-*", "Core.Equations").
2. Type, shape, and unit
   • type [required]: scalar|vector|matrix|field|bool|categorical.
   • shape [conditional]: required when type ∈ {vector,matrix,field}, e.g., "[3]", "[3,3]", "[Nx,Ny]".
   • unit [required]: unit or dimension string, e.g., "[L][T]^-1", "1", "[Tension]^-1" (per Metrology.).
3. Defaults, bounds, and feasibility
   • default [optional]: default value (omit if none).
   • bounds [optional]: {lb: ..., ub: ..., closed: "[left|right|both|none]"}; use null for unbounded.
   • constraints [optional]: list of {kind: "eq|ineq", expr: "C_eq(theta)=0|C_ineq(theta) ≤ 0"} (expressions in English).
4. Prior and transform
   • prior [optional]: {family: "Normal|LogNormal|Gamma|Beta|HalfNormal|Laplace|Uniform", hyper: {...}} (all hyper-parameters must be present).
   • transform [optional]: {name: "log|logit|softplus|zscore|identity", args: {...}}; must identify monotonicity and invertible domain.
5. Identifiability and relations
   • ident [optional]: {shared_with: ["code_a",...], tie_rule: "equality|ratio:k", rank_min: int}.
   • derived [conditional]: for derived parameters use {expr: "...", deps: ["..."]}; the expression must pass check_dim.
6. Governance and versioning
   • owner [required]: responsible person or team.
   • since [required]: first included version (e.g., "v1.0").
   • status [required]: active|frozen|deprecated.
   • semver [required]: semantic version of this entry.
   • changelog [optional]: change summary (English or other narrative).
   • scenario_overrides [optional]: per-scenario overrides, e.g., {ScenarioA: {default: ... , bounds: ...}}.
7. Quality and validation hooks
   • checks [optional]: {dim: "pass|fail", lint: "pass|fail", tests: ["id:pass", ...]}.
   • notes [optional]: supplemental notes (narrative allowed, no formulas).

III. Registration and Validation Rules (Mandatory)

• R-A1 Required: code|name|role|type|unit|owner|since|status|semver must all be present; otherwise reject.
• R-A2 Prior–bounds consistency: support(prior) must be contained within bounds; conflicts → reject.
• R-A3 Transform–domain consistency: domain(transform) must be compatible with bounds; inverse_transform must exist and be numerically stable.
• R-A4 Dimensional closure: derived.expr and every constraints[*].expr must satisfy check_dim == "ok".
• R-A5 Lint: expressions must not contain forms like ∫ n d ell / c; they must be written as ∫ ( n_eff / c_ref ) d ell with explicit gamma(ell) and d ell.
• R-A6 Freeze policy: entries with status="frozen" cannot change unit|bounds|transform|prior; only notes|changelog may be appended.
• R-A7 Aliases: aliases must not collide with any existing code; exports always write the canonical code.

IV. Field-to-API Mapping (I30 Binding)

• register_param ← code|name|type|unit|role|default|bounds|prior|transform|see
• add_alias ← aliases[*]; normalize_param is invoked during import.
• set_bounds, add_constraint ← bounds|constraints
• set_prior, sample_prior ← prior
• set_transform, forward_transform|inverse_transform ← transform
• derive_param, tie_params ← derived|ident.tie_rule|ident.shared_with
• freeze|thaw ← status; export_params|import_params cover the full schema

V. Example Entries (YAML Fragments; directly exportable)

- code: c_ref

name: reference propagation upper bound

role: physical

type: scalar

unit: "[L][T]^-1"

default: 3.0e8

bounds: {lb: 0.0, ub: null, closed: "left"}

prior: {family: LogNormal, hyper: {mu: 19.52, sigma: 0.05}}

transform: {name: softplus, args: {beta: 1.0}}

see: ["S20-*","Core.Equations"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

- code: n_eff_k

name: effective refractive index (segment k)

role: constitutive

type: scalar

unit: "1"

bounds: {lb: 1.0, ub: 5.0, closed: "both"}

prior: {family: LogNormal, hyper: {mu: 0.1, sigma: 0.5}}

transform: {name: log, args: {}}

group: n_eff_segments

see: ["S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

- code: n0

name: baseline effective index factor

role: constitutive

type: scalar

unit: "1"

bounds: {lb: 1.0, ub: 3.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 1.2, sigma: 0.1}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

- code: a_T

name: tension sensitivity coefficient

role: constitutive

type: scalar

unit: "[Tension]^-1"

bounds: {lb: -10.0, ub: 10.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 0.0, sigma: 1.0}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

- code: a_G

name: tension-gradient sensitivity coefficient

role: constitutive

type: scalar

unit: "[TensionGradient]^-1"

bounds: {lb: -10.0, ub: 10.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 0.0, sigma: 1.0}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

- code: n_eff_from_T

name: effective index from tension field

role: derived

type: field

shape: "[Nx,Ny]"

unit: "1"

derived:

expr: "n0 * ( 1 + a_T * T_fil(x) + a_G * |grad[T_fil](x)| )"

deps: ["n0","a_T","a_G","T_fil"]

constraints:

- {kind: "ineq", expr: "n_eff_from_T(x) - 1.0 ≥ 0"}

see: ["S40-*","S20-*","S70-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

VI. CSV Flat Format (Minimal Import Header)

• Header:
  code,name,role,type,unit,default,lb,ub,closed,prior_family,prior_hyper,transform_name,transform_args,group,see,owner,since,status,semver
• Example row:
  c_ref,reference propagation upper bound,physical,scalar,"[L][T]^-1",3.0e8,0.0,,left,LogNormal,"{mu:19.52,sigma:0.05}",softplus,"{beta:1.0}",,["S20-*"],EFT.Core,v1.0,active,1.0.0

VII. Expression and Dimension Lint Rules (Auto-Triggered on Registration)

• L1: any integral/division expression must be parenthesized and declare path and measure, e.g., T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell ).
• L2: never use n in place of n_eff; never let T_fil denote time or temperature.
• L3: constraints.expr and derived.expr must contain no non-ASCII letters; unit strings must use legal dimension symbols.
• L4: bounds.lb > bounds.ub or illegal closed ⇒ reject.
• L5: missing prior.family or incomplete hyper-parameters ⇒ reject.

VIII. Feasible Set and Prior-Support Consistency Card

• Feasible set: Theta = { theta | C_eq(theta)=0, C_ineq(theta) ≤ 0, lb ≤ theta ≤ ub }.
• Prior support: support(prior(theta_i)) ⊆ [lb_i, ub_i]; if a transform exists, validate in the original theta coordinates.
• Typical conflict & fix:
  prior(theta_i)=Normal(mu, sigma) but lb=0: switch to HalfNormal or apply a softplus transform.

IX. Release and Version Governance

• Version advancement: field or unit changes → MAJOR; prior/bounds tweaks → MINOR; default value or notes updates → PATCH.
• Scenario overrides: scenario_overrides may modify only default|bounds|prior, not unit|type.
• Freeze and deprecate: status="frozen" denotes regression baselines; deprecated entries must provide a replacement code and be retained for one release cycle.

X. Common Misuse and Fixes

• Misuse: writing ∫ n d ell / c in derived.expr.
  Fix: derived.expr: "( ∫_gamma ( n_eff / c_ref ) d ell )" and add see: ["S20-*"].
• Misuse: setting a_T with unit: "1" causing dimensional mismatch in a_T * T_fil.
  Fix: set unit to "[Tension]^-1" or modify the mapping so the product is dimensionless and passes check_dim.
• Misuse: omitting prior.hyper.
  Fix: complete hyper-parameters (e.g., Normal needs {mu, sigma}; Gamma needs {k, theta} or {alpha, beta}).

XI. Minimal Submission Checklist (Pre-Commit)

• code|name|role|type|unit|owner|since|status|semver are all present.
• bounds are valid and compatible with the transform domain.
• prior support is contained in bounds; hyper-parameters are complete.
• constraints|derived pass check_dim and lint.
• Cross-volume see provided where the entry participates in S20-*|S40-*|S50-*.
• export_params("yaml") reproduces this entry and passes regression comparison.