hiro/arb
1
0
Fork 0
mirror of https://github.com/vale981/arb synced 2025-03-05 17:31:38 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

some more doc housekeeping; add a page about contributing

Browse source
This commit is contained in:
fredrik 2018-04-10 00:31:41 +02:00
parent 0abfa1e555
commit 296e1703c0
4 changed files with 171 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
doc/source/arf.rst
View file

@ -19,16 +19,24 @@ integer *e* such that
The internal representation of an :type:`arf_t` stores the
exponent in the latter format.
Except where otherwise noted, the output of an operation is the
floating-point number obtained by viewing the inputs as exact numbers,
in principle carrying out the mathematical operation exactly, and rounding the
resulting real number to the nearest representable floating-point
number whose mantissa has at most the specified number of bits, in
the specified direction of rounding. Some operations are always
or optionally done exactly.
Functions that might round the result return an :type:`int` flag
which will have the value 0 if the result is exact and 1 if
the result is inexact (rounded).
Except where otherwise noted, functions have the following semantics:
* Functions taking *prec* and *rnd* parameters at the end of the argument list
and returning an :type:`int` flag round the result in the output variable
to *prec* bits in the direction specified by *rnd*. The return flag
is 0 if the result is exact
(not rounded) and 1 if the result is inexact (rounded).
Correct rounding is guaranteed: the result is the floating-point number
obtained by viewing the inputs as exact numbers, in principle carrying out
the mathematical operation exactly, and rounding the resulting real number
to the nearest representable floating-point number whose mantissa has at
most the specified number of bits, in the specified direction of rounding.
In particular, the error is at most 1 ulp with directed rounding mode
and 0.5 ulp when rounding to nearest.
* Other functions perform the operation exactly.
Since exponents are bignums, overflow or underflow cannot occur.
Types, macros and constants
-------------------------------------------------------------------------------
@ -504,8 +512,7 @@ Addition and multiplication
.. function:: int arf_neg_round(arf_t res, const arf_t x, slong prec, arf_rnd_t rnd)
Sets *res* to `-x`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `-x`.
.. function:: int arf_add(arf_t res, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
@ -515,13 +522,11 @@ Addition and multiplication
.. function:: int arf_add_fmpz(arf_t res, const arf_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)
Sets *res* to `x + y`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `x + y`.
.. function:: int arf_add_fmpz_2exp(arf_t res, const arf_t x, const fmpz_t y, const fmpz_t e, slong prec, arf_rnd_t rnd)
Sets *res* to `x + y 2^e`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `x + y 2^e`.
.. function:: int arf_sub(arf_t res, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
@ -531,8 +536,7 @@ Addition and multiplication
.. function:: int arf_sub_fmpz(arf_t res, const arf_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)
Sets *res* to `x - y`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `x - y`.
.. function:: void arf_mul_2exp_si(arf_t res, const arf_t x, slong e)
@ -550,8 +554,7 @@ Addition and multiplication
.. function:: int arf_mul_fmpz(arf_t res, const arf_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)
Sets *res* to `x \cdot y`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `x \cdot y`.
.. function:: int arf_addmul(arf_t z, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
@ -564,8 +567,6 @@ Addition and multiplication
.. function:: int arf_addmul_fmpz(arf_t z, const arf_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)
Performs a fused multiply-add `z = z + x \cdot y`, updating *z* in-place.
The result is rounded to *prec* bits in the direction specified by *rnd*,
and the function nonzero iff the operation is inexact.
.. function:: int arf_submul(arf_t z, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
@ -577,14 +578,11 @@ Addition and multiplication
.. function:: int arf_submul_fmpz(arf_t z, const arf_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)
Performs a fused multiply-subtract `z = z + x \cdot y`, updating *z* in-place.
The result is rounded to *prec* bits in the direction specified by *rnd*,
and the function nonzero iff the operation is inexact.
Performs a fused multiply-subtract `z = z - x \cdot y`, updating *z* in-place.
.. function:: int arf_sosq(arf_t res, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
Sets *res* to `x^2 + y^2`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact.
Sets *res* to `x^2 + y^2`, rounded to *prec* bits in the direction specified by *rnd*.
Summation
-------------------------------------------------------------------------------
@ -630,22 +628,19 @@ Square roots
.. function:: int arf_sqrt_fmpz(arf_t res, const fmpz_t x, slong prec, arf_rnd_t rnd)
Sets *res* to `\sqrt{x}`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact. The result is NaN if *x* is negative.
Sets *res* to `\sqrt{x}`. The result is NaN if *x* is negative.
.. function:: int arf_rsqrt(arf_t res, const arf_t x, slong prec, arf_rnd_t rnd)
Sets *res* to `1/\sqrt{x}`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact. The result is NaN if *x* is
Sets *res* to `1/\sqrt{x}`. The result is NaN if *x* is
negative, and `+\infty` if *x* is zero.
.. function:: int arf_root(arf_t res, const arf_t x, ulong k, slong prec, arf_rnd_t rnd)
Sets *res* to `x^{1/k}`, rounded to *prec* bits in the direction specified by *rnd*,
returning nonzero iff the operation is inexact. The result is NaN if *x* is negative.
Sets *res* to `x^{1/k}`. The result is NaN if *x* is negative.
Warning: this function is a wrapper around the MPFR root function.
It gets slow and uses much memory for large *k*.
Consider working with :func:`arb_root` for large *k* instead of using this
Consider working with :func:`arb_root_ui` for large *k* instead of using this
function directly.
Complex arithmetic

100
doc/source/contributing.rst Normal file
View file

@ -0,0 +1,100 @@
.. _contributing:
Contributing to Arb
===============================================================================
The Arb project welcomes new feature contributions in
addition to patches for bugs and performance problems.
What are appropriate new features?
Most of the numerical functionality that can be found in a general-purpose
computer algebra system is certainly within scope
(of course, the main restriction is that the algorithm
must have a proof of correctness).
However, if the functionality is easily accomplished by combining existing
functions in Arb, consider whether it is worth the increase in code size,
maintenance effort and test time.
Prospective contributors are recommended to discuss their ideas
on the mailing list or the issue tracker.
The process for actually submitting code is simple: anyone can submit a pull
request on GitHub. If the patch looks good to the maintainer and the test
code passes, the patch will get merged into the git master.
Code conventions
-------------------------------------------------------------------------------
Four steps are needed to add a new function:
* Add the function ``module_foo()`` in a new file ``module/foo.c``.
* Add a corresponding test program in a new file ``module/test/t-foo.c``.
* Add the function prototype to ``module.h``.
* Document the function in ``doc/source/module.rst``.
The build system takes care of everything else automatically.
Test code (see below)
can be omitted if ``module_foo()`` is a trivial helper function, but it should
at least be tested indirectly via another function in that case.
Auxiliary functions needed to implement ``module_foo()`` but which have no
use elsewhere should be declared as ``static`` in ``module/foo.c``.
If ``module_foo()`` is very short, it can be declared inline directly
in ``module.h`` with the ``MODULE_INLINE`` macro.
Use the following checklist regarding code style:
* Try to keep names and function arguments consistent with existing code.
* Follow the conventions regarding types, aliasing rules, etc. described
in :ref:`issues` and in ``code_conventions.txt`` in FLINT (https://github.com/wbhart/flint2/blob/trunk/code_conventions.txt).
* Use basic FLINT constants, types and functions: ``FLINT_BITS``, ``flint_malloc``/``flint_free``, ``flint_abort``, ``flint_printf``, etc.
* Complex macros should be avoided.
* Indentation is four spaces.
* Curly braces normally go on a new line.
* Binary operators are surrounded by spaces (but parentheses and brackets are not).
* Logically distinct chunks of code (variable declarations, initialization,
precomputations, the main loop, cleanup, etc.) should be separated by
a single blank line.
* Lines are up to 79 characters long, but this rule can be broken if it helps readability.
* Add correct copyright notices at the top of each file.
Test code
-------------------------------------------------------------------------------
See :ref:`setup` for instructions on running test code.
The easiest way to write a test program for a new function
is to adapt the test code for an existing, similar function.
Most of the test code in Arb uses the strategy of computing the same
mathematical quantity in two or more different ways (for example, using
functional equations, interchanging the order of parameter, or varying
the precision and other algorithm parameters) and verifying that
the results are consistent.
It is also a good idea to test that aliasing works.
Input data is usually generated randomly, but in some cases
including precomputed reference values also makes sense.
Faster test code is better. A single test program should not take more
than 10 seconds to run, and preferably no more than 1 second. Most functions
can be tested effectively in less than 0.1 seconds. Think of what the corner
cases are and try to generate random input biased toward such cases.
The ``randtest()`` functions attempt to generate corner cases automatically, but
some thought may be needed to use them optimally. Try to ensure that the test
code fails if you deliberately break the tested function in any way. It is also
a good idea to run the test code once with ``ARB_TEST_MULTIPLIER=10.0`` or higher.
If a function's input space is too large to probe effectively for corner cases
with random input, that can be a hint that the function should be split into
smaller logical parts that can be tested separately.
The test code must complete without errors when run with ``valgrind``.
The most common mistake leading to memory corruption or memory leaks
is to miss or duplicate an ``init()`` or ``clear()`` call.
Check that the ``init()`` and ``clear()`` calls exactly match the variable
declarations in each code block, including the test code itself.
Profiling code is not needed in most cases, but it is often a good idea to
run some benchmarks at least during the initial development of a new feature.
The ``TIMEIT_START``/``TIMEIT_STOP`` and ``SHOW_MEMORY_USAGE`` macros
in FLINT are useful for quick measurements.

1
doc/source/index.rst
View file

@ -89,6 +89,7 @@ General information
setup.rst
using.rst
issues.rst
contributing.rst
credits.rst
Example programs

71
doc/source/setup.rst
View file

@ -8,7 +8,7 @@ Package managers
The easiest way to install Arb including all dependencies is via ready-made
packages available for various distributions.
Note that some packages may not be up to date.
Note that some package managers may not have the latest version of Arb.
* Debian / Ubuntu / Linux Mint
@ -22,11 +22,17 @@ Note that some packages may not be up to date.
- https://www.archlinux.org/packages/community/x86_64/arb/
- https://www.archlinux.org/packages/community/i686/arb/
* Guix
- https://www.gnu.org/software/guix/packages/
- https://www.gnu.org/software/guix/packages/A/
* Anaconda
- https://anaconda.org/conda-forge/arb
Installing SageMath or Nemo (see below) will also create an installation
of Arb local to those systems. It is possible to link user code to
that installation by setting the proper paths.
Download
-------------------------------------------------------------------------------
@ -34,9 +40,9 @@ Download
Tarballs of released versions can be downloaded from https://github.com/fredrik-johansson/arb/releases
Alternatively, you can simply install Arb from a git checkout of https://github.com/fredrik-johansson/arb/.
The master branch is generally safe to use (the test suite should pass at all
times), and recommended for
keeping up with the latest improvements and bug fixes.
The master branch is recommended for keeping up with the latest improvements and bug fixes
and should be safe to use at all times (only stable code that passes the test suite
gets merged into the git master).
Dependencies
-------------------------------------------------------------------------------
@ -94,28 +100,6 @@ It is also possible to run the unit tests for a single module, for instance::
make check MOD=arb_poly
Installation as part of FLINT (deprecated)
-------------------------------------------------------------------------------
WARNING: this feature is being deprecated. Please install Arb as a separate
library, as detailed above.
With some versions of FLINT, Arb can be compiled as a FLINT
extension package.
Simply put the Arb source directory somewhere, say ``/path/to/arb``.
Then go to the FLINT source directory and build FLINT using::
./configure --extensions=/path/to/arb <other options>
make
make check (optional)
make install
This is convenient, as Arb does not need to be
configured or linked separately. Arb becomes part of the compiled FLINT
library, and the Arb header files will be installed along with the other
FLINT header files.
Building with MSVC
-------------------------------------------------------------------------------
@ -137,7 +121,7 @@ requires CMake >= 3.5.0
If the dependencies are not found, pass ``-DCMAKE_PREFIX_PATH=/path/to/deps``
to ``cmake`` to find the dependencies.
To build tests add, pass ``-DBUILD_TESTS=yes`` to ``cmake`` and run `ctest`
To build tests add, pass ``-DBUILD_TESTS=yes`` to ``cmake`` and run ``ctest``
to run the tests.
Running code
@ -181,3 +165,30 @@ The output of the example program should be something like the following::
[3.1415926535897932384626433832795028841971693993751 +/- 6.28e-50]
Computed with arb-2.4.0
Computer algebra systems and wrappers
-------------------------------------------------------------------------------
SageMath (http://sagemath.org/) includes Arb as a standard package and
contains a high-level Python interface. Refer to the SageMath documentation:
* RealBallField: http://doc.sagemath.org/html/en/reference/rings_numerical/sage/rings/real_arb.html
* ComplexBallField: http://doc.sagemath.org/html/en/reference/rings_numerical/sage/rings/complex_arb.html
Nemo (http://nemocas.org/) is a computer algebra package for the
Julia programming language which includes a high-level Julia interface to Arb.
The Nemo installation script will create a local installation of
Arb along with other dependencies.
* Real balls: http://nemocas.github.io/Nemo.jl/latest/arb.html
* Complex balls: http://nemocas.github.io/Nemo.jl/latest/acb.html
Other wrappers are also available:
* An experimental standalone Python interface to FLINT and Arb (not requiring SageMath): https://github.com/fredrik-johansson/python-flint
* A Java wrapper using JNA: https://github.com/crowlogic/arb/
* Another Julia interface: https://github.com/JuliaArbTypes/ArbFloats.jl
Since the various wrappers add some overhead and do not expose all the
functionality in Arb, you may consider using them to try out Arb and prototype
algorithms while doing a final implementation in C.