You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by cp...@apache.org on 2018/03/02 18:58:59 UTC

lucene-solr:master: SOLR-11597: Add contrib/ltr NeuralNetworkModel class. (Michael A. Alcorn, Yuki Yano, Christine Poerschke)

Repository: lucene-solr
Updated Branches:
  refs/heads/master c59e2e98d -> c5938f79e


SOLR-11597: Add contrib/ltr NeuralNetworkModel class.
(Michael A. Alcorn, Yuki Yano, Christine Poerschke)

Closes #270


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/c5938f79
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/c5938f79
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/c5938f79

Branch: refs/heads/master
Commit: c5938f79e540f81b6d61560d324b150a5efd7011
Parents: c59e2e9
Author: Christine Poerschke <cp...@apache.org>
Authored: Fri Mar 2 18:27:55 2018 +0000
Committer: Christine Poerschke <cp...@apache.org>
Committed: Fri Mar 2 18:27:55 2018 +0000

----------------------------------------------------------------------
 solr/CHANGES.txt                                |   2 +
 .../solr/ltr/model/NeuralNetworkModel.java      | 297 +++++++++++++++
 .../neuralnetworkmodel_features.json            |  30 ++
 .../neuralnetworkmodel_bad_activation.json      |  26 ++
 .../neuralnetworkmodel_custom.json              |  17 +
 .../neuralnetworkmodel_explainable.json         |  26 ++
 .../neuralnetworkmodel_mismatch_bias.json       |  26 ++
 .../neuralnetworkmodel_mismatch_input.json      |  26 ++
 .../neuralnetworkmodel_mismatch_layers.json     |  25 ++
 .../neuralnetworkmodel_too_many_rows.json       |  27 ++
 .../solr/ltr/model/TestNeuralNetworkModel.java  | 365 +++++++++++++++++++
 solr/solr-ref-guide/src/learning-to-rank.adoc   |   1 +
 12 files changed, 868 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/CHANGES.txt
----------------------------------------------------------------------
diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt
index 682f5d3..b902a27 100644
--- a/solr/CHANGES.txt
+++ b/solr/CHANGES.txt
@@ -170,6 +170,8 @@ New Features
 
 * SOLR-12006: Add a '*_t' and '*_t_sort' dynamic field for single valued text fields (Varun Thacker)
 
+* SOLR-11597: Add contrib/ltr NeuralNetworkModel class. (Michael A. Alcorn, Yuki Yano, Christine Poerschke)
+
 Bug Fixes
 ----------------------
 

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/java/org/apache/solr/ltr/model/NeuralNetworkModel.java
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/java/org/apache/solr/ltr/model/NeuralNetworkModel.java b/solr/contrib/ltr/src/java/org/apache/solr/ltr/model/NeuralNetworkModel.java
new file mode 100644
index 0000000..798b81c
--- /dev/null
+++ b/solr/contrib/ltr/src/java/org/apache/solr/ltr/model/NeuralNetworkModel.java
@@ -0,0 +1,297 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.ltr.model;
+
+import java.lang.Math;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.lucene.index.LeafReaderContext;
+import org.apache.lucene.search.Explanation;
+import org.apache.solr.ltr.feature.Feature;
+import org.apache.solr.ltr.norm.Normalizer;
+import org.apache.solr.util.SolrPluginUtils;
+
+/**
+ * A scoring model that computes document scores using a neural network.
+ * <p>
+ * Supported <a href="https://en.wikipedia.org/wiki/Activation_function">activation functions</a> are:
+ * <code>identity</code>, <code>relu</code>, <code>sigmoid</code> and
+ * contributions to support additional activation functions are welcome.
+ * <p>
+ * Example configuration:
+<pre>{
+    "class" : "org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name" : "rankNetModel",
+    "features" : [
+        { "name" : "documentRecency" },
+        { "name" : "isBook" },
+        { "name" : "originalScore" }
+    ],
+    "params" : {
+        "layers" : [
+            {
+                "matrix" : [ [ 1.0, 2.0, 3.0 ],
+                             [ 4.0, 5.0, 6.0 ],
+                             [ 7.0, 8.0, 9.0 ],
+                             [ 10.0, 11.0, 12.0 ] ],
+                "bias" : [ 13.0, 14.0, 15.0, 16.0 ],
+                "activation" : "sigmoid"
+            },
+            {
+                "matrix" : [ [ 17.0, 18.0, 19.0, 20.0 ],
+                             [ 21.0, 22.0, 23.0, 24.0 ] ],
+                "bias" : [ 25.0, 26.0 ],
+                "activation" : "relu"
+            },
+            {
+                "matrix" : [ [ 27.0, 28.0 ] ],
+                "bias" : [ 29.0 ],
+                "activation" : "identity"
+            }
+        ]
+    }
+}</pre>
+ * <p>
+ * Training libraries:
+ * <ul>
+ * <li> <a href="https://keras.io">Keras</a> is a high-level neural networks API, written in Python.
+ * A Keras and Solr implementation of RankNet can be found at <a href="https://github.com/airalcorn2/RankNet">https://github.com/airalcorn2/RankNet</a>.
+ * </ul>
+ * <p>
+ * Background reading:
+ * <ul>
+ * <li> <a href="http://icml.cc/2015/wp-content/uploads/2015/06/icml_ranking.pdf">
+ * C. Burges, T. Shaked, E. Renshaw, A. Lazier, M. Deeds, N. Hamilton, and G. Hullender. Learning to Rank Using Gradient Descent.
+ * Proceedings of the 22nd International Conference on Machine Learning (ICML), ACM, 2005.</a>
+ * </ul>
+ */
+public class NeuralNetworkModel extends LTRScoringModel {
+
+  private List<Layer> layers;
+
+  protected interface Activation {
+    // similar to UnaryOperator<Float>
+    float apply(float in);
+  }
+
+  public interface Layer {
+    public float[] calculateOutput(float[] inputVec);
+    public int validate(int inputDim) throws ModelException;
+    public String describe();
+  }
+
+  public class DefaultLayer implements Layer {
+    private int layerID;
+    private float[][] weightMatrix;
+    private int matrixRows;
+    private int matrixCols;
+    private float[] biasVector;
+    private int numUnits;
+    protected String activationStr;
+    protected Activation activation;
+
+    public DefaultLayer() {
+      layerID = layers.size();
+    }
+
+    public void setMatrix(Object matrixObj) {
+      final List<List<Double>> matrix = (List<List<Double>>) matrixObj;
+      this.matrixRows = matrix.size();
+      this.matrixCols = matrix.get(0).size();
+      this.weightMatrix = new float[this.matrixRows][this.matrixCols];
+
+      for (int i = 0; i < this.matrixRows; i++) {
+        for (int j = 0; j < this.matrixCols; j++) {
+          this.weightMatrix[i][j] = matrix.get(i).get(j).floatValue();
+        }
+      }
+    }
+
+    public void setBias(Object biasObj) {
+      final List<Double> vector = (List<Double>) biasObj;
+      this.numUnits = vector.size();
+      this.biasVector = new float[numUnits];
+
+      for (int i = 0; i < this.numUnits; i++) {
+        this.biasVector[i] = vector.get(i).floatValue();
+      }
+    }
+
+    public void setActivation(Object activationStr) {
+      this.activationStr = (String) activationStr;
+      switch (this.activationStr) {
+        case "relu":
+          this.activation = new Activation() {
+            @Override
+            public float apply(float in) {
+              return in < 0 ? 0 : in;
+            }
+          };
+          break;
+        case "sigmoid":
+          this.activation = new Activation() {
+            @Override
+            public float apply(float in) {
+              return (float) (1 / (1 + Math.exp(-in)));
+            }
+          };
+          break;
+        case "identity":
+          this.activation = new Activation() {
+            @Override
+            public float apply(float in) {
+              return in;
+            }
+          };
+          break;
+        default:
+          this.activation = null;
+          break;
+      }
+    }
+
+    public float[] calculateOutput(float[] inputVec) {
+
+      float[] outputVec = new float[this.matrixRows];
+
+      for (int i = 0; i < this.matrixRows; i++) {
+        float outputVal = this.biasVector[i];
+        for (int j = 0; j < this.matrixCols; j++) {
+          outputVal += this.weightMatrix[i][j] * inputVec[j];
+        }
+        outputVec[i] = this.activation.apply(outputVal);
+      }
+
+      return outputVec;
+    }
+
+    public int validate(int inputDim) throws ModelException {
+      if (this.numUnits != this.matrixRows) {
+        throw new ModelException("Dimension mismatch in model \""  + name +  "\". Layer " +
+                                 Integer.toString(this.layerID) + " has " + Integer.toString(this.numUnits) +
+                                 " bias weights but " + Integer.toString(this.matrixRows) + " weight matrix rows.");
+      }
+      if (this.activation == null) {
+        throw new ModelException("Invalid activation function (\""+this.activationStr+"\") in layer "+Integer.toString(this.layerID)+" of model \"" + name + "\".");
+      }
+      if (inputDim != this.matrixCols) {
+        if (this.layerID == 0) {
+          throw new ModelException("Dimension mismatch in model \"" + name + "\". The input has " +
+                                   Integer.toString(inputDim) + " features, but the weight matrix for layer 0 has " +
+                                   Integer.toString(this.matrixCols) + " columns.");
+        } else {
+          throw new ModelException("Dimension mismatch in model \"" + name + "\". The weight matrix for layer " +
+                                   Integer.toString(this.layerID - 1) + " has " + Integer.toString(inputDim) + " rows, but the " +
+                                   "weight matrix for layer " + Integer.toString(this.layerID) + " has " +
+                                   Integer.toString(this.matrixCols) + " columns.");
+        }
+      }
+      return this.matrixRows;
+    }
+
+    public String describe() {
+      final StringBuilder sb = new StringBuilder();
+      sb
+      .append("(matrix=").append(Integer.toString(this.matrixRows)).append('x').append(Integer.toString(this.matrixCols))
+      .append(",activation=").append(this.activationStr).append(")");
+      return sb.toString();
+    }
+  }
+
+  protected Layer createLayer(Object o) {
+    final DefaultLayer layer = new DefaultLayer();
+    if (o != null) {
+      SolrPluginUtils.invokeSetters(layer, ((Map<String,Object>) o).entrySet());
+    }
+    return layer;
+  }
+
+  public void setLayers(Object layers) {
+    this.layers = new ArrayList<Layer>();
+    for (final Object o : (List<Object>) layers) {
+      final Layer layer = createLayer(o);
+      this.layers.add(layer);
+    }
+  }
+
+  public NeuralNetworkModel(String name, List<Feature> features,
+                 List<Normalizer> norms,
+                 String featureStoreName, List<Feature> allFeatures,
+                 Map<String,Object> params) {
+    super(name, features, norms, featureStoreName, allFeatures, params);
+  }
+
+  @Override
+  protected void validate() throws ModelException {
+    super.validate();
+
+    int inputDim = features.size();
+
+    for (Layer layer : layers) {
+      inputDim = layer.validate(inputDim);
+    }
+
+    if (inputDim != 1) {
+      throw new ModelException("The output matrix for model \"" + name + "\" has " + Integer.toString(inputDim) +
+                               " rows, but should only have one.");
+    }
+  }
+
+  @Override
+  public float score(float[] inputFeatures) {
+
+    float[] outputVec = inputFeatures;
+
+    for (Layer layer : layers) {
+      outputVec = layer.calculateOutput(outputVec);
+    }
+
+    return outputVec[0];
+  }
+
+  @Override
+  public Explanation explain(LeafReaderContext context, int doc,
+                             float finalScore, List<Explanation> featureExplanations) {
+
+    final StringBuilder modelDescription = new StringBuilder();
+
+    modelDescription.append("(name=").append(getName());
+    modelDescription.append(",featureValues=[");
+
+    for (int i = 0; i < featureExplanations.size(); i++) {
+      Explanation featureExplain = featureExplanations.get(i);
+      if (i > 0) {
+        modelDescription.append(',');
+      }
+      final String key = features.get(i).getName();
+      modelDescription.append(key).append('=').append(featureExplain.getValue());
+    }
+
+    modelDescription.append("],layers=[");
+
+    for (int i = 0; i < layers.size(); i++) {
+      if (i > 0) modelDescription.append(',');
+      modelDescription.append(layers.get(i).describe());
+    }
+    modelDescription.append("])");
+
+    return Explanation.match(finalScore, modelDescription.toString());
+  }
+
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/featureExamples/neuralnetworkmodel_features.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/featureExamples/neuralnetworkmodel_features.json b/solr/contrib/ltr/src/test-files/featureExamples/neuralnetworkmodel_features.json
new file mode 100644
index 0000000..2f0bea5
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/featureExamples/neuralnetworkmodel_features.json
@@ -0,0 +1,30 @@
+[
+    {
+        "name": "constantOne",
+        "class": "org.apache.solr.ltr.feature.ValueFeature",
+        "params": {
+            "value": 1.0
+        }
+    },
+    {
+        "name": "constantTwo",
+        "class": "org.apache.solr.ltr.feature.ValueFeature",
+        "params": {
+            "value": 2.0
+        }
+    },
+    {
+        "name": "constantThree",
+        "class": "org.apache.solr.ltr.feature.ValueFeature",
+        "params": {
+            "value": 3.0
+        }
+    },
+    {
+        "name": "constantFour",
+        "class": "org.apache.solr.ltr.feature.ValueFeature",
+        "params": {
+            "value": 4.0
+        }
+    }
+]

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_bad_activation.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_bad_activation.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_bad_activation.json
new file mode 100644
index 0000000..482d99f
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_bad_activation.json
@@ -0,0 +1,26 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_bad_activation",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 2.0, 3.0, 4.0 ],
+                            [ 5.0, 6.0, 7.0, 8.0 ],
+                            [ 9.0, 10.0, 11.0, 12.0 ] ],
+                "bias" : [ 13.0, 14.0, 15.0 ],
+                "activation": "sig"
+            },
+            {
+                "matrix": [ [ 16.0, 17.0, 18.0 ] ],
+                "bias" : [ 19.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_custom.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_custom.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_custom.json
new file mode 100644
index 0000000..78b32e9
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_custom.json
@@ -0,0 +1,17 @@
+{
+    "class":"org.apache.solr.ltr.model.TestNeuralNetworkModel$CustomNeuralNetworkModel",
+    "name":"neuralnetworkmodel_custom",
+    "features":[
+        { "name": "constantFour"},
+        { "name": "constantTwo"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 1.0 ] ],
+                "bias" : [ 0.0 ],
+                "activation": "answer"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_explainable.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_explainable.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_explainable.json
new file mode 100644
index 0000000..7602f89
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_explainable.json
@@ -0,0 +1,26 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_explainable",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [
+                    [ 11.0, 2.0, 33.0, 4.0 ],
+                    [ 1.0, 22.0, 3.0, 44.0 ] ],
+                "bias" : [ 55.0, 66.0 ],
+                "activation": "relu"
+            },
+            {
+                "matrix": [ [ 11.0, 22.0 ] ],
+                "bias" : [ 77.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_bias.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_bias.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_bias.json
new file mode 100644
index 0000000..05d6b42
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_bias.json
@@ -0,0 +1,26 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_mismatch_bias",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 2.0, 3.0, 4.0 ],
+                            [ 5.0, 6.0, 7.0, 8.0 ],
+                            [ 9.0, 10.0, 11.0, 12.0 ] ],
+                "bias" : [ 13.0, 14.0 ],
+                "activation": "relu"
+            },
+            {
+                "matrix": [ [ 16.0, 17.0, 18.0 ] ],
+                "bias" : [ 19.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_input.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_input.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_input.json
new file mode 100644
index 0000000..4b1c078
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_input.json
@@ -0,0 +1,26 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_mismatch_input",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 2.0, 3.0 ],
+                            [ 5.0, 6.0, 7.0 ],
+                            [ 9.0, 10.0, 11.0 ] ],
+                "bias" : [ 13.0, 14.0, 15.0 ],
+                "activation": "relu"
+            },
+            {
+                "matrix": [ [ 16.0, 17.0, 18.0 ] ],
+                "bias" : [ 19.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_layers.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_layers.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_layers.json
new file mode 100644
index 0000000..e8d1dde
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_mismatch_layers.json
@@ -0,0 +1,25 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_mismatch_layers",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 2.0, 3.0, 4.0 ],
+                            [ 5.0, 6.0, 7.0, 8.0 ] ],
+                "bias" : [ 13.0, 14.0 ],
+                "activation": "relu"
+            },
+            {
+                "matrix": [ [ 16.0, 17.0, 18.0 ] ],
+                "bias" : [ 19.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_too_many_rows.json
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_too_many_rows.json b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_too_many_rows.json
new file mode 100644
index 0000000..b850506
--- /dev/null
+++ b/solr/contrib/ltr/src/test-files/modelExamples/neuralnetworkmodel_too_many_rows.json
@@ -0,0 +1,27 @@
+{
+    "class":"org.apache.solr.ltr.model.NeuralNetworkModel",
+    "name":"neuralnetworkmodel_too_many_rows",
+    "features":[
+        { "name": "constantOne"},
+        { "name": "constantTwo"},
+        { "name": "constantThree"},
+        { "name": "constantFour"}
+    ],
+    "params":{
+        "layers": [
+            {
+                "matrix": [ [ 1.0, 2.0, 3.0, 4.0 ],
+                            [ 5.0, 6.0, 7.0, 8.0 ],
+                            [ 9.0, 10.0, 11.0, 12.0 ] ],
+                "bias" : [ 13.0, 14.0, 15.0 ],
+                "activation": "relu"
+            },
+            {
+                "matrix": [ [ 16.0, 17.0, 18.0 ],
+                            [ 19.0, 20.0, 21.0 ] ],
+                "bias" : [ 19.0 ],
+                "activation": "identity"
+            }
+        ]
+    }
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/contrib/ltr/src/test/org/apache/solr/ltr/model/TestNeuralNetworkModel.java
----------------------------------------------------------------------
diff --git a/solr/contrib/ltr/src/test/org/apache/solr/ltr/model/TestNeuralNetworkModel.java b/solr/contrib/ltr/src/test/org/apache/solr/ltr/model/TestNeuralNetworkModel.java
new file mode 100644
index 0000000..712249f
--- /dev/null
+++ b/solr/contrib/ltr/src/test/org/apache/solr/ltr/model/TestNeuralNetworkModel.java
@@ -0,0 +1,365 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.ltr.model;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.lucene.search.Explanation;
+import org.apache.solr.ltr.TestRerankBase;
+import org.apache.solr.ltr.feature.Feature;
+import org.apache.solr.ltr.norm.IdentityNormalizer;
+import org.apache.solr.ltr.norm.Normalizer;
+import org.apache.solr.util.SolrPluginUtils;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class TestNeuralNetworkModel extends TestRerankBase {
+
+  public static LTRScoringModel createNeuralNetworkModel(String name, List<Feature> features,
+      List<Normalizer> norms,
+      String featureStoreName, List<Feature> allFeatures,
+      Map<String,Object> params) throws ModelException {
+    return LTRScoringModel.getInstance(solrResourceLoader,
+        NeuralNetworkModel.class.getName(),
+        name,
+        features, norms, featureStoreName, allFeatures, params);
+  }
+
+  @BeforeClass
+  public static void setup() throws Exception {
+    setuptest(false);
+  }
+  
+  @AfterClass
+  public static void after() throws Exception {
+    aftertest();
+  }
+
+  protected static Map<String,Object> createLayerParams(double[][] matrix, double[] bias, String activation) {
+
+    final ArrayList<ArrayList<Double>> matrixList = new ArrayList<ArrayList<Double>>();
+    for (int row = 0; row < matrix.length; row++) {
+      matrixList.add(new ArrayList<Double>());
+      for (int col = 0; col < matrix[row].length; col++) {
+        matrixList.get(row).add(matrix[row][col]);
+      }
+    }
+
+    final ArrayList<Double> biasList = new ArrayList<Double>();
+    for (int i = 0; i < bias.length; i++) {
+      biasList.add(bias[i]);
+    }
+
+    final Map<String,Object> layer = new HashMap<String,Object>();
+    layer.put("matrix", matrixList);
+    layer.put("bias", biasList);
+    layer.put("activation", activation);
+
+    return layer;
+  }
+
+  @Test
+  public void testLinearAlgebra() {
+
+    final double layer1Node1Weight1 = 1.0;
+    final double layer1Node1Weight2 = 2.0;
+    final double layer1Node1Weight3 = 3.0;
+    final double layer1Node1Weight4 = 4.0;
+    final double layer1Node2Weight1 = 5.0;
+    final double layer1Node2Weight2 = 6.0;
+    final double layer1Node2Weight3 = 7.0;
+    final double layer1Node2Weight4 = 8.0;
+    final double layer1Node3Weight1 = 9.0;
+    final double layer1Node3Weight2 = 10.0;
+    final double layer1Node3Weight3 = 11.0;
+    final double layer1Node3Weight4 = 12.0;
+
+    double[][] matrixOne = { { layer1Node1Weight1, layer1Node1Weight2, layer1Node1Weight3, layer1Node1Weight4 },
+                             { layer1Node2Weight1, layer1Node2Weight2, layer1Node2Weight3, layer1Node2Weight4 },
+                             { layer1Node3Weight1, layer1Node3Weight2, layer1Node3Weight3, layer1Node3Weight4 } };
+
+    final double layer1Node1Bias = 13.0;
+    final double layer1Node2Bias = 14.0;
+    final double layer1Node3Bias = 15.0;
+
+    double[] biasOne = { layer1Node1Bias, layer1Node2Bias, layer1Node3Bias };
+
+    final double outputNodeWeight1 = 16.0;
+    final double outputNodeWeight2 = 17.0;
+    final double outputNodeWeight3 = 18.0;
+
+    double[][] matrixTwo = { { outputNodeWeight1, outputNodeWeight2, outputNodeWeight3 } };
+
+    final double outputNodeBias = 19.0;
+
+    double[] biasTwo = { outputNodeBias };
+
+    Map<String,Object> params = new HashMap<String,Object>();
+    ArrayList<Map<String,Object>> layers = new ArrayList<Map<String,Object>>();
+
+    layers.add(createLayerParams(matrixOne, biasOne, "relu"));
+    layers.add(createLayerParams(matrixTwo, biasTwo, "relu"));
+
+    params.put("layers", layers);
+
+    final List<Feature> allFeaturesInStore
+       = getFeatures(new String[] {"constantOne", "constantTwo", "constantThree", "constantFour", "constantFive"});
+
+    final List<Feature> featuresInModel = new ArrayList<>(allFeaturesInStore);
+    Collections.shuffle(featuresInModel, random()); // store and model order of features can vary
+    featuresInModel.remove(0); // models need not use all the store's features
+    assertEquals(4, featuresInModel.size()); // the test model uses four features
+
+    final List<Normalizer> norms =
+        new ArrayList<Normalizer>(
+            Collections.nCopies(featuresInModel.size(),IdentityNormalizer.INSTANCE));
+    final LTRScoringModel ltrScoringModel = createNeuralNetworkModel("test_score",
+        featuresInModel, norms, "test_score", allFeaturesInStore, params);
+
+    {
+      // pretend all features scored zero
+      float[] testVec = { 0.0f, 0.0f, 0.0f, 0.0f };
+      // with all zero inputs the layer1 node outputs are layer1 node biases only
+      final double layer1Node1Output = layer1Node1Bias;
+      final double layer1Node2Output = layer1Node2Bias;
+      final double layer1Node3Output = layer1Node3Bias;
+      // with just one layer the output node calculation is easy
+      final double outputNodeOutput =
+          (layer1Node1Output*outputNodeWeight1) +
+          (layer1Node2Output*outputNodeWeight2) +
+          (layer1Node3Output*outputNodeWeight3) +
+          outputNodeBias;
+      assertEquals(735.0, outputNodeOutput, 0.001);
+      // and the expected score is that of the output node
+      final double expectedScore = outputNodeOutput;
+      float score = ltrScoringModel.score(testVec);
+      assertEquals(expectedScore, score, 0.001);
+    }
+
+    {
+      // pretend all features scored one
+      float[] testVec = { 1.0f, 1.0f, 1.0f, 1.0f };
+      // with all one inputs the layer1 node outputs are simply sum of weights and biases
+      final double layer1Node1Output = layer1Node1Weight1 + layer1Node1Weight2 + layer1Node1Weight3 + layer1Node1Weight4 + layer1Node1Bias;
+      final double layer1Node2Output = layer1Node2Weight1 + layer1Node2Weight2 + layer1Node2Weight3 + layer1Node2Weight4 + layer1Node2Bias;
+      final double layer1Node3Output = layer1Node3Weight1 + layer1Node3Weight2 + layer1Node3Weight3 + layer1Node3Weight4 + layer1Node3Bias;
+      // with just one layer the output node calculation is easy
+      final double outputNodeOutput =
+          (layer1Node1Output*outputNodeWeight1) +
+          (layer1Node2Output*outputNodeWeight2) +
+          (layer1Node3Output*outputNodeWeight3) +
+          outputNodeBias;
+      assertEquals(2093.0, outputNodeOutput, 0.001);
+      // and the expected score is that of the output node
+      final double expectedScore = outputNodeOutput;
+      float score = ltrScoringModel.score(testVec);
+      assertEquals(expectedScore, score, 0.001);
+    }
+
+    {
+      // pretend all features scored random numbers in 0.0 to 1.0 range
+      final float input1 = random().nextFloat();
+      final float input2 = random().nextFloat();
+      final float input3 = random().nextFloat();
+      final float input4 = random().nextFloat();
+      float[] testVec = {input1, input2, input3, input4};
+      // the layer1 node outputs are sum of input-times-weight plus bias
+      final double layer1Node1Output = input1*layer1Node1Weight1 + input2*layer1Node1Weight2 + input3*layer1Node1Weight3 + input4*layer1Node1Weight4 + layer1Node1Bias;
+      final double layer1Node2Output = input1*layer1Node2Weight1 + input2*layer1Node2Weight2 + input3*layer1Node2Weight3 + input4*layer1Node2Weight4 + layer1Node2Bias;
+      final double layer1Node3Output = input1*layer1Node3Weight1 + input2*layer1Node3Weight2 + input3*layer1Node3Weight3 + input4*layer1Node3Weight4 + layer1Node3Bias;
+      // with just one layer the output node calculation is easy
+      final double outputNodeOutput =
+          (layer1Node1Output*outputNodeWeight1) +
+          (layer1Node2Output*outputNodeWeight2) +
+          (layer1Node3Output*outputNodeWeight3) +
+          outputNodeBias;
+      assertTrue("outputNodeOutput="+outputNodeOutput, 735.0 <= outputNodeOutput); // inputs between zero and one produced output greater than 74
+      assertTrue("outputNodeOutput="+outputNodeOutput, outputNodeOutput <= 2093.0); // inputs between zero and one produced output less than 294
+      // and the expected score is that of the output node
+      final double expectedScore = outputNodeOutput;
+      float score = ltrScoringModel.score(testVec);
+      assertEquals(expectedScore, score, 0.001);
+    }
+  }
+
+  @Test
+  public void badActivationTest() throws Exception {
+    final ModelException expectedException =
+            new ModelException("Invalid activation function (\"sig\") in layer 0 of model \"neuralnetworkmodel_bad_activation\".");
+    try {
+      createModelFromFiles("neuralnetworkmodel_bad_activation.json",
+             "neuralnetworkmodel_features.json");
+      fail("badActivationTest failed to throw exception: "+expectedException);
+    } catch (Exception actualException) {
+      Throwable rootError = getRootCause(actualException);
+      assertEquals(expectedException.toString(), rootError.toString());
+    }
+  }
+
+  @Test
+  public void biasDimensionMismatchTest() throws Exception {
+    final ModelException expectedException =
+            new ModelException("Dimension mismatch in model \"neuralnetworkmodel_mismatch_bias\". " +
+                               "Layer 0 has 2 bias weights but 3 weight matrix rows.");
+    try {
+      createModelFromFiles("neuralnetworkmodel_mismatch_bias.json",
+             "neuralnetworkmodel_features.json");
+      fail("biasDimensionMismatchTest failed to throw exception: "+expectedException);
+    } catch (Exception actualException) {
+      Throwable rootError = getRootCause(actualException);
+      assertEquals(expectedException.toString(), rootError.toString());
+    }
+  }
+
+  @Test
+  public void inputDimensionMismatchTest() throws Exception {
+    final ModelException expectedException =
+        new ModelException("Dimension mismatch in model \"neuralnetworkmodel_mismatch_input\". The input has " +
+                           "4 features, but the weight matrix for layer 0 has 3 columns.");
+    try {
+        createModelFromFiles("neuralnetworkmodel_mismatch_input.json",
+               "neuralnetworkmodel_features.json");
+        fail("inputDimensionMismatchTest failed to throw exception: "+expectedException);
+    } catch (Exception actualException) {
+      Throwable rootError = getRootCause(actualException);
+      assertEquals(expectedException.toString(), rootError.toString());
+    }
+  }
+
+  @Test
+  public void layerDimensionMismatchTest() throws Exception {
+    final ModelException expectedException =
+        new ModelException("Dimension mismatch in model \"neuralnetworkmodel_mismatch_layers\". The weight matrix " +
+                           "for layer 0 has 2 rows, but the weight matrix for layer 1 has 3 columns.");
+    try {
+        createModelFromFiles("neuralnetworkmodel_mismatch_layers.json",
+               "neuralnetworkmodel_features.json");
+        fail("layerDimensionMismatchTest failed to throw exception: "+expectedException);
+    } catch (Exception actualException) {
+      Throwable rootError = getRootCause(actualException);
+      assertEquals(expectedException.toString(), rootError.toString());
+    }
+  }
+  
+  @Test
+  public void tooManyRowsTest() throws Exception {
+    final ModelException expectedException =
+        new ModelException("Dimension mismatch in model \"neuralnetworkmodel_too_many_rows\". " +
+                           "Layer 1 has 1 bias weights but 2 weight matrix rows.");
+    try {
+        createModelFromFiles("neuralnetworkmodel_too_many_rows.json",
+               "neuralnetworkmodel_features.json");
+        fail("layerDimensionMismatchTest failed to throw exception: "+expectedException);
+    } catch (Exception actualException) {
+      Throwable rootError = getRootCause(actualException);
+      assertEquals(expectedException.toString(), rootError.toString());
+    }
+  }
+
+  @Test
+  public void testExplain() throws Exception {
+
+    final LTRScoringModel model = createModelFromFiles("neuralnetworkmodel_explainable.json",
+        "neuralnetworkmodel_features.json");
+
+    final float[] featureValues = { 1.2f, 3.4f, 5.6f, 7.8f };
+
+    final List<Explanation> explanations = new ArrayList<Explanation>();
+    for (int ii=0; ii<featureValues.length; ++ii)
+    {
+      explanations.add(Explanation.match(featureValues[ii], ""));
+    }
+
+    final float finalScore = model.score(featureValues);
+    final Explanation explanation = model.explain(null, 0, finalScore, explanations);
+    assertEquals(finalScore+" = (name=neuralnetworkmodel_explainable"+
+        ",featureValues=[constantOne=1.2,constantTwo=3.4,constantThree=5.6,constantFour=7.8]"+
+        ",layers=[(matrix=2x4,activation=relu),(matrix=1x2,activation=identity)]"+
+        ")\n",
+        explanation.toString());
+  }
+
+  public static class CustomNeuralNetworkModel extends NeuralNetworkModel {
+
+    public CustomNeuralNetworkModel(String name, List<Feature> features, List<Normalizer> norms,
+        String featureStoreName, List<Feature> allFeatures, Map<String,Object> params) {
+      super(name, features, norms, featureStoreName, allFeatures, params);
+    }
+
+    public class DefaultLayer extends org.apache.solr.ltr.model.NeuralNetworkModel.DefaultLayer {
+      @Override
+      public void setActivation(Object o) {
+        super.setActivation(o);
+        switch (this.activationStr) {
+          case "answer":
+            this.activation = new Activation() {
+              @Override
+              public float apply(float in) {
+                return in * 42f;
+              }
+            };
+            break;
+          default:
+            break;
+        }
+      }
+    }
+
+    @Override
+    protected Layer createLayer(Object o) {
+      final DefaultLayer layer = new DefaultLayer();
+      if (o != null) {
+        SolrPluginUtils.invokeSetters(layer, ((Map<String,Object>) o).entrySet());
+      }
+      return layer;
+    }
+
+  }
+
+  @Test
+  public void testCustom() throws Exception {
+
+    final LTRScoringModel model = createModelFromFiles("neuralnetworkmodel_custom.json",
+        "neuralnetworkmodel_features.json");
+
+    final float featureValue1 = 4f;
+    final float featureValue2 = 2f;
+    final float[] featureValues = { featureValue1, featureValue2 };
+
+    final double expectedScore = (featureValue1+featureValue2) * 42f;
+    float actualScore = model.score(featureValues);
+    assertEquals(expectedScore, actualScore, 0.001);
+
+    final List<Explanation> explanations = new ArrayList<Explanation>();
+    for (int ii=0; ii<featureValues.length; ++ii)
+    {
+      explanations.add(Explanation.match(featureValues[ii], ""));
+    }
+    final Explanation explanation = model.explain(null, 0, actualScore, explanations);
+    assertEquals(actualScore+" = (name=neuralnetworkmodel_custom"+
+        ",featureValues=[constantFour=4.0,constantTwo=2.0]"+
+        ",layers=[(matrix=1x2,activation=answer)]"+
+        ")\n",
+        explanation.toString());
+  }
+
+}

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/c5938f79/solr/solr-ref-guide/src/learning-to-rank.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/learning-to-rank.adoc b/solr/solr-ref-guide/src/learning-to-rank.adoc
index f0b3811..b692ed7 100644
--- a/solr/solr-ref-guide/src/learning-to-rank.adoc
+++ b/solr/solr-ref-guide/src/learning-to-rank.adoc
@@ -87,6 +87,7 @@ Feature selection and model training take place offline and outside Solr. The lt
 |General form |Class |Specific examples
 |Linear |{solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/LinearModel.html[LinearModel] |RankSVM, Pranking
 |Multiple Additive Trees |{solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/MultipleAdditiveTreesModel.html[MultipleAdditiveTreesModel] |LambdaMART, Gradient Boosted Regression Trees (GBRT)
+|Neural Network |{solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/NeuralNetworkModel.html[NeuralNetworkModel] |RankNet
 |(wrapper) |{solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/DefaultWrapperModel.html[DefaultWrapperModel] |(not applicable)
 |(custom) |(custom class extending {solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/AdapterModel.html[AdapterModel]) |(not applicable)
 |(custom) |(custom class extending {solr-javadocs}/solr-ltr/org/apache/solr/ltr/model/LTRScoringModel.html[LTRScoringModel]) |(not applicable)