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-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.openmm;
39  
40  import com.sun.jna.Memory;
41  import com.sun.jna.Pointer;
42  import com.sun.jna.ptr.PointerByReference;
43  
44  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_destroy;
45  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_findPlatform;
46  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getDefaultPluginsDirectory;
47  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getName;
48  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getNumPlatforms;
49  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getOpenMMVersion;
50  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPlatform;
51  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPlatformByName;
52  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPlatform_1;
53  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPluginLoadFailures;
54  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPropertyDefaultValue;
55  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPropertyNames;
56  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getPropertyValue;
57  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_getSpeed;
58  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_loadPluginLibrary;
59  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_loadPluginsFromDirectory;
60  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_registerPlatform;
61  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_setPropertyDefaultValue;
62  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_setPropertyValue;
63  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_supportsDoublePrecision;
64  import static edu.uiowa.jopenmm.OpenMMLibrary.OpenMM_Platform_supportsKernels;
65  
66  /**
67   * A Platform defines an implementation of all the kernels needed to perform some calculation.
68   * More precisely, a Platform object acts as a registry for a set of KernelFactory
69   * objects which together implement the kernels.  The Platform class, in turn, provides a
70   * static registry of all available Platform objects.
71   */
72  public class Platform {
73  
74    /**
75     * OpenMM Platform pointer.
76     */
77    private PointerByReference pointer;
78  
79    /**
80     * OpenMM Platform constructor.
81     *
82     * @param pointer The OpenMM Platform pointer.
83     */
84    public Platform(PointerByReference pointer) {
85      this.pointer = pointer;
86    }
87  
88    /**
89     * OpenMM Platform constructor.
90     *
91     * @param platformName The name of the OpenMM Platform.
92     */
93    public Platform(String platformName) {
94      pointer = OpenMM_Platform_getPlatformByName(platformName);
95    }
96  
97    /**
98     * Default constructor.
99     */
100   public Platform() {
101     pointer = null;
102   }
103 
104   /**
105    * Destroy the OpenMM Platform instance.
106    */
107   public void destroy() {
108     if (pointer != null) {
109       OpenMM_Platform_destroy(pointer);
110       pointer = null;
111     }
112   }
113 
114   /**
115    * Find a platform that supports a specified set of kernels.
116    *
117    * @param kernelNames The set of kernels that must be supported.
118    * @return A platform that supports the specified kernels.
119    */
120   public static Platform findPlatform(StringArray kernelNames) {
121     PointerByReference platformPointer = OpenMM_Platform_findPlatform(kernelNames.getPointer());
122     return new Platform(platformPointer);
123   }
124 
125   /**
126    * Get the default directory from which to load plugins.
127    *
128    * @return The default directory from which to load plugins.
129    */
130   public static String getDefaultPluginsDirectory() {
131     Pointer directory = OpenMM_Platform_getDefaultPluginsDirectory();
132     return directory.getString(0);
133   }
134 
135   /**
136    * Get the name of the OpenMM Platform.
137    *
138    * @return The name of the OpenMM Platform.
139    */
140   public String getName() {
141     Pointer name = OpenMM_Platform_getName(pointer);
142     return name.getString(0);
143   }
144 
145   /**
146    * Get the number of OpenMM Platforms.
147    *
148    * @return The number of OpenMM Platforms.
149    */
150   public static int getNumPlatforms() {
151     return OpenMM_Platform_getNumPlatforms();
152   }
153 
154   /**
155    * Get the OpenMM version.
156    *
157    * @return The version of OpenMM.
158    */
159   public static String getOpenMMVersion() {
160     Pointer version = OpenMM_Platform_getOpenMMVersion();
161     return version.getString(0);
162   }
163 
164   /**
165    * Get the OpenMM Platform pointer.
166    *
167    * @return The OpenMM Platform pointer.
168    */
169   public PointerByReference getPointer() {
170     return pointer;
171   }
172 
173   /**
174    * Get a registered platform by index.
175    *
176    * @param index The index of the platform to get.
177    * @return The platform with the specified index.
178    */
179   public static Platform getPlatform(int index) {
180     PointerByReference platformPointer = OpenMM_Platform_getPlatform(index);
181     return new Platform(platformPointer);
182   }
183 
184   /**
185    * Get a registered platform by name.
186    *
187    * @param name The name of the platform to get.
188    * @return The platform with the specified name.
189    */
190   public static Platform getPlatform_1(String name) {
191     PointerByReference platformPointer = OpenMM_Platform_getPlatform_1(name);
192     return new Platform(platformPointer);
193   }
194 
195   /**
196    * Get the plugin load failures.
197    *
198    * @return The OpenMMStringArray of plugin load failures.
199    */
200   public static StringArray getPluginLoadFailures() {
201     return new StringArray(OpenMM_Platform_getPluginLoadFailures());
202   }
203 
204   /**
205    * Get the default value of a platform property.
206    *
207    * @param property The name of the property to get.
208    * @return The default value of the property.
209    */
210   public String getPropertyDefaultValue(String property) {
211     Pointer propertyPointer = pointerForString(property);
212     Pointer value = OpenMM_Platform_getPropertyDefaultValue(pointer, propertyPointer);
213     if (value == null) {
214       return null;
215     }
216     return value.getString(0);
217   }
218 
219   /**
220    * Get the names of all platform properties.
221    *
222    * @return A StringArray containing the names of all platform properties.
223    */
224   public StringArray getPropertyNames() {
225     return new StringArray(OpenMM_Platform_getPropertyNames(pointer));
226   }
227 
228   /**
229    * Get the value of a context-specific platform property.
230    *
231    * @param context  The context for which to get the property value.
232    * @param property The name of the property to get.
233    * @return The value of the property.
234    */
235   public String getPropertyValue(Context context, String property) {
236     Pointer propertyPointer = pointerForString(property);
237     Pointer value = OpenMM_Platform_getPropertyValue(pointer, context.getPointer(), propertyPointer);
238     if (value == null) {
239       return null;
240     }
241     return value.getString(0);
242   }
243 
244   /**
245    * Get an estimate of how fast this Platform class is.
246    *
247    * @return The speed of the OpenMM Platform.
248    */
249   public double getSpeed() {
250     return OpenMM_Platform_getSpeed(pointer);
251   }
252 
253   /**
254    * Load plugins from a directory.
255    *
256    * @param directory The directory to load plugins from.
257    * @return The OpenMMStringArray of plugins loaded.
258    */
259   public static StringArray loadPluginsFromDirectory(String directory) {
260     return new StringArray(OpenMM_Platform_loadPluginsFromDirectory(directory));
261   }
262 
263   /**
264    * Load a dynamic library that contains a plugin.
265    *
266    * @param file The path to the dynamic library file.
267    */
268   public static void loadPluginLibrary(String file) {
269     OpenMM_Platform_loadPluginLibrary(file);
270   }
271 
272   /**
273    * Register a new platform.
274    *
275    * @param platform The platform to register.
276    */
277   public static void registerPlatform(Platform platform) {
278     OpenMM_Platform_registerPlatform(platform.getPointer());
279   }
280 
281   /**
282    * Set the default value of a platform property.
283    *
284    * @param property The name of the property to set.
285    * @param value    The new default value for the property.
286    */
287   public void setPropertyDefaultValue(String property, String value) {
288     Pointer propertyPointer = pointerForString(property);
289     Pointer valuePointer = pointerForString(value);
290     OpenMM_Platform_setPropertyDefaultValue(pointer, propertyPointer, valuePointer);
291   }
292 
293   /**
294    * Set the value of a context-specific platform property.
295    *
296    * @param context  The context for which to set the property value.
297    * @param property The name of the property to set.
298    * @param value    The new value for the property.
299    */
300   public void setPropertyValue(Context context, String property, String value) {
301     Pointer propertyPointer = pointerForString(property);
302     Pointer valuePointer = pointerForString(value);
303     OpenMM_Platform_setPropertyValue(pointer, context.getPointer(), propertyPointer, valuePointer);
304   }
305 
306   /**
307    * Determine whether this Platform supports double precision arithmetic.
308    *
309    * @return true if the Platform supports double precision, false otherwise.
310    */
311   public boolean supportsDoublePrecision() {
312     int result = OpenMM_Platform_supportsDoublePrecision(pointer);
313     return result != 0;
314   }
315 
316   /**
317    * Determine whether this Platform supports a specified set of kernels.
318    *
319    * @param kernelNames The set of kernels to test for support.
320    * @return true if the Platform supports all of the specified kernels, false otherwise.
321    */
322   public boolean supportsKernels(StringArray kernelNames) {
323     int result = OpenMM_Platform_supportsKernels(pointer, kernelNames.getPointer());
324     return result != 0;
325   }
326 
327   /**
328    * Create a JNA Pointer to a String.
329    *
330    * @param string WARNING: assumes ascii-only string
331    * @return pointer.
332    */
333   private static Pointer pointerForString(String string) {
334     Pointer pointer = new Memory(string.length() + 1);
335     pointer.setString(0, string);
336     return pointer;
337   }
338 }