1Math::NumSeq::OEIS(3) User Contributed Perl DocumentationMath::NumSeq::OEIS(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14       This module selects a "NumSeq" by an A-number of Sloane's Online
15       Encyclopedia of Integer Sequences.
16
17       If there's "NumSeq" code implementing the sequence then that's used,
18       otherwise local downloaded OEIS files if available.  See
19       Math::NumSeq::OEIS::Catalogue for querying available A-numbers.
20
21   Files
22       Local files should be in a ~/OEIS direectory, ie. an OEIS directory in
23       the user's home directory (File::HomeDir).  Files can be HTML, OEIS
24       internal, b-file, and/or a-file.
25
26           ~/OEIS/A000032.html
27           ~/OEIS/A000032.internal.txt
28           ~/OEIS/A000032.internal.html
29           ~/OEIS/b000032.txt
30           ~/OEIS/a000032.txt
31
32       As downloaded from for example
33
34           http://oeis.org/A000032
35           http://oeis.org/search?q=id:A000032&fmt=text
36           http://oeis.org/A000032/internal
37           http://oeis.org/A000032/b000032.txt
38           http://oeis.org/A000032/a000032.txt
39
40       The "internal" text format is the most reliable for parsing.  This is
41       the "text" link in each sequence web page (filename .internal.txt).
42       The "internal" link is the same wrapped in HTML (filename
43       .internal.html).
44
45       b-files b000000.txt are long lists of values.  a-files a000000.txt
46       similarly and even longer, but sometimes they are auxiliary info
47       instead (and in that case not used).  All sequences have a b-file, but
48       sometimes they are merely the web page samples put into a separate
49       file.  (The web page samples might be enough for fast growing
50       sequences.)
51
52       b-file or a-file can be used alone by this module, without the text or
53       HTML parts.  In that case there's no "$seq->description()" and it may
54       limit the "$seq->characteristic()" attributes.
55
56   Other Notes
57       Sometimes more than one NumSeq module generates an OEIS sequence.  For
58       example A000290 is Squares, and also Polygonal k=4.  The catalogue is
59       arranged so "Math::NumSeq::OEIS" selects the better, faster, or more
60       specific one.
61
62       Sometimes the OEIS has duplicates, ie. two A-numbers which are the same
63       sequence.  Both are catalogued so they both give NumSeq module code,
64       but the "$seq->oeis_anum()" method generally only returns whichever is
65       the "primary" one.
66
67       Presently NumSeq code is catalogued with A-numbers only when it is the
68       same as the OEIS sequence.  In particular this means "offset" in the
69       OEIS matching "i_start" of the NumSeq, so i here corresponds to n
70       there.  Sometimes an "i_start" parameter here can alter numbering
71       suitably (and in "PlanePathCoord" etc tie-ins the similar "n_start"),
72       but some NumSeq may be uncatalogued because numbering or first few
73       values are not the same.
74

FUNCTIONS

76       See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence
77       classes.
78
79       "$seq = Math::NumSeq::OEIS->new (anum => 'A000000')"
80           Create and return a new sequence object.
81
82   Iterating
83       "($i, $value) = $seq->next()"
84           Return the next index and value in the sequence.
85
86           In the current code, when reading from a file, any values bigger
87           than a usual Perl int or float are returned as "Math::BigInt"
88           objects in order to preserve precision for numeric operations.  An
89           application can pre-load "Math::BigInt" to choose its back-end or
90           other global options.
91
92           An a000000.txt or b000000.txt file is read line by line.  For
93           ithreads of Perl 5.8 up there's a "CLONE" setup which re-opens the
94           file in the new thread so $seq in each thread has its own position.
95           (See perlthrtut and "Making your module threadsafe" in perlmod.)
96
97           But a process "fork()" will have both parent and child with the
98           same open file so care should be taken that only one of them uses
99           $seq in that case.  This is the same as for all open files across a
100           "fork()".
101
102   Random Access
103       "$value = $seq->ith($i)"
104           Return the $i'th value from $seq, or "undef" if $i is outside the
105           range of available values.
106
107           An a000000.txt or b000000.txt file is read by a binary search to
108           find the target $i.  This is reasonably efficient and avoids
109           loading or processing an entire file if just a few values are
110           wanted.
111
112           If $i happens to be the next line or just a short distance ahead of
113           what was last read then no search is necessary.  So "ith()" called
114           sequentially i=1,2,3,4,etc simply reads successive lines the same
115           as "next()" would do.
116
117   Information
118       "$str = $seq->description()"
119           Return a human-readable description of the sequence.  For
120           downloaded files, this is the name part ("%N") which is a short
121           description of the sequence.
122
123           Some sequences may have non-ASCII characters in the description,
124           usually in names of people.  For Perl 5.8 and up they're decoded to
125           wide-chars.  For earlier Perl they're left as the bytes from the
126           download, which is UTF-8.
127
128       "$value = $seq->values_min()"
129       "$value = $seq->values_max()"
130           Return the minimum or maximum values in the sequence, or "undef" if
131           unknown or infinity.
132
133           For files, "values_min()" is guessed from the first few values if
134           non-negative, and "values_max()" is normally considered to be
135           infinite.  For keyword "full", the samples are the entire sequence
136           and they give the range.  If a range seems to be limited (eg.
137           sequences of -1,0,1) then min and max are obtained from those.
138
139           (Would like the OEIS data to have range information like this in
140           machine-readable form.  It's usually in sequence comments or
141           implicit in the definition for human readers.)
142
143       "$ret = $seq->characteristic($key)"
144           For a file, the following standard characteristics are obtained
145           (per "Information" in Math::NumSeq),
146
147           •   "integer" always true.
148
149           •   "increasing", "non_decreasing" and "smaller" are determined
150               from the sample values or the first few values from an a-file
151               or b-file.  Looking at only the few ensures a big file isn't
152               read in its entirety and is normally enough.  The intention
153               would be to look at enough values not to be tricked by
154               decreasing values after the first few, etc.
155
156           •   "digits" is from keyword "cons" for decimal constants.  Some
157               other digit sequences are recognised by their name part though
158               this may be unreliable.
159
160           •   "count" is from a name with "number of".  This is unreliable
161               but often close enough.
162
163           All the keywords from the OEIS are provided as booleans under names
164           "OEIS_easy" etc.  So for example
165
166               if ($seq->characteristic("OEIS_nice")) {
167                 print "nooiice ...\n";
168               }
169

SEE ALSO

171       Math::NumSeq, Math::NumSeq::OEIS::Catalogue
172

HOME PAGE

174       <http://user42.tuxfamily.org/math-numseq/index.html>
175

LICENSE

177       Copyright 2011, 2012, 2013, 2014, 2016, 2018, 2019, 2020 Kevin Ryde
178
179       Math-NumSeq is free software; you can redistribute it and/or modify it
180       under the terms of the GNU General Public License as published by the
181       Free Software Foundation; either version 3, or (at your option) any
182       later version.
183
184       Math-NumSeq is distributed in the hope that it will be useful, but
185       WITHOUT ANY WARRANTY; without even the implied warranty of
186       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
187       General Public License for more details.
188
189       You should have received a copy of the GNU General Public License along
190       with Math-NumSeq.  If not, see <http://www.gnu.org/licenses/>.
191
192
193
194perl v5.34.1                      2022-06-06             Math::NumSeq::OEIS(3)
Impressum