View Javadoc
1   // ******************************************************************************
2   //
3   // Title:       Force Field X.
4   // Description: Force Field X - Software for Molecular Biophysics.
5   // Copyright:   Copyright (c) Michael J. Schnieders 2001-2024.
6   //
7   // This file is part of Force Field X.
8   //
9   // Force Field X is free software; you can redistribute it and/or modify it
10  // under the terms of the GNU General Public License version 3 as published by
11  // the Free Software Foundation.
12  //
13  // Force Field X is distributed in the hope that it will be useful, but WITHOUT
14  // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  // FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
16  // details.
17  //
18  // You should have received a copy of the GNU General Public License along with
19  // Force Field X; if not, write to the Free Software Foundation, Inc., 59 Temple
20  // Place, Suite 330, Boston, MA 02111-1307 USA
21  //
22  // Linking this library statically or dynamically with other modules is making a
23  // combined work based on this library. Thus, the terms and conditions of the
24  // GNU General Public License cover the whole combination.
25  //
26  // As a special exception, the copyright holders of this library give you
27  // permission to link this library with independent modules to produce an
28  // executable, regardless of the license terms of these independent modules, and
29  // to copy and distribute the resulting executable under terms of your choice,
30  // provided that you also meet, for each linked independent module, the terms
31  // and conditions of the license of that module. An independent module is a
32  // module which is not derived from or based on this library. If you modify this
33  // library, you may extend this exception to your version of the library, but
34  // you are not obligated to do so. If you do not wish to do so, delete this
35  // exception statement from your version.
36  //
37  // ******************************************************************************
38  package ffx.numerics.math;
39  
40  import static java.lang.System.arraycopy;
41  
42  /**
43   * Convenience class for working with 3D float vectors.
44   *
45   * @author Michael J. Schnieders
46   * @since 1.0
47   */
48  public class Float3 {
49  
50    /** Internal storage for the vector. */
51    private final float[] a;
52  
53    /** Construct a Float3 at (0.0, 0.0, 0.0). */
54    public Float3() {
55      a = new float[] {0.0f, 0.0f, 0.0f};
56    }
57  
58    /**
59     * Construct a Float3 at (x, y, z).
60     *
61     * @param x X value.
62     * @param y Y value.
63     * @param z Z value.
64     */
65    public Float3(float x, float y, float z) {
66      a = new float[] {x, y, z};
67    }
68  
69    /**
70     * Construct a Float3 at a.
71     *
72     * @param a Float3 to initialize from (the data is copied).
73     */
74    public Float3(float[] a) {
75      this.a = new float[] {a[0], a[1], a[2]};
76    }
77  
78    /**
79     * Compute a * b + c and return the result in a new Float3.
80     *
81     * @param b Scalar.
82     * @param c Float3.
83     * @return Returns the FMA of a * b + c in a new Float3.
84     */
85    public Float3 fma(float b, Float3 c) {
86      Float3 ret = new Float3();
87      FloatMath.fma(a, b, c.get(), ret.get());
88      return ret;
89    }
90  
91    /**
92     * Compute a * b + c and return the result in a new Float3.
93     *
94     * @param b Scalar.
95     * @param c Float3.
96     * @return Returns the FMA of a * b + c in a new Float3.
97     */
98    public Float3 fmaI(float b, Float3 c) {
99      FloatMath.fma(a, b, c.get(), a);
100     return this;
101   }
102 
103   /**
104    * Cross product of this Float3 with b.
105    *
106    * @param b Vector b.
107    * @return Returns the cross product in a new Float3.
108    */
109   public Float3 X(Float3 b) {
110     Float3 ret = new Float3();
111     FloatMath.X(a, b.get(), ret.get());
112     return ret;
113   }
114 
115   /**
116    * In-place Cross product of this Float3 with b.
117    *
118    * @param b Vector b.
119    * @return Returns the cross product in this Float3.
120    */
121   public Float3 XI(Float3 b) {
122     return set(X(b));
123   }
124 
125   /**
126    * Finds the sum of this Float3 with b.
127    *
128    * @param b Second Float3.
129    * @return Returns the sum in a new Float3.
130    */
131   public Float3 add(Float3 b) {
132     Float3 ret = new Float3();
133     FloatMath.add(a, b.get(), ret.get());
134     return ret;
135   }
136 
137   /**
138    * Finds the sum of this Float3 with b in place.
139    *
140    * @param b Second Float3.
141    * @return Returns the sum in this Float3.
142    */
143   public Float3 addI(Float3 b) {
144     FloatMath.add(a, b.get(), a);
145     return this;
146   }
147 
148   /**
149    * Angle of this Float3 with b.
150    *
151    * @param b Vector b.
152    * @return Returns the angle.
153    */
154   public float angle(Float3 b) {
155     return FloatMath.angle(a, b.get());
156   }
157 
158   /**
159    * Returns a new copy of this Float3.
160    *
161    * @return Returns a copy of this Float3.
162    */
163   public Float3 copy() {
164     return new Float3(a);
165   }
166 
167   /**
168    * Finds the distance between two vectors.
169    *
170    * @param b Second vector.
171    * @return Returns the distance between this Float3 and b.
172    */
173   public float dist(Float3 b) {
174     return FloatMath.dist(a, b.get());
175   }
176 
177   /**
178    * Finds the squared distance between two vectors
179    *
180    * @param b Second vector.
181    * @return Returns the squared distance between this Float3 and b.
182    */
183   public float dist2(Float3 b) {
184     return FloatMath.dist2(a, b.get());
185   }
186 
187   /**
188    * Finds the dot product between two vectors.
189    *
190    * @param b Second vector.
191    * @return Returns the dot product of this Float3 and b.
192    */
193   public float dot(Float3 b) {
194     return FloatMath.dot(a, b.get());
195   }
196 
197   /**
198    * Returns a reference to the internal float array that stores this Float3.
199    *
200    * @return A reference to the internal float array.
201    */
202   public float[] get() {
203     return a;
204   }
205 
206   /**
207    * Returns the coordinate at position i.
208    *
209    * @return The coordinate.
210    */
211   public float get(int i) {
212     return a[i];
213   }
214 
215   /**
216    * Finds the length of this Float3.
217    *
218    * @return Length of vector this Float3.
219    */
220   public float length() {
221     return FloatMath.length(a);
222   }
223 
224   /**
225    * Finds the length of this Float3 squared.
226    *
227    * @return Length of vector this Float3 squared.
228    */
229   public float length2() {
230     return FloatMath.length2(a);
231   }
232 
233   /** Log this Float3. */
234   public void log() {
235     FloatMath.log(a);
236   }
237 
238   /**
239    * Normalize this Float3.
240    *
241    * @return Returns the normalized vector in a new Float3.
242    */
243   public Float3 normalize() {
244     Float3 ret = new Float3();
245     FloatMath.normalize(a, ret.get());
246     return ret;
247   }
248 
249   /**
250    * Normalize this Float3 in place.
251    *
252    * @return Returns a reference to this Float3 normalized.
253    */
254   public Float3 normalizeI() {
255     FloatMath.normalize(a, a);
256     return this;
257   }
258 
259   /**
260    * Scales a Float3.
261    *
262    * @param d A scalar value.
263    * @return Returns a new scaled Float3.
264    */
265   public Float3 scale(float d) {
266     Float3 ret = new Float3();
267     FloatMath.scale(a, d, ret.get());
268     return ret;
269   }
270 
271   /**
272    * Scales a Float3 in place.
273    *
274    * @param d A scalar value.
275    * @return Returns a reference to this Float3 scaled.
276    */
277   public Float3 scaleI(float d) {
278     FloatMath.scale(a, d, a);
279     return this;
280   }
281 
282   /**
283    * Squares values in Float3.
284    *
285    * @return Returns a reference to this Float3 squared.
286    */
287   public Float3 square() {
288     Float3 ret = new Float3();
289     FloatMath.square(a, ret.get());
290     return ret;
291   }
292 
293   /**
294    * Squares values in Float3 in place.
295    *
296    * @return Returns a reference to this Float3 squared.
297    */
298   public Float3 squareI() {
299     FloatMath.square(a, a);
300     return this;
301   }
302 
303   /**
304    * Square roots values in Float3.
305    *
306    * @return Returns a reference to this Float3 square rooted.
307    */
308   public Float3 sqrt() {
309     Float3 ret = new Float3();
310     FloatMath.squareRoot(a, ret.get());
311     return ret;
312   }
313 
314   /**
315    * Square roots values in Float3 in place.
316    *
317    * @return Returns a reference to this Float3 square rooted.
318    */
319   public Float3 sqrtI() {
320     FloatMath.squareRoot(a, a);
321     return this;
322   }
323 
324   /**
325    * Set the value of this Float3.
326    *
327    * @param x X-value.
328    * @param y Y-value.
329    * @param z Z-value.
330    * @return A reference to this Float3.
331    */
332   public Float3 set(float x, float y, float z) {
333     a[0] = x;
334     a[1] = y;
335     a[2] = z;
336     return this;
337   }
338 
339   /**
340    * Set the value of this Float3.
341    *
342    * @param b Double array that is copied.
343    * @return A reference to this Float3.
344    */
345   public Float3 set(float[] b) {
346     arraycopy(b, 0, a, 0, 3);
347     return this;
348   }
349 
350   /**
351    * Set the value of this Float3.
352    *
353    * @param b Float3 that is copied.
354    * @return A reference to this Float3.
355    */
356   public Float3 set(Float3 b) {
357     arraycopy(b.get(), 0, a, 0, 3);
358     return this;
359   }
360 
361   /**
362    * Finds the difference between two vectors.
363    *
364    * @param b Second vector
365    * @return Returns the difference in a new Float3.
366    */
367   public Float3 sub(Float3 b) {
368     Float3 ret = new Float3();
369     FloatMath.sub(a, b.get(), ret.get());
370     return ret;
371   }
372 
373   /**
374    * Finds the difference between two vectors.
375    *
376    * @param b Second vector
377    * @return Returns the difference in this Float3.
378    */
379   public Float3 subI(Float3 b) {
380     FloatMath.sub(a, b.get(), a);
381     return this;
382   }
383 
384   /**
385    * Describe this Float3 in a String.
386    *
387    * @return Returns a String description.
388    */
389   @Override
390   public String toString() {
391     return FloatMath.toString(a);
392   }
393 
394   /**
395    * Get the value x.
396    *
397    * @return Returns x.
398    */
399   public float x() {
400     return a[0];
401   }
402 
403   /**
404    * Get the value of y.
405    *
406    * @return Returns y.
407    */
408   public float y() {
409     return a[1];
410   }
411 
412   /**
413    * Get the value of z.
414    *
415    * @return Returns z.
416    */
417   public float z() {
418     return a[2];
419   }
420 }