1 /* Copyright 2002-2023 CS GROUP
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.orekit.utils.units;
18
19 import java.io.Serializable;
20 import java.util.List;
21
22 import org.hipparchus.fraction.Fraction;
23 import org.hipparchus.util.FastMath;
24 import org.hipparchus.util.Precision;
25 import org.orekit.errors.OrekitException;
26 import org.orekit.errors.OrekitMessages;
27
28 /** Basic handling of multiplicative units.
29 * <p>
30 * This class is by no means a complete handling of units. For complete
31 * support, look at libraries like {@code UOM}. This class handles only
32 * time, length, mass and current dimensions, as well as angles (which are
33 * dimensionless).
34 * </p>
35 * <p>
36 * Instances of this class are immutable.
37 * </p>
38 * @see <a href="https://github.com/netomi/uom">UOM</a>
39 * @author Luc Maisonobe
40 * @since 11.0
41 */
42 public class Unit implements Serializable {
43
44 /** No unit. */
45 public static final Unit NONE = new Unit("n/a", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);
46
47 /** Dimensionless unit. */
48 public static final Unit ONE = new Unit("1", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);
49
50 /** Percentage unit. */
51 public static final Unit PERCENT = new Unit("%", 1.0e-2, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);
52
53 /** Second unit. */
54 public static final Unit SECOND = new Unit("s", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ONE, Fraction.ZERO, Fraction.ZERO);
55
56 /** Minute unit. */
57 public static final Unit MINUTE = SECOND.scale("min", 60.0);
58
59 /** Hour unit. */
60 public static final Unit HOUR = MINUTE.scale("h", 60);
61
62 /** Day unit. */
63 public static final Unit DAY = HOUR.scale("d", 24.0);
64
65 /** Julian year unit.
66 * @see <a href="https://www.iau.org/publications/proceedings_rules/units/">SI Units at IAU</a>
67 */
68 public static final Unit YEAR = DAY.scale("a", 365.25);
69
70 /** Hertz unit. */
71 public static final Unit HERTZ = SECOND.power("Hz", Fraction.MINUS_ONE);
72
73 /** Metre unit. */
74 public static final Unit METRE = new Unit("m", 1.0, Fraction.ZERO, Fraction.ONE, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);
75
76 /** Kilometre unit. */
77 public static final Unit KILOMETRE = METRE.scale("km", 1000.0);
78
79 /** Kilogram unit. */
80 public static final Unit KILOGRAM = new Unit("kg", 1.0, Fraction.ONE, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);
81
82 /** Gram unit. */
83 public static final Unit GRAM = KILOGRAM.scale("g", 1.0e-3);
84
85 /** Ampere unit. */
86 public static final Unit AMPERE = new Unit("A", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ONE, Fraction.ZERO);
87
88 /** Radian unit. */
89 public static final Unit RADIAN = new Unit("rad", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ONE);
90
91 /** Degree unit. */
92 public static final Unit DEGREE = RADIAN.scale("°", FastMath.toRadians(1.0));
93
94 /** Arc minute unit. */
95 public static final Unit ARC_MINUTE = DEGREE.scale("′", 1.0 / 60.0);
96
97 /** Arc second unit. */
98 public static final Unit ARC_SECOND = ARC_MINUTE.scale("″", 1.0 / 60.0);
99
100 /** Revolution unit. */
101 public static final Unit REVOLUTION = RADIAN.scale("rev", 2.0 * FastMath.PI);
102
103 /** Newton unit. */
104 public static final Unit NEWTON = KILOGRAM.multiply(null, METRE).divide("N", SECOND.power(null, Fraction.TWO));
105
106 /** Pascal unit. */
107 public static final Unit PASCAL = NEWTON.divide("Pa", METRE.power(null, Fraction.TWO));
108
109 /** Bar unit. */
110 public static final Unit BAR = PASCAL.scale("bar", 100000.0);
111
112 /** Joule unit. */
113 public static final Unit JOULE = NEWTON.multiply("J", METRE);
114
115 /** Watt unit. */
116 public static final Unit WATT = JOULE.divide("W", SECOND);
117
118 /** Coulomb unit. */
119 public static final Unit COULOMB = SECOND.multiply("C", AMPERE);
120
121 /** Volt unit. */
122 public static final Unit VOLT = WATT.divide("V", AMPERE);
123
124 /** Ohm unit. */
125 public static final Unit OHM = VOLT.divide("Ω", AMPERE);
126
127 /** tesla unit. */
128 public static final Unit TESLA = VOLT.multiply(null, SECOND).divide("T", METRE.power(null, Fraction.TWO));
129
130 /** Solar Flux Unit. */
131 public static final Unit SOLAR_FLUX_UNIT = WATT.divide(null, METRE.power(null, Fraction.TWO).multiply(null, HERTZ)).scale("SFU", 1.0e-22);
132
133 /** Total Electron Content Unit. */
134 public static final Unit TOTAL_ELECTRON_CONTENT_UNIT = METRE.power(null, new Fraction(-2)).scale("TECU", 1.0e+16);
135
136 /** Earth Radii used as Bstar unit in CCSDS OMM. */
137 public static final Unit EARTH_RADII = new Unit("ER", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ONE, Fraction.ZERO);
138
139 /** Serializable UID. */
140 private static final long serialVersionUID = 20210402L;
141
142 /** Name name of the unit. */
143 private final String name;
144
145 /** Scaling factor to SI units. */
146 private final double scale;
147
148 /** Mass exponent. */
149 private final Fraction mass;
150
151 /** Length exponent. */
152 private final Fraction length;
153
154 /** Time exponent. */
155 private final Fraction time;
156
157 /** Current exponent. */
158 private final Fraction current;
159
160 /** Angle exponent. */
161 private final Fraction angle;
162
163 /** Simple constructor.
164 * @param name name of the unit
165 * @param scale scaling factor to SI units
166 * @param mass mass exponent
167 * @param length length exponent
168 * @param time time exponent
169 * @param current current exponent
170 * @param angle angle exponent
171 */
172 public Unit(final String name, final double scale,
173 final Fraction mass, final Fraction length,
174 final Fraction time, final Fraction current,
175 final Fraction angle) {
176 this.name = name;
177 this.scale = scale;
178 this.mass = mass;
179 this.length = length;
180 this.time = time;
181 this.current = current;
182 this.angle = angle;
183 }
184
185 /** Get the name of the unit.
186 * @return name of the unit
187 */
188 public String getName() {
189 return name;
190 }
191
192 /** Get the scaling factor to SI units.
193 * @return scaling factor to SI units
194 */
195 public double getScale() {
196 return scale;
197 }
198
199 /** Get the mass exponent.
200 * @return mass exponent
201 */
202 public Fraction getMass() {
203 return mass;
204 }
205
206 /** Get the length exponent.
207 * @return length exponent
208 */
209 public Fraction getLength() {
210 return length;
211 }
212
213 /** Get the time exponent.
214 * @return time exponent
215 */
216 public Fraction getTime() {
217 return time;
218 }
219
220 /** Get the current exponent.
221 * @return current exponent
222 */
223 public Fraction getCurrent() {
224 return current;
225 }
226
227 /** Get the angle exponent.
228 * @return angle exponent
229 */
230 public Fraction getAngle() {
231 return angle;
232 }
233
234 /** Check if a unit has the same dimension as another unit.
235 * @param other other unit to check against
236 * @return true if unit has the same dimension as the other unit
237 */
238 public boolean sameDimension(final Unit other) {
239 return time.equals(other.time) && length.equals(other.length) &&
240 mass.equals(other.mass) && current.equals(other.current) &&
241 angle.equals(other.angle);
242 }
243
244 /** Create the SI unit with same dimension.
245 * @return a new unit, with same dimension as instance and scaling factor set to 1.0
246 */
247 public Unit sameDimensionSI() {
248 final StringBuilder builder = new StringBuilder();
249 append(builder, KILOGRAM.name, mass);
250 append(builder, METRE.name, length);
251 append(builder, SECOND.name, time);
252 append(builder, AMPERE.name, current);
253 append(builder, RADIAN.name, angle);
254 if (builder.length() == 0) {
255 builder.append('1');
256 }
257 return new Unit(builder.toString(), 1.0, mass, length, time, current, angle);
258 }
259
260 /** Ensure some units are compatible with reference units.
261 * @param description description of the units list (for error message generation)
262 * @param reference reference units
263 * @param units units to check
264 * @param allowScaleDifferences if true, unit with same dimension but different
265 * scale (like {@link #KILOMETRE} versus {@link #METRE}) are allowed, otherwise they will trigger an exception
266 * @exception OrekitException if units are not compatible (number of elements, dimensions or scaling)
267 */
268 public static void ensureCompatible(final String description, final List<Unit> reference,
269 final boolean allowScaleDifferences, final List<Unit> units) {
270 if (units.size() != reference.size()) {
271 throw new OrekitException(OrekitMessages.WRONG_NB_COMPONENTS,
272 description, reference.size(), units.size());
273 }
274 for (int i = 0; i < reference.size(); ++i) {
275 if (!reference.get(i).sameDimension(units.get(i))) {
276 throw new OrekitException(OrekitMessages.INCOMPATIBLE_UNITS,
277 reference.get(i).getName(),
278 units.get(i).getName());
279 }
280 if (!(allowScaleDifferences ||
281 Precision.equals(reference.get(i).getScale(), units.get(i).getScale(), 1))) {
282 throw new OrekitException(OrekitMessages.INCOMPATIBLE_UNITS,
283 reference.get(i).getName(),
284 units.get(i).getName());
285 }
286 }
287 }
288
289 /** Append a dimension contribution to a unit name.
290 * @param builder builder for unit name
291 * @param dim name of the dimension
292 * @param exp exponent of the dimension
293 */
294 private void append(final StringBuilder builder, final String dim, final Fraction exp) {
295 if (!exp.isZero()) {
296 if (builder.length() > 0) {
297 builder.append('.');
298 }
299 builder.append(dim);
300 if (exp.getDenominator() == 1) {
301 if (exp.getNumerator() != 1) {
302 builder.append(Integer.toString(exp.getNumerator()).
303 replace('-', '⁻').
304 replace('0', '⁰').
305 replace('1', '¹').
306 replace('2', '²').
307 replace('3', '³').
308 replace('4', '⁴').
309 replace('5', '⁵').
310 replace('6', '⁶').
311 replace('7', '⁷').
312 replace('8', '⁸').
313 replace('9', '⁹'));
314 }
315 } else {
316 builder.
317 append("^(").
318 append(exp.getNumerator()).
319 append('/').
320 append(exp.getDenominator()).
321 append(')');
322 }
323 }
324 }
325
326 /** Create an alias for a unit.
327 * @param newName name of the new unit
328 * @return a new unit representing same unit as the instance but with a different name
329 */
330 public Unit alias(final String newName) {
331 return new Unit(newName, scale, mass, length, time, current, angle);
332 }
333
334 /** Scale a unit.
335 * @param newName name of the new unit
336 * @param factor scaling factor
337 * @return a new unit representing scale times the instance
338 */
339 public Unit scale(final String newName, final double factor) {
340 return new Unit(newName, factor * scale, mass, length, time, current, angle);
341 }
342
343 /** Create power of unit.
344 * @param newName name of the new unit
345 * @param exponent exponent to apply
346 * @return a new unit representing the power of the instance
347 */
348 public Unit power(final String newName, final Fraction exponent) {
349
350 final int num = exponent.getNumerator();
351 final int den = exponent.getDenominator();
352 double s = (num == 1) ? scale : FastMath.pow(scale, num);
353 if (den > 1) {
354 if (den == 2) {
355 s = FastMath.sqrt(s);
356 } else if (den == 3) {
357 s = FastMath.cbrt(s);
358 } else {
359 s = FastMath.pow(s, 1.0 / den);
360 }
361 }
362
363 return new Unit(newName, s,
364 mass.multiply(exponent), length.multiply(exponent),
365 time.multiply(exponent), current.multiply(current),
366 angle.multiply(exponent));
367 }
368
369 /** Create root of unit.
370 * @param newName name of the new unit
371 * @return a new unit representing the square root of the instance
372 */
373 public Unit sqrt(final String newName) {
374 return new Unit(newName, FastMath.sqrt(scale),
375 mass.divide(2), length.divide(2),
376 time.divide(2), current.divide(2),
377 angle.divide(2));
378 }
379
380 /** Create product of units.
381 * @param newName name of the new unit
382 * @param other unit to multiply with
383 * @return a new unit representing the this times the other unit
384 */
385 public Unit multiply(final String newName, final Unit other) {
386 return new Unit(newName, scale * other.scale,
387 mass.add(other.mass), length.add(other.length),
388 time.add(other.time), current.add(other.current),
389 angle.add(other.angle));
390 }
391
392 /** Create quotient of units.
393 * @param newName name of the new unit
394 * @param other unit to divide with
395 * @return a new unit representing the this divided by the other unit
396 */
397 public Unit divide(final String newName, final Unit other) {
398 return new Unit(newName, scale / other.scale,
399 mass.subtract(other.mass), length.subtract(other.length),
400 time.subtract(other.time), current.subtract(other.current),
401 angle.subtract(other.angle));
402 }
403
404 /** Convert a value to SI units.
405 * @param value value instance unit
406 * @return value in SI units
407 */
408 public double toSI(final double value) {
409 return value * scale;
410 }
411
412 /** Convert a value to SI units.
413 * @param value value instance unit
414 * @return value in SI units
415 */
416 public double toSI(final Double value) {
417 return value == null ? Double.NaN : value.doubleValue() * scale;
418 }
419
420 /** Convert a value from SI units.
421 * @param value value SI unit
422 * @return value in instance units
423 */
424 public double fromSI(final double value) {
425 return value / scale;
426 }
427
428 /** Convert a value from SI units.
429 * @param value value SI unit
430 * @return value in instance units
431 */
432 public double fromSI(final Double value) {
433 return value == null ? Double.NaN : value.doubleValue() / scale;
434 }
435
436 /** Parse a unit.
437 * <p>
438 * The grammar for unit specification allows chains units multiplication and
439 * division, as well as putting powers on units.
440 * </p>
441 * <p>The symbols used for units are the SI units with some extensions.
442 * </p>
443 * <dl>
444 * <dt>year</dt>
445 * <dd>the accepted non-SI unit for Julian year is "a" but we also accept "yr"</dd>
446 * <dt>day</dt>
447 * <dd>the accepted non-SI unit for day is "d" but we also accept "day"</dd>
448 * <dt>dimensionless</dt>
449 * <dd>both "1" and "#" (U+0023, NUMBER SIGN) are accepted</dd>
450 * <dt>mass</dt>
451 * <dd>"g" is the standard symbol, despite the unit is "kg" (it is the only
452 * unit that has a prefix in its name, so all multiples must be based on "g")</dd>
453 * <dt>degrees</dt>
454 * <dd>the base symbol for degrees is "°" (U+00B0, DEGREE SIGN), but we also accept
455 * "◦" (U+25E6, WHITE BULLET) and "deg"</dd>
456 * <dt>arcminute</dt>
457 * <dd>The base symbol for arcminute is "′" (U+2032, PRIME) but we also accept "'" (U+0027, APOSTROPHE)</dd>
458 * <dt>arcsecond</dt>
459 * <dd>The base symbol for arcsecond is "″" (U+2033, DOUBLE PRIME) but we also accept
460 * "''" (two occurrences of U+0027, APOSTROPHE), "\"" (U+0022, QUOTATION MARK) and "as"</dd>
461 * </dl>
462 * <p>
463 * All the SI prefix (from "y", yocto, to "Y", Yotta) are accepted, as well
464 * as integer prefixes. The standard symbol for micro 10⁻⁶ is "µ" (U+00B5, MICRO SIGN),
465 * but we also accept "μ" (U+03BC, GREEK SMALL LETTER MU). Beware that some combinations
466 * are forbidden, for example "Pa" is Pascal, not peta-years, and "as" is arcsecond for
467 * this parser, not atto-seconds, because many people in the space field use mas for
468 * milliarcseconds and µas for microarcseconds. Beware that prefixes are case-sensitive!
469 * Integer prefixes can be used to specify units like "30s", but only once at the beginning
470 * of the specification (i.e. "2rev/d²" is accepted, but "rev/(2d)²" is refused). Conforming
471 * with SI brochure "The International System of Units" (9th edition, 2019), each SI
472 * prefix is part of the unit and precedes the unit symbol without a separator
473 * (i.e. MHz is seen as one identifier).
474 * </p>
475 * <dl>
476 * <dt>multiplication</dt>
477 * <dd>can specified with either "*" (U+002A, ASTERISK), "×" (U+00D7, MULTIPLICATION SIGN),
478 * "." (U+002E, FULL STOP) or "·" (U+00B7, MIDDLE DOT) as the operator</dd>
479 * <dt>division</dt>
480 * <dd>can be specified with either "/" (U+002F, SOLIDUS) or "⁄" (U+2044, FRACTION SLASH)
481 * as the operator</dd>
482 * <dt>powers</dt>
483 * <dd>can be specified either by
484 * <ul>
485 * <li>prefixing with the unicode "√" (U+221A, SQUARE ROOT) character</li>
486 * <li>postfixing with "**", "^" or implicitly using unicode superscripts</li>
487 * </ul>
488 * </dd>
489 * </dl>
490 * <p>
491 * Exponents can be specified in different ways:
492 * <ul>
493 * <li>as an integer, as in "m^-2" or "m⁻²"</li>
494 * <li>directly as unicode characters for the few fractions that unicode supports, as in "Ω^⅞"</li>
495 * <li>as the special decimal value 0.5 which is used by CCSDS, as in "km**0.5"</li>
496 * <li>as a pair of parentheses surrounding two integers separated by a solidus or fraction slash,
497 * as in "Pa^(11/12)"</li>
498 * </ul>
499 * For integer exponents, the digits must be ASCII digits from the Basic Latin block from
500 * unicode if explicit exponent marker "**" or "^" is used, or using unicode superscript
501 * digits if implicit exponentiation (i.e. no markers at all) is used. Unicode superscripts
502 * are not allowed for fractional exponents because unicode does not provide a superscript solidus.
503 * Negative exponents can be used too.
504 * <p>
505 * These rules mean all the following (silly) examples are parsed properly:
506 * MHz, km/√d, kg.m.s⁻¹, µas^⅖/(h**(2)×m)³, km/√(kg.s), km**0.5, 2rev/d²
507 * </p>
508 * @param unitSpecification unit specification to parse
509 * @return parsed unit
510 */
511 public static Unit parse(final String unitSpecification) {
512
513 // parse the specification
514 final List<PowerTerm> terms = Parser.buildTermsList(unitSpecification);
515
516 if (terms == null) {
517 // special handling of "n/a"
518 return Unit.NONE;
519 }
520
521 // build compound unit
522 Unit unit = Unit.ONE;
523 for (final PowerTerm term : terms) {
524 try {
525 Unit u = PrefixedUnit.valueOf(term.getBase().toString());
526 if (!Fraction.ONE.equals(term.getExponent())) {
527 u = u.power(null, term.getExponent());
528 }
529 u = u.scale(null, term.getScale());
530 unit = unit.multiply(null, u);
531 } catch (IllegalArgumentException iae) {
532 throw new OrekitException(OrekitMessages.UNKNOWN_UNIT, term.getBase());
533 }
534 }
535
536 // give final name to unit
537 return unit.alias(unitSpecification);
538
539 }
540
541 /** Check if the instance represents the same unit as another instance.
542 * <p>
543 * The name is not considered so aliases are considered equal.
544 * </p>
545 * @param unit other unit
546 * @return true if the instance and the other unit refer to the same unit
547 */
548 public boolean equals(final Object unit) {
549
550 if (unit == this) {
551 // first fast check
552 return true;
553 }
554
555 if (unit instanceof Unit) {
556 final Unit u = (Unit) unit;
557 return Precision.equals(scale, u.scale, 1) &&
558 mass.equals(u.mass) && length.equals(u.length) && time.equals(u.time) &&
559 current.equals(u.current) && angle.equals(u.angle);
560 }
561
562 return false;
563
564 }
565
566 /** Get a hashcode for this unit.
567 * @return hashcode
568 */
569 public int hashCode() {
570 return 0x67e7 ^
571 (Double.hashCode(scale) << 12) ^
572 (mass.hashCode() << 10) ^
573 (length.hashCode() << 8) ^
574 (time.hashCode() << 6) ^
575 (current.hashCode() << 4) ^
576 (angle.hashCode() << 2);
577 }
578
579 /** {@inheritDoc} */
580 @Override
581 public String toString() {
582 return getName();
583 }
584
585 }