Under the hood API refactoring

.github/workflows/build.yml

@@ -5,12 +5,17 @@ on: [push, pull_request]
 
 jobs:
   linux:
+    strategy:
+      fail-fast: false
+      matrix:
+        long: [0, 1]
+
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - run: sudo apt-get install libopenblas-dev liblapack-dev
-      - run: make
-      - run: make test
+      - run: make DLONG=${{ matrix.long }}
+      - run: make test DLONG=${{ matrix.long }}
       - run: out/run_tests_direct    # test direct solver
       - run: out/run_tests_indirect  # test indirect solver
 
@@ -23,11 +28,16 @@ jobs:
   #    - run: test/run_tests
 
   mac:
+    strategy:
+      fail-fast: false
+      matrix:
+        long: [0, 1]
+
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v2
       - run: brew install openblas lapack
-      - run: make
-      - run: make test
+      - run: make DLONG=${{ matrix.long }}
+      - run: make test DLONG=${{ matrix.long }}
       - run: out/run_tests_direct    # test direct solver
       - run: out/run_tests_indirect  # test indirect solver

.gitignore

@@ -49,3 +49,4 @@ out
 *.jar
 hs21_tiny_qp
 rob_gauss_cov_est
+build/

CMakeLists.txt

@@ -88,13 +88,57 @@ if(BUILD_TESTING)
   enable_testing()
 endif()
 
+# Add uninstall target
+# After 'make install' can run 'make uninstall' to remove.
+include(AddUninstallTarget)
+
 ### Some variables useful for sampling the building process
 # Note that the GPU profile is not compiled.
 set(LINSYS linsys)
 set(DIRSRC ${LINSYS}/cpu/direct)
 set(INDIRSRC ${LINSYS}/cpu/indirect)
 set(EXTERNAL ${LINSYS}/external)
 
+# Options
+# ----------------------------------------------
+# Use floats instead of doubles
+option(SFLOAT "Use single precision floats rather than doubles" OFF)
+message(STATUS "Single precision floats (32bit) are ${SFLOAT}")
+
+# Use long integers for indexing
+option(DLONG "Use long integers (64bit) for indexing" OFF)
+message(STATUS "Long integers (64bit) are ${DLONG}")
+
+
+set(COMPILER_OPTS "-DUSE_LAPACK -DCOPYAMATRIX -DCTRLC")
+
+# Primitive types
+if(SFLOAT)
+  set(SCS_FLOAT_TYPE "float")
+  set(COMPILER_OPTS "-DSFLOAT ${COMPILER_OPTS}")
+else()
+  set(SCS_FLOAT_TYPE "double")
+endif()
+
+if(DLONG)
+  set(SCS_INT_TYPE "long long")
+  set(COMPILER_OPTS "-DDLONG ${COMPILER_OPTS}")
+else()
+  set(SCS_INT_TYPE "int")
+endif()
+
+message(STATUS "COMPILER_OPTS = ${COMPILER_OPTS}")
+
+# TODO this is a hack that overwrites the scs_types.h file, we should
+# find a way to do this that doesn't pollute the master directory.
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/scs_types.h.in
+               ${CMAKE_CURRENT_SOURCE_DIR}/include/scs_types.h
+               NEWLINE_STYLE LF)
+
+# Public headers 
+set(${PROJECT_NAME}_PUBLIC_HDR
+  include/scs_types.h
+  include/scs.h)
 
 # Common source files
 set(${PROJECT_NAME}_SRC
@@ -122,6 +166,8 @@ set(${PROJECT_NAME}_HDR
   include/rw.h
   include/scs.h
   include/scs_blas.h
+  include/scs_types.h
+  include/scs_work.h
   include/util.h
   ${LINSYS}/csparse.h
   ${LINSYS}/scs_matrix.h)
@@ -162,7 +208,7 @@ target_include_directories(${${PROJECT_NAME}_DIRECT} PUBLIC
   "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/scs>")
 
 # Compiled with blas and lapack, can solve LPs, SOCPs, SDPs, ECPs, and PCPs
-target_compile_definitions(${${PROJECT_NAME}_DIRECT} PRIVATE -DUSE_LAPACK -DCOPYAMATRIX -DCTRLC)
+target_compile_definitions(${${PROJECT_NAME}_DIRECT} PRIVATE ${COMPILER_OPTS})
 
 # The library depends on math (m) blas and lapack
 target_link_libraries(${${PROJECT_NAME}_DIRECT} PRIVATE
@@ -173,7 +219,7 @@ target_link_libraries(${${PROJECT_NAME}_DIRECT} PRIVATE
 # Set some properties
 set_target_properties(${${PROJECT_NAME}_DIRECT} PROPERTIES
   VERSION ${scs_VERSION}
-  PUBLIC_HEADER "${${PROJECT_NAME}_HDR}")
+  PUBLIC_HEADER "${${PROJECT_NAME}_PUBLIC_HDR}")
 
 add_library(scs::${${PROJECT_NAME}_DIRECT} ALIAS ${${PROJECT_NAME}_DIRECT})
 
@@ -209,7 +255,7 @@ target_include_directories(${${PROJECT_NAME}_INDIRECT} PUBLIC
   "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/scs>")
 
 # Compiled with blas and lapack, can solve LPs, SOCPs, SDPs, ECPs, and PCPs
-target_compile_definitions(${${PROJECT_NAME}_INDIRECT} PRIVATE -DUSE_LAPACK -DCOPYAMATRIX -DCTRLC -DINDIRECT)
+target_compile_definitions(${${PROJECT_NAME}_INDIRECT} PRIVATE ${COMPILER_OPTS} -DINDIRECT)
 
 # The library depends on math (m) blas and lapack
 target_link_libraries(${${PROJECT_NAME}_INDIRECT} PUBLIC
@@ -220,7 +266,7 @@ target_link_libraries(${${PROJECT_NAME}_INDIRECT} PUBLIC
 # Set some properties
 set_target_properties(${${PROJECT_NAME}_INDIRECT} PROPERTIES
   VERSION ${scs_VERSION}
-  PUBLIC_HEADER "${${${PROJECT_NAME}_INDIRECT}_HDR}")
+  PUBLIC_HEADER "${${PROJECT_NAME}_PUBLIC_HDR}")
 
 add_library(scs::${${PROJECT_NAME}_INDIRECT} ALIAS ${${PROJECT_NAME}_INDIRECT})
 
@@ -250,20 +296,22 @@ install_basic_package_files(${PROJECT_NAME}
 ### Add the tests
 if(BUILD_TESTING)
   add_executable(run_tests_direct  test/run_tests.c)
+  target_compile_definitions(run_tests_direct PRIVATE ${COMPILER_OPTS})
   target_link_libraries(run_tests_direct PRIVATE
     scs::scsdir)
   target_include_directories(run_tests_direct PRIVATE
-    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/test;${CMAKE_CURRENT_SOURCE_DIR}/include;${CMAKE_CURRENT_SOURCE_DIR}/${LINSYS}>")
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/test;${CMAKE_CURRENT_SOURCE_DIR}/include;${CMAKE_CURRENT_SOURCE_DIR}/${LINSYS}>"  )
 
   add_test(NAME run_tests_direct
     COMMAND run_tests_direct
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
 
   add_executable(run_tests_indirect  test/run_tests.c)
+  target_compile_definitions(run_tests_indirect PRIVATE ${COMPILER_OPTS})
   target_link_libraries(run_tests_indirect PRIVATE
     scs::scsindir)
   target_include_directories(run_tests_indirect PRIVATE
-    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/test;${CMAKE_CURRENT_SOURCE_DIR}/include;${CMAKE_CURRENT_SOURCE_DIR}/${LINSYS}>")
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/test;${CMAKE_CURRENT_SOURCE_DIR}/include;${CMAKE_CURRENT_SOURCE_DIR}/${LINSYS}>"  )
 
   add_test(NAME run_tests_indirect
     COMMAND run_tests_indirect

Makefile

@@ -39,13 +39,13 @@ $(SCS_INDIR_O): src/scs.c $(INC_FILES)
 %.o : src/%.c
 	$(CC) $(CFLAGS) -c $< -o $@
 
-src/util.o	: src/util.c include/util.h include/glbopts.h
-src/cones.o	: src/cones.c include/cones.h include/scs_blas.h
-src/aa.o	: src/aa.c include/aa.h include/scs_blas.h
-src/rw.o	: src/rw.c include/rw.h
-src/linalg.o: src/linalg.c include/linalg.h
-src/ctrl.o  : src/ctrl.c include/ctrl.h
-src/scs_version.o: src/scs_version.c include/glbopts.h
+src/util.o	: src/util.c $(INC_FILES)
+src/cones.o	: src/cones.c $(INC_FILES)
+src/aa.o	: src/aa.c $(INC_FILES)
+src/rw.o	: src/rw.c $(INC_FILES)
+src/linalg.o: src/linalg.c $(INC_FILES)
+src/ctrl.o  : src/ctrl.c $(INC_FILES)
+src/scs_version.o: src/scs_version.c $(INC_FILES)
 
 $(DIRSRC)/private.o: $(DIRSRC)/private.c  $(DIRSRC)/private.h
 $(INDIRSRC)/indirect/private.o: $(INDIRSRC)/private.c $(INDIRSRC)/private.h

cmake/scs_types.h.in

@@ -0,0 +1,22 @@
+/*
+ * GENERATED BY CMAKE
+ */
+
+/*
+ * Definitions of primitive types used in SCS.
+ */
+
+#ifndef SCS_TYPES_H_GUARD
+#define SCS_TYPES_H_GUARD
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef @SCS_INT_TYPE@    scs_int;
+typedef @SCS_FLOAT_TYPE@  scs_float;
+
+#ifdef __cplusplus
+}
+#endif
+#endif

docs/src/api/c.rst

@@ -42,6 +42,8 @@ specified in the :ref:`settings` page.
 Primitive types
 ---------------
 
+These are defined in header file :code:`scs_types.h`.
+
 * :code:`scs_int`: is :code:`long` if the :ref:`compiler flag <compile_flags>` :code:`DLONG` is set, otherwise it is :code:`int`
 * :code:`scs_float`: is :code:`float` if the :ref:`compiler flag <compile_flags>` :code:`SFLOAT` is set, otherwise it is :code:`double`
 
@@ -125,6 +127,3 @@ Workspace
 The user should not need to interact with the :code:`ScsWork` struct,
 which contains the internal workspace allocated and maintained by SCS.
 
-.. doxygenstruct:: ScsWork
-   :members:
-

docs/src/api/compile_flags.rst

@@ -23,7 +23,7 @@ executing, e.g., :code:`make DLONG=1`, to set the :code:`DLONG` flag to True.
      - True/False
      - 0
    * - :code:`SFLOAT`
-     - If True use 32 bit floats, else 64 bit
+     - If True use 32 bit floats, else 64 bit (WARNING: currently broken)
      - True/False
      - 0
    * - :code:`CTRLC`

docs/src/api/exit_flags.rst

@@ -2,7 +2,8 @@
 
 Exit flags
 -----------
-The integer values that SCS can return are documented below.
+The integer values that SCS can return are documented below and are defined
+in the :code:`'include/scs.h` file.
 
 .. list-table::
    :widths: 50 10 40

docs/src/examples/qp.c

@@ -1,4 +1,6 @@
-#include "scs.h" /* SCS API */
+#include "scs.h"    /* SCS API */
+#include <stdio.h>  /* printf */
+#include <stdlib.h> /* memory allocation */
 
 /* Set up and solve basic qp */
 int main(int argc, char **argv) {

docs/src/examples/qp.c.out

@@ -13,12 +13,12 @@ lin-sys:  sparse-direct
 ------------------------------------------------------------------
  iter | pri res | dua res |   gap   |   obj   |  scale  | time (s)
 ------------------------------------------------------------------
-     0| 1.78e+00  1.00e+00  1.42e+00 -1.04e+00  1.00e-01  2.28e-05 
-   175| 3.34e-11  4.17e-10  4.07e-10  1.24e+00  2.08e+01  4.26e-04 
+     0| 1.78e+00  1.00e+00  1.42e+00 -1.04e+00  1.00e-01  2.14e-05 
+   175| 3.34e-11  4.17e-10  4.07e-10  1.24e+00  2.08e+01  1.25e-04 
 ------------------------------------------------------------------
 status:  solved
-timings: total: 1.17e-03s = setup: 7.40e-04s + solve: 4.28e-04s
-	 lin-sys: 3.06e-05s, cones: 1.57e-05s, accel: 2.42e-05s
+timings: total: 2.01e-04s = setup: 7.52e-05s + solve: 1.26e-04s
+	 lin-sys: 2.56e-05s, cones: 1.43e-05s, accel: 2.20e-05s
 ------------------------------------------------------------------
 objective = 1.235000
 ------------------------------------------------------------------

docs/src/install/c.rst

@@ -35,6 +35,15 @@ project, please call the following command
   make
   ctest
 
+Some :ref:`compile flags <compile_flags>` can be overridden using the
+command line, for example we can compile the library (and headers) to use 64 bit
+integers using:
+
+.. code:: bash
+
+  cmake -DCMAKE_INSTALL_PREFIX:PATH=<custom-folder> -DDLONG=ON ../
+  make
+
 By default the build-system will compile the library as shared. If you want to
 compile it as static, please call the following command when you configure the
 project
@@ -45,8 +54,9 @@ project
   make
 
 The CMake build-system exports two CMake targets called :code:`scs::scsdir` and
-:code:`scs::scsindir` which can be imported using the find_package CMake command and
-used by calling target_link_libraries as in the following example:
+:code:`scs::scsindir` as well as a header file `scs.h` that defines the API. The
+libraries can be imported using the find_package CMake command and used by
+calling target_link_libraries as in the following example:
 
 .. code:: bash
 

include/aa.h

@@ -23,7 +23,7 @@ typedef struct ACCEL_WORK AaWork;
  * @param type1             if True use type 1 AA, otherwise use type 2
  * @param regularization    type-I and type-II different, for type-I: 1e-8 works
  *                          well, type-II: more stable can use 1e-12 often
- * @param relaxation        float \in [0,2], mixing parameter (1.0 is vanilla)
+ * @param relaxation        float in [0,2], mixing parameter (1.0 is vanilla)
  * @param safeguard_factor  factor that controls safeguarding checks
  *                          larger is more aggressive but less stable
  * @param max_weight_norm   float, maximum norm of AA weights

include/cones.h

@@ -8,6 +8,8 @@ extern "C" {
 #include "glbopts.h"
 #include "scs.h"
 #include "scs_blas.h"
+#include "scs_work.h"
+#include <string.h>
 
 /* private data to help cone projection step */
 struct SCS_CONE_WORK {