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.xray;
39  
40  import static java.lang.System.arraycopy;
41  import static java.util.Arrays.fill;
42  import static org.apache.commons.math3.util.FastMath.min;
43  
44  import edu.rit.pj.IntegerSchedule;
45  import edu.rit.util.Range;
46  
47  /**
48   * SliceSchedule class.
49   *
50   * @author Armin Avdic
51   * @since 1.0
52   */
53  public class SliceSchedule extends IntegerSchedule {
54  
55    private final int fftZ;
56    private final int[] lowerBounds;
57    private int nThreads;
58    private boolean[] threadDone;
59    private Range[] ranges;
60    private int[] weights;
61  
62    /**
63     * Constructor for SliceSchedule.
64     *
65     * @param nThreads a int.
66     * @param fftZ a int.
67     */
68    protected SliceSchedule(int nThreads, int fftZ) {
69      this.nThreads = nThreads;
70      this.fftZ = fftZ;
71      int length = min(nThreads, fftZ);
72      threadDone = new boolean[length];
73      ranges = new Range[length];
74      lowerBounds = new int[length + 1];
75    }
76  
77    /** {@inheritDoc} */
78    @Override
79    public boolean isFixedSchedule() {
80      return true;
81    }
82  
83    /** {@inheritDoc} */
84    @Override
85    public Range next(int threadID) {
86      if (threadID >= min(fftZ, nThreads)) {
87        return null;
88      }
89      if (!threadDone[threadID]) {
90        threadDone[threadID] = true;
91        return ranges[threadID];
92      }
93      return null;
94    }
95  
96    /** {@inheritDoc} */
97    @Override
98    public void start(int nThreads, Range chunkRange) {
99      this.nThreads = nThreads;
100     int length = min(nThreads, fftZ);
101 
102     if (length != threadDone.length) {
103       threadDone = new boolean[length];
104     }
105     fill(threadDone, false);
106 
107     if (length != ranges.length) {
108       ranges = new Range[length];
109     }
110     fill(lowerBounds, 0);
111     defineRanges();
112   }
113 
114   /**
115    * updateWeights.
116    *
117    * @param weights an array of {@link int} objects.
118    */
119   void updateWeights(int[] weights) {
120     this.weights = weights;
121   }
122 
123   private int totalWeight() {
124     int totalWeight = 0;
125     for (int i = 0; i < fftZ; i++) {
126       totalWeight += weights[i];
127     }
128     return totalWeight;
129   }
130 
131   private void defineRanges() {
132     double totalWeight = totalWeight();
133 
134     int length = min(nThreads, fftZ);
135 
136     // Infrequent edge case where the total weight is less than or equal to the number of threads.
137     if (totalWeight <= length) {
138       Range temp = new Range(0, fftZ - 1);
139       ranges = temp.subranges(length);
140       return;
141     }
142 
143     // Handle the case where we only have a single thread, which will receive all the slices.
144     if (nThreads == 1) {
145       ranges[0] = new Range(0, fftZ - 1);
146       return;
147     }
148 
149     double targetWeight = (totalWeight / nThreads) * .96;
150     int lastSlice = fftZ - 1;
151 
152     int currentSlice = 0;
153     lowerBounds[0] = 0;
154     int currentThread = 0;
155     while (currentThread < length) {
156       int threadWeight = 0;
157       while (threadWeight < targetWeight && currentSlice < lastSlice) {
158         threadWeight += weights[currentSlice];
159         currentSlice++;
160       }
161       currentThread++;
162       if (currentSlice < lastSlice) {
163         lowerBounds[currentThread] = currentSlice;
164       } else {
165         lowerBounds[currentThread] = lastSlice;
166         break;
167       }
168     }
169 
170     int lastThread = currentThread;
171 
172     // Loop over all threads that will receive work except the final one.
173     for (currentThread = 0; currentThread < lastThread - 1; currentThread++) {
174       ranges[currentThread] =
175           new Range(lowerBounds[currentThread], lowerBounds[currentThread + 1] - 1);
176     }
177 
178     // Final range for the last thread that will receive work.
179     ranges[lastThread - 1] = new Range(lowerBounds[lastThread - 1], lastSlice);
180 
181     // Left-over threads with null ranges.
182     for (int it = lastThread; it < length; it++) {
183       ranges[it] = null;
184     }
185   }
186 
187   /**
188    * getThreadWeights.
189    *
190    * @return an array of {@link int} objects.
191    */
192   int[] getThreadWeights() {
193     int length = min(fftZ, nThreads);
194     int[] weightsToReturn = new int[length];
195     arraycopy(weights, 0, weightsToReturn, 0, length);
196     return weightsToReturn;
197   }
198 
199   /**
200    * Getter for the field <code>lowerBounds</code>.
201    *
202    * @return an array of {@link int} objects.
203    */
204   int[] getLowerBounds() {
205     int length = min(fftZ, nThreads);
206     int[] boundsToReturn = new int[length];
207     arraycopy(lowerBounds, 1, boundsToReturn, 0, length);
208     return boundsToReturn;
209   }
210 }