otko/docs/consistent_units.md

Consistent Units

Plan for making units explicit and uniform across OTKO: model input, solver boundary, result display, and persistence. This is a plan, not an implementation — no code changes ship with this document.

1. Principle

OpenSees is unit-agnostic: it never converts. The engineer picks one consistent system and sticks to it. OTKO follows the same rule, one step further:

1. Stored values are always in the project's native system (ProjectMeta.units, default SI_M_N). The solver, persistence, and undo stack only ever see native values.
2. Views may relabel or rescale for humans, never for the solver. Any display conversion is a pure view-layer factor applied on read; converted values are never written back.
3. Every number shown to the user carries its unit, or is explicitly dimensionless (strain, drift ratio, damping ratio).

What this document does NOT propose: auto-conversion on input, unit migration of existing models, or any change to OpenSeesPy command emission order/content (docs/architecture.md stays authoritative).

2. Where we are

• src/otko/core/units.py — UnitSystem enum (4 systems), frozen UnitLabels bundle (length / force / moment / stress / curvature / rotation, rotation always rad), labels_for() helper. Display only; zero conversion factors anywhere in the repo.
• ProjectMeta.units (src/otko/core/project.py:124) persisted in every .osmodel; SetUnitsCommand (src/otko/commands/project.py) is display-only by contract; Options → Set Display Units (src/otko/views/action_handlers.py) applies it and refreshes docks.
• Views consume labels via set_units() (src/otko/views/dock_manager.py): pushover curve and material tester do; force diagrams, time-history, results panel, and response-spectrum Sa axis do not. section_editor hardcodes y (m) / z (m) — wrong for kip-in models. DOF labels (views/docks/_labels.py) are unitless by design.
• ADR-0001 §2.7 deferred per-field UnitTag quantity annotations; generated catalog fields are still str placeholders ('500 MPa', # TODO: unit-aware type). The quantity taxonomy in §5 below is meant to become those UnitTag strings verbatim.
• Examples use two systems in practice: SI_M_N (cantilever → M3 peaks 50 kN·m; portal, space frame, concrete04) and US_IN_KIP (ex1a–ex4 families in inches/kips/ksi, G=386.4 in/s²). SI_MM_N and US_FT_KIP appear only in the enum, tests, and assign_hinge prefills. basic_truss.py hand-converts (IN_TO_M, KIP_TO_N) to work in SI — the only example that does.
• Roadmap backlog item 3 already asks for "units-aware labels" in the input-dialog pass; this plan is the spec for that item.

3. Canonical systems

Update (Sept 2026): collapsed to two stored systems, METRIC and IMPERIAL (§3.1 and §3.4 below, renamed). SI_MM_N and US_FT_KIP are retired — old .osmodel files still load via the LEGACY_UNIT_SYSTEMS map in core/units.py, but their stored numbers keep the old mm/ft scale (re-enter values natively). The status bar offers Metric / Imperial only; switching routes through SetUnitsCommand and refreshes every units-aware label (_sync_units_everywhere on modelMutated, covering combo, menu, and undo/redo). All values stay native, so every label next to a value uses the NATIVE table (native_label()), never the DISPLAY prefixes — DISPLAY remains data-only for a future true display-switching phase. Each table lists the stored unit (what the solver and .osmodel see) and the display unit + factor (view layer only, applied on read).

3.1 Metric — SI_M_N (m, N, Pa)

Building/civil scale. Stored = displayed, except where humans expect scaled prefixes (factor applies at the view, values untouched).

Quantity	Stored	Display	Factor
Geometry / length	m	m	1
Section dims	m	mm	1000
Displacement	m	mm	1000
Rotation	rad	rad	1 (° toggle, §6)
Point load	N	kN	1e-3
Distributed load	N/m	kN/m	1e-3
Moment	N·m	kN·m	1e-3
Stress / modulus	Pa	MPa	1e-6
Area	m²	mm²	1e6
Inertia	m⁴	mm⁴ / cm⁴	1e12 / 1e8
Mass	kg	kg (t for large)	1
Time / period	s	s	1

3.2 Metric — SI_MM_N (mm, N, MPa)

Detail/component scale (steel connections, lab specimens). Stored = displayed everywhere; no factors.

Quantity	Stored = Display
Geometry, section dims, displacement	mm
Rotation	rad
Point load	N
Distributed load	N/mm
Moment	N·mm
Stress / modulus	MPa
Mass	t

3.3 Imperial — US_FT_KIP (ft, kip, ksf)

Building scale. The mixed ft/in convention engineers expect (lengths in feet, displacements in inches) requires display factors — this is the case that forces §4 to exist.

Quantity	Stored	Display	Factor
Geometry / length	ft	ft	1
Section dims	ft	in	12
Displacement	ft	in	12
Rotation	rad	rad	1 (° toggle, §6)
Point load	kip	kip	1
Distributed load	kip/ft	kip/ft (plf alt.)	1
Moment	kip·ft	kip·ft	1
Stress / modulus	ksf	ksi (materials)	1/144
Area	ft²	in²	144
Inertia	ft⁴	in⁴	20736
Mass	slug	slug	1
Time / period	s	s	1

Small-load alternative: lbf / plf / lb·ft are display aliases (×1000 from kip units), not separate systems. A view showing 0.004 kip should render 4.0 lbf; threshold and format rules are view concerns (§6).

3.4 Imperial — US_IN_KIP (in, kip, ksi)

Component scale (members, sections, the ex1a–ex4 example families). Stored = displayed everywhere; no factors.

Quantity	Stored = Display
Geometry, section dims, displacement	in
Rotation	rad
Point load	kip (lbf alias ×1000)
Distributed load	kip/in
Moment	kip·in
Stress / modulus	ksi
Mass	kip·s²/in

Gravity for mass derivation is 386.4 in/s² in this system (32.2 ft/s² under US_FT_KIP, 9.81 m/s² metric) — document the constant next to every mass-from-weight computation; never hardcode it in a system-agnostic path.

4. Display-factor mechanism (view layer only)

New pure-data table in core/units.py, e.g. DISPLAY: dict[UnitSystem, dict[str, tuple[str, float]]] mapping quantity → (display label, multiply-by-factor). Rules:

• Factors live in core/ as data only (like _LABELS today) — no Qt, no application logic, trivially unit-testable.
• Factors are applied in views/viewmodels on read (axis labels, table cells, diagram annotations). Converted values never flow into commands, services, or persistence.
• rotation factor is always 1 (rad); a degrees toggle is a formatting option (§6), not a system.
• Dimensionless quantities (strain, drift, damping ratio, mass participation) never take factors.

This keeps the current "we don't auto-convert" contract intact: the solver boundary is untouched; only human-facing strings change.

5. Quantity taxonomy (shared with ADR-0001)

Each numeric field in core/ and catalog/ eventually gets one of these quantity tags (same strings as the future UnitTag, so the follow-up ADR adopts them unchanged):

length, displacement, rotation, force, moment, distributed_load, stress, area, inertia, mass, time, frequency, temperature

Minimum viable step (no ADR needed): use the taxonomy as the key set for the §4 table and as the vocabulary for dialog hints (§6). Field annotation (UnitTag) stays deferred per ADR-0001 §2.7.

6. UI rollout checklist

File-by-file, each item independently reviewable:

• views/dialogs/section_editor.py:184-185 — replace hardcoded (m) with labels_for() length unit. (Bug fix, do first.)
• views/docks/force_diagram.py — append force/moment display units to component labels and min/max annotations.
• views/docks/time_history.py — y-axis unit per trace kind (displacement / velocity / acceleration); x-axis stays s.
• views/docks/results_panel.py — displacement/force headers take display units; modal table keeps rad²/s², rad/s, Hz, s.
• views/docks/response_spectrum.py — Sa axis takes the acceleration display unit; period stays s.
• Assign dialogs (assign_load, distributed_load, pattern_loads) — unit hints on field labels, e.g. wy (kip/ft), driven by project system (roadmap item 3).
• Table dock headers — name-style unit suffixes where numeric columns carry units; dimensionless columns stay bare.
• Rotation display — solver and storage stay rad; add an optional ° formatting toggle in post views only (×180/π on read).
• lbf/plf small-value aliases — formatting rule in shared label helper, not per-view logic.

7. Persistence, examples, conventions

• meta.units keeps meaning "native stored system". Display choices (factors applied, ° toggle, lbf alias) are never persisted — reopening a file always shows native-unit defaults.
• Old files without new fields (if any are added as Optional with defaults) load unchanged; ProjectMeta extra="forbid" still rejects unknown keys — no migration needed for this plan.
• Document each example family's convention at the top of its script (one comment line: system + key constants). Add one SI_MM_N and one US_FT_KIP example so all four systems have runner-verified coverage; today two systems have none.
• Rule for new examples: no hand-conversion constants. Either model natively in the declared system or, once §4 exists, use the shared factor table. basic_truss.py is grandfathered until then.

8. Verification

• Extend tests/unit/test_unit_labels.py: factor-table coverage per system (identity for US_IN_KIP/SI_MM_N; ft→in ×12, N→kN, Pa→MPa, ksf→ksi spots), rotation always factor 1, dimensionless quantities absent from the table.
• Round-trip invariant: regen all examples, git diff on *.osmodel must show label/metadata changes only — never numeric value changes.
• GUI smoke (offscreen/xvfb): open one model per system, flip display units, assert axis/table labels change and stored values do not (compare model_dump() before/after).

9. Phases

• A — label the stored unit everywhere (§6 minus factors): no new mechanism, pure label plumbing. Shippable alone.
• B — display-factor table + apply in post views (§4, §5 keys): ft→in, N→kN, Pa→MPa and friends appear; solver untouched.
• C — input-dialog hints + section_editor fix (roadmap item 3): hints only, values still entered in native units.
• D — optional, needs follow-up ADR: true display-unit switching (type in inches, store feet) and UnitTag field annotation per ADR-0001 §2.7. Explicitly out of scope until A–C ship.