Diab Jerius

# NAME

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

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[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`.

# 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`, 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`.

# 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,
]``````

# BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Number or by email to bug-cxc-number@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

``  The GNU General Public License, Version 3, June 2007``