Print notice message when group.all() is updated

[hoomd-blue.git] / python-module / hoomd_script / compute.py

# -- start license --
# Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
# (HOOMD-blue) Open Source Software License Copyright 2008-2011 Ames Laboratory
# Iowa State University and The Regents of the University of Michigan All rights
# reserved.

# HOOMD-blue may contain modifications ("Contributions") provided, and to which
# copyright is held, by various Contributors who have granted The Regents of the
# University of Michigan the right to modify and/or distribute such Contributions.

# You may redistribute, use, and create derivate works of HOOMD-blue, in source
# and binary forms, provided you abide by the following conditions:

# * Redistributions of source code must retain the above copyright notice, this
# list of conditions, and the following disclaimer both in the code and
# prominently in any materials provided with the distribution.

# * Redistributions in binary form must reproduce the above copyright notice, this
# list of conditions, and the following disclaimer in the documentation and/or
# other materials provided with the distribution.

# * All publications and presentations based on HOOMD-blue, including any reports
# or published results obtained, in whole or in part, with HOOMD-blue, will
# acknowledge its use according to the terms posted at the time of submission on:
# http://codeblue.umich.edu/hoomd-blue/citations.html

# * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
# http://codeblue.umich.edu/hoomd-blue/

# * Apart from the above required attributions, neither the name of the copyright
# holder nor the names of HOOMD-blue's contributors may be used to endorse or
# promote products derived from this software without specific prior written
# permission.

# Disclaimer

# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
# WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.

# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
# -- end license --

# Maintainer: joaander / All Developers are free to add commands for new features

import hoomd;
from hoomd_script import globals;
import sys;
from hoomd_script import util;
from hoomd_script import init;

## \package hoomd_script.compute
# \brief Commands that %compute properties of the system
#
# A %compute calculates properties of the system on demand. Most computes are automatically generated by the command
# that needs them (e.g. integrate.nvt creates a compute.thermo for temperature calculations). User-specified computes
# can be used when more flexibility is needed. Properties calculated by specified computes (automatically, or by the
# user) can be logged with analyze.log.

## \internal
# \brief Base class for computes
#
# A compute in hoomd_script reflects a Compute in c++. It is responsible
# for all high-level management that happens behind the scenes for hoomd_script
# writers. 1) The instance of the c++ compute itself is tracked and added to the
# System 2) methods are provided for disabling the compute
class _compute:
    ## \internal
    # \brief Constructs the compute
    #
    # Initializes the cpp_compute to None.
    # Assigns a name to the compute in compute_name
    def __init__(self):
        # check if initialization has occurred
        if not init.is_initialized():
            globals.msg.error("Cannot create compute before initialization\n");
            raise RuntimeError('Error creating compute');

        self.cpp_compute = None;

        # increment the id counter
        id = _compute.cur_id;
        _compute.cur_id += 1;

        self.compute_name = "compute%d" % (id);
        self.enabled = True;

    ## \var enabled
    # \internal
    # \brief True if the compute is enabled

    ## \var cpp_compute
    # \internal
    # \brief Stores the C++ side Compute managed by this class

    ## \var compute_name
    # \internal
    # \brief The Compute's name as it is assigned to the System

    ## \internal
    # \brief Checks that proper initialization has completed
    def check_initialization(self):
        # check that we have been initialized properly
        if self.cpp_compute is None:
            globals.msg.error('Bug in hoomd_script: cpp_compute not set, please report\n');
            raise RuntimeError();

    ## Disables the compute
    #
    # \b Examples:
    # \code
    # c.disable()
    # \endcode
    #
    # Executing the disable command will remove the %compute from the system. Any run() command executed after disabling
    # a %compute will not be able to log computed values with analyze.log.
    #
    # A disabled %compute can be re-enabled with enable()
    #
    # To use this command, you must have saved the %compute in a variable, as
    # shown in this example:
    # \code
    # c = compute.some_compute()
    # # ... later in the script
    # c.disable()
    # \endcode
    def disable(self):
        util.print_status_line();
        self.check_initialization();

        # check if we are already disabled
        if not self.enabled:
            globals.msg.warning("Ignoring command to disable a compute that is already disabled");
            return;

        globals.system.removeCompute(self.compute_name);
        self.enabled = False;

    ## Enables the %compute
    #
    # \b Examples:
    # \code
    # c.enable()
    # \endcode
    #
    # See disable() for a detailed description.
    def enable(self):
        util.print_status_line();
        self.check_initialization();

        # check if we are already disabled
        if self.enabled:
            globals.msg.warning("Ignoring command to enable a compute that is already enabled");
            return;

        globals.system.addCompute(self.cpp_compute, self.compute_name);
        self.enabled = True;

# set default counter
_compute.cur_id = 0;


## Compute thermodynamic properties of a group of particles
#
# compute.thermo acts on a given group of particles and calculates thermodynamic properties of those particles when
# requested. A default compute.thermo is created that operates on the group of all particles. Integration methods
# such as integrate.nvt automatically create an internal compute.thermo for the group that they operate on.
# If thermodynamic properties are needed on additional groups, a user can specify additional compute.thermo commands.
#
# Whether they are automatically created or created by a user, all specified thermos are available for logging via
# the analyze.log command. Each one provides a set of quantities for logging, suffixed with _groupname, so that
# values for different groups are differentiated in the log file. The default compute.thermo specified on the group
# of all particles has no suffix placed on its quantity names.
#
# The quantities provided are:
#  - <b>num_particles</b><i>_groupname</i> - \f$ N \f$ - number of particles in the group
#  - <b>ndof</b><i>_groupname</i>  - \f$ N_{\mathrm{dof}} \f$ - number of degrees of freedom given to the group by
#    integrate commands
#  - <b>potential_energy</b><i>_groupname</i> - \f$ U \f$ - potential energy that the group contributes to the entire
#    system (in energy units)
#  - <b>kinetic_energy</b><i>_groupname</i> - \f$ K \f$ - total kinetic energy of all particles in the group (in energy units)
#  - <b>temperature</b><i>_groupname</i> - \f$ T \f$ - instantaneous thermal energy of the group (in energy units). Calculated as
#    \f$ T = 2 \cdot \frac{K}{N_{\mathrm{dof}}} \f$
#  - <b>pressure</b><i>_groupname</i> - \f$ P \f$ - instantaneous pressure of the group (in pressure units). Calculated as
#    \f$ P = (\frac{2}{3} \cdot K + \frac{1}{3}\cdot W)/V \f$ in 3D, where \f$ V \f$ is the volume of the simulation box and
#    \f$ W = \frac{1}{2} \sum_{i}\sum_{j \ne i} \vec{F}_{ij} \cdot \vec{r_{ij}} \f$. In 2D simulations,
#    \f$ P = (K + \frac{1}{2}\cdot W)/A \f$ where \f$ A \f$ is the area
#    of the simulation box.
#  - <b>pressure_xx</b><i>_groupname</i>, <b>pressure_xy</b><i>_groupname</i>, <b>pressure_xz</b><i>_groupname</i>,
#    <b>pressure_yy</b><i>_groupname</i>, <b>pressure_yz</b><i>_groupname</i>, <b>pressure_zz</b><i>_groupname</i> -
#    instantaneous pressure tensor of the group (in pressure units).
#    \f[ P_{ij} = \left[  \sum_{k\in[0..N)} m_k v_{k,i} v_{k,j} +
#                           \sum_{k\in[0..N)} \sum_{l > k} \frac{1}{2} \left(\vec{r}_{kl,i} \vec{F}_{kl,j} + \vec{r}_{kl,j} \vec{F}_{kl, i} \right) \right]/V \f]
#
# \sa analyze.log
class thermo(_compute):
    ## Initialize the thermodynamics computation
    #
    # \param group Group for which to compute thermodynamic properties
    #
    # \b Examples:
    # \code
    # g = group.type(name='typeA', type='A')
    # compute.thermo(group=g)
    # \endcode
    #
    def __init__(self, group):
        util.print_status_line();

        # initialize base class
        _compute.__init__(self);

        suffix = '';
        if group.name != 'all':
            suffix = '_' + group.name;

        # warn user if an existing compute thermo already uses this group or name
        for t in globals.thermos:
            if t.group is group:
                globals.msg.warning("compute.thermo already specified for this group");
            elif t.group.name == group.name:
                globals.msg.warning("compute.thermo already specified for a group with name " + str(group.name) + "\n");

        # create the c++ mirror class
        if not globals.exec_conf.isCUDAEnabled():
            self.cpp_compute = hoomd.ComputeThermo(globals.system_definition, group.cpp_group, suffix);
        else:
            self.cpp_compute = hoomd.ComputeThermoGPU(globals.system_definition, group.cpp_group, suffix);

        globals.system.addCompute(self.cpp_compute, self.compute_name);

        # save the group for later referencing
        self.group = group;
        # add ourselves to the list of compute thermos specified so far
        globals.thermos.append(self);

## \internal
# \brief Returns the previously created compute.thermo with the same group, if created. Otherwise, creates a new
# compute.thermo
def _get_unique_thermo(group):

    # first check the globals for an existing compute.thermo
    for t in globals.thermos:
        # if we find a match, return it
        if t.group is group:
            return t;

    # if we get here, there were no matches: create a new one
    util._disable_status_lines = True;
    res = thermo(group);
    util._disable_status_lines = False;
    return res;