Convex_Optimization/lib_include/scocp_include/csocp.h

/**
 * @file csocp.h
 * @brief 实现主函数和宏定义。使用时只需 #include "csocp.h"
 * This file implements main functions and macros
 * @version 0.1
 * @date 2021-09-17
 * 
 * @copyright Copyright (c) 2021
 * 
 */

#ifndef __CSOCP_H__
#define __CSOCP_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "csocp_config.h"

/** 求解状态码 Solving status */
#define CSOCP_UNSTARTED 0   /**< 未求解 Solving unstarted */
#define CSOCP_OPTIMAL 1     /**< 找到最优解 Found optimal solution */
#define CSOCP_PRIMALINF 2   /**< 原问题不可行 Primal infeasible */
#define CSOCP_DUALINF 3     /**< 对偶问题不可行 Dual infeasible */
#define CSOCP_ITERLIMIT 4   /**< 到达最大迭代次数 Maximum number of iterations reached */
#define CSOCP_NUMERICAL 5   /**< 搜索方向不可靠 Search direction unreliable */
#define CSOCP_INTERRUPTED 6 /**< 求解器被中止 Solver interrupted */
#define CSOCP_UNFINISHED 7  /**< 未求解完毕 Solve not finished */
#define CSOCP_ERROR 8       /**< 求解器致命错误 Fatal error in solver */

/** double类型参数 Double parameters */
#define CSOCP_DBLPARAM_FEASTOL 1    /**< 原始问题/对偶问题的不可行容限 Primal/dual infeasibility tolerance */
#define CSOCP_DBLPARAM_ABSTOL 2     /**< 对偶间隙的绝对容限 Absolute tolerance on duality gap */
#define CSOCP_DBLPARAM_RELTOL 3     /**< 对偶间隙的相对容限 Relative tolerance on duality gap */
#define CSOCP_DBLPARAM_IRFACT 4     /**< IR误差系数 Factor of IR error */
#define CSOCP_DBLPARAM_LINSYSTOL 5  /**< 线性系统容差 Linear system tolerance */
#define CSOCP_DBLPARAM_DELTASTAT 6  /**< 静态正则化参数 Static regularization parameter */
#define CSOCP_DBLPARAM_DELTA 7      /**< 动态正则化参数 Dynamic regularization parameter */
#define CSOCP_DBLPARAM_EPSILON 8    /**< epsilon容差 Epsilon tolerance */
#define CSOCP_DBLPARAM_SCALETOL 9   /**< 缩放容差 Scaling tolerance */
#define CSOCP_DBLPARAM_GAMMA 10     /**< 步长缩放系数 Scaling factor of step length */
#define CSOCP_DBLPARAM_STEPMIN 11   /**< 允许的最小步长 Smallest step allowed */
#define CSOCP_DBLPARAM_STEPMAX 12   /**< 允许的最大步长 Largest step allowed */
#define CSOCP_DBLPARAM_SIGMAMIN 13  /**< 始终进行中心化的参数 Always do some centering */
#define CSOCP_DBLPARAM_SIGMAMAX 14  /**< 始终不完全中心化的参数 Never fully center */

/** integer类型参数 Integer parameters */
#define CSOCP_INTPARAM_ITERLIMIT 1 /**< 最大迭代次数 Maximal number of iterations */
#define CSOCP_INTPARAM_IRITER 2    /**< IR步数量 Number of IR steps */
#define CSOCP_INTPARAM_SCALEITER 3 /**< 缩放迭代次数 Number of scaling iterations */

/** double类型属性 Double attributes */
#define CSOCP_DBLATTR_PRIMALOBJ 1    /**< 原问题目标函数值 Primal objective value */
#define CSOCP_DBLATTR_DUALOBJ 2      /**< 对偶问题目标函数值 Dual objective value */
#define CSOCP_DBLATTR_PRIMALRES 3    /**< 原始残差 Primal residual */
#define CSOCP_DBLATTR_DUALRES 4      /**< 对偶残差 Dual residual */
#define CSOCP_DBLATTR_PRIMALINFRES 5 /**< 原始不可行性残差 Primal residual of infeasibilities */
#define CSOCP_DBLATTR_DUALINFRES 6   /**< 对偶不可行性残差 Dual residual of infeasibilities */
#define CSOCP_DBLATTR_ABSGAP 7       /**< 绝对间隙 Absolute gap */
#define CSOCP_DBLATTR_RELGAP 8       /**< 相对间隙 Relative gap */
#define CSOCP_DBLATTR_LOADTIME 9     /**< 加载时间 Loading time */
#define CSOCP_DBLATTR_SOLVETIME 10   /**< 求解时间 Solving time */

/** integer类型属性 Integer attributes */
#define CSOCP_INTATTR_STATUS 1  /**< 求解状态 Solving status */
#define CSOCP_INTATTR_ISPINF 2  /**< 是否原问题不可行 Is primal infeasible */
#define CSOCP_INTATTR_ISDINF 3  /**< 是否对偶问题不可行 Is dual infeasible */
#define CSOCP_INTATTR_ITERCNT 4 /**< 迭代次数计数 Iteration counts */

/** 创建优化问题 Create problem */
c_int CSOCP_create(csocp_prob **p_prob);

/** 建立二阶锥优化问题 Set up SOCP problem */
c_int CSOCP_loadsocp(csocp_prob *prob, /**< CSOCP优化问题结构体 The CSOCP problem */
                     c_int n,          /**< 变量数量 Number of variables */
                     c_int m,          /**< 不等式约束数量 Number of inequalities */
                     c_int p,          /**< 等式约束数量 Number of equalities */
                     c_int l,          /**< 线性锥（非负象限）数量 Number of positive orthant */
                     c_int ncones,     /**< 二阶锥数量 Number of SOC cones */
                     c_int *q,         /**< 指针：二阶锥维度 Dimension for each SOC cone */
                     c_real *Gpr,      /**< 不等式约束矩阵G的element指针 Element pointer of inequality matrix */
                     c_int *Gjc,       /**< 不等式约束矩阵G的begin指针 Begin pointer of inequality matrix */
                     c_int *Gir,       /**< 不等式约束矩阵G的index指针 Index pointer of inequality matrix */
                     c_real *Apr,      /**< 等式约束矩阵A的element指针 Element pointer of equality matrix */
                     c_int *Ajc,       /**< 等式约束矩阵A的begin指针 Begin pointer of equality matrix */
                     c_int *Air,       /**< 等式约束矩阵A的index指针 Index pointer of equality matrix */
                     c_real *c,        /**< 目标函数向量c Objective costs */
                     c_real *h,        /**< 不等式约束（锥约束）的右端项 RHS of cones */
                     c_real *b         /**< 等式约束的右端项 RHS of equalities */
);

/** 建立二次优化问题 Set up QP problem */
c_int CSOCP_loadqp(csocp_prob *prob,    /**< CSOCP优化问题结构体 The CSOCP problem */
                   c_int nCol,          /**< 变量数量 Number of variables */
                   c_int nIneqRow,      /**< 不等式约束数量 Number of inequalities */
                   c_int nEqRow,        /**< 等式约束数量 Number of equalities */
                   c_int nQElem,        /**< 二次目标函数中的元素数量 Number of elements in quadratic objective */
                   c_real *colObj,      /**< 目标函数中线性部分的向量 Objective costs of linear objective */
                   c_int *qRowIdx,      /**< 二次目标函数的行索引 Row index of quadratic objective */
                   c_int *qColIdx,      /**< 二次目标函数的列索引 Column index of quadratic objective */
                   c_real *qObjElem,    /**< 二次目标函数的元素值 Elements of quadratic objective */
                   c_int *ineqMatBeg,   /**< 不等式约束矩阵的begin指针 Begin pointer of inequality matrix */
                   c_int *ineqMatIdx,   /**< 不等式约束矩阵的index指针 Index pointer of inequality matrix */
                   c_real *ineqMatElem, /**< 不等式约束矩阵的element指针 Element pointer of inequality matrix */
                   c_real *ineqRHS,     /**< 不等式约束的右端项 RHS of inequalities */
                   c_int *eqMatBeg,     /**< 等式约束矩阵的begin指针 Begin pointer of equality matrix */
                   c_int *eqMatIdx,     /**< 等式约束矩阵的index指针 Index pointer of equality matrix */
                   c_real *eqMatElem,   /**< 等式约束矩阵的element指针 Element pointer of equality matrix */
                   c_real *eqRHS,       /**< 等式约束的右端项 RHS of equalities */
                   c_real *colLower,    /**< 每一列的下界 Lower bounds of columns */
                   c_real *colUpper     /**< 每一列的上界 Upper bounds of columns */
);

/** 求解优化问题 Solve problem */
c_int CSOCP_solve(csocp_prob *prob /**< 指针：指向优化问题结构体 Pointer to problem */
);

/** 获取求解结果 Get solution */
void CSOCP_getsolution(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                       c_real *x,        /**< 原问题的解 Primal solution */
                       c_real *y,        /**< 对偶问题的解 Dual solution of equalties */
                       c_real *s,        /**< 不等式约束的松弛变量 Slack of inequalities */
                       c_real *z         /**< 不等式约束的对偶变量 Dual of inequalities */
);

/** 设置double类型的参数 Set double parameter */
void CSOCP_setdblparam(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                       c_int dblparam,   /**< double类型的参数 Double paramter */
                       c_real newval     /**< 新参数值 New value */
);

/** 设置integer类型的参数 Set integer parameter */
void CSOCP_setintparam(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                       c_int intparam,   /**< integer类型的参数 Integer parameter */
                       c_int newval      /**< 新参数值 New value */
);

/** 获取double类型的参数 Get double parameter */
c_real CSOCP_getdblparam(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                         c_int dblparam    /**< double类型的参数值 Double paramter */
);

/** 获取integer类型的参数 Get integer parameter */
c_int CSOCP_getintparam(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                        c_int intparam    /**< integer类型的参数 Integer parameter */
);

/** 获取double类型的属性 Get double attribute */
c_real CSOCP_getdblattr(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                        c_int dblattr     /**< double类型的属性 Double attribute */
);

/** 获取integer类型的属性 Get integer attribute */
c_int CSOCP_getintattr(csocp_prob *prob, /**< 指针：指向优化问题结构体 Pointer to problem */
                       c_int intattr     /**< integer类型的属性 Integer attribute */
);

/** 析构优化问题结构体 Free problem */
void CSOCP_free(csocp_prob **p_prob /**< 指针：指向优化问题结构体 Pointer to problem */
);

#ifdef __cplusplus
}
#endif

#endif