Fix documentation structure and fine tune explanations

.gitignore

@@ -59,6 +59,7 @@ error_log.txt
 docs/cuopt/source/cuopt-c/lp-milp/cuopt-cli-help.txt
 docs/cuopt/source/cuopt-server/client-api/sh-cli-help.txt
 docs/cuopt/source/cuopt-server/server-api/server-cli-help.txt
+docs/cuopt/source/cuopt-cli/cuopt-cli-help.txt
 docs/cuopt/source/cuopt_spec.yaml
 python/cuopt_self_hosted/cuopt_sh_client/tests/utils/certs/*.key
 docs/cuopt/build

README.md

@@ -17,6 +17,7 @@ Review the [CONTRIBUTING.md](CONTRIBUTING.md) file for information on how to con
 - [cuopt (Python) documentation](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html)
 - [libcuopt (C++/CUDA) documentation](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html)
 - [Examples and Notebooks](https://github.com/NVIDIA/cuopt-examples)
+- [Test cuopt with Brev](https://brev.nvidia.com/launchable/deploy?launchableID=env-2qIG6yjGKDtdMSjXHcuZX12mDNJ): Examples notebooks are pulled and hosted on [Brev](https://docs.nvidia.com/brev/latest/).
 
 ## Installation
 

ci/test_wheel_cuopt.sh

@@ -49,4 +49,13 @@ cd ./datasets
 ./get_test_data.sh --solomon
 ./get_test_data.sh --tsp
 cd -
+
+RAPIDS_DATASET_ROOT_DIR="$(realpath datasets)"
+export RAPIDS_DATASET_ROOT_DIR
+
+# Run CLI tests
+timeout 10m bash ./python/libcuopt/libcuopt/tests/test_cli.sh
+
+# Run Python tests
 RAPIDS_DATASET_ROOT_DIR=./datasets timeout 30m python -m pytest --verbose --capture=no ./python/cuopt/cuopt/tests/
+

cpp/include/cuopt/linear_programming/cuopt_c.h

@@ -27,54 +27,62 @@
 extern "C" {
 #endif
 
-/* @brief A ``cuOptOptimizationProblem`` object contains a representation of
+/**
+ * @brief A ``cuOptOptimizationProblem`` object contains a representation of
  * an LP or MIP. It is created by ``cuOptCreateProblem`` or ``cuOptCreateRangedProblem``.
  * It is passed to ``cuOptSolve``. It should be destroyed using ``cuOptDestroyProblem``.
  */
 typedef void* cuOptOptimizationProblem;
 
-/* @brief A ``cuOptSolverSettings`` object contains parameter settings and other information
+/**
+ * @brief A ``cuOptSolverSettings`` object contains parameter settings and other information
  * for an LP or MIP solve. It is created by ``cuOptCreateSolverSettings``. It is passed to
  * ``cuOptSolve``. It should be destroyed using ``cuOptDestroySolverSettings``.
  */
 typedef void* cuOptSolverSettings;
 
-/* @brief A ``cuOptSolution`` object contains the solution to an LP or MIP. It is created by
+/**
+ * @brief A ``cuOptSolution`` object contains the solution to an LP or MIP. It is created by
  * ``cuOptSolve``. It should be destroyed using ``cuOptDestroySolution``.
  */
 typedef void* cuOptSolution;
 
 #if CUOPT_INSTANTIATE_FLOAT
 
-/* @brief The type of the floating point number used by the solver. Use ``cuOptGetFloatSize``
+/**
+ * @brief The type of the floating point number used by the solver. Use ``cuOptGetFloatSize``
  * to get the number of bytes in the floating point type.
  */
 typedef float cuopt_float_t;
 
 #endif
 
 #if CUOPT_INSTANTIATE_DOUBLE
-/* @brief The type of the floating point number used by the solver. Use ``cuOptGetFloatSize``
+/**
+ * @brief The type of the floating point number used by the solver. Use ``cuOptGetFloatSize``
  * to get the size of the floating point type.
  */
 typedef double cuopt_float_t;
 #endif
 
 #if CUOPT_INSTANTIATE_INT32
-/* @brief The type of the integer number used by the solver. Use ``cuOptGetIntSize``
+/**
+ * @brief The type of the integer number used by the solver. Use ``cuOptGetIntSize``
  * to get the size of the integer type.
  */
 typedef int32_t cuopt_int_t;
 #endif
 
 #if CUOPT_INSTANTIATE_INT64
-/* @brief The type of the integer number used by the solver. Use ``cuOptGetIntSize``
+/**
+ * @brief The type of the integer number used by the solver. Use ``cuOptGetIntSize``
  * to get the size of the integer type.
  */
 typedef int64_t cuopt_int_t;
 #endif
 
-/* @brief Get the size of the float type.
+/**
+ * @brief Get the size of the float type.
  *
  * @return The size in bytes of the float type.
  */
@@ -85,7 +93,8 @@ int8_t cuOptGetFloatSize();
  */
 int8_t cuOptGetIntSize();
 
-/* @brief Read an optimization problem from an MPS file.
+/**
+ * @brief Read an optimization problem from an MPS file.
  *
  * @param[in] filename - The path to the MPS file.
  *
@@ -102,7 +111,7 @@ cuopt_int_t cuOptReadProblem(const char* filename, cuOptOptimizationProblem* pro
  *                minimize/maximize  cᵀx + offset
  *                  subject to       A x {=, ≤, ≥} b
  *                                   l ≤ x ≤ u
- *                                   xᵢ ∈ ℤ for some i
+ *                                   x_i integer for some i
  * @endverbatim
  *
  * @param[in] num_constraints The number of constraints

datasets/mip/sample.mps

@@ -0,0 +1,26 @@
+* Optimal solution -28
+NAME          MIP_SAMPLE
+ROWS
+ N  OBJ
+ L  C1
+ L  C2
+ L  C3
+COLUMNS
+ MARK0001  'MARKER'                 'INTORG'
+   X1        OBJ             -7
+   X1        C1              -1
+   X1        C2               5
+   X1        C3              -2
+   X2        OBJ             -2
+   X2        C1               2
+   X2        C2               1
+   X2        C3              -2
+ MARK0001  'MARKER'                 'INTEND'
+RHS
+   RHS       C1               4
+   RHS       C2              20
+   RHS       C3              -7
+BOUNDS
+ UP BOUND     X1               10
+ UP BOUND     X2               10
+ENDATA

docs/cuopt/source/conf.py

@@ -30,7 +30,7 @@
 subprocess.run(["cuopt_sh", "--help"], stdout=open("cuopt-server/client-api/sh-cli-help.txt", "w"))
 
 # Run cuopt_cli help command and save output
-subprocess.run(["cuopt_cli", "--help"], stdout=open("cuopt-c/lp-milp/cuopt-cli-help.txt", "w"))
+subprocess.run(["cuopt_cli", "--help"], stdout=open("cuopt-cli/cuopt-cli-help.txt", "w"))
 
 with open('cuopt_spec.yaml', 'w') as f:
     yaml.dump(get_openapi(
@@ -146,6 +146,10 @@
 html_theme_options = {
     'collapse_navigation': False,
     'navigation_depth': 6,
+     "switcher": {
+        "json_url": "../versions1.json",
+        "version_match": release,
+    },
     'extra_head': [  # Adding Adobe Analytics
         '''
     <script src="https://assets.adobedtm.com/5d4962a43b79/c1061d2c5e7b/launch-191c2462b890.min.js" ></script>
@@ -159,11 +163,15 @@
     "show_nav_level": 2
 }
 
+
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["swagger-nvidia.css"]
+html_extra_path = ["project.json", "versions1.json"]
+
 
 # -- Options for Breathe (Doxygen) ----------------------------------------
 breathe_projects = {

docs/cuopt/source/cuopt-c/lp-milp/lp-example.rst

@@ -5,7 +5,7 @@ LP C API Examples
 Example With Data
 -----------------
 
-This example demonstrates how to use the cuOpt linear programming solver in C. More details on the API can be found in `C API <lp-milp-c-api.html>`_.
+This example demonstrates how to use the LP solver in C. More details on the API can be found in `C API <lp-milp-c-api.html>`_.
 
 Copy the code below into a file called ``lp_example.c``:
 
@@ -208,7 +208,7 @@ Copy the code below into a file called ``lp_example.c``:
    }
 
 
-Need to find PATH for cuopt_c.h and libcuopt.so, if you know the path, please add it to these path variables directly. Else, run the following commands to find the path and assign it to the path variables.
+It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables.
 The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system.
 
 If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``.
@@ -423,7 +423,7 @@ Copy the code below into a file called ``lp_example_mps.c``:
    }
 
 
-Need to find PATH for cuopt_c.h and libcuopt.so, if you know the path, please add it to these path variables directly. Else, run the following commands to find the path and assign it to the path variables.
+It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables.
 The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system.
 
 If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``.
@@ -494,53 +494,3 @@ You should see the following output:
    x2 = 0.000000
 
    Solver completed successfully!
-
-
-Example for CLI with MPS file
-------------------------------
-
-This example demonstrates how to use the cuOpt CLI to solve an MPS file and how to set the parameters for the solver.
-
-.. code-block:: bash
-
-   echo "* optimize
-   *  cost = -0.2 * VAR1 + 0.1 * VAR2
-   * subject to
-   *  3 * VAR1 + 4 * VAR2 <= 5.4
-   *  2.7 * VAR1 + 10.1 * VAR2 <= 4.9
-   NAME   good-1
-   ROWS
-    N  COST
-    L  ROW1
-    L  ROW2
-   COLUMNS
-      VAR1      COST      -0.2
-      VAR1      ROW1      3              ROW2      2.7  
-      VAR2      COST      0.1
-      VAR2      ROW1      4              ROW2      10.1
-   RHS
-      RHS1      ROW1      5.4            ROW2      4.9
-   ENDATA" > sample.mps
-
-   # Solve the MPS file with the additional parameter settings
-   cuopt_cli sample.mps --absolute-primal-tolerance 0.0001 --pdlp-solver-mode 1 --time-limit 5
-
-
-This should give you the following output:
-
-.. code-block:: bash
-   :caption: Output
-
-   [2025-05-17 15:22:16:143587] [CUOPT] [info  ] Running file sample.mps
-   Solving a problem with 2 constraints 2 variables (0 integers) and 4 nonzeros
-   Objective offset 0.000000 scaling_factor 1.000000
-   Running concurrent
-
-   Dual simplex finished in 0.00 seconds
-      Iter    Primal Obj.      Dual Obj.    Gap        Primal Res.  Dual Res.   Time
-         0 +0.00000000e+00 +0.00000000e+00  0.00e+00   0.00e+00     2.00e-01   0.011s
-   PDLP finished
-   Concurrent time:  0.012s
-   Solved with dual simplex
-   Status: Optimal   Objective: -3.60000000e-01  Iterations: 1  Time: 0.012s
-