xapian-core/weight/pl2weight.cc

   1 /** @file
   2  * @brief Xapian::PL2Weight class - the PL2 weighting scheme of the DFR framework.
   3  */
   4 /* Copyright (C) 2013 Aarsh Shah
   5  * Copyright (C) 2013,2014,2016 Olly Betts
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  20  */
  21
  22 #include <config.h>
  23
  24 #include "xapian/weight.h"
  25 #include "common/log2.h"
  26
  27 #include "serialise-double.h"
  28
  29 #include "xapian/error.h"
  30
  31 #include <algorithm>
  32
  33 using namespace std;
  34
  35 namespace Xapian {
  36
  37 PL2Weight::PL2Weight(double c) : param_c(c)
  38 {
  39     if (param_c <= 0)
  40         throw Xapian::InvalidArgumentError("Parameter c is invalid");
  41     need_stat(AVERAGE_LENGTH);
  42     need_stat(DOC_LENGTH);
  43     need_stat(DOC_LENGTH_MIN);
  44     need_stat(DOC_LENGTH_MAX);
  45     need_stat(COLLECTION_SIZE);
  46     need_stat(COLLECTION_FREQ);
  47     need_stat(WDF);
  48     need_stat(WDF_MAX);
  49     need_stat(WQF);
  50 }
  51
  52 PL2Weight *
  53 PL2Weight::clone() const
  54 {
  55     return new PL2Weight(param_c);
  56 }
  57
  58 void
  59 PL2Weight::init(double factor_)
  60 {
  61     if (factor_ == 0.0) {
  62         // This object is for the term-independent contribution, and that's
  63         // always zero for this scheme.
  64         return;
  65     }
  66
  67     // lower_bound is really factor.
  68     lower_bound = factor_;
  69
  70     if (get_wdf_upper_bound() == 0) {
  71         // The "extra" weight object is cloned, init() called and then
  72         // get_maxextra() is called and we discover that we don't need it.
  73         // So we need to handle that case (which will give us 0 from
  74         // get_wdf_upper_bound() here).
  75         upper_bound = 0;
  76         return;
  77     }
  78
  79     // lower_bound is really factor.
  80     lower_bound *= get_wqf();
  81
  82     cl = param_c * get_average_length();
  83
  84     double base_change(1.0 / log(2.0));
  85     double mean = double(get_collection_freq()) / get_collection_size();
  86     P1 = mean * base_change + 0.5 * log2(2.0 * M_PI);
  87     P2 = log2(mean) + base_change;
  88
  89     double wdfn_lower = log2(1 + cl / get_doclength_upper_bound());
  90     double divisior = max(get_wdf_upper_bound(), get_doclength_lower_bound());
  91     double wdfn_upper = get_wdf_upper_bound() * log2(1 + cl / divisior);
  92
  93     // Calculate an upper bound on the weights which get_sumpart() can return.
  94     //
  95     // We consider the equation for P as the sum of two parts which we
  96     // maximise individually:
  97     //
  98     // (a) (wdfn + 0.5) / (wdfn + 1) * log2(wdfn)
  99     // (b) (P1 - P2 * wdfn) / (wdfn + 1)
 100     //
 101     // To maximise (a), the fractional part is always positive (since wdfn>0)
 102     // and is maximised by maximising wdfn - clearer when rewritten as:
 103     // (1 - 0.5 / (wdfn + 1))
 104     //
 105     // The log part of (a) is clearly also maximised by maximising wdfn,
 106     // so we want to evaluate (a) at wdfn=wdfn_upper.
 107     double P_max2a = (wdfn_upper + 0.5) * log2(wdfn_upper) / (wdfn_upper + 1.0);
 108     // To maximise (b) substitute x=wdfn+1 (so x>1) and we get:
 109     //
 110     // (P1 + P2)/x - P2
 111     //
 112     // Differentiating wrt x gives:
 113     //
 114     // -(P1 + P2)/x²
 115     //
 116     // So there are no local minima or maxima, and the function is continuous
 117     // in the range of interest, so the sign of this differential tells us
 118     // whether we want to maximise or minimise wdfn, and since x>1, we can
 119     // just consider the sign of: (P1 + P2)
 120     //
 121     // Commonly P1 + P2 > 0, in which case we evaluate P at wdfn=wdfn_upper
 122     // giving us a bound that can't be bettered if wdfn_upper is tight.
 123     double wdfn_optb = P1 + P2 > 0 ? wdfn_upper : wdfn_lower;
 124     double P_max2b = (P1 - P2 * wdfn_optb) / (wdfn_optb + 1.0);
 125     // lower_bound is really factor.
 126     upper_bound = lower_bound * (P_max2a + P_max2b);
 127
 128     if (rare(upper_bound <= 0)) upper_bound = 0;
 129 }
 130
 131 string
 132 PL2Weight::name() const
 133 {
 134     return "Xapian::PL2Weight";
 135 }
 136
 137 string
 138 PL2Weight::serialise() const
 139 {
 140     return serialise_double(param_c);
 141 }
 142
 143 PL2Weight *
 144 PL2Weight::unserialise(const string & s) const
 145 {
 146     const char *ptr = s.data();
 147     const char *end = ptr + s.size();
 148     double c = unserialise_double(&ptr, end);
 149     if (rare(ptr != end))
 150         throw Xapian::SerialisationError("Extra data in PL2Weight::unserialise()");
 151     return new PL2Weight(c);
 152 }
 153
 154 double
 155 PL2Weight::get_sumpart(Xapian::termcount wdf, Xapian::termcount len,
 156                        Xapian::termcount) const
 157 {
 158     if (wdf == 0) return 0.0;
 159
 160     double wdfn = wdf * log2(1 + cl / len);
 161
 162     double P = P1 + (wdfn + 0.5) * log2(wdfn) - P2 * wdfn;
 163     if (rare(P <= 0)) return 0.0;
 164
 165     // lower_bound is really factor.
 166     return lower_bound * P / (wdfn + 1.0);
 167 }
 168
 169 double
 170 PL2Weight::get_maxpart() const
 171 {
 172     return upper_bound;
 173 }
 174
 175 double
 176 PL2Weight::get_sumextra(Xapian::termcount, Xapian::termcount) const
 177 {
 178     return 0;
 179 }
 180
 181 double
 182 PL2Weight::get_maxextra() const
 183 {
 184     return 0;
 185 }
 186
 187 }