Share via

BrainScript Basic Concepts

  • Article

BrainScript--A Walk-Through

This section introduces the basic concepts of the "BrainScript" language. A new language? Don't worry & read on, it's very straight-forward.

In CNTK, custom networks are defined using the BrainScriptNetworkBuilder and described in the CNTK network description language "BrainScript." Likewise, networks descriptions are called brain scripts.

BrainScript provides a simple way to define a network in a code-like fashion, using expressions, variables, primitive and self-defined functions, nested blocks, and other well understood concepts. It looks similar to a scripting language in syntax.

OK, let's get our feet wet with a complete BrainScript example!

A Complete BrainScript Example Network Definition

The following example shows the network description of a simple Neural Network with one hidden layer and one classification layer. We will explain concepts along this example. Before you move on, maybe spend a few minutes with the example and try to guess what it means. You may find, as you read on, that you guessed most of it correctly.

BrainScriptNetworkBuilder = {   # (we are inside the train section of the CNTK config file)

    SDim = 28*28 # feature dimension
    HDim = 256   # hidden dimension
    LDim = 10    # number of classes

    # define the model function. We choose to name it 'model()'.
    model (features) = {
        # model parameters
        W0 = ParameterTensor {(HDim:SDim)} ; b0 = ParameterTensor {HDim}
        W1 = ParameterTensor {(LDim:HDim)} ; b1 = ParameterTensor {LDim}

        # model formula
        r = RectifiedLinear (W0 * features + b0) # hidden layer
        z = W1 * r + b1                          # unnormalized softmax
    }.z

    # define inputs
    features = Input {SDim}
    labels   = Input {LDim} 

    # apply model to features
    z = model (features)

    # define criteria and output(s)
    ce   = CrossEntropyWithSoftmax (labels, z)  # criterion (loss)
    errs = ErrorPrediction         (labels, z)  # additional metric
    P    = Softmax (z)     # actual model usage uses this

    # connect to the system. These five variables must be named exactly like this.
    featureNodes    = (features)
    inputNodes      = (labels)
    criterionNodes  = (ce)
    evaluationNodes = (errs)
    outputNodes     = (P)
}

BrainScript Syntax Basics

Before we dig right in, a few general notes about BrainScript's syntax.

BrainScript uses a simple syntax that is aimed at allowing to express neural networks in a way that looks like math formulas. Hence, the fundamental syntactical unit is the assignment, which is used in both variable assignments and function definitions. For example:

Softplus (x) = Log (1 + Exp (x))
h = Softplus (W * v + b)

Lines, Comments, Include

Although an assignment is typically written on a single line, expressions can span multiple lines. To put multiple assignments on a single line, however, you must separate them by a semicolon. For example:

SDim = 28*28 ; HDim = 256 ; LDim = 10    # feature, hidden, and label dimension

Other than requiring a semicolon between assignments in absence of a line break, BrainScript is not white-space sensitive.

BrainScript understands line-end comments using both Python style # and C++-style //. Inline comments use C syntax (/* this is a comment*/), but unlike C, these may not span multiple lines.

For BrainScript embedded in CNTK config files (as opposed to BrainScript read from a separate file through an include directive), due to an interaction with the config parser, there is the (somewhat strange) additional restriction that any parentheses, curly braces, or brackets must be balanced inside C/C++ style comments and string literals. Hence, no smileys in C/C++-style comments!

An include "PATH" directive may be used at any place to insert the content of a file at the point of the statement. Here, PATH can be an absolute or a relative relative path (with or without subdirectories). If it is a relative path, the following locations are searched in order: current working directory; directory(s) containing outer including files if any; directory(s) containing the config file(s); and lastly the directory containing the CNTK executable. All built-in BrainScript functions are included this way from a file called CNTK.core.bs which is located next to the CNTK executable.

Expressions

Next, you need to know about BrainScript expressions--the formulas that describe your network. BrainScript expressions are written math-like in a syntax similar to popular programming languages. The simplest expressions are literals, e.g. numbers and strings. A math-like example is W1 * r + b, where * refers to a scalar, matrix, or tensor product depending on the type of the variables. Another common kind of expression is the function invocation, e.g. RectifiedLinear (.).

BrainScript is a dynamically-typed language. An important expression type is the record, defined using the {...} syntax, and accessed through the dot syntax. For example, r = { x = 13 ; y = 42 } assigns a record with two members to r, where the first member can be accessed as r.x.

In addition to the usual math operators, BrainScript has a conditional expression (if c then t else f), an array expression, and simple lambdas. Lastly, to interface with the CNTK C++ code, BrainScript can directly instantiate a limited set of predefined C++ objects, predominantly the ComputationNode that computational networks are composed of. For more details, see Expressions.

BrainScript expressions are evaluated upon first use. The primary purpose of BrainScript is to describe the network, so the value of an expression is often not a final value, but rather a node in a computation graph for deferred computation (as in W1 * r + b). Only BrainScript expressions of scalars (e.g. 28*28) are 'computed' at the time the BrainScript is parsed. Expressions that are never used (e.g. due to a condition) are never evaluated.

Note: The now deprecated NDLNetworkBuilder version only supported function-invocation syntax; e.g., one would have to write Plus (Times (W1, r), b1).

Variables

Variables can hold the value of any BrainScript expression (number, string, record, array, lambda, CNTK C++ object), and are substituted when used in an expression. Variables are immutable, i.e. assigned only once. For example, the network definition above begins with:

SDim = 28*28  
HDim = 256
LDim = 10

Here the variables are set to scalar numeric values that are used as parameters in subsequent expressions. These values are the dimensions of the data samples, hidden layers, and labels used in training. This particular example setup is for the MNIST dataset, which is a collection of [28 x 28]-pixel images. Each image is a handwritten digit (0-9), so there are 10 possible labels that can be applied to each image. The hidden activation dimension HDim is a user choice.

Most variables are record members (the outer BrainScript block is implicitly a record). In addition, variables can be function arguments or stored as arrays elements.

OK, ready to go through the model definition.

Defining the Network

A network is primarily described by formulae of how the network's outputs are computed from the inputs. We call this the model function, which is often defined as an actual function in BrainScript. As part of the model function, the user must declare the model parameters. Lastly, one must define the network's inputs, and criteria/outputs. All of these are defined as variables. The input and criteria/output variables must then be communicated to the system.

The Network's Model Function and Model Parameters

The model function contains the actual network formulas and the respective model parameters. Our example uses matrix product and addition, and the 'primitive' (built-in) function for the energy function RectifiedLinear(), so the core of the network function consists of these equations:

r = RectifiedLinear (W0 * features + b0)
z = W1 * r + b1

Model parameters are matrices, bias vectors, or any other tensor that constitute the learned model upon completion of training. The model-parameter tensors are used in transforming the input sample data into the desired output, and are updated by the learning process. The example network above contains the following matrix parameters:

W0 = ParameterTensor {(HDim:SDim)}
b0 = ParameterTensor {(HDim)}

In this case, W0 is the weight matrix and b0 is the bias vector. ParameterTensor{} denotes a special CNTK primitive, which instantiates a vector, matrix, or arbitrary-rank tensor, and takes the dimension parameters as a BrainScript array (numbers concatenated by a colon :). A vector's dimension is a single number, while a matrix dimension should be specified as (numRows:numCols). By default, Parameters are initialized with uniform random numbers when instantiated directly, and heNormal when used through layers, but other options exist (see here) for the full list. Unlike regular functions, ParameterTensor{} takes its arguments in curly braces instead of parentheses. Curly braces are the BrainScript convention for functions that create parameters or objects, as opposed to functions.

This is then all wrapped into a BrainScript function. BrainScript functions are declared in the form f(x) = an expression of x. For example, Sqr (x) = x * x is a valid BrainScript function declaration. Could not be much simpler and direct, right?

Now, the actual model function of our example above is a bit more complex:

model (features) = {
    # model parameters
    W0 = ParameterTensor {(HDim:SDim)} ; b0 = ParameterTensor {HDim}  
    W1 = ParameterTensor {(LDim:HDim)} ; b1 = ParameterTensor {LDim}

    # model formula
    r = RectifiedLinear (W0 * features + b0) # hidden layer
    z = W1 * r + b1                          # unnormalized softmax
}.z

The outer { ... } and that final .z deserves some explanation. The outer curlies { ... } and their content actually define a record with 6 record members (W0, b0, W1, b1, r, and z). However, the model function's value is just z; all others are internal to the function. Hence, we use .z to select the record member we care to return. This is just the dot syntax for accessing record members. This way, the other record members are not accessible from outside. But they continue to exist as part of the expression to compute z. The { ... ; x = ... }.x pattern is a way of using local variables.

Note that the record syntax is not necessary. Alternatively, model(features) could also have been declared without the detour via the record, as a single expression:

model (features) = ParameterTensor {(LDim:HDim)} * (RectifiedLinear (ParameterTensor {(HDim:SDim)}
                   * features + ParameterTensor {HDim})) + ParameterTensor {LDim}

This is much harder to read, and, more importantly, will not allow to use the same parameter at multiple places in the formula.

Inputs

Inputs into the network are defined by the sample data and the labels associated with the samples:

features = Input {SDim}
labels   = Input {LDim}

Input{} is the second special CNTK primitive needed for model definition (the first being Parameter{}). It creates a variable that receives input from outside the network: from the reader. The argument of Input{} is the data dimension. In this example, the features input will have the dimensions of the sample data (which we defined in variable SDim), and the labels input will have the dimensions of the labels. The variable names of the inputs are expected to match corresponding entries in the reader definition.

Training Criteria and Network Outputs

We still need to declare how the network's output interacts with the world. Our model function computes logit values (non-normalized log probabilities). These logit values can be used to

  • define the training criterion,
  • measure accuracy, and
  • compute the probability over output classes given an input, to base a classification decision on (note that the unnormalized log posterior z can often be used for classification directly).

The example network uses category labels, which are represented as one-hot vectors. For the MNIST example these will appear as an array of 10 floating point values, all of which are zero except for the proper label category which is 1.0. Classification tasks like ours commonly use the SoftMax() function to obtain the probabilities for each label. The network is then optimized to maximize the log probability of the correct class (cross-entropy), and minimize that of all other classes. This is our training criterion, or loss function. In CNTK these two actions are typically combined in one function for efficiency:

ce = CrossEntropyWithSoftmax (labels, z)

CrossEntropyWithSoftmax() function takes the input, computes the SoftMax() function, calculates the error from the actual value using cross-entropy, and that error signal is used to update the parameters in the network via back propagation. Hence, in the example above, the normalized Softmax() value, which we computed as P, is not used during training. It will, however, be needed for using the network (again note that in many cases, z is often sufficient for classification; in that case, z itself would be the output).

CNTK uses Stochastic Gradient Descent (SGD) as the learning algorithm. SGD needs to compute the gradient of the objective function with respect to all model parameters. Importantly, CNTK does not require users to specify those gradients. Rather, each built-in function in CNTK also has a derivative counterpart function, and the system automatically performs the back propagation update of the network parameters. This is not visible to the user. Users never have to be concerned with gradients. Ever.

In addition to the training criterion, predicted error rates are often computed during the training phase to validate improvement of the system as the training is going further. This is handled in CNTK using the following function:

errs = ClassificationError (labels, z)

The probabilities produced by the network are compared to the actual label and the error rate is computed. This is generally displayed by the system. Though this is useful, it is not mandatory to use ClassificationError().

Communicating Inputs, Outputs, and Criteria to the System

Now that all variables are defined, we must tell the system which of the variables it should treat as inputs, outputs, and criteria. This is done by defining 5 special variables which must have exactly these names:

featureNodes    = (features)
labelNodes      = (labels)
criterionNodes  = (ce)
evaluationNodes = (errs)
outputNodes     = (z:P)

The values are arrays, where the values should be separated by a colon (the colon : is a BrainScript operator that forms an array by concatenating two values or arrays). This is shown above for outputNodes, which declares both z and P as outputs.

(Note: The deprecated NDLNetworkBuilder required the array elements to be separated by commas instead.)

Summary of Special Names

As we saw above, there are 7 special names we must be aware of, which carry "magic" properties:

  • ParameterTensor{}: Declares and initializes a learnable parameter.
  • Input{}: Declares a variable that gets connected and fed from a data reader.
  • featureNodes, labelNodes, criterionNodes, evaluationNodes, and outputNodes: Declares to the system which of our variables to use as inputs, outputs, and criteria.

In addition, there are 3 more special functions with built-in "magic" in CNTK, which are discussed elsewhere:

  • Constant(): Declares a constant.
  • PastValue() and FutureValue(): Access a variable in a network function at a different time step, for form recurrent loops.

Any other predefined name is either a built-in primitive function such as Sigmoid() or Convolution() with a C++ implementation, a predefined library function realized in BrainScript such as BS.RNNs.LSTMP(), or a record that acts as a namespace for library functions (e.g. BS.RNNs). See BrainScript-Full-Function-Reference for a full list.

Next: BrainScript Expressions