comparison mayachemtools/docs/modules/man3/MathUtil.3 @ 0:73ae111cf86f draft

Uploaded

0:73ae111cf86f

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MATHUTIL 1"
.TH MATHUTIL 1 "2015-03-29" "perl v5.14.2" "MayaChemTools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MathUtil
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use MathUtil;
.PP
use MathUtil qw(:all);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBMathUtil\fR module provides a variety of common math functions not available in core
Perl package or some other useful math utilities. In order to be consistent with other
Perl functions, name of all the functions in this package are in lowercase which differs
from MayaChemTools naming convention for function names.
.PP
\&\fBMathUtil\fR module provides the following functions:
.PP
GeneratePrimeNumbersUpToCount, GeneratePrimeNumbersUpToLimit, acos, asin, ceil,
floor, log10, max, min, random, round, srandom, tan
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
.IP "\fBGeneratePrimeNumbersUpToCount\fR" 4
.IX Item "GeneratePrimeNumbersUpToCount"
.Vb 2
\&    $PrimesRef = GeneratePrimeNumbersUpToCount();
\&    $PrimesRef = GeneratePrimeNumbersUpToCount($Count);
.Ve
.Sp
Generate prime numbers up to specified \fICount\fR of prime numbers and return a
reference to an array containing the prime numbers.
.Sp
By default, the first 1000 prime numbers are generated. The 1000th prime
number is 7919.
.Sp
The algorithm to generate prime numbers is a modification of  Sieve of Erastothenes
prime number generator.
.IP "\fBGeneratePrimeNumbersUpToLimit\fR" 4
.IX Item "GeneratePrimeNumbersUpToLimit"
.Vb 2
\&    $PrimesRef = GeneratePrimeNumbersUpToLimit();
\&    $PrimesRef = GeneratePrimeNumbersUpToLimit($Limit);
.Ve
.Sp
Generate prime numbers up to a specified \fILimit\fR and return a reference to an
array containing the prime numbers.
.Sp
By default, the first 1000 prime numbers are generated. The 1000th prime
number is 7919 and that's why default limit is set to 7920.
.Sp
The algorithm to generate prime numbers is a modification of  Sieve of Erastothenes
prime number generator.
.IP "\fBacos\fR" 4
.IX Item "acos"
.Vb 1
\&    $Value = acos($AngleInRadians);
.Ve
.Sp
Returns the nverse cosine of an angle expressed in \fIRadians\fR using Math::Trig::acos
function.
.IP "\fBasin\fR" 4
.IX Item "asin"
.Vb 1
\&    $Value = asin($AngleInRadians);
.Ve
.Sp
Returns the inverse sine of an angle expressed in \fIRadians\fR using Math::Trig::asin
function.
.IP "\fBceil\fR" 4
.IX Item "ceil"
.Vb 1
\&    $IntegerValue = ceil($Value);
.Ve
.Sp
Returns the next largest integer for \fIValue\fR using POSIX::ceil function.
.IP "\fBfloor\fR" 4
.IX Item "floor"
.Vb 1
\&    $IntegerValue = floor($Value);
.Ve
.Sp
Returns the previous smallest integer for \fIValue\fR using POSIX::floor function.
.IP "\fBlog10\fR" 4
.IX Item "log10"
.Vb 1
\&    $Log10Value = log10($Value);
.Ve
.Sp
Returns the log of \fIValue\fR using base 10.
.IP "\fBmax\fR" 4
.IX Item "max"
.Vb 1
\&    $Number = max($Number1, $Number2);
.Ve
.Sp
Returns a \fBNumber\fR corresponding to the maximum of \fINumber1\fR and \fINumber2\fR.
.IP "\fBmin\fR" 4
.IX Item "min"
.Vb 1
\&    $Number = min($Number1, $Number2);
.Ve
.Sp
Returns a \fBNumber\fR corresponding to the minimum of \fINumber1\fR and \fINumber2\fR.
.IP "\fBround\fR" 4
.IX Item "round"
.Vb 2
\&    $RoundedValue = round($Number);
\&    $RoundedValue = round($Number, $DecimalPlaces);
.Ve
.Sp
Returns a value corresponding to a nearst ingeter for \fINumber\fR or formatted to \fIDecimalPlaces\fR.
.IP "\fBrandom\fR" 4
.IX Item "random"
.Vb 2
\&    $RandomNumber = random();
\&    $RandomNumber = random($Size);
.Ve
.Sp
Returns a random number between 0 and less than 1 or specified size.
.Sp
The random number generator implemented in MayaChemTools is a variant of linear
congruential generator (\s-1LCG\s0) as described by Miller et al. [ Ref 120 ]. It is
also referred to as Lehmer random number generator or Park-Miller random number
generator.
.Sp
Unlike Perl's core random number generator function rand, the random number
generator implemented in MayaChemTools generates consistent random values
across different platforms \- Windows, CygWin, Linux, Unix \- for a specific random
seed.
.IP "\fBsrandom\fR" 4
.IX Item "srandom"
.Vb 1
\&    $Seed = srandom($Seed);
.Ve
.Sp
Sets random number seed to be used by <random> function and returns seed value.
.Sp
The random number seed is recommeded to be an integer between 1 and 2**31 \- 2
[Ref 120] which translates to be 1 and 2147483646.
.Sp
The default seed is set to 123456789.
.IP "\fBtan\fR" 4
.IX Item "tan"
.Vb 1
\&    $Value = tan($AngleInRadians);
.Ve
.Sp
Returns the tangent of an angle expressed in \fIRadians\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Manish Sud <[e-mail]>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Constants.pm, ConversionsUtil.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2015 Manish Sud. All rights reserved.
.PP
This file is part of MayaChemTools.
.PP
MayaChemTools is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option)
any later version.