unitsml 0.6.13 → 0.6.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c599180abf511dcf8c6bc582c48126e482b80b3acbb0c443f89b270334243ab6
4
- data.tar.gz: 48450a6d5df613392cf903581ef55ce193b0f5e32731f9a0e6812d170ebf5381
3
+ metadata.gz: 4f0e789863b74838c4a9cabe798ff4ea0bbef3f010d193cfab139ee3af6a407e
4
+ data.tar.gz: 6c8bde6232eeb9b601629ebd8c49a68571d01c6f84d86bb138cff715cf41f105
5
5
  SHA512:
6
- metadata.gz: 2d0e5ca17cb5d3124151463fb8bbdb436521f175eeba95f38a08f464e104a8d89e4f30afdf80d24e86f1f0985799929b14cfcd9013f266967a7ceebb437cb2de
7
- data.tar.gz: 9a83f7c51f331e0db38072dfaf61ae61f50c0f76535f11ba00246847770fc943625cf0deb10dedee13c1310315bee1e11e810fd00c46b03f1e30bf097f87070a
6
+ metadata.gz: 793fc719afa895d9d11ec3e7da13d9e5f75f1b9d269127c521aa7deadc775ce4fbbd500713ae5c08677bc2394793d4bb3cbae562c71c87e4a497c25fa7e7237c
7
+ data.tar.gz: a2c617c33eb6842a0c120afe81bdbaef08a4b4dba621a01916665c308efa8840fa114e14a526ade2f253647f95d7814ffd9a53891dc3361c42c182d1537d41fb
@@ -16,13 +16,10 @@ module Unitsml
16
16
  # "/" and inverts b's power; `a * b` keeps "*"). An explicit trailing
17
17
  # extender on the left (from #extender) already is the join, so no glyph
18
18
  # is inserted after it — but `/` still inverts the right-hand side.
19
- # An empty side inserts no glyph. invert_dimensions: false keeps
20
- # Dimension leaves un-inverted on division (Quantity compatibility).
21
- def build_product(left_terms, right_terms, operator,
22
- invert_dimensions: true)
19
+ # An empty side inserts no glyph.
20
+ def build_product(left_terms, right_terms, operator)
23
21
  left = build_terms(left_terms, invert: false)
24
- right = build_terms(right_terms, invert: operator == "/",
25
- invert_dimensions: invert_dimensions)
22
+ right = build_terms(right_terms, invert: operator == "/")
26
23
  joiner = join_glyph(left, right, operator)
27
24
  build_root_formula(left + joiner + right)
28
25
  end
@@ -33,7 +30,7 @@ module Unitsml
33
30
  return nil unless left || right
34
31
 
35
32
  build_product(left ? left.value : [], right ? right.value : [],
36
- operator, invert_dimensions: false)
33
+ operator)
37
34
  end
38
35
 
39
36
  # Independent copy of a Formula (tree, powers, prefixes, text and
@@ -99,11 +96,8 @@ module Unitsml
99
96
  # Rebuild every operand: map_leaves reconstructs branch wrappers and
100
97
  # each Unit/Dimension leaf is copied with a freshly built final power
101
98
  # (and a duplicated prefix). Non-leaf terms (Extender/Number) plain-dup.
102
- def build_terms(terms, invert:, invert_dimensions: true)
103
- TermTree.map_leaves(terms) do |leaf|
104
- rebuild_leaf(leaf, invert && (invert_dimensions ||
105
- !leaf.is_a?(Dimension)))
106
- end
99
+ def build_terms(terms, invert:)
100
+ TermTree.map_leaves(terms) { |leaf| rebuild_leaf(leaf, invert) }
107
101
  end
108
102
 
109
103
  def join_glyph(left, right, operator)
@@ -0,0 +1,175 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Unitsml
4
+ module Conversion
5
+ # A validated caller register: per-unit factors (and affine offsets)
6
+ # to the canonical SI composition, supplied by the caller rather than
7
+ # read from UnitsDB. WORK-PACKAGES F02: "Use data or validated caller
8
+ # registers for factors/addends; preserve exact arithmetic and source
9
+ # provenance."
10
+ #
11
+ # Entry: { "unit" => id or symbol, "factor" => exact decimal/rational
12
+ # String, "offset" => optional exact String, "dimensions" => { base
13
+ # dimension name => exponent String } }. Semantics match the UnitsDB
14
+ # canonical_conversion: value_SI = value * factor + offset.
15
+ #
16
+ # Validation fails explicitly (InvalidUnitRegisterError): unknown
17
+ # fields, non-String or non-exact numbers, a factor that is not
18
+ # positive, declared dimensions that differ from the unit's own, and an
19
+ # entry that disagrees with the register's canonical_conversion for
20
+ # the same unit (the 1e-9 relative tolerance used by Conversion#agree!).
21
+ # An unknown unit raises UnknownUnitError. A later entry for the same
22
+ # unit replaces an earlier one.
23
+ #
24
+ # A register applies only inside Conversion.with_register; it never
25
+ # persists past the block.
26
+ class Register
27
+ FIELDS = %w[unit factor offset dimensions].freeze
28
+ EXACT = %r{\A[+-]?(?:\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|\d+/\d+)\z}
29
+ # vector: the declared base-dimension exponents, used by Quantity to gate
30
+ # units that have no UnitsDB decomposition of their own.
31
+ Entry = Struct.new(:record, :factor, :offset, :vector, keyword_init: true)
32
+
33
+ attr_reader :entries
34
+
35
+ def initialize(entries)
36
+ unless entries.is_a?(Array)
37
+ raise Errors::InvalidUnitRegisterError,
38
+ "a register is an Array of entries, got #{entries.class}"
39
+ end
40
+
41
+ @entries = {}
42
+ entries.each do |raw|
43
+ entry = build_entry(raw)
44
+ @entries[identity(entry.record)] = entry
45
+ end
46
+ end
47
+
48
+ def entry_for(record)
49
+ @entries[identity(record)]
50
+ end
51
+
52
+ def empty?
53
+ @entries.empty?
54
+ end
55
+
56
+ private
57
+
58
+ def identity(record)
59
+ record.identifiers.to_a.map { |i| "#{i.type}:#{i.id}" }.sort.join("|")
60
+ end
61
+
62
+ def build_entry(raw) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
63
+ unless raw.is_a?(Hash)
64
+ raise Errors::InvalidUnitRegisterError,
65
+ "a register entry is a Hash, got #{raw.class}"
66
+ end
67
+
68
+ raw = raw.transform_keys(&:to_s)
69
+ extra = raw.keys - FIELDS
70
+ unless extra.empty?
71
+ raise Errors::InvalidUnitRegisterError,
72
+ "unknown register entry field(s) #{extra.sort.inspect}"
73
+ end
74
+
75
+ record = resolve_unit(raw["unit"])
76
+ factor = exact(raw["factor"], "factor")
77
+ unless factor.positive?
78
+ raise Errors::InvalidUnitRegisterError,
79
+ "register factor must be positive, got #{raw['factor']}"
80
+ end
81
+
82
+ offset = raw.key?("offset") ? exact(raw["offset"], "offset") : 0r
83
+ vector = check_dimensions!(record, raw["dimensions"])
84
+ check_canonical!(record, factor, offset)
85
+ Entry.new(record: record, factor: factor, offset: offset,
86
+ vector: vector)
87
+ end
88
+
89
+ def resolve_unit(name)
90
+ unless name.is_a?(String) && !name.strip.empty?
91
+ raise Errors::InvalidUnitRegisterError,
92
+ "register unit must be a non-empty String"
93
+ end
94
+
95
+ record = Unitsdb.units.find_by_id(name) ||
96
+ Unitsdb.units.find_by_name(name)
97
+ return record if record
98
+
99
+ raise Errors::UnknownUnitError.new(value: name)
100
+ end
101
+
102
+ def exact(value, field)
103
+ unless value.is_a?(String) && EXACT.match?(value)
104
+ raise Errors::InvalidUnitRegisterError,
105
+ "register #{field} must be an exact decimal or rational " \
106
+ "String, got #{value.inspect}"
107
+ end
108
+
109
+ Rational(value)
110
+ end
111
+
112
+ # The declared dimensions must name the unit's own UnitsDB dimension:
113
+ # both are resolved to a dimension identity through Utility.dim_id and
114
+ # the unit's primary quantity, so no expression is reparsed.
115
+ def check_dimensions!(record, declared) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
116
+ unless declared.is_a?(Hash) && !declared.empty?
117
+ raise Errors::InvalidUnitRegisterError,
118
+ "register dimensions must be a non-empty Hash"
119
+ end
120
+
121
+ list = declared.filter_map do |name, exponent|
122
+ value = exact(exponent.to_s, "dimension exponent")
123
+ next if value.zero?
124
+
125
+ unless value.denominator == 1
126
+ raise Errors::InvalidUnitRegisterError,
127
+ "register dimension exponents must be integers"
128
+ end
129
+
130
+ { dimension: name.to_s, exponent: value.to_i }
131
+ end
132
+ wanted = registered_dimension_id(list)
133
+ actual = unit_dimension_id(record)
134
+ if actual && wanted == actual
135
+ return list.to_h { |d| [d[:dimension], d[:exponent]] }
136
+ end
137
+
138
+ raise Errors::InvalidUnitRegisterError,
139
+ "register dimensions #{declared.inspect} (#{wanted.inspect}) " \
140
+ "differ from the unit's dimension #{actual.inspect}"
141
+ end
142
+
143
+ # Only dimensions the register itself names; an unnamed vector has no
144
+ # identity to compare and is refused.
145
+ def registered_dimension_id(list)
146
+ vector = Utility::DIMS_VECTOR.map do |name|
147
+ list.find { |d| d[:dimension] == name }&.dig(:exponent)
148
+ end.join(":")
149
+ Unitsdb.dimensions.find_by_vector(vector)&.id&.to_s
150
+ end
151
+
152
+ def unit_dimension_id(record)
153
+ QuantityKind.primary_for(record)&.dimension_id ||
154
+ (record.respond_to?(:dimension_url) && record.dimension_url)
155
+ end
156
+
157
+ def check_canonical!(record, factor, offset) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
158
+ cc = record.canonical_conversion
159
+ return unless cc
160
+
161
+ canonical = [Rational(cc.factor), Rational(cc.offset || 0)]
162
+ agreed = canonical.zip([factor, offset]).all? do |ours, theirs|
163
+ delta = (ours - theirs).abs
164
+ delta.zero? || delta <= ours.abs / Rational(10**9)
165
+ end
166
+ return if agreed
167
+
168
+ raise Errors::InvalidUnitRegisterError,
169
+ "register entry (#{factor}, #{offset}) disagrees with the " \
170
+ "canonical conversion (#{canonical[0]}, #{canonical[1]}) for " \
171
+ "#{record.symbols.to_a.first&.id.inspect}"
172
+ end
173
+ end
174
+ end
175
+ end
@@ -12,6 +12,7 @@ module Unitsml
12
12
  # inside a composite raises.
13
13
  module Conversion
14
14
  autoload :Definition, "unitsml/conversion/definition"
15
+ autoload :Register, "unitsml/conversion/register"
15
16
 
16
17
  Result = Struct.new(:factor, :offset, keyword_init: true)
17
18
 
@@ -30,6 +31,32 @@ module Unitsml
30
31
  walk(formula, 1, definitions: definitions)
31
32
  end
32
33
 
34
+ REGISTER_KEY = :unitsml_conversion_register
35
+
36
+ # Applies a validated caller register (Conversion::Register, or the
37
+ # Array of entries it validates) to every conversion inside the block,
38
+ # including the operand alignment of Quantity#+ and #-. The register is
39
+ # scoped to the block and the current thread; it never persists.
40
+ #
41
+ # Validation (Register.new) completes before the thread state is
42
+ # touched, and the ensure restores only what this call replaced: a
43
+ # register rejected inside an outer with_register leaves the outer one
44
+ # active.
45
+ def with_register(register)
46
+ register = Register.new(register) unless register.is_a?(Register)
47
+ previous = Thread.current[REGISTER_KEY]
48
+ Thread.current[REGISTER_KEY] = register
49
+ begin
50
+ yield register
51
+ ensure
52
+ Thread.current[REGISTER_KEY] = previous
53
+ end
54
+ end
55
+
56
+ def current_register
57
+ Thread.current[REGISTER_KEY]
58
+ end
59
+
33
60
  def walk(node, sign, definitions: nil)
34
61
  case node
35
62
  when Formula
@@ -90,7 +117,17 @@ module Unitsml
90
117
  # A supplied definition replaces the canonical factor/offset for its
91
118
  # unit — the two paths are never applied in sequence; when the
92
119
  # register also carries canonical data, the two must agree.
93
- if (definition = definition_for(record, definitions))
120
+ definition = definition_for(record, definitions)
121
+ entry = definition ? nil : current_register&.entry_for(record)
122
+ if entry
123
+ return register_result(entry, power, prefix_factor)
124
+ end
125
+
126
+ if power.denominator != 1
127
+ return fractional_unit_result(record, definition, prefix_factor, power)
128
+ end
129
+
130
+ if definition
94
131
  def_factor, def_offset = definition_result(definition, power, record)
95
132
  return Result.new(factor: def_factor * (prefix_factor**power),
96
133
  offset: def_offset)
@@ -98,11 +135,68 @@ module Unitsml
98
135
 
99
136
  # The prefix scales with the unit power: 1 km2 = 1 000 000 m2, not
100
137
  # 1 000 m2 — the prefix is as squared as the unit is.
101
- factor, offset = record_factor(record, power, [record_identity(record)])
138
+ factor, offset = record_factor(record, power)
102
139
  factor *= prefix_factor**power
103
140
  Result.new(factor: factor, offset: offset)
104
141
  end
105
142
 
143
+ # Resolve the complete ratio before taking a root. The record and prefix
144
+ # factors can have irrational roots individually and a rational root
145
+ # after multiplication (for example, the square root of a milligram).
146
+ def fractional_unit_result(record, definition, prefix_factor, power)
147
+ factor, offset = if definition
148
+ definition_result(definition, 1, record)
149
+ else
150
+ record_factor(record, 1)
151
+ end
152
+ unless offset.zero?
153
+ raise Errors::ConversionError, "affine unit raised to power #{power}"
154
+ end
155
+
156
+ base = factor * prefix_factor
157
+ degree = power.denominator
158
+ numerator = exact_integer_root(base.numerator, degree)
159
+ denominator = exact_integer_root(base.denominator, degree)
160
+ unless numerator && denominator
161
+ raise Errors::InexactPowerError, "#{base} raised to #{power} is not rational"
162
+ end
163
+
164
+ Result.new(factor: Rational(numerator, denominator)**power.numerator,
165
+ offset: offset)
166
+ end
167
+
168
+ def exact_integer_root(value, degree)
169
+ return if value.negative? && degree.even?
170
+
171
+ magnitude = value.abs
172
+ return value if magnitude <= 1
173
+ return if degree > magnitude.bit_length
174
+
175
+ lower = 1
176
+ upper = 1 << ((magnitude.bit_length + degree - 1) / degree)
177
+ root = (lower..upper).bsearch { |candidate| candidate**degree >= magnitude }
178
+ return unless root**degree == magnitude
179
+
180
+ value.negative? ? -root : root
181
+ end
182
+
183
+ # A caller register entry replaces the canonical factor/offset for its
184
+ # unit, as a definition does. Affine entries (non-zero offset) are legal
185
+ # only at power 1; a fractional power of a register entry is refused
186
+ # rather than approximated.
187
+ def register_result(entry, power, prefix_factor)
188
+ if entry.offset != 0 && power != 1
189
+ raise Errors::ConversionError, "affine unit raised to power #{power}"
190
+ end
191
+ if power.denominator != 1
192
+ raise Errors::InexactPowerError,
193
+ "a register entry at fractional power #{power} is not exact"
194
+ end
195
+
196
+ Result.new(factor: (entry.factor**power) * (prefix_factor**power),
197
+ offset: entry.offset)
198
+ end
199
+
106
200
  # The definition supplied for this record, if any. Lookup keys are the
107
201
  # register ids and symbols of the record.
108
202
  def definition_for(record, definitions)
@@ -174,7 +268,52 @@ module Unitsml
174
268
  record.identifiers&.map { |i| "#{i.type}:#{i.id}" }&.sort&.join("|")
175
269
  end
176
270
 
177
- def record_factor(record, power, _visited = [])
271
+ # Cycle guard: the derivation chain of one unit (si_derived_bases /
272
+ # root_units) is followed with the path of unit identities already on
273
+ # it. Reaching a unit already on the path is a cyclic definition in the
274
+ # register data (gram-force NISTu196 lists kilo x itself as its root):
275
+ # it has no linear canonical conversion, so it raises ConversionError
276
+ # naming the cycle instead of recursing without bound.
277
+ def guard_cycle!(record, path)
278
+ identity = record_identity(record)
279
+ return path + [identity] unless path.include?(identity)
280
+
281
+ cycle = path[path.index(identity)..] + [identity]
282
+ raise Errors::ConversionError,
283
+ "cyclic unit definition in the register data: " \
284
+ "#{cycle.map { |id| unit_label(id) }.join(' -> ')}"
285
+ end
286
+
287
+ def unit_label(identity)
288
+ nist = identity.to_s.split("|").find { |part| part.start_with?("nist:") }
289
+ id = nist&.delete_prefix("nist:")
290
+ record = id && Unitsml::Unitsdb.units.find_by_id(id)
291
+ symbol = record && record.symbols.to_a.first&.id
292
+ symbol ? "#{symbol} (#{id})" : identity.to_s
293
+ end
294
+
295
+ # Cycle-free results are reused. The key includes the loaded database
296
+ # object, so a reloaded or substituted database never sees stale values;
297
+ # errors (cycles, missing paths) are never cached.
298
+ MEMO_LIMIT = 4096
299
+
300
+ def memoized(kind, record, power)
301
+ memo = (@memo ||= {})
302
+ key = [kind, Unitsml::Unitsdb.database.object_id,
303
+ record_identity(record), power]
304
+ return memo[key] if memo.key?(key)
305
+
306
+ value = yield
307
+ memo.clear if memo.size >= MEMO_LIMIT
308
+ memo[key] = value.freeze
309
+ end
310
+
311
+ def record_factor(record, power, path = [])
312
+ path = guard_cycle!(record, path)
313
+ memoized(:factor, record, power) { record_factor_uncached(record, power, path) }
314
+ end
315
+
316
+ def record_factor_uncached(record, power, path)
178
317
  cc = record.canonical_conversion
179
318
  return conversion_factor(cc, power) if cc
180
319
 
@@ -195,7 +334,8 @@ module Unitsml
195
334
  bases.each do |base|
196
335
  base_power = (base.power || 1) * power
197
336
  prefix_factor = prefix_factor_from_reference(base.prefix_reference)
198
- sub_factor, sub_offset = base_factor(base.unit_reference, base_power)
337
+ sub_factor, sub_offset = base_factor(base.unit_reference, base_power,
338
+ path)
199
339
  if sub_offset != 0
200
340
  raise Errors::ConversionError,
201
341
  "affine unit inside a derived composition"
@@ -219,11 +359,11 @@ module Unitsml
219
359
  [factor, offset]
220
360
  end
221
361
 
222
- def base_factor(unit_reference, power)
362
+ def base_factor(unit_reference, power, path = [])
223
363
  record = Unitsml::Unitsdb.units.find_by_id(unit_reference.id)
224
364
  raise Errors::ConversionError, "unknown conversion target" unless record
225
365
 
226
- record_factor(record, power)
366
+ record_factor(record, power, path)
227
367
  end
228
368
 
229
369
  def prefix_factor_from_reference(reference)
@@ -291,10 +431,19 @@ module Unitsml
291
431
  end
292
432
  end
293
433
 
434
+ # visited: the path of unit identities above this record (an Array; the
435
+ # legacy callers pass []). A revisit is a cyclic definition and raises
436
+ # ConversionError, as record_factor does.
294
437
  def unit_dimensions(record, power, visited)
295
- return nil if record.nil? || visited.include?(record.object_id)
438
+ return nil if record.nil?
439
+
440
+ path = guard_cycle!(record, visited)
441
+ memoized(:dimensions, record, power) do
442
+ unit_dimensions_uncached(record, power, path)
443
+ end
444
+ end
296
445
 
297
- visited = visited + [record.object_id]
446
+ def unit_dimensions_uncached(record, power, visited)
298
447
  sym = record.symbols&.first&.id
299
448
  if (u2d = Unitsml::Utility::U2D[sym])
300
449
  return [{ dimension: u2d[:dimension], symbol: u2d[:symbol],
@@ -7,5 +7,17 @@ module Unitsml
7
7
  class ScaleOperationError < QuantityOperationError; end
8
8
  class IndeterminateResultError < QuantityOperationError; end
9
9
  class ConversionError < QuantityOperationError; end
10
+ class InexactPowerError < ConversionError; end
11
+ # Data-declared kinds of the same dimension that the register does not
12
+ # make interchangeable (torque + energy).
13
+ class QuantityKindMismatchError < QuantityOperationError; end
14
+ class UnknownQuantityKindError < QuantityOperationError; end
15
+ # A unit record whose quantity references do not identify exactly one
16
+ # primary quantity.
17
+ class PrimaryQuantityError < BaseError; end
18
+ # A caller register entry that cannot be used: bad factor/offset,
19
+ # declared dimensions that differ from the unit's, or disagreement
20
+ # with the register's own canonical conversion.
21
+ class InvalidUnitRegisterError < ConversionError; end
10
22
  end
11
23
  end
@@ -6,6 +6,7 @@ module Unitsml
6
6
  autoload :ConversionError, "unitsml/errors/quantity_errors"
7
7
  autoload :EmptyCompositionError, "unitsml/errors/empty_composition_error"
8
8
  autoload :InvalidModelError, "unitsml/errors/invalid_model_error"
9
+ autoload :InexactPowerError, "unitsml/errors/quantity_errors"
9
10
  autoload :InvalidPowerError, "unitsml/errors/invalid_power_error"
10
11
  autoload :InvalidUnitEntryError, "unitsml/errors/invalid_unit_entry_error"
11
12
  autoload :MisplacedExtenderError,
@@ -20,6 +21,10 @@ module Unitsml
20
21
  autoload :DimensionMismatchError, "unitsml/errors/quantity_errors"
21
22
  autoload :ScaleOperationError, "unitsml/errors/quantity_errors"
22
23
  autoload :IndeterminateResultError, "unitsml/errors/quantity_errors"
24
+ autoload :QuantityKindMismatchError, "unitsml/errors/quantity_errors"
25
+ autoload :UnknownQuantityKindError, "unitsml/errors/quantity_errors"
26
+ autoload :PrimaryQuantityError, "unitsml/errors/quantity_errors"
27
+ autoload :InvalidUnitRegisterError, "unitsml/errors/quantity_errors"
23
28
  autoload :UnknownDimensionError, "unitsml/errors/unknown_dimension_error"
24
29
  autoload :UnknownPrefixError, "unitsml/errors/unknown_prefix_error"
25
30
  autoload :UnknownUnitError, "unitsml/errors/unknown_unit_error"