view release on metacpan or  search on metacpan

lib/Math/DifferenceSet/Planar.pm  view on Meta::CPAN

=item I<iterate_available_sets>

The class method
C<Math::DifferenceSet::Planar-E<gt>iterate_available_sets> returns
a code reference that, repeatedly called, returns one stored sample
planar difference set for each order known to the module, one by one.
The iterator returns a false value when it is exhausted.

C<Math::DifferenceSet::Planar-E<gt>iterate_available_sets($lo, $hi)>
returns an iterator over samples with orders between C<$lo> and C<$hi>
(inclusively), ordered by ascending size.  If C<$lo> is not defined,
it is taken as zero.  If C<$hi> is omitted or not defined, it is taken
as plus infinity.  If C<$lo> is greater than C<$hi>, they are swapped
and the sequence is reversed, so that it is ordered by descending size.

=item I<available_min_order>

The class method C<Math::DifferenceSet::Planar-E<gt>available_min_order>
returns the order of the smallest sample planar difference set currently
known to the module.

=item I<available_max_order>

The class method C<Math::DifferenceSet::Planar-E<gt>available_max_order>
returns the order of the largest sample planar difference set currently
known to the module.

=item I<available_count>

The class method C<Math::DifferenceSet::Planar-E<gt>available_count>
returns the number of sample planar difference sets with distinct orders
currently known to the module.

=item I<known_std_ref>

=item I<known_lex_ref>

=item I<known_gap_ref>

The class methods
C<Math::DifferenceSet::Planar-E<gt>known_I<E<lt>typeE<gt>>_ref($order)>
with I<E<lt>typeE<gt>> one of C<std>, C<lex>, or C<gap>, returns a
boolean value of true if the current difference set samples database
contains the reference set of the respective type, otherwise false.
With the default database, this will be the true for all available sets,
but data extension modules might provide large sample sets without
accompanying reference sets of all kinds.

=item I<iterate_known_std_refs>

=item I<iterate_known_lex_refs>

=item I<iterate_known_gap_refs>

The class methods
C<Math::DifferenceSet::Planar-E<gt>iterate_known_I<E<lt>typeE<gt>>_refs(@args)>
with I<E<lt>typeE<gt>> one of C<std>, C<lex>, or C<gap>, provide
iterators analogous to I<iterate>, but iterating over the reference
sets of the respective type rather than unspecified samples.  Note that
these iterations may terminate sooner than I<iterate> and may even skip
some orders.

=item I<known_std_ref_min_order>

=item I<known_std_ref_max_order>

=item I<known_std_ref_count>

=item I<known_lex_ref_min_order>

=item I<known_lex_ref_max_order>

=item I<known_lex_ref_count>

=item I<known_gap_ref_min_order>

=item I<known_gap_ref_max_order>

=item I<known_gap_ref_count>

The class methods C<Math::DifferenceSet::Planar>
C<-E<gt>known_I<E<lt>typeE<gt>>_ref_I<E<lt>propertyE<gt>>> with
I<E<lt>typeE<gt>> one of C<std>, C<lex>, or C<gap>, and with
I<E<lt>propertyE<gt>> one of C<min_order>, C<max_order>, or C<count>,
return the smallest and largest order and the number of known reference
sets of the respective kind.

In the unusual case of a database not containing any reference sets of the
desired type, minimum and maximum will be C<undef> and count will be zero.

=item I<known_space>

The class method C<Math::DifferenceSet::Planar-E<gt>known_space($order)>
returns a positive integer if pre-computed rotator space information for
order C<$order> is available to the module, otherwise zero.  Currently,
in case of availability, the integer number is the number of radices
used for difference set plane enumeration.  For sets with known space,
I<iterate_planes> and I<iterate_rotators> will be more efficient than
otherwise.

The precise meaning of non-zero values returned by I<known_space> is
implementation specific and should not be relied upon.

=item I<known_space_desc>

The class method
C<Math::DifferenceSet::Planar-E<gt>known_space_desc($order)> returns a
descriptive string if pre-computed rotator space information for order
C<$order> is available to the module, otherwise undef.

The precise meaning of strings returned by I<known_space_desc> is
implementation specific and should not be relied upon.  They are intended
for documentation rather than further processing.

=item I<iterate_known_spaces>

The class method C<Math::DifferenceSet::Planar-E<gt>iterate_known_spaces>
returns a code reference that, repeatedly called, returns descriptions
of all pre-computed rotator spaces known to the module, one by one.
The iterator returns a false value when it is exhausted.

lib/Math/DifferenceSet/Planar.pm  view on Meta::CPAN

sets, the existence of linear mappings conjecture, or the conjecture
that all multipliers are divisors of the order should be proven wrong,
we will have to decide how this library should be improved to reflect
on the matter.  Conversely, if some of these conjectures are finally
confirmed, at least the documentation should be updated.

The verify_elements() method currently builds a complete operator table
in memory.  This does not scale very well in terms of either space or
time for larger sets.

The documentation should be reorganized to move detailed explanations
into separate POD files while keeping API descriptions in the modules
themselves.

Bug reports and suggestions are welcome.
Please submit them through the github issue tracker,
L<https://github.com/mhasch/perl-Math-DifferenceSet-Planar/issues>.

More information for potential contributors can be found in the file
named F<CONTRIBUTING> in this distribution.

=head1 ROADMAP

With version 1.000, a release series intended to be more stable than
previous versions has been established.  New functionality may yet be
introduced, but with backwards compatibility as an objective not to be
given up lightly.  There is of course room for improvements behind the
scenes, too, notably addressing time and space efficiency.

Other changes may of course reflect research progress, as we get along,
and also work towards other goals mentioned in the CONTRIBUTING agenda.
In particular, we intend to cover more geometric and algebraic aspects
of planar difference sets.  We will also look out for opportunities to
interface with more generic set types.

The inclusion of sets of order one has been considered to perhaps not
justify the extra work so far.  These three sets would satisfy difference
set definitions but not all projective plane properties.

Further extensions of the sample set database are a part
of the project but will only affect the collection of
extension modules Math::DifferenceSet::Planar::Data::M,
Math::DifferenceSet::Planar::Data::L,
Math::DifferenceSet::Planar::Data::XL, etc.

For most planes in the larger collections, gap reference sets are not
yet computed.  At the time of the 1.003 release, we have computed gap
reference sets for 716 planes only, while standard and lex reference sets
are available for all of the 12400 planes included in the XL database,
and even for most of the sets with millions of elements provided as
an extra.  Lacking more efficient algorithms, a substantial extension of
gap reference sets would require massive computing power, but we expect
to at least gradually increase their number over time.

More important perhaps is double- and triple-checking the data that is
already present, before it can be regarded as scientifically acceptable.
For each order, we used Singer's construction to generate a sample
set, which is provably valid, and iterated through its multiples
to find reference sets with their respective optimality properties.
As this was of course performed by computer programs and computers may
malfunction, repetitions or, even better, independent reiterations
will increase confidence in the results and weed out actual errors.

Verifying difference set properties using complete difference tables is
impractical for large sets.  Verification using reference sets, on the
other hand, relies partly on conjectures.  Therefore, we are still looking
for an efficient and proven verification method for very large sets.

=head1 SEE ALSO

=over 4

=item *

L<Math::DifferenceSet::Planar::Data> - planar difference set storage.

=item *

L<Math::DifferenceSet::Planar::Examples> - overview of example scripts.

=item *

L<Math::DifferenceSet::Planar::Computation> - origins of pre-computed data.

=item *

L<Math::DifferenceSet::Planar::Data::M|https://github.com/mhasch/perl-Math-DifferenceSet-Planar-Data-M>,
L<Math::DifferenceSet::Planar::Data::L|https://github.com/mhasch/perl-Math-DifferenceSet-Planar-Data-L>,
and
L<Math::DifferenceSet::Planar::Data::XL|https://github.com/mhasch/perl-Math-DifferenceSet-Planar-Data-XL>
- data extension modules of various sizes, available on GitHub.  They just
contain data and no additional functionality.  We don't intend to upload
these modules to CPAN, where they would only be dead weight, while users
actually interested in them should not have much trouble to fetch them
from the sources referenced above.

=item *

L<Math::ModInt> - modular integer arithmetic.

=item *

L<PDL> - the Perl Data Language.

=item *

Moore, Emily H., Pollatsek, Harriet S., "Difference Sets", American
Mathematical Society, Providence, 2013, ISBN 978-0-8218-9176-6.

=item *

Dinitz, J.H., Stinson, D.R., "Contemporary Design Theory: A collection
of surveys", John Wiley and Sons, New York, 1992, ISBN 0-471-53141-3.

=item *

Gordon, Daniel M., "La Jolla Difference Set Repository".
L<https://www.dmgordon.org/diffset/>

=item *