PaddleAPI.h 25.2 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
#include <vector>
L
liaogang 已提交
22
#include "paddle/utils/Common.h"
Z
zhangjinchao01 已提交
23 24
#include "paddle/utils/GlobalConstants.h"

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
using namespace paddle::enumeration_wrapper;  // NOLINT

/**
 * @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);

41
/// Return FLAGS_use_gpu
42
bool isUsingGpu();
43

44 45 46
/// Set the Flags_use_gpu to the given parameter
void setUseGpu(bool useGpu);

Z
zhangjinchao01 已提交
47 48 49
/// Return true if this py_paddle is compiled in GPU Version
bool isGpuVersion();

D
dangqingqing 已提交
50
/// Return FLAGS_trainer_count
51 52
int getTrainerCount();

Z
zhangjinchao01 已提交
53 54 55 56 57 58 59
/// 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.
60 61
class UnsupportError : public std::runtime_error {
public:
62 63
  UnsupportError() : std::runtime_error(" "){};
  UnsupportError(const std::string& message) : std::runtime_error(message){};
64
};
Z
zhangjinchao01 已提交
65 66 67

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

/// 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 已提交
84
  const float* valBuf;
Z
zhangjinchao01 已提交
85 86 87
  const int* idxBuf;
  const size_t length;
  bool needFree;
L
liaogang 已提交
88
  IntWithFloatArray(const float* v, const int* i, size_t l, bool f = false);
Z
zhangjinchao01 已提交
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
};

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.
104
  DISABLE_COPY(Matrix);
Z
zhangjinchao01 已提交
105 106 107 108 109 110 111 112
  static Matrix* createByPaddleMatrixPtr(void* sharedPtr);

public:
  virtual ~Matrix();

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

  /**
   * 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.
   */
126 127 128 129 130
  static Matrix* createSparse(size_t height,
                              size_t width,
                              size_t nnz,
                              bool isNonVal = true,
                              bool trans = false,
131
                              bool useGpu = isUsingGpu());
Z
zhangjinchao01 已提交
132 133 134 135 136 137 138

  /**
   * Create Dense Matrix.
   *
   * @param data  list of float should be passed in python.
   * @note        the value will be copy into a new matrix.
   */
139 140 141 142 143 144 145 146 147 148 149
  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 已提交
150 151 152 153 154 155 156 157

  /**
   *  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 已提交
158 159 160 161
   *               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 已提交
162
   */
163 164 165
  static Matrix* createCpuDenseFromNumpy(float* data,
                                         int dim1,
                                         int dim2,
X
xuwei06 已提交
166
                                         bool copy = true);
Z
zhangjinchao01 已提交
167 168

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

  /**
   * 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
   */
185 186
  void toNumpyMatInplace(float** view_data,
                         int* dim1,
Z
zhangjinchao01 已提交
187 188 189
                         int* dim2) throw(UnsupportError);

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

  /// Copy From Numpy Mat
L
liaogang 已提交
195
  void copyFromNumpyMat(float* data, int dim1, int dim2) throw(UnsupportError,
Z
zhangjinchao01 已提交
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
                                                               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 已提交
214
  float get(size_t x, size_t y) const throw(RangeError);
Z
zhangjinchao01 已提交
215

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

  /// 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 已提交
228 229
                      const std::vector<float>& values =
                          std::vector<float>()) throw(UnsupportError);
Z
zhangjinchao01 已提交
230 231 232 233 234 235 236 237 238 239 240 241 242 243

  bool isGpu() const;

private:
  void* getSharedPtr() const;

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

struct VectorPrivate;
class Vector {
244
  DISABLE_COPY(Vector);
Z
zhangjinchao01 已提交
245 246 247 248 249 250 251 252 253
  Vector();
  static Vector* createByPaddleVectorPtr(void* ptr);

  void* getSharedPtr();

public:
  ~Vector();

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

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

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

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

X
xuwei06 已提交
281 282 283 284 285 286 287
  /**
   * 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 已提交
288
  /// Cast to numpy array inplace.
L
liaogang 已提交
289
  void toNumpyArrayInplace(float** view_data, int* dim1) throw(UnsupportError);
Z
zhangjinchao01 已提交
290 291

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

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

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

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

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

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

Z
zhangjinchao01 已提交
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323
  /// __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();
324
  DISABLE_COPY(IVector);
Z
zhangjinchao01 已提交
325 326 327 328
  static IVector* createByPaddleVectorPtr(void* ptr);

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

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

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

  /**
   * Create Cpu IVector from numpy array, which dtype=int32
   *
   * If copy is false, it will create vector inplace
   */
349 350
  static IVector* createCpuVectorFromNumpy(int* data,
                                           int dim,
X
xuwei06 已提交
351
                                           bool copy = true);
Z
zhangjinchao01 已提交
352 353 354
  /**
   * Create Gpu IVector from numpy array, which dtype=int32
   */
355
  static IVector* createGpuVectorFromNumpy(int* data, int dim);
Z
zhangjinchao01 已提交
356 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

  /// 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.
404
  DISABLE_COPY(Arguments);
Z
zhangjinchao01 已提交
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

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 已提交
430
  Matrix* getSlotGrad(size_t idx) const throw(RangeError);
Z
zhangjinchao01 已提交
431 432 433
  IVector* getSlotIds(size_t idx) const throw(RangeError);
  Matrix* getSlotIn(size_t idx) const throw(RangeError);
  IVector* getSlotSequenceStartPositions(size_t idx) const throw(RangeError);
434
  IVector* getSlotSubSequenceStartPositions(size_t idx) const throw(RangeError);
Z
zhangjinchao01 已提交
435 436 437 438 439 440 441 442 443 444 445 446
  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 已提交
447
  void setSlotGrad(size_t idx, Matrix* mat) throw(RangeError);
Z
zhangjinchao01 已提交
448 449 450 451
  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);
452
  void setSlotSubSequenceStartPositions(size_t idx,
Y
yuyang18 已提交
453
                                        IVector* vec) throw(RangeError);
Z
zhangjinchao01 已提交
454 455
  void setSlotSequenceDim(size_t idx, IVector* vec) throw(RangeError);

Y
Yu Yang 已提交
456 457
  float sumCosts() const;

Z
zhangjinchao01 已提交
458 459
private:
  static Arguments* createByPaddleArgumentVector(void* ptr);
L
liaogang 已提交
460
  static Arguments* createByPaddleArgument(const void* ptr);
Z
zhangjinchao01 已提交
461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
  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 {
477
  DISABLE_COPY(ParameterConfig);
Z
zhangjinchao01 已提交
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
  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 {
507
  DISABLE_COPY(OptimizationConfig);
Z
zhangjinchao01 已提交
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523
  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 已提交
524
  friend class ParameterUpdater;
E
emailweixu 已提交
525
  friend class Trainer;
Z
zhangjinchao01 已提交
526 527 528 529 530 531
};

struct ParameterPrivate;
class Parameter {
private:
  Parameter();
532
  DISABLE_COPY(Parameter);
Z
zhangjinchao01 已提交
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552

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 已提交
553
  void setValueUpdated();
Z
zhangjinchao01 已提交
554

Y
Yu Yang 已提交
555 556 557 558
  bool save(const std::string& filename) const;

  bool load(const std::string& filename) const;

Y
Yu Yang 已提交
559 560
  size_t getSize() const;

Z
zhangjinchao01 已提交
561 562 563 564 565 566 567 568
private:
  static Parameter* createFromRawPtr(void* ptr);
  static Parameter* createFromSharedPtr(void* ptr);

private:
  ParameterPrivate* m;
  friend class UpdateCallbackWrapper;
  friend class GradientMachine;
Y
Yu Yang 已提交
569
  friend class ParameterUpdater;
Z
zhangjinchao01 已提交
570 571 572 573 574 575 576 577 578 579 580
};

struct ModelConfigPrivate;
/**
 * You can only get model config from TrainerConfig.
 *
 * It is used by GradientMachine.
 */
class ModelConfig {
private:
  ModelConfig();
581
  DISABLE_COPY(ModelConfig);
Z
zhangjinchao01 已提交
582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601

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();
602
  DISABLE_COPY(TrainerConfig);
Z
zhangjinchao01 已提交
603 604 605 606 607 608

public:
  virtual ~TrainerConfig();

  static TrainerConfig* createFromTrainerConfigFile(
      const std::string& configPath);
E
emailweixu 已提交
609
  static TrainerConfig* createFromProtoString(const std::string& str);
Z
zhangjinchao01 已提交
610 611 612 613 614 615 616

  ModelConfig* getModelConfig() const;

  OptimizationConfig* getOptimizationConfig() const;

private:
  TrainerConfigPrivate* m;
E
emailweixu 已提交
617
  friend class Trainer;
Z
zhangjinchao01 已提交
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 {
642
  DISABLE_COPY(ParameterTraverseCallback);
Z
zhangjinchao01 已提交
643 644 645 646 647
  ParameterTraverseCallback();

public:
  ~ParameterTraverseCallback();

648 649
  void apply(const std::vector<Vector*>& vecs,
             const ParameterConfig& config,
Z
zhangjinchao01 已提交
650 651 652 653 654 655 656 657 658 659 660 661 662 663
             size_t sparseId);

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

/**
 * The ParameterOptimizer Wrapper Class.
 *
 * Basically same as common/ParameterOptimizer.h
 */
struct ParameterOptimizerPrivate;
class ParameterOptimizer {
664
  DISABLE_COPY(ParameterOptimizer);
Z
zhangjinchao01 已提交
665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681
  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();

682 683
  void update(const std::vector<Vector*>& vecs,
              const ParameterConfig& conf,
Z
zhangjinchao01 已提交
684 685 686 687 688 689 690 691 692 693 694 695
              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 已提交
696
class Evaluator;
Z
zhangjinchao01 已提交
697 698 699 700
struct GradientMachinePrivate;
class GradientMachine {
private:
  GradientMachine();
701
  DISABLE_COPY(GradientMachine);
Z
zhangjinchao01 已提交
702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722

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(
723 724
      ModelConfig* conf,
      GradientMatchineCreateMode mode = CREATE_MODE_NORMAL,
Z
zhangjinchao01 已提交
725 726
      const std::vector<int>& parameterTypes = defaultParamTypes);

Y
Yu Yang 已提交
727 728 729 730 731 732 733
  /**
   * @brief finish
   */
  void finish();

  void start();

734 735 736 737 738 739 740 741 742 743
  /**
   * Prefetch row ids of sparse parameter.
   */
  void prefetch(const Arguments& inArgs);

  /**
   * Do some thing when train pass ended.
   */
  void onPassEnd();

Z
zhangjinchao01 已提交
744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763
  /**
   * 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
   */
764 765
  void forwardBackward(const Arguments& inArgs,
                       Arguments* outArgs,
Z
zhangjinchao01 已提交
766 767 768 769 770 771 772 773 774 775
                       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();

L
liaogang 已提交
776
  Arguments* getLayerOutput(const std::string& layerName) const
Z
zhangjinchao01 已提交
777 778 779 780 781 782 783 784 785
      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>(),
786 787 788
      size_t begin_id = 0UL,
      size_t end_id = 0UL,
      size_t max_length = 100UL,
Z
zhangjinchao01 已提交
789 790
      size_t beam_size = -1UL);

Y
Yu Yang 已提交
791 792 793 794
  Evaluator* makeEvaluator();

  void eval(Evaluator* evaluator);

Z
zhangjinchao01 已提交
795 796 797 798
private:
  GradientMachinePrivate* m;

  static GradientMachine* createFromPaddleModelPtr(
799 800
      const void* confPtr,
      GradientMatchineCreateMode mode,
Z
zhangjinchao01 已提交
801 802 803 804
      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 已提交
805
  friend class Trainer;
Y
Yu Yang 已提交
806 807 808 809 810 811 812 813 814 815
  friend class ParameterUpdater;
};

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

public:
  static ParameterUpdater* createLocalUpdater(OptimizationConfig* config);
Q
qiaolongfei 已提交
816 817
  static ParameterUpdater* createRemoteUpdater(OptimizationConfig* config,
                                               int passCount);
Y
Yu Yang 已提交
818 819
  ~ParameterUpdater();

Y
Yu Yang 已提交
820 821 822 823
  /**
   * @brief initialize Parameter Updater by GradientMachine.
   * @param gm
   */
Y
Yu Yang 已提交
824 825
  void init(const GradientMachine& gm);

Y
Yu Yang 已提交
826 827 828
  /**
   * @brief begin of a training/testing of one pass.
   */
Y
Yu Yang 已提交
829 830
  void startPass();

Y
Yu Yang 已提交
831 832 833
  /**
   * @brief end of a traning/testing of one pass.
   */
Y
Yu Yang 已提交
834 835
  void finishPass();

Y
Yu Yang 已提交
836 837 838 839 840
  /**
   * @brief begin of a training/testing of one batch.
   * @param data batch's size
   * @return PassType, mostly will be training.
   */
Y
Yu Yang 已提交
841
  PassType startBatch(size_t batchSize);
Y
Yu Yang 已提交
842

Y
Yu Yang 已提交
843 844 845 846
  /**
   * @brief end of a traning/testing of one batch
   * @param cost current batch cost.
   */
Y
Yu Yang 已提交
847 848
  void finishBatch(float cost);

Y
Yu Yang 已提交
849 850 851 852
  /**
   * @brief update a parameter (by local optimizer or by cluster pserver)
   * @param param
   */
Y
Yu Yang 已提交
853 854
  void update(Parameter* param);

Y
Yu Yang 已提交
855 856 857 858 859
  /**
   * @brief restore the average parameter.
   * @note It is only used in AverageOptimizer. Restore will get the current
   * PARAMETER_VALUE back.
   */
Y
Yu Yang 已提交
860 861
  void restore();

Y
Yu Yang 已提交
862 863 864 865 866 867
  /**
   * @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 已提交
868 869
  void apply();

Y
Yu Yang 已提交
870 871 872 873 874
  /**
   * @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 已提交
875 876
  void catchUpWith();

Y
Yu Yang 已提交
877 878
private:
  ParameterUpdaterPrivate* m;
Z
zhangjinchao01 已提交
879 880
};

Y
Yu Yang 已提交
881 882 883 884
struct EvaluatorPrivate;
class Evaluator {
private:
  Evaluator();
Y
Yu Yang 已提交
885
  DISABLE_COPY(Evaluator);
Y
Yu Yang 已提交
886 887 888 889

public:
  ~Evaluator();

Y
Yu Yang 已提交
890 891 892
  /**
   * @brief begin an evaluate stage.
   */
Y
Yu Yang 已提交
893 894
  void start();

Y
Yu Yang 已提交
895 896 897
  /**
   * @brief end an evaluate stage.
   */
Y
Yu Yang 已提交
898 899
  void finish();

Y
Yu Yang 已提交
900 901 902 903 904
  /**
   * @brief toString will get a evaluate result.
   *
   * __repr__ method in python
   */
Y
Yu Yang 已提交
905 906
  std::string toString();

Y
Yu Yang 已提交
907 908
  std::vector<std::string> getNames() const;

909 910
  double getValue(const std::string name) const;

Y
Yu Yang 已提交
911 912 913 914
private:
  EvaluatorPrivate* m;

  friend class GradientMachine;
Z
zhangjinchao01 已提交
915 916 917 918 919 920 921
};

struct TrainerPrivate;
class Trainer {
private:
  TrainerPrivate* m;
  Trainer();
E
emailweixu 已提交
922
  Trainer(TrainerConfig* optConfig, GradientMachine* gm);
923
  DISABLE_COPY(Trainer);
Z
zhangjinchao01 已提交
924 925 926 927 928 929 930

public:
  virtual ~Trainer();

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

931 932
  static Trainer* create(TrainerConfig* optConfig,
                         GradientMachine* gm) throw(IOError);
E
emailweixu 已提交
933 934

  /// Start training
Z
zhangjinchao01 已提交
935
  void startTrain();
E
emailweixu 已提交
936 937

  /// Finish training
Z
zhangjinchao01 已提交
938 939
  void finishTrain();

E
emailweixu 已提交
940
  /// Start a pass.
Z
zhangjinchao01 已提交
941 942
  void startTrainPass();

E
emailweixu 已提交
943 944
  /// Finish a pass
  void finishTrainPass();
Z
zhangjinchao01 已提交
945 946 947 948 949 950

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

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

E
emailweixu 已提交
955 956 957
  void startTestPeriod();
  void testOneDataBatch(size_t batchSize, const Arguments& args);
  void finishTestPeriod();
Z
zhangjinchao01 已提交
958

E
emailweixu 已提交
959
  void forwardOneBatch(size_t batchSize);
Z
zhangjinchao01 已提交
960

E
emailweixu 已提交
961
  Arguments* getForwardOutput();
Z
zhangjinchao01 已提交
962

L
liaogang 已提交
963
  Arguments* getLayerOutput(const std::string& layerName) const;
Z
zhangjinchao01 已提交
964 965
};

E
emailweixu 已提交
966
/// the N-Best results generated from one input sequence.
Z
zhangjinchao01 已提交
967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988
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 {
989
  DISABLE_COPY(SequenceGenerator);
Z
zhangjinchao01 已提交
990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016
  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;
};