001/*
002 * Units of Measurement Implementation for Java SE
003 * Copyright (c) 2005-2017, Jean-Marie Dautelle, Werner Keil, V2COM.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-363 nor the names of its contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package tec.uom.se.spi;
031
032import tec.uom.se.AbstractConverter;
033import tec.uom.se.quantity.QuantityDimension;
034import javax.measure.Dimension;
035import java.util.Map;
036
037/**
038 * <p>
039 * This class represents the physical model used for dimensional analysis.
040 * </p>
041 *
042 * <p>
043 * In principle, dimensions of physical quantities could be defined as "fundamental" (such as momentum or energy or electric current) making such
044 * quantities uncommensurate (not comparable). Modern physics has cast doubt on the very existence of incompatible fundamental dimensions of physical
045 * quantities. For example, most physicists do not recognize temperature, {@link QuantityDimension#TEMPERATURE Θ}, as a fundamental dimension since it
046 * essentially expresses the energy per particle per degree of freedom, which can be expressed in terms of energy (or mass, length, and time). To
047 * support, such model the method {@link #getConverter} may returns a non-null value for distinct dimensions.
048 * </p>
049 * 
050 * <p>
051 * The default model is {@link StandardModel Standard}. Applications may use one of the predefined model or create their own. <code>
052 *     DimensionalModel relativistic = new DimensionalModel() {
053 *         public Dimension getFundamentalDimension(Dimension dimension) {
054 *             if (dimension.equals(QuantityDimension.LENGTH)) return QuantityDimension.TIME; // Consider length derived from time.
055 *                 return super.getDimension(dimension); // Returns product of fundamental dimension.
056 *             }
057 *             public UnitConverter getDimensionalTransform(Dimension dimension) {
058 *                 if (dimension.equals(QuantityDimension.LENGTH)) return new RationalConverter(1, 299792458); // Converter (1/C) from LENGTH SI unit (m) to TIME SI unit (s).
059 *                 return super.getDimensionalTransform(dimension);
060 *             }
061 *     };
062 *     try {
063 *         DimensionalModel.setCurrent(relativistic); // Current thread use the relativistic model.
064 *         Units.KILOGRAM.getConverterToAny(Units.JOULE); // Allowed.
065 *         ...
066 *     } finally {
067 *        cleanup();
068 *     }
069 *     </code>
070 * </p>
071 * 
072 * @see <a href="http://en.wikipedia.org/wiki/Dimensional_analysis">Wikipedia: Dimensional Analysis</a>
073 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
074 * @author <a href="mailto:units@catmedia.us">Werner Keil</a>
075 * @version 0.5.5, $Date: 2015-07-25 $
076 */
077public abstract class DimensionalModel {
078
079  /**
080   * Holds the current model.
081   */
082  private static DimensionalModel currentModel = new StandardModel();
083
084  /**
085   * Returns the current model (by default an instance of {@link StandardModel}).
086   *
087   * @return the current dimensional model.
088   */
089  public static DimensionalModel current() {
090    return currentModel;
091  }
092
093  /**
094   * Sets the current dimensional model
095   *
096   * @param model
097   *          the new current model.
098   * @see #current
099   */
100  protected static void setCurrent(DimensionalModel model) {
101    currentModel = model;
102  }
103
104  /**
105   * DefaultQuantityFactory constructor (allows for derivation).
106   */
107  protected DimensionalModel() {
108  }
109
110  /**
111   * Returns the fundamental dimension for the one specified. If the specified dimension is a dimensional product, the dimensional product of its
112   * fundamental dimensions is returned. Physical quantities are considered commensurate only if their fundamental dimensions are equals using the
113   * current physics model.
114   *
115   * @param dimension
116   *          the dimension for which the fundamental dimension is returned.
117   * @return <code>this</code> or a rational product of fundamental dimension.
118   */
119  public Dimension getFundamentalDimension(Dimension dimension) {
120    Map<? extends Dimension, Integer> dimensions = dimension.getBaseDimensions();
121    if (dimensions == null)
122      return dimension; // Fundamental dimension.
123    // Dimensional Product.
124    Dimension fundamentalProduct = QuantityDimension.NONE;
125    for (Map.Entry<? extends Dimension, Integer> e : dimensions.entrySet()) {
126      fundamentalProduct = fundamentalProduct.multiply(this.getFundamentalDimension(e.getKey())).pow(e.getValue());
127    }
128    return fundamentalProduct;
129  }
130
131  /**
132   * Returns the dimensional transform of the specified dimension. If the specified dimension is a fundamental dimension or a product of fundamental
133   * dimensions the identity converter is returned; otherwise the converter from the system unit (SI) of the specified dimension to the system unit
134   * (SI) of its fundamental dimension is returned.
135   *
136   * @param dimension
137   *          the dimension for which the dimensional transform is returned.
138   * @return the dimensional transform (identity for fundamental dimensions).
139   */
140  public AbstractConverter getDimensionalTransform(Dimension dimension) {
141    Map<? extends Dimension, Integer> dimensions = dimension.getBaseDimensions();
142    if (dimensions == null)
143      return AbstractConverter.IDENTITY; // Fundamental dimension.
144    // Dimensional Product.
145    AbstractConverter toFundamental = AbstractConverter.IDENTITY;
146    for (Map.Entry<? extends Dimension, Integer> e : dimensions.entrySet()) {
147      AbstractConverter cvtr = this.getDimensionalTransform(e.getKey());
148      if (!(cvtr.isLinear()))
149        throw new UnsupportedOperationException("Non-linear dimensional transform");
150      int pow = e.getValue();
151      if (pow < 0) { // Negative power.
152        pow = -pow;
153        cvtr = cvtr.inverse();
154      }
155      for (int j = 0; j < pow; j++) {
156        toFundamental = toFundamental.concatenate(cvtr);
157      }
158    }
159    return toFundamental;
160  }
161}