/ 
CXC-Number-0.11
River stage zero No dependents
/ CXC::Number::Sequence::Ratio

NAME

CXC::Number::Sequence::Ratio - Numeric Sequence with Relative Fractional Spacing

VERSION

version 0.11

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[k-1] is a constant, e.g.,

 w[k] = r * w[k-1]                  (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.

CONSTRUCTORS

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, then w0 must be negative, otherwise it must be positive. If w[0] has the incorrect sign, an exception will be thrown.

e0

E[0]. This is usually implicitly specified by the min or max 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 if E[0] > max.

INTERNALS

# COPYRIGHT

EXAMPLES

  1. 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 from 20 to 2, starting at 1, 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,
]

SUPPORT

Bugs

Please report any bugs or feature requests to bug-cxc-number@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Number

Source

Source is available at

https://gitlab.com/djerius/cxc-number

and may be cloned from

https://gitlab.com/djerius/cxc-number.git

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