一段关于神经网络的故事

def affine_forward(x, w, b):
    """
    Inputs:
    - x: A numpy array containing input data, of shape (N, d_1, ..., d_k)
    - w: A numpy array of weights, of shape (D, M) 权重
    - b: A numpy array of biases, of shape (M,) 偏置
    Returns a tuple of:
    - out: output, of shape (N, M)
    - cache: (x, w, b)
    """
  out = None                    # 初始化
  reshaped_x = np.reshape(x, (x.shape[0],-1))   # 确保x是一个规整的矩阵
  out = reshape_x.dot(w) +b     # out = w x +b
  cache = (x, w, b)            # 将该函数的输入值缓冲储存起来，以备他用
  return out, cache

def relu_forward(x):
    """
    Computes the forward pass for a layer of rectified linear units (ReLUs).
    Input:
    - x: Inputs, of any shape
    Returns a tuple of:
    - out: Output, of the same shape as x
    - cache: x
    """
    out = np.maximum(0, x)    # 取x中每个元素和0做比较
    cache = x                 # 缓冲输入进来的x矩阵
    return out, cache

def affine_relu_forward(x, w, b):
    """
    Convenience layer that perorms an affine transform followed by a ReLU

    Inputs:
    - x: Input to the affine layer
    - w, b: Weights for the affine layer

    Returns a tuple of:
    - out: Output from the ReLU
    - cache: Object to give to the backward pass
    """
    a, fc_cache = affine_forward(x, w, b) # 线性模型
    out, relu_cache = relu_forward(a)     # 激活函数
    cache = (fc_cache, relu_cache)        # 缓冲的是元组：(x, w, b, (a))
    return out, cache

def softmax_loss(x, y):
    """
    Computes the loss and gradient for softmax classification.
    Inputs:
    - x: Input data, of shape (N, C) where x[i, j] is the score for the jth class
      for the ith input.
    - y: Vector of labels, of shape (N,) where y[i] is the label for x[i] and
      0 <= y[i] < C
    Returns a tuple of:
    - loss: Scalar giving the loss
    - dx: Gradient of the loss with respect to x
    """
    probs = np.exp(x - np.max(x, axis=1, keepdims=True))    # 1
    probs /= np.sum(probs, axis=1, keepdims=True)           # 2
    N = x.shape[0]                                          # 3
    loss = -np.sum(np.log(probs[np.arange(N), y])) / N      # 4
    dx = probs.copy()
    dx[np.arange(N), y] -= 1
    dx /= N
    return loss, dx

def softmax_loss(x, y):
    """
    Computes the loss and gradient for softmax classification.
    Inputs:
    - x: Input data, of shape (N, C) where x[i, j] is the score for the jth class
      for the ith input.
    - y: Vector of labels, of shape (N,) where y[i] is the label for x[i] and
      0 <= y[i] < C
    Returns a tuple of:
    - loss: Scalar giving the loss
    - dx: Gradient of the loss with respect to x, of shape (N, C)
    """
    probs = np.exp(x - np.max(x, axis=1, keepdims=True))
    probs /= np.sum(probs, axis=1, keepdims=True)
    N = x.shape[0]
    loss = -np.sum(np.log(probs[np.arange(N), y])) / N
    dx = probs.copy()         # 1 probs.copy() 表示获得变量probs的副本
    dx[np.arange(N), y] -= 1  # 2 
    dx /= N                   # 3
    return loss, dx

def affine_backward(dout, cache):
    """
    Computes the backward pass for an affine layer.
    Inputs:
    - dout: Upstream derivative, of shape (N, M)    上一层的散度输出
    - cache: Tuple of:
    - x: Input data, of shape (N, d_1, ... d_k)
    - w: Weights, of shape (D, M)
    - b: biases, of shape (M,) 
    Returns a tuple of:
    - dx: Gradient with respect to x, of shape (N, d1, ..., d_k)
    - dw: Gradient with respect to w, of shape (D, M)
    - db: Gradient with respect to b, of shape (M,)
    """
    x, w, b = cache
    dx, dw, db = None, None, None
    reshaped_x = np.reshape(x, (x.shape[0], -1))
    dx = np.reshape(dout.dot(w.T), x.shape)   # np.dot() 是矩阵乘法
    dw = (reshaped_x.T).dot(dout)
    db = np.sum(dout, axis=0)
    return dx, dw, db

dx = np.reshape(dout.dot(w.T), x.shape)
dw = (reshaped_x.T).dot(dout) 
db = np.sum(dout, axis=0)

  def relu_backward(dout, cache):
    """
    Computes the backward pass for a layer of rectified linear units (ReLUs).
    Input:
    - dout: Upstream derivatives, of any shape
    - cache: Input x, of same shape as dout
    Returns:
    - dx: Gradient with respect to x
    """
    dx, x = None, cache
    dx = (x > 0) * dout    
    # 与所有x中元素为正的位置处，位置对应于dout矩阵的元素保留，其他都取0
    return dx
  
  def affine_relu_backward(dout, cache):
    """
    Backward pass for the affine-relu convenience layer
    """
    fc_cache, relu_cache = cache            # fc_cache = (x, w, b)   relu_cache = a
    da = relu_backward(dout, relu_cache)    # da = (x > 0) * relu_cache
    dx, dw, db = affine_backward(da, fc_cache)
    return dx, dw, db

loss += 0.5 * self.reg * (np.sum(self.params["W1"] ** 2) + \
                                  np.sum(self.params["W2"] ** 2))
dW2 += self.reg * self.params["W2"]
dW1 += self.reg * self.params["W1"]

def batchnorm_forward(x, gamma, beta, bn_param):
    """
        During training the sample mean and (uncorrected) sample variance are
    computed from minibatch statistics and used to normalize the incoming data.
    During training we also keep an exponentially decaying running mean of the mean
    and variance of each feature, and these averages are used to normalize data
    t test-time.

    At each timestep we update the running averages for mean and variance using
    an exponential decay based on the momentum parameter:

    running_mean = momentum * running_mean + (1 - momentum) * sample_mean
    running_var = momentum * running_var + (1 - momentum) * sample_var

    Note that the batch normalization paper suggests a different test-time
    behavior: they compute sample mean and variance for each feature using a
    large number of training images rather than using a running average. For
    this implementation we have chosen to use running averages instead since
    they do not require an additional estimation step; the torch7 implementation
    of batch normalization also uses running averages.
    
    Input:
    - x: Data of shape (N, D)
    - gamma: Scale parameter of shape (D,)
    - beta: Shift paremeter of shape (D,)
    - bn_param: Dictionary with the following keys:
    - mode: 'train' or 'test'; required
    - eps: Constant for numeric stability
    - momentum: Constant for running mean / variance.
    - running_mean: Array of shape (D,) giving running mean of features
    - running_var Array of shape (D,) giving running variance of features

    Returns a tuple of:
    - out: of shape (N, D)
    - cache: A tuple of values needed in the backward pass
    """
    mode = bn_param['mode']
    eps = bn_param.get('eps', 1e-5)
    momentum = bn_param.get('momentum', 0.9)

    N, D = x.shape
    running_mean = bn_param.get('running_mean', np.zeros(D, dtype=x.dtype))
    running_var = bn_param.get('running_var', np.zeros(D, dtype=x.dtype))

    out, cache = None, None
    if mode == 'train':     # 训练模式
        sample_mean = np.mean(x, axis=0)  # 矩阵x每一列的平均值 shaple: (D,)
        sample_var = np.var(x, axis=0)    # 矩阵x每一列的方差 shape: (D,)
        x_hat = (x - sample_mean) / (np.sqrt(sample_var + eps))
        out = gamma * x_hat + beta
        cache = (x, sample_mean, sample_var, x_hat, eps, gamma, beta)
        running_mean = momentum * running_mean + (1 - momentum) * sample_mean
        running_var = momentum * running_var + (1 - momentum) * sample_var

    elif mode == 'test':    # 测试模式
        out = (x - running_mean) * gamma / (np.sqrt(running_var + eps)) + beta
    else:
        raise ValueError('Invalid forward batchnorm mode "%s"' % mode)

    # Store the updated running means back into bn_param
    bn_param['running_mean'] = running_mean
    bn_param['running_var'] = running_var
    
    return out, cache

def affine_bn_relu_forward(x, w, b, gamma, beta, bn_param):
    """
    Inputs:
    - x: Array of shape (N, D1); input to the affine layer
    - w, b: Arrays of shape (D2, D2) and (D2,) giving the weight and bias for
      the affine transform.
    - gamma, beta: Arrays of shape (D2,) and (D2,) giving scale and shift
      parameters for batch normalization.
    - bn_param: Dictionary of parameters for batch normalization.
    Returns:
    - out: Output from ReLU, of shape (N, D2)
    - cache: Object to give to the backward pass.
    """
    a, fc_cache = affine_forward(x, w, b)
    a_bn, bn_cache = batchnorm_forward(a, gamma, beta, bn_param) # BN层
    out, relu_cache = relu_forward(a_bn)    # ReLU层
    cache = (fc_cache, bn_cache, relu_cache)
    return out, cache

def batchnorm_backward(dout, cache):
    """
    Inputs:
    - dout: Upstream derivatives, of shape (N, D)
    - cache: Variable of intermediates from batchnorm_forward.
    Returns a tuple of:
    - dx: Gradient with respect to inputs x, of shape (N, D)
    - dgamma: Gradient with respect to scale parameter gamma, of shape (D,)
    - dbeta: Gradient with respect to shift parameter beta, of shape (D,)
    """
    x, mean, var, x_hat, eps, gamma, beta = cache
    N = x.shape[0]
    dgamma = np.sum(dout * x_hat, axis=0) # 第5行公式
    dbeta = np.sum(dout * 1.0, axis=0)    # 第6行公式
    dx_hat = dout * gamma                 # 第1行公式
    dx_hat_numerator = dx_hat / np.sqrt(var + eps)            # 第3行第1项(未负求和)
    dx_hat_denominator = np.sum(dx_hat * (x - mean), axis=0)  # 第2行前半部分
    dx_1 = dx_hat_numerator               # 第4行第1项
    dvar = -0.5 * ((var + eps) ** (-1.5)) * dx_hat_denominator   # 第2行公式
    # Note var is also a function of mean
    dmean = -1.0 * np.sum(dx_hat_numerator, axis=0) + \
              dvar * np.mean(-2.0 * (x - mean), axis=0)       # 第3行公式(部分)
    dx_var = dvar * 2.0 / N * (x - mean)  # 第4行第2项
    dx_mean = dmean * 1.0 / N             # 第4行第3项
    # with shape (D,), no trouble with broadcast
    dx = dx_1 + dx_var + dx_mean          # 第4行公式

    return dx, dgamma, dbeta

def affine_bn_relu_backward(dout, cache):
    """
    Backward pass for the affine-batchnorm-relu convenience layer.
    """
    fc_cache, bn_cache, relu_cache = cache
    da_bn = relu_backward(dout, relu_cache)                    # ReLU层
    da, dgamma, dbeta = batchnorm_backward(da_bn, bn_cache)   # BN层
    dx, dw, db = affine_backward(da, fc_cache)
    return dx, dw, db, dgamma, dbeta

def dropout_forward(x, dropout_param):
    """
    Performs the forward pass for (inverted) dropout.
    Inputs:
    - x: Input data, of any shape
    - dropout_param: A dictionary with the following keys:
    - p: Dropout parameter. We drop each neuron output with probability p.
    - mode: 'test' or 'train'. If the mode is train, then perform dropout;
      if the mode is test, then just return the input.
    - seed: Seed for the random number generator. Passing seed makes this
      function deterministic, which is needed for gradient checking but not in
      real networks.
    Outputs:
    - out: Array of the same shape as x.
    - cache: A tuple (dropout_param, mask). In training mode, mask is the dropout
      mask that was used to multiply the input; in test mode, mask is None.
    """
    p, mode = dropout_param['p'], dropout_param['mode']
    if 'seed' in dropout_param:
        np.random.seed(dropout_param['seed'])

    mask = None
    out = None
    # 训练模式
    if mode == 'train':
        keep_prob = 1 - p
        mask = (np.random.rand(*x.shape) < keep_prob) / keep_prob
        out = mask * x
    # 测试模式
    elif mode == 'test':
        out = x

    cache = (dropout_param, mask)
    out = out.astype(x.dtype, copy=False)

    return out, cache

def dropout_backward(dout, cache):
    """
    Perform the backward pass for (inverted) dropout.
    Inputs:
    - dout: Upstream derivatives, of any shape
    - cache: (dropout_param, mask) from dropout_forward.
    """
    dropout_param, mask = cache
    mode = dropout_param['mode']
  
    dx = None
    if mode == 'train':
        dx = mask * dout
        
    elif mode == 'test':
        dx = dout
    return dx

class FullyConnectedNet(object):
    """
    一个任意隐藏层数和神经元数的全连接神经网络，其中 ReLU 激活函数，sofmax 损失函数，同时可选的
    采用 dropout 和 batch normalization(批量归一化)。那么，对于一个L层的神经网络来说，其
    框架是：  
    
    {affine - [batch norm] - relu - [dropout]} x (L - 1) - affine - softmax
    
    其中的[batch norm]和[dropout]是可选非必须的，框架中{...}部分将会重复L-1次，代表L-1 个隐藏层。

    与我们在上面的故事中定义的 TwoLayerNet() 类保持一致，所有待学习的参数都会存在 
    self.params 字典中，并且最终会被最优化 Solver() 类训练学习得到(后面的故事会谈到)。
    """


    #1# 第一步是初始化我们的 FullyConnectedNet() 类：
    def __init__(self
                 ,hidden_dims       # 一个列表，元素个数是隐藏层数，元素值为该层神经元数
                 ,input_dim=3*32*32 # 默认输入神经元的个数是3072个(匹配CIFAR-10数据集)
                 ,num_classes=10    # 默认输出神经元的个数是10个(匹配CIFAR-10数据集)
                 ,dropout=0         # 默认不开启dropout，若取(0,1)表示失活概率
                 ,use_batchnorm=False # 默认不开启批量归一化，若开启取True
                 ,reg=0.0           # 默认无L2正则化，取某scalar表示正则化的强度
                 ,weight_scale=1e-2 # 默认0.01，表示权重参数初始化的标准差
                 ,dtype=np.float64  # 默认np.float64精度，要求所有的计算都应该在此精度下。
                 ,seed=None):       # 默认无随机种子，若有会传递给dropout层。


        # 实例(Instance)中增加变量并赋予初值，以方便后面的 loss() 函数调用：
        self.use_batchnorm = use_batchnorm
        self.use_dropout = dropout > 0    # 可见，若dropout若为0时，为False
        self.reg = reg
        self.num_layers = 1 + len(hidden_dims)    
        # 在loss()函数里, 我们用神经网络的层数来标记规模
        self.dtype = dtype
        self.params = {}            # self.params 空字典保存待训练学习的参数


        # 定义所有隐藏层的参数到字典 self.params 中：
        in_dim = input_dim  # Eg: in_dim = D
        for i, h_dim in enumerate(hidden_dims): # Eg:(i, h_dim)=(0, H1)、(1, H2)...
            # Eg: W1(D, H1)、W2(H1, H2)...    小随机数为初始值
            self.params["W%d" % (i+1,)] = weight_scale * \
                                          np.random.randn(in_dim
                                                         ,h_dim)
            # Eg: b1(H1,)、b2(H2,)...         0为初始值
            self.params["b%d" % (i+1,)] = np.zeros((h_dim,))
            if use_batchnorm:    # 若有批量归一化层
                # Eg: gamma1(H1,)、gamma2(H2,)... 1为初始值
                # Eg: beta1(H1,)、beta2(H2)...    0为初始值
                self.params["gamma%d" % (i+1,)] = np.ones((h_dim,))
                self.params["beta%d" % (i+1,)] = np.zeros((h_dim,))
            in_dim = h_dim      # 将该隐藏层的列数传递给下一层的行数


        # 定义输出层的参数到字典 params 中：
        self.params["W%d" % (self.num_layers,)] = weight_scale * \
                                                np.random.randn(in_dim
                                                                ,num_classes)
        self.params["b%d" % (self.num_layers,)] = np.zeros((num_classes,))


        """
        当开启 dropout 时，我们需要在每一个神经元层中传递一个相同的
        dropout 参数字典 self.dropout_param ，以保证每一层的神经元们
        都知晓失活概率p和当前神经网络的模式状态mode(训练／测试)。        
        """
        self.dropout_param = {} # dropout的参数字典
        if self.use_dropout:    # 如果use_dropout的值是(0,1)，即启用dropout
            # 设置mode默认为训练模式，取p为失活概率
            self.dropout_param = {'mode': 'train', 'p': dropout}
        if seed is not None:    # 如果有seed随机种子，存入seed
            self.dropout_param['seed'] = seed


        """
        当开启批量归一化时，我们要定义一个BN算法的参数列表 self.bn_params ，
        以用来跟踪记录每一层的平均值和标准差。其中，第0个元素 self.bn_params[0] 
        表示正向传播第1个BN层的参数，第1个元素 self.bn_params[1] 表示正向传播
        第2个BN层的参数，以此类推。
        """
        self.bn_params = []     # BN算法的参数列表
        if self.use_batchnorm:  # 如果开启批量归一化，设置每层mode默认为训练模式
            self.bn_params = [{'mode': 'train'} for i in range(self.num_layers - 1)] 
            # 上面 self.bn_params 列表的元素个数是hidden layers的个数


        # 最后，调整所有的待学习神经网络参数为指定计算精度：np.float64
        for k, v in self.params.items():
            self.params[k] = v.astype(dtype)


    #2# 第二步是定义我们的损失函数：
    def loss(self, X, y=None):
        """
        和 TwoLayerNet() 一样：
        首先，输入的数据X是一个多维的array，shape为(样本图片的个数N*3*32*32),
        y是与输入数据X对应的正确标签，shape为(N,)。
        # 在训练模式下：#
        我们loss函数目标输出一个损失值loss和一个grads字典，
        其中存有loss关于隐藏层和输出层的参数(W,B,gamma,beta)的梯度值.
        # 在测试模式下：#
        我们的loss函数只需要直接给出输出层后的得分即可。
        """


        # 把输入数据源矩阵X的精度调整一下
        X = X.astype(self.dtype)
        # 根据正确标签y是否为None来调整模式是test还是train
        mode = 'test' if y is None else 'train'   


        """
        确定了当前神经网络所处的模式状态后，
        就可以设置 dropout 的参数字典和 BN 算法的参数列表中的mode了，
        因为他们在不同的模式下行为是不同的。
        """
        if self.dropout_param is not None:  # 如果开启dropout
            self.dropout_param['mode'] = mode
        if self.use_batchnorm:              # 如果开启批量归一化
            for bn_param in self.bn_params:
                bn_param['mode'] = mode


        scores = None


        """
        %正向传播%
        如果开启了dropout，我们需要将dropout的参数字典 self.dropout_param 
        在每一个dropout层中传递。
        如果开启了批量归一化，我们需要指定BN算法的参数列表 self.bn_params[0]
        对应正向传播第一层的参数，self.bn_params[1]对应第二层的参数，以此类推。
        """
        fc_mix_cache = {}       # 初始化每层正向传播的缓冲字典
        if self.use_dropout:    # 如果开启了dropout，初始化其对应的缓冲字典
            dp_cache = {}


        # 从第一个隐藏层开始循环每一个隐藏层，传递数据out，保存每一层的缓冲cache
        out = X
        for i in range(self.num_layers - 1):  # 在每个hidden层中循环
            w, b = self.params["W%d" % (i + 1,)], self.params["b%d" % (i + 1,)] 
            if self.use_batchnorm:    # 若开启批量归一化
                gamma = self.params["gamma%d" % (i + 1,)]
                beta = self.params["beta%d" % (i + 1,)]
                out, fc_mix_cache[i] = affine_bn_relu_forward(out, w, b
                                                              ,gamma
                                                              ,beta
                                                              ,self.bn_params[i])
            else:                     # 若未开启批量归一化
                out, fc_mix_cache[i] = affine_relu_forward(out, w, b)
            if self.use_dropout:      # 若开启dropout
                out, dp_cache[i] = dropout_forward(out, self.dropout_param)
        # 最后的输出层
        w = self.params["W%d" % (self.num_layers,)]
        b = self.params["b%d" % (self.num_layers,)]
        out, out_cache = affine_forward(out, w, b)
        scores = out
        """
        可以看到，上面对隐藏层的每次循环中，out变量实现了自我迭代更新；
        fc_mix_cache 缓冲字典中顺序地存储了每个隐藏层的得分情况和模型参数(其中可内含BN层)；
        dp_cache 缓冲字典中单独顺序地保存了每个dropout层的失活概率和遮罩；
        out_cache 变量缓存了输出层处的信息；
        值得留意的是，若开启批量归一化的话，BN层的参数列表 self.bn_params[i]，
        从第一层开始多出'running_mean'和'running_var'的键值保存在参数列表的每一个元素中，
        形如：[{'mode': 'train','running_mean': ***,'running_var':***},{...}]
        """


        # 接下来开始让loss函数区分不同模式：
        if mode == 'test':  # 若是测试模式，输出scores表示预测的每个分类概率后，函数停止跳出。
            return scores


        """
        %反向传播%
        既然运行到了这里，说明我们的神经网络是在训练模式下了，
        接下来我们要计算损失值，并且通过反向传播，计算损失函数关于模型参数的梯度！
        """
        loss, grads = 0.0, {} # 初始化 loss 变量和梯度字典 grads
        loss, dout = softmax_loss(scores, y)
        loss += 0.5 * self.reg * np.sum(self.params["W%d" % (self.num_layers,)]**2)
        """
        你可能奇怪上面的loss损失值是不是有问题，还有其他隐藏层的权重矩阵的正则化呢？
        别着急，我们要loss损失值的求解，跟随梯度的反向传播一点一点的算出来～
        """
        # 在输出层处梯度的反向传播，顺便把梯度保存在梯度字典 grad 中：
        dout, dw, db = affine_backward(dout, out_cache)
        grads["W%d" % (self.num_layers,)] = dw + self.reg * \
                                            self.params["W%d" % (self.num_layers,)]
        grads["b%d" % (self.num_layers,)] = db
        # 在每一个隐藏层处梯度的反向传播，不仅顺便更新了梯度字典 grad，还迭代算出了损失值loss:
        for i in range(self.num_layers - 1):
            ri = self.num_layers - 2 - i    # 倒数第ri+1隐藏层
            # 迭代地补上每层的正则项给loss
            loss += 0.5 * self.reg * \
                      np.sum(self.params["W%d" % (ri+1,)]**2)
            if self.use_dropout:    # 若开启dropout
                dout = dropout_backward(dout, dp_cache[ri])
            if self.use_batchnorm:  # 若开启批量归一化
                dout, dw, db, dgamma, dbeta = affine_bn_relu_backward(dout, 
                                                            fc_mix_cache[ri])
                grads["gamma%d" % (ri+1,)] = dgamma
                grads["beta%d" % (ri+1,)] = dbeta
            else:   # 若未开启批量归一化
                dout, dw, db = affine_relu_backward(dout, fc_mix_cache[ri])
            grads["W%d" % (ri+1,)] = dw + self.reg * self.params["W%d" % (ri+1,)]
            grads["b%d" % (ri+1,)] = db

        return loss, grads  # 输出训练模式下的损失值和损失函数的梯度！

def sgd(w, dw, config=None):
    """
    Performs vanilla stochastic gradient descent.
    config format:
    - learning_rate: Scalar learning rate.
    """
    if config is None: config = {}
    config.setdefault('learning_rate', 1e-2)

    w -= config['learning_rate'] * dw
    return w, config

def sgd_momentum(w, dw, config=None):
    """
    Performs stochastic gradient descent with momentum.
    config format:
    - learning_rate: Scalar learning rate.
    - momentum: Scalar between 0 and 1 giving the momentum value.
      Setting momentum = 0 reduces to sgd.
    - velocity: A numpy array of the same shape as w and dw used to store a
      moving average of the gradients.
    """
    if config is None: config = {}
    config.setdefault('learning_rate', 1e-2)
    config.setdefault('momentum', 0.9)
    v = config.get('velocity', np.zeros_like(w))
    next_w = None

    v = config["momentum"] * v - config["learning_rate"] * dw
    next_w = w + v
    config['velocity'] = v

    return next_w, config

# Load the (preprocessed) CIFAR10 data.
data = get_CIFAR10_data()
for k, v in data.items():
    print('%s: ' % k, v.shape)
"""
y_train:  (49000,)
y_test:  (1000,)
X_val:  (1000, 3, 32, 32)
y_val:  (1000,)
X_test:  (1000, 3, 32, 32)
X_train:  (49000, 3, 32, 32)
"""

import numpy as np
# 我们把优化算法的函数 sgd() 和 sgd_momentum() 定义在当前目录中的 optim.py 文件中
import optim

class Solver(object):
    """
    我们定义的这个Solver类将会根据我们的神经网络模型框架——FullyConnectedNet()类，
    在数据源的训练集部分和验证集部分中，训练我们的模型，并且通过周期性的检查准确率的方式，
    以避免过拟合。
    
    在这个类中，包括__init__()，共定义5个函数，其中只有train()函数是最重要的。调用
    它后，会自动启动神经网络模型优化程序。
    
    训练结束后，经过更新在验证集上优化后的模型参数会保存在model.params中。此外，损失值的
    历史训练信息会保存在solver.loss_history中，还有solver.train_acc_history和
    solver.val_acc_history中会分别保存训练集和验证集在每一次epoch时的模型准确率。
    ===============================
    下面是给出一个Solver类使用的实例：
    data = {
        'X_train': # training data
        'y_train': # training labels
        'X_val': # validation data
    '   y_val': # validation labels
        } # 以字典的形式存入训练集和验证集的数据和标签
    model = FullyConnectedNet(hidden_size=100, reg=10) # 我们的神经网络模型
    solver = Solver(model, data,        # 模型／数据
                  update_rule='sgd',    # 优化算法
                  optim_config={        # 该优化算法的参数
                    'learning_rate': 1e-3,  # 学习率
                  },
                  lr_decay=0.95,        # 学习率的衰减速率
                  num_epochs=10,        # 训练模型的遍数
                  batch_size=100,       # 每次丢入模型训练的图片数目
                  print_every=100)
    solver.train()
    ===============================    
    # 神经网络模型中必须要有两个函数方法：模型参数model.params和损失函数model.loss(X, y)
    A Solver works on a model object that must conform to the following API:
    - model.params must be a dictionary mapping string parameter names to numpy
        arrays containing parameter values. # 
    - model.loss(X, y) must be a function that computes training-time loss and
        gradients, and test-time classification scores, with the following inputs
        and outputs:
    Inputs:   # 全局的输入变量
    - X: Array giving a minibatch of input data of shape (N, d_1, ..., d_k)
    - y: Array of labels, of shape (N,) giving labels for X where y[i] is the
      label for X[i].
    Returns:  # 全局的输出变量
    # 用标签y的存在与否标记训练mode还是测试mode
    If y is None, run a test-time forward pass and return: # 
    - scores: Array of shape (N, C) giving classification scores for X where
      scores[i, c] gives the score of class c for X[i].
    If y is not None, run a training time forward and backward pass and return
    a tuple of:
    - loss: Scalar giving the loss # 损失函数值
    - grads: Dictionary with the same keys as self.params mapping parameter
      names to gradients of the loss with respect to those parameters.# 模型梯度
    """


    #1# 初始化我们的 Slover() 类：
    def __init__(self, model, data, **kwargs):
        """
        Construct a new Solver instance.
        # 必须要输入的函数参数：模型和数据
        Required arguments:
        - model: A model object conforming to the API described above
        - data: A dictionary of training and validation data with the following:
            'X_train': Array of shape (N_train, d_1, ..., d_k) giving training images
            'X_val': Array of shape (N_val, d_1, ..., d_k) giving validation images
            'y_train': Array of shape (N_train,) giving labels for training images
            'y_val': Array of shape (N_val,) giving labels for validation images
        # 可选的输入参数：
        Optional arguments:
          # 优化算法：默认为sgd
        - update_rule: A string giving the name of an update rule in optim.py.
          Default is 'sgd'.
          # 设置优化算法的超参数：
        - optim_config: A dictionary containing hyperparameters that will be
          passed to the chosen update rule. Each update rule requires different
          hyperparameters (see optim.py) but all update rules require a
          'learning_rate' parameter so that should always be present. 
          # 学习率在每次epoch时衰减率
        - lr_decay: A scalar for learning rate decay; after each epoch the learning
          rate is multiplied by this value.
          # 在训练时，模型输入层接收样本图片的大小，默认100
        - batch_size: Size of minibatches used to compute loss and gradient during
          training.
          # 在训练时，让神经网络模型一次全套训练的遍数
        - num_epochs: The number of epochs to run for during training.
          # 在训练时，打印损失值的迭代次数
        - print_every: Integer; training losses will be printed every print_every
          iterations.
          # 是否在训练时输出中间过程
        - verbose: Boolean; if set to false then no output will be printed during
          training.
        """
        # 实例(Instance)中增加变量并赋予初值，以方便后面的 train() 函数等调用：
        self.model = model                    # 模型
        self.X_train = data["X_train"]        # 训练样本图片数据
        self.y_train = data["y_train"]        # 训练样本图片的标签
        self.X_val, self.y_val = data["X_val"], data["y_val"] # 验证样本图片的数据和标签
        """
        以下是可选择输入的类参数，逐渐一个一个剪切打包kwargs参数列表
        """
        self.update_rule = kwargs.pop('update_rule', 'sgd') # 默认优化算法sgd
        self.optim_config = kwargs.pop('optim_config', {})  # 默认设置优化算法为空字典
        self.lr_decay = kwargs.pop('lr_decay', 1.0)         # 默认学习率不衰减
        self.batch_size = kwargs.pop('batch_size', 100)     # 默认输入层神经元数100
        self.num_epochs = kwargs.pop('num_epochs', 10)      # 默认神经网络训练10遍

        self.print_every = kwargs.pop('print_every', 10)
        self.verbose = kwargs.pop('verbose', True)          # 默认打印训练的中间过程
        """ 
        异常处理：如果kwargs参数列表中除了上述元素外还有其他的就报错！
        """
        if len(kwargs) > 0:
            extra = ', '.join('"%s"' % k for k in kwargs.keys())
            raise ValueError('Unrecognized arguments %s' % extra)
        """ 
        异常处理：如果kwargs参数列表中没有优化算法，就报错！
        将self.update_rule转化为优化算法的函数，即:
        self.update_rule(w, dw, config) = (next_w, config)
        """
        if not hasattr(optim, self.update_rule):  # 若optim.py中没有写好的优化算法对应
            raise ValueError('Invalid update_rule "%s"' % self.update_rule)
        self.update_rule = getattr(optim, self.update_rule)
        # 执行_reset()函数：
        self._reset()


    #2# 定义我们的 _reset() 函数，其仅在类初始化函数 __init__() 中调用
    def _reset(self):
        """
        重置一些用于记录优化的变量
        """
        # Set up some variables for book-keeping
        self.epoch = 0
        self.best_val_acc = 0
        self.best_params = {}
        self.loss_history = []
        self.train_acc_history = []
        self.val_acc_history = []
        # Make a deep copy of the optim_config for each parameter
        self.optim_configs = {}
        for p in self.model.params:
            d = {k: v for k, v in self.optim_config.items()}
            self.optim_configs[p] = d
        """ 上面根据模型中待学习的参数，创建了新的优化字典self.optim_configs，
        形如：{'b': {'learnning_rate': 0.0005}
             ,'w': {'learnning_rate': 0.0005}}，为每个模型参数指定了相同的超参数。
        """


    #3# 定义我们的 _step() 函数，其仅在 train() 函数中调用
    def _step(self):
        """
        训练模式下，样本图片数据的一次正向和反向传播，并且更新模型参数一次。
        """
        # Make a minibatch of training data # 输入数据准备
        num_train = self.X_train.shape[0]   # 要训练的数据集总数
        batch_mask = np.random.choice(num_train, self.batch_size)
        X_batch = self.X_train[batch_mask]  # 随机取得输入神经元个数的样本图片数据
        y_batch = self.y_train[batch_mask]  # 随机取得输入神经元个数的样本图片标签


        # Compute loss and gradient         # 数据通过神经网络后得到损失值和梯度字典
        loss, grads = self.model.loss(X_batch, y_batch)
        self.loss_history.append(loss)      # 把本次算得的损失值记录下来


        # Perform a parameter update  # 执行一次模型参数的更新
        for p, w in self.model.params.items():
            dw = grads[p]             # 取出模型参数p对应的梯度值
            config = self.optim_configs[p]    # 取出模型参数p对应的优化超参数
            next_w, next_config = self.update_rule(w, dw, config) # 优化算法
            self.model.params[p] = next_w     # 新参数替换掉旧的
            self.optim_configs[p] = next_config   # 新超参数替换掉旧的


    #4# 定义我们的 check_accuracy() 函数，其仅在 train() 函数中调用
    def check_accuracy(self, X, y, num_samples=None, batch_size=100):
        """
        根据某图片样本数据，计算某与之对应的标签的准确率
        Inputs:
        - X: Array of data, of shape (N, d_1, ..., d_k)
        - y: Array of labels, of shape (N,)
        - num_samples: If not None, subsample the data and only test the model
          on num_samples datapoints.
        - batch_size: Split X and y into batches of this size to avoid using too
          much memory.
      
        Returns:
        - acc: Scalar giving the fraction of instances that were correctly
          classified by the model.
        """
    
        # Maybe subsample the data
        N = X.shape[0]    # 样本图片X的总数
        if num_samples is not None and N > num_samples:
            mask = np.random.choice(N, num_samples)
            N = num_samples
            X = X[mask]
            y = y[mask]

        # Compute predictions in batches
        num_batches = N // batch_size
        if N % batch_size != 0:
            num_batches += 1
        y_pred = []
        for i in range(num_batches):
            start = i * batch_size
            end = (i + 1) * batch_size
            scores = self.model.loss(X[start:end])
            y_pred.append(np.argmax(scores, axis=1))
        y_pred = np.hstack(y_pred)
        acc = np.mean(y_pred == y)

        return acc

    #5# 定义我们最重要的 train() 函数
    def train(self):
        """
        首先要确定下来总共要进行的迭代的次数num_iterations，
        """
        num_train = self.X_train.shape[0] # 全部要用来训练的样本图片总数
        iterations_per_epoch = max(num_train // self.batch_size, 1) # 每遍迭代的次数
        num_iterations = self.num_epochs * iterations_per_epoch # 总迭代次数
        """
        开始迭代循环！
        """
        for t in range(num_iterations):
            self._step()
            """
            上面完成了一次神经网络的迭代。此时，模型的参数已经更新过一次，
            并且在self.loss_history中添加了一个新的loss值
            """
            # Maybe print training loss   从self.loss_history中取最新的loss值
            if self.verbose and t % self.print_every == 0:
                print('(Iteration %d / %d) loss: %f' % (t + 1, 
                        num_iterations, self.loss_history[-1]))


            # At the end of every epoch, increment the epoch counter and 
            # decay the learning rate.
            epoch_end = (t + 1) % iterations_per_epoch == 0
            if epoch_end:       # 只有当t = iterations_per_epoch-1 时为True
                self.epoch += 1 # 第一遍之后开始，从0自加1为每遍计数
                for k in self.optim_configs:  # 第一遍之后开始，每遍给学习率自乘一个衰减率
                    self.optim_configs[k]['learning_rate'] *= self.lr_decay


            # Check train and val accuracy on the first iteration, the last
            # iteration, and at the end of each epoch.
            first_it = (t == 0)                 # 起始的t
            last_it = (t == num_iterations - 1) # 最后的t
            if first_it or last_it or epoch_end:  # 在最开始／最后／每遍结束时
                train_acc = self.check_accuracy(self.X_train, self.y_train,
                                        num_samples=1000) # 随机取1000个训练图看准确率
                val_acc = self.check_accuracy(self.X_val, self.y_val)
                self.train_acc_history.append(train_acc)  # 计算全部验证图片的准确率
                self.val_acc_history.append(val_acc)


                if self.verbose:  # 在最开始／最后／每遍结束时，打印准确率等信息
                    print('(Epoch %d / %d) train acc: %f; val_acc: %f' % (
                            self.epoch, self.num_epochs, train_acc, val_acc))


                # 在最开始／最后／每遍结束时，比较当前验证集的准确率和过往最佳验证集
                # Keep track of the best model
                if val_acc > self.best_val_acc:
                    self.best_val_acc = val_acc
                    self.best_params = {}
                    for k, v in self.model.params.items():
                        self.best_params[k] = v.copy() # opy()仅复制值过来
        """
        结束迭代循环！
        """
        # At the end of training swap the best params into the model
        self.model.params = self.best_params  # 最后把得到的最佳模型参数存入到模型中