Unit.java

  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;

  19. import java.io.Serializable;
  20. import java.util.List;

  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;

  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 {

  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);

  47.     /** Dimensionless unit. */
  48.     public static final Unit ONE = new Unit("1", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);

  50.     /** Percentage unit. */
  51.     public static final Unit PERCENT = new Unit("%", 1.0e-2, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);

  53.     /** Second unit. */
  54.     public static final Unit SECOND = new Unit("s", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ONE, Fraction.ZERO, Fraction.ZERO);

  56.     /** Minute unit. */
  57.     public static final Unit MINUTE = SECOND.scale("min", 60.0);

  59.     /** Hour unit. */
  60.     public static final Unit HOUR = MINUTE.scale("h", 60);

  62.     /** Day unit. */
  63.     public static final Unit DAY = HOUR.scale("d", 24.0);

  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);

  70.     /** Hertz unit. */
  71.     public static final Unit HERTZ = SECOND.power("Hz", Fraction.MINUS_ONE);

  73.     /** Metre unit. */
  74.     public static final Unit METRE = new Unit("m", 1.0, Fraction.ZERO, Fraction.ONE, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);

  76.     /** Kilometre unit. */
  77.     public static final Unit KILOMETRE = METRE.scale("km", 1000.0);

  79.     /** Kilogram unit. */
  80.     public static final Unit KILOGRAM = new Unit("kg", 1.0, Fraction.ONE, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO);

  82.     /** Gram unit. */
  83.     public static final Unit GRAM = KILOGRAM.scale("g", 1.0e-3);

  85.     /** Ampere unit. */
  86.     public static final Unit AMPERE = new Unit("A", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ONE, Fraction.ZERO);

  88.     /** Radian unit. */
  89.     public static final Unit RADIAN = new Unit("rad", 1.0, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ZERO, Fraction.ONE);

  91.     /** Degree unit. */
  92.     public static final Unit DEGREE = RADIAN.scale("°", FastMath.toRadians(1.0));

  94.     /** Arc minute unit. */
  95.     public static final Unit ARC_MINUTE = DEGREE.scale("′", 1.0 / 60.0);

  97.     /** Arc second unit. */
  98.     public static final Unit ARC_SECOND = ARC_MINUTE.scale("″", 1.0 / 60.0);

  100.     /** Revolution unit. */
  101.     public static final Unit REVOLUTION = RADIAN.scale("rev", 2.0 * FastMath.PI);

  103.     /** Newton unit. */
  104.     public static final Unit NEWTON = KILOGRAM.multiply(null, METRE).divide("N", SECOND.power(null, Fraction.TWO));

  106.     /** Pascal unit. */
  107.     public static final Unit PASCAL = NEWTON.divide("Pa", METRE.power(null, Fraction.TWO));

  109.     /** Bar unit. */
  110.     public static final Unit BAR = PASCAL.scale("bar", 100000.0);

  112.     /** Joule unit. */
  113.     public static final Unit JOULE = NEWTON.multiply("J", METRE);

  115.     /** Watt unit. */
  116.     public static final Unit WATT = JOULE.divide("W", SECOND);

  118.     /** Coulomb unit. */
  119.     public static final Unit COULOMB = SECOND.multiply("C", AMPERE);

  121.     /** Volt unit. */
  122.     public static final Unit VOLT = WATT.divide("V", AMPERE);

  124.     /** Ohm unit. */
  125.     public static final Unit OHM = VOLT.divide("Ω", AMPERE);

  127.     /** tesla unit. */
  128.     public static final Unit TESLA = VOLT.multiply(null, SECOND).divide("T", METRE.power(null, Fraction.TWO));

  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);

  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);

  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);

  139.     /** Serializable UID. */
  140.     private static final long serialVersionUID = 20210402L;

  142.     /** Name name of the unit. */
  143.     private final String name;

  145.     /** Scaling factor to SI units. */
  146.     private final double scale;

  148.     /** Mass exponent. */
  149.     private final Fraction mass;

  151.     /** Length exponent. */
  152.     private final Fraction length;

  154.     /** Time exponent. */
  155.     private final Fraction time;

  157.     /** Current exponent. */
  158.     private final Fraction current;

  160.     /** Angle exponent. */
  161.     private final Fraction angle;

  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.     }

  185.     /** Get the name of the unit.
  186.      * @return name of the unit
  187.      */
  188.     public String getName() {
  189.         return name;
  190.     }

  192.     /** Get the scaling factor to SI units.
  193.      * @return scaling factor to SI units
  194.      */
  195.     public double getScale() {
  196.         return scale;
  197.     }

  199.     /** Get the mass exponent.
  200.      * @return mass exponent
  201.      */
  202.     public Fraction getMass() {
  203.         return mass;
  204.     }

  206.     /** Get the length exponent.
  207.      * @return length exponent
  208.      */
  209.     public Fraction getLength() {
  210.         return length;
  211.     }

  213.     /** Get the time exponent.
  214.      * @return time exponent
  215.      */
  216.     public Fraction getTime() {
  217.         return time;
  218.     }

  220.     /** Get the current exponent.
  221.      * @return current exponent
  222.      */
  223.     public Fraction getCurrent() {
  224.         return current;
  225.     }

  227.     /** Get the angle exponent.
  228.      * @return angle exponent
  229.      */
  230.     public Fraction getAngle() {
  231.         return angle;
  232.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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) {

  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.         }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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) {

  513.         // parse the specification
  514.         final List<PowerTerm> terms = Parser.buildTermsList(unitSpecification);

  516.         if (terms == null) {
  517.             // special handling of "n/a"
  518.             return Unit.NONE;
  519.         }

  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.         }

  536.         // give final name to unit
  537.         return unit.alias(unitSpecification);

  539.     }

  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) {

  550.         if (unit == this) {
  551.             // first fast check
  552.             return true;
  553.         }

  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.         }

  562.         return false;

  564.     }

  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.     }

  579.     /** {@inheritDoc} */
  580.     @Override
  581.     public String toString() {
  582.         return getName();
  583.     }

  585. }
Created with JaCoCo 0.8.11.202310140853