small changes to API (#12)

* code dump

* workflows

* ran formatter

* readme

* workflow

* removed old workflows

* new workflow

* c++ workflow

* C++ workflow

* new line at eof to formatter

* improved interface

* new workflow

* new workflow

* new workflow

* updated default settings

* small changes to API

Author: dance858

include/PSLP/PSLP_API.h

@@ -16,11 +16,9 @@
  * limitations under the License.
  */
 
-/* Public header containing the outward facing API. It includes all the
-   input/output data structs and the API functions.  Make sure this file is
-   somewhere appropriate and then use `#include <PSLP/"API.h"
->` to access the
-   public API. */
+/* Public header containing the outward facing API. Together with the other
+   files in the folder "PSLP", it includes the input/output data structs
+   and the API functions. */
 #ifndef PRESOLVER_H
 #define PRESOLVER_H
 
@@ -29,8 +27,8 @@ extern "C"
 {
 #endif
 
-#include "PresolveStatus.h"
-#include "Sol.h"
+#include "PSLP_sol.h"
+#include "PSLP_status.h"
 #include <stdbool.h>
 
     /* forward declaration */
@@ -69,13 +67,21 @@ extern "C"
         double *rhs;
         double *c;
 
-        // variable bounds bounds[k].lb <= x_k <= bounds[k].ub
-        // Bound *bounds;
+        // variable bounds lbs <= x <= ubs
         double *lbs;
         double *ubs;
     } PresolvedProblem;
 
-    /* struct corresponding to the presolver*/
+    /* struct corresponding to the presolver:
+         - 'stats' contains statistics about the presolving process
+         - 'stgs' contains the settings used for presolving
+         - 'prob' contains the internal problem representation used during
+            presolving
+         - 'reduced_prob' contains the presolved problem after running
+            'run_presolver'
+         - 'sol' contains the solution to the original problem after running
+            'postsolve'
+    */
     typedef struct
     {
         struct PresolveStats *stats;
@@ -85,16 +91,15 @@ extern "C"
         Solution *sol;
     } Presolver;
 
-    /* The user is responsible for freeing the settings struct using standard free.
-     */
+    /* The user is responsible for freeing the settings using 'free_settings'. */
     Settings *default_settings();
     void free_settings(Settings *stgs);
     void set_settings_true(Settings *stgs);
     void set_settings_false(Settings *stgs);
 
     /* Initialize presolver, allocate memory, and build internal data structures.
        The presolver maintains internal deep copies of Ax, Ai, Ap, lhs, rhs, lbs,
-       ubs, and c. The user is responsible for freeing this memory using
+       ubs, and c. The user is responsible for freeing the presolver using
        'free_presolver'. If the allocation fails, the function returns NULL. */
     Presolver *new_presolver(const double *Ax, const int *Ai, const int *Ap, int m,
                              int n, int nnz, const double *lhs, const double *rhs,
@@ -104,13 +109,14 @@ extern "C"
     /* Free the memory allocated for the presolver. */
     void free_presolver(Presolver *presolver);
 
-    /* Runs the presolver. At completion, the 'problem' field of the presolver
-       contains the presolved problem. */
+    /* Runs the presolver. At completion, the 'reduced_prob' field of the
+       presolver contains the presolved problem. */
     PresolveStatus run_presolver(Presolver *presolver);
 
     /* Postsolve the problem given the primal-dual solution (x, y, z) of the
        reduced problem. The optimal value of the reduced problem is 'obj'.
-       The function populates presolver->sol. */
+       The function populates presolver->sol, so if you're looking for the
+       solution to the original problem, you should look there. */
     void postsolve(Presolver *presolver, const double *x, const double *y,
                    const double *z, double obj);
 

include/PSLP/PSLP_infs.h

@@ -19,8 +19,8 @@
 #ifndef CORE_TRANSFORMATIONS_H
 #define CORE_TRANSFORMATIONS_H
 
+#include "PSLP_status.h"
 #include "Postsolver.h"
-#include "PresolveStatus.h"
 #include "Tags.h"
 #include "debug_macros.h"
 #include "glbopts.h"

include/PSLP/Sol.h include/PSLP/PSLP_sol.hinclude/PSLP/Sol.h renamed to include/PSLP/PSLP_sol.h

@@ -22,7 +22,7 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-#include "Sol.h"
+#include "PSLP_sol.h"
 #include "Tags.h"
 
 struct u16Vec;

include/PSLP/PresolveStatus.h include/PSLP/PSLP_status.hinclude/PSLP/PresolveStatus.h renamed to include/PSLP/PSLP_status.h

@@ -19,7 +19,7 @@
 #ifndef DTONS_EQ_H
 #define DTONS_EQ_H
 
-#include "PresolveStatus.h"
+#include "PSLP_status.h"
 struct Matrix;
 struct Problem;
 struct PostsolveInfo;

include/core/CoreTransformations.h

@@ -19,7 +19,7 @@
 #ifndef PARALLEL_COLS_H
 #define PARALLEL_COLS_H
 
-#include "PresolveStatus.h"
+#include "PSLP_status.h"
 
 // forward declaration
 struct Problem;

include/core/Postsolver.h

@@ -19,7 +19,7 @@
 #ifndef PARALLEL_ROWS_H
 #define PARALLEL_ROWS_H
 
-#include "PresolveStatus.h"
+#include "PSLP_status.h"
 #include "Tags.h"
 
 // forward declarations

include/explorers/DTonsEq.h

@@ -21,7 +21,7 @@
 
 #include <stdbool.h>
 
-#include "PresolveStatus.h"
+#include "PSLP_status.h"
 #include "Tags.h"
 
 struct Constraints;