1 /* 2 * This file is part of the GROMACS molecular simulation package. 3 * 4 * Copyright (c) 2019,2020, by the GROMACS development team, led by 5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, 6 * and including many others, as listed in the AUTHORS file in the 7 * top-level source directory and at http://www.gromacs.org. 8 * 9 * GROMACS is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU Lesser General Public License 11 * as published by the Free Software Foundation; either version 2.1 12 * of the License, or (at your option) any later version. 13 * 14 * GROMACS is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with GROMACS; if not, see 21 * http://www.gnu.org/licenses, or write to the Free Software Foundation, 22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 23 * 24 * If you want to redistribute modifications to GROMACS, please 25 * consider that scientific software is very special. Version 26 * control is crucial - bugs must be traceable. We will be happy to 27 * consider code for inclusion in the official distribution, but 28 * derived work must not be called official GROMACS. Details are found 29 * in the README & COPYING files - if they are missing, get the 30 * official version at http://www.gromacs.org. 31 * 32 * To help us fund GROMACS development, we humbly ask that you cite 33 * the research papers on the package. Check out http://www.gromacs.org. 34 */ 35 /*! \libinternal \file 36 * \brief 37 * Declares density similarity measures and their derivatives. 38 * 39 * \author Christian Blau <blau@kth.se> 40 * \inlibraryapi 41 * \ingroup module_math 42 */ 43 #ifndef GMX_MATH_DENSITYFIT_H 44 #define GMX_MATH_DENSITYFIT_H 45 46 #include "gromacs/mdspan/extensions.h" 47 #include "gromacs/utility/classhelpers.h" 48 #include "gromacs/utility/real.h" 49 50 namespace gmx 51 { 52 /*! \brief 53 * The methods that determine how two densities are compared to one another. 54 */ 55 enum class DensitySimilarityMeasureMethod : int 56 { 57 /*! \brief Measure similarity between densities as normalized inner product of their 58 * voxel values. 59 * 60 * \f[ 61 * \mathrm{Similarity}(\rho_{\mathrm{r}},\rho_{\mathrm{c}}) = 62 * \frac{1}{N_\mathrm{voxel}}/\sum_{v=1}^{N_\mathrm{voxel}} \rho^v_{\mathrm{r}} 63 * \rho^v_{\mathrm{c}} 64 * \f] 65 */ 66 innerProduct, 67 68 /*! \brief Measure similarity between densities by negative relative entropy. 69 * \note Voxels with negative values are ignored. 70 * 71 * \f[ 72 * \mathrm{Similarity}(\rho_{\mathrm{r}},\rho_{\mathrm{c}}) = 73 * \sum_{v=1}^{N_\mathrm{voxel}} 74 * \rho^v_{\mathrm{r}} (\log(\rho^v_{\mathrm{c}}) - \log(\rho^v_{\mathrm{r}})) 75 * \f] 76 */ 77 relativeEntropy, 78 79 /*! \brief Measure similarity between densities by cross correlation. 80 * 81 * \f[ 82 * \mathrm{Similarity}(\rho_{\mathrm{r}},\rho_{\mathrm{c}}) = 83 * \frac{\sum_{v}\left((\rho_{\mathrm{r}} - \bar{\rho}_{\mathrm{r}})(\rho_{\mathrm{c}} - \bar{\rho}_{\mathrm{c}})\right)} 84 * {\sqrt{\sum_v(\rho_{\mathrm{r}} - \bar{\rho}_{\mathrm{r}})^2 \sum_v (\rho_{\mathrm{c}} - \bar{\rho}_{\mathrm{c}})^2}} 85 * \f] 86 */ 87 crossCorrelation, 88 Count, 89 }; 90 91 /* Forward declaration of implementation class outside class to allow 92 * choose implementation class during construction of the DensitySimilarityMeasure*/ 93 class DensitySimilarityMeasureImpl; 94 95 /*! \libinternal \brief 96 * Measure similarity and gradient between densities. 97 */ 98 class DensitySimilarityMeasure 99 { 100 public: 101 //! a three-dimensional const view into density data 102 using density = basic_mdspan<const float, dynamicExtents3D>; 103 /*! \brief Chose comparison method and set reference density. 104 * \param[in] method defines how densities are compared to one another 105 * \param[in] referenceDensity 106 * \throws NotImplementedError if method is not known 107 */ 108 DensitySimilarityMeasure(DensitySimilarityMeasureMethod method, density referenceDensity); 109 ~DensitySimilarityMeasure(); 110 //! Copy constructor 111 DensitySimilarityMeasure(const DensitySimilarityMeasure& other); 112 //! Copy assignment 113 DensitySimilarityMeasure& operator=(const DensitySimilarityMeasure& other); 114 //! Move constructor 115 DensitySimilarityMeasure(DensitySimilarityMeasure&& other) noexcept; 116 //! Move assignment 117 DensitySimilarityMeasure& operator=(DensitySimilarityMeasure&& other) noexcept; 118 119 /*! \brief Derivative of the density similarity measure at all voxels. 120 * \param[in] comparedDensity the variable density 121 * \returns density similarity measure derivative 122 */ 123 density gradient(density comparedDensity); 124 /*! \brief Similarity between reference and compared density. 125 * \param[in] comparedDensity the variable density 126 * \returns density similarity 127 */ 128 real similarity(density comparedDensity); 129 130 private: 131 std::unique_ptr<DensitySimilarityMeasureImpl> impl_; 132 }; 133 134 } // namespace gmx 135 136 #endif 137