xapian-core/weight/pl2weight.cc

   1 /** @file pl2weight.cc
   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 #include "weightinternal.h"
  27
  28 #include "serialise-double.h"
  29
  30 #include "xapian/error.h"
  31
  32 using namespace std;
  33
  34 namespace Xapian {
  35
  36 PL2Weight::PL2Weight(double c) : param_c(c)
  37 {
  38     if (param_c <= 0)
  39         throw Xapian::InvalidArgumentError("Parameter c is invalid.");
  40     need_stat(AVERAGE_LENGTH);
  41     need_stat(DOC_LENGTH);
  42     need_stat(DOC_LENGTH_MIN);
  43     need_stat(DOC_LENGTH_MAX);
  44     need_stat(COLLECTION_SIZE);
  45     need_stat(COLLECTION_FREQ);
  46     need_stat(WDF);
  47     need_stat(WDF_MAX);
  48     need_stat(WQF);
  49 }
  50
  51 PL2Weight *
  52 PL2Weight::clone() const
  53 {
  54     return new PL2Weight(param_c);
  55 }
  56
  57 void
  58 PL2Weight::init(double factor_)
  59 {
  60     factor = factor_;
  61
  62     if (get_wdf_upper_bound() == 0) {
  63         // The "extra" weight object is cloned, init() called and then
  64         // get_maxextra() is called and we discover that we don't need it.
  65         // So we need to handle that case (which will give us 0 from
  66         // get_wdf_upper_bound() here).
  67         upper_bound = 0;
  68         return;
  69     }
  70
  71     factor *= get_wqf();
  72
  73     cl = param_c * get_average_length();
  74
  75     double base_change(1.0 / log(2.0));
  76     double mean = double(get_collection_freq()) / get_collection_size();
  77     P1 = mean * base_change + 0.5 * log2(2.0 * M_PI);
  78     P2 = log2(mean) + base_change;
  79
  80     double wdfn_lower = log2(1 + cl / get_doclength_upper_bound());
  81     double divisior = max(get_wdf_upper_bound(), get_doclength_lower_bound());
  82     double wdfn_upper = get_wdf_upper_bound() * log2(1 + cl / divisior);
  83
  84     // Calculate an upper bound on the weights which get_sumpart() can return.
  85     //
  86     // We consider the equation for P as the sum of two parts which we
  87     // maximise individually:
  88     //
  89     // (a) (wdfn + 0.5) / (wdfn + 1) * log2(wdfn)
  90     // (b) (P1 - P2 * wdfn) / (wdfn + 1)
  91     //
  92     // To maximise (a), the fractional part is always positive (since wdfn>0)
  93     // and is maximised by maximising wdfn - clearer when rewritten as:
  94     // (1 - 0.5 / (wdfn + 1))
  95     //
  96     // The log part of (a) is clearly also maximised by maximising wdfn,
  97     // so we want to evaluate (a) at wdfn=wdfn_upper.
  98     double P_max2a = (wdfn_upper + 0.5) * log2(wdfn_upper) / (wdfn_upper + 1.0);
  99     // To maximise (b) substitute x=wdfn+1 (so x>1) and we get:
 100     //
 101     // (P1 + P2)/x - P2
 102     //
 103     // Differentiating wrt x gives:
 104     //
 105     // -(P1 + P2)/x²
 106     //
 107     // So there are no local minima or maxima, and the function is continuous
 108     // in the range of interest, so the sign of this differential tells us
 109     // whether we want to maximise or minimise wdfn, and since x>1, we can
 110     // just consider the sign of: (P1 + P2)
 111     //
 112     // Commonly P1 + P2 > 0, in which case we evaluate P at wdfn=wdfn_upper
 113     // giving us a bound that can't be bettered if wdfn_upper is tight.
 114     double wdfn_optb = P1 + P2 > 0 ? wdfn_upper : wdfn_lower;
 115     double P_max2b = (P1 - P2 * wdfn_optb) / (wdfn_optb + 1.0);
 116     upper_bound = factor * (P_max2a + P_max2b);
 117
 118     if (rare(upper_bound <= 0)) upper_bound = 0;
 119 }
 120
 121 string
 122 PL2Weight::name() const
 123 {
 124     return "Xapian::PL2Weight";
 125 }
 126
 127 string
 128 PL2Weight::short_name() const
 129 {
 130     return "pl2";
 131 }
 132
 133 string
 134 PL2Weight::serialise() const
 135 {
 136     return serialise_double(param_c);
 137 }
 138
 139 PL2Weight *
 140 PL2Weight::unserialise(const string & s) const
 141 {
 142     const char *ptr = s.data();
 143     const char *end = ptr + s.size();
 144     double c = unserialise_double(&ptr, end);
 145     if (rare(ptr != end))
 146         throw Xapian::SerialisationError("Extra data in PL2Weight::unserialise()");
 147     return new PL2Weight(c);
 148 }
 149
 150 double
 151 PL2Weight::get_sumpart(Xapian::termcount wdf, Xapian::termcount len,
 152                        Xapian::termcount) const
 153 {
 154     if (wdf == 0) return 0.0;
 155
 156     double wdfn = wdf * log2(1 + cl / len);
 157
 158     double P = P1 + (wdfn + 0.5) * log2(wdfn) - P2 * wdfn;
 159     if (rare(P <= 0)) return 0.0;
 160
 161     return factor * P / (wdfn + 1.0);
 162 }
 163
 164 double
 165 PL2Weight::get_maxpart() const
 166 {
 167     return upper_bound;
 168 }
 169
 170 double
 171 PL2Weight::get_sumextra(Xapian::termcount, Xapian::termcount) const
 172 {
 173     return 0;
 174 }
 175
 176 double
 177 PL2Weight::get_maxextra() const
 178 {
 179     return 0;
 180 }
 181
 182 PL2Weight *
 183 PL2Weight::create_from_parameters(const char * p) const
 184 {
 185     if (*p == '\0')
 186         return new Xapian::PL2Weight();
 187     double k = 1.0;
 188     if (!Xapian::Weight::Internal::double_param(&p, &k))
 189         Xapian::Weight::Internal::parameter_error("Parameter is invalid", "pl2");
 190     if (*p)
 191         Xapian::Weight::Internal::parameter_error("Extra data after parameter", "pl2");
 192     return new Xapian::PL2Weight(k);
 193 }
 194
 195 }