KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jscience > physics > measures > MeasureVector


1 /*
2  * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
3  * Copyright (C) 2006 - JScience (http://jscience.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package org.jscience.physics.measures;
10
11 import javax.measure.converters.ConversionException;
12 import javax.measure.quantities.Quantity;
13 import javax.measure.units.Unit;
14 import javax.realtime.MemoryArea;
15
16 import javolution.context.PoolContext;
17 import org.jscience.mathematics.structures.VectorSpaceNormed;
18 import org.jscience.mathematics.vectors.DimensionException;
19 import org.jscience.mathematics.vectors.Vector;
20
21 /**
22  * <p> This class represents a measurement vector for which all components
23  * are of the same type.</p>
24  *
25  * <p> Measure vectors are typically 2 or 3 dimensional. For example:[code]
26  * class Velocity2D extends MeasureVector<Velocity> { ... }
27  * MeasureVector<Length> xyz = MeasureVector.valueOf(METER, 2.0, -4.0, 3.0);
28  * [/code]</p>
29  *
30  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
31  * @version 3.1, April 2, 2006
32  */
33 public class MeasureVector<Q extends Quantity> extends Vector<Measure<?>>
34         implements VectorSpaceNormed<Vector<Measure<?>>, Measure<?>> {
35
36     /**
37      * Holds the vector's elements.
38      */
39     Measure<Q>[] _elements;
40
41     /**
42      * Holds the vector's dimension.
43      */
44     int _dimension;
45
46     /**
47      * Creates a measurement vector holding the specified elements.
48      *
49      * @param elements the vector elements.
50      */
51     @SuppressWarnings JavaDoc("unchecked")
52     public MeasureVector(Measure<Q> ... elements) {
53         _dimension = elements.length;
54         _elements = new Measure[_dimension];
55         for (int i = 0; i < _dimension; i++) {
56             _elements[i] = elements[i];
57         }
58     }
59
60     /**
61      * Returns a new measurement vector (potentially {@link #recycle recycled})
62      * holding the specified elements.
63      *
64      * @param elements the vector elements.
65      * @return the vector having the specified elements.
66      * @throws DimensionException if the rows do not have the same length.
67      * @see javolution.context.ObjectFactory#object()
68      */
69     public static <Q extends Quantity> MeasureVector<Q> valueOf(Measure<Q> ... elements) {
70         int n = elements.length;
71         MeasureVector<Q> V = MeasureVector.newInstance(n);
72         for (int i = 0; i < n; i++) {
73             V._elements[i] = elements[i];
74         }
75         return V;
76     }
77
78     /**
79      * Returns a {@link MeasureVector} stated in the specified unit equivalent
80      * to the specified vector
81      *
82      * @param unit the unit in which the measurements are stated.
83      * @param that the vector to convert.
84      * @return <code>that</code> or new equivalent dense vector.
85      */
86     public static <Q extends Quantity> MeasureVector<Q> valueOf(Unit<Q> unit, Vector<Measure<?>> that) {
87         int n = that.getDimension();
88         MeasureVector<Q> V = MeasureVector.newInstance(n);
89         for (int i = 0; i < n; i++) {
90             V._elements[i] = that.get(i).to(unit);
91         }
92         return V;
93     }
94     
95     /**
96      * Returns the exact measurement vector holding the specified values stated
97      * in the specified unit.
98      *
99      * @param unit the unit in which the measurements are stated.
100      * @param values the exact values stated in the specified unit.
101      * @return the corresponding measurement vector.
102      */
103     public static <Q extends Quantity> MeasureVector<Q> valueOf(Unit<Q> unit,
104             long... values) {
105         final int d = values.length;
106         MeasureVector<Q> V = MeasureVector.newInstance(d);
107         for (int i = 0; i < d; i++) {
108             V._elements[i] = Measure.valueOf(values[i], unit);
109         }
110         return V;
111     }
112
113     /**
114      * Returns the approximate measurement vector holding the specified values
115      * stated in the specified unit.
116      *
117      * @param unit the unit in which the measurements are stated.
118      * @param values the approximate values stated in the specified unit.
119      * @return the corresponding measurement vector.
120      */
121     public static <Q extends Quantity> MeasureVector<Q> valueOf(Unit<Q> unit,
122             double... values) {
123         final int d = values.length;
124         MeasureVector<Q> V = MeasureVector.newInstance(d);
125         for (int i = 0; i < d; i++) {
126             V._elements[i] = Measure.valueOf(values[i], unit);
127         }
128         return V;
129     }
130
131     /**
132      * Recycles the specified vector immediately.
133      *
134      * @param vector the vector being recycled.
135      * @see javolution.context.ObjectFactory#recycle(Object)
136      */
137     public static void recycle(MeasureVector vector) {
138         FACTORY.recycle(vector);
139     }
140
141     /**
142      * Returns the Euclidian norm of this vector (square root of the
143      * dot product of this vector and itself).
144      *
145      * @return <code>sqrt(this ยท this)</code>.
146      */
147     @SuppressWarnings JavaDoc("unchecked")
148     public Measure<Q> norm() {
149         Measure<?> normSquared = _elements[0].times(_elements[0]);
150         for (int i = 1; i < _dimension; i++) {
151             normSquared = normSquared.plus(_elements[i].times(_elements[i]));
152         }
153         return (Measure<Q>) normSquared.sqrt();
154     }
155
156     /**
157      * Returns the measurement vector equivalent to this vector but stated
158      * in the specified unit.
159      *
160      * @param unit the unit of the measurements to be returned.
161      * @return a measurement vector equivalent to this vector but whose
162      * elements are stated in the specified unit.
163      * @throws ConversionException if the current model does not allows for
164      * conversion to the specified unit.
165      */
166     @SuppressWarnings JavaDoc("unchecked")
167     public <R extends Quantity> MeasureVector<R> to(Unit<R> unit) {
168         MeasureVector<R> V = MeasureVector.newInstance(_dimension);
169         for (int i = 0; i < _dimension; i++) {
170             V._elements[i] = _elements[i].to(unit);
171         }
172         return V;
173     }
174
175     @Override JavaDoc
176     public final int getDimension() {
177         return _dimension;
178     }
179
180     @Override JavaDoc
181     public final Measure<Q> get(int i) {
182         if (i >= _dimension)
183             throw new IndexOutOfBoundsException JavaDoc();
184         return _elements[i];
185     }
186
187     @Override JavaDoc
188     public MeasureVector<Q> opposite() {
189         MeasureVector<Q> V = MeasureVector.newInstance(_dimension);
190         for (int i = 0; i < _dimension; i++) {
191             V._elements[i] = _elements[i].opposite();
192         }
193         return V;
194     }
195
196     @Override JavaDoc
197     public MeasureVector<Q> plus(Vector<Measure<?>> that) {
198         MeasureVector<Q> T = MeasureVector.valueOf(_elements[0].getUnit(), that);
199         if (T._dimension != _dimension) throw new DimensionException();
200         MeasureVector<Q> V = MeasureVector.newInstance(_dimension);
201         for (int i = 0; i < _dimension; i++) {
202             V._elements[i] = _elements[i].plus(T._elements[i]);
203         }
204         return V;
205     }
206
207     @SuppressWarnings JavaDoc("unchecked")
208     @Override JavaDoc
209     public MeasureVector<? extends Quantity> times(Measure k) {
210         MeasureVector V = MeasureVector.newInstance(_dimension);
211         for (int i = 0; i < _dimension; i++) {
212             V._elements[i] = _elements[i].times(k);
213         }
214         return V;
215     }
216
217     @Override JavaDoc
218     public Measure<?> times(Vector<Measure<?>> that) {
219         MeasureVector<? extends Quantity> T = MeasureVector.valueOf(that.get(0).getUnit(), that);
220         if (T._dimension != _dimension) throw new DimensionException();
221         PoolContext.enter();
222         try {
223            Measure<?> sum = (Measure<?>) _elements[0].times(T._elements[0]);
224            for (int i = 1; i < _dimension; i++) {
225                sum = sum.plus(_elements[i].times(T._elements[i]));
226            }
227            sum.move(ObjectSpace.OUTER);
228            return sum;
229        } finally {
230            PoolContext.exit();
231        }
232     }
233     
234     ///////////////////////
235 // Factory creation. //
236 ///////////////////////
237
238     @SuppressWarnings JavaDoc("unchecked")
239     static <Q extends Quantity> MeasureVector<Q> newInstance(final int dimension) {
240         final MeasureVector<Q> V = FACTORY.object();
241         V._dimension = dimension;
242         if ((V._elements == null) || (V._elements.length < dimension)) {
243             MemoryArea.getMemoryArea(V).executeInArea(new Runnable JavaDoc() {
244                 public void run() {
245                     V._elements = new Measure[dimension];
246                 }
247             });
248         }
249         return V;
250     }
251
252     private static Factory<MeasureVector> FACTORY = new Factory<MeasureVector>() {
253         protected MeasureVector create() {
254             return new MeasureVector();
255         }
256     };
257
258     private MeasureVector() {
259     }
260
261     private static final long serialVersionUID = 1L;
262 }
Popular Tags