PaddleAPI.h 24.9 KB
Newer Older
1
/* Copyright (c) 2016 PaddlePaddle Authors. All Rights Reserve.
Z
zhangjinchao01 已提交
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. */

#pragma once

#include <stddef.h>
#include <stdint.h>
19
#include <stdexcept>
Y
Yu Yang 已提交
20
#include <string>
Z
zhangjinchao01 已提交
21 22
#include <vector>
#include "paddle/utils/GlobalConstants.h"
23
#include "paddle/utils/TypeDefs.h"
Z
zhangjinchao01 已提交
24

L
lipeng17 已提交
25
/// Import PaddlePaddle's enumeration into global namespace.
Z
zhangjinchao01 已提交
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
using namespace paddle::enumeration_wrapper;  // NOLINT

#define DISABLE_COPY_AND_ASSIGN(classname) \
  classname(const classname& other);       \
  classname& operator=(const classname& other)

/**
 * @brief Initialize paddle.
 *
 * In python, this method should be invoked as
 * @code
 *  import sys
 *  import paddle
 *  paddle.initPaddle(sys.argv)
 *  or you can change arguments as any list of str.
 * @endcode
 */
void initPaddle(int argc, char** argv);

45
/// Return FLAGS_use_gpu
46
bool isUsingGpu();
47

48 49 50
/// Set the Flags_use_gpu to the given parameter
void setUseGpu(bool useGpu);

Z
zhangjinchao01 已提交
51 52 53 54 55 56 57 58 59 60
/// Return true if this py_paddle is compiled in GPU Version
bool isGpuVersion();

/// The Error of IO Operation. Such as file not found, etc.
class IOError {};

/// Out of range error
class RangeError {};

/// Not support Error, such as access GPU memory directly, etc.
61 62
class UnsupportError : public std::runtime_error {
public:
63 64
  UnsupportError() : std::runtime_error(" "){};
  UnsupportError(const std::string& message) : std::runtime_error(message){};
65
};
Z
zhangjinchao01 已提交
66 67 68

/// This type will map to python's list of float.
struct FloatArray {
L
liaogang 已提交
69
  const float* buf;
Z
zhangjinchao01 已提交
70 71
  const size_t length;
  bool needFree;  // true if the buf is dynamic alloced.
L
liaogang 已提交
72
  FloatArray(const float* b, const size_t l);
Z
zhangjinchao01 已提交
73 74 75 76 77 78 79 80 81 82 83 84
};

/// This type will map to python's list of int
struct IntArray {
  const int* buf;
  const size_t length;
  bool needFree;
  IntArray(const int* b, const size_t l, bool f = false);
};

/// This type will map to python's list of (int, float)
struct IntWithFloatArray {
L
liaogang 已提交
85
  const float* valBuf;
Z
zhangjinchao01 已提交
86 87 88
  const int* idxBuf;
  const size_t length;
  bool needFree;
L
liaogang 已提交
89
  IntWithFloatArray(const float* v, const int* i, size_t l, bool f = false);
Z
zhangjinchao01 已提交
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
};

enum SparseValueType { SPARSE_NON_VALUE = 0, SPARSE_VALUE = 1 };

enum SparseFormatType { SPARSE_CSR = 0, SPARSE_CSC = 1 };

/**
 * In Python, -1UL is hard to write. So define a const value used by python
 * side.
 */
const size_t NO_SPARSE_ID = -1UL;

struct MatrixPrivate;
class Matrix {
  Matrix();  // User Cannot Create Matrix.
  DISABLE_COPY_AND_ASSIGN(Matrix);
  static Matrix* createByPaddleMatrixPtr(void* sharedPtr);

public:
  virtual ~Matrix();

  /**
   * Create A Matrix with height,width, which is filled by zero.
   */
114 115
  static Matrix* createZero(size_t height,
                            size_t width,
116
                            bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
117 118 119 120 121 122 123 124 125 126

  /**
   * Create Sparse Matrix.
   *
   * After create sparse, sparseCopyFrom can be used to fill matrix.
   *
   * @param nnz  Number of non zero values.
   *
   * @note the default sparse type is SPARSE_CSR.
   */
127 128 129 130 131
  static Matrix* createSparse(size_t height,
                              size_t width,
                              size_t nnz,
                              bool isNonVal = true,
                              bool trans = false,
132
                              bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
133 134 135 136 137 138 139

  /**
   * Create Dense Matrix.
   *
   * @param data  list of float should be passed in python.
   * @note        the value will be copy into a new matrix.
   */
140 141 142 143 144 145 146 147 148 149 150
  static Matrix* createDense(const std::vector<float>& data,
                             size_t height,
                             size_t width,
                             bool useGpu = isUsingGpu());

  static Matrix* createDenseFromNumpy(
      float* data,
      int dim1,
      int dim2,
      bool copy = true,
      bool useGpu = isUsingGpu()) throw(UnsupportError);
Z
zhangjinchao01 已提交
151 152 153 154 155 156 157 158

  /**
   *  Create Cpu Dense Matrix from numpy matrix, dtype=float32
   *
   *  @param data  a numpy matrix.
   *  @param dim1  dimension of data.
   *  @param dim2  dimension of data.
   *  @param copy  true if copy into a new matrix, false will create
X
xuwei06 已提交
159 160 161 162
   *               matrix inplace. copy = false should be used with extreme
   *               care because Matrix will share the memory with the given
   *               numpy array. If the numpy array object is no longer valid,
   *               the memory space will not be usable.
Z
zhangjinchao01 已提交
163
   */
164 165 166
  static Matrix* createCpuDenseFromNumpy(float* data,
                                         int dim1,
                                         int dim2,
X
xuwei06 已提交
167
                                         bool copy = true);
Z
zhangjinchao01 已提交
168 169

  /// Create Gpu Dense Matrix from numpy matrix, dtype=float32
L
liaogang 已提交
170
  static Matrix* createGpuDenseFromNumpy(float* data, int dim1, int dim2);
Z
zhangjinchao01 已提交
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185

  /**
   * Cast to numpy matrix.
   *
   * @note    This method take no parameter in python.
   * @note    This method in python will return a numpy matrix, not void.
   * @note    Only CpuDenseMatrix is supported.
   *
   * Example:
   * @code
   * import paddle
   * m = paddle.Matrix.createZero(10,2)
   * numpy_mat = m.toNumpyMat()
   * @endcode
   */
186 187
  void toNumpyMatInplace(float** view_data,
                         int* dim1,
Z
zhangjinchao01 已提交
188 189 190
                         int* dim2) throw(UnsupportError);

  /// Copy To numpy mat.
191 192
  void copyToNumpyMat(float** view_m_data,
                      int* dim1,
Z
zhangjinchao01 已提交
193 194 195
                      int* dim2) throw(UnsupportError);

  /// Copy From Numpy Mat
L
liaogang 已提交
196
  void copyFromNumpyMat(float* data, int dim1, int dim2) throw(UnsupportError,
Z
zhangjinchao01 已提交
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
                                                               RangeError);

  /// return true if this matrix is sparse.
  bool isSparse() const;

  SparseValueType getSparseValueType() const throw(UnsupportError);

  SparseFormatType getSparseFormat() const throw(UnsupportError);

  IntArray getSparseRowCols(size_t i) const throw(UnsupportError, RangeError);

  IntWithFloatArray getSparseRowColsVal(size_t i) const
      throw(UnsupportError, RangeError);

  size_t getHeight() const;

  size_t getWidth() const;

L
liaogang 已提交
215
  float get(size_t x, size_t y) const throw(RangeError);
Z
zhangjinchao01 已提交
216

L
liaogang 已提交
217
  void set(size_t x, size_t y, float val) throw(RangeError, UnsupportError);
Z
zhangjinchao01 已提交
218 219 220 221 222 223 224 225 226 227 228

  /// return type is list of float
  FloatArray getData() const;

  /**
   * Copy from rows, cols, values.
   *
   * if sparse_nonvalue, the values should be []
   */
  void sparseCopyFrom(const std::vector<int>& rows,
                      const std::vector<int>& cols,
L
liaogang 已提交
229 230
                      const std::vector<float>& values =
                          std::vector<float>()) throw(UnsupportError);
Z
zhangjinchao01 已提交
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

  bool isGpu() const;

private:
  void* getSharedPtr() const;

  MatrixPrivate* m;
  friend class Trainer;
  friend class GradientMachine;
  friend class Arguments;
};

struct VectorPrivate;
class Vector {
  DISABLE_COPY_AND_ASSIGN(Vector);
  Vector();
  static Vector* createByPaddleVectorPtr(void* ptr);

  void* getSharedPtr();

public:
  ~Vector();

  /// Create Vector filled with zero.
255
  static Vector* createZero(size_t sz, bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
256 257 258 259 260 261

  /**
   * Create Vector from list of float.
   *
   * It will create a new vector, and copy data into it.
   */
262
  static Vector* create(const std::vector<float>& data,
263
                        bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
264

265 266 267 268 269
  static Vector* createVectorFromNumpy(
      float* data,
      int dim,
      bool copy = true,
      bool useGpu = isUsingGpu()) throw(UnsupportError);
Z
zhangjinchao01 已提交
270 271 272 273 274
  /**
   * Create Cpu Vector from numpy array, which dtype=float32
   *
   * If copy is false, it will create vector inplace.
   */
275 276
  static Vector* createCpuVectorFromNumpy(float* data,
                                          int dim,
X
xuwei06 已提交
277
                                          bool copy = true);
Z
zhangjinchao01 已提交
278 279

  /// Create Gpu Vector from numpy array, which dtype=float32
L
liaogang 已提交
280
  static Vector* createGpuVectorFromNumpy(float* data, int dim);
Z
zhangjinchao01 已提交
281

X
xuwei06 已提交
282 283 284 285 286 287 288
  /**
   * copy from another vector
   * throw(RangeError) if size of src vector is different from size of this
   * vector
   */
  void copyFrom(Vector* src) throw(RangeError);

Z
zhangjinchao01 已提交
289
  /// Cast to numpy array inplace.
L
liaogang 已提交
290
  void toNumpyArrayInplace(float** view_data, int* dim1) throw(UnsupportError);
Z
zhangjinchao01 已提交
291 292

  /// Copy to numpy array.
L
liaogang 已提交
293
  void copyToNumpyArray(float** view_m_data, int* dim1);
Z
zhangjinchao01 已提交
294 295

  /// Copy from numpy array.
L
liaogang 已提交
296
  void copyFromNumpyArray(float* data, int dim);
Z
zhangjinchao01 已提交
297 298

  /// __getitem__ in python
L
liaogang 已提交
299
  float get(const size_t idx) const throw(RangeError, UnsupportError);
Z
zhangjinchao01 已提交
300 301

  /// __setitem__ in python
L
liaogang 已提交
302
  void set(const size_t idx, float val) throw(RangeError, UnsupportError);
Z
zhangjinchao01 已提交
303 304 305 306

  /// Return is GPU vector or not.
  bool isGpu() const;

307 308 309
  /// Return a list of float, the memory is alloced and copied.
  FloatArray getData() const;

Z
zhangjinchao01 已提交
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329
  /// __len__ in python
  size_t getSize() const;

private:
  VectorPrivate* m;

private:
  friend class Parameter;
  friend class ParameterOptimizer;
  friend struct ParameterTraverseCallbackPrivate;
};

struct IVectorPrivate;
class IVector {
  IVector();
  DISABLE_COPY_AND_ASSIGN(IVector);
  static IVector* createByPaddleVectorPtr(void* ptr);

public:
  /// Create IVector filled with zero
330
  static IVector* createZero(size_t sz, bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
331 332 333 334 335

  /**
   * Create IVector from list of int.
   * It will create a new vector, and copy data into it.
   */
336
  static IVector* create(const std::vector<int>& data,
337
                         bool useGpu = isUsingGpu());
338

339 340 341 342 343
  static IVector* createVectorFromNumpy(
      int* data,
      int dim,
      bool copy = true,
      bool useGpu = isUsingGpu()) throw(UnsupportError);
Z
zhangjinchao01 已提交
344 345 346 347 348 349

  /**
   * Create Cpu IVector from numpy array, which dtype=int32
   *
   * If copy is false, it will create vector inplace
   */
350 351
  static IVector* createCpuVectorFromNumpy(int* data,
                                           int dim,
X
xuwei06 已提交
352
                                           bool copy = true);
Z
zhangjinchao01 已提交
353 354 355
  /**
   * Create Gpu IVector from numpy array, which dtype=int32
   */
356
  static IVector* createGpuVectorFromNumpy(int* data, int dim);
Z
zhangjinchao01 已提交
357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430

  /// Cast to numpy array inplace.
  void toNumpyArrayInplace(int** view_data, int* dim1) throw(UnsupportError);

  /// Copy to numpy array.
  void copyToNumpyArray(int** view_m_data, int* dim1);

  /// Copy from numpy array.
  void copyFromNumpyArray(int* data, int dim);

  virtual ~IVector();

  /// Return a list of int, the memory is alloced and copied.
  IntArray getData() const;

  /// This method will map to python [] method.
  int& operator[](const size_t idx) throw(RangeError, UnsupportError);

  const int& operator[](const size_t idx) const
      throw(RangeError, UnsupportError);

  inline int get(const size_t idx) const throw(RangeError, UnsupportError) {
    return (*this)[idx];
  }

  inline void set(const size_t idx, int val) throw(RangeError, UnsupportError) {
    (*this)[idx] = val;
  }

  /// Return true if it is gpu vector.
  bool isGpu() const;

  /// This method will map to python __len__();
  size_t getSize() const;

private:
  void* getSharedPtr() const;

  friend class Arguments;
  IVectorPrivate* m;
};

struct ArgumentsPrivate;

/// The Arguments is actual a std::vector<paddle::Argument> in paddle.
class Arguments {
private:
  Arguments();  // Internal Create.
  DISABLE_COPY_AND_ASSIGN(Arguments);

public:
  /**
   * Create a arguments with size.
   * Note that it can be zero.
   */
  static Arguments* createArguments(size_t slotNum);

  void resize(size_t slotNum);

  virtual ~Arguments();

  /**
   * Return the slot number that aguments contains.
   *
   * It is actually the vector's size
   */
  size_t getSlotNum() const;

  /**
   * The get functions of Arguments
   *
   * the param idx is the slot id
   */
  Matrix* getSlotValue(size_t idx) const throw(RangeError);
X
xuwei06 已提交
431
  Matrix* getSlotGrad(size_t idx) const throw(RangeError);
Z
zhangjinchao01 已提交
432 433 434
  IVector* getSlotIds(size_t idx) const throw(RangeError);
  Matrix* getSlotIn(size_t idx) const throw(RangeError);
  IVector* getSlotSequenceStartPositions(size_t idx) const throw(RangeError);
435
  IVector* getSlotSubSequenceStartPositions(size_t idx) const throw(RangeError);
Z
zhangjinchao01 已提交
436 437 438 439 440 441 442 443 444 445 446 447
  IVector* getSlotSequenceDim(size_t idx) const throw(RangeError);
  // End Of get functions of Arguments

  int64_t getBatchSize(size_t idx = 0) const throw(RangeError);

  /**
   * The set functions of Arguments.
   *
   * The param idx is the slot id.
   * The other param is the input Matrix or vector.
   */
  void setSlotValue(size_t idx, Matrix* mat) throw(RangeError);
X
xuwei06 已提交
448
  void setSlotGrad(size_t idx, Matrix* mat) throw(RangeError);
Z
zhangjinchao01 已提交
449 450 451 452
  void setSlotIn(size_t idx, Matrix* mat) throw(RangeError);
  void setSlotIds(size_t idx, IVector* vec) throw(RangeError);
  void setSlotSequenceStartPositions(size_t idx,
                                     IVector* vec) throw(RangeError);
453
  void setSlotSubSequenceStartPositions(size_t idx,
Y
yuyang18 已提交
454
                                        IVector* vec) throw(RangeError);
Z
zhangjinchao01 已提交
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521
  void setSlotSequenceDim(size_t idx, IVector* vec) throw(RangeError);

private:
  static Arguments* createByPaddleArgumentVector(void* ptr);
  void* getInternalArgumentsPtr() const;

private:
  ArgumentsPrivate* m;
  friend class Trainer;
  friend class GradientMachine;
  friend class SequenceGenerator;
};

enum GradientMatchineCreateMode {
  CREATE_MODE_NORMAL = 0,
  CREATE_MODE_TESTING = 4
};

struct ParameterConfigPrivate;
class ParameterConfig {
  DISABLE_COPY_AND_ASSIGN(ParameterConfig);
  ParameterConfig();

  /**
   * Internal methods
   */
  static ParameterConfig* createParameterConfigFromParameterSharedPtr(
      void* ptr);
  static ParameterConfig* createParameterConfigFromParameterPtr(void* ptr);
  void* getRawPtr();

public:
  ~ParameterConfig();

  /**
   * return proto buf string.
   */
  std::string toProtoString() const;

private:
  ParameterConfigPrivate* m;

private:
  friend class Parameter;
  friend class ParameterOptimizer;
  friend struct ParameterTraverseCallbackPrivate;
};

struct OptimizationConfigPrivate;
class OptimizationConfig {
  DISABLE_COPY_AND_ASSIGN(OptimizationConfig);
  OptimizationConfig();

public:
  static OptimizationConfig* createFromProtoString(const std::string& str);
  ~OptimizationConfig();

  /**
   * return protobuf string.
   */
  std::string toProtoString();

private:
  OptimizationConfigPrivate* m;

  friend class TrainerConfig;
  friend class ParameterOptimizer;
Y
Yu Yang 已提交
522
  friend class ParameterUpdater;
E
emailweixu 已提交
523
  friend class Trainer;
Z
zhangjinchao01 已提交
524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550
};

struct ParameterPrivate;
class Parameter {
private:
  Parameter();
  DISABLE_COPY_AND_ASSIGN(Parameter);

public:
  virtual ~Parameter();

  /**
   * get parameter name
   */
  std::string getName() const;

  /**
   * get buf in Parameter
   */
  Vector* getBuf(ParameterType type);

  /**
   * get id
   */
  size_t getID() const;

  ParameterConfig* getConfig();
X
xuwei06 已提交
551
  void setValueUpdated();
Z
zhangjinchao01 已提交
552

Y
Yu Yang 已提交
553 554
  size_t getSize() const;

Z
zhangjinchao01 已提交
555 556 557 558 559 560 561 562
private:
  static Parameter* createFromRawPtr(void* ptr);
  static Parameter* createFromSharedPtr(void* ptr);

private:
  ParameterPrivate* m;
  friend class UpdateCallbackWrapper;
  friend class GradientMachine;
Y
Yu Yang 已提交
563
  friend class ParameterUpdater;
Z
zhangjinchao01 已提交
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602
};

struct ModelConfigPrivate;
/**
 * You can only get model config from TrainerConfig.
 *
 * It is used by GradientMachine.
 */
class ModelConfig {
private:
  ModelConfig();
  DISABLE_COPY_AND_ASSIGN(ModelConfig);

public:
  virtual ~ModelConfig();

private:
  ModelConfigPrivate* m;
  friend class TrainerConfig;
  friend struct TrainerConfigPrivate;
  friend class GradientMachine;
};

struct TrainerConfigPrivate;
/**
 * To get TrainerConfig from file.
 *
 * It is used by GradientMachine.
 */
class TrainerConfig {
private:
  TrainerConfig();
  DISABLE_COPY_AND_ASSIGN(TrainerConfig);

public:
  virtual ~TrainerConfig();

  static TrainerConfig* createFromTrainerConfigFile(
      const std::string& configPath);
E
emailweixu 已提交
603
  static TrainerConfig* createFromProtoString(const std::string& str);
Z
zhangjinchao01 已提交
604 605 606 607 608 609 610

  ModelConfig* getModelConfig() const;

  OptimizationConfig* getOptimizationConfig() const;

private:
  TrainerConfigPrivate* m;
E
emailweixu 已提交
611
  friend class Trainer;
Z
zhangjinchao01 已提交
612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641
};

/**
 * The callback in backword.
 *
 * You can inherit this class in python.
 *
 * @code
 * class UpdateCallbackInPython(paddle.UpdateCallback):
 *   def __init__(self):
 *     paddle.UpdateCallback.__init__(self)
 *
 *   def apply(self, param):
 *     assert isinstance(param, paddle.Parameter)
 * @endcode
 */
class UpdateCallback {
public:
  virtual ~UpdateCallback();
  virtual void apply(Parameter* p);
};

struct ParameterTraverseCallbackPrivate;
class ParameterTraverseCallback {
  DISABLE_COPY_AND_ASSIGN(ParameterTraverseCallback);
  ParameterTraverseCallback();

public:
  ~ParameterTraverseCallback();

642 643
  void apply(const std::vector<Vector*>& vecs,
             const ParameterConfig& config,
Z
zhangjinchao01 已提交
644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675
             size_t sparseId);

private:
  ParameterTraverseCallbackPrivate* m;
  friend class ParameterOptimizer;
};

/**
 * The ParameterOptimizer Wrapper Class.
 *
 * Basically same as common/ParameterOptimizer.h
 */
struct ParameterOptimizerPrivate;
class ParameterOptimizer {
  DISABLE_COPY_AND_ASSIGN(ParameterOptimizer);
  ParameterOptimizer();

public:
  static ParameterOptimizer* create(OptimizationConfig* config);

  ~ParameterOptimizer();

  void init(size_t numRows, const ParameterConfig* config);

  void startPass();

  void finishPass();

  void startBatch(size_t numSamplesProcessed);

  void finishBatch();

676 677
  void update(const std::vector<Vector*>& vecs,
              const ParameterConfig& conf,
Z
zhangjinchao01 已提交
678 679 680 681 682 683 684 685 686 687 688 689
              size_t sparseId = NO_SPARSE_ID);

  std::vector<int> getParameterTypes() const;

  ParameterTraverseCallback* needSpecialTraversal(
      const ParameterConfig& config) const;

private:
  ParameterOptimizerPrivate* m;
};

class SequenceGenerator;
Y
Yu Yang 已提交
690
class Evaluator;
Z
zhangjinchao01 已提交
691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716
struct GradientMachinePrivate;
class GradientMachine {
private:
  GradientMachine();
  DISABLE_COPY_AND_ASSIGN(GradientMachine);

public:
  virtual ~GradientMachine();

  /**
   * Create By ProtoStr.
   *
   * The ProtoStr can be generate by python's protobuf code.
   */
  static GradientMachine* createByConfigProtoStr(
      const std::string& protoStr,
      GradientMatchineCreateMode mode = CREATE_MODE_NORMAL,
      const std::vector<int>& parameterTypes = defaultParamTypes);

  /**
   * Create by ModelConfig object.
   *
   * To get ModelConfig, you can get TrainerConfig from config file, then get
   * model config by TrainerConfig
   */
  static GradientMachine* createByModelConfig(
717 718
      ModelConfig* conf,
      GradientMatchineCreateMode mode = CREATE_MODE_NORMAL,
Z
zhangjinchao01 已提交
719 720
      const std::vector<int>& parameterTypes = defaultParamTypes);

Y
Yu Yang 已提交
721 722 723 724 725 726 727
  /**
   * @brief finish
   */
  void finish();

  void start();

Z
zhangjinchao01 已提交
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747
  /**
   * The forward stage of GradientMachine.
   *
   * @note  the outArgs could be zero length arguemnts.
   * @note  THIS METHOD IS VERY USEFULL FOR PREDICT FROM TRAINED MODEL.
   */
  void forward(const Arguments& inArgs, Arguments* outArgs, PassType passType);

  /**
   * The backward stage of GradientMachine.
   *
   * @note  Currently the ParameterUpdater is not wrapped in SWIG, so backward
   * cannot actually train a network. But you can write a update callback to
   * change the parameter or implement a ParameterUpdater in python side.
   */
  void backward(const UpdateCallback& callback = UpdateCallback());

  /**
   * Combine forward/backward
   */
748 749
  void forwardBackward(const Arguments& inArgs,
                       Arguments* outArgs,
Z
zhangjinchao01 已提交
750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
                       PassType passType,
                       const UpdateCallback& callback = UpdateCallback());

  void loadParameters(const std::string& path);

  size_t getParameterSize() const;
  Parameter* getParameter(size_t i) throw(RangeError);

  void randParameters();

  Matrix* getLayerOutput(const std::string& layerName) const
      throw(UnsupportError);

  /**
   * Create a sequence generator.
   *
   * @note  It just like a paddle_gen_sequence.
   */
  SequenceGenerator* asSequenceGenerator(
      const std::vector<std::string>& dict = std::vector<std::string>(),
770 771 772
      size_t begin_id = 0UL,
      size_t end_id = 0UL,
      size_t max_length = 100UL,
Z
zhangjinchao01 已提交
773 774
      size_t beam_size = -1UL);

Y
Yu Yang 已提交
775 776 777 778
  Evaluator* makeEvaluator();

  void eval(Evaluator* evaluator);

Z
zhangjinchao01 已提交
779 780 781 782
private:
  GradientMachinePrivate* m;

  static GradientMachine* createFromPaddleModelPtr(
783 784
      const void* confPtr,
      GradientMatchineCreateMode mode,
Z
zhangjinchao01 已提交
785 786 787 788
      const std::vector<int>& types);

  // Not to use c++ 11 init-list, so we use static var as function default arg.
  static std::vector<int> defaultParamTypes;
E
emailweixu 已提交
789
  friend class Trainer;
Y
Yu Yang 已提交
790 791 792 793 794 795 796 797 798 799 800 801
  friend class ParameterUpdater;
};

struct ParameterUpdaterPrivate;
class ParameterUpdater {
private:
  ParameterUpdater();

public:
  static ParameterUpdater* createLocalUpdater(OptimizationConfig* config);
  ~ParameterUpdater();

Y
Yu Yang 已提交
802 803 804 805
  /**
   * @brief initialize Parameter Updater by GradientMachine.
   * @param gm
   */
Y
Yu Yang 已提交
806 807
  void init(const GradientMachine& gm);

Y
Yu Yang 已提交
808 809 810
  /**
   * @brief begin of a training/testing of one pass.
   */
Y
Yu Yang 已提交
811 812
  void startPass();

Y
Yu Yang 已提交
813 814 815
  /**
   * @brief end of a traning/testing of one pass.
   */
Y
Yu Yang 已提交
816 817
  void finishPass();

Y
Yu Yang 已提交
818 819 820 821 822
  /**
   * @brief begin of a training/testing of one batch.
   * @param data batch's size
   * @return PassType, mostly will be training.
   */
Y
Yu Yang 已提交
823
  PassType startBatch(size_t batchSize);
Y
Yu Yang 已提交
824

Y
Yu Yang 已提交
825 826 827 828
  /**
   * @brief end of a traning/testing of one batch
   * @param cost current batch cost.
   */
Y
Yu Yang 已提交
829 830
  void finishBatch(float cost);

Y
Yu Yang 已提交
831 832 833 834
  /**
   * @brief update a parameter (by local optimizer or by cluster pserver)
   * @param param
   */
Y
Yu Yang 已提交
835 836
  void update(Parameter* param);

Y
Yu Yang 已提交
837 838 839 840 841
  /**
   * @brief restore the average parameter.
   * @note It is only used in AverageOptimizer. Restore will get the current
   * PARAMETER_VALUE back.
   */
Y
Yu Yang 已提交
842 843
  void restore();

Y
Yu Yang 已提交
844 845 846 847 848 849
  /**
   * @brief apply. Store the average parameter.
   * @note It is only used in AverageOptimizer. Apply will store the current
   * PARAMETER_VALUE to buffer, calcaualte current Average Parameter, and save
   * it to PARAMETER_VALUE.
   */
Y
Yu Yang 已提交
850 851
  void apply();

Y
Yu Yang 已提交
852 853 854 855 856
  /**
   * @brief catchUpWith The Regularization will be delayed in many situations(
   * pserver, local sparse). Catch Up means catch the regularization up, apply
   * regularization to all params.
   */
Y
Yu Yang 已提交
857 858
  void catchUpWith();

Y
Yu Yang 已提交
859 860
private:
  ParameterUpdaterPrivate* m;
Z
zhangjinchao01 已提交
861 862
};

Y
Yu Yang 已提交
863 864 865 866 867 868 869 870 871
struct EvaluatorPrivate;
class Evaluator {
private:
  Evaluator();
  DISABLE_COPY_AND_ASSIGN(Evaluator);

public:
  ~Evaluator();

Y
Yu Yang 已提交
872 873 874
  /**
   * @brief begin an evaluate stage.
   */
Y
Yu Yang 已提交
875 876
  void start();

Y
Yu Yang 已提交
877 878 879
  /**
   * @brief end an evaluate stage.
   */
Y
Yu Yang 已提交
880 881
  void finish();

Y
Yu Yang 已提交
882 883 884 885 886
  /**
   * @brief toString will get a evaluate result.
   *
   * __repr__ method in python
   */
Y
Yu Yang 已提交
887 888 889 890 891 892 893 894
  std::string toString();

private:
  EvaluatorPrivate* m;

  friend class GradientMachine;
};

Z
zhangjinchao01 已提交
895 896 897 898 899
struct TrainerPrivate;
class Trainer {
private:
  TrainerPrivate* m;
  Trainer();
E
emailweixu 已提交
900
  Trainer(TrainerConfig* optConfig, GradientMachine* gm);
Z
zhangjinchao01 已提交
901 902 903 904 905 906 907 908
  DISABLE_COPY_AND_ASSIGN(Trainer);

public:
  virtual ~Trainer();

  /// Create A Trainer By TrainerConfig. using paddle command line.
  static Trainer* createByCommandLine() throw(IOError);

909 910
  static Trainer* create(TrainerConfig* optConfig,
                         GradientMachine* gm) throw(IOError);
E
emailweixu 已提交
911 912

  /// Start training
Z
zhangjinchao01 已提交
913
  void startTrain();
E
emailweixu 已提交
914 915

  /// Finish training
Z
zhangjinchao01 已提交
916 917
  void finishTrain();

E
emailweixu 已提交
918
  /// Start a pass.
Z
zhangjinchao01 已提交
919 920
  void startTrainPass();

E
emailweixu 已提交
921 922
  /// Finish a pass
  void finishTrainPass();
Z
zhangjinchao01 已提交
923 924 925 926 927 928

  /**
   * Train one batch,
   *
   * @return true if all batch finished.
   */
E
emailweixu 已提交
929
  bool trainOneBatch(size_t batchSize);
Z
zhangjinchao01 已提交
930

E
emailweixu 已提交
931
  void trainOneDataBatch(size_t batchSize, const Arguments& args);
Z
zhangjinchao01 已提交
932

E
emailweixu 已提交
933 934 935
  void startTestPeriod();
  void testOneDataBatch(size_t batchSize, const Arguments& args);
  void finishTestPeriod();
Z
zhangjinchao01 已提交
936

E
emailweixu 已提交
937
  void forwardOneBatch(size_t batchSize);
Z
zhangjinchao01 已提交
938

E
emailweixu 已提交
939
  Arguments* getForwardOutput();
Z
zhangjinchao01 已提交
940 941 942 943

  Matrix* getLayerOutput(const std::string& layerName);
};

E
emailweixu 已提交
944
/// the N-Best results generated from one input sequence.
Z
zhangjinchao01 已提交
945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994
class ISequenceResults {
public:
  virtual ~ISequenceResults();

  /// Number of result.
  virtual size_t getSize() const = 0;

  /**
   * Get sentence from dictionary.
   *
   * @param id  the index of result.
   * @param split  if true, the return sentence will be splited with ' ' by
   *               each word. Default is false.
   */
  virtual std::string getSentence(size_t id, bool split = false) const
      throw(RangeError) = 0;
  virtual std::vector<int> getSequence(size_t id) const throw(RangeError) = 0;
  virtual float getScore(size_t id) const throw(RangeError) = 0;
};

struct SequenceGeneratorPrivate;
class SequenceGenerator {
  DISABLE_COPY_AND_ASSIGN(SequenceGenerator);
  SequenceGenerator();

public:
  virtual ~SequenceGenerator();

  /**
   * Generate Sequence by input.
   *
   * @note  The inArgs is just one sequence of data.
   * @note  The return will get a N-best generate result by inArgs.
   *        Sort by score.
   */
  ISequenceResults* generateSequence(const Arguments& inArgs) const;

  void setDict(const std::vector<std::string>& dict);
  void setBos(size_t bos);
  void setEos(size_t eos);
  void setMaxLength(size_t maxlength);
  void setBeamSize(size_t beamSize);

private:
  static SequenceGenerator* createByGradientMachineSharedPtr(void* ptr);
  friend class GradientMachine;

private:
  SequenceGeneratorPrivate* m;
};