#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the Common Development
# and Distribution License Version 1.0 (the "License").
#
# You can obtain a copy of the license at
# http://www.opensource.org/licenses/CDDL-1.0.  See the License for the
# specific language governing permissions and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each file and
# include the License file in a prominent location with the name LICENSE.CDDL.
# If applicable, add the following below this CDDL HEADER, with the fields
# enclosed by brackets "[]" replaced with your own identifying information:
#
# Portions Copyright (c) [yyyy] [name of copyright owner]. All rights reserved.
#
# CDDL HEADER END
#

#
# Copyright (c) 2019, Regents of the University of Minnesota.
#
# Contributors:
#    Mingjian Wen
#


This directory contains a model driver for neural network (NN) potential, which
supports both fully-connected NN potential and the dropout uncertainty neural
network (DUNN) potential.

1. Three parameter files are needed:

   descriptor.params: atomic environment descriptor hyperparameters, cutoffs,
   species.

   NN.params: definition of the neural network (number of layers, number of
   nodes in each layer, activation function), dropout ratio, and the weights and
   biases in each layer.

   dropout_binary.params: predefined dropout matrix. For a fully-connected NN
   potential (no dropout), "0" should be given as the only content of this file.

   These files can be automatically generated by the KLIFF fitting package (https://kliff.readthedocs.io).


2. The driver publish two parameters:

   ensemble_size: the size of the dropout ensemble.
   If 0, this model will run in fully-connected mode, and "active_member_id" is
   ignored. If positive, the running mode depends on "active_member_id".

   active_member_id: determines the running mode when "ensemble_size" is
   positive.
   If [1, ensemble_size], using a single ensemble member;
   If 0, run in fully-connected mode;
   If -1, run in averaging mode, i.e. the output (energy, forces, virial,
   particle virial) is the mean of ensemble.


3. The following files are included in this directory:

   ANN.hpp, ANN.cpp:
      implementation wrapper of the driver
   ANNImplementation.hpp, ANNImplementation.cpp:
      implementation of the driver
   descriptor.h, descriptor.cpp:
      atomic environment descriptor
   network.h, network.cpp:
      feed-forward neural network
   helper.hpp, helper.cpp:
      help functions to manage memory and compute virial
   eigen-v3.3.7.tar.xz:
      the Eigen matrix operation library
   ANNImplementationComputeDispatch.cpp
      helper function


References:

1. M. Wen and E. B. Tadmor, "Uncertainty quantification in molecular simulations
with dropout neural network potentials," submitted, 2019.