PaddleCAPI.h

/* Copyright (c) 2016 PaddlePaddle Authors. All Rights Reserve.

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. */

#ifndef PADDLECAPI_H_
#define PADDLECAPI_H_
#include <stdbool.h>
#include <stdint.h>
#include "config.h"
#include "error.h"
#include "matrix.h"
#include "vector.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Paddle C API. It will replace SWIG as Multiple Language API for model
 * training & inference. Currently it is only used in model infernece.
 *
 * NOTE: This is an experimental API, it could be changed.
 */

/**
 * Arguments functions. Each argument means layer output. Arguments means a
 * array of arguemnt.
 */
typedef void* paddle_arguments;

/**
 * @brief paddle_arguments_create_none Create a array of arguments, which size
 * is zero.
 * @return Arguemnts
 */
PD_API paddle_arguments paddle_arguments_create_none();

/**
 * @brief paddle_arguments_destroy Destroy the arguments
 * @param args arguments to destroy
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_destroy(paddle_arguments args);

/**
 * @brief PDArgsGetSize Get size of arguments array
 * @param [in] args arguments array
 * @param [out] size array size
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_size(paddle_arguments args,
                                          uint64_t* size);

/**
 * @brief PDArgsResize Resize a arguments array.
 * @param args arguments array.
 * @param size target size of array
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_resize(paddle_arguments args,
                                            uint64_t size);

/**
 * @brief PDArgsSetValue Set value matrix of one argument in array, which index
 *        is `ID`.
 * @param args arguments array
 * @param ID array index
 * @param mat matrix pointer
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_set_value(paddle_arguments args,
                                               uint64_t ID,
                                               paddle_matrix mat);

/**
 * @brief PDArgsGetValue Get value matrix of one argument in array, which index
 *        is `ID`.
 * @param [in] args arguments array
 * @param [in] ID array index
 * @param [out] mat matrix pointer
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_value(paddle_arguments args,
                                           uint64_t ID,
                                           paddle_matrix mat);

/**
 * @brief PDArgsGetIds Get the integer vector of one argument in array, which
 *        index is `ID`.
 * @param args arguments array
 * @param ID array index
 * @param ids integer vector pointer
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_ids(paddle_arguments args,
                                         uint64_t ID,
                                         paddle_ivector ids);

/**
 * @brief PDArgsSetIds Set the integer vector of one argument in array, which
 *        index is `ID`.
 * @param [in] args arguments array
 * @param [in] ID array index
 * @param [out] ids integer vector pointer
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_set_ids(paddle_arguments args,
                                             uint64_t ID,
                                             paddle_ivector ids);

/**
 * @brief PDArgsSetSequenceStartPos Set sequence start position vector of one
 *        argument in array, which index is `ID`.
 * @param args arguments array
 * @param ID array index
 * @param seqPos sequence position array.
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_set_sequence_start_pos(
    paddle_arguments args, uint64_t ID, paddle_ivector seqPos);
/**
 * @brief PDArgsGetSequenceStartPos Get sequence start position vector of one
 *        argument in array, which index is `ID`.
 * @param [in] args arguments array
 * @param [in] ID array index
 * @param [out] seqPos sequence position array
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_sequence_start_pos(paddle_arguments args,
                                                        uint64_t ID,
                                                        paddle_ivector seqPos);

/**
 * @brief PDArgsSetSubSequenceStartPos Set sub-sequence start position vector of
 *        one argument in array, which index is `ID`.
 * @param args arguments array
 * @param ID array index
 * @param subSeqPos sub-sequence start position array.
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_set_sub_sequence_start_pos(
    paddle_arguments args, uint64_t ID, paddle_ivector subSeqPos);

/**
 * @brief PDArgsGetSubSequenceStartPos Get sub-sequence start position vector of
 *        one argument in array, which index is `ID`.
 * @param args arguments array
 * @param ID array index
 * @param subSeqPos sub-sequence start position array
 * @return paddle_error
 */
PD_API paddle_error paddle_arguments_sub_sequence_start_pos(
    paddle_arguments args, uint64_t ID, paddle_ivector subSeqPos);
/**
 * @brief GradientMachine means a neural network.
 */
typedef void* PD_GradientMachine;

/**
 * @brief PDGradientMachineCreateForPredict Create a gradient machine used for
 *        model inference.
 * @param [out] machine that used for model inference.
 * @param [in] modelConfigProtobuf
 * @param [in] size
 * @return paddle_error
 */
PD_API paddle_error PDGradientMachineCreateForPredict(
    PD_GradientMachine* machine, void* modelConfigProtobuf, int size);

/**
 * @brief PDGradientMachineLoadParameterFromDisk Load parameter from disk.
 * @param machine Gradient Machine.
 * @param path local directory path.
 * @return paddle_error
 */
PD_API paddle_error PDGradientMachineLoadParameterFromDisk(
    PD_GradientMachine machine, const char* path);

/**
 * @brief PDGradientMachineForward Forward a gradient machine
 * @param machine Gradient machine
 * @param inArgs input arguments
 * @param outArgs output arguments
 * @param isTrain is train or not
 * @return paddle_error
 */
PD_API paddle_error PDGradientMachineForward(PD_GradientMachine machine,
                                             paddle_arguments inArgs,
                                             paddle_arguments outArgs,
                                             bool isTrain);

/**
 * @brief PDGradientMachineCreateSharedParam Create a gradient machine, which
 *        parameters are shared from another gradient machine.
 * @param [in] origin gradient machine
 * @param [in] modelConfigProtobuf model config protobuf
 * @param [in] size of model config buffer.
 * @param [out] slave gradient machine, the output value.
 * @return paddle_error
 */
PD_API paddle_error
PDGradientMachineCreateSharedParam(PD_GradientMachine origin,
                                   void* modelConfigProtobuf,
                                   int size,
                                   PD_GradientMachine* slave);

/**
 * @brief PDGradientMachineDestroy Destroy a gradient machine
 * @param machine that need to destroy
 * @return paddle_error
 */
PD_API paddle_error PDGradientMachineDestroy(PD_GradientMachine machine);

/**
 * Initialize Paddle.
 */
PD_API paddle_error PDInit(int argc, char** argv);

#ifdef __cplusplus
}
#endif

#endif  // PADDLECAPI_H_