ConstantCalculus-CircleConstant

 view release on metacpan or  search on metacpan

lib/ConstantCalculus/CircleConstant.pm  view on Meta::CPAN

  my $tau = undef;

  # Set the number of places.
  my $places = 100;

  # Use the calculation method for Tau.
  my $tau = tau_chudnovsky($places);
  print $tau . "\n";

  # Use the calculation method for Tau.
  my $tau = tau_borwein25($places);
  print $tau . "\n";

  # Use the calculation algorithm for Pi directly.
  $tau = chudnovsky([
      Places => 100,     # Set the number of places to 100
      Terms => 9,        # Set the number of terms to 9 
      Precision => 115,  # Set the precision to 115
      Trim => 115,       # Trim the value of Tau to 115 places      
      Type => "tau"      # Calculate the value of Tau
  ]);
  print $tau . "\n";

Use BBP for calculation with respect to C<Pi>:

  # Print the nth hexadecimal digit of Pi.
  my $nth = 1;
  print bbp_digit($nth, 14);  # Use precision 14

  # Print the nth hexadecimal digit of Pi upwards.
  my $nth = 1;
  print bbp_digits($nth, 32, 128);  # Output 32 digits and use precision 128

  # Print Pi using BBP.
  my $places = 1;
  print bbp_algorithm($places, 14); # Use precision 14

Use predefined values of Pi and Tau.

    # Print Pi with 1000 decimal places.
    print $PI_DEC . "\n";

    # Print Pi with 1000 hexadecimal places.
    print $PI_HEX . "\n";

The square brackets in the above subroutine calls means that the named
arguments within the brackets are optional. Every named argument will be
preset in the subroutine if not defined.

=head1 REQUIREMENT

L<CPAN bignum|https://metacpan.org/dist/bignum>

=head1 DESCRIPTION

The circle constant is a mathematical constant. There are two variants of the
circle constant. Most common is the use of Pi (Ï€) for the circle constant. More
uncommon is the use of Tau (Ï„) for the circle constant. The relation between 
them is τ = 2 π. There can be found other denotations for the well known name
Pi. The names are Archimedes's constant or Ludolph's constant. The circle
constant is used in formulas across mathematics and physics.

The circle constant is the ratio of the circumference C of a circle to its
diameter d, which is π = C/d or τ = 2 C/d. It is an irrational number, which
means that it cannot be expressed exactly as a ratio of two integers.  In
consequence of this, the decimal representation of a circle constant never
ends in there decimal places having a infinite number of places, nor enters
a permanently repeating pattern in the decimal places. The circle constant is
also a not algebraic transcendental number.

Over the centuries scientists developed formulas for approximating the circle
constant Pi. Chudnovsky's formula is one of them. A algorithm based on Chudnovsky's
formula can be used to calculate an approximation for Pi and also for Tau. The
advantage of the Chudnovsky formula is the good convergence. In contradiction 
the convergence of the Leibniz formula is quit bad.      

The challenge in providing an algorithm for the circle constant is that all
decimal places must be correct in terms of the formula. Based on the desired decimal
place number or precision, the number of places must be correct. The provided
algorithm takes care of this. At the moment the result of the implemented algorithm
was checked against the known decimal places of Pi up to 10000 places.

=head1 APPROXIMATIONS OF PI AND TAU

Fractions such as 22/7 or 355/113 can be used to approximate the circle constant
Pi, whereas 44/7 or 710/113 represent the approximation of the circle constant
Tau.

At the moment Chudnovsky's formula is fully implemented in the module to calculate
Pi as well as Tau. The algorithm from Borwein from 1989 is implemented for experimental
purposes. The most popular formula for calculating the circle constant is the Leibniz
formula.

=head1 IMPLEMENTATION

To be able to deal with large numbers pre decimal point and after the decimal point
as needed, the Perl module C<bignum> is used. The main subroutine argument is the 
number of places, which should be calculated for the circle constant.        

If terms and precision is not given, both are estimated from the given number of
places. This will result in a value of Pi, which is accurate to the requested 
places. If places, terms and/or precision is given, the behaviour of the algorithm
can be studied with respect to terms and/or precision.  

The number of iterations is calculated using the knowledge, that each iteration
should result in e.g. 14 new digits after the decimal point. So the value for the 
calculation of the number of terms is set to e.g. 14.  To make sure that reverse as
less as possible digits are changed, the number of terms to calculated is uneven.
So the sign of the term to add is negative after the decimal point.

To prevent rounding errors in the last digit, the precision is a factor of e.g. 14
higher than the requested number of places. The correct number of places is realised
by truncating the calculated and possibly rounded value of Pi to the requested number
of places.      

=head1 EXAMPLES

=head2 Calculation of Pi

=head3 Example 1

  # Load the Perl module.
  use ConstantCalculus::CircleConstant;

  # Declare the variable for Pi.
  my $pi = undef;

  # Set the number of places.
  my $places = 100;  

  # Calculate Pi.
  $pi = chudnovsky($places);
  print $pi . "\n";

=head3 Example 2

  # Load the Perl module.
  use ConstantCalculus::CircleConstant;

  # Declare the variable for Pi.
  my $pi = undef;

  # Set the number of places.
  my $places = 100;  

  # Set the number of terms.
  my $terms = 50;  

  # Set the precision.
  my $precision = 115;  

  # Set the value for trim.

lib/ConstantCalculus/CircleConstant.pm  view on Meta::CPAN

  my $places = 100;  

  # Calculate Tau.
  $tau = chudnovsky($places);
  print $tau . "\n";

=head3 Example 2

  # Load the Perl module.
  use ConstantCalculus::CircleConstant;

  # Declare the variable for Tau.
  my $tau = undef;

  # Set the number of places.
  my $places = 100;  

  # Set the number of terms.
  my $terms = 50;  

  # Set the precision.
  my $precision = 115;  

  # Set the value for trim.
  my $trim = 115;  

  # Calculate Tau.
  $tau = chudnovsky(
      Places => $places, 
      Terms => $terms,      
      Precision => $precision,
      Trim => $trim, 
      Type => "pi"  
  );
  print $tau . "\n";

=head3 Example 3

  # Load the Perl module.
  use ConstantCalculus::CircleConstant;

  # Create an alias for the module method.
  *tau = \&tau_borwein25;

  # Declare the variable for Pi.
  my $tau = undef;

  # Set the number of places.
  my $places = 100;  

  # Calculate and print the value Pi.
  $tau = tau($places);
  print $tau . "\n";

=head1 MODULE METHODS

=head2 Main Methods
   
=head3 chudnovsky_algorithm()

Implementation of the Chudnovsky formula.

=head3 borwein25_algorithm()

Implementation of the Borwein 25 formula.

=head3 pi_borwein25()

Calculate Pi with the Borwein 25 algorithm.

=head3 tau_borwein25()

Calculate Tau with the Borwein 25 algorithm.

=head3 pi_chudnovsky()

Calculate Pi with the Chudnovsky algorithm.

=head3 tau_chudnovsky()

Calculate Tau with the Chudnovsky algorithm.

=head3 bbp_algorithm()

Apply the BBP algorithm.

=head3 bbp_digits()

Calculate as much as possible hexadecimal digits.

=head3 bbp_digit()

Calculate one hexadecimal digit.

=head3 S()

Calculate the S terms of the BBP algorithm

=head2 Other Methods

=head3 factorial()

The subroutine calculates the factorial of given number.

=head3 sqrtroot()

The subroutine calculates the square root of given number.

=head3 modexp()

The subroutine returns the result of a modular exponentiation. A modular 
exponentiation is an exponentiation applied over a modulus. The result
of the modular exponentiation is the remainder when an integer b (base) 
is exponentiated by e (exponent) and divided by a positive integer m
(modulus).

=head3 estimate_terms()

Estimates the terms or iterations to get the correct number of place.

=head3 truncate_places()

Truncate the number of places to a given value.

=head1 MODULE EXPORT

lib/ConstantCalculus/CircleConstant.pm  view on Meta::CPAN

=head2 Generic export

=over 4

=item * chudnovsky_algorithm

=item * borwein25_algorithm

=item * pi_borwein25

=item * tau_borwein25

=item * pi_chudnovsky

=item * tau_chudnovsky

=item * bbp_algorithm

=item * bbp_digits

=item * bbp_digit

=item * S

=item * $PI_DEC

=item * $PI_HEX

=back

=head2 Export on demand

=over 4

=item * factorial

=item * sqrtroot

=item * modexp

=item * estimate_terms

=item * truncate_places

=back

=head1 LIMITATIONS

Limitations are not known yet.

=head1 BUGS

Bugs are not known yet.

=head1 NOTES

The implemented chudnovsky algorithm is used in a representation where the
well known terms are optimised for calculation. 

It seems that the Perl builtin function C<sqrt()> cannot used in general for
 determining the value of Pi or Tau with respect to some calculation formulas.

Chudnovsky's formula is working using the Perl builtin function C<sqrt()>. In
contradiction Borwein25's formula fails in calculation using the Perl builtin
function C<sqrt()>.

Using a coded user defined subroutine for calculating of a square root,
Borwein25's could be used for the calculation.  

=head1 OPEN ISSUE

Further calculations with higher precision are outstanding to check the
accuracy of the correctness of the last digits of the calculated circle
constant.

=head1 SEE ALSO

=head2 Programming informations

=over 4

=item * L<CPAN bignum|https://metacpan.org/dist/bignum>

=item * L<Perldoc bignum|https://perldoc.perl.org/bignum>

=back

=head2 Mathematical informations

=over 4

=item * Sources w.r.t. the circle constant Pi

=item * Sources w.r.t. the circle constant Tau

=item * Resources about the Leibniz formula

=item * Resources about the Chudnovsky formula

=item * Resources about Borwein's formulas

=back

=head2 Bibliography

=over 4

=item * David H. Bailey, The BBP Algorithm for Pi, September 17, 2006

=item * David H. Bailey, A catalogue of mathematical formulas involving π, with analysis, December 10, 2021

=item * David H. Bailey, Jonathan M. Borwein, Peter B. Borwein and Simon Plouffe, The Quest for Pi, June 25, 1996

=back

=head1 AUTHOR

Dr. Peter Netz, E<lt>ztenretep@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2022 by Dr. Peter Netz

This library is free software; you can redistribute it and/or modify it
under the same terms of The MIT License. For more details, see the full
text of the license in the attached file LICENSE in the main module folder.
This program is distributed in the hope that it will be useful, but without
any warranty; without even the implied warranty of merchantability or fitness
for a particular purpose.

=cut