python-module/hoomd_script/tune.py

   1 # -- start license --
   2 # Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 # (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
   4 # the University of Michigan All rights reserved.
   5
   6 # HOOMD-blue may contain modifications ("Contributions") provided, and to which
   7 # copyright is held, by various Contributors who have granted The Regents of the
   8 # University of Michigan the right to modify and/or distribute such Contributions.
   9
  10 # You may redistribute, use, and create derivate works of HOOMD-blue, in source
  11 # and binary forms, provided you abide by the following conditions:
  12
  13 # * Redistributions of source code must retain the above copyright notice, this
  14 # list of conditions, and the following disclaimer both in the code and
  15 # prominently in any materials provided with the distribution.
  16
  17 # * Redistributions in binary form must reproduce the above copyright notice, this
  18 # list of conditions, and the following disclaimer in the documentation and/or
  19 # other materials provided with the distribution.
  20
  21 # * All publications and presentations based on HOOMD-blue, including any reports
  22 # or published results obtained, in whole or in part, with HOOMD-blue, will
  23 # acknowledge its use according to the terms posted at the time of submission on:
  24 # http://codeblue.umich.edu/hoomd-blue/citations.html
  25
  26 # * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 # http://codeblue.umich.edu/hoomd-blue/
  28
  29 # * Apart from the above required attributions, neither the name of the copyright
  30 # holder nor the names of HOOMD-blue's contributors may be used to endorse or
  31 # promote products derived from this software without specific prior written
  32 # permission.
  33
  34 # Disclaimer
  35
  36 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  37 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  38 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  39 # WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  40
  41 # IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  42 # INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 # BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  44 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  46 # OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  47 # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 # -- end license --
  49 # Maintainer: joaander
  50
  51 import hoomd
  52
  53 from hoomd_script import globals
  54 from hoomd_script import init
  55 from hoomd_script import util
  56 import hoomd_script
  57
  58 import math
  59 import os
  60 import sys
  61
  62 ##
  63 # \package hoomd_script.tune
  64 # \brief Commands for tuning the performance of HOOMD
  65
  66 ## Make a series of short runs to determine the fastest performing r_buff setting
  67 # \param warmup Number of time steps to run() to warm up the benchmark
  68 # \param r_min Smallest value of r_buff to test
  69 # \param r_max Largest value of r_buff to test
  70 # \param jumps Number of different r_buff values to test
  71 # \param steps Number of time steps to run() at each point
  72 # \param set_max_check_period Set to True to enable automatic setting of the maximum nlist check_period
  73 #
  74 # tune.r_buff() executes \a warmup time steps. Then it sets the nlist \a r_buff value to \a r_min and runs for
  75 # \a steps time steps. The TPS value is recorded, and the benchmark moves on to the next \a r_buff value
  76 # completing at \a r_max in \a jumps jumps. Status information is printed out to the screen, and the optimal
  77 # \a r_buff value is left set for further runs() to continue at optimal settings.
  78 #
  79 # Each benchmark is repeated 3 times and the median value chosen. Then, \a warmup time steps are run() again
  80 # at the optimal r_buff in order to determine the maximum value of check_period. In total,
  81 # (2*warmup + 3*jump*steps) time steps are run().
  82 #
  83 # \note By default, the maximum check_period is \b not set in tune.r_buff() for safety. If you wish to have it set
  84 # when the call completes, call with the parameter set_max_check_period=True.
  85 #
  86 # \returns (optimal_r_buff, maximum check_period)
  87 #
  88 # \MPI_SUPPORTED
  89 def r_buff(warmup=200000, r_min=0.05, r_max=1.0, jumps=20, steps=5000, set_max_check_period=False):
  90     # check if initialization has occurred
  91     if not init.is_initialized():
  92         globals.msg.error("Cannot tune r_buff before initialization\n");
  93
  94     # check that there is a nlist
  95     if globals.neighbor_list is None:
  96         globals.msg.error("Cannot tune r_buff when there is no neighbor list\n");
  97
  98     # start off at a check_period of 1
  99     globals.neighbor_list.set_params(check_period=1);
 100
 101     # make the warmup run
 102     hoomd_script.run(warmup);
 103
 104     # initialize scan variables
 105     dr = (r_max - r_min) / (jumps - 1);
 106     r_buff_list = [];
 107     tps_list = [];
 108
 109     # loop over all desired r_buff points
 110     for i in range(0,jumps):
 111         # set the current r_buff
 112         r_buff = r_min + i * dr;
 113         globals.neighbor_list.set_params(r_buff=r_buff);
 114
 115         # run the benchmark 3 times
 116         tps = [];
 117         hoomd_script.run(steps);
 118         tps.append(globals.system.getLastTPS())
 119         hoomd_script.run(steps);
 120         tps.append(globals.system.getLastTPS())
 121         hoomd_script.run(steps);
 122         tps.append(globals.system.getLastTPS())
 123
 124         # record the median tps of the 3
 125         tps.sort();
 126         tps_list.append(tps[1]);
 127         r_buff_list.append(r_buff);
 128
 129     # find the fastest r_buff
 130     fastest = tps_list.index(max(tps_list));
 131     fastest_r_buff = r_buff_list[fastest];
 132
 133     # set the fastest and rerun the warmup steps to identify the max check period
 134     globals.neighbor_list.set_params(r_buff=fastest_r_buff);
 135     hoomd_script.run(warmup);
 136
 137     # notify the user of the benchmark results
 138     globals.msg.notice(2, "r_buff = " + str(r_buff_list) + '\n');
 139     globals.msg.notice(2, "tps = " + str(tps_list) + '\n');
 140     globals.msg.notice(2, "Optimal r_buff: " + str(fastest_r_buff) + '\n');
 141     globals.msg.notice(2, "Maximum check_period: " + str(globals.neighbor_list.query_update_period()) + '\n');
 142
 143     # set the found max check period
 144     if set_max_check_period:
 145         globals.neighbor_list.set_params(check_period=globals.neighbor_list.query_update_period());
 146
 147     # return the results to the script
 148     return (fastest_r_buff, globals.neighbor_list.query_update_period());