NAME
CXC::Number::Sequence::Ratio  Numeric Sequence with Relative Fractional Spacing
VERSION
version 0.05
SYNOPSIS
use CXC::Number::Sequence::Ratio;
$seq = CXC::Number::Sequence::Ratio>new( min = $min, max => $max,
w0 => $spacing,
ratio => $ratio );
$sequence = $seq>elements;
DESCRIPTION
CXC::Number::Sequence::Ratio generates an increasing sequence of numbers covering a range, where the ratio of the spacing, w[k], between consecutive numbers E[k] and E[k1] is a constant, e.g.,
w[k] = r * w[k1] (1)
In general, a number in the sequence is
k
1  r
E[k] = E[0] + w[0]  (2)
1  r
Where E[0] is the alignment value, w[0] is the initial spacing, E[1]E[0], and k is the generating index (not the output order). The sequence is always output in increasing value, regardless of the order in which it was generated.
r must be positive and not equal to 1 (that would generate a linear sequence and the algorithms used in this module would break). The alignment value, E[0], need not be one of the range extrema, nor even in the range.
If the sequence must cover a specific range, then some caveats apply. If r < 1, Eq. 2 may converge to a value which does not allow covering the specified range:
w[0]
E[Infinity] = E[0] +  (3)
1  r
An exception will be thrown if this is the case.
If E[0] >= E[max] the sequence values are generated from larger to smaller values. w[0]
must be < 0
, and r
is the growth factor in the direction of smaller sequence values.
It subclasses CXC::Number::Sequence, so see documentation for that class for additional methods.
A full description of the available parameters may be found in the description of the constructor "new".
If an inconsistent set of parameters is passed, new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::IllegalCombination
.
If an unknown parameter is passed, new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::unknown
.
If a parameter value is illegal or a combination of values is illegal (e.g. min > max
), new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::constraint
.
CONSTRUCTOR
new
$sequence = CXC::Number::Sequence::Ratio>new( %attr );
Construct a sequence. The available attributes are those for the parent constructor in CXC::Number::Sequence::Base, as well as the following:
Only certain combinations of parameters are allowed; see "Valid Parameter Combinations".
Range Parameters
Range extrema may be hard, indicating that the sequence must exactly cover the extrema, or soft, indicating that the sequence may cover a larger range. Usually the combination of parameters will uniquely determine whether an extremum is soft or hard, but in some cases soft bounds must be explicitly labeled as soft, requiring use of the soft_min
and soft_max
parameters.
min
soft_min

The minimum value that the sequence should cover. Use
soft_min
to disambiguate hard from soft limits as documented above. max
soft_max

The maximum value that the sequence should cover. Use
soft_max
to disambiguate hard from soft limits as documented above. nelem

The number of elements in the sequence
Spacing and Alignment
w0

The spacing between E[0] and E[1]. All other spacings are based on this. If
E[0] >= max
, thenw0
must be negative, otherwise it must be positive. Ifw[0]
has the incorrect sign, an exception will be thrown. e0

E[0]
. This is usually implicitly specified by themin
ormax
parameters. Set it explicitly if it is not one of the extrema.
Valid Parameter Combinations
min
,soft_max
,w0
,ratio

E[0] = min
, and the sequence minimally covers the range. soft_min
,max
,w0
,ratio

E[0] = max
, and the sequence minimally covers the range.w0 < 0
. min
,nelem
,w0
,ratio

E[0] = min
and the sequence exactly covers the specified range.w0 > 0
max
,nelem
,w0
,ratio

E[0] = max
, and the sequence exactly covers the range.w0 < 0
. e0
min
,max
,w0
,ratio

E[0] = e0
, and the sequence covers the range.E[0]
need not be inside the range.w0 < 0
ifE[0] > max
.
# COPYRIGHT
EXAMPLES

Range: [2,20] E[0] = 20 w[0] = 1 r = 1.1
Cover the range
[2, 20]
, with the alignment value at the max of the range. Spacing increases from20
to2
, starting at1
, by a factor of 1.1 per value.use Data::Dump; use aliased 'CXC::Number::Sequence::Ratio'; dd Ratio>new( soft_min => 2, max => 20, ratio => 1.1, w0 => 1 )>elements;
results in
[ 1.4688329389, 4.062575399, 6.42052309, 8.5641119, 10.512829, 12.28439, 13.8949, 15.359, 16.69, 17.9, 19, 20, ]
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CXCNumber or by email to bugcxcnumber@rt.cpan.org.
When submitting a bug or request, please include a testfile or a patch to an existing testfile that illustrates the bug or desired feature.
SEE ALSO
Please see those modules/websites for more information related to this module.
AUTHOR
Diab Jerius <djerius@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007