<!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>
