[GSoC14] Adding fixed precision support and extending test suite for Ledger-CLI

[tripun goel]

Hello everyone,
I am Tripun Goel and I am glad to announce that I am the selected student
sponsored by GSoC '2014 to intern for Software Freedom Conservancy. I am
excited to work with my mentor Bradley Kuhn and other community members.
Here are some details of the project.
------------------------------------
*Short description:* Add a -–precision option to specify maximum precision
you want and set it as default minimum precision for all amounts.Add
suitable tests for the bugs I will close related to precision. Extend test
suite to for better coverage.

*Project*:  My proposal has two parts depending upon which design is
selected.

     (1) *Convert Ledger-CLI to use fixed-point arithmetic*
         The point to note is that Ledger-CLI uses multiple precision
floating point numbers via MPFR library. I got to say that it is robust in
terms of precision with correct rounding, so I compared in terms of what
benefit we may get if we convert and how to implement. I already responded
to bug 992 which show that internally round off errors occur only when
precision is not properly set. There may be other floating point issues but
not the issue rose in the bug. The precision is taken to be the maximum
precision of quantity of a commodity encountered till the parsing of
current transaction and hence precision of fixed lot price or cost is
ignored. The amount of each commodity in each account should be set to
highest precision of the lot price, cost or quantity. This will
automatically prevent balance from being rounded off.  However it is also
important to guarantee fixed precision in any accounting software rather
than the arbitrary one.
        How to do this?

        (a) *Add a   --precision option* to specify maximum precision you
want and set it as default minimum precision for all amounts. Of course the
precision will be the maximum of either of all transactions or of that set
by the user. This is in order to guarantee the user at least the precision
specified. It has following benefits

        ·Minimal changes to the source.

        · The previous tests should still pass when  this option is not set.

*or*

        (b) *Add a fixed point class.*

         Although desirable, it will be the least preferred task to do. As
Ledger CLI is actively maintained and uses MPFR library, any effort to
convert to fixed point will be a parallel effort and needs to be maintained
separately. Also fixed point is specific to NPO project as there may be
other use cases which require arbitrary and higher precision. Many
fixed-point implementations are already available on the internet but we
need to have portable integer format and transactions which may involve
calculations well beyond the limits of standard integer data types provided
in C++. The numbers are stored in integer format with decimal part (base
10) multiplied by 10^p where p is the number of digits of precision.


   -         ·Define a fixed class with mpz_t (From GMP lib) for  integer
   part and an integer precision specifying the number of digits required
   after decimal. Then we overload the required operators and define necessary
   constructors. The intermediate calculations  are  real numbers which are
   converted to fixed point which cause precision loss if the precision
   involved is greater than fixed precision.
   -         ·Write  wrapper classes for mpfr types used in the program and
   replacing their declaration with the wrapper classes.
   -         ·List out the errors caused and correct them by providing
   appropriate overloaded operators and functions.
   -         · Test that the build passes for specified tests as it is
   bound to fail for tests involving higher precision than the fixed
   precision.Eg unit tests for amount intialization.





     (2) *Build a better test suite for Ledger-CLI.*

      Keeping in mind it is an NPO accounting project. More test cases can
be written which will focus on the need of this project. Although the suite
is good but not all test cases are covered. Add suitable tests for the bugs
I will close related to precision. Following are the issues I want to cover
in the basic test suites


   - Test overflow (input and precision)
      -   Input million dummy transactions.
      -   Each transaction with thousands of entries
   - Baseline tests
      -   write validation tests for more options and various combinations.
   - Test Value Expressions
      - Test more evaluation expression,masks, queries and automated
      transaction expressions
   - Add more corner cases
      - for example : pricemap and price history option are not extensively
      tested
   - Unit Tests
      - extend tests to more functions and classes like xact, commodity
      pool
   - Regression tests
      - .Write test for fixed issues which were not included in regression
      tests
   - Others
      - Test cases to determine whether unconfirmed bugs exist or not.
      Writing and testing scripts for generating reports in various formats as
      relevant to NPO requirements like the ones contributed to ledger
project by
      Software conservancy.


* Deliverables*:
    1. Fixed and closed round-off by one bugs
    2. Extended Test suite.

 *Challenge*s:
  1. Fix precision bug by either way.
  2. List as many test cases as possible.
  3. Get those tests merged with the main branch.

  4. Prevent new bugs

  5. Pass the build with new as well old tests


 *Benefits:*
 1. More reliable accounting with fixed precision.
 2. Better the test suite , lesser bugs post release.
-------------------------------------
I hope I will deliver up to the expectations of the community and receive
support of its members.

Regards
Tripun Goel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sfconservancy.org/pipermail/npo-accounting/attachments/20140507/fa380fd4/attachment.html>