document scs.wasm (#304)

Author: DominikPeters

docs/src/api/index.rst

@@ -42,6 +42,8 @@ SCS is written in raw C code, with interfaces for several other languages.
 
 :ref:`Ruby <ruby_interface>`
 
+:ref:`JavaScript / WebAssembly <javascript_interface>`
+
 .. toctree::
    :maxdepth: 2
    :hidden:
@@ -52,3 +54,4 @@ SCS is written in raw C code, with interfaces for several other languages.
    julia.rst
    r.rst
    ruby.rst
+   javascript.rst

docs/src/api/javascript.rst

@@ -0,0 +1,190 @@
+.. _javascript_interface:
+
+JavaScript / WebAssembly
+========================
+
+After :ref:`installing the scs-solver package <javascript_install>`, or after 
+loading ``scs.js`` :ref:`in the browser <javascript_install>`, you can use SCS
+using the following interface.
+
+Instantiating the Solver
+------------------------
+
+In Node.js, you can use SCS as follows using CommonJS:
+
+.. code-block:: javascript
+
+    const createSCS = require('scs-solver');
+
+    createSCS().then(SCS => {
+        // define problem here
+        SCS.solve(data, cone, settings);
+    });
+
+Alternatively, you can use ES6 modules, as well as async/await:
+
+.. code-block:: javascript
+
+    import createSCS from 'scs-solver';
+
+    async function main() {
+        const SCS = await createSCS();
+        // define problem here
+        SCS.solve(data, cone, settings);
+    }
+
+    main();
+
+In browsers, you can load SCS using a script tag:
+
+.. code-block:: html
+
+    <script src="https://unpkg.com/scs-solver/dist/scs.js"></script>
+    <script>
+        createSCS().then(SCS => {
+            // define problem here
+            SCS.solve(data, cone, settings);
+        });
+    </script>
+
+Data Format
+-----------
+
+Problem data must be provided as sparse matrices in CSC format using the following structure:
+
+.. code-block:: javascript
+
+    const data = {
+        m: number,     // Number of rows of A
+        n: number,     // Number of cols of A and of P
+        A_x: number[], // Non-zero elements of matrix A
+        A_i: number[], // Row indices of A elements
+        A_p: number[], // Column pointers for A
+        P_x: number[], // Non-zero elements of matrix P (optional)
+        P_i: number[], // Row indices of P elements (optional)
+        P_p: number[], // Column pointers for P (optional)
+        b: number[],   // Length m array
+        c: number[]    // Length n array
+    };
+
+One way to handle the CSC format in javascript is via the 
+`Math.js library <https://mathjs.org/docs/reference/classes/sparsematrix.html>`_,
+for example
+
+.. code-block:: javascript
+
+    // npm install mathjs
+    const { matrix } = require('mathjs');
+    // or import { matrix } from 'mathjs';
+    // or <script src="https://unpkg.com/[email protected]/lib/browser/math.js"></script>
+
+    const A = matrix([
+        [1, 0],
+        [0, 1],
+        [1, 1]
+    ], 'sparse');
+
+    const P = matrix([
+        [3, 0],
+        [0, 2]
+    ], 'sparse');
+
+    const data = {
+        m: 3,
+        n: 2,
+        A_x: A._values,
+        A_i: A._index,
+        A_p: A._ptr,
+        P_x: P._values,
+        P_i: P._index,
+        P_p: P._ptr,
+        b: [-1.0, 0.3, -0.5],
+        c: [-1.0, -1.0]
+    };
+
+Cone Specification
+------------------
+
+Cones are specified using the following structure:
+
+.. code-block:: javascript
+
+    const cone = {
+        z: number,     // Number of zero cones
+        l: number,     // Number of positive (or linear) cones
+        bu: number[],  // Box cone upper values
+        bl: number[],  // Box cone lower values
+        bsize: number, // Total length of box cone
+        q: number[],   // Array of second-order cone lengths
+        qsize: number, // Number of second-order cones
+        ep: number,    // Number of primal exponential cone triples
+        ed: number,    // Number of dual exponential cone triples
+        p: number[],   // Array of power cone parameters
+        psize: number  // Number of power cone triples
+    };
+
+Note that positive semidefinite cones are not supported in the JavaScript interface.
+
+Usually, not all cone types are used in a problem, in which case the unused 
+cones can be omitted. For example, if only zero and positive cones are used:
+
+.. code-block:: javascript
+
+    const cone = {
+        z: 1,
+        l: 2
+    };
+
+Settings
+--------
+
+Control solver behavior using settings:
+
+.. code-block:: javascript
+
+    const settings = new Module.ScsSettings();
+    Module.setDefaultSettings(settings);
+
+Available settings:
+
+- ``normalize`` (boolean): Heuristically rescale problem data
+- ``scale`` (number): Initial dual scaling factor
+- ``adaptiveScale`` (boolean): Whether to adaptively update scale
+- ``rhoX`` (number): Primal constraint scaling factor
+- ``maxIters`` (number): Maximum iterations to take
+- ``epsAbs`` (number): Absolute convergence tolerance
+- ``epsRel`` (number): Relative convergence tolerance
+- ``epsInfeas`` (number): Infeasible convergence tolerance
+- ``alpha`` (number): Douglas-Rachford relaxation parameter
+- ``timeLimitSecs`` (number): Time limit in seconds
+- ``verbose`` (number): Output level (0-3)
+- ``warmStart`` (boolean): Use warm starting
+
+Solving Problems
+----------------
+
+Use the ``solve`` function to solve optimization problems:
+
+.. code-block:: javascript
+
+    const solution = Module.solve(data, cone, settings, [warmStartSolution]);
+
+The function takes an optional ``warmStartSolution`` object to warm-start the solver,
+provided ``settings.warmStart`` is set to ``true``.
+
+The returned ``solution`` object contains:
+
+- ``x``: Primal variables
+- ``y``: Dual variables
+- ``s``: Slack variables
+- ``info``: Solver information
+
+    - ``iter``: Number of iterations
+    - ``pobj``: Primal objective
+    - ``dobj``: Dual objective
+    - ``solveTime``: Solve time
+    - and :ref:`other solver information <info>`
+    
+- ``status``: Solution status (e.g. ``SOLVED``, ``INFEASIBLE``, ``UNBOUNDED``, see :ref:`exit flags <exit_flags>`)
+- ``statusVal``: Solution status value (see :ref:`exit flags <exit_flags>`)
+

docs/src/examples/index.rst

@@ -17,6 +17,8 @@ Here we present a few simple examples of calling SCS from different languages.
 
 :ref:`Ruby <ruby_example>`
 
+:ref:`JavaScript / WebAssembly <javascript_example>`
+
 .. toctree::
    :maxdepth: 2
    :hidden:
@@ -27,4 +29,5 @@ Here we present a few simple examples of calling SCS from different languages.
    julia.rst
    r.rst
    ruby.rst
+   javascript.rst