1 // ******************************************************************************
2 //
3 // Title: Force Field X.
4 // Description: Force Field X - Software for Molecular Biophysics.
5 // Copyright: Copyright (c) Michael J. Schnieders 2001-2025.
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 /**
168 * A java.util.concurrent.atomic.DoubleAdder implementation.
169 */
170 ADDER,
171 /**
172 * Each thread has its own array, and reduction is performed by the user.
173 */
174 MULTI,
175 /**
176 * Parallel Java edu.rit.pj.reduction.SharedDoubleArray implementation.
177 */
178 PJ
179 }
180 }