Added an "explain" method to compatibility. This prints out a message…

… explaining

all the corrections that are applied to an entry.

examples/Explanation of Corrections.ipynb

@@ -0,0 +1,115 @@
+{
+ "metadata": {
+  "name": "",
+  "signature": "sha256:1b0762dea41bd3b1b6224430bfd0661f6a71ee0df8e3f375cec94e2e5dacbca3"
+ },
+ "nbformat": 3,
+ "nbformat_minor": 0,
+ "worksheets": [
+  {
+   "cells": [
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "This notebook illustrates how to obtain an explaination of the different corrections being applied in the Materials Project."
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "import re\n",
+      "from pymatgen.entries.computed_entries import ComputedEntry\n",
+      "from pymatgen.entries.compatibility import MaterialsProjectCompatibility"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 1
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "from pymatgen import MPRester\n",
+      "\n",
+      "#To do our testing, let's use the MPRester to get a sample computed entry from the Materials Project.\n",
+      "m = MPRester()\n",
+      "entries = m.get_entries(\"LiFePO4\")\n",
+      "entry = entries[0]"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 2
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "compat = MaterialsProjectCompatibility()"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 3
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "compat.explain(entry)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [
+      {
+       "output_type": "stream",
+       "stream": "stdout",
+       "text": [
+        "The uncorrected value of the energy of P4 Fe4 O16 Li4 is -191.338121 eV\n",
+        "The following corrections / screening are applied for MaterialsProjectCompatibility:\n",
+        "\n",
+        "MP Potcar Correction correction: Checks that POTCARs are valid within a pre-defined input set. This\n",
+        "    ensures that calculations performed using different InputSets are not\n",
+        "    compared against each other.\n",
+        "\n",
+        "    Entry.parameters must contain a \"potcar_symbols\" key that is a list of\n",
+        "    all POTCARs used in the run. Again, using the example of an Fe2O3 run\n",
+        "    using Materials Project parameters, this would look like\n",
+        "    entry.parameters[\"potcar_symbols\"] = ['PAW_PBE Fe_pv 06Sep2000',\n",
+        "    'PAW_PBE O 08Apr2002'].\n",
+        "\n",
+        "This correction does not make any changes to the energy.\n",
+        "------------------------------\n",
+        "MP Gas Correction correction: Correct gas energies to obtain the right formation energies. Note that\n",
+        "    this depends on calculations being run within the same input set.\n",
+        "\n",
+        "For the entry, this correction has the value -11.236640 eV.\n",
+        "------------------------------\n",
+        "MP Advanced Correction correction: This class implements the GGA/GGA+U mixing scheme, which allows mixing of\n",
+        "    entries. Entry.parameters must contain a \"hubbards\" key which is a dict\n",
+        "    of all non-zero Hubbard U values used in the calculation. For example,\n",
+        "    if you ran a Fe2O3 calculation with Materials Project parameters,\n",
+        "    this would look like entry.parameters[\"hubbards\"] = {\"Fe\": 5.3}\n",
+        "    If the \"hubbards\" key is missing, a GGA run is assumed.\n",
+        "\n",
+        "    It should be noted that ComputedEntries assimilated using the\n",
+        "    pymatgen.apps.borg package and obtained via the MaterialsProject REST\n",
+        "    interface using the pymatgen.matproj.rest package will automatically have\n",
+        "    these fields populated.\n",
+        "\n",
+        "For the entry, this correction has the value -10.932000 eV.\n",
+        "------------------------------\n",
+        "The final energy after corrections is -213.506761\n"
+       ]
+      }
+     ],
+     "prompt_number": 4
+    }
+   ],
+   "metadata": {}
+  }
+ ]
+}

pymatgen/entries/compatibility.py

@@ -366,6 +366,33 @@ def process_entries(self, entries):
         """
         return filter(None, map(self.process_entry, entries))
 
+    def explain(self, entry):
+        """
+        Prints an explanation of the corrections that are being applied for a
+        given compatibility scheme. Inspired by the "explain" methods in many
+        database methodologies.
+
+        Args:
+            entry: A ComputedEntry.
+        """
+        entry = self.process_entry(entry)
+        print "The uncorrected value of the energy of %s is %f eV" % (
+            entry.composition, entry.uncorrected_energy)
+        print "The following corrections / screening are applied for %s:\n" %\
+            self.__class__.__name__
+        corr_dict = self.get_corrections_dict(entry)
+        for c in self.corrections:
+            desc = c.__doc__.split("Args")[0].strip()
+            print "%s correction: %s\n" % (str(c), desc.strip())
+            if str(c) in corr_dict:
+                print "For the entry, this correction has the value %f eV." % \
+                      corr_dict[str(c)]
+            else:
+                print "This correction does not make any changes to the energy."
+            print "-" * 30
+
+        print "The final energy after corrections is %f" % entry.energy
+
 
 @cached_class
 class MaterialsProjectCompatibility(Compatibility):