<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> <title>scs.h Source File</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.2.15 --> <center> <a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="annotated.html">Data Structures</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Data Fields</a> <a class="qindex" href="globals.html">Globals</a> </center> <hr><h1>scs.h</h1><a href="scs_8h.html">Go to the documentation of this file.</a><div class="fragment"><pre>00001 <font class="comment">/** This is the main header file of the SCS library, which defines the</font> 00002 <font class="comment"> SCS data structure, and the functions that implement arithmetic on it.</font> 00003 <font class="comment"></font> 00004 <font class="comment">@file scs.h</font> 00005 <font class="comment"></font> 00006 <font class="comment">@author David Defour David.Defour@ens-lyon.fr</font> 00007 <font class="comment">@author Florent de Dinechin Florent.de.Dinechin@ens-lyon.fr</font> 00008 <font class="comment"></font> 00009 <font class="comment">This file is part of the SCS library.</font> 00010 <font class="comment"></font> 00011 <font class="comment">Copyright (C) 2002 David Defour and Florent de Dinechin</font> 00012 <font class="comment"></font> 00013 <font class="comment">This library is free software; you can redistribute it and/or</font> 00014 <font class="comment">modify it under the terms of the GNU Lesser General Public</font> 00015 <font class="comment">License as published by the Free Software Foundation; either</font> 00016 <font class="comment">version 2.1 of the License, or (at your option) any later version.</font> 00017 <font class="comment"></font> 00018 <font class="comment">This library is distributed in the hope that it will be useful,</font> 00019 <font class="comment">but WITHOUT ANY WARRANTY; without even the implied warranty of</font> 00020 <font class="comment">MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU</font> 00021 <font class="comment">Lesser General Public License for more details.</font> 00022 <font class="comment"></font> 00023 <font class="comment">You should have received a copy of the GNU Lesser General Public</font> 00024 <font class="comment">License along with this library; if not, write to the Free Software</font> 00025 <font class="comment">Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</font> 00026 <font class="comment"></font> 00027 <font class="comment">*/</font> 00028 00029 00030 00031 <font class="comment">/* Avoid loading the header twice */</font> 00032 <font class="preprocessor">#ifndef INCLUDE_SCS </font> 00033 <font class="preprocessor"></font><font class="preprocessor">#define INCLUDE_SCS 1</font> 00034 <font class="preprocessor"></font> 00035 <font class="preprocessor">#ifndef DOXYGEN_SHOULD_SKIP_THIS </font><font class="comment">/* because it is not very clean */</font> 00036 00037 <font class="preprocessor">#include <limits.h></font> 00038 00039 <font class="preprocessor">#include "scs_config.h"</font> 00040 00041 <font class="preprocessor">#ifdef HAVE_GMP_H</font> 00042 <font class="preprocessor"></font><font class="preprocessor"> #include <gmp.h></font> 00043 <font class="preprocessor">#endif</font> 00044 <font class="preprocessor"></font> 00045 <font class="preprocessor">#ifdef HAVE_MPFR_H</font> 00046 <font class="preprocessor"></font><font class="preprocessor"> #include <mpfr.h></font> 00047 <font class="preprocessor">#endif</font> 00048 <font class="preprocessor"></font> 00049 00050 <font class="preprocessor">#endif </font><font class="comment">/* DOXYGEN_SHOULD_SKIP_THIS */</font> 00051 00052 00053 00054 00055 00056 <font class="comment"></font> 00057 <font class="comment">/** @internal An union to cast floats into doubles or the other way round. For</font> 00058 <font class="comment"> internal purpose only */</font> 00059 00060 <font class="keyword">typedef</font> <font class="keyword">union </font>{ 00061 <font class="keywordtype">int</font> i[2]; 00062 <font class="keywordtype">unsigned</font> <font class="keywordtype">long</font> <font class="keywordtype">long</font> <font class="keywordtype">int</font> l; 00063 <font class="keywordtype">double</font> d; 00064 } scs_db_number; 00065 00066 00067 00068 00069 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00070 <font class="comment">/**@name SCS data-types */</font> <font class="comment">/**@{*/</font> 00071 <font class="comment"></font> 00072 <font class="comment">/** @struct scs </font> 00073 <font class="comment">The SCS data type. </font> 00074 <font class="comment"></font> 00075 <font class="comment">An SCS number is a a floating-point number in base 2^32.</font> 00076 <font class="comment"></font> 00077 <font class="comment">- Its mantissa is formed of SCS_NB_WORDS digits (currently 32 bits by default)</font> 00078 <font class="comment"></font> 00079 <font class="comment">- Its exponent is a 32-bit integer</font> 00080 <font class="comment"></font> 00081 <font class="comment">- It also has a sign field, and an exception field used to store and</font> 00082 <font class="comment"> propagate IEEE-754 exceptions.</font> 00083 <font class="comment"></font> 00084 <font class="comment"></font> 00085 <font class="comment">The real number represented by a scs structure is equal to:</font> 00086 <font class="comment">@f$</font> 00087 <font class="comment">\displaystyle </font> 00088 <font class="comment">\sum_{i=0}^{\mathtt{SCS\_NB\_WORDS}} </font> 00089 <font class="comment">2^{(\mathtt{index} -i)\mathtt{SCS\_NB\_BITS}}</font> 00090 <font class="comment">\times</font> 00091 <font class="comment">\mathtt{h\_word}[i] </font> 00092 <font class="comment">@f$</font> 00093 <font class="comment">*/</font> 00094 00095 <font class="comment">/*</font> 00096 <font class="comment"> (verbatim-mode formula for the above eqation:) the number represented by a</font> 00097 <font class="comment"> SCS structure is :</font> <a name="l00098"></a><a class="code" href="structscs.html">00098</a> <font class="comment"></font> 00099 <font class="comment"> i<SCS_NB_WORDS (index - i).SCS_NB_BITS</font> <a name="l00100"></a><a class="code" href="structscs.html#m0">00100</a> <font class="comment"> sign . ( sum ( h_word[i] . 2^ ) </font> 00101 <font class="comment"> i=0 </font> <a name="l00102"></a><a class="code" href="structscs.html#m1">00102</a> <font class="comment">*/</font> 00103 00104 <font class="keyword">struct </font><a class="code" href="structscs.html">scs</a> {<font class="comment"></font> <a name="l00105"></a><a class="code" href="structscs.html#m2">00105</a> <font class="comment"> /** the digits, as 32 bits words */</font> 00106 <font class="keywordtype">unsigned</font> <font class="keywordtype">int</font> <a class="code" href="structscs.html#m0">h_word</a>[SCS_NB_WORDS]; <font class="comment"></font> <a name="l00107"></a><a class="code" href="structscs.html#m3">00107</a> <font class="comment"> /** Used to store Nan,+/-0, Inf, etc and then let the hardware handle them */</font> 00108 scs_db_number <a class="code" href="structscs.html#m1">exception</a>; <font class="comment"></font> 00109 <font class="comment"> /** This corresponds to the exponent in an FP format, but here we are</font> 00110 <font class="comment"> in base 2^32 */</font> 00111 <font class="keywordtype">int</font> <a class="code" href="structscs.html#m2">index</a>; <font class="comment"></font> 00112 <font class="comment"> /** The sign equals 1 or -1*/</font> 00113 <font class="keywordtype">int</font> <a class="code" href="structscs.html#m3">sign</a>; 00114 }; 00115 <a name="l00116"></a><a class="code" href="scs_8h.html#a2">00116</a> 00117 <font class="keyword">typedef</font> <font class="keyword">struct </font><a class="code" href="structscs.html">scs</a> scs; 00118 00119 00120 <font class="comment"></font> 00121 <font class="comment">/** scs_ptr is a pointer on a SCS structure */</font> 00122 <font class="keyword">typedef</font> <font class="keyword">struct </font>scs * scs_ptr; 00123 00124 <a name="l00125"></a><a class="code" href="scs_8h.html#a3">00125</a> 00126 <font class="comment"></font> 00127 <font class="comment">/** scs_t is an array of one SCS struct to lighten syntax : you may</font> 00128 <font class="comment"> declare a scs_t object, and pass it to the scs functions (which</font> 00129 <font class="comment"> expect pointers) without using ampersands.</font> 00130 <font class="comment">*/</font> 00131 <font class="keyword">typedef</font> <font class="keyword">struct </font>scs scs_t[1]; 00132 <font class="comment"></font> 00133 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for SCS data-types */</font> 00134 00135 00136 00137 00138 00139 00140 00141 00142 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00143 <font class="comment">/**@name Conversion and initialization functions */</font> <font class="comment">/**@{*/</font> 00144 <font class="comment"></font> 00145 <font class="comment">/** Convert a SCS number to a double, rounding to the nearest */</font> 00146 <font class="keywordtype">void</font> <a class="code" href="scs2double_8c.html#a0">scs_get_d</a>(<font class="keywordtype">double</font>*, scs_ptr); 00147 <font class="comment"></font> 00148 <font class="comment">/** Convert a SCS number to a double, rounding towards minus infinity */</font> 00149 <font class="keywordtype">void</font> scs_get_d_minf(<font class="keywordtype">double</font>*, scs_ptr); 00150 <font class="comment"></font> 00151 <font class="comment">/** Convert a SCS number to a double, rounding towards plus infinity */</font> 00152 <font class="keywordtype">void</font> scs_get_d_pinf(<font class="keywordtype">double</font>*, scs_ptr); 00153 <font class="comment"></font> 00154 <font class="comment">/** Convert a SCS number to a double, rounding towards zero */</font> 00155 <font class="keywordtype">void</font> scs_get_d_zero(<font class="keywordtype">double</font>*, scs_ptr); 00156 <font class="comment"></font> 00157 <font class="comment">/** Convert a double into a SCS number (this is an exact operation) */</font> 00158 <font class="keywordtype">void</font> <a class="code" href="double2scs_8c.html#a0">scs_set_d</a>(scs_ptr, <font class="keywordtype">double</font>); 00159 <font class="comment"></font> 00160 <font class="comment">/** Convert an unsigned int into a SCS number (this is an exact operation) */</font> 00161 <font class="keywordtype">void</font> <a class="code" href="double2scs_8c.html#a1">scs_set_si</a>(scs_ptr, <font class="keywordtype">signed</font> <font class="keywordtype">int</font>); 00162 00163 <font class="comment"></font> 00164 <font class="comment">/** Print out a SCS number. Sorry for the strange name, we are mimicking GMP */</font> 00165 <font class="keywordtype">void</font> scs_get_std(scs_ptr); 00166 00167 <font class="comment"></font> 00168 <font class="comment">/** Copy a SCS number into another */</font> 00169 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a0">scs_set</a>(scs_ptr, scs_ptr); 00170 00171 <font class="comment"></font> 00172 <font class="comment">/** Set a SCS number to zero */</font> 00173 <font class="keywordtype">void</font> <a class="code" href="zero__scs_8c.html#a0">scs_zero</a>(scs_ptr); 00174 00175 <font class="comment"></font> 00176 <font class="comment">/** Generate a random SCS number. </font> 00177 <font class="comment"> The index field of result will be between -expo_max and +expo_max.</font> 00178 <font class="comment"> Example: to get a number in the double-precision floating-point range,</font> 00179 <font class="comment"> expo_max should be smaller than 39.</font> 00180 <font class="comment"> @warning No guarantee is made about the quality of the random algorithm</font> 00181 <font class="comment"> used... */</font> 00182 <font class="keywordtype">void</font> scs_rand(scs_ptr result, <font class="keywordtype">int</font> expo_max); 00183 <font class="comment"></font> 00184 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for conversion / initialisation functions*/</font> 00185 00186 00187 00188 00189 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00190 <font class="comment">/**@name Addition and renormalisation functions */</font> <font class="comment">/**@{*/</font> 00191 00192 <font class="comment"></font> 00193 <font class="comment">/** Addition of two SCS numbers. </font> 00194 <font class="comment"> The arguments x, y and result may point to the same memory</font> 00195 <font class="comment"> location. The result is a normalised SCS number.</font> 00196 <font class="comment">*/</font> 00197 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a8">scs_add</a>(scs_ptr result, scs_ptr x, scs_ptr y); 00198 00199 <font class="comment"></font> 00200 <font class="comment">/** Subtraction of two SCS numbers. </font> 00201 <font class="comment"> The arguments x, y and result may point to the same memory</font> 00202 <font class="comment"> location. The result is a normalised SCS number.</font> 00203 <font class="comment"> */</font> 00204 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a9">scs_sub</a>(scs_ptr result, scs_ptr x, scs_ptr y); 00205 00206 <font class="comment"></font> 00207 <font class="comment">/** Addition without renormalisation, to be used for adding many</font> 00208 <font class="comment"> numbers.</font> 00209 <font class="comment"> @warning In case of a cancellation, severe loss of precision could</font> 00210 <font class="comment"> happen. Safe if the numbers are of the same sign.</font> 00211 <font class="comment"> */</font> 00212 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a4">scs_add_no_renorm</a>(scs_ptr result, scs_ptr x, scs_ptr y); 00213 00214 <font class="comment"></font> 00215 <font class="comment">/** Renormalisation (to be used after several scs_add_no_renorm).</font> 00216 <font class="comment">This function removes the carry from each digit, and also shifts the</font> 00217 <font class="comment">digits in case of a cancellation (so that if result != 0 then its</font> 00218 <font class="comment">first digit is non-zero)</font> 00219 <font class="comment"> </font> 00220 <font class="comment"> @warning THIS FUNCTION HAS NEVER BEEN PROPERLY TESTED and is</font> 00221 <font class="comment"> currently unused in the library: instead, specific renormalisation</font> 00222 <font class="comment"> steps are fused within the code of the operations which require it.</font> 00223 <font class="comment"> */</font> 00224 00225 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a1">scs_renorm</a>(scs_ptr); 00226 00227 <font class="comment"></font> 00228 <font class="comment">/** Renormalisation assuming no cancellation. This function is useful</font> 00229 <font class="comment"> for example when adding many numbers of the same sign */</font> 00230 <font class="keywordtype">void</font> <a class="code" href="addition__scs_8c.html#a2">scs_renorm_no_cancel_check</a>(scs_ptr); 00231 <font class="comment"></font> 00232 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for addition and normalisation functions*/</font> 00233 00234 00235 00236 00237 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00238 <font class="comment">/**@name Multiplication functions */</font> <font class="comment">/**@{*/</font> 00239 <font class="comment"></font> 00240 <font class="comment">/** Multiplication of two SCS numbers. The arguments x, y and result</font> 00241 <font class="comment"> may point to the same memory location. The result is a normalised SCS</font> 00242 <font class="comment"> number.</font> 00243 <font class="comment"> */</font> 00244 <font class="keywordtype">void</font> <a class="code" href="multiplication__scs_8c.html#a2">scs_mul</a>(scs_ptr result, <font class="keyword">const</font> scs_ptr x, <font class="keyword">const</font> scs_ptr y); 00245 <font class="comment"></font> 00246 <font class="comment">/** Multiplication of a SCS with an unsigned integer; result is</font> 00247 <font class="comment"> returned in x. */</font> 00248 <font class="keywordtype">void</font> <a class="code" href="multiplication__scs_8c.html#a4">scs_mul_ui</a>(scs_ptr, <font class="keyword">const</font> <font class="keywordtype">unsigned</font> <font class="keywordtype">int</font>); 00249 <font class="comment"></font> 00250 <font class="comment">/** Square. Result is normalised */</font> 00251 <font class="keywordtype">void</font> <a class="code" href="multiplication__scs_8c.html#a3">scs_square</a>(scs_ptr result, scs_ptr x); 00252 <font class="comment"></font> 00253 <font class="comment">/** Fused multiply-and-add (ab+c); Result is normalised</font> 00254 <font class="comment">\warning This function has not been tested thoroughly */</font> 00255 <font class="keywordtype">void</font> scs_fma(scs_ptr result, scs_ptr a, scs_ptr b, scs_ptr c); 00256 <font class="comment"></font> 00257 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for Multiplication functions*/</font> 00258 00259 00260 00261 00262 00263 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00264 <font class="comment">/**@name Divisions */</font> <font class="comment">/**@{*/</font> 00265 <font class="comment"></font> 00266 <font class="comment">/** SCS inverse. </font> 00267 <font class="comment">Stores 1/x in result. Result is normalised </font> 00268 <font class="comment"></font> 00269 <font class="comment">@warning This function is known not to work for most precisions: it</font> 00270 <font class="comment">performs a fixed number of Newton-Raphson iterations (two), starting</font> 00271 <font class="comment">with a FP number (53 bits), so provides roughly 210 bits of</font> 00272 <font class="comment">precision. It should be modified to perform more iterations if more</font> 00273 <font class="comment">precision is needed.</font> 00274 <font class="comment">*/</font> 00275 <font class="keywordtype">void</font> <a class="code" href="division__scs_8c.html#a0">scs_inv</a>(scs_ptr result, scs_ptr x); 00276 <font class="comment"></font> 00277 <font class="comment">/** SCS division. Computes x/y. Result is normalised </font> 00278 <font class="comment">@warning This function is known not to work for most precisions: it</font> 00279 <font class="comment">performs a fixed number of Newton-Raphson iterations (two), starting</font> 00280 <font class="comment">with a FP number (53 bits), so provides roughly 210 bits of</font> 00281 <font class="comment">precision. It should be modified to perform more iterations if more</font> 00282 <font class="comment">precision is needed.</font> 00283 <font class="comment">*/</font> 00284 <font class="keywordtype">void</font> <a class="code" href="division__scs_8c.html#a1">scs_div</a>(scs_ptr result, scs_ptr x, scs_ptr y); 00285 <font class="comment"></font> 00286 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for division functions*/</font> 00287 00288 00289 00290 00291 00292 <font class="comment">/* ****************************************************************** */</font><font class="comment"></font> 00293 <font class="comment">/**@name Functions for testing purpose */</font> <font class="comment">/**@{*/</font> 00294 00295 00296 <font class="preprocessor">#ifdef HAVE_LIBGMP</font> 00297 <font class="preprocessor"></font><font class="comment">/** Convert a SCS number into a GMP MPF (multiple precision,</font> 00298 <font class="comment"> floating-point) number. Should be exact if the target number has</font> 00299 <font class="comment"> more precision than the SCS number, otherwise the rounding is</font> 00300 <font class="comment"> unspecified (the conversion uses MPF functions) */</font> 00301 <font class="keywordtype">void</font> scs_get_mpf(scs_ptr, mpf_t); 00302 <font class="preprocessor">#endif</font> 00303 <font class="preprocessor"></font> 00304 00305 00306 <font class="preprocessor">#ifdef HAVE_MPFR_H </font> 00307 <font class="preprocessor"></font><font class="comment">/** Convert a SCS number into a MPFR (multiple precision,</font> 00308 <font class="comment"> floating-point) number. Should be exact if the target number has</font> 00309 <font class="comment"> more precision than the SCS number, otherwise should be correctly</font> 00310 <font class="comment"> rounded (the conversion uses MPFR functions). Not heavily tested</font> 00311 <font class="comment"> though */</font> 00312 <font class="keywordtype">void</font> scs_get_mpfr(scs_ptr, mpfr_t); 00313 <font class="preprocessor">#endif</font> 00314 <font class="preprocessor"></font> 00315 <font class="comment"></font> 00316 <font class="comment">/**@}*/</font> <font class="comment">/* end doxygen group for functions for testing purpose */</font> 00317 00318 <font class="preprocessor">#endif </font><font class="comment">/* INCLUDE_SCS */</font> 00319 00320 00321 00322 00323 </pre></div><hr><address align="right"><small>Generated on Tue Jun 17 10:15:51 2003 for SCSLib by <a href="http://www.doxygen.org/index.html"> <img src="doxygen.png" alt="doxygen" align="middle" border=0 width=110 height=53></a>1.2.15 </small></address> </body> </html>