Notes:
Version
-------
This version ($Name: ALPHA_01_01 $) is functionally identical with the previous
alpha-0.01.00. The runit tests have been extended and further tests
have been added. A lot of additional testing has been done using
random numbers as parameters with testrandom.rb and values for which
these random tests have failed have been added to the regular tests in
testlongdecimal.rb . So this release is mostly bug-fixing, enough to
justify declaring itself as alpha-version.
This software development effort is hosted on RubyForge (
http://rubyforge.org/ ) under the project name "long-decimal", to be
found directly with http://rubyforge.org/projects/long-decimal/ . So
you should feel encouraged to look if there is a newer version, when
you install long-decimal.
This version is an alpha-version. Operations +, -, *, / and sqrt
should be working properly and would justify calling this release at
least beta. Even log, exp and power should be fine. log, log2, log10
and exp have been tested for about a million random values and the
current version should cover all of these correctly. But it is still
possible,that in some cases the result deviates in the last digit by 1
or 2 from the real result. A deviation of slightly more than half of
the unit of the last digit is already present. Improving on this
would require an extensive extension of internal functionality to
provide rounding information in case of last digits being 50000...,
where additional digits would reveal if this really needs to be
rounded up or down. Because these functions are transcendental, at
least exp and log will always have either one of these true, it will
never be exactly ....5. Speed could be improved as well.
It would be a good idea to do some more mathematical analysis on how
many digits are needed internally to guarantee the correctness of the
digits that are provided. But this will not be considered as a
requirement for the alpha-version.
Test
----
Some runit tests have been included. They give some indication of the
correctness of this library and allow changes to be checked in order
to make sure that what was running before would still work afterwards.
Tests for a library as complex as long-decimal can never be
exhaustive, but they give a good indication that methods are working
correctly. About 95% of the tests that will be eventually needed are
already present. As a policy a release is not created unless all
tests succeed. Running the tests can take a few minutes, depending on
your machine. It is about 15 minutes on my machine (1300 MHz).
Whatever is gained by making the software run faster is used up again
by adding more tests. This is the result of the test:
Finished in 1160.808707 seconds.
131 tests, 45612 assertions, 0 failures, 0 errors
In addition random tests for exp, exp2, exp10, sqrt, log, log2 and
log10 can be run for a long time, using the script test/testrandom.rb.
Likewise tests for powers x to the yth with random x and y can be
tested for a long time using test/testrandpower.rb
These two require installation of the ruby-library crypt-isaac for its
random numbers, which works well with Linux or Windows and Cygwin. If
you actually want to run this and find an error with it, please report
it with the lines of output revealing the bug on
http://rubyforge.org/projects/long-decimal/ -> tracker
Install
-------
(REMARK: installation has only been successfully tested on Linux with
ruby 1.8.4 and on Windows XP with Cygwin and ruby 1.8.4 and on Windows
2000 with ruby 1.8.2)
1. Using ruby-gems (preferred)
- open a shell window
- become root, unless the current user has the right to install gems
(which is usually the case on windows)
su
- uninstall old versions
gem uninstall long-decimal
- install the newest version
gem install long-decimal
- Usage from your ruby-programs:
require "rubygems"
require_gem "long-decimal"
- documentation will be found in HTML-format in the directory
$RUBY_DIR/gems/$RUBY_VERSION/doc/long-decimal-$LONG_DECIMAL_VERSION/rdoc/index.html
where $RUBY_DIR is the directory containing your ruby-installation,
usually /usr/lib/ruby or /usr/local/lib/ruby on
Linux/Unix-systems.
$RUBY_VERSION is the major version of your Ruby, like 1.8
$LONG_DECIMAL_VERSION is the version of long-decimal that you
have installed, like 0.00.20
on my machine that would be
/usr/local/lib/ruby/gems/1.8/doc/long-decimal-0.00.20/rdoc/index.html
2. Installing from the sources (it is preferred to use the
gem-installation, but since long-decimal is open-source-software you
are off course granted the right to download the source and change
it and install your own version.
- download the newest source-tar.gz-file from long-decimal project at rubyforge
which can be found by
http://rubyforge.org/projects/long-decimal/ -> Files
( http://rubyforge.org/frs/?group_id=1334 )
- open a shell window
cd to the directory where you have downloaded the gem-file
unpack the file using tar
tar xfzvv long-decimal-alpha-1_00.tar.gz
cd long-decimal
- now you can use rake for several operations
- rake test
runs runit tests. All tests should succeed.
- rake doc
creates the documentation
- rake gem creates the gem-file in a sub-directory pkg
recommended for installation, proceed as in 1
- cd pkg
- gem install --local long-decimal
3. The documentation can be created from the sources. It is contained
in the gem-file. It is not provided as a separate file any more.
Bugs
----
There are no known bugs against the current specification and bugs
that occur are usually fixed within a few days.
It is considered somewhat arbitrary to disallow calculation
exponential functions if the result could not be expressed as Float.
This limitation should be removed, even though it has to be added,
that results of exponentiation that go beyond Float can only be handled
at a great cost of performance, because they really need more than 300
digits.
Certain calculations are too slow. Algorithms need to be optimized
for speed. The goal is to keep the algorithms in Ruby-code as long as
possible to make it easier to optimize the algorithm. If optimization
beyond this level will be needed, C-code might be used, preferably
based on an existing library.
Even though some mathematical background has already been invested,
more effort from the theoretical side is needed in order to choose
internal precision parameters in such a way that correctness of the
result to all given digits can be guaranteed with a minimum of
overhead. Currently parameters are probably slightly too careful,
which slows calculations down. But it is also possible that they are
insufficient for certain calculations, yielding wrong results.
rdoc-documentation and in-code comments are somewhat complete, but for
a sophisticated library like this additional external documentation
should be provided. Currently this does not exist at all.
Please report any bugs you come across on
http://rubyforge.org/projects/long-decimal -> Tracker.
The status of long-decimal is considered to be alpha.
License
-------
Ruby's license or LGPL
Find copies of these licenses on http://www.gnu.org/ or http://www.ruby-lang.org/
Warranty
--------
This is a alpha-version. Do not expect too much! This is work in
progress! I do not take any responsibility. Please use it as it is,
change it according to the terms of the license or wait for a more
stable version (for which I can't take any warranty either...)
Author
------
Karl Brodowsky
http://www.velofahren.de/cgi-bin/mailform.cgi
(no direct mail address because I do not like spam)
Changes:
fixed calculation of power where both base and exponent are LongDecimal for better speed and better accuracy.
|
