dim.h: truncate() should be documented

[chunyang-wen]

  /**
   * \brief [TODO]
   * \details [long description]
   * \return [description]
   */
  inline Dim truncate() const {
    Dim r = *this;
    unsigned int m = 1;
    unsigned int s = size();
    for (unsigned int i = 1; i < s; ++i)
      if (size(i) > 1) m = i + 1;
    r.resize(m);
    return r;
  }

size(i) definitions can not be found. And I want to know the purpose of truncate which means description. And it is related to find the problem of cdiv (#892)

Thanks in advance.

[neubig]

This removes all dimensions of size 1 from the end of the dim object. A PR documenting this would be welcome.

[chunyang-wen]

If so, I think the implementation is not that efficient.

/**
   * \brief [TODO]
   * \details [long description]
   * \return [description]
   */
  inline Dim truncate() const {
    Dim r = *this;
    unsigned int m = 1;
    unsigned int s = size();
    for (unsigned int i = 1; i < s; ++i)
      if (size(i) > 1) m = i + 1;
    r.resize(m);
    return r;
  }

  inline unsigned int size() const {
    return batch_size() * bd;
  }

  inline unsigned int batch_size() const {
    unsigned int p = 1;
    for (unsigned int i = 0; i < nd; ++i) p *= d[i];
    return p;
  }

  inline void resize(unsigned int i) {
    // if i < nd, it will remove size of dimension 1.
    while(nd < i)
      d[nd++] = 1;
    nd = i;
  }

inline unsigned int size(unsigned int i) const { return (*this)[i]; }

inline unsigned int operator[](unsigned int i) const { return i < nd ? d[i] : 1; }

The size() function in truncate calculate number of elements. We will iterate through all the elements.

For example:

Dim = { 2, 3, 4, 1}, nd=4, bd=1
truncate will iterate through 2*3*4*1 times to remove trailing dimensions of 1.
Actually only 4 times is required. If iterate backward, only 2 times is required.

truncate() is called in following files:

• nodes-arith-cwise.cc
• nodes-arith-scalar.cc
• nodes-arith-sum.cc
• nodes-logsumexp.cc

I will try to figure out why dimensions of 1 should be removed in dim_forward.

[msperber]

It might be worth considering to remove the dimension truncation for better consistency? That's what already happened for some operations touched by #776.

[pmichel31415]

fixed by #970 I think