== Dev branch           ==
This branch contains some features that are not yet checked into main branch. To enlist this branch, run 

git checkout origin/Dev 

== To-do                ==
Add descriptions to LSTMnode
Add descriptions to 0/1 mask segmentation in feature reader, delay node, and crossentropywithsoftmax node
Change criterion node to use the 0/1 mask, following example in crossentropywithsoftmax node
Add description of encoder-decoder simple network builder
Add description of time-reverse node, simple network builder and NDL builder for bi-directional models

== Author of the README ==
   	Kaisheng Yao
        Microsoft Research
        email: [email protected]

	Wengong Jin,
	Shanghai Jiao Tong University
	email: [email protected]

    Yu Zhang, Leo Liu
    CSAIL, Massachusetts Institute of Technology
    email: [email protected]
    email: [email protected]

    Guoguo Chen
    CLSP, Johns Hopkins University
    email: [email protected]

== Preeliminaries ==
To build the cpu version, you have to install intel MKL blas library or ACML library first. Note that ACML is free, where MKL may not be.

for MKL:
1. Download from https://software.intel.com/en-us/intel-mkl
2. You can modify variable MKL_PATH in makefile.cpu to change your mkl path.

for ACML:
1. Download from http://developer.amd.com/tools-and-sdks/cpu-development/amd-core-math-library-acml/
2. Modify ACML_PATH in the makefile.cpu and makefile.gpu to provide your ACML library path.

for Kaldi:
1. In kaldi-trunk/tools/Makefile, uncomment # OPENFST_VERSION = 1.4.1, and
   re-install OpenFst using the makefile.
2. In kaldi-trunk/src/, do ./configure --shared; make depend -j 8; make -j 8;
   and re-compile Kaldi (the -j option is for parallelization).

To build the gpu version, you have to install NIVIDIA CUDA first

== Build Preparation ==
Create a directory for your build.  You can create different directories for different build configuration,
for example, different directories for GPU versus CPU, debug versus release.  Each directory must have a
Config.make file in it which defines your build configuration, as follows:

ACML_PATH= path to ACML library installation
  only needed if MATHLIB=acml
MKL_PATH= path to MKL library installation
  only needed if MATHLIB=mkl
GDK_PATH= path to cuda gdk installation, so $(GDK_PATH)/include/nvidia/gdk/nvml.h exists
  defaults to /usr
BUILDTYPE= One of release or debug
  defaults to release
MATHLIB= One of acml or mkl
  defaults to acml
CUDA_PATH= Path to CUDA
  If not specified, GPU will not be enabled
KALDI_PATH= Path to Kaldi
  If not specified, Kaldi plugins will not be built

A possible configuration is to create a directory called "build" (which is ignored by .gitignore)
and create directories in build for various configurations.  The build directory can have a Paths.make
that defines the paths the various configurations will choose from.  A Config.make can include
build/Paths.make and then set CUDA_PATH, KALDI_PATH, and BUILDTYPE appropriately.

To build
make PREFIX=build_directory

  .build will contain object files, and can be deleted
  bin contains the cntk program
  lib contains libraries and plugins

  The bin and lib directories can safely be moved as long as they remain siblings.

To clean
make PREFIX=build_directory clean

== Run ==
All executables are in bin directory:
	cntk: The main executable for CNTK
	*.so: shared library for corresponding reader, these readers will be linked and loaded dynamically at runtime.

	./cntk configFile=${your cntk config file}

== Kaldi Reader ==
This is a HTKMLF reader and kaldi writer (for decode)

To build, set KALDI_PATH in your Config.make

The feature section is like:

writer=[
    writerType=KaldiReader
    readMethod=blockRandomize
    frameMode=false
    miniBatchMode=Partial
    randomize=Auto
    verbosity=1
    ScaledLogLikelihood=[
        dim=$labelDim$
        Kaldicmd="ark:-" # will pipe to the Kaldi decoder latgen-faster-mapped
        scpFile=$outputSCP$ # the file key of the features
    ]
]

== Kaldi2 Reader ==
This is a kaldi reader and kaldi writer (for decode)

To build, set KALDI_PATH in your Config.make

The features section is different:

features=[
    dim=
    rx=
    scpFile=
    featureTransform=
]

rx is a text file which contains:

    one Kaldi feature rxspecifier readable by RandomAccessBaseFloatMatrixReader.
    'ark:' specifiers don't work; only 'scp:' specifiers work.

scpFile is a text file generated by running:

    feat-to-len FEATURE_RXSPECIFIER_FROM_ABOVE ark,t:- > TEXT_FILE_NAME

    scpFile should contain one line per utterance.

    If you want to run with fewer utterances, just shorten this file.
    (It will load the feature rxspecifier but ignore utterances not present in scpFile).

featureTransform is the name of a Kaldi feature transform file:
    
    Kaldi feature transform files are used for stacking / applying transforms to features.

    An empty string (if permitted by the config file reader?) or the special string: NO_FEATURE_TRANSFORM
    says to ignore this option.

********** Labels **********

The labels section is also different.

labels=[
    mlfFile=
    labelDim=
    labelMappingFile=
]

Only difference is mlfFile. mlfFile is a different format now. It is a text file which contains:

    one Kaldi label rxspecifier readable by Kaldi's copy-post binary.