Breaking changes in Master compared to beta15

After we shipped beta15, we have made some breaking changes that are currently in master. These breaking changes will make it to our release candidate 1 soon.

Based on the feedback we got we are changing some APIs, refactor some code, deprecated old APIs and changing namespaces to a more logical hierarchy. The plan is that after the release Candidate there will be very little breaking change.

These are the current breaking changes:

• NDArrayView's data() method is now a property

• Namespaces:

  • Readers are exposed through cntk.io namespace, they no longer imported to the root CNTK namespace.
  • Several functionalities that were under cntk.utils are now refactored (removed) into their suitable namespace. Some of the popular ones are
    • Print progress has moved to cntk.logging.
    • Print graph or finding nodes by names moved from cntk.graph to CNTK.logging.graph
  • All debugging APIs have moved to cntk.debugging.
  • Move profiler APIs to cntk.debugging.
  • Losses and metrics have moved to cntk.losses and cntk.metrics respectively.
  • Former cntk_learner namespace is replaced by cntk.learners with all learners moved under cntk.learners namespace.
  • trainer, training_session, and distributed have moved to cntk.train namespace.
  • variables module has moved to cntk root namespace.
  • one_hot function is now a static method in Value class.
  • value_to_seq and value_variable_to_seq functions are now a method in Value class and renamed to to_seq.
  • Layers APIs aren't loaded by default, so you need from cntk.layers import *.
    • Input is gone use input

• Evaluating a node that has only the batch axis and no sequence axis, previously always returned the result containing a sequence dimension. This was fixed, i.e., it will now only output the batch axis.

• Evaluating a node that has a sequence axis, previously returned a list of NumPy arrays when the sequences were of different length, but a single NumPy array containing all sequences, when the sequences were of same length (most of the time, because the sequence axis was not used at all, resulting in all sequences having only one element). This was inconsistent is now fixed, such that whenever a sequence axis is present, the output is a Python list. If your program breaks because of this change, it might be a sign that you specified your input with a sequence axis (the default in input_variable()), but are not using it.

• adam_sgd() is deprecated:

  • If you used adam_sgd() with low_memory=True or didn't specify low_memory at all, switch to fsadagrad().
  • Otherwise, use adam(), which matches the published ADAM method.

• upper_pad and lower_pad are gone.

• MinibatchData.value is deprecated, because it encourages inefficient usage patterns. Instead, MinibatchData.data now returns a Value instance, which does not need to be converted to NumPy when being passed to eval(), forward() or train_minibatch().

• Automatic conversion to NumPy via np.asarray(cntk_obj) is being replaced by asarray()/as_sequences() member function of those objects

  • asarray() returns dense or sparse (instance of scipy.csr_matrix) versions of the underlying data
    • supported by Constant, Parameter, NDArrayView, Value, and MinibatchData
  • as_sequences(var) returns a Python list of sequences whose elements are NumPy arrays (according to var's dynamic and static axes)
    • supported by Value and MinibatchData
  • The reasons for this change are that np.assarray()
    • always returns NumPy arrays, so no sequences could be supported
    • only supports dense arrays
    • does not allow to throw exceptions from within the array interface