<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>C API — CVXOPT User's Guide</title> <link rel="stylesheet" href="_static/cvxopt.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '#', VERSION: '1.1.1', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: false }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="copyright" title="Copyright" href="copyright.html" /> <link rel="top" title="CVXOPT User's Guide" href="index.html" /> <link rel="next" title="Matrix Formatting" href="printing.html" /> <link rel="prev" title="Modeling" href="modeling.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="printing.html" title="Matrix Formatting" accesskey="N">next</a></li> <li class="right" > <a href="modeling.html" title="Modeling" accesskey="P">previous</a> |</li> <li><a href="http://abel.ee.ucla.edu/cvxopt">CVXOPT home</a> |</li> <li><a href="index.html">user's guide</a> </li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="c-api"> <span id="c-capi"></span><h1>C API<a class="headerlink" href="#c-api" title="Permalink to this headline">¶</a></h1> <p>The API can be used to extend CVXOPT with interfaces to external C routines and libraries. A C program that creates or manipulates the dense or sparse matrix objects defined in CVXOPT must include the <tt class="xref docutils literal"><span class="pre">cvxopt.h</span></tt> header file in the <tt class="xref docutils literal"><span class="pre">src</span></tt> directory of the distribution.</p> <p>Before the C API can be used in an extension module it must be initialized by calling the macro <tt class="xref docutils literal"><span class="pre">import_cvxopt</span></tt>. As an example we show the module initialization from the <tt class="xref docutils literal"><span class="pre">cvxopt.blas</span></tt> module, which itself uses the API:</p> <div class="highlight-c"><div class="highlight"><pre><span class="n">PyMODINIT_FUNC</span> <span class="nf">initblas</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">m</span><span class="p">;</span> <span class="n">m</span> <span class="o">=</span> <span class="n">Py_InitModule3</span><span class="p">(</span><span class="s">"cvxopt.blas"</span><span class="p">,</span> <span class="n">blas_functions</span><span class="p">,</span> <span class="n">blas__doc__</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="n">import_cvxopt</span><span class="p">()</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> <div class="section" id="dense-matrices"> <h2>Dense Matrices<a class="headerlink" href="#dense-matrices" title="Permalink to this headline">¶</a></h2> <p>As can be seen from the header file <tt class="xref docutils literal"><span class="pre">cvxopt.h</span></tt>, a <tt class="xref docutils literal"><span class="pre">matrix</span></tt> is essentially a structure with four fields. The fields <tt class="xref docutils literal"><span class="pre">nrows</span></tt> and <tt class="xref docutils literal"><span class="pre">ncols</span></tt> are two integers that specify the dimensions. The <tt class="xref docutils literal"><span class="pre">id</span></tt> field controls the type of the matrix and can have values <tt class="xref docutils literal"><span class="pre">DOUBLE</span></tt>, <tt class="xref docutils literal"><span class="pre">INT</span></tt>, and <tt class="xref docutils literal"><span class="pre">COMPLEX</span></tt>. The <tt class="xref docutils literal"><span class="pre">buffer</span></tt> field is an array that contains the matrix elements stored contiguously in column-major order.</p> <p>The following C functions can be used to create matrices.</p> <dl class="cfunction"> <dt id="Matrix_New"> matrix * <tt class="descname">Matrix_New</tt><big>(</big>int<em> nrows</em>, int<em> ncols</em>, int<em> id</em><big>)</big><a class="headerlink" href="#Matrix_New" title="Permalink to this definition">¶</a></dt> <dd>Returns a <tt class="xref docutils literal"><span class="pre">matrix</span></tt> object of type <cite>id</cite> with <cite>nrows</cite> rows and <cite>ncols</cite> columns. The elements of the matrix are uninitialized.</dd></dl> <dl class="cfunction"> <dt id="Matrix_NewFromMatrix"> matrix * <tt class="descname">Matrix_NewFromMatrix</tt><big>(</big>matrix<em> *src</em>, int<em> id</em><big>)</big><a class="headerlink" href="#Matrix_NewFromMatrix" title="Permalink to this definition">¶</a></dt> <dd>Returns a copy of the matrix <cite>src</cite> converted to type <cite>id</cite>. The following type conversions are allowed: <tt class="xref docutils literal"><span class="pre">'i'</span></tt> to <tt class="xref docutils literal"><span class="pre">'d'</span></tt>, <tt class="xref docutils literal"><span class="pre">'i'</span></tt> to <tt class="xref docutils literal"><span class="pre">'z'</span></tt>, and <tt class="xref docutils literal"><span class="pre">'d'</span></tt> to <tt class="xref docutils literal"><span class="pre">'z'</span></tt>.</dd></dl> <dl class="cfunction"> <dt id="Matrix_NewFromSequence"> matrix * <tt class="descname">Matrix_NewFromSequence</tt><big>(</big>PyListObject<em> *x</em>, int<em> id</em><big>)</big><a class="headerlink" href="#Matrix_NewFromSequence" title="Permalink to this definition">¶</a></dt> <dd>Creates a matrix of type <cite>id</cite> from the Python sequence type <cite>x</cite>. The returned matrix has size <tt class="docutils literal"><span class="pre">(len(x),</span> <span class="pre">1)</span></tt>. The size can be changed by modifying the <tt class="xref docutils literal"><span class="pre">nrows</span></tt> and <tt class="xref docutils literal"><span class="pre">ncols</span></tt> fields of the returned matrix.</dd></dl> <p>To illustrate the creation and manipulation of dense matrices (as well as the Python C API), we show the code for the <a title="cvxopt.uniform" class="reference external" href="matrices.html#cvxopt.uniform"><tt class="xref docutils literal"><span class="pre">cvxopt.uniform</span></tt></a> function described in the section <a class="reference external" href="matrices.html#s-random"><em>Randomly Generated Matrices</em></a>.</p> <div class="highlight-c"><div class="highlight"><pre><span class="n">PyObject</span> <span class="o">*</span> <span class="nf">uniform</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">kwrds</span><span class="p">)</span> <span class="p">{</span> <span class="n">matrix</span> <span class="o">*</span><span class="n">obj</span><span class="p">;</span> <span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="n">nrows</span><span class="p">,</span> <span class="n">ncols</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="kt">double</span> <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="kt">char</span> <span class="o">*</span><span class="n">kwlist</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="s">"nrows"</span><span class="p">,</span> <span class="s">"ncols"</span><span class="p">,</span> <span class="s">"a"</span><span class="p">,</span> <span class="s">"b"</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">};</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyArg_ParseTupleAndKeywords</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">kwrds</span><span class="p">,</span> <span class="s">"i|idd"</span><span class="p">,</span> <span class="n">kwlist</span><span class="p">,</span> <span class="o">&</span><span class="n">nrows</span><span class="p">,</span> <span class="o">&</span><span class="n">ncols</span><span class="p">,</span> <span class="o">&</span><span class="n">a</span><span class="p">,</span> <span class="o">&</span><span class="n">b</span><span class="p">))</span> <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> <span class="k">if</span> <span class="p">((</span><span class="n">nrows</span><span class="o"><</span><span class="mi">0</span><span class="p">)</span> <span class="o">||</span> <span class="p">(</span><span class="n">ncols</span><span class="o"><</span><span class="mi">0</span><span class="p">))</span> <span class="p">{</span> <span class="n">PyErr_SetString</span><span class="p">(</span><span class="n">PyExc_TypeError</span><span class="p">,</span> <span class="s">"dimensions must be non-negative"</span><span class="p">);</span> <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> <span class="p">}</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="p">(</span><span class="n">obj</span> <span class="o">=</span> <span class="n">Matrix_New</span><span class="p">(</span><span class="n">nrows</span><span class="p">,</span> <span class="n">ncols</span><span class="p">,</span> <span class="n">DOUBLE</span><span class="p">)))</span> <span class="k">return</span> <span class="n">PyErr_NoMemory</span><span class="p">();</span> <span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">nrows</span><span class="o">*</span><span class="n">ncols</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="n">MAT_BUFD</span><span class="p">(</span><span class="n">obj</span><span class="p">)[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">Uniform</span><span class="p">(</span><span class="n">a</span><span class="p">,</span><span class="n">b</span><span class="p">);</span> <span class="k">return</span> <span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">)</span><span class="n">obj</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> </div> <div class="section" id="sparse-matrices"> <h2>Sparse Matrices<a class="headerlink" href="#sparse-matrices" title="Permalink to this headline">¶</a></h2> <p>Sparse matrices are stored in compressed column storage (CCS) format. For a general <cite>nrows</cite> by <cite>ncols</cite> sparse matrix with <cite>nnz</cite> nonzero entries this means the following. The sparsity pattern and the nonzero values are stored in three fields:</p> <dl class="docutils"> <dt><tt class="xref docutils literal"><span class="pre">values</span></tt></dt> <dd>A <tt class="xref docutils literal"><span class="pre">'d'</span></tt> or <tt class="xref docutils literal"><span class="pre">'z'</span></tt> matrix of size <tt class="docutils literal"><span class="pre">(nnz,1)</span></tt> with the nonzero entries of the matrix stored columnwise.</dd> <dt><tt class="xref docutils literal"><span class="pre">rowind</span></tt></dt> <dd>An array of integers of length <cite>nnz</cite> containing the row indices of the nonzero entries, stored in the same order as <tt class="xref docutils literal"><span class="pre">values</span></tt>.</dd> <dt><tt class="xref docutils literal"><span class="pre">colptr</span></tt></dt> <dd>An array of integers of length <cite>ncols</cite> + 1 with for each column of the matrix the index of the first element in <tt class="xref docutils literal"><span class="pre">values</span></tt> from that column. More precisely, <tt class="docutils literal"><span class="pre">colptr[0]</span></tt> is <tt class="xref docutils literal"><span class="pre">0</span></tt>, and for k = 0, 1, ..., <cite>ncols</cite> - 1, <tt class="docutils literal"><span class="pre">colptr[k+1]</span></tt> is equal to <tt class="docutils literal"><span class="pre">colptr[k]</span></tt> plus the number of nonzeros in column <cite>k</cite> of the matrix. Thus, <tt class="docutils literal"><span class="pre">colptr[ncols]</span></tt> is equal to <cite>nnz</cite>, the number of nonzero entries.</dd> </dl> <p>For example, for the matrix</p> <div class="math"> <p><img src="_images/math/f4cc3b4324f3f4bb12a7db934c2c5c5acc98fe66.png" alt="A=\left [\begin{array}{cccc} 1 & 0 & 0 & 5\\ 2 & 0 & 4 & 0\\ 0 & 0 & 0 & 6\\ 3 & 0 & 0 & 0 \end{array}\right]" /></p> </div><p>the elements of <tt class="xref docutils literal"><span class="pre">values</span></tt>, <tt class="xref docutils literal"><span class="pre">rowind</span></tt>, and <tt class="xref docutils literal"><span class="pre">colptr</span></tt> are:</p> <dl class="docutils"> <dt><tt class="xref docutils literal"><span class="pre">values</span></tt>:</dt> <dd>1.0, 2.0, 3.0, 4.0, 5.0, 6.0</dd> <dt><tt class="xref docutils literal"><span class="pre">rowind</span></tt>:</dt> <dd>0, 1,3, 1, 0, 2</dd> <dt><tt class="xref docutils literal"><span class="pre">colptr</span></tt>:</dt> <dd>0, 3, 3, 4, 6.</dd> </dl> <p>It is crucial that for each column the row indices in <tt class="xref docutils literal"><span class="pre">rowind</span></tt> are sorted; the equivalent representation</p> <dl class="docutils"> <dt><tt class="xref docutils literal"><span class="pre">values</span></tt>:</dt> <dd>3.0, 2.0, 1.0, 4.0, 5.0, 6.0</dd> <dt><tt class="xref docutils literal"><span class="pre">rowind</span></tt>:</dt> <dd>3, 1, 0, 1, 0, 2</dd> <dt><tt class="xref docutils literal"><span class="pre">colptr</span></tt>:</dt> <dd>0, 3, 3, 4, 6</dd> </dl> <p>is not allowed (and will likely cause the program to crash).</p> <p>The <tt class="xref docutils literal"><span class="pre">nzmax</span></tt> field specifies the number of non-zero elements the matrix can store. It is equal to the length of <tt class="xref docutils literal"><span class="pre">rowind</span></tt> and <tt class="xref docutils literal"><span class="pre">values</span></tt>; this number can be larger that <tt class="docutils literal"><span class="pre">colptr[nrows]</span></tt>, but never less. This field makes it possible to preallocate a certain amount of memory to avoid reallocations if the matrix is constructed sequentially by filling in elements. In general the <tt class="xref docutils literal"><span class="pre">nzmax</span></tt> field can safely be ignored, however, since it will always be adjusted automatically as the number of non-zero elements grows.</p> <p>The <tt class="xref docutils literal"><span class="pre">id</span></tt> field controls the type of the matrix and can have values <tt class="xref docutils literal"><span class="pre">DOUBLE</span></tt> and <tt class="xref docutils literal"><span class="pre">COMPLEX</span></tt>.</p> <p>Sparse matrices are created using the following functions from the API.</p> <dl class="cfunction"> <dt id="SpMatrix_New"> spmatrix * <tt class="descname">SpMatrix_New</tt><big>(</big>int<em> nrows</em>, int<em> ncols</em>, int<em> nzmax</em>, int<em> id</em><big>)</big><a class="headerlink" href="#SpMatrix_New" title="Permalink to this definition">¶</a></dt> <dd>Returns a sparse zero matrix with <cite>nrows</cite> rows and <cite>ncols</cite> columns. <cite>nzmax</cite> is the number of elements that will be allocated (the length of the <tt class="xref docutils literal"><span class="pre">values</span></tt> and <tt class="xref docutils literal"><span class="pre">rowind</span></tt> fields).</dd></dl> <dl class="cfunction"> <dt id="SpMatrix_NewFromMatrix"> spmatrix * <tt class="descname">SpMatrix_NewFromMatrix</tt><big>(</big>spmatrix<em> *src</em>, int<em> id</em><big>)</big><a class="headerlink" href="#SpMatrix_NewFromMatrix" title="Permalink to this definition">¶</a></dt> <dd>Returns a copy the sparse matrix var{src}.</dd></dl> <dl class="cfunction"> <dt id="SpMatrix_NewFromIJV"> spmatrix * <tt class="descname">SpMatrix_NewFromIJV</tt><big>(</big>matrix<em> *I</em>, matrix<em> *J</em>, matrix<em> *V</em>, int<em> nrows</em>, int<em> ncols</em>, int<em> nzmax</em>, int<em> id</em><big>)</big><a class="headerlink" href="#SpMatrix_NewFromIJV" title="Permalink to this definition">¶</a></dt> <dd>Creates a sparse matrix with <cite>nrows</cite> rows and <cite>ncols</cite> columns from a triplet description. <cite>I</cite> and <cite>J</cite> must be integer matrices and <cite>V</cite> either a double or complex matrix, or <tt class="xref docutils literal"><span class="pre">NULL</span></tt>. If <cite>V</cite> is <tt class="xref docutils literal"><span class="pre">NULL</span></tt> the values of the entries in the matrix are undefined, otherwise they are specified by <cite>V</cite>. Repeated entries in <cite>V</cite> are summed. The number of allocated elements is given by <cite>nzmax</cite>, which is adjusted if it is smaller than the required amount.</dd></dl> <p>We illustrate use of the sparse matrix class by listing the source code for the <a title="real" class="reference external" href="matrices.html#real"><tt class="xref docutils literal"><span class="pre">real</span></tt></a> method, which returns the real part of a sparse matrix:</p> <div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span> <span class="nf">spmatrix_real</span><span class="p">(</span><span class="n">spmatrix</span> <span class="o">*</span><span class="n">self</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="n">SP_ID</span><span class="p">(</span><span class="n">self</span><span class="p">)</span> <span class="o">!=</span> <span class="n">COMPLEX</span><span class="p">)</span> <span class="k">return</span> <span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">)</span><span class="n">SpMatrix_NewFromMatrix</span><span class="p">(</span><span class="n">self</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">SP_ID</span><span class="p">(</span><span class="n">self</span><span class="p">));</span> <span class="n">spmatrix</span> <span class="o">*</span><span class="n">ret</span> <span class="o">=</span> <span class="n">SpMatrix_New</span><span class="p">(</span><span class="n">SP_NROWS</span><span class="p">(</span><span class="n">self</span><span class="p">),</span> <span class="n">SP_NCOLS</span><span class="p">(</span><span class="n">self</span><span class="p">),</span> <span class="n">SP_NNZ</span><span class="p">(</span><span class="n">self</span><span class="p">),</span> <span class="n">DOUBLE</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">ret</span><span class="p">)</span> <span class="k">return</span> <span class="n">PyErr_NoMemory</span><span class="p">();</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="k">for</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">SP_NNZ</span><span class="p">(</span><span class="n">self</span><span class="p">);</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="n">SP_VALD</span><span class="p">(</span><span class="n">ret</span><span class="p">)[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">creal</span><span class="p">(</span><span class="n">SP_VALZ</span><span class="p">(</span><span class="n">self</span><span class="p">)[</span><span class="n">i</span><span class="p">]);</span> <span class="n">memcpy</span><span class="p">(</span><span class="n">SP_COL</span><span class="p">(</span><span class="n">ret</span><span class="p">),</span> <span class="n">SP_COL</span><span class="p">(</span><span class="n">self</span><span class="p">),</span> <span class="p">(</span><span class="n">SP_NCOLS</span><span class="p">(</span><span class="n">self</span><span class="p">)</span><span class="o">+</span><span class="mi">1</span><span class="p">)</span><span class="o">*</span><span class="k">sizeof</span><span class="p">(</span><span class="n">int_t</span><span class="p">));</span> <span class="n">memcpy</span><span class="p">(</span><span class="n">SP_ROW</span><span class="p">(</span><span class="n">ret</span><span class="p">),</span> <span class="n">SP_ROW</span><span class="p">(</span><span class="n">self</span><span class="p">),</span> <span class="n">SP_NNZ</span><span class="p">(</span><span class="n">self</span><span class="p">)</span><span class="o">*</span><span class="k">sizeof</span><span class="p">(</span><span class="n">int_t</span><span class="p">));</span> <span class="k">return</span> <span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">)</span><span class="n">ret</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">C API</a><ul> <li><a class="reference external" href="#dense-matrices">Dense Matrices</a></li> <li><a class="reference external" href="#sparse-matrices">Sparse Matrices</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="modeling.html" title="previous chapter">Modeling</a></p> <h4>Next topic</h4> <p class="topless"><a href="printing.html" title="next chapter">Matrix Formatting</a></p> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="printing.html" title="Matrix Formatting" >next</a></li> <li class="right" > <a href="modeling.html" title="Modeling" >previous</a> |</li> <li><a href="http://abel.ee.ucla.edu/cvxopt">CVXOPT home</a> |</li> <li><a href="index.html">user's guide</a> </li> </ul> </div> <div class="footer"> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5. </div> </body> </html>