Class Unit

  • All Implemented Interfaces:
    Serializable

    public class Unit
    extends Object
    implements Serializable
    Basic handling of multiplicative units.

    This class is by no means a complete handling of units. For complete support, look at libraries like UOM. This class handles only time, length, mass and current dimensions, as well as angles (which are dimensionless).

    Instances of this class are immutable.

    Since:
    11.0
    Author:
    Luc Maisonobe
    See Also:
    UOM, Serialized Form
    • Field Detail

      • NONE

        public static final Unit NONE
        No unit.
      • ONE

        public static final Unit ONE
        Dimensionless unit.
      • CYCLE

        public static final Unit CYCLE
        Cycle unit.
        Since:
        13.0
      • PERCENT

        public static final Unit PERCENT
        Percentage unit.
      • SECOND

        public static final Unit SECOND
        Second unit.
      • MINUTE

        public static final Unit MINUTE
        Minute unit.
      • HOUR

        public static final Unit HOUR
        Hour unit.
      • DAY

        public static final Unit DAY
        Day unit.
      • HERTZ

        public static final Unit HERTZ
        Hertz unit.
      • METRE

        public static final Unit METRE
        Metre unit.
      • KILOMETRE

        public static final Unit KILOMETRE
        Kilometre unit.
      • KILOGRAM

        public static final Unit KILOGRAM
        Kilogram unit.
      • GRAM

        public static final Unit GRAM
        Gram unit.
      • AMPERE

        public static final Unit AMPERE
        Ampere unit.
      • RADIAN

        public static final Unit RADIAN
        Radian unit.
      • DEGREE

        public static final Unit DEGREE
        Degree unit.
      • ARC_MINUTE

        public static final Unit ARC_MINUTE
        Arc minute unit.
      • ARC_SECOND

        public static final Unit ARC_SECOND
        Arc second unit.
      • REVOLUTION

        public static final Unit REVOLUTION
        Revolution unit.
      • NEWTON

        public static final Unit NEWTON
        Newton unit.
      • PASCAL

        public static final Unit PASCAL
        Pascal unit.
      • BAR

        public static final Unit BAR
        Bar unit.
      • JOULE

        public static final Unit JOULE
        Joule unit.
      • WATT

        public static final Unit WATT
        Watt unit.
      • COULOMB

        public static final Unit COULOMB
        Coulomb unit.
      • VOLT

        public static final Unit VOLT
        Volt unit.
      • OHM

        public static final Unit OHM
        Ohm unit.
      • TESLA

        public static final Unit TESLA
        tesla unit.
      • SOLAR_FLUX_UNIT

        public static final Unit SOLAR_FLUX_UNIT
        Solar Flux Unit.
      • TOTAL_ELECTRON_CONTENT_UNIT

        public static final Unit TOTAL_ELECTRON_CONTENT_UNIT
        Total Electron Content Unit.
      • EARTH_RADII

        public static final Unit EARTH_RADII
        Earth Radii used as Bstar unit in CCSDS OMM.
    • Constructor Detail

      • Unit

        public Unit​(String name,
                    double scale,
                    Fraction mass,
                    Fraction length,
                    Fraction time,
                    Fraction current,
                    Fraction angle)
        Simple constructor.
        Parameters:
        name - name of the unit
        scale - scaling factor to SI units
        mass - mass exponent
        length - length exponent
        time - time exponent
        current - current exponent
        angle - angle exponent
    • Method Detail

      • getName

        public String getName()
        Get the name of the unit.
        Returns:
        name of the unit
      • getScale

        public double getScale()
        Get the scaling factor to SI units.
        Returns:
        scaling factor to SI units
      • getMass

        public Fraction getMass()
        Get the mass exponent.
        Returns:
        mass exponent
      • getLength

        public Fraction getLength()
        Get the length exponent.
        Returns:
        length exponent
      • getTime

        public Fraction getTime()
        Get the time exponent.
        Returns:
        time exponent
      • getCurrent

        public Fraction getCurrent()
        Get the current exponent.
        Returns:
        current exponent
      • getAngle

        public Fraction getAngle()
        Get the angle exponent.
        Returns:
        angle exponent
      • sameDimension

        public boolean sameDimension​(Unit other)
        Check if a unit has the same dimension as another unit.
        Parameters:
        other - other unit to check against
        Returns:
        true if unit has the same dimension as the other unit
      • sameDimensionSI

        public Unit sameDimensionSI()
        Create the SI unit with same dimension.
        Returns:
        a new unit, with same dimension as instance and scaling factor set to 1.0
      • ensureCompatible

        public static void ensureCompatible​(String description,
                                            List<Unit> reference,
                                            boolean allowScaleDifferences,
                                            List<Unit> units)
        Ensure some units are compatible with reference units.
        Parameters:
        description - description of the units list (for error message generation)
        reference - reference units
        units - units to check
        allowScaleDifferences - if true, unit with same dimension but different scale (like KILOMETRE versus METRE) are allowed, otherwise they will trigger an exception
        Throws:
        OrekitException - if units are not compatible (number of elements, dimensions or scaling)
      • alias

        public Unit alias​(String newName)
        Create an alias for a unit.
        Parameters:
        newName - name of the new unit
        Returns:
        a new unit representing same unit as the instance but with a different name
      • scale

        public Unit scale​(String newName,
                          double factor)
        Scale a unit.
        Parameters:
        newName - name of the new unit
        factor - scaling factor
        Returns:
        a new unit representing scale times the instance
      • power

        public Unit power​(String newName,
                          Fraction exponent)
        Create power of unit.
        Parameters:
        newName - name of the new unit
        exponent - exponent to apply
        Returns:
        a new unit representing the power of the instance
      • sqrt

        public Unit sqrt​(String newName)
        Create root of unit.
        Parameters:
        newName - name of the new unit
        Returns:
        a new unit representing the square root of the instance
      • multiply

        public Unit multiply​(String newName,
                             Unit other)
        Create product of units.
        Parameters:
        newName - name of the new unit
        other - unit to multiply with
        Returns:
        a new unit representing the this times the other unit
      • divide

        public Unit divide​(String newName,
                           Unit other)
        Create quotient of units.
        Parameters:
        newName - name of the new unit
        other - unit to divide with
        Returns:
        a new unit representing the this divided by the other unit
      • toSI

        public double toSI​(double value)
        Convert a value to SI units.
        Parameters:
        value - value instance unit
        Returns:
        value in SI units
      • toSI

        public double toSI​(Double value)
        Convert a value to SI units.
        Parameters:
        value - value instance unit
        Returns:
        value in SI units
      • toSI

        public <T extends CalculusFieldElement<T>> T toSI​(T value)
        Convert a value to SI units.
        Type Parameters:
        T - type of the field elements
        Parameters:
        value - value instance unit
        Returns:
        value in SI units
        Since:
        12.1
      • fromSI

        public double fromSI​(double value)
        Convert a value from SI units.
        Parameters:
        value - value SI unit
        Returns:
        value in instance units
      • fromSI

        public double fromSI​(Double value)
        Convert a value from SI units.
        Parameters:
        value - value SI unit
        Returns:
        value in instance units
      • fromSI

        public <T extends CalculusFieldElement<T>> T fromSI​(T value)
        Convert a value from SI units.
        Type Parameters:
        T - type of the field elements
        Parameters:
        value - value SI unit
        Returns:
        value in instance units
      • parse

        public static Unit parse​(String unitSpecification)
        Parse a unit.

        The grammar for unit specification allows chains units multiplication and division, as well as putting powers on units.

        The symbols used for units are the SI units with some extensions.

        year
        the accepted non-SI unit for Julian year is "a" but we also accept "yr"
        day
        the accepted non-SI unit for day is "d" but we also accept "day"
        dimensionless
        both "1" and "#" (U+0023, NUMBER SIGN) are accepted
        mass
        "g" is the standard symbol, despite the unit is "kg" (it is the only unit that has a prefix in its name, so all multiples must be based on "g")
        degrees
        the base symbol for degrees is "°" (U+00B0, DEGREE SIGN), but we also accept "◦" (U+25E6, WHITE BULLET) and "deg"
        arcminute
        The base symbol for arcminute is "′" (U+2032, PRIME) but we also accept "'" (U+0027, APOSTROPHE)
        arcsecond
        The base symbol for arcsecond is "″" (U+2033, DOUBLE PRIME) but we also accept "''" (two occurrences of U+0027, APOSTROPHE), "\"" (U+0022, QUOTATION MARK) and "as"

        All the SI prefix (from "y", yocto, to "Y", Yotta) are accepted, as well as integer prefixes. The standard symbol for micro 10⁻⁶ is "µ" (U+00B5, MICRO SIGN), but we also accept "μ" (U+03BC, GREEK SMALL LETTER MU). Beware that some combinations are forbidden, for example "Pa" is Pascal, not peta-years, and "as" is arcsecond for this parser, not atto-seconds, because many people in the space field use mas for milliarcseconds and µas for microarcseconds. Beware that prefixes are case-sensitive! Integer prefixes can be used to specify units like "30s", but only once at the beginning of the specification (i.e. "2rev/d²" is accepted, but "rev/(2d)²" is refused). Conforming with SI brochure "The International System of Units" (9th edition, 2019), each SI prefix is part of the unit and precedes the unit symbol without a separator (i.e. MHz is seen as one identifier).

        multiplication
        can specified with either "*" (U+002A, ASTERISK), "×" (U+00D7, MULTIPLICATION SIGN), "." (U+002E, FULL STOP) or "·" (U+00B7, MIDDLE DOT) as the operator
        division
        can be specified with either "/" (U+002F, SOLIDUS) or "⁄" (U+2044, FRACTION SLASH) as the operator
        powers
        can be specified either by
        • prefixing with the unicode "√" (U+221A, SQUARE ROOT) character
        • postfixing with "**", "^" or implicitly using unicode superscripts

        Exponents can be specified in different ways:

        • as an integer, as in "m^-2" or "m⁻²"
        • directly as unicode characters for the few fractions that unicode supports, as in "Ω^⅞"
        • as the special decimal value 0.5 which is used by CCSDS, as in "km**0.5"
        • as a pair of parentheses surrounding two integers separated by a solidus or fraction slash, as in "Pa^(11/12)"
        For integer exponents, the digits must be ASCII digits from the Basic Latin block from unicode if explicit exponent marker "**" or "^" is used, or using unicode superscript digits if implicit exponentiation (i.e. no markers at all) is used. Unicode superscripts are not allowed for fractional exponents because unicode does not provide a superscript solidus. Negative exponents can be used too.

        These rules mean all the following (silly) examples are parsed properly: MHz, km/√d, kg.m.s⁻¹, µas^⅖/(h**(2)×m)³, km/√(kg.s), km**0.5, 2rev/d²

        Parameters:
        unitSpecification - unit specification to parse
        Returns:
        parsed unit
      • equals

        public boolean equals​(Object unit)
        Check if the instance represents the same unit as another instance.

        The name is not considered so aliases are considered equal.

        Overrides:
        equals in class Object
        Parameters:
        unit - other unit
        Returns:
        true if the instance and the other unit refer to the same unit
      • hashCode

        public int hashCode()
        Get a hashcode for this unit.
        Overrides:
        hashCode in class Object
        Returns:
        hashcode