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.atomic;
39  
40  import edu.rit.pj.ParallelTeam;
41  
42  /**
43   * This interface abstracts away the implementation of maintaining a 1D double array that is operated
44   * on by multiple threads.
45   *
46   * @author Michael J. Schnieders
47   * @since 1.0
48   */
49  public interface AtomicDoubleArray {
50  
51    /**
52     * Factory method to create an AtomicDoubleArray instance.
53     *
54     * @param atomicDoubleArrayImpl The implementation to use.
55     * @param threads The number of threads.
56     * @param size The size of the array.
57     * @return An AtomicDoubleArray instance.
58     */
59    static AtomicDoubleArray atomicDoubleArrayFactory(
60        AtomicDoubleArrayImpl atomicDoubleArrayImpl, int threads, int size) {
61      return switch (atomicDoubleArrayImpl) {
62        case ADDER -> new AdderDoubleArray(size);
63        case PJ -> new PJDoubleArray(size);
64        // MULTI is the default.
65        default -> new MultiDoubleArray(threads, size);
66      };
67    }
68  
69    /**
70     * Add value to the double array at the specified index.
71     *
72     * @param threadID the thread ID.
73     * @param index the index.
74     * @param value the value to add.
75     */
76    void add(int threadID, int index, double value);
77  
78    /**
79     * Ensure the AtomicDoubleArray instance is greater than or equal to size.
80     *
81     * @param size The size of the array.
82     */
83    void alloc(int size);
84  
85    /**
86     * Get the value of the array at the specified index. The <code>reduce</code> method should be
87     * called first when using the MULTI implementation.
88     *
89     * @param index the index.
90     * @return the value of the array at the specified index.
91     */
92    double get(int index);
93  
94    /**
95     * Perform reduction between the given lower bound (lb) and upper bound (up) if necessary.
96     *
97     * @param lb the lower bound.
98     * @param ub the upper bound.
99     */
100   void reduce(int lb, int ub);
101 
102   /**
103    * Perform reduction between the given lower bound (lb) and upper bound (up) using a ParallelTeam.
104    *
105    * @param parallelTeam ParallelTeam to use.
106    * @param lb the lower bound.
107    * @param ub the upper bound.
108    */
109   void reduce(ParallelTeam parallelTeam, int lb, int ub);
110 
111   /**
112    * Reset the double array to Zero.
113    *
114    * @param threadID the thread ID.
115    * @param lb the lower bound.
116    * @param ub the upper bound.
117    */
118   void reset(int threadID, int lb, int ub);
119 
120   /**
121    * Reset the double array to Zero using a ParallelTeam.
122    *
123    * @param parallelTeam ParallelTeam to use.
124    * @param lb the lower bound.
125    * @param ub the upper bound.
126    */
127   void reset(ParallelTeam parallelTeam, int lb, int ub);
128 
129   /**
130    * Scale the double array at the specified index by the given value.
131    *
132    * @param threadID the thread ID.
133    * @param index the index.
134    * @param value the value to scale by.
135    */
136   void scale(int threadID, int index, double value);
137 
138   /**
139    * Set the double array at the specified index to the given value.
140    *
141    * @param threadID the thread ID.
142    * @param index the index.
143    * @param value the value to set.
144    */
145   void set(int threadID, int index, double value);
146 
147   /**
148    * Get the size of the array.
149    *
150    * @return Returns the size of the array.
151    */
152   int size();
153 
154   /**
155    * Subtract value to the double array at the specified index.
156    *
157    * @param threadID the thread ID.
158    * @param index the index.
159    * @param value the value to subtract.
160    */
161   void sub(int threadID, int index, double value);
162 
163   /**
164    * AtomicDoubleArray implementations (ADDER, MULTI, PJ).
165    */
166   enum AtomicDoubleArrayImpl {
167     ADDER,
168     MULTI,
169     PJ
170   }
171 }