NAME

Math::NumSeq::OEIS -- number sequence by OEIS A-number

SYNOPSIS

 use Math::NumSeq::OEIS;
 my $seq = Math::NumSeq::OEIS->new (anum => 'A000032');
 my ($i, $value) = $seq->next;

DESCRIPTION

This module selects a NumSeq by an A-number of Sloane's Online Encyclopedia of Integer Sequences.

If there's NumSeq code implementing the sequence then that's used, otherwise local downloaded OEIS files if available. See Math::NumSeq::OEIS::Catalogue for querying available A-numbers.

Files

Local files should be in a ~/OEIS direectory, ie. an OEIS directory in the user's home directory (File::HomeDir). Files can be HTML, OEIS internal, b-file, and/or a-file.

    ~/OEIS/A000032.html
    ~/OEIS/A000032.internal.txt
    ~/OEIS/A000032.internal.html
    ~/OEIS/b000032.txt
    ~/OEIS/a000032.txt

As downloaded from for example

    http://oeis.org/A000032
    http://oeis.org/search?q=id:A000032&fmt=text
    http://oeis.org/A000032/internal
    http://oeis.org/A000032/b000032.txt
    http://oeis.org/A000032/a000032.txt

The "internal" text format is the most reliable for parsing. This is the "text" link in each sequence web page (filename .internal.txt). The "internal" link is the same wrapped in HTML (filename .internal.html).

b-files b000000.txt are long lists of values. a-files a000000.txt similarly and even longer, but sometimes they are auxiliary info instead (and in that case not used). All sequences have a b-file, but sometimes they are merely the web page samples put into a separate file. (The web page samples might be enough for fast growing sequences.)

b-file or a-file can be used alone by this module, without the text or HTML parts. In that case there's no $seq->description() and it may limit the $seq->characteristic() attributes.

Other Notes

Sometimes more than one NumSeq module generates an OEIS sequence. For example A000290 is Squares, and also Polygonal k=4. The catalogue is arranged so Math::NumSeq::OEIS selects the better, faster, or more specific one.

Sometimes the OEIS has duplicates, ie. two A-numbers which are the same sequence. Both are catalogued so they both give NumSeq module code, but the $seq->oeis_anum() method generally only returns whichever is the "primary" one.

Presently NumSeq code is catalogued with A-numbers only when it is the same as the OEIS sequence. In particular this means "offset" in the OEIS matching i_start of the NumSeq, so i here corresponds to n there. Sometimes an i_start parameter here can alter numbering suitably (and in PlanePathCoord etc tie-ins the similar n_start), but some NumSeq may be uncatalogued because numbering or first few values are not the same.

FUNCTIONS

See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence classes.

$seq = Math::NumSeq::OEIS->new (anum => 'A000000')

Create and return a new sequence object.

Iterating

($i, $value) = $seq->next()

Return the next index and value in the sequence.

In the current code, when reading from a file, any values bigger than a usual Perl int or float are returned as Math::BigInt objects in order to preserve precision for numeric operations. An application can pre-load Math::BigInt to choose its back-end or other global options.

An a000000.txt or b000000.txt file is read line by line. For ithreads of Perl 5.8 up there's a CLONE setup which re-opens the file in the new thread so $seq in each thread has its own position. (See perlthrtut and "Making your module threadsafe" in perlmod.)

But a process fork() will have both parent and child with the same open file so care should be taken that only one of them uses $seq in that case. This is the same as for all open files across a fork().

Random Access

$value = $seq->ith($i)

Return the $i'th value from $seq, or undef if $i is outside the range of available values.

An a000000.txt or b000000.txt file is read by a binary search to find the target $i. This is reasonably efficient and avoids loading or processing an entire file if just a few values are wanted.

If $i happens to be the next line or just a short distance ahead of what was last read then no search is necessary. So ith() called sequentially i=1,2,3,4,etc simply reads successive lines the same as next() would do.

Information

$str = $seq->description()

Return a human-readable description of the sequence. For downloaded files, this is the name part ("%N") which is a short description of the sequence.

Some sequences may have non-ASCII characters in the description, usually in names of people. For Perl 5.8 and up they're decoded to wide-chars. For earlier Perl they're left as the bytes from the download, which is UTF-8.

$value = $seq->values_min()

$value = $seq->values_max()

Return the minimum or maximum values in the sequence, or undef if unknown or infinity.

For files, values_min() is guessed from the first few values if non-negative, and values_max() is normally considered to be infinite. For keyword "full", the samples are the entire sequence and they give the range. If a range seems to be limited (eg. sequences of -1,0,1) then min and max are obtained from those.

(Would like the OEIS data to have range information like this in machine-readable form. It's usually in sequence comments or implicit in the definition for human readers.)

$ret = $seq->characteristic($key)

For a file, the following standard characteristics are obtained (per "Information" in Math::NumSeq),

• "integer" always true.

• "increasing", "non_decreasing" and "smaller" are determined from the sample values or the first few values from an a-file or b-file. Looking at only the few ensures a big file isn't read in its entirety and is normally enough. The intention would be to look at enough values not to be tricked by decreasing values after the first few, etc.

• "digits" is from keyword "cons" for decimal constants. Some other digit sequences are recognised by their name part though this may be unreliable.

• "count" is from a name with "number of". This is unreliable but often close enough.

All the keywords from the OEIS are provided as booleans under names "OEIS_easy" etc. So for example

    if ($seq->characteristic("OEIS_nice")) {
      print "nooiice ...\n";
    }

SEE ALSO

Math::NumSeq, Math::NumSeq::OEIS::Catalogue

HOME PAGE

http://user42.tuxfamily.org/math-numseq/index.html

LICENSE

Copyright 2011, 2012, 2013, 2014, 2016, 2018, 2019, 2020 Kevin Ryde

Math-NumSeq is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Math-NumSeq 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Math-NumSeq. If not, see <http://www.gnu.org/licenses/>.

cpanm Math::NumSeq

perl -MCPAN -e shell
install Math::NumSeq